@case-framework/survey-assistant 0.6.0 → 0.7.0

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

@@ -1,10 +1,10 @@
-import { X as SURVEY_OPERATION_KINDS, bt as surveyOperationSchemasByKind, f as surveyChangeSetSchema, q as assistantItemTypeManifestSchema, yt as surveyOperationSchema } from "./protocol-DJUP4gc0.mjs";
-import { d as getDeterministicCreateItemTypes, f as inspectAssistantItem, p as resolveAssistantCapabilityReference } from "./form-authoring-kQDgC5oz.mjs";
-import { A as getKeyIndexEntries, F as itemSummarySchema, G as summarizeKeyIndexEntries, H as sliceWithCursor, I as mapKeyIndexById, J as summarizeRawItem, L as mapOutlineById, M as getRawSurveyItems, N as itemConfigDetailsSchema, P as itemMatchesQuery, R as mapRawItemsById, T as findDirectChildrenByFullKey, U as summarizeFocusItemNode, V as resolveItemSummary, W as summarizeItemById, X as unique, Y as translationEntrySchema, Z as analyzeSurveyAssistantExpressionReferences, b as buildItemConfigDetails, f as normalizeSurveyChangeOperations, i as auditSurvey, j as getRawSurvey, l as createSurveyChangeSet, m as expressionMutationSchema, p as buildExpressionMutationPatches, q as summarizeOutlineNode, v as buildConfigSearchText, w as clampLimit, x as buildItemTranslationEntries, y as buildEmbeddedFormDetails, z as normalizeText } from "./engine-CQwOAcwK.mjs";
-import { r as getSurveyAssistantEngineContext, s as requireSurveyAssistantTurnState } from "./request-context-BjTHNcDd.mjs";
-import { a as surveyAuthoringReferences, i as surveyAuthoringReferenceTopics, r as getBuiltInItemTypeAuthoringReference, t as builtInSurveyAuthoringItemTypes } from "./authoring-references-CW38pYzK.mjs";
+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 { z } from "zod";
-import { JsonPatchError, SURVEY_EDITOR_ITEM_COLORS, encodeJsonPointerSegment, getAssetUsagesFromContent, getContentPlainText, getValueAtJsonPointer } from "@case-framework/survey-core";
+import { JsonPatchError, SURVEY_EDITOR_ITEM_COLORS, encodeJsonPointerSegment, getAssetUsagesFromContent, getContentPlainText, getValueAtJsonPointer, isBlockingSurveyExpressionReferenceDiagnostic } from "@case-framework/survey-core";
 import { randomUUID } from "node:crypto";
 import { createTool, isValidationError } from "@mastra/core/tools";
 //#region src/server/operation-contract-reference.ts
