@claritylabs/cl-sdk 0.16.2 → 0.17.1

package/dist/index.mjs

@@ -169,7 +169,14 @@ function createPipelineContext(opts) {
   let latest = opts.resumeFrom;
   const completedPhases = /* @__PURE__ */ new Set();
   if (opts.resumeFrom) {
-    completedPhases.add(opts.resumeFrom.phase);
+    const phaseIndex = opts.phaseOrder?.indexOf(opts.resumeFrom.phase) ?? -1;
+    if (phaseIndex >= 0 && opts.phaseOrder) {
+      for (const phase of opts.phaseOrder.slice(0, phaseIndex + 1)) {
+        completedPhases.add(phase);
+      }
+    } else {
+      completedPhases.add(opts.resumeFrom.phase);
+    }
   }
   return {
     id: opts.id,
@@ -1226,6 +1233,29 @@ var AuxiliaryFactSchema = z16.object({
   subject: z16.string().optional(),
   context: z16.string().optional()
 });
+var DefinitionSchema = z16.object({
+  term: z16.string(),
+  definition: z16.string(),
+  pageNumber: z16.number().optional(),
+  formNumber: z16.string().optional(),
+  formTitle: z16.string().optional(),
+  sectionRef: z16.string().optional(),
+  originalContent: z16.string().optional()
+});
+var CoveredReasonSchema = z16.object({
+  coverageName: z16.string(),
+  reasonNumber: z16.string().optional(),
+  title: z16.string().optional(),
+  content: z16.string(),
+  conditions: z16.array(z16.string()).optional(),
+  exceptions: z16.array(z16.string()).optional(),
+  appliesTo: z16.array(z16.string()).optional(),
+  pageNumber: z16.number().optional(),
+  formNumber: z16.string().optional(),
+  formTitle: z16.string().optional(),
+  sectionRef: z16.string().optional(),
+  originalContent: z16.string().optional()
+});
 var BaseDocumentFields = {
   id: z16.string(),
   carrier: z16.string(),
@@ -1236,6 +1266,8 @@ var BaseDocumentFields = {
   policyTypes: z16.array(z16.string()).optional(),
   coverages: z16.array(CoverageSchema),
   sections: z16.array(SectionSchema).optional(),
+  definitions: z16.array(DefinitionSchema).optional(),
+  coveredReasons: z16.array(CoveredReasonSchema).optional(),
   // Enriched fields (v1.2+)
   carrierLegalName: z16.string().optional(),
   carrierNaicNumber: z16.string().optional(),
@@ -1683,33 +1715,102 @@ async function runExtractor(params) {
   };
 }
 
+// src/extraction/memory.ts
+function isMemoryRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readMemoryRecord(memory, key) {
+  const value = memory.get(key);
+  return isMemoryRecord(value) ? value : void 0;
+}
+function readRecordValue(record, key) {
+  return record?.[key];
+}
+function readRecordArray(record, key) {
+  const value = readRecordValue(record, key);
+  return Array.isArray(value) ? value : void 0;
+}
+function getCarrierInfo(memory) {
+  return readMemoryRecord(memory, "carrier_info");
+}
+function getNamedInsured(memory) {
+  return readMemoryRecord(memory, "named_insured");
+}
+function getCoverageLimits(memory) {
+  return readMemoryRecord(memory, "coverage_limits");
+}
+function getCoverageLimitCoverages(memory) {
+  return readRecordArray(getCoverageLimits(memory), "coverages") ?? [];
+}
+function getSectionsPayload(memory) {
+  return readMemoryRecord(memory, "sections");
+}
+function getSections(memory) {
+  return readRecordArray(getSectionsPayload(memory), "sections");
+}
+function getDefinitionsPayload(memory) {
+  return readMemoryRecord(memory, "definitions");
+}
+function getDefinitions(memory) {
+  return readRecordArray(getDefinitionsPayload(memory), "definitions");
+}
+function getCoveredReasonsPayload(memory) {
+  return readMemoryRecord(memory, "covered_reasons");
+}
+function getCoveredReasons(memory) {
+  const payload = getCoveredReasonsPayload(memory);
+  return readRecordArray(payload, "coveredReasons") ?? readRecordArray(payload, "covered_reasons");
+}
+
 // src/extraction/promote.ts
 function getDeclarationFields(doc) {
   const decl = doc.declarations;
   return Array.isArray(decl?.fields) ? decl.fields : [];
 }
 function fieldMatches(fieldName, patterns) {
-  const lower = fieldName.toLowerCase().replace(/[\s_-]/g, "");
-  return patterns.some((p) => lower === p.toLowerCase().replace(/[\s_-]/g, ""));
+  const lower = normalizeFieldName(fieldName);
+  return patterns.some((p) => lower === normalizeFieldName(p));
+}
+function normalizeFieldName(fieldName) {
+  return fieldName.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
-function findFieldValue(fields, patterns) {
-  const match = fields.find((f) => fieldMatches(f.field, patterns));
+function findFieldValue(fields, patterns, reject) {
+  const match = fields.find((f) => fieldMatches(f.field, patterns) && !reject?.(f));
   return match?.value;
 }
-function promoteCarrierFields(doc) {
-  const raw = doc;
-  if (!raw.carrierNaicNumber && raw.naicNumber) {
-    raw.carrierNaicNumber = raw.naicNumber;
-  }
-  if (!raw.carrierAmBestRating && raw.amBestRating) {
-    raw.carrierAmBestRating = raw.amBestRating;
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function findRawString(raw, keys) {
+  for (const key of keys) {
+    const value = stringValue(raw[key]);
+    if (value) return value;
   }
-  if (!raw.carrierAdmittedStatus && raw.admittedStatus) {
-    raw.carrierAdmittedStatus = raw.admittedStatus;
+  return void 0;
+}
+function promoteRawFields(raw, mappings) {
+  for (const { from, to } of mappings) {
+    if (!raw[to] && raw[from]) {
+      raw[to] = raw[from];
+    }
+    delete raw[from];
   }
-  delete raw.naicNumber;
-  delete raw.amBestRating;
-  delete raw.admittedStatus;
+}
+function findRawOrDeclarationValue(raw, fields, lookup) {
+  return (lookup.rawKey ? raw[lookup.rawKey] : void 0) || findFieldValue(fields, lookup.patterns, lookup.reject);
+}
+function promoteRawOrDeclarationString(raw, fields, targetKey, rawKeys, lookup) {
+  if (raw[targetKey]) return;
+  const value = findRawString(raw, rawKeys) ?? findFieldValue(fields, lookup.patterns, lookup.reject);
+  if (value) raw[targetKey] = value;
+}
+function promoteCarrierFields(doc) {
+  const raw = doc;
+  promoteRawFields(raw, [
+    { from: "naicNumber", to: "carrierNaicNumber" },
+    { from: "amBestRating", to: "carrierAmBestRating" },
+    { from: "admittedStatus", to: "carrierAdmittedStatus" }
+  ]);
   if (!raw.insurer && raw.carrierLegalName) {
     raw.insurer = {
       legalName: raw.carrierLegalName,
@@ -1750,12 +1851,21 @@ var BROKER_ADDRESS_PATTERNS = ["brokerAddress", "agentAddress", "producerAddress
 function promoteBroker(doc) {
   const raw = doc;
   const fields = getDeclarationFields(doc);
-  const brokerAgency = raw.brokerAgency || findFieldValue(fields, BROKER_NAME_PATTERNS);
-  const brokerContact = raw.brokerContactName || findFieldValue(fields, BROKER_CONTACT_PATTERNS);
-  const brokerLicense = raw.brokerLicenseNumber || findFieldValue(fields, BROKER_LICENSE_PATTERNS);
-  const brokerPhone = findFieldValue(fields, BROKER_PHONE_PATTERNS);
-  const brokerEmail = findFieldValue(fields, BROKER_EMAIL_PATTERNS);
-  const brokerAddress = findFieldValue(fields, BROKER_ADDRESS_PATTERNS);
+  const brokerAgency = findRawOrDeclarationValue(raw, fields, {
+    rawKey: "brokerAgency",
+    patterns: BROKER_NAME_PATTERNS
+  });
+  const brokerContact = findRawOrDeclarationValue(raw, fields, {
+    rawKey: "brokerContactName",
+    patterns: BROKER_CONTACT_PATTERNS
+  });
+  const brokerLicense = findRawOrDeclarationValue(raw, fields, {
+    rawKey: "brokerLicenseNumber",
+    patterns: BROKER_LICENSE_PATTERNS
+  });
+  const brokerPhone = findRawOrDeclarationValue(raw, fields, { patterns: BROKER_PHONE_PATTERNS });
+  const brokerEmail = findRawOrDeclarationValue(raw, fields, { patterns: BROKER_EMAIL_PATTERNS });
+  const brokerAddress = findRawOrDeclarationValue(raw, fields, { patterns: BROKER_ADDRESS_PATTERNS });
   if (brokerAgency) raw.brokerAgency = brokerAgency;
   if (brokerContact) raw.brokerContactName = brokerContact;
   if (brokerLicense) raw.brokerLicenseNumber = brokerLicense;
@@ -2011,25 +2121,171 @@ function synthesizeDeductibles(doc) {
     raw.deductibles = deductibles;
   }
 }
-var PREMIUM_PATTERNS = ["premium", "totalPremium", "annualPremium", "policyPremium", "basePremium"];
-var TOTAL_COST_PATTERNS = ["totalCost", "totalDue", "totalAmount", "totalPolicyPremium"];
+var PREMIUM_PATTERNS = [
+  "premium",
+  "premiumAmount",
+  "premium amount",
+  "totalPremium",
+  "total premium",
+  "totalPolicyPremium",
+  "total policy premium",
+  "annualPremium",
+  "annual premium",
+  "estimatedAnnualPremium",
+  "estimated annual premium",
+  "policyPremium",
+  "policy premium",
+  "basePremium",
+  "base premium",
+  "planCost",
+  "plan cost",
+  "policyCost",
+  "policy cost",
+  "premiumSubtotal",
+  "premium subtotal",
+  "subtotalPremium",
+  "subtotal premium",
+  "quotedPremium",
+  "quoted premium"
+];
+var TOTAL_COST_PATTERNS = [
+  "totalCost",
+  "total cost",
+  "total",
+  "totalDue",
+  "total due",
+  "amountPaid",
+  "amount paid",
+  "totalPaid",
+  "total paid",
+  "totalPrice",
+  "total price",
+  "totalTripCost",
+  "total trip cost",
+  "amountCharged",
+  "amount charged",
+  "amountDue",
+  "amount due",
+  "totalAmountDue",
+  "total amount due",
+  "totalAmount",
+  "total amount",
+  "grandTotal",
+  "grand total",
+  "totalPayable",
+  "total payable",
+  "totalCharges",
+  "total charges",
+  "totalPolicyCost",
+  "total policy cost"
+];
+var PREMIUM_RAW_KEYS = [
+  "premium",
+  "premiumAmount",
+  "premium_amount",
+  "totalPremium",
+  "totalPolicyPremium",
+  "annualPremium",
+  "estimatedAnnualPremium",
+  "policyPremium",
+  "basePremium",
+  "planCost",
+  "policyCost",
+  "premiumSubtotal",
+  "subtotalPremium",
+  "quotedPremium"
+];
+var TOTAL_COST_RAW_KEYS = [
+  "totalCost",
+  "total_cost",
+  "total",
+  "totalDue",
+  "amountPaid",
+  "amount_paid",
+  "totalPaid",
+  "total_paid",
+  "totalPrice",
+  "totalTripCost",
+  "amountCharged",
+  "amountDue",
+  "totalAmountDue",
+  "totalAmount",
+  "grandTotal",
+  "totalPayable",
+  "totalCharges",
+  "totalPolicyCost"
+];
+function isTaxOrFeeField(fieldName) {
+  const normalized = normalizeFieldName(fieldName);
+  return /tax|gst|hst|pst|qst|fee|surcharge|assessment|stamp|filing|inspection/.test(normalized);
+}
+function isTotalCostField(fieldName) {
+  return fieldMatches(fieldName, TOTAL_COST_PATTERNS);
+}
+function taxFeeType(fieldName) {
+  const normalized = normalizeFieldName(fieldName);
+  if (normalized.includes("tax") || ["gst", "hst", "pst", "qst"].some((token) => normalized.includes(token))) return "tax";
+  if (normalized.includes("surcharge")) return "surcharge";
+  if (normalized.includes("assessment")) return "assessment";
+  if (normalized.includes("fee") || normalized.includes("stamp") || normalized.includes("filing")) return "fee";
+  return void 0;
+}
+function titleizeFieldName(fieldName) {
+  const spaced = fieldName.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();
+  return spaced.replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function taxFeeKey(item) {
+  return [
+    normalizeFieldName(item.name),
+    normalizeFieldName(item.amount),
+    item.type ?? ""
+  ].join("|");
+}
+function taxFeeItemFromField(field) {
+  const type = taxFeeType(field.field);
+  return {
+    name: titleizeFieldName(field.field),
+    amount: absorbNegative(field.value),
+    ...type ? { type } : {}
+  };
+}
 function absorbNegative(value) {
   return value.replace(/^-\s*/, "").replace(/^\(\s*(.*?)\s*\)$/, "$1");
 }
 function promotePremium(doc) {
   const raw = doc;
   const fields = getDeclarationFields(doc);
-  if (!raw.premium) {
-    const premium = findFieldValue(fields, PREMIUM_PATTERNS);
-    if (premium) raw.premium = premium;
-  }
-  if (!raw.totalCost) {
-    const totalCost = findFieldValue(fields, TOTAL_COST_PATTERNS);
-    if (totalCost) raw.totalCost = totalCost;
-  }
+  promoteRawOrDeclarationString(raw, fields, "premium", PREMIUM_RAW_KEYS, {
+    patterns: PREMIUM_PATTERNS,
+    reject: (field) => isTaxOrFeeField(field.field)
+  });
+  promoteRawOrDeclarationString(raw, fields, "totalCost", TOTAL_COST_RAW_KEYS, {
+    patterns: TOTAL_COST_PATTERNS
+  });
   if (typeof raw.premium === "string") raw.premium = absorbNegative(raw.premium);
   if (typeof raw.totalCost === "string") raw.totalCost = absorbNegative(raw.totalCost);
 }
+function synthesizeTaxesAndFees(doc) {
+  const raw = doc;
+  const fields = getDeclarationFields(doc);
+  if (fields.length === 0) return;
+  const existing = Array.isArray(raw.taxesAndFees) ? raw.taxesAndFees : [];
+  const byKey = /* @__PURE__ */ new Map();
+  for (const item of existing) {
+    if (!item?.name || !item?.amount) continue;
+    byKey.set(taxFeeKey(item), item);
+  }
+  for (const field of fields) {
+    if (!field.value?.trim()) continue;
+    if (!isTaxOrFeeField(field.field)) continue;
+    if (isTotalCostField(field.field)) continue;
+    const item = taxFeeItemFromField(field);
+    byKey.set(taxFeeKey(item), item);
+  }
+  if (byKey.size > 0) {
+    raw.taxesAndFees = [...byKey.values()];
+  }
+}
 function promoteExtractedFields(doc) {
   promoteCarrierFields(doc);
   promoteBroker(doc);
@@ -2037,44 +2293,53 @@ function promoteExtractedFields(doc) {
   promoteLocations(doc);
   synthesizeLimits(doc);
   synthesizeDeductibles(doc);
+  synthesizeTaxesAndFees(doc);
   promotePremium(doc);
 }
 
 // src/extraction/assembler.ts
 function assembleDocument(documentId, documentType, memory) {
-  const carrier = memory.get("carrier_info");
-  const insured = memory.get("named_insured");
-  const coverages = memory.get("coverage_limits");
-  const endorsements = memory.get("endorsements");
-  const exclusions = memory.get("exclusions");
-  const conditions = memory.get("conditions");
-  const premium = memory.get("premium_breakdown");
-  const declarations = memory.get("declarations");
-  const lossHistory = memory.get("loss_history");
-  const sections = memory.get("sections");
-  const supplementary = memory.get("supplementary");
-  const formInventory = memory.get("form_inventory");
-  const classify = memory.get("classify");
+  const carrier = getCarrierInfo(memory);
+  const insured = getNamedInsured(memory);
+  const coverages = getCoverageLimits(memory);
+  const endorsements = readMemoryRecord(memory, "endorsements");
+  const exclusions = readMemoryRecord(memory, "exclusions");
+  const conditions = readMemoryRecord(memory, "conditions");
+  const premium = readMemoryRecord(memory, "premium_breakdown");
+  const declarations = readMemoryRecord(memory, "declarations");
+  const lossHistory = readMemoryRecord(memory, "loss_history");
+  const supplementary = readMemoryRecord(memory, "supplementary");
+  const formInventory = readMemoryRecord(memory, "form_inventory");
+  const classify = readMemoryRecord(memory, "classify");
+  const lossPayees = readRecordArray(insured, "lossPayees");
+  const mortgageHolders = readRecordArray(insured, "mortgageHolders");
   const base = {
     id: documentId,
-    carrier: carrier?.carrierName ?? "Unknown",
-    insuredName: insured?.insuredName ?? "Unknown",
-    coverages: coverages?.coverages ?? [],
-    policyTypes: classify?.policyTypes,
+    carrier: readRecordValue(carrier, "carrierName") ?? "Unknown",
+    insuredName: readRecordValue(insured, "insuredName") ?? "Unknown",
+    coverages: getCoverageLimitCoverages(memory),
+    policyTypes: readRecordValue(classify, "policyTypes"),
     ...sanitizeNulls(carrier ?? {}),
     ...sanitizeNulls(insured ?? {}),
     // Map named_insured extractor's loss payees/mortgage holders to EndorsementParty shape
-    ...Array.isArray(insured?.lossPayees) && insured.lossPayees.length > 0 ? { lossPayees: insured.lossPayees.map((lp) => ({ ...lp, role: "loss_payee" })) } : {},
-    ...Array.isArray(insured?.mortgageHolders) && insured.mortgageHolders.length > 0 ? { mortgageHolders: insured.mortgageHolders.map((mh) => ({ ...mh, role: "mortgage_holder" })) } : {},
+    ...lossPayees && lossPayees.length > 0 ? { lossPayees: lossPayees.map((lp) => ({ ...lp, role: "loss_payee" })) } : {},
+    ...mortgageHolders && mortgageHolders.length > 0 ? {
+      mortgageHolders: mortgageHolders.map((mh) => ({
+        ...mh,
+        role: "mortgage_holder"
+      }))
+    } : {},
     ...sanitizeNulls(coverages ?? {}),
     ...sanitizeNulls(premium ?? {}),
     ...sanitizeNulls(supplementary ?? {}),
-    supplementaryFacts: supplementary?.auxiliaryFacts,
-    endorsements: endorsements?.endorsements,
-    exclusions: exclusions?.exclusions,
-    conditions: conditions?.conditions,
-    sections: sections?.sections,
-    formInventory: formInventory?.forms,
+    supplementaryFacts: readRecordValue(supplementary, "auxiliaryFacts"),
+    endorsements: readRecordValue(endorsements, "endorsements"),
+    exclusions: readRecordValue(exclusions, "exclusions"),
+    conditions: readRecordValue(conditions, "conditions"),
+    sections: getSections(memory),
+    formInventory: readRecordValue(formInventory, "forms"),
+    definitions: getDefinitions(memory),
+    coveredReasons: getCoveredReasons(memory),
     declarations: declarations ? sanitizeNulls(declarations) : void 0,
     ...sanitizeNulls(lossHistory ?? {})
   };
@@ -2083,21 +2348,21 @@ function assembleDocument(documentId, documentType, memory) {
     doc = {
       ...base,
       type: "policy",
-      policyNumber: carrier?.policyNumber ?? insured?.policyNumber ?? "Unknown",
-      effectiveDate: carrier?.effectiveDate ?? insured?.effectiveDate ?? "Unknown",
-      expirationDate: carrier?.expirationDate,
-      policyTermType: carrier?.policyTermType
+      policyNumber: readRecordValue(carrier, "policyNumber") ?? readRecordValue(insured, "policyNumber") ?? "Unknown",
+      effectiveDate: readRecordValue(carrier, "effectiveDate") ?? readRecordValue(insured, "effectiveDate") ?? "Unknown",
+      expirationDate: readRecordValue(carrier, "expirationDate"),
+      policyTermType: readRecordValue(carrier, "policyTermType")
     };
   } else {
     doc = {
       ...base,
       type: "quote",
-      quoteNumber: carrier?.quoteNumber ?? "Unknown",
-      proposedEffectiveDate: carrier?.proposedEffectiveDate,
-      proposedExpirationDate: carrier?.proposedExpirationDate,
-      subjectivities: coverages?.subjectivities,
-      underwritingConditions: coverages?.underwritingConditions,
-      premiumBreakdown: premium?.premiumBreakdown
+      quoteNumber: readRecordValue(carrier, "quoteNumber") ?? "Unknown",
+      proposedEffectiveDate: readRecordValue(carrier, "proposedEffectiveDate"),
+      proposedExpirationDate: readRecordValue(carrier, "proposedExpirationDate"),
+      subjectivities: readRecordValue(coverages, "subjectivities"),
+      underwritingConditions: readRecordValue(coverages, "underwritingConditions"),
+      premiumBreakdown: readRecordValue(premium, "premiumBreakdown")
     };
   }
   promoteExtractedFields(doc);
@@ -2199,6 +2464,23 @@ ${block}`;
 }
 
 // src/extraction/formatter.ts
+var LONG_CONTENT_THRESHOLD = 1200;
+function shouldFormatContent(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return false;
+  if (trimmed.length >= LONG_CONTENT_THRESHOLD) return true;
+  if (/```|~~~|<br\s*\/?>/i.test(trimmed)) return true;
+  if (/(^|\s)(\*\*|__|`)/.test(trimmed)) return true;
+  if (/!?\[[^\]]+\]\([^)]+\)/.test(trimmed)) return true;
+  if (/^\s{0,3}#{1,6}\s*\S/m.test(trimmed)) return true;
+  if (/^\s{0,6}(?:[-*+]|\d+[.)])\s+\S/m.test(trimmed)) return true;
+  if (/\t|[^\S\r\n]{3,}|\n{3,}|[ \t]+$/m.test(text)) return true;
+  const lines = trimmed.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.some((line) => (line.match(/\|/g)?.length ?? 0) >= 2)) return true;
+  const spaceAlignedRows = lines.filter((line) => /\S\s{2,}\S\s{2,}\S/.test(line));
+  if (spaceAlignedRows.length >= 2) return true;
+  return false;
+}
 function collectContentFields(doc) {
   const entries = [];
   let id = 0;
@@ -2234,6 +2516,21 @@ function collectContentFields(doc) {
       add(`conditions[${i}].content`, doc.conditions[i].content);
     }
   }
+  const extendedDoc = doc;
+  if (extendedDoc.definitions) {
+    for (let i = 0; i < extendedDoc.definitions.length; i++) {
+      add(`definitions[${i}].definition`, extendedDoc.definitions[i].definition);
+    }
+  }
+  const coveredReasons = extendedDoc.coveredReasons ?? extendedDoc.covered_reasons;
+  if (coveredReasons) {
+    for (let i = 0; i < coveredReasons.length; i++) {
+      add(`coveredReasons[${i}].content`, coveredReasons[i].content);
+      coveredReasons[i].conditions?.forEach((condition, j) => {
+        add(`coveredReasons[${i}].conditions[${j}]`, condition);
+      });
+    }
+  }
   return entries;
 }
 function parseFormatResponse(response) {
@@ -2249,6 +2546,10 @@ function parseFormatResponse(response) {
   return results;
 }
 function applyFormattedContent(doc, entries, formatted) {
+  const docRecord = doc;
+  if (!docRecord.coveredReasons && docRecord.covered_reasons) {
+    docRecord.coveredReasons = docRecord.covered_reasons;
+  }
   for (const entry of entries) {
     const cleaned = formatted.get(entry.id);
     if (!cleaned) continue;
@@ -2257,6 +2558,14 @@ function applyFormattedContent(doc, entries, formatted) {
     const [, field, idx1, sub1, idx2, sub2] = segments;
     if (!sub1) {
       doc[field] = cleaned;
+    } else if (idx2 && !sub2) {
+      const arr = doc[field];
+      if (arr && arr[Number(idx1)]) {
+        const nested = arr[Number(idx1)][sub1];
+        if (Array.isArray(nested)) {
+          nested[Number(idx2)] = cleaned;
+        }
+      }
     } else if (!sub2) {
       const arr = doc[field];
       if (arr && arr[Number(idx1)]) {
@@ -2275,7 +2584,7 @@ function applyFormattedContent(doc, entries, formatted) {
 }
 var MAX_ENTRIES_PER_BATCH = 20;
 async function formatDocumentContent(doc, generateText, options) {
-  const entries = collectContentFields(doc);
+  const entries = collectContentFields(doc).filter((entry) => shouldFormatContent(entry.text));
   const totalUsage = { inputTokens: 0, outputTokens: 0 };
   if (entries.length === 0) {
     return { document: doc, usage: totalUsage };
@@ -2321,6 +2630,16 @@ function formatAddress(addr) {
   const parts = [addr.street1, addr.street2, addr.city, addr.state, addr.zip, addr.country].filter(Boolean);
   return parts.join(", ");
 }
+function asRecordArray(value) {
+  return Array.isArray(value) ? value.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item)) : [];
+}
+function firstString(item, keys) {
+  for (const key of keys) {
+    const value = item[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return void 0;
+}
 function chunkDocument(doc) {
   const ensureArray = (v) => Array.isArray(v) ? v : [];
   doc = {
@@ -2334,6 +2653,7 @@ function chunkDocument(doc) {
   const chunks = [];
   const docId = doc.id;
   const policyTypesStr = doc.policyTypes?.length ? doc.policyTypes.join(",") : void 0;
+  const extendedDoc = doc;
   function stringMetadata(entries) {
     const base = Object.fromEntries(
       Object.entries(entries).filter(([, value]) => value !== void 0 && value !== null && String(value).length > 0).map(([key, value]) => [key, String(value)])
@@ -2341,11 +2661,22 @@ function chunkDocument(doc) {
     if (policyTypesStr) base.policyTypes = policyTypesStr;
     return base;
   }
-  chunks.push({
-    id: `${docId}:carrier_info:0`,
-    documentId: docId,
-    type: "carrier_info",
-    text: [
+  function lines(values) {
+    return values.filter(Boolean).join("\n");
+  }
+  function pushChunk(idSuffix, type, text, metadata) {
+    chunks.push({
+      id: `${docId}:${idSuffix}`,
+      documentId: docId,
+      type,
+      text,
+      metadata: stringMetadata(metadata)
+    });
+  }
+  pushChunk(
+    "carrier_info:0",
+    "carrier_info",
+    lines([
       `Carrier: ${doc.carrier}`,
       doc.carrierLegalName ? `Legal Name: ${doc.carrierLegalName}` : null,
       doc.carrierNaicNumber ? `NAIC: ${doc.carrierNaicNumber}` : null,
@@ -2362,94 +2693,83 @@ function chunkDocument(doc) {
       doc.isPackage != null ? `Package: ${doc.isPackage ? "Yes" : "No"}` : null,
       doc.security ? `Security: ${doc.security}` : null,
       doc.policyTypes?.length ? `Policy Types: ${doc.policyTypes.join(", ")}` : null
-    ].filter(Boolean).join("\n"),
-    metadata: stringMetadata({ carrier: doc.carrier, documentType: doc.type })
-  });
+    ]),
+    { carrier: doc.carrier, documentType: doc.type }
+  );
   if (doc.summary) {
-    chunks.push({
-      id: `${docId}:declaration:summary`,
-      documentId: docId,
-      type: "declaration",
-      text: `Policy Summary: ${doc.summary}`,
-      metadata: stringMetadata({ documentType: doc.type })
-    });
+    pushChunk("declaration:summary", "declaration", `Policy Summary: ${doc.summary}`, { documentType: doc.type });
   }
   if (doc.type === "policy") {
     const pol = doc;
-    chunks.push({
-      id: `${docId}:declaration:policy_details`,
-      documentId: docId,
-      type: "declaration",
-      text: [
+    pushChunk(
+      "declaration:policy_details",
+      "declaration",
+      lines([
         `Policy Number: ${pol.policyNumber}`,
         `Effective Date: ${pol.effectiveDate}`,
         pol.expirationDate ? `Expiration Date: ${pol.expirationDate}` : null,
         pol.policyTermType ? `Term Type: ${pol.policyTermType}` : null,
         pol.effectiveTime ? `Effective Time: ${pol.effectiveTime}` : null,
         pol.nextReviewDate ? `Next Review Date: ${pol.nextReviewDate}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         policyNumber: pol.policyNumber,
         effectiveDate: pol.effectiveDate,
         expirationDate: pol.expirationDate,
         documentType: doc.type
-      })
-    });
+      }
+    );
   } else {
     const quote = doc;
-    chunks.push({
-      id: `${docId}:declaration:quote_details`,
-      documentId: docId,
-      type: "declaration",
-      text: [
+    pushChunk(
+      "declaration:quote_details",
+      "declaration",
+      lines([
         `Quote Number: ${quote.quoteNumber}`,
         quote.proposedEffectiveDate ? `Proposed Effective Date: ${quote.proposedEffectiveDate}` : null,
         quote.proposedExpirationDate ? `Proposed Expiration Date: ${quote.proposedExpirationDate}` : null,
         quote.quoteExpirationDate ? `Quote Expiration Date: ${quote.quoteExpirationDate}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         quoteNumber: quote.quoteNumber,
         documentType: doc.type
-      })
-    });
+      }
+    );
   }
   if (doc.insurer) {
-    chunks.push({
-      id: `${docId}:party:insurer`,
-      documentId: docId,
-      type: "party",
-      text: [
+    pushChunk(
+      "party:insurer",
+      "party",
+      lines([
         `Insurer: ${doc.insurer.legalName}`,
         doc.insurer.naicNumber ? `NAIC: ${doc.insurer.naicNumber}` : null,
         doc.insurer.amBestRating ? `AM Best Rating: ${doc.insurer.amBestRating}` : null,
         doc.insurer.amBestNumber ? `AM Best Number: ${doc.insurer.amBestNumber}` : null,
         doc.insurer.admittedStatus ? `Admitted Status: ${doc.insurer.admittedStatus}` : null,
         doc.insurer.stateOfDomicile ? `State of Domicile: ${doc.insurer.stateOfDomicile}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({ partyRole: "insurer", partyName: doc.insurer.legalName, documentType: doc.type })
-    });
+      ]),
+      { partyRole: "insurer", partyName: doc.insurer.legalName, documentType: doc.type }
+    );
   }
   if (doc.producer) {
-    chunks.push({
-      id: `${docId}:party:producer`,
-      documentId: docId,
-      type: "party",
-      text: [
+    pushChunk(
+      "party:producer",
+      "party",
+      lines([
         `Producer/Broker: ${doc.producer.agencyName}`,
         doc.producer.contactName ? `Contact: ${doc.producer.contactName}` : null,
         doc.producer.licenseNumber ? `License: ${doc.producer.licenseNumber}` : null,
         doc.producer.phone ? `Phone: ${doc.producer.phone}` : null,
         doc.producer.email ? `Email: ${doc.producer.email}` : null,
         doc.producer.address ? `Address: ${formatAddress(doc.producer.address)}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({ partyRole: "producer", partyName: doc.producer.agencyName, documentType: doc.type })
-    });
+      ]),
+      { partyRole: "producer", partyName: doc.producer.agencyName, documentType: doc.type }
+    );
   }
-  chunks.push({
-    id: `${docId}:named_insured:0`,
-    documentId: docId,
-    type: "named_insured",
-    text: [
+  pushChunk(
+    "named_insured:0",
+    "named_insured",
+    lines([
       `Insured: ${doc.insuredName}`,
       doc.insuredDba ? `DBA: ${doc.insuredDba}` : null,
       doc.insuredEntityType ? `Entity Type: ${doc.insuredEntityType}` : null,
@@ -2457,36 +2777,34 @@ function chunkDocument(doc) {
       doc.insuredSicCode ? `SIC: ${doc.insuredSicCode}` : null,
       doc.insuredNaicsCode ? `NAICS: ${doc.insuredNaicsCode}` : null,
       doc.insuredAddress ? `Address: ${formatAddress(doc.insuredAddress)}` : null
-    ].filter(Boolean).join("\n"),
-    metadata: stringMetadata({ insuredName: doc.insuredName, documentType: doc.type })
-  });
+    ]),
+    { insuredName: doc.insuredName, documentType: doc.type }
+  );
   doc.additionalNamedInsureds?.forEach((insured, i) => {
-    chunks.push({
-      id: `${docId}:named_insured:${i + 1}`,
-      documentId: docId,
-      type: "named_insured",
-      text: [
+    pushChunk(
+      `named_insured:${i + 1}`,
+      "named_insured",
+      lines([
         `Additional Named Insured: ${insured.name}`,
         insured.address ? `Address: ${formatAddress(insured.address)}` : null,
         insured.relationship ? `Relationship: ${insured.relationship}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({ insuredName: insured.name, role: "additional_named_insured", documentType: doc.type })
-    });
+      ]),
+      { insuredName: insured.name, role: "additional_named_insured", documentType: doc.type }
+    );
   });
   doc.coverages.forEach((cov, i) => {
-    chunks.push({
-      id: `${docId}:coverage:${i}`,
-      documentId: docId,
-      type: "coverage",
-      text: [
+    pushChunk(
+      `coverage:${i}`,
+      "coverage",
+      lines([
         `Coverage: ${cov.name}`,
         `Limit: ${cov.limit}`,
         cov.limitValueType ? `Limit Type: ${cov.limitValueType}` : null,
         cov.deductible ? `Deductible: ${cov.deductible}` : null,
         cov.deductibleValueType ? `Deductible Type: ${cov.deductibleValueType}` : null,
         cov.originalContent ? `Source: ${cov.originalContent}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         coverageName: cov.name,
         limit: cov.limit,
         limitValueType: cov.limitValueType,
@@ -2496,15 +2814,14 @@ function chunkDocument(doc) {
         pageNumber: cov.pageNumber,
         sectionRef: cov.sectionRef,
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   doc.enrichedCoverages?.forEach((cov, i) => {
-    chunks.push({
-      id: `${docId}:coverage:enriched:${i}`,
-      documentId: docId,
-      type: "coverage",
-      text: [
+    pushChunk(
+      `coverage:enriched:${i}`,
+      "coverage",
+      lines([
         `Coverage: ${cov.name}`,
         cov.coverageCode ? `Code: ${cov.coverageCode}` : null,
         `Limit: ${cov.limit}`,
@@ -2521,8 +2838,8 @@ function chunkDocument(doc) {
         `Included: ${cov.included ? "Yes" : "No"}`,
         cov.premium ? `Premium: ${cov.premium}` : null,
         cov.originalContent ? `Source: ${cov.originalContent}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         coverageName: cov.name,
         coverageCode: cov.coverageCode,
         limit: cov.limit,
@@ -2531,8 +2848,8 @@ function chunkDocument(doc) {
         pageNumber: cov.pageNumber,
         included: cov.included,
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   if (doc.limits) {
     const limitLines = ["Limit Schedule"];
@@ -2556,39 +2873,31 @@ function chunkDocument(doc) {
       limitLines.push(`Employers Liability \u2014 Each Accident: ${lim.employersLiability.eachAccident}, Disease Policy Limit: ${lim.employersLiability.diseasePolicyLimit}, Disease Each Employee: ${lim.employersLiability.diseaseEachEmployee}`);
     }
     if (lim.defenseCostTreatment) limitLines.push(`Defense Cost Treatment: ${lim.defenseCostTreatment}`);
-    chunks.push({
-      id: `${docId}:coverage:limit_schedule`,
-      documentId: docId,
-      type: "coverage",
-      text: limitLines.join("\n"),
-      metadata: stringMetadata({ coverageName: "limit_schedule", documentType: doc.type })
-    });
+    pushChunk("coverage:limit_schedule", "coverage", limitLines.join("\n"), { coverageName: "limit_schedule", documentType: doc.type });
     lim.sublimits?.forEach((sub, i) => {
-      chunks.push({
-        id: `${docId}:coverage:sublimit:${i}`,
-        documentId: docId,
-        type: "coverage",
-        text: [
+      pushChunk(
+        `coverage:sublimit:${i}`,
+        "coverage",
+        lines([
           `Sublimit: ${sub.name}`,
           `Limit: ${sub.limit}`,
           sub.appliesTo ? `Applies To: ${sub.appliesTo}` : null,
           sub.deductible ? `Deductible: ${sub.deductible}` : null
-        ].filter(Boolean).join("\n"),
-        metadata: stringMetadata({ coverageName: sub.name, limit: sub.limit, documentType: doc.type })
-      });
+        ]),
+        { coverageName: sub.name, limit: sub.limit, documentType: doc.type }
+      );
     });
     lim.sharedLimits?.forEach((sl, i) => {
-      chunks.push({
-        id: `${docId}:coverage:shared_limit:${i}`,
-        documentId: docId,
-        type: "coverage",
-        text: [
+      pushChunk(
+        `coverage:shared_limit:${i}`,
+        "coverage",
+        [
           `Shared Limit: ${sl.description}`,
           `Limit: ${sl.limit}`,
           `Coverage Parts: ${sl.coverageParts.join(", ")}`
         ].join("\n"),
-        metadata: stringMetadata({ coverageName: sl.description, limit: sl.limit, documentType: doc.type })
-      });
+        { coverageName: sl.description, limit: sl.limit, documentType: doc.type }
+      );
     });
   }
   if (doc.deductibles) {
@@ -2602,12 +2911,9 @@ function chunkDocument(doc) {
     if (ded.waitingPeriod) dedLines.push(`Waiting Period: ${ded.waitingPeriod}`);
     if (ded.appliesTo) dedLines.push(`Applies To: ${ded.appliesTo}`);
     if (dedLines.length > 1) {
-      chunks.push({
-        id: `${docId}:coverage:deductible_schedule`,
-        documentId: docId,
-        type: "coverage",
-        text: dedLines.join("\n"),
-        metadata: stringMetadata({ coverageName: "deductible_schedule", documentType: doc.type })
+      pushChunk("coverage:deductible_schedule", "coverage", dedLines.join("\n"), {
+        coverageName: "deductible_schedule",
+        documentType: doc.type
       });
     }
   }
@@ -2619,76 +2925,141 @@ function chunkDocument(doc) {
     doc.extendedReportingPeriod?.supplementalPremium ? `Extended Reporting Period Premium: ${doc.extendedReportingPeriod.supplementalPremium}` : null
   ].filter(Boolean);
   if (claimsMadeLines.length > 0) {
-    chunks.push({
-      id: `${docId}:coverage:claims_made_details`,
-      documentId: docId,
-      type: "coverage",
-      text: claimsMadeLines.join("\n"),
-      metadata: stringMetadata({ coverageName: "claims_made_details", documentType: doc.type })
+    pushChunk("coverage:claims_made_details", "coverage", claimsMadeLines.join("\n"), {
+      coverageName: "claims_made_details",
+      documentType: doc.type
     });
   }
   doc.formInventory?.forEach((form, i) => {
-    chunks.push({
-      id: `${docId}:declaration:form:${i}`,
-      documentId: docId,
-      type: "declaration",
-      text: [
+    pushChunk(
+      `declaration:form:${i}`,
+      "declaration",
+      lines([
         `Form: ${form.formNumber}`,
         form.title ? `Title: ${form.title}` : null,
         `Type: ${form.formType}`,
         form.editionDate ? `Edition: ${form.editionDate}` : null,
         form.pageStart ? `Pages: ${form.pageStart}${form.pageEnd ? `-${form.pageEnd}` : ""}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         formNumber: form.formNumber,
         formType: form.formType,
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   doc.endorsements?.forEach((end, i) => {
-    chunks.push({
-      id: `${docId}:endorsement:${i}`,
-      documentId: docId,
-      type: "endorsement",
-      text: `Endorsement: ${end.title}
+    pushChunk(
+      `endorsement:${i}`,
+      "endorsement",
+      `Endorsement: ${end.title}
 ${end.content}`.trim(),
-      metadata: stringMetadata({
+      {
         endorsementType: end.endorsementType,
         formNumber: end.formNumber,
         pageStart: end.pageStart,
         pageEnd: end.pageEnd,
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   doc.exclusions?.forEach((exc, i) => {
-    chunks.push({
-      id: `${docId}:exclusion:${i}`,
-      documentId: docId,
-      type: "exclusion",
-      text: `Exclusion: ${exc.name}
-${exc.content}`.trim(),
-      metadata: stringMetadata({ formNumber: exc.formNumber, pageNumber: exc.pageNumber, documentType: doc.type })
+    pushChunk(`exclusion:${i}`, "exclusion", `Exclusion: ${exc.name}
+${exc.content}`.trim(), {
+      formNumber: exc.formNumber,
+      pageNumber: exc.pageNumber,
+      documentType: doc.type
     });
   });
   doc.conditions?.forEach((cond, i) => {
-    chunks.push({
-      id: `${docId}:condition:${i}`,
-      documentId: docId,
-      type: "condition",
-      text: [
+    pushChunk(
+      `condition:${i}`,
+      "condition",
+      [
         `Condition: ${cond.name}`,
         `Type: ${cond.conditionType}`,
         cond.content,
         ...cond.keyValues?.map((kv) => `${kv.key}: ${kv.value}`) ?? []
       ].join("\n"),
-      metadata: stringMetadata({
+      {
         conditionName: cond.name,
         conditionType: cond.conditionType,
         pageNumber: cond.pageNumber,
         documentType: doc.type
-      })
+      }
+    );
+  });
+  asRecordArray(extendedDoc.definitions).forEach((definition, i) => {
+    const term = firstString(definition, ["term", "name", "title"]) ?? `Definition ${i + 1}`;
+    const body = firstString(definition, ["definition", "content", "text", "meaning"]);
+    pushChunk(
+      `definition:${i}`,
+      "definition",
+      lines([
+        `Definition: ${term}`,
+        body,
+        firstString(definition, ["originalContent", "source"]) ? `Source: ${firstString(definition, ["originalContent", "source"])}` : null
+      ]),
+      {
+        term,
+        formNumber: firstString(definition, ["formNumber"]),
+        formTitle: firstString(definition, ["formTitle"]),
+        pageNumber: typeof definition.pageNumber === "number" ? definition.pageNumber : void 0,
+        sectionRef: firstString(definition, ["sectionRef", "sectionTitle"]),
+        documentType: doc.type
+      }
+    );
+  });
+  const coveredReasons = asRecordArray(extendedDoc.coveredReasons ?? extendedDoc.covered_reasons);
+  coveredReasons.forEach((coveredReason, i) => {
+    const title = firstString(coveredReason, ["title", "name", "reason", "peril", "cause"]) ?? `Covered Reason ${i + 1}`;
+    const coverageName = firstString(coveredReason, ["coverageName", "coverage", "coveragePart"]);
+    const reasonNumber = firstString(coveredReason, ["reasonNumber", "number"]);
+    const body = firstString(coveredReason, ["content", "description", "text", "coverageGrant"]);
+    pushChunk(
+      `covered_reason:${i}`,
+      "covered_reason",
+      lines([
+        coverageName ? `Coverage: ${coverageName}` : null,
+        reasonNumber ? `Reason Number: ${reasonNumber}` : null,
+        `Covered Reason: ${title}`,
+        body,
+        firstString(coveredReason, ["originalContent", "source"]) ? `Source: ${firstString(coveredReason, ["originalContent", "source"])}` : null
+      ]),
+      {
+        coverageName,
+        reasonNumber,
+        title,
+        formNumber: firstString(coveredReason, ["formNumber"]),
+        formTitle: firstString(coveredReason, ["formTitle"]),
+        pageNumber: typeof coveredReason.pageNumber === "number" ? coveredReason.pageNumber : void 0,
+        sectionRef: firstString(coveredReason, ["sectionRef", "sectionTitle"]),
+        documentType: doc.type
+      }
+    );
+    const conditions = Array.isArray(coveredReason.conditions) ? coveredReason.conditions.filter((condition) => typeof condition === "string" && condition.trim().length > 0) : [];
+    conditions.forEach((condition, conditionIndex) => {
+      pushChunk(
+        `covered_reason:${i}:condition:${conditionIndex}`,
+        "covered_reason",
+        lines([
+          coverageName ? `Coverage: ${coverageName}` : null,
+          reasonNumber ? `Reason Number: ${reasonNumber}` : null,
+          `Covered Reason Condition: ${title}`,
+          condition
+        ]),
+        {
+          coverageName,
+          reasonNumber,
+          title,
+          conditionIndex,
+          formNumber: firstString(coveredReason, ["formNumber"]),
+          formTitle: firstString(coveredReason, ["formTitle"]),
+          pageNumber: typeof coveredReason.pageNumber === "number" ? coveredReason.pageNumber : void 0,
+          sectionRef: firstString(coveredReason, ["sectionRef", "sectionTitle"]),
+          documentType: doc.type
+        }
+      );
     });
   });
   if (doc.declarations) {
@@ -2703,50 +3074,42 @@ ${exc.content}`.trim(),
       const declMeta = { documentType: doc.type };
       if (typeof decl.formType === "string") declMeta.formType = decl.formType;
       if (typeof decl.line === "string") declMeta.declarationLine = decl.line;
-      chunks.push({
-        id: `${docId}:declaration:0`,
-        documentId: docId,
-        type: "declaration",
-        text: `Declarations
-${declLines.join("\n")}`,
-        metadata: stringMetadata(declMeta)
-      });
+      pushChunk("declaration:0", "declaration", `Declarations
+${declLines.join("\n")}`, declMeta);
     }
   }
   doc.sections?.forEach((sec, i) => {
     const hasSubsections = sec.subsections && sec.subsections.length > 0;
     const contentLength = sec.content.length;
     if (hasSubsections) {
-      chunks.push({
-        id: `${docId}:section:${i}`,
-        documentId: docId,
-        type: "section",
-        text: `Section: ${sec.title}
+      pushChunk(
+        `section:${i}`,
+        "section",
+        `Section: ${sec.title}
 ${sec.content}`,
-        metadata: stringMetadata({
+        {
           sectionType: sec.type,
           sectionNumber: sec.sectionNumber,
           pageStart: sec.pageStart,
           pageEnd: sec.pageEnd,
           documentType: doc.type,
           hasSubsections: "true"
-        })
-      });
+        }
+      );
       sec.subsections.forEach((sub, j) => {
-        chunks.push({
-          id: `${docId}:section:${i}:sub:${j}`,
-          documentId: docId,
-          type: "section",
-          text: `${sec.title} > ${sub.title}
+        pushChunk(
+          `section:${i}:sub:${j}`,
+          "section",
+          `${sec.title} > ${sub.title}
 ${sub.content}`,
-          metadata: stringMetadata({
+          {
             sectionType: sec.type,
             parentSection: sec.title,
             sectionNumber: sub.sectionNumber,
             pageNumber: sub.pageNumber,
             documentType: doc.type
-          })
-        });
+          }
+        );
       });
     } else if (contentLength > 2e3) {
       const paragraphs = sec.content.split(/\n\n+/);
@@ -2754,58 +3117,55 @@ ${sub.content}`,
       let chunkIndex = 0;
       for (const para of paragraphs) {
         if (currentChunk.length + para.length > 1e3 && currentChunk.length > 0) {
-          chunks.push({
-            id: `${docId}:section:${i}:part:${chunkIndex}`,
-            documentId: docId,
-            type: "section",
-            text: `Section: ${sec.title} (part ${chunkIndex + 1})
+          pushChunk(
+            `section:${i}:part:${chunkIndex}`,
+            "section",
+            `Section: ${sec.title} (part ${chunkIndex + 1})
 ${currentChunk.trim()}`,
-            metadata: stringMetadata({
+            {
               sectionType: sec.type,
               sectionNumber: sec.sectionNumber,
               pageStart: sec.pageStart,
               pageEnd: sec.pageEnd,
               documentType: doc.type,
               partIndex: chunkIndex
-            })
-          });
+            }
+          );
           currentChunk = "";
           chunkIndex++;
         }
         currentChunk += (currentChunk ? "\n\n" : "") + para;
       }
       if (currentChunk.trim()) {
-        chunks.push({
-          id: `${docId}:section:${i}:part:${chunkIndex}`,
-          documentId: docId,
-          type: "section",
-          text: `Section: ${sec.title} (part ${chunkIndex + 1})
+        pushChunk(
+          `section:${i}:part:${chunkIndex}`,
+          "section",
+          `Section: ${sec.title} (part ${chunkIndex + 1})
 ${currentChunk.trim()}`,
-          metadata: stringMetadata({
+          {
             sectionType: sec.type,
             sectionNumber: sec.sectionNumber,
             pageStart: sec.pageStart,
             pageEnd: sec.pageEnd,
             documentType: doc.type,
             partIndex: chunkIndex
-          })
-        });
+          }
+        );
       }
     } else {
-      chunks.push({
-        id: `${docId}:section:${i}`,
-        documentId: docId,
-        type: "section",
-        text: `Section: ${sec.title}
+      pushChunk(
+        `section:${i}`,
+        "section",
+        `Section: ${sec.title}
 ${sec.content}`,
-        metadata: stringMetadata({
+        {
           sectionType: sec.type,
           sectionNumber: sec.sectionNumber,
           pageStart: sec.pageStart,
           pageEnd: sec.pageEnd,
           documentType: doc.type
-        })
-      });
+        }
+      );
     }
   });
   doc.locations?.forEach((loc, i) => {
@@ -3236,6 +3596,13 @@ function dedupeByKey(items, keyFn) {
   }
   return merged;
 }
+function normalizeKeyPart(value) {
+  if (value === void 0 || value === null) return "";
+  return String(value).toLowerCase().replace(/&/g, "and").replace(/[^a-z0-9]+/g, "");
+}
+function keyFromParts(...parts) {
+  return parts.map(normalizeKeyPart).join("|");
+}
 function mergeUniqueObjects(existing, incoming, keyFn) {
   return dedupeByKey([...existing, ...incoming], keyFn);
 }
@@ -3264,13 +3631,13 @@ function mergeCoverageLimits(existing, incoming) {
   const merged = mergeShallowPreferPresent(existing, incoming);
   const existingCoverages = Array.isArray(existing.coverages) ? existing.coverages : [];
   const incomingCoverages = Array.isArray(incoming.coverages) ? incoming.coverages : [];
-  const coverageKey = (coverage) => [
-    String(coverage.name ?? "").toLowerCase(),
-    String(coverage.limitType ?? "").toLowerCase(),
-    String(coverage.limit ?? "").toLowerCase(),
-    String(coverage.deductible ?? "").toLowerCase(),
-    String(coverage.formNumber ?? "").toLowerCase()
-  ].join("|");
+  const coverageKey = (coverage) => keyFromParts(
+    coverage.name,
+    coverage.limitType,
+    coverage.limit,
+    coverage.deductible,
+    coverage.formNumber
+  );
   const byKey = /* @__PURE__ */ new Map();
   for (const coverage of [...existingCoverages, ...incomingCoverages]) {
     const key = coverageKey(coverage);
@@ -3284,11 +3651,11 @@ function mergeDeclarations(existing, incoming) {
   const merged = mergeShallowPreferPresent(existing, incoming);
   const existingFields = Array.isArray(existing.fields) ? existing.fields : [];
   const incomingFields = Array.isArray(incoming.fields) ? incoming.fields : [];
-  merged.fields = mergeUniqueObjects(existingFields, incomingFields, (field) => [
-    String(field.field ?? "").toLowerCase(),
-    String(field.value ?? "").toLowerCase(),
-    String(field.section ?? "").toLowerCase()
-  ].join("|"));
+  merged.fields = mergeUniqueObjects(existingFields, incomingFields, (field) => keyFromParts(
+    field.field,
+    field.value,
+    field.section
+  ));
   return merged;
 }
 function mergeArrayPayload(existing, incoming, arrayKey, keyFn) {
@@ -3298,30 +3665,53 @@ function mergeArrayPayload(existing, incoming, arrayKey, keyFn) {
   merged[arrayKey] = mergeUniqueObjects(existingItems, incomingItems, keyFn);
   return merged;
 }
+function readArray(record, ...keys) {
+  for (const key of keys) {
+    if (Array.isArray(record[key])) return record[key];
+  }
+  return [];
+}
+function mergeAliasedArrayPayload(existing, incoming, outputKey, inputKeys, keyFn) {
+  const merged = mergeShallowPreferPresent(existing, incoming);
+  const byKey = /* @__PURE__ */ new Map();
+  for (const item of [
+    ...readArray(existing, outputKey, ...inputKeys),
+    ...readArray(incoming, outputKey, ...inputKeys)
+  ]) {
+    const key = keyFn(item);
+    const current = byKey.get(key);
+    byKey.set(key, current ? mergeShallowPreferPresent(current, item) : item);
+  }
+  merged[outputKey] = [...byKey.values()];
+  for (const key of inputKeys) {
+    if (key !== outputKey) delete merged[key];
+  }
+  return merged;
+}
 function mergeSupplementary(existing, incoming) {
   const merged = mergeShallowPreferPresent(existing, incoming);
   const mergeContactArray = (arrayKey) => {
     const existingItems = Array.isArray(existing[arrayKey]) ? existing[arrayKey] : [];
     const incomingItems = Array.isArray(incoming[arrayKey]) ? incoming[arrayKey] : [];
-    merged[arrayKey] = mergeUniqueObjects(existingItems, incomingItems, (item) => [
-      String(item.name ?? "").toLowerCase(),
-      String(item.phone ?? "").toLowerCase(),
-      String(item.email ?? "").toLowerCase(),
-      String(item.address ?? "").toLowerCase(),
-      String(item.type ?? "").toLowerCase()
-    ].join("|"));
+    merged[arrayKey] = mergeUniqueObjects(existingItems, incomingItems, (item) => keyFromParts(
+      item.name,
+      item.phone,
+      item.email,
+      item.address,
+      item.type
+    ));
   };
   mergeContactArray("regulatoryContacts");
   mergeContactArray("claimsContacts");
   mergeContactArray("thirdPartyAdministrators");
   const existingFacts = Array.isArray(existing.auxiliaryFacts) ? existing.auxiliaryFacts : [];
   const incomingFacts = Array.isArray(incoming.auxiliaryFacts) ? incoming.auxiliaryFacts : [];
-  merged.auxiliaryFacts = mergeUniqueObjects(existingFacts, incomingFacts, (item) => [
-    String(item.key ?? "").toLowerCase(),
-    String(item.value ?? "").toLowerCase(),
-    String(item.subject ?? "").toLowerCase(),
-    String(item.context ?? "").toLowerCase()
-  ].join("|"));
+  merged.auxiliaryFacts = mergeUniqueObjects(existingFacts, incomingFacts, (item) => keyFromParts(
+    item.key,
+    item.value,
+    item.subject,
+    item.context
+  ));
   return merged;
 }
 function mergeExtractorResult(extractorName, existing, incoming) {
@@ -3342,31 +3732,43 @@ function mergeExtractorResult(extractorName, existing, incoming) {
       return mergeCoverageLimits(current, next);
     case "declarations":
       return mergeDeclarations(current, next);
+    case "definitions":
+      return mergeArrayPayload(current, next, "definitions", (item) => keyFromParts(
+        item.term ?? item.name ?? item.key,
+        item.pageNumber ?? item.pageStart
+      ));
+    case "covered_reasons":
+      return mergeAliasedArrayPayload(current, next, "coveredReasons", ["covered_reasons"], (item) => keyFromParts(
+        item.coverageName ?? item.coverage,
+        item.reasonNumber ?? item.number,
+        item.title ?? item.reason ?? item.name ?? item.cause,
+        item.pageNumber ?? item.pageStart
+      ));
     case "endorsements":
-      return mergeArrayPayload(current, next, "endorsements", (item) => [
-        String(item.formNumber ?? "").toLowerCase(),
-        String(item.title ?? "").toLowerCase(),
-        String(item.pageStart ?? "")
-      ].join("|"));
+      return mergeArrayPayload(current, next, "endorsements", (item) => keyFromParts(
+        item.formNumber,
+        item.title,
+        item.pageStart
+      ));
     case "exclusions":
-      return mergeArrayPayload(current, next, "exclusions", (item) => [
-        String(item.name ?? "").toLowerCase(),
-        String(item.formNumber ?? "").toLowerCase(),
-        String(item.pageNumber ?? "")
-      ].join("|"));
+      return mergeArrayPayload(current, next, "exclusions", (item) => keyFromParts(
+        item.name,
+        item.formNumber,
+        item.pageNumber
+      ));
     case "conditions":
-      return mergeArrayPayload(current, next, "conditions", (item) => [
-        String(item.name ?? "").toLowerCase(),
-        String(item.conditionType ?? "").toLowerCase(),
-        String(item.pageNumber ?? "")
-      ].join("|"));
+      return mergeArrayPayload(current, next, "conditions", (item) => keyFromParts(
+        item.name,
+        item.conditionType,
+        item.pageNumber
+      ));
     case "sections":
-      return mergeArrayPayload(current, next, "sections", (item) => [
-        String(item.title ?? "").toLowerCase(),
-        String(item.type ?? "").toLowerCase(),
-        String(item.pageStart ?? ""),
-        String(item.pageEnd ?? "")
-      ].join("|"));
+      return mergeArrayPayload(current, next, "sections", (item) => keyFromParts(
+        item.title,
+        item.type,
+        item.pageStart,
+        item.pageEnd
+      ));
     default:
       return mergeShallowPreferPresent(current, next);
   }
@@ -4225,6 +4627,8 @@ var PageExtractorSchema = z20.enum([
   "carrier_info",
   "named_insured",
   "coverage_limits",
+  "covered_reasons",
+  "definitions",
   "endorsements",
   "exclusions",
   "conditions",
@@ -4271,6 +4675,8 @@ Available extractors:
 - carrier_info
 - named_insured
 - coverage_limits
+- covered_reasons
+- definitions
 - endorsements
 - exclusions
 - conditions
@@ -4284,6 +4690,8 @@ Rules:
 - Identify the broad section or form context first, then assign focused extractors within that context.
 - Use specific extractors for declarations, schedules, endorsements, exclusions, conditions, premium pages, and loss runs.
 - Use "sections" for pages that contain substantive policy text or mixed content that should still be preserved as raw sections.
+- Use "definitions" for policy-form pages containing defined terms, definitions sections, or term meaning clauses.
+- Use "covered_reasons" for pages listing covered causes of loss, covered reasons, covered perils, named perils, covered events, or covered loss triggers.
 - Avoid assigning broad ranges mentally; decide page by page.
 - A page may map to multiple extractors if it legitimately contains multiple relevant sections.
 - Prefer declarations and schedules for numeric limits/deductibles over later generic form wording.
@@ -4291,6 +4699,7 @@ Rules:
 - Do NOT assign "coverage_limits" for generic policy-form or endorsement text that merely explains how limits, deductibles, waiting periods, or coinsurance work, or that says values are "shown in the declarations", "shown in the schedule", "as stated", or "if applicable".
 - Headings like "Limits of Insurance", "Deductible", "Coinsurance", "Loss Conditions", or "Definitions" inside a policy form usually indicate form language, not declarations or schedules.
 - Continuation pages near the end of a form should stay mapped to "sections" plus "conditions"/"exclusions" when applicable, even if they mention limits or deductibles.
+- Covered causes/reasons and definitions often span a whole form section; tag every substantive page in that section, not just the heading page.
 - When a form inventory entry identifies a page range as a specific form type (e.g., endorsement, coverage, application), use that classification to guide your extractor choice. Do not assign "coverage_limits" to pages the inventory identifies as endorsement or condition/exclusion forms unless the page contains actual schedule values.
 - Do not tag a page with "exclusions" or "conditions" if it only contains a table of contents, page-number reference, running header/footer, or a heading that points to another page without substantive wording.
 - If a page appears to be part of a larger exclusion, conditions, or endorsement section within the same form, keep the assignment consistent across nearby pages in that section rather than isolating a single page fragment.
@@ -4334,12 +4743,15 @@ var ReviewResultSchema = z21.object({
     description: z21.string()
   }))
 });
-function buildReviewPrompt(templateExpected, extractedKeys, extractionSummary, pageMapSummary) {
-  return `You are reviewing an extraction for completeness and quality. Compare what was expected vs what was found.
+function buildReviewPrompt(templateExpected, extractedKeys, extractionSummary, pageMapSummary, extractorCatalog) {
+  return `You are the extraction coordinator for an insurance-document agent system. Review the current extraction state, decide whether the result is complete enough, and choose any follow-up extractor tasks needed to improve it.
 
 EXPECTED FIELDS (from document type template):
 ${templateExpected.map((f) => `- ${f}`).join("\n")}
 
+AVAILABLE FOLLOW-UP EXTRACTORS:
+${extractorCatalog}
+
 FIELDS ALREADY EXTRACTED:
 ${extractedKeys.map((f) => `- ${f}`).join("\n")}
 
@@ -4353,15 +4765,21 @@ Determine:
 1. Is the extraction complete enough?
 2. What fields are missing?
 3. What quality issues are present?
-4. Should any additional extraction tasks be dispatched?
+4. Which follow-up extraction tasks, if any, should be dispatched?
 
 Mark the extraction as NOT complete if any of these are true:
 - required fields are missing
 - extracted values are generic placeholders like "shown in declarations", "per schedule", "if applicable", "as stated"
 - coverage limits or deductibles appear to come from generic form language instead of declaration/schedule-specific values
+- definitions pages were mapped but no definition records or definition-type sections were extracted
+- covered causes/reasons pages were mapped but no covered reason, covered peril, covered cause, or matching section records were extracted
 - page assignments suggest declaration, schedule, endorsement, exclusion, or condition pages were not actually extracted with the matching focused extractor
 - a focused extractor exists but returned too little substance for the relevant pages
 
+When reviewing CURRENT EXTRACTION SUMMARY, compare the page-map counts to extracted counts. If an assigned extractor produced no useful records, produce a quality issue and a narrow follow-up task over the mapped page range.
+
+Choose follow-up tasks from AVAILABLE FOLLOW-UP EXTRACTORS. You may dispatch any listed extractor when the page map, current extraction summary, or quality evidence shows that the focused extraction is missing, generic, referential, or too thin. Do not invent extractor names.
+
 Return JSON:
 {
   "complete": boolean,
@@ -4372,7 +4790,7 @@ Return JSON:
   ]
 }
 
-Use the page map to target follow-up extraction pages precisely. Prefer narrow, declaration/schedule-focused follow-up tasks over broad page ranges.
+Use the page map to target follow-up extraction pages precisely. Prefer narrow, declaration/schedule-focused follow-up tasks over broad page ranges. If no additional model work is likely to improve the extraction, return an empty additionalTasks array.
 
 Respond with JSON only.`;
 }
@@ -4907,6 +5325,7 @@ var SectionsSchema = z32.object({
         "policy_form",
         "endorsement",
         "application",
+        "covered_reason",
         "exclusion",
         "condition",
         "definition",
@@ -4930,6 +5349,7 @@ For each section, classify its type:
 - "policy_form" \u2014 named ISO or proprietary forms (e.g. CG 00 01, IL 00 17). All sections within a named form should be typed as "policy_form"
 - "endorsement" \u2014 standalone endorsements modifying the base policy
 - "application" \u2014 the insurance application or supplemental application
+- "covered_reason" \u2014 affirmative grants of coverage, covered causes of loss, covered perils, or named covered events
 - "insuring_agreement" \u2014 the insuring agreement clause (only if standalone, not inside a policy_form)
 - "exclusion", "condition", "definition" \u2014 for standalone sections only
 - "schedule" \u2014 coverage or rating schedules
@@ -5005,7 +5425,155 @@ For auxiliaryFacts:
 Return JSON only.`;
 }
 
+// src/prompts/extractors/definitions.ts
+import { z as z34 } from "zod";
+var DefinitionsSchema = z34.object({
+  definitions: z34.array(
+    z34.object({
+      term: z34.string().describe("Defined term exactly as shown in the document"),
+      definition: z34.string().describe("Full verbatim definition text, preserving original wording"),
+      pageNumber: z34.number().optional().describe("Original document page number"),
+      formNumber: z34.string().optional().describe("Form number where this definition appears"),
+      formTitle: z34.string().optional().describe("Form title where this definition appears"),
+      sectionRef: z34.string().optional().describe("Definition section heading or subsection reference"),
+      originalContent: z34.string().optional().describe("Short verbatim source snippet containing the term and definition")
+    })
+  ).describe("All substantive insurance definitions found in the document")
+});
+function buildDefinitionsPrompt() {
+  return `You are an expert insurance document analyst. Extract ALL substantive defined terms from this document. Preserve original wording verbatim.
+
+For EACH definition, extract:
+- term: defined term exactly as shown \u2014 REQUIRED
+- definition: full verbatim definition text including all included subparts \u2014 REQUIRED
+- pageNumber: original document page number where the definition appears
+- formNumber: form number where the definition appears, if shown
+- formTitle: form title where the definition appears, if shown
+- sectionRef: heading such as "Definitions", "Words and Phrases Defined", or coverage-specific definition section
+- originalContent: short verbatim source snippet containing the term and definition
+
+Focus on:
+- Terms in sections titled Definitions, Words and Phrases Defined, Glossary, or similar
+- Coverage-specific defined terms embedded in insuring agreements, endorsements, exclusions, or conditions
+- Multi-part definitions with numbered, lettered, or bulleted clauses
+- Definitions that affect coverage triggers, covered property, insured status, exclusions, limits, or duties
+
+Critical rules:
+- Preserve the original content. Do not paraphrase content.
+- Keep all subparts of a definition together in one item when they define the same term.
+- Ignore table-of-contents entries, running headers/footers, indexes, and cross-references that do not include substantive definition text.
+- Do not emit generic headings like "Definitions" as a term unless the page defines an actual term.
+- Always include pageNumber when the definition appears on a specific page in the supplied document chunk.
+- Use definition as the canonical full text. Do not return a separate content field.
+
+Return JSON only.`;
+}
+
+// src/prompts/extractors/covered-reasons.ts
+import { z as z35 } from "zod";
+var CoveredReasonsSchema = z35.object({
+  coveredReasons: z35.array(
+    z35.object({
+      coverageName: z35.string().describe("Coverage, coverage part, or form this covered reason belongs to"),
+      reasonNumber: z35.string().optional().describe("Source number or letter for the covered reason, if shown"),
+      title: z35.string().optional().describe("Covered reason title, peril, cause of loss, trigger, or short name"),
+      content: z35.string().describe("Full verbatim covered-reason or insuring-agreement text"),
+      conditions: z35.array(z35.string()).optional().describe("Conditions, timing rules, documentation requirements, or prerequisites attached to this covered reason"),
+      exceptions: z35.array(z35.string()).optional().describe("Exceptions or limitations attached to this covered reason"),
+      appliesTo: z35.array(z35.string()).optional().describe("Covered property, persons, autos, locations, operations, or coverage parts this reason applies to"),
+      pageNumber: z35.number().optional().describe("Original document page number"),
+      formNumber: z35.string().optional().describe("Form number where this covered reason appears"),
+      formTitle: z35.string().optional().describe("Form title where this covered reason appears"),
+      sectionRef: z35.string().optional().describe("Section heading where this covered reason appears"),
+      originalContent: z35.string().optional().describe("Short verbatim source snippet used for this covered reason")
+    })
+  ).describe("Covered causes, perils, triggers, or reasons that affirmatively grant coverage")
+});
+function buildCoveredReasonsPrompt() {
+  return `You are an expert insurance document analyst. Extract ALL covered reasons from this document. Preserve original wording verbatim.
+
+A covered reason is affirmative coverage language explaining why, when, or for what cause the insurer will pay. This may be called a covered peril, covered cause of loss, accident, occurrence, loss trigger, additional coverage, expense, or insuring agreement grant.
+
+For EACH covered reason, extract:
+- coverageName: coverage, coverage part, or form this covered reason belongs to \u2014 REQUIRED
+- reasonNumber: source number or letter for the covered reason, if shown
+- title: covered peril, cause of loss, trigger, or short name
+- content: full verbatim covered-reason or insuring-agreement text \u2014 REQUIRED
+- conditions: conditions, timing rules, documentation requirements, or prerequisites attached to this covered reason
+- exceptions: exceptions or limitations attached to this covered reason
+- appliesTo: covered property, persons, autos, locations, operations, or coverage parts this reason applies to
+- pageNumber: original document page number where this covered reason appears
+- formNumber: form number where this covered reason appears, if shown
+- formTitle: form title where this covered reason appears, if shown
+- sectionRef: heading where this covered reason appears
+- originalContent: short verbatim source snippet used for this covered reason
+
+Focus on:
+- Named perils and covered causes of loss
+- Insuring agreement grants and coverage triggers
+- Additional coverages and coverage extensions that state when payment applies
+- Personal lines phrases such as fire, lightning, windstorm, hail, theft, collision, comprehensive, or accidental direct physical loss
+- Commercial lines phrases such as bodily injury, property damage, personal and advertising injury, employee dishonesty, computer fraud, equipment breakdown, or professional services acts
+
+Critical rules:
+- Preserve the original content. Do not paraphrase content.
+- Extract affirmative coverage grants, not exclusions, conditions, or declarations-only limit rows.
+- Do not emit a covered reason from a table-of-contents entry, running header/footer, or reference that only points elsewhere.
+- If a covered reason includes exceptions or limitations in the same clause, keep them in content and also list them in exceptions when they can be separated cleanly.
+- Always include pageNumber when the covered reason appears on a specific page in the supplied document chunk.
+- Preserve coverage grouping. Do not merge separate coverage parts into one generic list.
+
+Return JSON only.`;
+}
+
 // src/prompts/extractors/index.ts
+function asRecord(data) {
+  return data && typeof data === "object" ? data : void 0;
+}
+function getSections2(data) {
+  const sections = asRecord(data)?.sections;
+  return Array.isArray(sections) ? sections : [];
+}
+function isCoveredReasonsEmpty(data) {
+  const record = asRecord(data);
+  if (!record) return true;
+  const coveredReasons = Array.isArray(record.coveredReasons) ? record.coveredReasons : Array.isArray(record.covered_reasons) ? record.covered_reasons : [];
+  return coveredReasons.length === 0;
+}
+function isDefinitionsEmpty(data) {
+  const definitions = asRecord(data)?.definitions;
+  return !Array.isArray(definitions) || definitions.length === 0;
+}
+function sectionLooksLikeCoveredReason(section) {
+  const type = String(section.type ?? "").toLowerCase();
+  const title = String(section.title ?? "").toLowerCase();
+  return type === "covered_reason" || title.includes("covered cause") || title.includes("covered reason") || title.includes("covered peril") || title.includes("named peril") || title.includes("insuring agreement");
+}
+function deriveCoveredReasonsFromSections(data) {
+  const coveredReasons = getSections2(data).filter(sectionLooksLikeCoveredReason).map((section) => ({
+    coverageName: String(section.coverageName ?? section.formTitle ?? section.title ?? "Covered Reasons"),
+    title: typeof section.title === "string" ? section.title : void 0,
+    content: String(section.content ?? ""),
+    pageNumber: typeof section.pageStart === "number" ? section.pageStart : void 0,
+    formNumber: typeof section.formNumber === "string" ? section.formNumber : void 0,
+    formTitle: typeof section.formTitle === "string" ? section.formTitle : void 0,
+    sectionRef: typeof section.sectionNumber === "string" ? section.sectionNumber : void 0,
+    originalContent: typeof section.content === "string" ? section.content.slice(0, 500) : void 0
+  })).filter((coveredReason) => coveredReason.content.trim().length > 0);
+  return coveredReasons.length > 0 ? { coveredReasons } : void 0;
+}
+function deriveDefinitionsFromSections(data) {
+  const definitions = getSections2(data).filter((section) => String(section.type ?? "").toLowerCase() === "definition").map((section) => ({
+    term: String(section.title ?? "Definitions"),
+    definition: String(section.content ?? ""),
+    pageNumber: typeof section.pageStart === "number" ? section.pageStart : void 0,
+    formNumber: typeof section.formNumber === "string" ? section.formNumber : void 0,
+    formTitle: typeof section.formTitle === "string" ? section.formTitle : void 0,
+    sectionRef: typeof section.sectionNumber === "string" ? section.sectionNumber : void 0,
+    originalContent: typeof section.content === "string" ? section.content.slice(0, 500) : void 0
+  })).filter((definition) => definition.definition.trim().length > 0);
+  return definitions.length > 0 ? { definitions } : void 0;
+}
 var EXTRACTORS = {
   carrier_info: { buildPrompt: buildCarrierInfoPrompt, schema: CarrierInfoSchema, maxTokens: 2048 },
   named_insured: { buildPrompt: buildNamedInsuredPrompt, schema: NamedInsuredSchema2, maxTokens: 2048 },
@@ -5017,28 +5585,54 @@ var EXTRACTORS = {
   declarations: { buildPrompt: buildDeclarationsPrompt, schema: DeclarationsExtractSchema, maxTokens: 8192 },
   loss_history: { buildPrompt: buildLossHistoryPrompt, schema: LossHistorySchema, maxTokens: 4096 },
   sections: { buildPrompt: buildSectionsPrompt, schema: SectionsSchema, maxTokens: 8192 },
-  supplementary: { buildPrompt: buildSupplementaryPrompt, schema: SupplementarySchema, maxTokens: 2048 }
+  supplementary: { buildPrompt: buildSupplementaryPrompt, schema: SupplementarySchema, maxTokens: 2048 },
+  definitions: {
+    buildPrompt: buildDefinitionsPrompt,
+    schema: DefinitionsSchema,
+    maxTokens: 8192,
+    fallback: {
+      extractorName: "sections",
+      isEmpty: isDefinitionsEmpty,
+      deriveFocusedResult: deriveDefinitionsFromSections
+    }
+  },
+  covered_reasons: {
+    buildPrompt: buildCoveredReasonsPrompt,
+    schema: CoveredReasonsSchema,
+    maxTokens: 8192,
+    fallback: {
+      extractorName: "sections",
+      isEmpty: isCoveredReasonsEmpty,
+      deriveFocusedResult: deriveCoveredReasonsFromSections
+    }
+  }
 };
 function getExtractor(name) {
   return EXTRACTORS[name];
 }
+function formatExtractorCatalogForPrompt() {
+  return Object.entries(EXTRACTORS).map(([name, extractor]) => {
+    const fallback = extractor.fallback ? `; fallback: ${extractor.fallback.extractorName}` : "";
+    return `- ${name} (maxTokens: ${extractor.maxTokens ?? 4096}${fallback})`;
+  }).join("\n");
+}
 
 // src/extraction/resolve-referential.ts
-import { z as z35 } from "zod";
+import { z as z37 } from "zod";
 
 // src/prompts/extractors/referential-lookup.ts
-import { z as z34 } from "zod";
-var ReferentialLookupSchema = z34.object({
-  resolvedCoverages: z34.array(
-    z34.object({
-      coverageName: z34.string().describe("The coverage name that was referenced"),
-      resolvedLimit: z34.string().optional().describe("The concrete limit value found, if any"),
+import { z as z36 } from "zod";
+var ReferentialLookupSchema = z36.object({
+  resolvedCoverages: z36.array(
+    z36.object({
+      coverageName: z36.string().describe("The coverage name that was referenced"),
+      resolvedLimit: z36.string().optional().describe("The concrete limit value found, if any"),
       resolvedLimitValueType: CoverageValueTypeSchema.optional(),
-      resolvedDeductible: z34.string().optional().describe("The concrete deductible value found, if any"),
+      resolvedDeductible: z36.string().optional().describe("The concrete deductible value found, if any"),
       resolvedDeductibleValueType: CoverageValueTypeSchema.optional(),
-      pageNumber: z34.number().optional().describe("Page where the resolved value was found"),
-      originalContent: z34.string().optional().describe("Verbatim source text for the resolved value"),
-      confidence: z34.enum(["high", "medium", "low"]).describe("Confidence in the resolution")
+      pageNumber: z36.number().optional().describe("Page where the resolved value was found"),
+      originalContent: z36.string().optional().describe("Verbatim source text for the resolved value"),
+      confidence: z36.enum(["high", "medium", "low"]).describe("Confidence in the resolution")
     })
   )
 });
@@ -5073,18 +5667,124 @@ Your task:
 Return JSON only.`;
 }
 
-// src/extraction/resolve-referential.ts
+// src/extraction/heuristics.ts
 function looksReferential(value) {
   if (typeof value !== "string") return false;
   const normalized = value.toLowerCase();
   return normalized.includes("shown in the declarations") || normalized.includes("shown in declarations") || normalized.includes("shown in the schedule") || normalized.includes("as stated") || normalized.includes("if applicable");
 }
+function looksCoveredReasonSection(section) {
+  const title = String(section.title ?? "").toLowerCase();
+  const type = String(section.type ?? "").toLowerCase();
+  return type === "covered_reason" || title.includes("covered cause") || title.includes("covered reason") || title.includes("covered peril");
+}
+
+// src/extraction/referential-workflow.ts
+function normalizeText(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+function containsTarget(value, target) {
+  const normalizedValue = normalizeText(value);
+  return Boolean(normalizedValue && target && normalizedValue.includes(target));
+}
+function pageRangeFrom(startPage, endPage) {
+  if (typeof startPage !== "number" || !Number.isFinite(startPage) || startPage <= 0) {
+    return void 0;
+  }
+  const normalizedEnd = typeof endPage === "number" && Number.isFinite(endPage) && endPage >= startPage ? endPage : startPage;
+  return { startPage, endPage: normalizedEnd };
+}
+function parseReferentialTarget(rawTarget) {
+  const raw = rawTarget?.trim() || "unknown";
+  const normalized = raw.toLowerCase();
+  if (normalized === "unknown") return { raw, normalized, kind: "unknown" };
+  if (/declarations?|dec\b|decs\b/.test(normalized)) return { raw, normalized, kind: "declarations" };
+  if (/schedule|scheduled/.test(normalized)) return { raw, normalized, kind: "schedule" };
+  if (/\bitem\b/.test(normalized)) return { raw, normalized, kind: "item" };
+  if (/premises?|location|building/.test(normalized)) return { raw, normalized, kind: "premises" };
+  if (/\bsection\b/.test(normalized)) return { raw, normalized, kind: "section" };
+  if (/policy|coverage\s+part|coverage\s+form/.test(normalized)) return { raw, normalized, kind: "policy" };
+  return { raw, normalized, kind: "unknown" };
+}
+function findLocalReferentialPages(params) {
+  const targetLower = params.referenceTarget.toLowerCase();
+  for (const section of params.sections) {
+    if (containsTarget(section.title, targetLower)) {
+      const range = pageRangeFrom(section.pageStart, section.pageEnd);
+      if (range) return range;
+    }
+  }
+  for (const form of params.formInventory) {
+    const titleMatch = containsTarget(form.title, targetLower);
+    const typeMatch = containsTarget(form.formType, targetLower);
+    const numberMatch = containsTarget(form.formNumber, targetLower);
+    if (titleMatch || typeMatch || numberMatch) {
+      const range = pageRangeFrom(form.pageStart, form.pageEnd);
+      if (range) return range;
+    }
+  }
+  return void 0;
+}
+function findDeclarationsSchedulePages(parsedTarget, formInventory) {
+  for (const form of formInventory) {
+    const formType = normalizeText(form.formType);
+    const title = normalizeText(form.title);
+    const matchesDeclarations = formType === "declarations" || /declarations?|dec\b|decs\b/.test(title);
+    const matchesSchedule = /schedule|scheduled|coverage/.test(title) || formType === "coverage";
+    const shouldUse = parsedTarget.kind === "declarations" ? matchesDeclarations : parsedTarget.kind === "schedule" || parsedTarget.kind === "item" || parsedTarget.kind === "premises" ? matchesSchedule || matchesDeclarations : parsedTarget.kind === "policy" ? matchesDeclarations || matchesSchedule : false;
+    if (shouldUse) {
+      const range = pageRangeFrom(form.pageStart, form.pageEnd);
+      if (range) return range;
+    }
+  }
+  return void 0;
+}
+function findSectionPages(parsedTarget, sections) {
+  for (const section of sections) {
+    const title = normalizeText(section.title);
+    const type = normalizeText(section.type);
+    const matchesKind = parsedTarget.kind === "declarations" && (type === "declarations" || /declarations?/.test(title)) || parsedTarget.kind === "schedule" && (type === "schedule" || /schedule|scheduled/.test(title)) || parsedTarget.kind === "premises" && /premises?|location|building/.test(title) || parsedTarget.kind === "item" && /\bitem\b|schedule|scheduled/.test(title) || parsedTarget.kind === "section" && containsTarget(title, parsedTarget.normalized);
+    if (matchesKind) {
+      const range = pageRangeFrom(section.pageStart, section.pageEnd);
+      if (range) return range;
+    }
+  }
+  return void 0;
+}
+function decideReferentialResolutionAction(params) {
+  if (params.localPageRange) {
+    return { kind: "lookup_pages", source: "local", pageRange: params.localPageRange };
+  }
+  const parsedTarget = parseReferentialTarget(params.referenceTarget);
+  const declarationsScheduleRange = findDeclarationsSchedulePages(parsedTarget, params.formInventory);
+  if (declarationsScheduleRange) {
+    return {
+      kind: "lookup_pages",
+      source: "declarations_schedule",
+      pageRange: declarationsScheduleRange
+    };
+  }
+  const sectionRange = findSectionPages(parsedTarget, params.sections);
+  if (sectionRange) {
+    return { kind: "lookup_pages", source: "sections", pageRange: sectionRange };
+  }
+  if (parsedTarget.kind === "unknown") {
+    return { kind: "skip", reason: "no concrete reference target" };
+  }
+  return { kind: "page_location" };
+}
+
+// src/extraction/resolve-referential.ts
 function parseReferenceTarget(text) {
   if (typeof text !== "string") return void 0;
   const normalized = text.trim();
   if (!normalized) return void 0;
   const sectionMatch = normalized.match(/\b(Section\s+\d+[A-Za-z]?)/i);
   if (sectionMatch) return sectionMatch[1];
+  const itemMatch = normalized.match(/\b(Item\s+\d+[A-Za-z]?)/i);
+  if (itemMatch) return itemMatch[1];
+  const premisesMatch = normalized.match(/\b(Premises?(?:\s+No\.?\s*\d+[A-Za-z]?|\s+\d+[A-Za-z]?)?)/i);
+  if (premisesMatch) return premisesMatch[1].trim();
   if (/declarations/i.test(normalized)) return "Declarations";
   const scheduleMatch = normalized.match(/\b(Schedule(?:\s+of\s+[A-Za-z ]+)?)/i);
   if (scheduleMatch) return scheduleMatch[1].trim();
@@ -5097,9 +5797,9 @@ function parseReferenceTarget(text) {
   if (/if applicable/i.test(normalized)) return void 0;
   return void 0;
 }
-var PageLocationSchema = z35.object({
-  startPage: z35.number(),
-  endPage: z35.number()
+var PageLocationSchema = z37.object({
+  startPage: z37.number(),
+  endPage: z37.number()
 });
 async function findReferencedPages(params) {
   const {
@@ -5110,26 +5810,31 @@ async function findReferencedPages(params) {
     pageCount,
     generateObject,
     providerOptions,
+    trackUsage,
     log
   } = params;
-  const targetLower = referenceTarget.toLowerCase();
-  for (const section of sections) {
-    if (section.title && section.pageStart != null && section.title.toLowerCase().includes(targetLower)) {
-      return {
-        startPage: section.pageStart,
-        endPage: section.pageEnd ?? section.pageStart
-      };
-    }
+  const localPageRange = findLocalReferentialPages({
+    referenceTarget,
+    sections,
+    formInventory
+  });
+  const action = decideReferentialResolutionAction({
+    referenceTarget,
+    sections,
+    formInventory,
+    localPageRange
+  });
+  if (action.kind === "lookup_pages") {
+    await log?.(
+      `Referential target "${referenceTarget}" resolved to pages ${action.pageRange.startPage}-${action.pageRange.endPage} via ${action.source}.`
+    );
+    return action.pageRange;
   }
-  for (const form of formInventory) {
-    const titleMatch = form.title && form.title.toLowerCase().includes(targetLower);
-    const typeMatch = form.formType && form.formType.toLowerCase().includes(targetLower);
-    if ((titleMatch || typeMatch) && form.pageStart != null) {
-      return {
-        startPage: form.pageStart,
-        endPage: form.pageEnd ?? form.pageStart
-      };
-    }
+  if (action.kind === "skip") {
+    await log?.(
+      `Skipping referential target "${referenceTarget}": ${action.reason}.`
+    );
+    return void 0;
   }
   try {
     const result = await safeGenerateObject(
@@ -5157,6 +5862,7 @@ Return JSON only.`,
         )
       }
     );
+    trackUsage?.(result.usage);
     if (result.object.startPage > 0 && result.object.endPage > 0) {
       return {
         startPage: result.object.startPage,
@@ -5214,7 +5920,9 @@ async function resolveReferentialCoverages(params) {
   for (let i = 0; i < referentialCoverages.length; i++) {
     const cov = referentialCoverages[i];
     const refString = (looksReferential(cov.limit) ? cov.limit : void 0) ?? (looksReferential(cov.deductible) ? cov.deductible : void 0) ?? cov.limit ?? "";
-    const target = parseReferenceTarget(refString) ?? "unknown";
+    const sectionRef = typeof cov.sectionRef === "string" ? cov.sectionRef : "";
+    const parsedTarget = parseReferenceTarget(refString) ?? parseReferenceTarget(sectionRef) ?? sectionRef;
+    const target = parsedTarget || "unknown";
     const group = targetGroups.get(target) ?? [];
     group.push({ coverage: cov, index: i });
     targetGroups.set(target, group);
@@ -5238,6 +5946,7 @@ async function resolveReferentialCoverages(params) {
           pageCount,
           generateObject,
           providerOptions,
+          trackUsage,
           log
         });
         if (!pageRange) {
@@ -5355,6 +6064,78 @@ async function resolveReferentialCoverages(params) {
   };
 }
 
+// src/extraction/focused-dispatch.ts
+async function runFocusedExtractorWithFallback(params) {
+  const {
+    task,
+    pdfInput,
+    generateObject,
+    convertPdfToImages,
+    providerOptions,
+    trackUsage,
+    log
+  } = params;
+  const ext = getExtractor(task.extractorName);
+  if (!ext) {
+    await log?.(`Unknown extractor: ${task.extractorName}, skipping`);
+    return null;
+  }
+  try {
+    const result = await runExtractor({
+      name: task.extractorName,
+      prompt: ext.buildPrompt(),
+      schema: ext.schema,
+      pdfInput,
+      startPage: task.startPage,
+      endPage: task.endPage,
+      generateObject,
+      convertPdfToImages,
+      maxTokens: ext.maxTokens ?? 4096,
+      providerOptions
+    });
+    trackUsage(result.usage);
+    if (!ext.fallback?.isEmpty(result.data)) {
+      return result;
+    }
+    if (!ext.fallback) {
+      return result;
+    }
+  } catch (error) {
+    await log?.(`Extractor ${task.extractorName} failed: ${error}`);
+    if (!ext.fallback) {
+      return null;
+    }
+  }
+  const fallbackExt = getExtractor(ext.fallback.extractorName);
+  if (!fallbackExt) return null;
+  await log?.(
+    `Extractor ${task.extractorName} produced no usable records; trying ${ext.fallback.extractorName} fallback for pages ${task.startPage}-${task.endPage}`
+  );
+  try {
+    const fallbackResult = await runExtractor({
+      name: ext.fallback.extractorName,
+      prompt: fallbackExt.buildPrompt(),
+      schema: fallbackExt.schema,
+      pdfInput,
+      startPage: task.startPage,
+      endPage: task.endPage,
+      generateObject,
+      convertPdfToImages,
+      maxTokens: fallbackExt.maxTokens ?? 4096,
+      providerOptions
+    });
+    trackUsage(fallbackResult.usage);
+    const focusedData = ext.fallback.deriveFocusedResult(fallbackResult.data);
+    return focusedData ? [
+      fallbackResult,
+      { name: task.extractorName, data: focusedData, usage: void 0 }
+    ] : fallbackResult;
+  } catch (fallbackError) {
+    await log?.(`${ext.fallback.extractorName} fallback for ${task.extractorName} failed: ${fallbackError}`);
+    return null;
+  }
+}
+
 // src/core/quality.ts
 function evaluateQualityGate(params) {
   const { issues, hasRoundWarnings = false } = params;
@@ -5391,11 +6172,6 @@ function addFormEntry(inventory, formNumber, source, extra) {
     sources: [source]
   });
 }
-function looksReferential2(value) {
-  if (typeof value !== "string") return false;
-  const normalized = value.toLowerCase();
-  return normalized.includes("shown in the declarations") || normalized.includes("shown in declarations") || normalized.includes("shown in the schedule") || normalized.includes("as stated") || normalized.includes("if applicable");
-}
 function looksTocArtifact(value) {
   if (typeof value !== "string") return false;
   return /\.{4,}\d{1,3}$/.test(value.trim()) || /^\d+\.\s+[A-Z][\s\S]*\.{3,}\d{1,3}$/.test(value.trim());
@@ -5419,6 +6195,28 @@ function buildExtractionReviewReport(params) {
   const exclusions = memory.get("exclusions")?.exclusions ?? [];
   const conditions = memory.get("conditions")?.conditions ?? [];
   const sections = memory.get("sections")?.sections ?? [];
+  const definitionsResult = memory.get("definitions");
+  const coveredReasonsResult = memory.get("covered_reasons");
+  const definitions = Array.isArray(definitionsResult?.definitions) ? definitionsResult.definitions : sections.filter((section) => section.type === "definition");
+  const coveredReasons = Array.isArray(coveredReasonsResult?.coveredReasons) ? coveredReasonsResult.coveredReasons : Array.isArray(coveredReasonsResult?.covered_reasons) ? coveredReasonsResult.covered_reasons : sections.filter(looksCoveredReasonSection);
+  const mappedDefinitions = params.pageAssignments.some((assignment) => assignment.extractorNames.includes("definitions"));
+  const mappedCoveredReasons = params.pageAssignments.some((assignment) => assignment.extractorNames.includes("covered_reasons"));
+  if (mappedDefinitions && definitions.length === 0) {
+    deterministicIssues.push({
+      code: "definitions_mapped_but_empty",
+      severity: "warning",
+      message: "Page map assigned definitions extraction, but no definition records were extracted.",
+      extractorName: "definitions"
+    });
+  }
+  if (mappedCoveredReasons && coveredReasons.length === 0) {
+    deterministicIssues.push({
+      code: "covered_reasons_mapped_but_empty",
+      severity: "warning",
+      message: "Page map assigned covered reasons extraction, but no covered reason records were extracted.",
+      extractorName: "covered_reasons"
+    });
+  }
   for (const form of extractedFormInventory) {
     addFormEntry(
       inventory,
@@ -5515,7 +6313,7 @@ function buildExtractionReviewReport(params) {
         itemName: typeof coverage.name === "string" ? coverage.name : void 0
       });
     }
-    if (looksReferential2(coverage.limit) || looksReferential2(coverage.deductible)) {
+    if (looksReferential(coverage.limit) || looksReferential(coverage.deductible)) {
       deterministicIssues.push({
         code: "coverage_referential_value",
         severity: "warning",
@@ -5616,6 +6414,67 @@ function buildExtractionReviewReport(params) {
       });
     }
   }
+  for (const definition of definitions) {
+    const term = typeof definition.term === "string" ? definition.term : typeof definition.title === "string" ? definition.title : "unknown";
+    const content = typeof definition.definition === "string" ? definition.definition : typeof definition.content === "string" ? definition.content : "";
+    if (!content.trim()) {
+      deterministicIssues.push({
+        code: "definition_missing_content",
+        severity: "warning",
+        message: `Definition "${term}" is missing definition text.`,
+        extractorName: "definitions",
+        formNumber: normalizeFormNumber(definition.formNumber),
+        pageNumber: typeof definition.pageNumber === "number" ? definition.pageNumber : typeof definition.pageStart === "number" ? definition.pageStart : void 0,
+        itemName: term
+      });
+    }
+    if (typeof definition.pageNumber !== "number" && typeof definition.pageStart !== "number") {
+      deterministicIssues.push({
+        code: "definition_missing_page_number",
+        severity: "warning",
+        message: `Definition "${term}" is missing page provenance.`,
+        extractorName: "definitions",
+        formNumber: normalizeFormNumber(definition.formNumber),
+        itemName: term
+      });
+    }
+  }
+  for (const coveredReason of coveredReasons) {
+    const itemName = typeof coveredReason.name === "string" ? coveredReason.name : typeof coveredReason.reason === "string" ? coveredReason.reason : typeof coveredReason.title === "string" ? coveredReason.title : "unknown";
+    const content = typeof coveredReason.content === "string" ? coveredReason.content : typeof coveredReason.description === "string" ? coveredReason.description : "";
+    if (!content.trim()) {
+      deterministicIssues.push({
+        code: "covered_reason_missing_content",
+        severity: "warning",
+        message: `Covered reason "${itemName}" is missing substantive text.`,
+        extractorName: "covered_reasons",
+        formNumber: normalizeFormNumber(coveredReason.formNumber),
+        pageNumber: typeof coveredReason.pageNumber === "number" ? coveredReason.pageNumber : typeof coveredReason.pageStart === "number" ? coveredReason.pageStart : void 0,
+        itemName
+      });
+    }
+    if (typeof coveredReason.pageNumber !== "number" && typeof coveredReason.pageStart !== "number") {
+      deterministicIssues.push({
+        code: "covered_reason_missing_page_number",
+        severity: "warning",
+        message: `Covered reason "${itemName}" is missing page provenance.`,
+        extractorName: "covered_reasons",
+        formNumber: normalizeFormNumber(coveredReason.formNumber),
+        itemName
+      });
+    }
+    if (looksReferential(content) || looksReferential(coveredReason.reason)) {
+      deterministicIssues.push({
+        code: "covered_reason_referential_value",
+        severity: "warning",
+        message: `Covered reason "${itemName}" contains referential language instead of the extracted covered cause wording.`,
+        extractorName: "covered_reasons",
+        formNumber: normalizeFormNumber(coveredReason.formNumber),
+        pageNumber: typeof coveredReason.pageNumber === "number" ? coveredReason.pageNumber : typeof coveredReason.pageStart === "number" ? coveredReason.pageStart : void 0,
+        itemName
+      });
+    }
+  }
   for (const section of sections) {
     if (typeof section.content === "string" && section.content.trim().length < 120 && typeof section.pageStart === "number" && (!("pageEnd" in section) || section.pageEnd === section.pageStart || section.pageEnd === void 0)) {
       deterministicIssues.push({
@@ -5638,6 +6497,8 @@ function buildExtractionReviewReport(params) {
   const artifacts = [
     { kind: "form_inventory", label: "Form Inventory", itemCount: formInventory.length },
     { kind: "page_map", label: "Page Map", itemCount: params.pageAssignments.length },
+    { kind: "definitions", label: "Definitions", itemCount: definitions.length },
+    { kind: "covered_reasons", label: "Covered Reasons", itemCount: coveredReasons.length },
     { kind: "referential_resolution", label: "Referential Resolution", itemCount: coverages.filter((c) => c.limitValueType === "referential" || c.limitValueType === "as_stated" || c.deductibleValueType === "referential" || c.deductibleValueType === "as_stated").length }
   ];
   const qualityGateStatus = evaluateQualityGate({
@@ -5663,6 +6524,134 @@ function toReviewRoundRecord(round, review) {
   };
 }
 
+// src/extraction/planning.ts
+function normalizePageAssignments(pageAssignments, formInventory) {
+  const pageFormTypes = /* @__PURE__ */ new Map();
+  if (formInventory) {
+    for (const form of formInventory.forms) {
+      if (form.pageStart != null) {
+        const end = form.pageEnd ?? form.pageStart;
+        for (let p = form.pageStart; p <= end; p += 1) {
+          const types = pageFormTypes.get(p) ?? /* @__PURE__ */ new Set();
+          types.add(form.formType);
+          pageFormTypes.set(p, types);
+        }
+      }
+    }
+  }
+  return pageAssignments.map((assignment) => {
+    let extractorNames = [...new Set(
+      (assignment.extractorNames.length > 0 ? assignment.extractorNames : ["sections"]).filter(Boolean)
+    )];
+    const hasDeclarations = extractorNames.includes("declarations");
+    const hasConditions = extractorNames.includes("conditions");
+    const hasExclusions = extractorNames.includes("exclusions");
+    const hasEndorsements = extractorNames.includes("endorsements");
+    const looksLikeScheduleValues = assignment.hasScheduleValues === true;
+    const roleBlocksCoverageLimits = assignment.pageRole === "policy_form" || assignment.pageRole === "condition_exclusion_form" || assignment.pageRole === "endorsement_form";
+    const inventoryTypes = pageFormTypes.get(assignment.localPageNumber);
+    const inventoryBlocksCoverageLimits = inventoryTypes != null && !looksLikeScheduleValues && !hasDeclarations && (inventoryTypes.has("endorsement") || inventoryTypes.has("notice") || inventoryTypes.has("application"));
+    if (extractorNames.includes("coverage_limits")) {
+      const shouldDropCoverageLimits = inventoryBlocksCoverageLimits || !looksLikeScheduleValues && roleBlocksCoverageLimits || !hasDeclarations && !looksLikeScheduleValues && (hasConditions || hasExclusions) || !hasDeclarations && !looksLikeScheduleValues && hasEndorsements;
+      if (shouldDropCoverageLimits) {
+        extractorNames = extractorNames.filter((name) => name !== "coverage_limits");
+      }
+    }
+    if (inventoryTypes?.has("endorsement") && !extractorNames.includes("endorsements")) {
+      extractorNames = [...extractorNames, "endorsements"];
+    }
+    if (extractorNames.length === 0) {
+      extractorNames = ["sections"];
+    }
+    return {
+      ...assignment,
+      extractorNames
+    };
+  });
+}
+function buildTemplateHints(primaryType, documentType, pageCount, template) {
+  return [
+    `Document type: ${primaryType} ${documentType}`,
+    `Expected sections: ${template.expectedSections.join(", ")}`,
+    `Page hints: ${Object.entries(template.pageHints).map(([k, v]) => `${k}: ${v}`).join("; ")}`,
+    `Total pages: ${pageCount}`
+  ].join("\n");
+}
+function groupContiguousPages(pages) {
+  if (pages.length === 0) return [];
+  const sorted = [...new Set(pages)].sort((a, b) => a - b);
+  const ranges = [];
+  let start = sorted[0];
+  let previous = sorted[0];
+  for (let i = 1; i < sorted.length; i += 1) {
+    const current = sorted[i];
+    if (current === previous + 1) {
+      previous = current;
+      continue;
+    }
+    ranges.push({ startPage: start, endPage: previous });
+    start = current;
+    previous = current;
+  }
+  ranges.push({ startPage: start, endPage: previous });
+  return ranges;
+}
+function buildPlanFromPageAssignments(pageAssignments, pageCount, formInventory) {
+  const extractorPages = /* @__PURE__ */ new Map();
+  for (const assignment of pageAssignments) {
+    const extractors = assignment.extractorNames.length > 0 ? assignment.extractorNames : ["sections"];
+    for (const extractorName of extractors) {
+      extractorPages.set(extractorName, [...extractorPages.get(extractorName) ?? [], assignment.localPageNumber]);
+    }
+  }
+  const coveredPages = /* @__PURE__ */ new Set();
+  for (const pages of extractorPages.values()) {
+    for (const page of pages) coveredPages.add(page);
+  }
+  for (let page = 1; page <= pageCount; page += 1) {
+    if (!coveredPages.has(page)) {
+      extractorPages.set("sections", [...extractorPages.get("sections") ?? [], page]);
+    }
+  }
+  const contextualExtractors = /* @__PURE__ */ new Set(["conditions", "covered_reasons", "definitions", "exclusions", "endorsements"]);
+  const contextualForms = (formInventory?.forms ?? []).filter(
+    (form) => form.pageStart != null && (form.pageEnd ?? form.pageStart) != null
+  );
+  const expandPagesToFormRanges = (extractorName, pages) => {
+    if (!contextualExtractors.has(extractorName)) return pages;
+    const expanded = new Set(pages);
+    for (const page of pages) {
+      for (const form of contextualForms) {
+        const pageStart = form.pageStart;
+        const pageEnd = form.pageEnd ?? form.pageStart;
+        const formType = form.formType;
+        const supportsContextualExpansion = extractorName === "endorsements" ? formType === "endorsement" : formType === "coverage" || formType === "endorsement";
+        if (!supportsContextualExpansion) continue;
+        if (page < pageStart || page > pageEnd) continue;
+        for (let current = pageStart; current <= pageEnd; current += 1) {
+          expanded.add(current);
+        }
+      }
+    }
+    return [...expanded].sort((a, b) => a - b);
+  };
+  const tasks = [...extractorPages.entries()].flatMap(
+    ([extractorName, pages]) => groupContiguousPages(expandPagesToFormRanges(extractorName, pages)).map(({ startPage, endPage }) => ({
+      extractorName,
+      startPage,
+      endPage,
+      description: `Page-mapped ${extractorName} extraction for pages ${startPage}-${endPage}`
+    }))
+  ).sort((a, b) => a.startPage - b.startPage || a.extractorName.localeCompare(b.extractorName));
+  return {
+    tasks,
+    pageMap: [...extractorPages.entries()].map(([section, pages]) => ({
+      section,
+      pages: `pages ${[...new Set(pages)].sort((a, b) => a - b).join(", ")}`
+    }))
+  };
+}
+
 // src/extraction/coordinator.ts
 function createExtractor(config) {
   const {
@@ -5679,6 +6668,7 @@ function createExtractor(config) {
     onCheckpointSave
   } = config;
   const limit = pLimit(concurrency);
+  const extractorCatalog = formatExtractorCatalogForPrompt();
   let totalUsage = { inputTokens: 0, outputTokens: 0 };
   let modelCalls = 0;
   let callsWithUsage = 0;
@@ -5699,32 +6689,56 @@ function createExtractor(config) {
     memory.set(name, mergeExtractorResult(name, existing, data));
   }
   function summarizeExtraction(memory) {
-    const coverageResult = memory.get("coverage_limits");
-    const declarationResult = memory.get("declarations");
-    const endorsementResult = memory.get("endorsements");
-    const exclusionResult = memory.get("exclusions");
-    const conditionResult = memory.get("conditions");
-    const sectionResult = memory.get("sections");
-    const coverageSummary = Array.isArray(coverageResult?.coverages) ? coverageResult.coverages.slice(0, 12).map((coverage) => ({
+    const declarationResult = readMemoryRecord(memory, "declarations");
+    const endorsements = readRecordArray(readMemoryRecord(memory, "endorsements"), "endorsements") ?? [];
+    const exclusions = readRecordArray(readMemoryRecord(memory, "exclusions"), "exclusions") ?? [];
+    const conditions = readRecordArray(readMemoryRecord(memory, "conditions"), "conditions") ?? [];
+    const sections = getSections(memory) ?? [];
+    const definitions = getDefinitions(memory) ?? sections.filter((section) => section.type === "definition");
+    const coveredReasons = getCoveredReasons(memory) ?? sections.filter(looksCoveredReasonSection);
+    const coverages = getCoverageLimitCoverages(memory);
+    const coverageSummary = coverages.slice(0, 12).map((coverage) => ({
       name: coverage.name,
       limit: coverage.limit,
       deductible: coverage.deductible,
       formNumber: coverage.formNumber
-    })) : [];
+    }));
     return JSON.stringify({
       extractedKeys: [...memory.keys()].filter((key) => key !== "classify"),
       declarationFieldCount: Array.isArray(declarationResult?.fields) ? declarationResult.fields.length : 0,
-      coverageCount: Array.isArray(coverageResult?.coverages) ? coverageResult.coverages.length : 0,
+      coverageCount: coverages.length,
       coverageSamples: coverageSummary,
-      endorsementCount: Array.isArray(endorsementResult?.endorsements) ? endorsementResult.endorsements.length : 0,
-      exclusionCount: Array.isArray(exclusionResult?.exclusions) ? exclusionResult.exclusions.length : 0,
-      conditionCount: Array.isArray(conditionResult?.conditions) ? conditionResult.conditions.length : 0,
-      sectionCount: Array.isArray(sectionResult?.sections) ? sectionResult.sections.length : 0
+      endorsementCount: endorsements.length,
+      exclusionCount: exclusions.length,
+      conditionCount: conditions.length,
+      definitionCount: definitions.length,
+      coveredReasonCount: coveredReasons.length,
+      sectionCount: sections.length
     }, null, 2);
   }
+  function textIncludesSupplementarySignal(value) {
+    if (typeof value !== "string") return false;
+    return /\b(supplementary|regulatory|department of insurance|ombudsman|complaint|claim|claims|contact|phone|email|cancellation|cancelled|nonrenewal|non-renewal|non renew|notice|governing law|jurisdiction|third[- ]party administrator|tpa)\b/i.test(value);
+  }
+  function hasSupplementaryExtractionSignal(pageAssignments, formInventory, memory) {
+    const hasPageSignal = pageAssignments.some(
+      (assignment) => assignment.pageRole === "supplementary" || assignment.extractorNames.includes("supplementary") || textIncludesSupplementarySignal(assignment.notes)
+    );
+    if (hasPageSignal) return true;
+    const hasFormSignal = (formInventory?.forms ?? []).some(
+      (form) => form.formType === "notice" || textIncludesSupplementarySignal(form.title) || textIncludesSupplementarySignal(form.formNumber)
+    );
+    if (hasFormSignal) return true;
+    const likelySupplementaryKeys = ["sections", "conditions", "endorsements", "exclusions"];
+    return likelySupplementaryKeys.some((key) => {
+      const value = memory.get(key);
+      if (!value) return false;
+      return textIncludesSupplementarySignal(JSON.stringify(value));
+    });
+  }
   function buildAlreadyExtractedSummary(memory) {
     const lines = [];
-    const declarationResult = memory.get("declarations");
+    const declarationResult = readMemoryRecord(memory, "declarations");
     if (Array.isArray(declarationResult?.fields)) {
       for (const field of declarationResult.fields) {
         if (field.key && field.value) {
@@ -5733,20 +6747,17 @@ function createExtractor(config) {
         }
       }
     }
-    const coverageResult = memory.get("coverage_limits");
-    if (Array.isArray(coverageResult?.coverages)) {
-      for (const cov of coverageResult.coverages) {
-        const parts = [cov.name, cov.limit && `limit=${cov.limit}`, cov.deductible && `deductible=${cov.deductible}`].filter(Boolean);
-        if (parts.length > 0) lines.push(`- coverage: ${parts.join(", ")}`);
-      }
+    for (const cov of getCoverageLimitCoverages(memory)) {
+      const parts = [cov.name, cov.limit && `limit=${cov.limit}`, cov.deductible && `deductible=${cov.deductible}`].filter(Boolean);
+      if (parts.length > 0) lines.push(`- coverage: ${parts.join(", ")}`);
     }
-    const namedInsured = memory.get("named_insured");
+    const namedInsured = getNamedInsured(memory);
     if (namedInsured) {
       for (const [key, value] of Object.entries(namedInsured)) {
         if (value && typeof value === "string") lines.push(`- ${key}: ${value}`);
       }
     }
-    const carrierInfo = memory.get("carrier_info");
+    const carrierInfo = getCarrierInfo(memory);
     if (carrierInfo) {
       for (const [key, value] of Object.entries(carrierInfo)) {
         if (value && typeof value === "string") lines.push(`- ${key}: ${value}`);
@@ -5754,141 +6765,43 @@ function createExtractor(config) {
     }
     return lines.length > 0 ? lines.join("\n") : "";
   }
-  function formatPageMapSummary(pageAssignments) {
-    const extractorPages = /* @__PURE__ */ new Map();
-    for (const assignment of pageAssignments) {
-      for (const extractorName of assignment.extractorNames) {
-        extractorPages.set(extractorName, [...extractorPages.get(extractorName) ?? [], assignment.localPageNumber]);
-      }
-    }
-    if (extractorPages.size === 0) return "No page assignments available.";
-    return [...extractorPages.entries()].map(([extractorName, pages]) => `${extractorName}: pages ${pages.join(", ")}`).join("\n");
-  }
-  function normalizePageAssignments(pageAssignments, formInventory) {
-    const pageFormTypes = /* @__PURE__ */ new Map();
-    if (formInventory) {
-      for (const form of formInventory.forms) {
-        if (form.pageStart != null) {
-          const end = form.pageEnd ?? form.pageStart;
-          for (let p = form.pageStart; p <= end; p++) {
-            const types = pageFormTypes.get(p) ?? /* @__PURE__ */ new Set();
-            types.add(form.formType);
-            pageFormTypes.set(p, types);
-          }
-        }
-      }
+  async function runFocusedExtractorTask(task, pdfInput, memory) {
+    if (task.extractorName === "supplementary") {
+      const alreadyExtractedSummary = buildAlreadyExtractedSummary(memory);
+      const result = await runExtractor({
+        name: "supplementary",
+        prompt: buildSupplementaryPrompt(alreadyExtractedSummary),
+        schema: SupplementarySchema,
+        pdfInput,
+        startPage: task.startPage,
+        endPage: task.endPage,
+        generateObject,
+        convertPdfToImages,
+        maxTokens: 4096,
+        providerOptions
+      });
+      trackUsage(result.usage);
+      return result;
     }
-    return pageAssignments.map((assignment) => {
-      let extractorNames = [...new Set(
-        (assignment.extractorNames.length > 0 ? assignment.extractorNames : ["sections"]).filter(Boolean)
-      )];
-      const hasDeclarations = extractorNames.includes("declarations");
-      const hasConditions = extractorNames.includes("conditions");
-      const hasExclusions = extractorNames.includes("exclusions");
-      const hasEndorsements = extractorNames.includes("endorsements");
-      const looksLikeScheduleValues = assignment.hasScheduleValues === true;
-      const roleBlocksCoverageLimits = assignment.pageRole === "policy_form" || assignment.pageRole === "condition_exclusion_form" || assignment.pageRole === "endorsement_form";
-      const inventoryTypes = pageFormTypes.get(assignment.localPageNumber);
-      const inventoryBlocksCoverageLimits = inventoryTypes != null && !looksLikeScheduleValues && !hasDeclarations && (inventoryTypes.has("endorsement") || inventoryTypes.has("notice") || inventoryTypes.has("application"));
-      if (extractorNames.includes("coverage_limits")) {
-        const shouldDropCoverageLimits = inventoryBlocksCoverageLimits || !looksLikeScheduleValues && roleBlocksCoverageLimits || !hasDeclarations && !looksLikeScheduleValues && (hasConditions || hasExclusions) || !hasDeclarations && !looksLikeScheduleValues && hasEndorsements;
-        if (shouldDropCoverageLimits) {
-          extractorNames = extractorNames.filter((name) => name !== "coverage_limits");
-        }
-      }
-      if (inventoryTypes?.has("endorsement") && !extractorNames.includes("endorsements")) {
-        extractorNames = [...extractorNames, "endorsements"];
-      }
-      if (extractorNames.length === 0) {
-        extractorNames = ["sections"];
-      }
-      return {
-        ...assignment,
-        extractorNames
-      };
+    return runFocusedExtractorWithFallback({
+      task,
+      pdfInput,
+      generateObject,
+      convertPdfToImages,
+      providerOptions,
+      trackUsage,
+      log
     });
   }
-  function buildTemplateHints(primaryType, documentType, pageCount, template) {
-    return [
-      `Document type: ${primaryType} ${documentType}`,
-      `Expected sections: ${template.expectedSections.join(", ")}`,
-      `Page hints: ${Object.entries(template.pageHints).map(([k, v]) => `${k}: ${v}`).join("; ")}`,
-      `Total pages: ${pageCount}`
-    ].join("\n");
-  }
-  function groupContiguousPages(pages) {
-    if (pages.length === 0) return [];
-    const sorted = [...new Set(pages)].sort((a, b) => a - b);
-    const ranges = [];
-    let start = sorted[0];
-    let previous = sorted[0];
-    for (let i = 1; i < sorted.length; i += 1) {
-      const current = sorted[i];
-      if (current === previous + 1) {
-        previous = current;
-        continue;
-      }
-      ranges.push({ startPage: start, endPage: previous });
-      start = current;
-      previous = current;
-    }
-    ranges.push({ startPage: start, endPage: previous });
-    return ranges;
-  }
-  function buildPlanFromPageAssignments(pageAssignments, pageCount, formInventory) {
+  function formatPageMapSummary(pageAssignments) {
     const extractorPages = /* @__PURE__ */ new Map();
     for (const assignment of pageAssignments) {
-      const extractors = assignment.extractorNames.length > 0 ? assignment.extractorNames : ["sections"];
-      for (const extractorName of extractors) {
+      for (const extractorName of assignment.extractorNames) {
         extractorPages.set(extractorName, [...extractorPages.get(extractorName) ?? [], assignment.localPageNumber]);
       }
     }
-    const coveredPages = /* @__PURE__ */ new Set();
-    for (const pages of extractorPages.values()) {
-      for (const page of pages) coveredPages.add(page);
-    }
-    for (let page = 1; page <= pageCount; page += 1) {
-      if (!coveredPages.has(page)) {
-        extractorPages.set("sections", [...extractorPages.get("sections") ?? [], page]);
-      }
-    }
-    const contextualExtractors = /* @__PURE__ */ new Set(["conditions", "exclusions", "endorsements"]);
-    const contextualForms = (formInventory?.forms ?? []).filter(
-      (form) => form.pageStart != null && (form.pageEnd ?? form.pageStart) != null
-    );
-    const expandPagesToFormRanges = (extractorName, pages) => {
-      if (!contextualExtractors.has(extractorName)) return pages;
-      const expanded = new Set(pages);
-      for (const page of pages) {
-        for (const form of contextualForms) {
-          const pageStart = form.pageStart;
-          const pageEnd = form.pageEnd ?? form.pageStart;
-          const formType = form.formType;
-          const supportsContextualExpansion = extractorName === "endorsements" ? formType === "endorsement" : formType === "coverage" || formType === "endorsement";
-          if (!supportsContextualExpansion) continue;
-          if (page < pageStart || page > pageEnd) continue;
-          for (let current = pageStart; current <= pageEnd; current += 1) {
-            expanded.add(current);
-          }
-        }
-      }
-      return [...expanded].sort((a, b) => a - b);
-    };
-    const tasks = [...extractorPages.entries()].flatMap(
-      ([extractorName, pages]) => groupContiguousPages(expandPagesToFormRanges(extractorName, pages)).map(({ startPage, endPage }) => ({
-        extractorName,
-        startPage,
-        endPage,
-        description: `Page-mapped ${extractorName} extraction for pages ${startPage}-${endPage}`
-      }))
-    ).sort((a, b) => a.startPage - b.startPage || a.extractorName.localeCompare(b.extractorName));
-    return {
-      tasks,
-      pageMap: [...extractorPages.entries()].map(([section, pages]) => ({
-        section,
-        pages: `pages ${[...new Set(pages)].sort((a, b) => a - b).join(", ")}`
-      }))
-    };
+    if (extractorPages.size === 0) return "No page assignments available.";
+    return [...extractorPages.entries()].map(([extractorName, pages]) => `${extractorName}: ${pages.length} page(s), pages ${pages.join(", ")}`).join("\n");
   }
   async function extract(pdfInput, documentId, options) {
     const id = documentId ?? `doc-${Date.now()}`;
@@ -5900,7 +6813,8 @@ function createExtractor(config) {
     const pipelineCtx = createPipelineContext({
       id,
       onSave: onCheckpointSave,
-      resumeFrom: options?.resumeFrom
+      resumeFrom: options?.resumeFrom,
+      phaseOrder: ["classify", "form_inventory", "page_map", "plan", "extract", "resolve_referential", "review", "assemble"]
     });
     const resumed = pipelineCtx.getCheckpoint()?.state;
     if (resumed?.memory) {
@@ -6068,40 +6982,18 @@ function createExtractor(config) {
       const extractorResults = await Promise.all(
         tasks.map(
           (task) => limit(async () => {
-            const ext = getExtractor(task.extractorName);
-            if (!ext) {
-              await log?.(`Unknown extractor: ${task.extractorName}, skipping`);
-              return null;
-            }
             onProgress?.(`Extracting ${task.extractorName} (pages ${task.startPage}-${task.endPage})...`);
-            try {
-              const result = await runExtractor({
-                name: task.extractorName,
-                prompt: ext.buildPrompt(),
-                schema: ext.schema,
-                pdfInput,
-                startPage: task.startPage,
-                endPage: task.endPage,
-                generateObject,
-                convertPdfToImages,
-                maxTokens: ext.maxTokens ?? 4096,
-                providerOptions
-              });
-              trackUsage(result.usage);
-              return result;
-            } catch (error) {
-              await log?.(`Extractor ${task.extractorName} failed: ${error}`);
-              return null;
-            }
+            return runFocusedExtractorTask(task, pdfInput, memory);
           })
         )
       );
-      for (const result of extractorResults) {
+      for (const result of extractorResults.flatMap((item) => Array.isArray(item) ? item : item ? [item] : [])) {
         if (result) {
           mergeMemoryResult(result.name, result.data, memory);
         }
       }
-      {
+      const planIncludesSupplementary = tasks.some((task) => task.extractorName === "supplementary");
+      if (!planIncludesSupplementary && hasSupplementaryExtractionSignal(pageAssignments, formInventory, memory)) {
         onProgress?.("Extracting supplementary retrieval facts...");
         try {
           const alreadyExtractedSummary = buildAlreadyExtractedSummary(memory);
@@ -6175,7 +7067,7 @@ function createExtractor(config) {
         const reviewResponse = await safeGenerateObject(
           generateObject,
           {
-            prompt: buildReviewPrompt(template.required, extractedKeys, extractionSummary, pageMapSummary),
+            prompt: buildReviewPrompt(template.required, extractedKeys, extractionSummary, pageMapSummary, extractorCatalog),
             schema: ReviewResultSchema,
             maxTokens: 1536,
             providerOptions: await buildPdfProviderOptions(pdfInput, providerOptions)
@@ -6199,31 +7091,11 @@ function createExtractor(config) {
         const followUpResults = await Promise.all(
           reviewResponse.object.additionalTasks.map(
             (task) => limit(async () => {
-              const ext = getExtractor(task.extractorName);
-              if (!ext) return null;
-              try {
-                const result = await runExtractor({
-                  name: task.extractorName,
-                  prompt: ext.buildPrompt(),
-                  schema: ext.schema,
-                  pdfInput,
-                  startPage: task.startPage,
-                  endPage: task.endPage,
-                  generateObject,
-                  convertPdfToImages,
-                  maxTokens: ext.maxTokens ?? 4096,
-                  providerOptions
-                });
-                trackUsage(result.usage);
-                return result;
-              } catch (error) {
-                await log?.(`Follow-up extractor ${task.extractorName} failed: ${error}`);
-                return null;
-              }
+              return runFocusedExtractorTask(task, pdfInput, memory);
             })
           )
         );
-        for (const result of followUpResults) {
+        for (const result of followUpResults.flatMap((item) => Array.isArray(item) ? item : item ? [item] : [])) {
           if (result) {
             mergeMemoryResult(result.name, result.data, memory);
           }
@@ -6539,8 +7411,8 @@ Respond with JSON only:
 }`;
 
 // src/schemas/application.ts
-import { z as z36 } from "zod";
-var FieldTypeSchema = z36.enum([
+import { z as z38 } from "zod";
+var FieldTypeSchema = z38.enum([
   "text",
   "numeric",
   "currency",
@@ -6549,131 +7421,131 @@ var FieldTypeSchema = z36.enum([
   "table",
   "declaration"
 ]);
-var ApplicationFieldSchema = z36.object({
-  id: z36.string(),
-  label: z36.string(),
-  section: z36.string(),
+var ApplicationFieldSchema = z38.object({
+  id: z38.string(),
+  label: z38.string(),
+  section: z38.string(),
   fieldType: FieldTypeSchema,
-  required: z36.boolean(),
-  options: z36.array(z36.string()).optional(),
-  columns: z36.array(z36.string()).optional(),
-  requiresExplanationIfYes: z36.boolean().optional(),
-  condition: z36.object({
-    dependsOn: z36.string(),
-    whenValue: z36.string()
+  required: z38.boolean(),
+  options: z38.array(z38.string()).optional(),
+  columns: z38.array(z38.string()).optional(),
+  requiresExplanationIfYes: z38.boolean().optional(),
+  condition: z38.object({
+    dependsOn: z38.string(),
+    whenValue: z38.string()
   }).optional(),
-  value: z36.string().optional(),
-  source: z36.string().optional().describe("Where the value came from: auto-fill, user, lookup"),
-  confidence: z36.enum(["confirmed", "high", "medium", "low"]).optional()
-});
-var ApplicationClassifyResultSchema = z36.object({
-  isApplication: z36.boolean(),
-  confidence: z36.number().min(0).max(1),
-  applicationType: z36.string().nullable()
-});
-var FieldExtractionResultSchema = z36.object({
-  fields: z36.array(ApplicationFieldSchema)
-});
-var AutoFillMatchSchema = z36.object({
-  fieldId: z36.string(),
-  value: z36.string(),
-  confidence: z36.enum(["confirmed"]),
-  contextKey: z36.string()
-});
-var AutoFillResultSchema = z36.object({
-  matches: z36.array(AutoFillMatchSchema)
-});
-var QuestionBatchResultSchema = z36.object({
-  batches: z36.array(z36.array(z36.string()).describe("Array of field IDs in this batch"))
-});
-var LookupRequestSchema = z36.object({
-  type: z36.string().describe("Type of lookup: 'records', 'website', 'policy'"),
-  description: z36.string(),
-  url: z36.string().optional(),
-  targetFieldIds: z36.array(z36.string())
-});
-var ReplyIntentSchema = z36.object({
-  primaryIntent: z36.enum(["answers_only", "question", "lookup_request", "mixed"]),
-  hasAnswers: z36.boolean(),
-  questionText: z36.string().optional(),
-  questionFieldIds: z36.array(z36.string()).optional(),
-  lookupRequests: z36.array(LookupRequestSchema).optional()
-});
-var ParsedAnswerSchema = z36.object({
-  fieldId: z36.string(),
-  value: z36.string(),
-  explanation: z36.string().optional()
-});
-var AnswerParsingResultSchema = z36.object({
-  answers: z36.array(ParsedAnswerSchema),
-  unanswered: z36.array(z36.string()).describe("Field IDs that were not answered")
-});
-var LookupFillSchema = z36.object({
-  fieldId: z36.string(),
-  value: z36.string(),
-  source: z36.string().describe("Specific citable reference, e.g. 'GL Policy #POL-12345 (Hartford)'")
-});
-var LookupFillResultSchema = z36.object({
-  fills: z36.array(LookupFillSchema),
-  unfillable: z36.array(z36.string()),
-  explanation: z36.string().optional()
-});
-var FlatPdfPlacementSchema = z36.object({
-  fieldId: z36.string(),
-  page: z36.number(),
-  x: z36.number().describe("Percentage from left edge (0-100)"),
-  y: z36.number().describe("Percentage from top edge (0-100)"),
-  text: z36.string(),
-  fontSize: z36.number().optional(),
-  isCheckmark: z36.boolean().optional()
-});
-var AcroFormMappingSchema = z36.object({
-  fieldId: z36.string(),
-  acroFormName: z36.string(),
-  value: z36.string()
-});
-var QualityGateStatusSchema = z36.enum(["passed", "warning", "failed"]);
-var QualitySeveritySchema = z36.enum(["info", "warning", "blocking"]);
-var ApplicationQualityIssueSchema = z36.object({
-  code: z36.string(),
+  value: z38.string().optional(),
+  source: z38.string().optional().describe("Where the value came from: auto-fill, user, lookup"),
+  confidence: z38.enum(["confirmed", "high", "medium", "low"]).optional()
+});
+var ApplicationClassifyResultSchema = z38.object({
+  isApplication: z38.boolean(),
+  confidence: z38.number().min(0).max(1),
+  applicationType: z38.string().nullable()
+});
+var FieldExtractionResultSchema = z38.object({
+  fields: z38.array(ApplicationFieldSchema)
+});
+var AutoFillMatchSchema = z38.object({
+  fieldId: z38.string(),
+  value: z38.string(),
+  confidence: z38.enum(["confirmed"]),
+  contextKey: z38.string()
+});
+var AutoFillResultSchema = z38.object({
+  matches: z38.array(AutoFillMatchSchema)
+});
+var QuestionBatchResultSchema = z38.object({
+  batches: z38.array(z38.array(z38.string()).describe("Array of field IDs in this batch"))
+});
+var LookupRequestSchema = z38.object({
+  type: z38.string().describe("Type of lookup: 'records', 'website', 'policy'"),
+  description: z38.string(),
+  url: z38.string().optional(),
+  targetFieldIds: z38.array(z38.string())
+});
+var ReplyIntentSchema = z38.object({
+  primaryIntent: z38.enum(["answers_only", "question", "lookup_request", "mixed"]),
+  hasAnswers: z38.boolean(),
+  questionText: z38.string().optional(),
+  questionFieldIds: z38.array(z38.string()).optional(),
+  lookupRequests: z38.array(LookupRequestSchema).optional()
+});
+var ParsedAnswerSchema = z38.object({
+  fieldId: z38.string(),
+  value: z38.string(),
+  explanation: z38.string().optional()
+});
+var AnswerParsingResultSchema = z38.object({
+  answers: z38.array(ParsedAnswerSchema),
+  unanswered: z38.array(z38.string()).describe("Field IDs that were not answered")
+});
+var LookupFillSchema = z38.object({
+  fieldId: z38.string(),
+  value: z38.string(),
+  source: z38.string().describe("Specific citable reference, e.g. 'GL Policy #POL-12345 (Hartford)'")
+});
+var LookupFillResultSchema = z38.object({
+  fills: z38.array(LookupFillSchema),
+  unfillable: z38.array(z38.string()),
+  explanation: z38.string().optional()
+});
+var FlatPdfPlacementSchema = z38.object({
+  fieldId: z38.string(),
+  page: z38.number(),
+  x: z38.number().describe("Percentage from left edge (0-100)"),
+  y: z38.number().describe("Percentage from top edge (0-100)"),
+  text: z38.string(),
+  fontSize: z38.number().optional(),
+  isCheckmark: z38.boolean().optional()
+});
+var AcroFormMappingSchema = z38.object({
+  fieldId: z38.string(),
+  acroFormName: z38.string(),
+  value: z38.string()
+});
+var QualityGateStatusSchema = z38.enum(["passed", "warning", "failed"]);
+var QualitySeveritySchema = z38.enum(["info", "warning", "blocking"]);
+var ApplicationQualityIssueSchema = z38.object({
+  code: z38.string(),
   severity: QualitySeveritySchema,
-  message: z36.string(),
-  fieldId: z36.string().optional()
+  message: z38.string(),
+  fieldId: z38.string().optional()
 });
-var ApplicationQualityRoundSchema = z36.object({
-  round: z36.number(),
-  kind: z36.string(),
+var ApplicationQualityRoundSchema = z38.object({
+  round: z38.number(),
+  kind: z38.string(),
   status: QualityGateStatusSchema,
-  summary: z36.string().optional()
+  summary: z38.string().optional()
 });
-var ApplicationQualityArtifactSchema = z36.object({
-  kind: z36.string(),
-  label: z36.string().optional(),
-  itemCount: z36.number().optional()
+var ApplicationQualityArtifactSchema = z38.object({
+  kind: z38.string(),
+  label: z38.string().optional(),
+  itemCount: z38.number().optional()
 });
-var ApplicationEmailReviewSchema = z36.object({
-  issues: z36.array(ApplicationQualityIssueSchema),
+var ApplicationEmailReviewSchema = z38.object({
+  issues: z38.array(ApplicationQualityIssueSchema),
   qualityGateStatus: QualityGateStatusSchema
 });
-var ApplicationQualityReportSchema = z36.object({
-  issues: z36.array(ApplicationQualityIssueSchema),
-  rounds: z36.array(ApplicationQualityRoundSchema).optional(),
-  artifacts: z36.array(ApplicationQualityArtifactSchema).optional(),
+var ApplicationQualityReportSchema = z38.object({
+  issues: z38.array(ApplicationQualityIssueSchema),
+  rounds: z38.array(ApplicationQualityRoundSchema).optional(),
+  artifacts: z38.array(ApplicationQualityArtifactSchema).optional(),
   emailReview: ApplicationEmailReviewSchema.optional(),
   qualityGateStatus: QualityGateStatusSchema
 });
-var ApplicationStateSchema = z36.object({
-  id: z36.string(),
-  pdfBase64: z36.string().optional().describe("Original PDF, omitted after extraction"),
-  title: z36.string().optional(),
-  applicationType: z36.string().nullable().optional(),
-  fields: z36.array(ApplicationFieldSchema),
-  batches: z36.array(z36.array(z36.string())).optional(),
-  currentBatchIndex: z36.number().default(0),
+var ApplicationStateSchema = z38.object({
+  id: z38.string(),
+  pdfBase64: z38.string().optional().describe("Original PDF, omitted after extraction"),
+  title: z38.string().optional(),
+  applicationType: z38.string().nullable().optional(),
+  fields: z38.array(ApplicationFieldSchema),
+  batches: z38.array(z38.array(z38.string())).optional(),
+  currentBatchIndex: z38.number().default(0),
   qualityReport: ApplicationQualityReportSchema.optional(),
-  status: z36.enum(["classifying", "extracting", "auto_filling", "batching", "collecting", "confirming", "mapping", "complete"]),
-  createdAt: z36.number(),
-  updatedAt: z36.number()
+  status: z38.enum(["classifying", "extracting", "auto_filling", "batching", "collecting", "confirming", "mapping", "complete"]),
+  createdAt: z38.number(),
+  updatedAt: z38.number()
 });
 
 // src/application/agents/classifier.ts
@@ -7262,6 +8134,70 @@ function reviewBatchEmail(text, batchFields) {
   };
 }
 
+// src/application/workflow.ts
+var MAX_DOCUMENT_SEARCH_FIELDS = 5;
+var LOW_VALUE_FIELD_RATIO_LIMIT = 0.6;
+function planApplicationWorkflow(input) {
+  const unfilledFields = input.fields.filter(isUnfilled);
+  const documentSearchFields = planDocumentSearchFields(
+    unfilledFields,
+    input.hasDocumentStore && input.hasMemoryStore
+  );
+  return {
+    runBackfill: input.hasBackfillProvider && unfilledFields.length > 0,
+    runContextAutoFill: input.orgContextCount > 0 && unfilledFields.length > 0,
+    documentSearchFields,
+    runBatching: unfilledFields.length > 0,
+    unfilledFields
+  };
+}
+function planReplyActions(input) {
+  const hasCurrentFields = input.currentBatchFields.length > 0;
+  const nextBatchNeedsAnswers = (input.nextBatchFields ?? []).some(isUnfilled);
+  const hasLookupRequests = (input.intent.lookupRequests?.length ?? 0) > 0;
+  return {
+    parseAnswers: input.intent.hasAnswers && hasCurrentFields,
+    runLookup: hasLookupRequests && input.hasDocumentStore,
+    answerQuestion: Boolean(input.intent.questionText) && (input.intent.primaryIntent === "question" || input.intent.primaryIntent === "mixed"),
+    advanceBatch: hasCurrentFields && input.currentBatchFields.every((field) => !isUnfilled(field)),
+    generateNextEmail: nextBatchNeedsAnswers
+  };
+}
+function planDocumentSearchFields(unfilledFields, hasStores) {
+  if (!hasStores || unfilledFields.length === 0) return [];
+  const searchableFields = unfilledFields.filter(isHighValueLookupField);
+  if (searchableFields.length === 0) return [];
+  const lowValueRatio = 1 - searchableFields.length / unfilledFields.length;
+  if (unfilledFields.length > MAX_DOCUMENT_SEARCH_FIELDS && lowValueRatio > LOW_VALUE_FIELD_RATIO_LIMIT) {
+    return [];
+  }
+  return searchableFields.slice(0, MAX_DOCUMENT_SEARCH_FIELDS);
+}
+function isUnfilled(field) {
+  return field.value === void 0 || field.value.trim() === "";
+}
+function isHighValueLookupField(field) {
+  const text = `${field.section} ${field.label}`.toLowerCase();
+  if (field.required) return true;
+  return [
+    "carrier",
+    "policy",
+    "premium",
+    "limit",
+    "deductible",
+    "insured",
+    "address",
+    "revenue",
+    "payroll",
+    "effective",
+    "expiration",
+    "coverage",
+    "class code",
+    "fein",
+    "entity"
+  ].some((term) => text.includes(term));
+}
+
 // src/application/coordinator.ts
 function createApplicationPipeline(config) {
   const {
@@ -7360,27 +8296,37 @@ function createApplicationPipeline(config) {
     state.updatedAt = Date.now();
     await applicationStore?.save(state);
     onProgress?.(`Auto-filling ${fields.length} fields...`);
-    const fillTasks = [];
-    if (backfillProvider) {
-      fillTasks.push(
-        (async () => {
-          try {
-            const priorAnswers = await backfillFromPriorAnswers(fields, backfillProvider);
-            for (const pa of priorAnswers) {
-              const field = state.fields.find((f) => f.id === pa.fieldId);
-              if (field && !field.value && pa.relevance > 0.8) {
-                field.value = pa.value;
-                field.source = `backfill: ${pa.source}`;
-                field.confidence = "high";
-              }
-            }
-          } catch (e) {
-            await log?.(`Backfill failed: ${e}`);
+    let workflowPlan = planApplicationWorkflow({
+      fields: state.fields,
+      hasBackfillProvider: Boolean(backfillProvider),
+      orgContextCount: orgContext.length,
+      hasDocumentStore: Boolean(documentStore),
+      hasMemoryStore: Boolean(memoryStore)
+    });
+    if (workflowPlan.runBackfill && backfillProvider) {
+      try {
+        const priorAnswers = await backfillFromPriorAnswers(state.fields, backfillProvider);
+        for (const pa of priorAnswers) {
+          const field = state.fields.find((f) => f.id === pa.fieldId);
+          if (field && !field.value && pa.relevance > 0.8) {
+            field.value = pa.value;
+            field.source = `backfill: ${pa.source}`;
+            field.confidence = "high";
           }
-        })()
-      );
+        }
+      } catch (e) {
+        await log?.(`Backfill failed: ${e}`);
+      }
     }
-    if (orgContext.length > 0) {
+    workflowPlan = planApplicationWorkflow({
+      fields: state.fields,
+      hasBackfillProvider: false,
+      orgContextCount: orgContext.length,
+      hasDocumentStore: Boolean(documentStore),
+      hasMemoryStore: Boolean(memoryStore)
+    });
+    const fillTasks = [];
+    if (workflowPlan.runContextAutoFill) {
       fillTasks.push(
         limit(async () => {
           const unfilledFields2 = state.fields.filter((f) => !f.value);
@@ -7407,18 +8353,13 @@ function createApplicationPipeline(config) {
         })
       );
     }
-    if (documentStore && memoryStore) {
+    if (workflowPlan.documentSearchFields.length > 0 && memoryStore) {
       fillTasks.push(
         (async () => {
           try {
-            const unfilledFields2 = state.fields.filter((f) => !f.value);
-            const searchPromises = unfilledFields2.slice(0, 10).map(
+            const searchPromises = workflowPlan.documentSearchFields.map(
               (f) => limit(async () => {
-                const chunks = await memoryStore.search(f.label, { limit: 3 });
-                for (const chunk of chunks) {
-                  if (!state.fields.find((sf) => sf.id === f.id)?.value) {
-                  }
-                }
+                await memoryStore.search(f.label, { limit: 3 });
               })
             );
             await Promise.all(searchPromises);
@@ -7431,8 +8372,15 @@ function createApplicationPipeline(config) {
     await Promise.all(fillTasks);
     state.updatedAt = Date.now();
     await applicationStore?.save(state);
-    const unfilledFields = state.fields.filter((f) => !f.value);
-    if (unfilledFields.length > 0) {
+    workflowPlan = planApplicationWorkflow({
+      fields: state.fields,
+      hasBackfillProvider: false,
+      orgContextCount: 0,
+      hasDocumentStore: false,
+      hasMemoryStore: false
+    });
+    const unfilledFields = workflowPlan.unfilledFields;
+    if (workflowPlan.runBatching) {
       onProgress?.(`Batching ${unfilledFields.length} remaining questions...`);
       state.status = "batching";
       try {
@@ -7499,7 +8447,12 @@ function createApplicationPipeline(config) {
     }
     let fieldsFilled = 0;
     let responseText;
-    if (intent.hasAnswers) {
+    let replyPlan = planReplyActions({
+      intent,
+      currentBatchFields,
+      hasDocumentStore: Boolean(documentStore)
+    });
+    if (replyPlan.parseAnswers) {
       onProgress?.("Parsing answers...");
       try {
         const { result: parseResult, usage: parseUsage } = await parseAnswers(
@@ -7522,7 +8475,7 @@ function createApplicationPipeline(config) {
         await log?.(`Answer parsing failed: ${error instanceof Error ? error.message : String(error)}`);
       }
     }
-    if (intent.lookupRequests?.length) {
+    if (replyPlan.runLookup && intent.lookupRequests?.length) {
       onProgress?.("Processing lookup requests...");
       let availableData = "";
       if (documentStore) {
@@ -7563,64 +8516,78 @@ function createApplicationPipeline(config) {
         }
       }
     }
-    if (intent.primaryIntent === "question" || intent.primaryIntent === "mixed") {
-      if (intent.questionText) {
-        try {
-          const { text, usage } = await generateText({
-            prompt: `The user is filling out an insurance application and asked: "${intent.questionText}"
+    if (replyPlan.answerQuestion && intent.questionText) {
+      try {
+        const { text, usage } = await generateText({
+          prompt: `The user is filling out an insurance application and asked: "${intent.questionText}"
 
 Provide a brief, helpful explanation (2-3 sentences). End with "Just reply with the answer when you're ready and I'll fill it in."`,
-            maxTokens: 512,
-            providerOptions
-          });
-          trackUsage(usage);
-          responseText = text;
-        } catch (error) {
-          await log?.(`Question response generation failed: ${error instanceof Error ? error.message : String(error)}`);
-          responseText = `I wasn't able to generate an explanation for your question. Could you rephrase it, or just provide the answer directly?`;
-        }
+          maxTokens: 512,
+          providerOptions
+        });
+        trackUsage(usage);
+        responseText = text;
+      } catch (error) {
+        await log?.(`Question response generation failed: ${error instanceof Error ? error.message : String(error)}`);
+        responseText = `I wasn't able to generate an explanation for your question. Could you rephrase it, or just provide the answer directly?`;
       }
     }
     const currentBatchComplete = currentBatchFieldIds.every(
       (fid) => state.fields.find((f) => f.id === fid)?.value
     );
-    if (currentBatchComplete && state.batches) {
-      if (state.currentBatchIndex < state.batches.length - 1) {
-        state.currentBatchIndex++;
-        const nextBatchFieldIds = state.batches[state.currentBatchIndex];
-        const nextBatchFields = state.fields.filter(
-          (f) => nextBatchFieldIds.includes(f.id)
-        );
+    let nextBatchIndex;
+    let nextBatchFields;
+    if (state.batches) {
+      for (let index = state.currentBatchIndex + 1; index < state.batches.length; index++) {
+        const candidateFields = state.fields.filter((f) => state.batches[index].includes(f.id));
+        if (candidateFields.some((f) => !f.value)) {
+          nextBatchIndex = index;
+          nextBatchFields = candidateFields;
+          break;
+        }
+      }
+    }
+    replyPlan = planReplyActions({
+      intent,
+      currentBatchFields,
+      nextBatchFields,
+      hasDocumentStore: Boolean(documentStore)
+    });
+    if (currentBatchComplete && replyPlan.advanceBatch && state.batches) {
+      if (nextBatchIndex !== void 0 && nextBatchFields) {
+        state.currentBatchIndex = nextBatchIndex;
         const filledCount = state.fields.filter((f) => f.value).length;
-        try {
-          const { text: emailText, usage: emailUsage } = await generateBatchEmail(
-            nextBatchFields,
-            state.currentBatchIndex,
-            state.batches.length,
-            {
-              appTitle: state.title,
-              totalFieldCount: state.fields.length,
-              filledFieldCount: filledCount,
-              companyName: context?.companyName
-            },
-            generateText,
-            providerOptions
-          );
-          trackUsage(emailUsage);
-          const emailReview = reviewBatchEmail(emailText, nextBatchFields);
-          state.qualityReport = {
-            ...buildApplicationQualityReport(state),
-            emailReview
-          };
-          if (!responseText) {
-            responseText = emailText;
-          } else {
-            responseText += `
+        if (replyPlan.generateNextEmail) {
+          try {
+            const { text: emailText, usage: emailUsage } = await generateBatchEmail(
+              nextBatchFields,
+              state.currentBatchIndex,
+              state.batches.length,
+              {
+                appTitle: state.title,
+                totalFieldCount: state.fields.length,
+                filledFieldCount: filledCount,
+                companyName: context?.companyName
+              },
+              generateText,
+              providerOptions
+            );
+            trackUsage(emailUsage);
+            const emailReview = reviewBatchEmail(emailText, nextBatchFields);
+            state.qualityReport = {
+              ...buildApplicationQualityReport(state),
+              emailReview
+            };
+            if (!responseText) {
+              responseText = emailText;
+            } else {
+              responseText += `
 
 ${emailText}`;
+            }
+          } catch (error) {
+            await log?.(`Batch email generation failed: ${error instanceof Error ? error.message : String(error)}`);
           }
-        } catch (error) {
-          await log?.(`Batch email generation failed: ${error instanceof Error ? error.message : String(error)}`);
         }
       } else {
         state.status = "confirming";
@@ -7779,7 +8746,7 @@ INSTRUCTIONS:
    - If the user's attachment already contains critical facts, still request chunk/document lookup when policy or quote details should be cross-checked against stored records
 
 CHUNK TYPES (for chunkTypes filter):
-carrier_info, named_insured, coverage, endorsement, exclusion, condition, section, declaration, loss_history, premium, supplementary
+carrier_info, named_insured, coverage, covered_reason, definition, endorsement, exclusion, condition, section, declaration, loss_history, premium, supplementary
 
 Respond with the structured classification.`;
 }
@@ -7810,91 +8777,91 @@ Respond with the final answer, deduplicated citations array, overall confidence
 }
 
 // src/schemas/query.ts
-import { z as z37 } from "zod";
-var QueryIntentSchema = z37.enum([
+import { z as z39 } from "zod";
+var QueryIntentSchema = z39.enum([
   "policy_question",
   "coverage_comparison",
   "document_search",
   "claims_inquiry",
   "general_knowledge"
 ]);
-var QueryAttachmentKindSchema = z37.enum(["image", "pdf", "text"]);
-var QueryAttachmentSchema = z37.object({
-  id: z37.string().optional().describe("Optional stable attachment ID from the caller"),
+var QueryAttachmentKindSchema = z39.enum(["image", "pdf", "text"]);
+var QueryAttachmentSchema = z39.object({
+  id: z39.string().optional().describe("Optional stable attachment ID from the caller"),
   kind: QueryAttachmentKindSchema,
-  name: z37.string().optional().describe("Original filename or user-facing label"),
-  mimeType: z37.string().optional().describe("MIME type such as image/jpeg or application/pdf"),
-  base64: z37.string().optional().describe("Base64-encoded file content for image/pdf attachments"),
-  text: z37.string().optional().describe("Plain-text attachment content when available"),
-  description: z37.string().optional().describe("Caller-provided description of the attachment")
-});
-var SubQuestionSchema = z37.object({
-  question: z37.string().describe("Atomic sub-question to retrieve and answer independently"),
+  name: z39.string().optional().describe("Original filename or user-facing label"),
+  mimeType: z39.string().optional().describe("MIME type such as image/jpeg or application/pdf"),
+  base64: z39.string().optional().describe("Base64-encoded file content for image/pdf attachments"),
+  text: z39.string().optional().describe("Plain-text attachment content when available"),
+  description: z39.string().optional().describe("Caller-provided description of the attachment")
+});
+var SubQuestionSchema = z39.object({
+  question: z39.string().describe("Atomic sub-question to retrieve and answer independently"),
   intent: QueryIntentSchema,
-  chunkTypes: z37.array(z37.string()).optional().describe("Chunk types to filter retrieval (e.g. coverage, endorsement, declaration)"),
-  documentFilters: z37.object({
-    type: z37.enum(["policy", "quote"]).optional(),
-    carrier: z37.string().optional(),
-    insuredName: z37.string().optional(),
-    policyNumber: z37.string().optional(),
-    quoteNumber: z37.string().optional(),
-    policyTypes: z37.array(PolicyTypeSchema).optional().describe("Filter by policy type (e.g. homeowners_ho3, renters_ho4, pet) to avoid mixing up similar policies")
+  chunkTypes: z39.array(z39.string()).optional().describe("Chunk types to filter retrieval (e.g. coverage, endorsement, declaration)"),
+  documentFilters: z39.object({
+    type: z39.enum(["policy", "quote"]).optional(),
+    carrier: z39.string().optional(),
+    insuredName: z39.string().optional(),
+    policyNumber: z39.string().optional(),
+    quoteNumber: z39.string().optional(),
+    policyTypes: z39.array(PolicyTypeSchema).optional().describe("Filter by policy type (e.g. homeowners_ho3, renters_ho4, pet) to avoid mixing up similar policies")
   }).optional().describe("Structured filters to narrow document lookup")
 });
-var QueryClassifyResultSchema = z37.object({
+var QueryClassifyResultSchema = z39.object({
   intent: QueryIntentSchema,
-  subQuestions: z37.array(SubQuestionSchema).min(1).describe("Decomposed atomic sub-questions"),
-  requiresDocumentLookup: z37.boolean().describe("Whether structured document lookup is needed"),
-  requiresChunkSearch: z37.boolean().describe("Whether semantic chunk search is needed"),
-  requiresConversationHistory: z37.boolean().describe("Whether conversation history is relevant")
-});
-var EvidenceItemSchema = z37.object({
-  source: z37.enum(["chunk", "document", "conversation", "attachment"]),
-  chunkId: z37.string().optional(),
-  documentId: z37.string().optional(),
-  turnId: z37.string().optional(),
-  attachmentId: z37.string().optional(),
-  text: z37.string().describe("Text excerpt from the source"),
-  relevance: z37.number().min(0).max(1),
-  metadata: z37.array(z37.object({ key: z37.string(), value: z37.string() })).optional()
-});
-var AttachmentInterpretationSchema = z37.object({
-  summary: z37.string().describe("Concise summary of what the attachment shows or contains"),
-  extractedFacts: z37.array(z37.string()).describe("Specific observable or document facts grounded in the attachment"),
-  recommendedFocus: z37.array(z37.string()).describe("Important details to incorporate when answering follow-up questions"),
-  confidence: z37.number().min(0).max(1)
-});
-var RetrievalResultSchema = z37.object({
-  subQuestion: z37.string(),
-  evidence: z37.array(EvidenceItemSchema)
-});
-var CitationSchema = z37.object({
-  index: z37.number().describe("Citation number [1], [2], etc."),
-  chunkId: z37.string().describe("Source chunk ID, e.g. doc-123:coverage:2"),
-  documentId: z37.string(),
-  documentType: z37.enum(["policy", "quote"]).optional(),
-  field: z37.string().optional().describe("Specific field path, e.g. coverages[0].deductible"),
-  quote: z37.string().describe("Exact text from source that supports the claim"),
-  relevance: z37.number().min(0).max(1)
-});
-var SubAnswerSchema = z37.object({
-  subQuestion: z37.string(),
-  answer: z37.string(),
-  citations: z37.array(CitationSchema),
-  confidence: z37.number().min(0).max(1),
-  needsMoreContext: z37.boolean().describe("True if evidence was insufficient to answer fully")
-});
-var VerifyResultSchema = z37.object({
-  approved: z37.boolean().describe("Whether all sub-answers are adequately grounded"),
-  issues: z37.array(z37.string()).describe("Specific grounding or consistency issues found"),
-  retrySubQuestions: z37.array(z37.string()).optional().describe("Sub-questions that need additional retrieval or re-reasoning")
-});
-var QueryResultSchema = z37.object({
-  answer: z37.string(),
-  citations: z37.array(CitationSchema),
+  subQuestions: z39.array(SubQuestionSchema).min(1).describe("Decomposed atomic sub-questions"),
+  requiresDocumentLookup: z39.boolean().describe("Whether structured document lookup is needed"),
+  requiresChunkSearch: z39.boolean().describe("Whether semantic chunk search is needed"),
+  requiresConversationHistory: z39.boolean().describe("Whether conversation history is relevant")
+});
+var EvidenceItemSchema = z39.object({
+  source: z39.enum(["chunk", "document", "conversation", "attachment"]),
+  chunkId: z39.string().optional(),
+  documentId: z39.string().optional(),
+  turnId: z39.string().optional(),
+  attachmentId: z39.string().optional(),
+  text: z39.string().describe("Text excerpt from the source"),
+  relevance: z39.number().min(0).max(1),
+  metadata: z39.array(z39.object({ key: z39.string(), value: z39.string() })).optional()
+});
+var AttachmentInterpretationSchema = z39.object({
+  summary: z39.string().describe("Concise summary of what the attachment shows or contains"),
+  extractedFacts: z39.array(z39.string()).describe("Specific observable or document facts grounded in the attachment"),
+  recommendedFocus: z39.array(z39.string()).describe("Important details to incorporate when answering follow-up questions"),
+  confidence: z39.number().min(0).max(1)
+});
+var RetrievalResultSchema = z39.object({
+  subQuestion: z39.string(),
+  evidence: z39.array(EvidenceItemSchema)
+});
+var CitationSchema = z39.object({
+  index: z39.number().describe("Citation number [1], [2], etc."),
+  chunkId: z39.string().describe("Source chunk ID, e.g. doc-123:coverage:2"),
+  documentId: z39.string(),
+  documentType: z39.enum(["policy", "quote"]).optional(),
+  field: z39.string().optional().describe("Specific field path, e.g. coverages[0].deductible"),
+  quote: z39.string().describe("Exact text from source that supports the claim"),
+  relevance: z39.number().min(0).max(1)
+});
+var SubAnswerSchema = z39.object({
+  subQuestion: z39.string(),
+  answer: z39.string(),
+  citations: z39.array(CitationSchema),
+  confidence: z39.number().min(0).max(1),
+  needsMoreContext: z39.boolean().describe("True if evidence was insufficient to answer fully")
+});
+var VerifyResultSchema = z39.object({
+  approved: z39.boolean().describe("Whether all sub-answers are adequately grounded"),
+  issues: z39.array(z39.string()).describe("Specific grounding or consistency issues found"),
+  retrySubQuestions: z39.array(z39.string()).optional().describe("Sub-questions that need additional retrieval or re-reasoning")
+});
+var QueryResultSchema = z39.object({
+  answer: z39.string(),
+  citations: z39.array(CitationSchema),
   intent: QueryIntentSchema,
-  confidence: z37.number().min(0).max(1),
-  followUp: z37.string().optional().describe("Suggested follow-up question if applicable")
+  confidence: z39.number().min(0).max(1),
+  followUp: z39.string().optional().describe("Suggested follow-up question if applicable")
 });
 
 // src/query/retriever.ts
@@ -8434,6 +9401,42 @@ ${item.text}`).join("\n\n");
   return { evidence, contextSummary };
 }
 
+// src/query/workflow.ts
+function shouldRetrieveForClassification(classification) {
+  return classification.requiresDocumentLookup || classification.requiresChunkSearch;
+}
+function buildInitialQueryWorkflowPlan(params) {
+  const { classification, attachmentEvidence } = params;
+  const actions = [];
+  const shouldRetrieve = shouldRetrieveForClassification(classification);
+  if (shouldRetrieve) {
+    actions.push({
+      type: "retrieve",
+      subQuestions: classification.subQuestions,
+      reason: "classification requested document or chunk lookup"
+    });
+  }
+  actions.push({
+    type: "reason",
+    subQuestions: classification.subQuestions,
+    reason: shouldRetrieve ? "answer with retrieved evidence and any attachment evidence" : attachmentEvidence.length > 0 ? "answer with attachment evidence only" : "answer without document retrieval"
+  });
+  actions.push(
+    {
+      type: "verify",
+      reason: "check grounding and request targeted retries when needed"
+    },
+    {
+      type: "respond",
+      reason: "compose final response"
+    }
+  );
+  return { actions, shouldRetrieve };
+}
+function getWorkflowAction(plan, type) {
+  return plan.actions.find((action) => action.type === type);
+}
+
 // src/query/coordinator.ts
 function createQueryAgent(config) {
   const {
@@ -8478,29 +9481,37 @@ function createQueryAgent(config) {
     onProgress?.("Classifying query...");
     const classification = await classify(question, conversationId, attachmentContext);
     await pipelineCtx.save("classify", { classification, attachmentEvidence });
-    onProgress?.(`Retrieving evidence for ${classification.subQuestions.length} sub-question(s)...`);
     const retrieverConfig = {
       documentStore,
       memoryStore,
       retrievalLimit,
       log
     };
-    const retrievalResults = await Promise.all(
-      classification.subQuestions.map(
-        (sq) => limit(() => retrieve(sq, conversationId, retrieverConfig))
-      )
-    );
+    const workflowPlan = buildInitialQueryWorkflowPlan({ classification, attachmentEvidence });
+    const retrieveAction = getWorkflowAction(workflowPlan, "retrieve");
+    const reasonAction = getWorkflowAction(workflowPlan, "reason");
+    await pipelineCtx.save("workflow", { classification, attachmentEvidence, workflowPlan });
+    const retrievalResults = retrieveAction ? await (async () => {
+      onProgress?.(`Retrieving evidence for ${retrieveAction.subQuestions.length} sub-question(s)...`);
+      return Promise.all(
+        retrieveAction.subQuestions.map(
+          (sq) => limit(() => retrieve(sq, conversationId, retrieverConfig))
+        )
+      );
+    })() : [];
     const allEvidence = [...attachmentEvidence, ...retrievalResults.flatMap((r) => r.evidence)];
     await pipelineCtx.save("retrieve", { classification, attachmentEvidence, evidence: allEvidence });
     onProgress?.("Reasoning over evidence...");
     const reasonerConfig = { generateObject, providerOptions };
+    const subQuestionsToReason = reasonAction?.subQuestions ?? classification.subQuestions;
     const reasonResults = await Promise.allSettled(
-      classification.subQuestions.map(
-        (sq, i) => limit(async () => {
+      subQuestionsToReason.map(
+        (sq) => limit(async () => {
+          const retrievedEvidence = retrievalResults.find((r) => r.subQuestion === sq.question)?.evidence ?? [];
           const { subAnswer, usage } = await reason(
             sq.question,
             sq.intent,
-            [...attachmentEvidence, ...retrievalResults[i].evidence],
+            [...attachmentEvidence, ...retrievedEvidence],
             reasonerConfig
           );
           trackUsage(usage);
@@ -8514,9 +9525,9 @@ function createQueryAgent(config) {
       if (result.status === "fulfilled") {
         subAnswers.push(result.value);
       } else {
-        await log?.(`Reasoner failed for sub-question "${classification.subQuestions[i].question}": ${result.reason}`);
+        await log?.(`Reasoner failed for sub-question "${subQuestionsToReason[i].question}": ${result.reason}`);
         subAnswers.push({
-          subQuestion: classification.subQuestions[i].question,
+          subQuestion: subQuestionsToReason[i].question,
           answer: "Unable to answer this part of the question due to a processing error.",
           citations: [],
           confidence: 0,
@@ -8899,6 +9910,7 @@ export {
   CoverageSchema,
   CoverageTriggerSchema,
   CoverageValueTypeSchema,
+  CoveredReasonSchema,
   CrimeDeclarationsSchema,
   CyberDeclarationsSchema,
   DEDUCTIBLE_TYPES,
@@ -8911,6 +9923,7 @@ export {
   DeductibleScheduleSchema,
   DeductibleTypeSchema,
   DefenseCostTreatmentSchema,
+  DefinitionSchema,
   DocumentTypeSchema,
   DriverRecordSchema,
   DwellingDetailsSchema,