@@ -53,12 +53,17 @@ const formatItemCapabilityProfile = (manifest, kind) => {
 		"",
 		`${manifest.displayName}: ${manifest.description ?? "No additional 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).join(", ")}.` : "Fixed content surfaces: none.",
-		patternedSurfaces.length > 0 ? `Dynamic content surfaces: ${patternedSurfaces.map((surface) => surface.key).join(", ")}.` : void 0,
-		kind === "create-item" && requiredSurfaces.length > 0 ? `Required on creation: ${requiredSurfaces.map((surface) => surface.key).join(", ")}.` : void 0,
-		manifest.referenceTopics?.length ? `Load a dedicated reference only when needed: ${manifest.referenceTopics.join(", ")}.` : 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({
+			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");
@@ -76,9 +81,9 @@ const formatSurveyOperationContractReference = (kind, options = {}) => {
 		`# \`${kind}\` operation contract`,
 		"",
 		"This JSON Schema is generated from the structural validator used by `survey_change`; it is",
-		"the canonical field shape. Cross-field and snapshot-dependent rules are enforced when the",
-		"proposal is validated. The tool may normalize limited schema-near shorthand, but prefer this",
-		"canonical form.",
+		"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.",
 		"",
 		"```json",
@@ -139,7 +144,7 @@ const suggestCanonicalNames = (input, candidates, limit = 3) => [...new Set(cand
 //#endregion
 //#region src/server/tools/tool-model-output.ts
 const FALLBACK_MODEL_TEXT = "The tool returned no model-readable output. Review the tool arguments and retry with valid values.";
-const unwrapToolOutput$1 = (value) => value && typeof value === "object" && "output" in value && value.output !== void 0 ? value.output : value;
+const unwrapToolOutput = (value) => value && typeof value === "object" && "output" in value && value.output !== void 0 ? value.output : value;
 const createTextModelOutput = (text) => ({
 	type: "content",
 	value: [{
@@ -148,7 +153,7 @@ const createTextModelOutput = (text) => ({
 	}]
 });
 const toTextModelOutput = (value, summarize) => {
-	const output = unwrapToolOutput$1(value);
+	const output = unwrapToolOutput(value);
 	if (isValidationError(output)) return createTextModelOutput(output.message);
 	try {
 		return createTextModelOutput(summarize(output));
@@ -158,7 +163,7 @@ const toTextModelOutput = (value, summarize) => {
 };
 //#endregion
 //#region src/server/tools/survey-authoring-reference-tool.ts
-const TOOL_ID$10 = "survey_authoring_reference";
+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."),
@@ -181,7 +186,7 @@ const formatCanonicalNameRecovery = (input, candidates, noun) => {
 	return suggestions.length > 0 ? ` Closest canonical ${noun}${suggestions.length === 1 ? "" : "s"}: ${suggestions.map((value) => `"${value}"`).join(", ")}. Retry with the intended canonical name.` : " Retry without the focused name to load the available catalog.";
 };
 const surveyAuthoringReferenceTool = createTool({
-	id: TOOL_ID$10,
+	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.",
 	inputSchema: inputSchema$10,
 	outputSchema: outputSchema$8,
@@ -264,14 +269,27 @@ const surveyAuthoringReferenceTool = createTool({
 			title: capabilityReference.title ?? `${capability?.manifest.displayName} authoring`,
 			content: capabilityReference.markdown
 		} : void 0;
-		const entry = focusedBuiltInItemTypeReference ?? capabilityEntry ?? builtInEntry;
+		const focusedCapabilityProfile = inputData.topic === "item-types" && itemCapability ? {
+			title: itemCapability.displayName,
+			content: formatItemCapabilityProfile(itemCapability)
+		} : void 0;
+		const baseEntry = inputData.topic === "item-types" && inputData.itemType ? focusedBuiltInItemTypeReference ?? focusedCapabilityProfile : builtInEntry;
+		const entry = baseEntry && capabilityEntry ? {
+			title: baseEntry.title,
+			content: baseEntry.content === capabilityEntry.content ? baseEntry.content : [
+				baseEntry.content,
+				"## Item-specific constraints",
+				"Apply the following capability constraints when using the shared grammar above.",
+				capabilityEntry.content
+			].join("\n\n")
+		} : baseEntry ?? capabilityEntry;
 		if (!entry) return {
 			ok: false,
 			topic: inputData.topic,
 			itemType: inputData.itemType,
 			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, "reference")
+			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")
 		};
 		return {
 			ok: true,
@@ -285,29 +303,44 @@ const surveyAuthoringReferenceTool = createTool({
 	toModelOutput: (value) => toTextModelOutput(value, (output) => `# ${output.title}\n\n${output.content}`)
 });
 //#endregion
+//#region src/server/tools/mutation-recovery.ts
+const retryOfChangeIdsSchema = z.array(z.string().min(1)).max(20).optional().describe("Rejected ids for required retries or intentional removal of pending targets. Retry the complete corrected scope with non-empty mutations. Only allowsAcknowledgment permits inspected no-ops via survey_change operations: []. Linkage never clears identifiable pending edits.");
+const summarizePendingRepairs = (event) => {
+	if (!event.pendingRepairs?.length) return [];
+	const requiredIds = event.pendingRepairs.filter((repair) => repair.requiresExplicitRetry).map((repair) => repair.changeId);
+	return [
+		...requiredIds.length > 0 ? [`Required retry linkage (copy exactly): ${JSON.stringify({ retryOfChangeIds: requiredIds })}. This addresses linkage only; preserve the requested content and structure while correcting validation errors.`] : [],
+		"TURN APPLY STATE: BLOCKED. These rejected proposal obligations remain unapplied. Repair every target; successful partial retries accumulate but do not clear the remaining obligations.",
+		...event.pendingRepairs.map((repair) => `Rejected change ${repair.changeId}: ${JSON.stringify(repair.targets)}.${repair.requiresExplicitRetry ? ` This repair requires explicit linkage. Include every id in the aggregate Required retry linkage above with the complete corrected scope. ${repair.allowsAcknowledgment ? "Validator-confirmed no-op obligations may be acknowledged after inspection with survey_change operations: []; other obligations remain pending." : "A non-empty corrected retry is required; an empty acknowledgment cannot resolve this rejection."} Identifiable targets still need repair. No further mutations are staged until required links are supplied.` : " Retry these same operations and surfaces with corrected values. If intentionally removing a pending target, include its rejected change id in retryOfChangeIds."}`)
+	];
+};
+//#endregion
 //#region src/server/tools/survey-change-tool.ts
-const TOOL_ID$9 = "survey_change";
+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.",
-	"Create items with { kind: \"create-item\", target: { parentItemId, index? }, item: { id?, key, itemType, config }, translations? }. Put respondent content in top-level translations and item settings in item.config.",
-	"Use update-item-translation with itemId, locale, contentKey, and plainText for ordinary text or content for a complete structured value. Item titles and option/field labels are translations, not item labels.",
+	"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 placement that already exists in the live survey or validated turn draft.",
+	"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.",
-	"Raw fallback is one { kind: \"survey-json-patch\", patches } operation containing all related survey-rooted edits; it must be the only operation in the call.",
+	"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."
 ].join(" ");
 const inputSchema$9 = z.object({
+	retryOfChangeIds: retryOfChangeIdsSchema,
 	summary: z.string().min(1).max(500).describe("Short user-facing summary of the intended survey change."),
-	operations: z.array(z.unknown()).min(1).max(200).describe(OPERATIONS_DESCRIPTION)
+	operations: z.array(z.unknown()).min(0).max(200).describe(OPERATIONS_DESCRIPTION)
 }).strict();
 const rejectedOperationParseEvent = ({ issueText, summary, turnId }) => ({
 	protocolVersion: 1,
@@ -413,10 +446,11 @@ const summarizeValidation = (event) => {
 		lines.push("Warnings:");
 		for (const warning of event.validation.warnings) lines.push(`- ${warning.code}: ${warning.message}`);
 	}
+	lines.push(...summarizePendingRepairs(event));
 	return lines.join("\n");
 };
 const surveyChangeTool = createTool({
-	id: TOOL_ID$9,
+	id: TOOL_ID$5,
 	description: "Add one bounded typed-operation delta to the request-scoped survey draft. Successful calls are immediately visible to every later tool in this turn. Rejected calls leave the draft unchanged; retry the failed target. The live editor changes once after successful completion. Every operation uses \"kind\".",
 	inputSchema: inputSchema$9,
 	outputSchema: surveyChangeSetSchema,
@@ -431,13 +465,20 @@ const surveyChangeTool = createTool({
 		const { turnDraft, turnId } = requireSurveyAssistantTurnState(context?.requestContext);
 		const snapshot = getSurveyAssistantEngineContext(context?.requestContext);
 		const defaultLocale = snapshot?.ui.selectedLocale ?? snapshot?.inspection.locales[0] ?? "en";
-		const operationsParse = z.array(surveyOperationSchema).safeParse(normalizeSurveyChangeOperations(inputData.operations, defaultLocale));
+		const normalized = normalizeSurveyChangeOperations(inputData.operations, defaultLocale);
+		if (normalized.issues.length > 0) return turnDraft.reject(rejectedOperationParseEvent({
+			summary: inputData.summary,
+			turnId,
+			issueText: normalized.issues.slice(0, 8).map((issue) => `${issue.path}: ${issue.message}`).join("; ")
+		}), collectMalformedSurveyOperationRecoveryTargets(normalized.operations, snapshot, normalized.issues));
+		const operationsParse = z.array(surveyOperationSchema).safeParse(normalized.operations);
 		if (!operationsParse.success) return turnDraft.reject(rejectedOperationParseEvent({
 			summary: inputData.summary,
 			turnId,
 			issueText: operationsParse.error.issues.slice(0, 8).map((issue) => `${issue.path.join(".") || "operation"}: ${issue.message}`).join("; ")
-		}));
+		}), collectMalformedSurveyOperationRecoveryTargets(normalized.operations, snapshot, normalized.issues));
 		return turnDraft.stage({
+			retryOfChangeIds: inputData.retryOfChangeIds,
 			operations: operationsParse.data,
 			snapshot,
 			summary: inputData.summary
@@ -447,28 +488,39 @@ const surveyChangeTool = createTool({
 });
 //#endregion
 //#region src/server/tools/survey-expression-tool.ts
-const TOOL_ID$8 = "survey_expression";
-const contextActionSchema = z.object({
-	action: z.literal("context"),
-	reason: z.string().max(500).optional(),
-	itemIds: z.array(z.string().min(1).max(240)).max(12).optional(),
-	includeRawLocations: z.boolean().optional()
-});
+const TOOL_ID$4 = "survey_expression";
+const MAX_EXPRESSION_MUTATIONS_PER_PROPOSAL = 40;
+const expressionMutationListSchema = z.array(expressionMutationSchema).min(1).max(MAX_EXPRESSION_MUTATIONS_PER_PROPOSAL);
 const prepareActionSchema = z.object({
 	action: z.literal("prepare"),
 	summary: z.string().min(1).max(500),
-	mutations: z.array(expressionMutationSchema).min(1).max(40)
+	mutations: expressionMutationListSchema
 });
 const inputSchema$8 = z.object({
-	action: z.enum(["context", "prepare"]).describe("Choose exactly one envelope. Inspect with { \"action\": \"context\", \"itemIds\"?: [...], \"includeRawLocations\"?: true, \"reason\"?: \"...\" }; omit summary and mutations. Create edits with { \"action\": \"prepare\", \"summary\": \"...\", \"mutations\": [...] }; omit reason, itemIds, and includeRawLocations."),
-	reason: z.string().max(500).optional(),
-	itemIds: z.array(z.string().min(1).max(240)).max(12).optional().describe("Context action only: optional item ids/keys to focus existing expression locations. Omit for prepare."),
-	includeRawLocations: z.boolean().optional().describe("Context action only: include existing expression locations by raw item. Omit for prepare."),
-	summary: z.string().min(1).max(500).optional().describe("Prepare action only: required user-facing summary. Omit for context."),
-	mutations: z.array(z.record(z.string(), z.unknown())).min(1).max(40).optional().describe("Prepare action only: required expression mutation objects using kebab-case kind names; omit this field for context. Item visibility shape: { kind: \"set-item-display-condition\", itemId: \"<existing-item-id>\", expression: { type: \"function\", functionName: \"eq\", arguments: [...] } }. expression is always CASE expression JSON, never a string or expression-language snippet. Other supported kinds set/clear component display/disabled conditions, validation expressions, prefills, and template values.")
+	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."),
+	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.`)
 }).strict().superRefine((value, ctx) => {
-	if (value.action !== "prepare") return;
-	if (!value.summary) ctx.addIssue({
+	if (value.action === "context") {
+		if (value.summary?.trim()) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ["summary"],
+			message: "Omit summary for context; use action=prepare to stage mutations."
+		});
+		if (value.mutations !== void 0) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ["mutations"],
+			message: "Omit mutations for context; use action=prepare to stage mutations."
+		});
+		return;
+	}
+	if (!value.summary?.trim()) ctx.addIssue({
 		code: z.ZodIssueCode.custom,
 		path: ["summary"],
 		message: "Required for prepare."
@@ -476,7 +528,7 @@ const inputSchema$8 = z.object({
 	if (!value.mutations?.length) ctx.addIssue({
 		code: z.ZodIssueCode.custom,
 		path: ["mutations"],
-		message: "At least one mutation is required for prepare."
+		message: "A non-empty mutation array is required for prepare."
 	});
 });
 const contextOutputSchema = z.object({
@@ -484,6 +536,11 @@ const contextOutputSchema = z.object({
 	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."),
+	nextCursor: z.string().optional(),
+	totalResponseSlots: z.number().int().nonnegative().optional(),
+	surveyResponseSlotCount: z.number().int().nonnegative().optional(),
+	totalExpressionLocations: z.number().int().nonnegative().optional(),
+	unresolvedItemIds: z.array(z.string()).optional(),
 	responseSlots: z.array(z.object({
 		ref: z.string(),
 		valueType: z.string().optional()
@@ -501,22 +558,6 @@ const createIssue = ({ severity = "error", ...input }) => ({
 	severity,
 	...input
 });
-const expressionMutationTarget = (mutation) => {
-	switch (mutation.kind) {
-		case "set-item-display-condition":
-		case "clear-item-display-condition": return `expression:item:${mutation.itemId}:display`;
-		case "set-component-display-condition":
-		case "clear-component-display-condition": return `expression:item:${mutation.itemId}:component:${mutation.componentId}:display`;
-		case "set-component-disabled-condition":
-		case "clear-component-disabled-condition": return `expression:item:${mutation.itemId}:component:${mutation.componentId}:disabled`;
-		case "set-validation-expression":
-		case "clear-validation-expression": return `expression:item:${mutation.itemId}:validation:${mutation.validationKey}`;
-		case "set-prefill": return `expression:item:${mutation.itemId}:prefill:${mutation.prefill.id}`;
-		case "clear-prefill": return `expression:item:${mutation.itemId}:prefill:${mutation.prefillId}`;
-		case "set-template-value":
-		case "clear-template-value": return `expression:template:${mutation.templateKey}`;
-	}
-};
 const buildResponseSlotTypes = (snapshot) => snapshot.responseSlotTypes;
 const rejectedEvent = ({ issues, summary, turnId, warnings = [] }) => ({
 	protocolVersion: 1,
@@ -545,17 +586,26 @@ const summarizeDraftEvent = (event) => {
 		lines.push("Warnings:");
 		for (const warning of event.validation.warnings) lines.push(`- ${warning.code}: ${warning.message}`);
 	}
+	lines.push(...summarizePendingRepairs(event));
 	return lines.join("\n");
 };
 const buildContextOutput = (snapshot, input) => {
 	const rawItems = getRawSurveyItems(snapshot);
-	const responseSlotTypes = buildResponseSlotTypes(snapshot);
-	const responseSlots = Object.entries(responseSlotTypes).map(([ref, valueType]) => ({
+	const resolvedItems = input.itemIds?.map((identifier) => ({
+		identifier,
+		itemId: snapshot.inspection.keyIndex.find((entry) => entry.itemId === identifier || entry.key === identifier || entry.fullKey === 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 itemFilter = input.action === "context" && input.itemIds?.length ? new Set(input.itemIds) : void 0;
-	const expressionLocations = input.action === "context" && input.includeRawLocations === true ? rawItems.map((item, rawIndex) => {
+	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,
@@ -572,6 +622,9 @@ const buildContextOutput = (snapshot, input) => {
 			locations
 		};
 	}).filter((entry) => Boolean(entry)) : void 0;
+	const expressionLocations = allExpressionLocations?.slice(offset, offset + limit);
+	const totalAvailable = Math.max(allResponseSlots.length, allExpressionLocations?.length ?? 0);
+	const nextCursor = offset + limit < totalAvailable ? String(offset + limit) : void 0;
 	return {
 		ok: true,
 		action: "context",
@@ -580,13 +633,23 @@ const buildContextOutput = (snapshot, input) => {
 			"Use prepare mutations for display conditions, disabled conditions, validations, prefills, and template values.",
 			"Display, disabled, validation, and prefill.when expressions must return boolean.",
 			"Use response refs exactly as listed and check their value types before choosing functions.",
+			"An isDefined ref means only that the respondent answered; it never means a particular answer such as Yes, selected, eligible, or has children.",
+			"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.",
 			"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.",
-			`Response slots (${responseSlots.length}): ${responseSlots.slice(0, 80).map((slot) => `${slot.ref}${slot.valueType ? `:${slot.valueType}` : ""}`).join(", ")}`,
-			responseSlots.length > 80 ? "Response slot list truncated in summary; inspect context result for more." : void 0,
+			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(", ")}`,
+			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
 		].filter((line) => Boolean(line)).join("\n"),
+		totalResponseSlots: allResponseSlots.length,
+		surveyResponseSlotCount: surveyResponseSlots.length,
+		...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.",
@@ -597,7 +660,7 @@ const buildContextOutput = (snapshot, input) => {
 	};
 };
 const surveyExpressionTool = createTool({
-	id: TOOL_ID$8,
+	id: TOOL_ID$4,
 	description: "Inspect response refs or add general expression edits to the request-scoped survey draft. Successful mutation calls are immediately visible to later tools; rejected calls leave the draft unchanged. Covers display and disabled conditions, validations, prefills, and template values.",
 	inputSchema: inputSchema$8,
 	outputSchema: outputSchema$7,
@@ -630,13 +693,22 @@ const surveyExpressionTool = createTool({
 				})]
 			}));
 		}
-		if (input.action === "context") {
-			const contextParse = contextActionSchema.safeParse(inputData);
-			return buildContextOutput(snapshot, contextParse.success ? contextParse.data : input);
-		}
+		if (input.action === "context") return buildContextOutput(snapshot, input);
 		const { turnDraft, turnId } = requireSurveyAssistantTurnState(requestContext);
-		const reject = (event, addressedTargets = []) => turnDraft.reject(event, addressedTargets);
-		const prepareParse = prepareActionSchema.safeParse(inputData);
+		const reject = (event, addressedTargets = [], refinements = []) => turnDraft.reject(event, addressedTargets, refinements);
+		if (!Array.isArray(input.mutations)) return reject(rejectedEvent({
+			summary: input.summary ?? "Expression change",
+			turnId,
+			issues: [createIssue({
+				code: "invalid-expression-mutation-shape",
+				message: "mutations is required for prepare and must be a canonical mutation array."
+			})]
+		}));
+		const prepareParse = prepareActionSchema.safeParse({
+			action: input.action,
+			summary: input.summary,
+			mutations: input.mutations
+		});
 		if (!prepareParse.success) return reject(rejectedEvent({
 			summary: input.summary ?? "Expression change",
 			turnId,
@@ -644,22 +716,10 @@ const surveyExpressionTool = createTool({
 				code: "invalid-expression-mutation-shape",
 				message: prepareParse.error.issues.slice(0, 8).map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ")
 			})]
-		}));
+		}), collectExpressionMutationRecoveryTargets(input.mutations, snapshot));
 		const prepareInput = prepareParse.data;
-		const addressedTargets = [...new Set(prepareInput.mutations.map(expressionMutationTarget))];
-		const issues = [];
-		const patches = [];
-		const responseSlotTypes = buildResponseSlotTypes(snapshot);
-		prepareInput.mutations.forEach((mutation, operationIndex) => {
-			buildExpressionMutationPatches({
-				mutation,
-				operationIndex,
-				issues,
-				patches,
-				responseSlotTypes,
-				snapshot
-			});
-		});
+		const addressedTargets = collectExpressionMutationRecoveryTargets(prepareInput.mutations, snapshot);
+		const { issues, patches } = buildExpressionMutationBatch(prepareInput.mutations, snapshot);
 		const errors = issues.filter((issue) => issue.severity === "error");
 		const warnings = issues.filter((issue) => issue.severity === "warning");
 		if (errors.length > 0) return reject(rejectedEvent({
@@ -667,21 +727,26 @@ const surveyExpressionTool = createTool({
 			turnId,
 			issues: errors,
 			warnings
-		}), addressedTargets);
-		if (patches.length === 0) return reject(rejectedEvent({
-			summary: prepareInput.summary,
-			turnId,
-			issues: [createIssue({
+		}), collectExpressionMutationRecoveryTargets(prepareInput.mutations, snapshot, errors), collectExpressionMutationRecoveryRefinements(prepareInput.mutations, snapshot, errors));
+		if (patches.length === 0) {
+			const noPatchIssues = prepareInput.mutations.map((_, operationIndex) => createIssue({
 				code: "no-expression-patches",
-				message: "No expression patches were produced. Check whether the requested locations already match the target state."
-			})],
-			warnings
-		}), addressedTargets);
+				operationIndex,
+				message: "No expression patches were produced. Inspect whether the requested locations already match the target state; acknowledge already-satisfied work through a linked survey_change with operations: []."
+			}));
+			return reject(rejectedEvent({
+				summary: prepareInput.summary,
+				turnId,
+				issues: noPatchIssues,
+				warnings
+			}), collectExpressionMutationRecoveryTargets(prepareInput.mutations, snapshot, noPatchIssues), collectExpressionMutationRecoveryRefinements(prepareInput.mutations, snapshot, noPatchIssues));
+		}
 		const operation = {
 			kind: "survey-json-patch",
 			patches
 		};
 		const event = turnDraft.stage({
+			retryOfChangeIds: input.retryOfChangeIds,
 			addressedTargets,
 			allowExpressionJsonPatches: true,
 			handledMutationRoutes: ["expression"],
@@ -700,8 +765,14 @@ const surveyExpressionTool = createTool({
 	toModelOutput: (value) => toTextModelOutput(value, (output) => "action" in output && output.action === "context" ? output.modelSummary : summarizeDraftEvent(output))
 });
 //#endregion
-//#region src/server/tools/survey-get-current-context-tool.ts
-const TOOL_ID$7 = "survey_get_current_context";
+//#region src/server/tools/parse-inspection-output.ts
+const parseInspectionOutput = (schema, value, backend) => {
+	const parsed = schema.safeParse(value);
+	if (!parsed.success) throw new Error(`${backend} produced invalid inspection output.`, { cause: parsed.error });
+	return parsed.data;
+};
+//#endregion
+//#region src/server/tools/inspect-current-context.ts
 const contextScopeSchema = z.enum([
 	"summary",
 	"selected-item",
@@ -723,7 +794,7 @@ const translationSnippetSchema = z.object({
 const inputSchema$7 = z.object({
 	scopes: z.array(contextScopeSchema).min(1).default(["summary"]).describe("Which current editor context sections to inspect."),
 	itemId: z.string().optional().describe("Optional item id to inspect. Defaults to the selected/focused item."),
-	query: z.string().max(160).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, keys, labels, or response slots."),
 	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."),
 	limit: z.number().int().min(1).max(50).default(12).describe("Maximum number of rows to return for list-like scopes.")
@@ -962,128 +1033,67 @@ const buildResponseSlots = (snapshot, input) => {
 		slots: page.items
 	};
 };
-const summarizeForModel$3 = (output) => {
-	if (!output.ok) return output.reason ?? "Current editor context is unavailable.";
-	const lines = [`Snapshot revision ${output.revision}, content hash ${output.contentHash}.`];
-	if (output.summary) {
-		const selected = output.summary.selectedItemId ?? "none";
-		const surveyKey = output.summary.surveyKey ?? "not set";
-		lines.push(`Summary: view=${output.summary.view}; selectedItemId=${selected}; locale=${output.summary.selectedLocale}; surveyKey=${surveyKey}; itemCount=${output.summary.itemCount} (excluding the structural root group).`);
-		if (output.summary.rootItem) lines.push(`Root group for top-level create-item target.parentItemId: ${output.summary.rootItem.fullKey} (id=${output.summary.rootItem.itemId}, key=${output.summary.rootItem.key}).`);
-		lines.push(`Outline access: ${output.summary.outlineItemCount} item(s), including the structural root group, are pageable.`);
-		const creatableDetails = output.summary.itemTypeDetails.filter((entry) => entry.create === "deterministic").map((entry) => {
-			const primarySurface = entry.contentSurfaces.find((surface) => surface.role === "primary");
-			const fixedSurfaces = entry.contentSurfaces.filter((surface) => !surface.pattern).map((surface) => surface.key);
-			const patterns = entry.contentSurfaces.filter((surface) => surface.pattern).map((surface) => surface.key);
-			const contentKeys = [
-				primarySurface ? `primary=${primarySurface.key}` : void 0,
-				fixedSurfaces.length ? `visible=${fixedSurfaces.join("|")}` : void 0,
-				patterns.length ? `dynamic=${patterns.join("|")}` : void 0,
-				entry.authoring?.compactHint
-			].filter((value) => Boolean(value)).join("; ");
-			return contentKeys ? `${entry.itemType} (${contentKeys})` : entry.itemType;
-		});
-		if (creatableDetails.length > 0) lines.push(`Creatable item types: ${creatableDetails.join(", ")}.`);
-	}
-	if (output.selectedItem) if (output.selectedItem.available && output.selectedItem.item) {
-		lines.push(`Selected item: ${output.selectedItem.item.fullKey} (${output.selectedItem.item.itemType})${output.selectedItem.item.itemLabel ? ` - ${output.selectedItem.item.itemLabel}` : ""}.`);
-		if (output.selectedItem.translationSnippets?.length) lines.push(`Translation snippets: ${output.selectedItem.translationSnippets.map((entry) => `${entry.locale}.${entry.contentKey}: ${entry.text}`).join("; ")}`);
-	} else lines.push(`Selected item unavailable: ${output.selectedItem.reason ?? "unknown reason"}.`);
-	if (output.outline) {
-		lines.push(`Outline (${output.outline.strategy}${output.outline.mode ? `, mode=${output.outline.mode}` : ""}): ${output.outline.returned}/${output.outline.totalAvailable} rows returned.`);
-		for (const item of output.outline.items) lines.push(`- ${item.fullKey} (${item.itemType})${item.itemLabel ? ` - ${item.itemLabel}` : ""}`);
-		lines.push(`Outline order: ${output.outline.ordering}`);
-		if (output.outline.nextCursor) lines.push(`More outline rows are available with cursor ${output.outline.nextCursor}.`);
-	}
-	if (output.responseSlots) {
-		lines.push(output.responseSlots.available ? `Response slots: ${output.responseSlots.slots.join(", ") || "none"}` : `Response slots unavailable: ${output.responseSlots.note ?? "not indexed"}.`);
-		if (output.responseSlots.available) lines.push(`Response-slot order: ${output.responseSlots.ordering}`);
-	}
-	if (output.uiContext) lines.push(`UI context: activeSurface=${output.uiContext.activeSurface ?? "not provided"}; openPanels=${output.uiContext.openPanels.join(", ") || "none"}; highlights=${output.uiContext.highlights.map((entry) => entry.label ?? entry.itemId ?? entry.componentId ?? entry.kind).join(", ") || "none"}.`);
-	if (output.history) lines.push(`Recent editor history (${output.history.currentIndex + 1}/${output.history.totalEntries}): ${output.history.recent.map((entry) => `${entry.index}:${entry.label}${entry.isCurrent ? " [current]" : ""}`).join("; ") || "none"}.`);
-	return lines.join("\n");
+const inspectSurveyCurrentContext = (inputData, requestContext) => {
+	const input = inputSchema$7.parse({
+		...inputData,
+		outlineMode: inputData.outlineMode ?? "full"
+	});
+	const snapshot = getSurveyAssistantEngineContext(requestContext);
+	if (!snapshot) return {
+		ok: false,
+		reason: "No live editor snapshot was provided with this assistant turn.",
+		scopes: input.scopes
+	};
+	const scopes = unique(input.scopes);
+	const listOrdering = {};
+	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."
+	});
+	if (scopes.includes("selected-item")) Object.assign(listOrdering, {
+		"selectedItem.pathItems": "Root-to-selected survey-tree path.",
+		"selectedItem.siblingItems": "Source survey item storage order; not necessarily respondent-visible order.",
+		"selectedItem.childItems": "Stored group-child order when the focused item is a group.",
+		"selectedItem.translationSnippets": "Grouped by locale and then source translation-key order; not positional survey content.",
+		"selectedItem.descendantItems": "Depth-first survey-tree traversal from the selected item."
+	});
+	if (scopes.includes("ui-context")) Object.assign(listOrdering, {
+		"uiContext.openPanels": "UI-provided set-like list; position has no meaning.",
+		"uiContext.highlights": "UI-provided set-like list; position has no meaning."
+	});
+	if (scopes.includes("history")) listOrdering["history.recent"] = "Chronological editor history, oldest to newest within this returned window.";
+	const output = {
+		ok: true,
+		revision: snapshot.version.revision,
+		contentHash: snapshot.version.contentHash,
+		scopes,
+		...Object.keys(listOrdering).length > 0 ? { listOrdering } : {}
+	};
+	if (scopes.includes("summary")) output.summary = buildSummary(snapshot);
+	if (scopes.includes("selected-item")) output.selectedItem = buildSelectedItem(snapshot, input);
+	if (scopes.includes("outline")) output.outline = buildOutline(snapshot, input);
+	if (scopes.includes("response-slots")) output.responseSlots = buildResponseSlots(snapshot, input);
+	if (scopes.includes("ui-context")) output.uiContext = {
+		activeSurface: snapshot.ui.activeSurface,
+		openPanels: snapshot.ui.openPanels ?? [],
+		highlights: snapshot.ui.highlights ?? []
+	};
+	if (scopes.includes("history") && snapshot.ui.history) output.history = snapshot.ui.history;
+	return parseInspectionOutput(outputSchema$6, output, "Current-context inspection");
 };
-const surveyGetCurrentContextTool = createTool({
-	id: TOOL_ID$7,
-	description: "Read the current Survey Editor context from the latest request snapshot. Use for questions about this screen, selected item, survey outline, item keys, labels, locales, or response slots. The outline scope can page the complete survey key index, so use cursor/limit instead of guessing when a focused outline is truncated.",
-	inputSchema: inputSchema$7,
-	outputSchema: outputSchema$6,
-	mcp: { annotations: {
-		title: "Get current survey context",
-		readOnlyHint: true,
-		destructiveHint: false,
-		idempotentHint: true,
-		openWorldHint: false
-	} },
-	execute: async (inputData, context) => {
-		const input = {
-			...inputData,
-			scopes: inputData.scopes ?? ["summary"],
-			limit: inputData.limit ?? 12,
-			outlineMode: inputData.outlineMode ?? "full"
-		};
-		const snapshot = getSurveyAssistantEngineContext(context?.requestContext);
-		if (!snapshot) return {
-			ok: false,
-			reason: "No live editor snapshot was provided with this assistant turn.",
-			scopes: input.scopes
-		};
-		const scopes = unique(input.scopes);
-		const listOrdering = {};
-		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."
-		});
-		if (scopes.includes("selected-item")) Object.assign(listOrdering, {
-			"selectedItem.pathItems": "Root-to-selected survey-tree path.",
-			"selectedItem.siblingItems": "Source survey item storage order; not necessarily respondent-visible order.",
-			"selectedItem.childItems": "Stored group-child order when the focused item is a group.",
-			"selectedItem.translationSnippets": "Grouped by locale and then source translation-key order; not positional survey content.",
-			"selectedItem.descendantItems": "Depth-first survey-tree traversal from the selected item."
-		});
-		if (scopes.includes("ui-context")) Object.assign(listOrdering, {
-			"uiContext.openPanels": "UI-provided set-like list; position has no meaning.",
-			"uiContext.highlights": "UI-provided set-like list; position has no meaning."
-		});
-		if (scopes.includes("history")) listOrdering["history.recent"] = "Chronological editor history, oldest to newest within this returned window.";
-		const output = {
-			ok: true,
-			revision: snapshot.version.revision,
-			contentHash: snapshot.version.contentHash,
-			scopes,
-			...Object.keys(listOrdering).length > 0 ? { listOrdering } : {}
-		};
-		if (scopes.includes("summary")) output.summary = buildSummary(snapshot);
-		if (scopes.includes("selected-item")) output.selectedItem = buildSelectedItem(snapshot, input);
-		if (scopes.includes("outline")) output.outline = buildOutline(snapshot, input);
-		if (scopes.includes("response-slots")) output.responseSlots = buildResponseSlots(snapshot, input);
-		if (scopes.includes("ui-context")) output.uiContext = {
-			activeSurface: snapshot.ui.activeSurface,
-			openPanels: snapshot.ui.openPanels ?? [],
-			highlights: snapshot.ui.highlights ?? []
-		};
-		if (scopes.includes("history") && snapshot.ui.history) output.history = snapshot.ui.history;
-		return output;
-	},
-	toModelOutput: (value) => toTextModelOutput(value, summarizeForModel$3)
-});
 //#endregion
-//#region src/server/tools/survey-get-item-details-tool.ts
-const TOOL_ID$6 = "survey_get_item_details";
-const DEFAULT_TEXT_LIMIT$1 = 400;
-const MAX_TEXT_LIMIT = 2e3;
-const DEFAULT_CHILDREN_LIMIT = 20;
+//#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."),
 	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(MAX_TEXT_LIMIT).default(DEFAULT_TEXT_LIMIT$1).describe("Maximum characters returned per translation snippet."),
+	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."),
-	childrenLimit: z.number().int().min(1).max(50).default(DEFAULT_CHILDREN_LIMIT).describe("Maximum number of direct survey-tree children to return.")
+	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({
 	ok: z.boolean(),
@@ -1099,129 +1109,68 @@ const outputSchema$5 = z.object({
 		details: z.unknown().optional()
 	}).optional()
 });
-const summarizeConfigDetails = (configDetails) => {
-	const lines = [`Config details (${configDetails.kind}): ${configDetails.summary.join("; ")}`];
-	if (configDetails.mainResponseSlotId) lines.push(`Main response slot: ${configDetails.mainResponseSlotId}`);
-	for (const option of configDetails.choiceOptions ?? []) {
-		lines.push(`- ${option.position}. option ${option.key ?? option.id} (id=${option.id}, labelContentKey=${option.labelContentKey})`);
-		if (option.embeddedFormItemId || option.embeddedFormFieldGroupCount) {
-			lines.push(`  embedded form: itemId=${option.embeddedFormItemId ?? "inline"}, fieldGroups=${option.embeddedFormFieldGroupCount ?? 0}, authoringMode=${option.embeddedFormAuthoringMode ?? "custom"}, simpleModeValid=${option.embeddedFormSimpleModeValid ?? true}`);
-			if (option.embeddedFormTranslationPrefix || option.embeddedFormResponseSlotPrefix) lines.push(`  embedded form keys: translationPrefix=${option.embeddedFormTranslationPrefix ?? "n/a"}, responseSlotPrefix=${option.embeddedFormResponseSlotPrefix ?? "n/a"}`);
+const inspectSurveyItemDetails = (inputData, requestContext) => {
+	const input = inputSchema$6.parse({
+		...inputData,
+		includeSurveyChildren: inputData.includeSurveyChildren ?? inputData.includeChildren
+	});
+	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 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.`
+	};
+	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."
 		}
+	};
+	if (input.includeSurveyChildren) {
+		const allChildren = findDirectChildrenByFullKey(getKeyIndexEntries(snapshot), outlineById, item.fullKey);
+		const limit = clampLimit(input.childrenLimit);
+		output.surveyChildren = allChildren.slice(0, limit);
+		output.surveyChildrenTruncated = allChildren.length > limit;
 	}
-	for (const group of configDetails.formFieldGroups ?? []) {
-		lines.push(`- ${group.position}. field group ${group.id}: ${group.fieldCount} field(s), titleContentKey=${group.titleContentKey}, layout=${group.layout.base}/${group.layout.xs}/${group.layout.sm}/${group.layout.md}/${group.layout.xl}`);
-		if (group.hasDisplayCondition !== void 0) lines.push(`  hasDisplayCondition=${group.hasDisplayCondition ? "true" : "false"}`);
-		for (const field of group.fields) {
-			lines.push(`  - ${field.position}. field ${field.key} (${field.type}, id=${field.id}, responseSlot=${field.responseSlotId}, labelContentKey=${field.labelContentKey})`);
-			lines.push(`    extra content keys: description=${field.descriptionContentKey}, error=${field.errorContentKey}${field.placeholderContentKey ? `, placeholder=${field.placeholderContentKey}` : ""}${field.unitContentKey ? `, unit=${field.unitContentKey}` : ""}${field.checkedLabelContentKey ? `, checkedLabel=${field.checkedLabelContentKey}` : ""}${field.uncheckedLabelContentKey ? `, uncheckedLabel=${field.uncheckedLabelContentKey}` : ""}`);
-			if (field.validationTypes?.length) lines.push(`    validations: ${field.validationTypes.join(", ")}`);
-			if (field.validationMessageContentKeys?.length) lines.push(`    validation message keys: ${field.validationMessageContentKeys.join(", ")}`);
-			if (field.selectOptions?.length) lines.push(`    select options: ${field.selectOptions.map((option) => `${option.position}. ${option.value ?? option.id} (${option.labelContentKey})`).join(", ")}`);
+	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];
+			}
 		}
 	}
-	return lines;
-};
-const summarizeForModel$2 = (output) => {
-	if (!output.ok) return output.reason ?? "Item details are unavailable.";
-	const lines = [];
-	if (output.item) lines.push(`Item: ${output.item.fullKey} (${output.item.itemType})${output.item.itemLabel ? ` - ${output.item.itemLabel}` : ""}.`);
-	if (output.translations?.length) lines.push(`Translations: ${output.translations.map((entry) => `${entry.locale}.${entry.contentKey}: ${entry.text}`).join("; ")}`);
-	else lines.push("Translations: none found for this item.");
-	if (output.surveyChildren) {
-		lines.push(`Survey-tree children (${output.surveyChildren.length}):`);
-		for (const child of output.surveyChildren) lines.push(`- ${child.fullKey} (${child.itemType})${child.itemLabel ? ` - ${child.itemLabel}` : ""}`);
-		if (output.surveyChildrenTruncated) lines.push("More children exist than were returned; narrow down or raise childrenLimit.");
-	}
-	if (output.configDetails) {
-		if (output.configDetails.listOrdering) for (const [list, meaning] of Object.entries(output.configDetails.listOrdering)) lines.push(`List order (${list}): ${meaning}`);
-		lines.push(...summarizeConfigDetails(output.configDetails));
-	}
-	if (output.capabilityDetails) {
-		lines.push(`Item capability: ${output.capabilityDetails.summary}`);
-		if (output.capabilityDetails.details !== void 0) lines.push(`Capability details: ${JSON.stringify(output.capabilityDetails.details)}`);
-	}
-	return lines.join("\n");
+	return parseInspectionOutput(outputSchema$5, output, "Item-details inspection");
 };
-const surveyGetItemDetailsTool = createTool({
-	id: TOOL_ID$6,
-	description: "Fetch full details for a SPECIFIC survey item, whether or not it is currently selected. Returns item translations plus item-internal config details such as choice options and form fields. Use survey_search_items first when you only know visible text.",
-	inputSchema: inputSchema$6,
-	outputSchema: outputSchema$5,
-	mcp: { annotations: {
-		title: "Get survey item details",
-		readOnlyHint: true,
-		destructiveHint: false,
-		idempotentHint: true,
-		openWorldHint: false
-	} },
-	execute: async (inputData, context) => {
-		const input = {
-			...inputData,
-			textLimit: inputData.textLimit ?? DEFAULT_TEXT_LIMIT$1,
-			includeSurveyChildren: inputData.includeSurveyChildren ?? inputData.includeChildren ?? false,
-			includeItemConfig: inputData.includeItemConfig ?? true,
-			childrenLimit: inputData.childrenLimit ?? DEFAULT_CHILDREN_LIMIT
-		};
-		const snapshot = getSurveyAssistantEngineContext(context?.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 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.`
-		};
-		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."
-			}
-		};
-		if (input.includeSurveyChildren) {
-			const allChildren = findDirectChildrenByFullKey(getKeyIndexEntries(snapshot), outlineById, item.fullKey);
-			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];
-				}
-			}
-		}
-		return output;
-	},
-	toModelOutput: (value) => toTextModelOutput(value, summarizeForModel$2)
-});
 //#endregion
-//#region src/server/tools/survey-get-raw-survey-tool.ts
-const TOOL_ID$5 = "survey_get_raw_survey";
+//#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 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."),
+	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({
@@ -1250,6 +1199,11 @@ const outputSchema$4 = z.object({
 		found: z.boolean(),
 		value: z.unknown().optional(),
 		preview: z.string().optional(),
+		text: z.string().optional(),
+		textOffset: z.number().int().nonnegative().optional(),
+		textLength: z.number().int().nonnegative().optional(),
+		nextTextOffset: z.number().int().nonnegative().optional(),
+		recovery: z.string().optional(),
 		truncated: z.boolean().optional(),
 		error: z.string().optional()
 	})).optional(),
@@ -1313,10 +1267,27 @@ const buildValues = (snapshot, input) => {
 	const rawSurvey = getRawSurvey(snapshot);
 	return input.paths.map((path) => {
 		try {
+			const value = getValueAtJsonPointer(rawSurvey, path);
+			if (typeof value === "string" && (input.textOffset !== void 0 || JSON.stringify(value).length > input.valueCharacterLimit)) {
+				const characters = [...value];
+				const textOffset = input.textOffset ?? 0;
+				const text = characters.slice(textOffset, textOffset + input.valueCharacterLimit).join("");
+				const nextTextOffset = textOffset + [...text].length;
+				return {
+					path,
+					found: true,
+					text,
+					textOffset,
+					textLength: characters.length,
+					truncated: textOffset > 0 || nextTextOffset < characters.length,
+					...nextTextOffset < characters.length ? { nextTextOffset } : {},
+					recovery: "This is a string segment, not the complete value. Concatenate segments in offset order. Continue with survey_inspect action=raw-json, this same path, and textOffset=nextTextOffset until nextTextOffset is absent. Restart after a draft mutation."
+				};
+			}
 			return {
 				path,
 				found: true,
-				...toOutputValue(getValueAtJsonPointer(rawSurvey, path), input.valueCharacterLimit)
+				...toOutputValue(value, input.valueCharacterLimit)
 			};
 		} catch (error) {
 			return {
@@ -1379,88 +1350,38 @@ const buildItemValues = (snapshot, input) => {
 		};
 	});
 };
-const summarizeForModel$1 = (output) => {
-	if (!output.ok) return output.reason ?? "Raw survey context is unavailable.";
-	const lines = [];
-	if (output.overview) {
-		lines.push(`Raw survey overview: ${output.overview.surveyItemCount} item(s), top-level keys ${output.overview.topLevelKeys.join(", ")}.`);
-		lines.push(`Locales: ${output.overview.locales.join(", ") || "none"}.`);
-		lines.push("Survey item JSON paths:");
-		for (const item of output.overview.itemPaths.slice(0, 50)) lines.push(`- ${item.path}: ${item.key} (${item.itemType}, id=${item.id})${item.parentId ? ` parent=${item.parentId}` : ""}`);
-		if (output.overview.itemPaths.length > 50) lines.push("More item paths exist; request a specific path for exact raw JSON.");
-	}
-	if (output.listOrdering) for (const [list, meaning] of Object.entries(output.listOrdering)) lines.push(`List order (${list}): ${meaning}`);
-	for (const item of output.items ?? []) {
-		if (!item.found) {
-			lines.push(`${item.identifier}: not found (${item.error ?? "unknown error"})`);
-			continue;
-		}
-		lines.push(`${item.identifier}: itemId=${item.itemId}; raw path ${item.itemPath}.`);
-		if (item.translationPaths?.length) lines.push(`Translation paths: ${item.translationPaths.join(", ")}.`);
-		if (item.rawItemTruncated) lines.push(`Raw item truncated preview:\n${item.rawItemPreview ?? ""}`);
-		else lines.push(`Raw item: ${JSON.stringify(item.rawItem)}`);
-		if (item.translationsTruncated) lines.push(`Translations truncated preview:\n${item.translationsPreview ?? ""}`);
-		else lines.push(`Translations by locale: ${JSON.stringify(item.translationsByLocale ?? {})}`);
-	}
-	for (const entry of output.values ?? []) {
-		if (!entry.found) {
-			lines.push(`${entry.path}: not found (${entry.error ?? "unknown error"})`);
-			continue;
-		}
-		if (entry.truncated) lines.push(`${entry.path}: truncated JSON preview:\n${entry.preview ?? ""}`);
-		else lines.push(`${entry.path}: ${JSON.stringify(entry.value)}`);
-	}
-	return lines.join("\n");
+const inspectRawSurvey = (inputData, requestContext) => {
+	const input = inputSchema$5.parse(inputData);
+	const snapshot = getSurveyAssistantEngineContext(requestContext);
+	if (!snapshot) return {
+		ok: false,
+		reason: "No live editor snapshot was provided with this assistant turn."
+	};
+	return parseInspectionOutput(outputSchema$4, {
+		ok: true,
+		revision: snapshot.version.revision,
+		contentHash: snapshot.version.contentHash,
+		listOrdering: {
+			"overview.topLevelKeys": "Alphabetical key order; not survey content order.",
+			"overview.locales": "Selected locale first, then remaining source locale order; locale position has no survey meaning.",
+			"overview.itemPaths": "Stored surveyItems array order. The numeric segment in each JSON Pointer path is its zero-based stored position; this differs from group-child display order.",
+			values: "Same order as the requested JSON Pointer paths.",
+			items: "Same order as the requested itemIdentifiers."
+		},
+		overview: input.paths || input.itemIdentifiers ? void 0 : buildOverview(snapshot),
+		items: input.itemIdentifiers ? buildItemValues(snapshot, {
+			itemIdentifiers: input.itemIdentifiers,
+			valueCharacterLimit: input.valueCharacterLimit ?? DEFAULT_VALUE_CHARACTER_LIMIT
+		}) : void 0,
+		values: input.paths ? buildValues(snapshot, {
+			paths: input.paths,
+			textOffset: input.textOffset,
+			valueCharacterLimit: input.valueCharacterLimit ?? DEFAULT_VALUE_CHARACTER_LIMIT
+		}) : void 0
+	}, "Raw-survey inspection");
 };
-const surveyGetRawSurveyTool = createTool({
-	id: TOOL_ID$5,
-	description: "Inspect exact raw survey JSON by item id/key/fullKey or JSON Pointer path. Use this before survey-json-patch edits to inspect item config, survey-level metadata, maxItemsPerPage, templateValues, translations/locales, or group ordering arrays.",
-	inputSchema: inputSchema$5,
-	outputSchema: outputSchema$4,
-	mcp: { annotations: {
-		title: "Get raw survey JSON",
-		readOnlyHint: true,
-		destructiveHint: false,
-		idempotentHint: true,
-		openWorldHint: false
-	} },
-	execute: async (inputData, context) => {
-		const input = {
-			...inputData,
-			valueCharacterLimit: inputData.valueCharacterLimit ?? DEFAULT_VALUE_CHARACTER_LIMIT
-		};
-		const snapshot = getSurveyAssistantEngineContext(context?.requestContext);
-		if (!snapshot) return {
-			ok: false,
-			reason: "No live editor snapshot was provided with this assistant turn."
-		};
-		return {
-			ok: true,
-			revision: snapshot.version.revision,
-			contentHash: snapshot.version.contentHash,
-			listOrdering: {
-				"overview.topLevelKeys": "Alphabetical key order; not survey content order.",
-				"overview.locales": "Selected locale first, then remaining source locale order; locale position has no survey meaning.",
-				"overview.itemPaths": "Stored surveyItems array order. The numeric segment in each JSON Pointer path is its zero-based stored position; this differs from group-child display order.",
-				values: "Same order as the requested JSON Pointer paths.",
-				items: "Same order as the requested itemIdentifiers."
-			},
-			overview: input.paths || input.itemIdentifiers ? void 0 : buildOverview(snapshot),
-			items: input.itemIdentifiers ? buildItemValues(snapshot, {
-				itemIdentifiers: input.itemIdentifiers,
-				valueCharacterLimit: input.valueCharacterLimit ?? DEFAULT_VALUE_CHARACTER_LIMIT
-			}) : void 0,
-			values: input.paths ? buildValues(snapshot, {
-				paths: input.paths,
-				valueCharacterLimit: input.valueCharacterLimit ?? DEFAULT_VALUE_CHARACTER_LIMIT
-			}) : void 0
-		};
-	},
-	toModelOutput: (value) => toTextModelOutput(value, summarizeForModel$1)
-});
 //#endregion
-//#region src/server/tools/survey-search-items-tool.ts
-const TOOL_ID$4 = "survey_search_items";
+//#region src/server/tools/search-survey-items.ts
 const MAX_QUERY_LENGTH = 180;
 const MAX_MATCHES_PER_ITEM = 6;
 const DEFAULT_TEXT_LIMIT = 220;
@@ -1621,59 +1542,27 @@ const searchItems = (snapshot, input) => {
 		};
 	}).filter((result) => Boolean(result)).sort((a, b) => b.score - a.score || a.item.fullKey.localeCompare(b.item.fullKey));
 };
-const summarizeForModel = (output) => {
-	if (!output.ok) return output.reason ?? "Survey item search is unavailable.";
-	const lines = [`Search "${output.query ?? ""}": ${output.returned ?? 0}/${output.totalAvailable ?? 0} matching item(s) returned.`];
-	for (const result of output.results ?? []) {
-		lines.push(`- ${result.item.fullKey} (${result.item.itemType}, itemId=${result.item.itemId}, score=${result.score})`);
-		for (const match of result.matches) {
-			const source = match.source === "translation" ? `${match.locale}.${match.contentKey}` : match.field ?? match.source;
-			lines.push(`  match ${match.source}:${source}: ${match.text}`);
-		}
-	}
-	if (output.nextCursor) lines.push(`More search results are available with cursor ${output.nextCursor}.`);
-	if (output.ordering) lines.push(`Search-result order: ${output.ordering}`);
-	lines.push("Use survey_inspect with action \"item-details\" and itemRef to inspect a result.");
-	return lines.join("\n");
+const searchSurveyItems = (inputData, requestContext) => {
+	const input = inputSchema$4.parse(inputData);
+	const snapshot = getSurveyAssistantEngineContext(requestContext);
+	if (!snapshot) return {
+		ok: false,
+		reason: "No live editor snapshot was provided with this assistant turn.",
+		query: input.query
+	};
+	const results = searchItems(snapshot, input);
+	const page = sliceWithCursor(results, input);
+	return parseInspectionOutput(outputSchema$3, {
+		ok: true,
+		query: input.query,
+		totalAvailable: results.length,
+		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.",
+		results: page.items
+	}, "Survey-item search");
 };
-const surveySearchItemsTool = createTool({
-	id: TOOL_ID$4,
-	description: "Search all survey items by visible translated text, item keys, labels, and config identifiers. Use this when the user refers to an unselected item by title, label, option text, field label, or another phrase rather than an item id.",
-	inputSchema: inputSchema$4,
-	outputSchema: outputSchema$3,
-	mcp: { annotations: {
-		title: "Search survey items",
-		readOnlyHint: true,
-		destructiveHint: false,
-		idempotentHint: true,
-		openWorldHint: false
-	} },
-	execute: async (inputData, context) => {
-		const input = {
-			...inputData,
-			limit: inputData.limit ?? 12
-		};
-		const snapshot = getSurveyAssistantEngineContext(context?.requestContext);
-		if (!snapshot) return {
-			ok: false,
-			reason: "No live editor snapshot was provided with this assistant turn.",
-			query: input.query
-		};
-		const results = searchItems(snapshot, input);
-		const page = sliceWithCursor(results, input);
-		return {
-			ok: true,
-			query: input.query,
-			totalAvailable: results.length,
-			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.",
-			results: page.items
-		};
-	},
-	toModelOutput: (value) => toTextModelOutput(value, summarizeForModel)
-});
 //#endregion
 //#region src/server/tools/survey-inspect-tool.ts
 const TOOL_ID$3 = "survey_inspect";
@@ -1715,6 +1604,7 @@ const inputSchema$3 = z.object({
 	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.`),
+	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."),
 	limit: optionalInput(z.number().int().min(1).max(50)).describe("Maximum list rows to return.")
@@ -1726,19 +1616,31 @@ const outputSchema$2 = z.object({
 	modelSummary: z.string(),
 	result: z.unknown().optional()
 });
-const runTool = async (tool, input, context) => {
-	const execute = tool.execute;
-	if (!execute) throw new Error("Survey inspection backend is not executable.");
-	return execute(input, context);
-};
-const unwrapToolOutput = (value) => {
-	if (value && typeof value === "object" && "output" in value && value.output !== void 0) return value.output;
-	return value;
-};
 const stringifyForModel = (value) => {
 	if (typeof value === "string") return value;
 	return JSON.stringify(value, null, 2);
 };
+const runInspectionBackend = (inspect) => {
+	try {
+		return {
+			ok: true,
+			value: inspect()
+		};
+	} catch (error) {
+		if (!(error instanceof z.ZodError)) throw error;
+		const firstIssue = error.issues[0];
+		return {
+			ok: false,
+			reason: `Survey inspection validation failed${firstIssue?.path?.length ? ` at ${firstIssue.path.join(".").slice(0, 120)}` : ""}: ${(firstIssue?.message ?? "Invalid internal inspection data.").slice(0, 400)}`
+		};
+	}
+};
+const inspectionBackendFailure = (action, reason) => ({
+	ok: false,
+	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 = [
@@ -1763,6 +1665,7 @@ const listLocalizationSurfaces = (input, snapshot, targetLocale) => {
 	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 } : {},
@@ -1774,11 +1677,17 @@ const listLocalizationSurfaces = (input, snapshot, targetLocale) => {
 			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)
+				targetText: truncateLocalizationText(targetContent),
+				targetTextLength: getContentPlainText(targetContent).trim().length,
+				targetTruncated: getContentPlainText(targetContent).trim().length > MAX_LOCALIZATION_TEXT_CHARS
 			} : {}
 		});
 	};
@@ -1812,6 +1721,7 @@ const listLocalizationSurfaces = (input, snapshot, targetLocale) => {
 			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,
@@ -1903,7 +1813,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, or focused raw JSON. 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 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.",
 	inputSchema: inputSchema$3,
 	outputSchema: outputSchema$2,
 	mcp: { annotations: {
@@ -1915,7 +1825,8 @@ const surveyInspectTool = createTool({
 	} },
 	execute: async (inputData, context) => {
 		const input = inputData;
-		const snapshot = getSurveyAssistantEngineContext(context?.requestContext);
+		const requestContext = context?.requestContext;
+		const snapshot = getSurveyAssistantEngineContext(requestContext);
 		if (!snapshot) return {
 			ok: false,
 			action: input.action,
@@ -1923,14 +1834,16 @@ const surveyInspectTool = createTool({
 			modelSummary: "No survey draft is available for this turn."
 		};
 		if (input.action === "current-context") {
-			const result = unwrapToolOutput(await runTool(surveyGetCurrentContextTool, {
+			const inspection = runInspectionBackend(() => inspectSurveyCurrentContext({
 				scopes: input.scopes ?? ["summary", "selected-item"],
 				limit: input.limit,
 				cursor: input.cursor,
 				itemId: resolveItemRef(input, snapshot),
 				query: input.query,
 				outlineMode: input.outlineMode
-			}, context));
+			}, requestContext));
+			if (!inspection.ok) return inspectionBackendFailure(input.action, inspection.reason);
+			const result = inspection.value;
 			return {
 				ok: true,
 				action: input.action,
@@ -1945,11 +1858,14 @@ const surveyInspectTool = createTool({
 				reason: "Search requires a query.",
 				modelSummary: "Search requires a query."
 			};
-			const result = unwrapToolOutput(await runTool(surveySearchItemsTool, {
-				query: input.query,
+			const query = input.query;
+			const inspection = runInspectionBackend(() => searchSurveyItems({
+				query,
 				limit: input.limit,
 				cursor: input.cursor
-			}, context));
+			}, requestContext));
+			if (!inspection.ok) return inspectionBackendFailure(input.action, inspection.reason);
+			const result = inspection.value;
 			return {
 				ok: true,
 				action: input.action,
@@ -1965,12 +1881,14 @@ const surveyInspectTool = createTool({
 				reason: "No item reference was provided and no item is selected.",
 				modelSummary: "No item reference was provided and no item is selected."
 			};
-			const result = unwrapToolOutput(await runTool(surveyGetItemDetailsTool, {
+			const inspection = runInspectionBackend(() => inspectSurveyItemDetails({
 				itemId,
 				includeSurveyChildren: input.includeChildren ?? false,
 				includeItemConfig: input.includeItemConfig ?? true,
 				childrenLimit: input.limit
-			}, context));
+			}, requestContext));
+			if (!inspection.ok) return inspectionBackendFailure(input.action, inspection.reason);
+			const result = inspection.value;
 			return {
 				ok: true,
 				action: input.action,
@@ -1982,17 +1900,29 @@ const surveyInspectTool = createTool({
 			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 advisoryCount = diagnostics.length - blockingCount;
 			const limit = input.limit ?? 50;
+			const limitedDiagnostics = orderedDiagnostics.slice(0, limit);
+			const guidanceByDispositionAndCategory = {};
+			for (const diagnostic of orderedDiagnostics) {
+				const byCategory = guidanceByDispositionAndCategory[diagnostic.disposition] ??= {};
+				byCategory[diagnostic.category] = getSurveyAssistantExpressionDiagnosticGuidance(diagnostic);
+			}
 			const result = {
-				valid: diagnostics.length === 0,
+				valid: blockingCount === 0,
 				count: diagnostics.length,
-				diagnostics: diagnostics.slice(0, limit),
+				blockingCount,
+				advisoryCount,
+				diagnostics: limitedDiagnostics,
+				guidanceByDispositionAndCategory,
 				truncated: diagnostics.length > limit
 			};
 			return {
 				ok: true,
 				action: input.action,
-				modelSummary: diagnostics.length === 0 ? "No broken expression references were found in the current survey draft." : `${diagnostics.length} broken expression reference${diagnostics.length === 1 ? " was" : "s were"} found. Repair every listed location, then run expression-diagnostics again before claiming completion.\n${stringifyForModel(result)}`,
+				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)}`,
 				result
 			};
 		}
@@ -2030,10 +1960,13 @@ const surveyInspectTool = createTool({
 		const itemIdentifiers = itemId ? [itemId] : void 0;
 		const requestedPaths = itemIdentifiers ? void 0 : input.paths;
 		const boundedPaths = requestedPaths?.slice(0, MAX_RAW_JSON_PATHS_PER_RESULT);
-		const rawResult = unwrapToolOutput(await runTool(surveyGetRawSurveyTool, {
+		const rawInspection = runInspectionBackend(() => inspectRawSurvey({
 			paths: boundedPaths,
-			itemIdentifiers
-		}, context));
+			itemIdentifiers,
+			textOffset: input.textOffset
+		}, requestContext));
+		if (!rawInspection.ok) return inspectionBackendFailure(input.action, rawInspection.reason);
+		const rawResult = rawInspection.value;
 		const ignoredPathCount = itemIdentifiers ? input.paths?.length ?? 0 : 0;
 		const omittedPathCount = Math.max(0, (requestedPaths?.length ?? 0) - (boundedPaths?.length ?? 0));
 		const requestCoverage = ignoredPathCount > 0 || omittedPathCount > 0 ? {
@@ -2204,7 +2137,7 @@ const formatAuditForModel = (output) => {
 				finding.locale,
 				finding.contentKey
 			].filter(Boolean).join(":");
-			return `- ${finding.code}${location ? ` (${location})` : ""}: ${previewAuditMessage(finding.message)}`;
+			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) => {
@@ -2244,6 +2177,7 @@ const surveyAuditTool = createTool({
 //#region src/server/tools/survey-asset-tool.ts
 const TOOL_ID = "survey_asset";
 const inputSchema = z.object({
+	retryOfChangeIds: retryOfChangeIdsSchema,
 	action: z.enum([
 		"import-attachment",
 		"update-metadata",
@@ -2293,12 +2227,13 @@ 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 it in a richText image block inside the create-item translation content.`);
-			lines.push(`New info-item translation example: { "locale": "<selected-locale>", "contentKey": "content", "content": { "type": "richText", "version": 1, "doc": { "type": "doc", "blocks": [{ "type": "image", "source": { "type": "asset", "assetId": "${importedAssetIds[0]}" }, "alt": "<meaningful description>" }] } } }.`);
+			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>" }] }.`);
 		}
 	}
 	if (event.validation.issues.length > 0) lines.push(`Issues:\n${event.validation.issues.map((issue) => `- ${issue.code}: ${issue.message}`).join("\n")}`);
 	if (event.validation.warnings.length > 0) lines.push(`Warnings:\n${event.validation.warnings.map((warning) => `- ${warning.code}: ${warning.message}`).join("\n")}`);
+	lines.push(...summarizePendingRepairs(event));
 	return lines.join("\n");
 };
 const redactEmbeddedImageOperation = (operation) => operation.kind === "set-image-asset" ? {
@@ -2408,9 +2343,10 @@ const surveyAssetTool = createTool({
 					normalizedOperations: []
 				}
 			});
-			if (event.status === "rejected") return turnDraft.reject(event, [`asset:${operation.assetId}`]);
+			if (event.status === "rejected") return turnDraft.reject(event, collectSurveyOperationRecoveryTargets([operation], snapshot));
 		}
 		return turnDraft.stage({
+			retryOfChangeIds: input.retryOfChangeIds,
 			operations: [operation],
 			snapshot,
 			summary: input.summary
@@ -2423,18 +2359,18 @@ const surveyAssetTool = createTool({
 //#region src/server/tools/index.ts
 const SURVEY_ASSISTANT_TOOL_IDS = [
 	TOOL_ID$3,
-	TOOL_ID$9,
-	TOOL_ID$8,
-	TOOL_ID$10,
+	TOOL_ID$5,
+	TOOL_ID$4,
+	TOOL_ID$6,
 	TOOL_ID$2,
 	TOOL_ID$1,
 	TOOL_ID
 ];
 const surveyAssistantTools = Object.freeze({
 	[TOOL_ID$3]: surveyInspectTool,
-	[TOOL_ID$9]: surveyChangeTool,
-	[TOOL_ID$10]: surveyAuthoringReferenceTool,
-	[TOOL_ID$8]: surveyExpressionTool,
+	[TOOL_ID$5]: surveyChangeTool,
+	[TOOL_ID$6]: surveyAuthoringReferenceTool,
+	[TOOL_ID$4]: surveyExpressionTool,
 	[TOOL_ID$2]: surveyAttachmentTool,
 	[TOOL_ID$1]: surveyAuditTool,
 	[TOOL_ID]: surveyAssetTool
@@ -2442,4 +2378,4 @@ const surveyAssistantTools = Object.freeze({
 //#endregion
 export { surveyAuditTool as i, surveyAssistantTools as n, surveyAssetTool as r, SURVEY_ASSISTANT_TOOL_IDS as t };
 
-//# sourceMappingURL=tools-CFh35R4d.mjs.map
+//# sourceMappingURL=tools-BvSovehT.mjs.map