diff --git a/.env.example b/.env.example
index 9ccb1901..fc51767b 100644
--- a/.env.example
+++ b/.env.example
@@ -349,6 +349,12 @@ AION_SKILL_VIEW_ENFORCE_PROFILE=1
 # o un path assoluto scrivibile — **non** lasciare `/app/data` se l’API non gira nel container.
 AION_DATA_DIR=data
 AION_UPLOAD_MAX_BYTES=52428800
+# Legacy Word (.doc Word 97–2003): convert to .docx on upload via LibreOffice (soffice).
+# Docker: libreoffice-writer-nogui in Dockerfile.backend. Dev Mac: brew install --cask libreoffice
+AION_OFFICE_AUTO_CONVERT_LEGACY_WORD=1
+# Path to soffice if not on PATH (macOS: /Applications/LibreOffice.app/Contents/MacOS/soffice)
+# AION_SOFFICE_PATH=
+# AION_OFFICE_CONVERT_TIMEOUT_SEC=90
 # 1 = embed session images as Haystack ImageContent on the user turn (vision-capable LLM).
 # 0 = legacy: only the text list from _format_attachments_block (default).
 AION_CHAT_MULTIMODAL_ATTACHMENTS=1
@@ -529,6 +535,13 @@ AION_WEB_FETCH_TIMEOUT_SEC=25
 AION_WEB_FETCH_MAX_BYTES=1500000
 # Estrazione pagina (trafilatura/bs4) prima dell'offload — default 24k inline; con offload vedi sotto
 AION_WEB_FETCH_MAX_CHARS=24000
+# Geocoding MCP (OpenStreetMap Nominatim) — geocode_place / reverse_geocode
+# AION_GEOCODING_NOMINATIM_URL=https://nominatim.openstreetmap.org
+# AION_GEOCODING_USER_AGENT=AION-Agent/1.0 (your-contact@example.com)
+# AION_GEOCODING_MIN_INTERVAL_SEC=1.1
+# PDF evidence crop (MCP pdf_evidence_crop on ocr server) — Word report screenshots
+# AION_PDF_EVIDENCE_DPI=200
+# AION_PDF_EVIDENCE_MAX_WHITE_RATIO=0.90
 # Con AION_TOOL_OFFLOAD_ENABLED=1: cap estrazione pagina su disco (default ~min(bytes/2, 250k))
 # AION_WEB_FETCH_OFFLOAD_MAX_CHARS=200000
 # Formato risultati tool web nel contesto LLM: toon (default, -30/60% token) | json
diff --git a/chat-ui/components/chat/ChatWorkspace.tsx b/chat-ui/components/chat/ChatWorkspace.tsx
index e467fd9e..30de4d57 100644
--- a/chat-ui/components/chat/ChatWorkspace.tsx
+++ b/chat-ui/components/chat/ChatWorkspace.tsx
@@ -17,6 +17,7 @@ import { ShimmerText } from "@/components/chat/ShimmerText";
 import Link from "next/link";
 import { AgentModeSelectChip } from "@/components/chat/AgentModeSelectChip";
 import { ChatEmptyState } from "@/components/chat/ChatEmptyState";
+import { CircularUploadProgress } from "@/components/chat/CircularUploadProgress";
 import { ComposerOptionRow } from "@/components/chat/ComposerOptionRow";
 import { ChatDragDrop } from "@/components/chat/ChatDragDrop";
 import { mergeAttachmentRefs } from "@/lib/attachments";
@@ -38,7 +39,6 @@ import {
   waitForChatPrepare,
   type ChatPrepareMcpError,
   sessionDownloadUrl,
-  uploadSessionFiles,
   listSessionUploads,
   fetchConversationHistory,
   fetchStreamStatus,
@@ -60,6 +60,7 @@ import {
   type SessionChart,
 } from "@/lib/api/aion";
 import { useStoredToken, useStoredUserId } from "@/lib/auth/use-stored-auth";
+import { usePendingSessionUploads } from "@/hooks/use-pending-session-uploads";
 import { useT } from "@/lib/i18n/use-t";
 import {
   extractStreamingPlanMarkdown,
@@ -413,6 +414,19 @@ export function ChatWorkspace({ conversationId: initialConversationId }: { conve
   const sidebarOpen = useSidebarOpen();
   const [conversationId, setConversationId] = useState(initialConversationId);
 
+  const {
+    items: pendingUploadItems,
+    queueFiles: queuePendingUploads,
+    removeItem: removePendingUpload,
+    retryItem: retryPendingUpload,
+    clearAll: clearPendingUploads,
+    isUploading: pendingUploadsInProgress,
+    hasUploadErrors: pendingUploadsFailed,
+    completedAttachments: pendingUploadedAttachments,
+  } = usePendingSessionUploads(conversationId, userId, token);
+
+  const sendBlockedByUploads = pendingUploadsInProgress || pendingUploadsFailed;
+
   const [dockTab, setDockTab] = useState<DockTab>("none");
   const [lastActiveTab, setLastActiveTab] = useState<DockTab>("plan");
 
@@ -1278,16 +1292,9 @@ export function ChatWorkspace({ conversationId: initialConversationId }: { conve
     minHeight: COMPOSER_TEXTAREA_MIN,
     maxHeight: composerTextMax,
   });
-  const [pendingFiles, setPendingFiles] = useState<File[]>([]);
-
   const handleFilesDropped = useCallback((files: File[]) => {
-    setPendingFiles((prev) => {
-      const filtered = files.filter(
-        (sf) => !prev.some((pf) => pf.name === sf.name && pf.size === sf.size)
-      );
-      return [...prev, ...filtered];
-    });
-  }, []);
+    queuePendingUploads(files);
+  }, [queuePendingUploads]);
 
   const [streamEpoch, setStreamEpoch] = useState(0);
   const abortRef = useRef<AbortController | null>(null);
@@ -1831,18 +1838,20 @@ export function ChatWorkspace({ conversationId: initialConversationId }: { conve
         opts?.deepResearchModeOverride !== undefined
           ? opts.deepResearchModeOverride
           : effectiveAgentMode === "deep_research";
+      if (pendingUploadsInProgress || pendingUploadsFailed) {
+        return;
+      }
+
       let uidMsg = crypto.randomUUID();
       let aid = crypto.randomUUID();
       setActiveMessageId(aid);
 
-      const hasPendingFiles = pendingFiles.length > 0;
-      const uploads = await uploadSessionFiles(conversationId, userId, pendingFiles, token);
-      setPendingFiles([]);
+      const uploads = [...pendingUploadedAttachments];
+      const hasNewUploads = uploads.length > 0;
+      clearPendingUploads();
       void fetchSessionFiles();
-      // Fetch existing session uploads only when new files were uploaded,
-      // so previous uploads aren't incorrectly attached to the current message.
-      const existing = hasPendingFiles ? await listSessionUploads(conversationId, userId, token) : [];
-      const attachments = hasPendingFiles ? mergeAttachmentRefs(uploads, existing) : [];
+      const existing = hasNewUploads ? await listSessionUploads(conversationId, userId, token) : [];
+      const attachments = hasNewUploads ? mergeAttachmentRefs(uploads, existing) : [];
 
       const userArtifacts: ChatHistoryArtifact[] = uploads.map((a, i) => ({
         id: `att-${i}-${Date.now()}`,
@@ -2245,7 +2254,10 @@ export function ChatWorkspace({ conversationId: initialConversationId }: { conve
       token,
       activeProfileSlug,
       effectiveEffort,
-      pendingFiles,
+      pendingUploadsInProgress,
+      pendingUploadsFailed,
+      pendingUploadedAttachments,
+      clearPendingUploads,
       thinkingEnabled,
       markStreamConversation,
       transcriptStreaming,
@@ -3834,24 +3846,58 @@ export function ChatWorkspace({ conversationId: initialConversationId }: { conve
                   </div>
                 )
               ) : null}
-              {pendingFiles.length > 0 && (
-                <div className="mb-3 flex flex-wrap gap-2">
-                  {pendingFiles.map((f) => (
-                    <span
-                      key={f.name}
-                      className="inline-flex items-center gap-1.5 rounded-full border border-border bg-muted/60 px-3 py-1.5 text-[0.857em] font-medium text-foreground backdrop-blur-sm"
-                    >
-                      {f.name}
-                      <button
-                        type="button"
-                        className="focus-ring rounded-full px-0.5 text-muted-foreground hover:text-destructive transition-colors"
-                        aria-label={t("chat.remove_file", { name: f.name })}
-                        onClick={() => setPendingFiles((prev) => prev.filter((x) => x.name !== f.name))}
+              {pendingUploadItems.length > 0 && (
+                <div className="mb-3 flex flex-wrap gap-2" aria-live="polite">
+                  {pendingUploadItems.map((item) => {
+                    const ringStatus =
+                      item.status === "done"
+                        ? "done"
+                        : item.status === "error"
+                          ? "error"
+                          : "uploading";
+                    const statusLabel =
+                      item.status === "done"
+                        ? t("chat.upload.done")
+                        : item.status === "error"
+                          ? t("chat.upload.failed")
+                          : t("chat.upload.uploading", { progress: item.progress });
+                    return (
+                      <span
+                        key={item.id}
+                        className={cn(
+                          "inline-flex max-w-full items-center gap-2 rounded-full border px-3 py-1.5 text-[0.857em] font-medium backdrop-blur-sm",
+                          item.status === "error"
+                            ? "border-destructive/40 bg-destructive/10 text-destructive"
+                            : "border-border bg-muted/60 text-foreground",
+                        )}
+                        title={statusLabel}
                       >
-                        ×
-                      </button>
-                    </span>
-                  ))}
+                        <CircularUploadProgress
+                          value={item.progress}
+                          status={ringStatus}
+                          size={18}
+                        />
+                        <span className="truncate max-w-[14rem]">{item.file.name}</span>
+                        {item.status === "error" ? (
+                          <button
+                            type="button"
+                            className="focus-ring rounded-full px-1 text-[0.786em] font-semibold hover:underline"
+                            onClick={() => retryPendingUpload(item.id)}
+                          >
+                            {t("chat.upload.retry")}
+                          </button>
+                        ) : null}
+                        <button
+                          type="button"
+                          className="focus-ring rounded-full px-0.5 text-muted-foreground hover:text-destructive transition-colors"
+                          aria-label={t("chat.remove_file", { name: item.file.name })}
+                          onClick={() => removePendingUpload(item.id)}
+                        >
+                          ×
+                        </button>
+                      </span>
+                    );
+                  })}
                 </div>
               )}
               {isProjectRequiredButMissing && (
@@ -3914,7 +3960,7 @@ export function ChatWorkspace({ conversationId: initialConversationId }: { conve
                         handleAgentModeChange(agentMode === "plan" ? "normal" : "plan");
                       } else if (e.key === "Enter" && !e.shiftKey) {
                         e.preventDefault();
-                        void send();
+                        if (!sendBlockedByUploads) void send();
                       }
                     }}
                     placeholder={isProjectRequiredButMissing ? t("chat.project_required.textarea_placeholder") : t("chat.composer_placeholder")}
@@ -3930,12 +3976,7 @@ export function ChatWorkspace({ conversationId: initialConversationId }: { conve
                     className="hidden"
                     onChange={(e) => {
                       const selected = Array.from(e.target.files || []);
-                      setPendingFiles((prev) => {
-                        const filtered = selected.filter(
-                          (sf) => !prev.some((pf) => pf.name === sf.name && pf.size === sf.size)
-                        );
-                        return [...prev, ...filtered];
-                      });
+                      queuePendingUploads(selected);
                       e.target.value = "";
                     }}
                   />
@@ -4492,7 +4533,14 @@ export function ChatWorkspace({ conversationId: initialConversationId }: { conve
                       <button
                         type="button"
                         onClick={() => void send()}
-                        disabled={!input.trim() || isProjectRequiredButMissing}
+                        disabled={
+                          !input.trim() ||
+                          isProjectRequiredButMissing ||
+                          sendBlockedByUploads
+                        }
+                        title={
+                          sendBlockedByUploads ? t("chat.upload.send_blocked") : undefined
+                        }
                         className="focus-ring inline-flex size-8 items-center justify-center rounded-full bg-primary text-primary-foreground transition-all duration-200 hover:scale-105 hover:bg-primary/95 disabled:pointer-events-none disabled:opacity-30"
                       >
                         <Send size={13} aria-hidden />
diff --git a/chat-ui/components/chat/CircularUploadProgress.tsx b/chat-ui/components/chat/CircularUploadProgress.tsx
new file mode 100644
index 00000000..2aab9fbe
--- /dev/null
+++ b/chat-ui/components/chat/CircularUploadProgress.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import { AlertCircle, Check } from "lucide-react";
+
+import { cn } from "@/lib/cn";
+
+export type CircularUploadStatus = "uploading" | "done" | "error";
+
+export function CircularUploadProgress({
+  value,
+  status,
+  size = 20,
+  className,
+}: {
+  value: number;
+  status: CircularUploadStatus;
+  size?: number;
+  className?: string;
+}) {
+  const stroke = 2;
+  const radius = (size - stroke) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const clamped = Math.max(0, Math.min(100, value));
+  const offset = circumference - (clamped / 100) * circumference;
+
+  if (status === "error") {
+    return (
+      <span
+        className={cn("inline-flex shrink-0 items-center justify-center text-destructive", className)}
+        style={{ width: size, height: size }}
+        aria-hidden
+      >
+        <AlertCircle size={size - 4} />
+      </span>
+    );
+  }
+
+  if (status === "done") {
+    return (
+      <span
+        className={cn(
+          "inline-flex shrink-0 items-center justify-center rounded-full bg-emerald-500/15 text-emerald-600 dark:text-emerald-400",
+          className,
+        )}
+        style={{ width: size, height: size }}
+        aria-hidden
+      >
+        <Check size={size - 6} strokeWidth={2.5} />
+      </span>
+    );
+  }
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox={`0 0 ${size} ${size}`}
+      className={cn("shrink-0 -rotate-90", className)}
+      aria-hidden
+    >
+      <circle
+        cx={size / 2}
+        cy={size / 2}
+        r={radius}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={stroke}
+        className="text-muted-foreground/25"
+      />
+      <circle
+        cx={size / 2}
+        cy={size / 2}
+        r={radius}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={stroke}
+        strokeLinecap="round"
+        className="text-primary transition-[stroke-dashoffset] duration-150"
+        strokeDasharray={circumference}
+        strokeDashoffset={offset}
+      />
+    </svg>
+  );
+}
diff --git a/chat-ui/hooks/use-pending-session-uploads.ts b/chat-ui/hooks/use-pending-session-uploads.ts
new file mode 100644
index 00000000..e00840c8
--- /dev/null
+++ b/chat-ui/hooks/use-pending-session-uploads.ts
@@ -0,0 +1,164 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { AttachmentRef } from "@/lib/attachments";
+import { uploadSessionFileWithProgress } from "@/lib/api/aion";
+
+export type PendingUploadStatus = "queued" | "uploading" | "done" | "error";
+
+export type PendingUploadItem = {
+  id: string;
+  file: File;
+  status: PendingUploadStatus;
+  progress: number;
+  attachment?: AttachmentRef;
+  error?: string;
+};
+
+function fileKey(file: File): string {
+  return `${file.name}\0${file.size}`;
+}
+
+export function usePendingSessionUploads(
+  conversationId: string,
+  userId: string,
+  token?: string | null,
+) {
+  const [items, setItems] = useState<PendingUploadItem[]>([]);
+  const abortByIdRef = useRef<Map<string, AbortController>>(new Map());
+  const itemsRef = useRef(items);
+  itemsRef.current = items;
+
+  const abortOne = useCallback((id: string) => {
+    abortByIdRef.current.get(id)?.abort();
+    abortByIdRef.current.delete(id);
+  }, []);
+
+  const abortAll = useCallback(() => {
+    for (const ctrl of abortByIdRef.current.values()) {
+      ctrl.abort();
+    }
+    abortByIdRef.current.clear();
+  }, []);
+
+  useEffect(() => {
+    abortAll();
+    setItems([]);
+  }, [conversationId, abortAll]);
+
+  const startUpload = useCallback(
+    (id: string, file: File) => {
+      abortOne(id);
+      const ctrl = new AbortController();
+      abortByIdRef.current.set(id, ctrl);
+
+      setItems((prev) =>
+        prev.map((it) =>
+          it.id === id
+            ? { ...it, status: "uploading", progress: 0, error: undefined, attachment: undefined }
+            : it,
+        ),
+      );
+
+      void uploadSessionFileWithProgress(conversationId, userId, file, token, {
+        signal: ctrl.signal,
+        onProgress: (pct) => {
+          setItems((prev) =>
+            prev.map((it) => (it.id === id ? { ...it, progress: pct } : it)),
+          );
+        },
+      })
+        .then(({ attachment }) => {
+          abortByIdRef.current.delete(id);
+          setItems((prev) =>
+            prev.map((it) =>
+              it.id === id
+                ? { ...it, status: "done", progress: 100, attachment, error: undefined }
+                : it,
+            ),
+          );
+        })
+        .catch((err: unknown) => {
+          abortByIdRef.current.delete(id);
+          if (err instanceof DOMException && err.name === "AbortError") {
+            return;
+          }
+          const message = err instanceof Error ? err.message : "upload failed";
+          setItems((prev) =>
+            prev.map((it) =>
+              it.id === id ? { ...it, status: "error", error: message } : it,
+            ),
+          );
+        });
+    },
+    [abortOne, conversationId, token, userId],
+  );
+
+  const queueFiles = useCallback(
+    (files: File[]) => {
+      if (!files.length) return;
+      const existing = new Set(itemsRef.current.map((it) => fileKey(it.file)));
+      const toAdd: PendingUploadItem[] = [];
+      for (const file of files) {
+        const key = fileKey(file);
+        if (existing.has(key)) continue;
+        existing.add(key);
+        toAdd.push({
+          id: crypto.randomUUID(),
+          file,
+          status: "queued",
+          progress: 0,
+        });
+      }
+      if (!toAdd.length) return;
+
+      setItems((prev) => [...prev, ...toAdd]);
+      for (const item of toAdd) {
+        startUpload(item.id, item.file);
+      }
+    },
+    [startUpload],
+  );
+
+  const removeItem = useCallback(
+    (id: string) => {
+      abortOne(id);
+      setItems((prev) => prev.filter((it) => it.id !== id));
+    },
+    [abortOne],
+  );
+
+  const retryItem = useCallback(
+    (id: string) => {
+      const row = itemsRef.current.find((it) => it.id === id);
+      if (!row) return;
+      startUpload(id, row.file);
+    },
+    [startUpload],
+  );
+
+  const clearAll = useCallback(() => {
+    abortAll();
+    setItems([]);
+  }, [abortAll]);
+
+  const isUploading = items.some(
+    (it) => it.status === "queued" || it.status === "uploading",
+  );
+  const hasUploadErrors = items.some((it) => it.status === "error");
+  const completedAttachments = items
+    .filter((it) => it.status === "done" && it.attachment)
+    .map((it) => it.attachment!);
+
+  return {
+    items,
+    queueFiles,
+    removeItem,
+    retryItem,
+    clearAll,
+    isUploading,
+    hasUploadErrors,
+    completedAttachments,
+  };
+}
diff --git a/chat-ui/lib/api/aion.ts b/chat-ui/lib/api/aion.ts
index 10bae8a4..32526d9e 100644
--- a/chat-ui/lib/api/aion.ts
+++ b/chat-ui/lib/api/aion.ts
@@ -63,19 +63,109 @@ export async function uploadSessionFiles(sessionId: string, userId: string, file
     body: fd,
   });
   if (!r.ok) return [];
-  const j = (await r.json()) as { files?: Array<Record<string, string>> };
+  const j = (await r.json()) as { files?: Array<Record<string, unknown>> };
   const attachments: AttachmentRef[] = [];
   for (const item of j.files || []) {
     attachments.push({
-      relative_path: item.relative_path,
-      original_relative_path: item.original_relative_path,
-      original_name: item.original_name,
-      mime: item.mime,
+      relative_path: String(item.relative_path ?? ""),
+      original_relative_path: item.original_relative_path as string | undefined,
+      original_name: item.original_name as string | undefined,
+      mime: item.mime as string | undefined,
+      converted_docx_path: item.converted_docx_path as string | undefined,
+      legacy_word: Boolean(item.legacy_word),
+      conversion_status: item.conversion_status as string | undefined,
     });
   }
   return attachments;
 }
 
+export type UploadSessionFileResult = {
+  attachment: AttachmentRef;
+};
+
+/** Upload one file with XMLHttpRequest progress (per-file gauge in composer). */
+export function uploadSessionFileWithProgress(
+  sessionId: string,
+  userId: string,
+  file: File,
+  token?: string | null,
+  opts?: {
+    onProgress?: (percent: number) => void;
+    signal?: AbortSignal;
+  },
+): Promise<UploadSessionFileResult> {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const fd = new FormData();
+    fd.append("files", file);
+
+    const url = `${apiBase()}/sessions/${encodeURIComponent(sessionId)}/upload`;
+
+    const onAbort = () => xhr.abort();
+    if (opts?.signal) {
+      if (opts.signal.aborted) {
+        reject(new DOMException("Upload aborted", "AbortError"));
+        return;
+      }
+      opts.signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    xhr.upload.addEventListener("progress", (e) => {
+      if (!e.lengthComputable) return;
+      const pct = Math.min(100, Math.round((e.loaded / e.total) * 100));
+      opts?.onProgress?.(pct);
+    });
+
+    xhr.addEventListener("load", () => {
+      opts?.signal?.removeEventListener("abort", onAbort);
+      if (xhr.status < 200 || xhr.status >= 300) {
+        reject(new Error(`upload failed (${xhr.status})`));
+        return;
+      }
+      try {
+        const j = JSON.parse(xhr.responseText) as {
+          files?: Array<Record<string, unknown>>;
+        };
+        const item = (j.files || [])[0];
+        if (!item?.relative_path) {
+          reject(new Error("upload response missing file"));
+          return;
+        }
+        resolve({
+          attachment: {
+            relative_path: String(item.relative_path),
+            original_relative_path: item.original_relative_path as string | undefined,
+            original_name: item.original_name as string | undefined,
+            mime: item.mime as string | undefined,
+            converted_docx_path: item.converted_docx_path as string | undefined,
+            legacy_word: Boolean(item.legacy_word),
+            conversion_status: item.conversion_status as string | undefined,
+          },
+        });
+      } catch {
+        reject(new Error("invalid upload response"));
+      }
+    });
+
+    xhr.addEventListener("error", () => {
+      opts?.signal?.removeEventListener("abort", onAbort);
+      reject(new Error("network error during upload"));
+    });
+
+    xhr.addEventListener("abort", () => {
+      opts?.signal?.removeEventListener("abort", onAbort);
+      reject(new DOMException("Upload aborted", "AbortError"));
+    });
+
+    xhr.open("POST", url);
+    const h = baseUserHeaders(userId, token);
+    for (const [k, v] of Object.entries(h)) {
+      xhr.setRequestHeader(k, v);
+    }
+    xhr.send(fd);
+  });
+}
+
 export type ChatRequestBody = {
   message: string;
   session_id: string;
diff --git a/chat-ui/lib/attachments.ts b/chat-ui/lib/attachments.ts
index 16790014..f923fd96 100644
--- a/chat-ui/lib/attachments.ts
+++ b/chat-ui/lib/attachments.ts
@@ -3,6 +3,9 @@ export type AttachmentRef = {
   original_name?: string | null;
   mime?: string | null;
   original_relative_path?: string | null;
+  converted_docx_path?: string | null;
+  legacy_word?: boolean | null;
+  conversion_status?: string | null;
 };
 
 /** Same merge as Chainlit `_merge_attachment_refs`. */
diff --git a/chat-ui/lib/i18n/locales/en.json b/chat-ui/lib/i18n/locales/en.json
index 7a222eb8..bcb713b4 100644
--- a/chat-ui/lib/i18n/locales/en.json
+++ b/chat-ui/lib/i18n/locales/en.json
@@ -523,6 +523,13 @@
     },
     "session_files_new": "New session files",
     "remove_file": "Remove {{name}}",
+    "upload": {
+      "uploading": "Uploading… {{progress}}%",
+      "done": "Upload complete",
+      "failed": "Upload failed",
+      "retry": "Retry",
+      "send_blocked": "Wait for file uploads to finish"
+    },
     "web_search": {
       "disabled": "Web search disabled",
       "restricted": "Restricted · {{count}} hosts",
diff --git a/chat-ui/lib/i18n/locales/it.json b/chat-ui/lib/i18n/locales/it.json
index 1b0ac025..72fd047b 100644
--- a/chat-ui/lib/i18n/locales/it.json
+++ b/chat-ui/lib/i18n/locales/it.json
@@ -523,6 +523,13 @@
     },
     "session_files_new": "Nuovi file sessione",
     "remove_file": "Rimuovi {{name}}",
+    "upload": {
+      "uploading": "Caricamento… {{progress}}%",
+      "done": "Caricamento completato",
+      "failed": "Caricamento fallito",
+      "retry": "Riprova",
+      "send_blocked": "Attendi il termine del caricamento file"
+    },
     "web_search": {
       "disabled": "Ricerca web disattivata",
       "restricted": "Controllata · {{count}} host",
diff --git a/config_proprietary/README.md b/config_proprietary/README.md
index e5ea6023..c8c8ae7f 100644
--- a/config_proprietary/README.md
+++ b/config_proprietary/README.md
@@ -30,6 +30,9 @@ python scripts/sync_proprietary_config.py
 python scripts/sync_proprietary_config.py --force
 ```
 
+**Nota:** non mettere commenti inline sulla stessa riga se il comando viene incollato in
+runner che non interpretano `#` (es. alcuni task IDE). Usa righe separate.
+
 `setup-aion-env.sh` / `upgrade-aion.sh` chiamano questo script **solo se**
 `config_proprietary/skills/` esiste.
 
@@ -48,3 +51,15 @@ config_proprietary/
 
 Senza `skills/`, i profili che referenziano `docx` / `pptx` / … funzionano ma
 `skill_view` su quelle skill non troverà i pacchetti finché non esegui il sync.
+
+### Verifica rapida
+
+Dopo il sync, i nuovi script report devono comparire in runtime:
+
+```bash
+ls config/skills/docx/scripts/report/
+# build_evidence_report.py  evidence_layout.py  qa_evidence_images.py
+```
+
+Se la directory manca ma esiste sotto `config_proprietary/`, il sync non è stato eseguito
+(o è fallito — controlla l'exit code).
diff --git a/config_std/mcp_registry.yaml b/config_std/mcp_registry.yaml
index c25e87ab..2507136c 100644
--- a/config_std/mcp_registry.yaml
+++ b/config_std/mcp_registry.yaml
@@ -43,6 +43,11 @@ ocr:
   args: ["-u", "ocr_mcp/server.py"]
   description: "OCR immagini/PDF tramite servizio dedicato (GLM-OCR)"
 
+geocoding:
+  command: "python"
+  args: ["-u", "geocoding/server.py"]
+  description: "Geocoding WGS84 via OpenStreetMap Nominatim (geocode_place, reverse_geocode)"
+
 session_sandbox:
   command: "python"
   args: ["-u", "session_sandbox/server.py"]
diff --git a/config_std/profiles/aion_std.yaml b/config_std/profiles/aion_std.yaml
index f9038e91..96481c6c 100644
--- a/config_std/profiles/aion_std.yaml
+++ b/config_std/profiles/aion_std.yaml
@@ -33,6 +33,7 @@ skills:
 - promotional_graphics
 - web_research_protocol
 - incremental_execution_protocol
+- long_document_protocol
 - docx
 - pdf
 - xlsx
diff --git a/config_std/profiles/document_extractor.yaml b/config_std/profiles/document_extractor.yaml
index 746b246b..ee60b0ca 100644
--- a/config_std/profiles/document_extractor.yaml
+++ b/config_std/profiles/document_extractor.yaml
@@ -6,7 +6,7 @@ instructions: |
   ## Workflow
   1. **Clarify the goal**: what must be extracted (entities, fields, constraints). If the user does not provide a schema, propose a field list consistent with the document type and ask for confirmation, or apply a default and state it clearly.
   2. **Identify the source**: files in the session workspace (`session_sandbox`), pasted text.
-  3. **Obtain text**: for scanned PDFs/images or sources that cannot be read as plain text, use **OCR**; when text is already readable (e.g. text files or text-based PDFs), prefer direct reads from the workspace and avoid unnecessary OCR.
+  3. **Obtain text**: for any PDF longer than a few pages use **`doc_ingest`** and follow `long_document_protocol` — it extracts the text layer page by page and falls back to OCR only where needed. Reserve `ocr_file` for single images or a small page range. When text is already readable (text files), read it directly and skip OCR entirely.
   4. **Extract**: populate only what is **supported by the text**; for missing values use `null` or empty arrays—do not invent.
   5. **Validate**: consistent formats (dates `YYYY-MM-DD`, amounts as numbers where possible), internal consistency across derived fields, and notes on ambiguity.
 
@@ -28,12 +28,15 @@ skills:
 - filesystem_tools_protocol
 - web_research_protocol
 - incremental_execution_protocol
+- long_document_protocol
 critical_skills:
 - core_protocol
 - artifact_protocol
+- long_document_protocol
 native_tool_groups:
 - web_research
 mcp_servers:
 - session_sandbox
 - skills_hub
 - ocr
+- geocoding
diff --git a/config_std/profiles/generic_assistant.yaml b/config_std/profiles/generic_assistant.yaml
index 837c10ba..60165b14 100644
--- a/config_std/profiles/generic_assistant.yaml
+++ b/config_std/profiles/generic_assistant.yaml
@@ -24,6 +24,7 @@ skills:
 - web_research_protocol
 - incremental_execution_protocol
 - email_imap_mcp
+- long_document_protocol
 - docx
 - pdf
 - xlsx
@@ -42,4 +43,5 @@ mcp_servers:
 - session_sandbox
 - skills_hub
 - ocr
+- geocoding
 - email-mcp-server
diff --git a/config_std/profiles/research_docs.yaml b/config_std/profiles/research_docs.yaml
index 7f50a0e5..db30d2a7 100644
--- a/config_std/profiles/research_docs.yaml
+++ b/config_std/profiles/research_docs.yaml
@@ -15,6 +15,7 @@ skills:
 - presentation_design
 - web_research_protocol
 - incremental_execution_protocol
+- long_document_protocol
 critical_skills:
 - core_protocol
 - artifact_protocol
diff --git a/config_std/skills/docx.md b/config_std/skills/docx.md
index 67b0da47..fa14c79b 100644
--- a/config_std/skills/docx.md
+++ b/config_std/skills/docx.md
@@ -4,7 +4,7 @@ description: "Create and edit Word .docx files via docx-js in the session sandbo
 tags: [office, docx, word, document]
 status: verified
 source: curated
-version: 2
+version: 4
 ---
 
 # Word (.docx) via docx-js
@@ -42,6 +42,57 @@ main().catch((e) => { console.error(e); process.exit(1); });
 
 Prefer unpack/edit/pack workflows from office scripts when available via `skill_view` and `sandbox_exec_allowlisted` on materialized `scripts/office/...` paths.
 
+## Legacy `.doc` (Word 97–2003)
+
+Binary `.doc` files **cannot** be read with `docx2txt`, `unpack.py`, or docx-js. On upload, the API host auto-converts them via **LibreOffice** (`soffice`) when `AION_OFFICE_AUTO_CONVERT_LEGACY_WORD=1` (default). Production Docker images ship `libreoffice-writer-nogui`; local dev needs LibreOffice on the API host (`brew install --cask libreoffice` on macOS).
+
+- Check the attachments block for **`converted_docx_path`** (e.g. `derived/converted/report.docx`).
+- Use **only that .docx path** for `skill_view("docx")`, unpack, and edits.
+- Do **not** convert in the sandbox and do **not** call `unpack.py` on the original `.doc` binary.
+
+If conversion is unavailable, install LibreOffice on the API server or set `AION_SOFFICE_PATH`.
+
+## Evidence images (from PDF)
+
+When building a report that cites PDF pages, use PNGs from `derived/docs/<slug>/evidence/`
+produced by the MCP tool **`pdf_evidence_crop`** (server `ocr`). Do **not** run `pdftoppm`
+full-page in the sandbox for evidence figures.
+
+- Each figure needs a caption: `source_doc / section / pag. N`.
+- Prefer `scripts/report/build_evidence_report.py` (after `skill_view("docx")`) when
+  findings JSON + evidence PNGs are ready.
+- Run `scripts/report/qa_evidence_images.py` on all evidence PNGs before delivery.
+
+### Figure layout (critical for report quality)
+
+When embedding PNGs with **python-docx**, never scale only by width — full-page crops become
+~9″ tall and Word pushes them to the next page, leaving a white band under the section title.
+
+Use `scripts/report/evidence_layout.py`:
+
+- **Max width** 6.0″ (content column), **max height** 4.75″ — preserves aspect ratio.
+- Put the **caption below** the image, not above.
+- Do **not** insert a blank paragraph before the picture.
+- Set **`keep_with_next`** on the heading / intro paragraphs so title and figure stay together.
+
+`build_evidence_report.py` applies these rules automatically.
+
+## Professional report deliverable (mandatory for PDF → Word)
+
+When the user asks for a report, relazione, or sintesi with screenshots from a decree/PDF:
+
+1. Follow **`long_document_protocol`** through findings JSON + evidence PNGs.
+2. **Always prefer** `scripts/report/build_evidence_report.py` over a custom script.
+3. The output must include: **cover**, **executive summary**, **obligations table**,
+   **numbered prescription sections** (verbatim quote + operational summary), **numbered figures**
+   (`Figura N — …`), **deadlines table**, header/footer with page numbers.
+4. **Never** deliver a bare screenshot gallery (title + image list only) — that is below quality bar.
+
+Metadata to pass to the template: `--title`, `--subtitle`, `--client`, `--plant`, `--source-doc`.
+
+If building manually with python-docx, import `scripts/report/report_style.py` and
+`scripts/report/evidence_layout.py` — do not invent ad-hoc formatting.
+
 ## Errors
 
 - **`empty_file` / `file_not_found` on run**: rewrite the script with `sandbox_write_workspace_file`.
diff --git a/config_std/skills/long_document_protocol.md b/config_std/skills/long_document_protocol.md
new file mode 100644
index 00000000..c7415db4
--- /dev/null
+++ b/config_std/skills/long_document_protocol.md
@@ -0,0 +1,202 @@
+---
+name: long_document_protocol
+description: "Mandatory protocol for finding and extracting facts from PDFs longer than a few pages: doc_ingest into one file per page, document identity check, exhaustive grep, verbatim citations with page numbers."
+tags: [core, protocol, documents, pdf, ocr, extraction]
+status: verified
+source: curated
+version: 4
+---
+
+# Long Document Protocol
+
+## When this applies
+
+Any request of the form "find / extract / summarize X from this document" where the
+source is a PDF or scan of **more than ~10 pages**. Typical cases: decrees,
+authorizations, contracts, technical reports, regulations.
+
+If the document is short, or you only need to read it front to back, this protocol is
+optional. Everything else below is mandatory.
+
+## Never do these
+
+| Shortcut | Why it fails |
+|----------|--------------|
+| `ocr_file` on a whole multi-page PDF | One vision-model call per page. On a 200-page file it always exceeds the MCP timeout, and the run is lost. |
+| A custom `pypdf`/`pdfplumber` script that accumulates text in a variable | Killed by the OOM killer (exit code `-9`) on large files. |
+| Concatenating everything into one big `.txt` and grepping it | `sandbox_grep_content` **silently skips** files above `AION_GREP_MAX_FILE_BYTES` (500 KB). You get zero hits and conclude, wrongly, that the term is absent. |
+| Answering after the first few grep hits | Prescriptions and clauses repeat across chapters. Partial retrieval reads as a complete answer and is worse than no answer. |
+
+## Step 1 — Verify extraction (auto-ingest on upload)
+
+PDF uploads are **automatically extracted** to `derived/docs/<slug>/pages/pNNNN.txt`
+(text layer only). Check the attachments block for `PDF extraction ready` or read
+`derived/docs/<slug>/manifest.json`.
+
+Call `doc_ingest(relative_path="uploads/<file>.pdf")` **only if**:
+- manifest is missing (extraction still running),
+- `"partial": true` (resume with `first_page=<resume_from>`),
+- `empty_pages` need OCR (`ocr_mode="auto"`),
+- or the user re-uploaded with `force=True`.
+
+Never call `ocr_file` on the whole PDF. Never write custom extraction scripts.
+
+Leave `write_full` off. A `full.txt` is exactly the file grep would skip.
+
+## Step 2 — Identity gate (do not skip)
+
+Read `title_guess` and `first_page_excerpt` from the manifest and confirm the document
+is the one the user is asking about — the right plant, company, year, protocol number.
+
+**If it does not match, stop and tell the user.** Do not proceed, do not name the
+deliverable after what the user asked for. Producing a well-formatted report from the
+wrong source document is the single most damaging failure mode in this workflow,
+because nothing in the output looks wrong.
+
+Also check `ocr_failed_pages` and `empty_pages`: those pages contain no usable text and
+any conclusion of the form "the document does not mention X" is unsound while they
+remain unread.
+
+## Step 3 — Search
+
+```
+sandbox_grep_content(
+    pattern="<regex>",
+    relative_root="derived",
+    glob_filter="docs/<slug>/pages/*.txt",
+    max_matches=200,
+)
+```
+
+The file name of each grep hit **is** the page number: `pages/p0101.txt` → page 101.
+
+Widen the pattern before you run it. One spelling is never enough:
+
+* case and accents: `[Rr]umor|[Aa]custic|acùstic`
+* morphological variants: `rumor(e|osità)|acustic(o|a|he|i)|sonor`
+* the domain synonyms a drafter would use: `dB\(A\)|Leq|fonometr|immission|emission`
+* numbered markers, if the document uses them: `\[[0-9]{1,3}\]`
+
+If a search returns `truncated: true`, narrow the glob to a page range and repeat —
+do not accept a truncated result set as complete.
+
+## Step 4 — Read every hit, plus one page either side
+
+For each distinct page in the hit list:
+
+```
+sandbox_read_file_chunk(relative_path="derived/docs/<slug>/pages/p0101.txt")
+```
+
+Always read `page-1` and `page+1` as well. Clauses run across page breaks: a
+prescription that starts at the bottom of one page and ends on the next is silently
+truncated if you only read the page that matched.
+
+## Step 4b — Evidence images (mandatory for Word deliverables)
+
+For every finding that will appear in a report with a screenshot, call:
+
+```
+pdf_evidence_crop(
+    relative_path="uploads/<file>.pdf",
+    page=<page>,
+    caption="<source_doc> / <section> / pag. <page>",
+)
+```
+
+Rules:
+
+| Rule | Why |
+|------|-----|
+| Use `pdf_evidence_crop`, not `pdftoppm` full-page | Full-page dumps fail the white-ratio guard and look unprofessional in Word. |
+| Caption is mandatory | Every figure in the deliverable must cite doc / section / PDF page. |
+| Read the sidecar JSON | `derived/docs/<slug>/evidence/eNNN.json` carries `white_ratio`, `bbox`, `cropped`. |
+| If `ok: false` with `too_much_whitespace` | Tighten with an explicit `bbox`, or call `sandbox_list_files(subdir="uploads")` if the PDF path was wrong — do not attach the image. |
+
+PNG output lives under `derived/docs/<slug>/evidence/eNNN.png`. Reference those paths in the
+`docx` deliverable (or `scripts/report/build_evidence_report.py` when available).
+
+## Step 5 — Record findings as you go
+
+Append to `workspace/<slug>_findings.json`, one object per extracted item, never in
+your reasoning only:
+
+```json
+{
+  "id": "53",
+  "source_doc": "<slug>",
+  "page": 101,
+  "section": "8.9 Rumore",
+  "verbatim_quote": "Il Gestore è tenuto al rispetto dei valori limite...",
+  "summary": "..."
+}
+```
+
+`source_doc` is mandatory on every record. When more than one document is in the
+session — for example a reference example supplied by the user alongside the document
+to analyse — it is the only thing that stops content from one leaking into the other.
+
+Never build a deliverable from what you remember of an earlier document in the
+conversation. Re-read the page.
+
+## Step 6 — Coverage gate before answering
+
+Before writing the answer or generating a file, verify that **every** page in the hit
+list has been either read or explicitly discarded with a reason. If any remain, go back
+to step 4.
+
+State the coverage in the answer: how many pages matched, how many were retained, and
+which pages could not be extracted.
+
+## Step 7 — Deliverable
+
+Every claim carries its `source_doc` and `page`. For a Word/Excel deliverable, load the
+`docx` / `xlsx` skill and build it **from `workspace/<slug>_findings.json`**, not from
+the conversation, so the citations cannot drift.
+
+### Professional Word standard (mandatory)
+
+The deliverable must read as a **client-ready relazione**, not a screenshot gallery.
+
+| Required | Forbidden |
+|----------|-----------|
+| Copertina (titolo, cliente/impianto, data, riservatezza) | Solo elenco immagini senza narrativa |
+| Sintesi esecutiva (1–2 paragrafi) | Script python-docx ad hoc se esiste `build_evidence_report.py` |
+| Tabella quadro obblighi (ID, sezione, pagina, sintesi) | Full-page `pdftoppm` / screenshot non croppati |
+| Sezioni numerate per prescrizione con testo + osservazioni | Indice manuale al posto del corpo analitico |
+| Figure numerate «Figura N — …» sotto l'immagine | `add_picture(width=6.5)` senza cap altezza |
+| Header/footer con titolo e numerazione pagine | |
+
+Preferred Word workflow when evidence PNGs exist:
+
+1. Collect findings JSON + all `derived/docs/<slug>/evidence/eNNN.png` paths (and sidecars).
+2. **Run `scripts/report/build_evidence_report.py`** (after `skill_view("docx")`) — this is the
+   default path; do not hand-roll a gallery script unless the template is unavailable.
+3. Pass meaningful metadata: `--title`, `--subtitle`, `--client`, `--plant`, `--source-doc`.
+4. **Run QA before delivery:** `python scripts/report/qa_evidence_images.py --glob derived/docs/<slug>/evidence/*.png`.
+5. Open the output and verify: tables present, sections numbered, figures captioned — not bare PNG stack.
+
+Example:
+
+```bash
+python scripts/report/build_evidence_report.py \
+  --findings workspace/decreto_findings.json \
+  --evidence derived/docs/<slug>/evidence/*.png \
+  --output workspace/prescrizioni_rumore_report.docx \
+  --title "Prescrizioni autorizzative — Rumore (PIC / PMC)" \
+  --subtitle "Estrazione da decreto IPPC" \
+  --client "Nome cliente" \
+  --plant "Impianto"
+```
+
+## Troubleshooting
+
+| Symptom | Action |
+|---------|--------|
+| `doc_ingest` returns `partial: true` | Call again with `first_page=<resume_from>`. |
+| `ocr_failed_pages` is not empty | Retry those pages with `ocr_file(relative_path, first_page=N, last_page=N)`; if OCR is unavailable, say so in the answer. |
+| Grep returns nothing | Your pattern is too narrow, or you grepped the wrong root. Confirm with a pattern you know is present, e.g. a word from `first_page_excerpt`. |
+| Grep returns `truncated: true` | Split by page range; do not treat it as the full result. |
+| Tool timeout | Reduce the page range. Do not repeat the same call unchanged. |
+| `pdf_evidence_crop` returns `too_much_whitespace` | Provide a tighter `bbox` in PDF points, or confirm the page has visible content. |
+| Evidence QA fails | Re-run `pdf_evidence_crop` with bbox; never ship full-page screenshots. |
diff --git a/docker/Dockerfile.backend b/docker/Dockerfile.backend
index 4ca5e715..1f694155 100644
--- a/docker/Dockerfile.backend
+++ b/docker/Dockerfile.backend
@@ -78,6 +78,7 @@ RUN apt-get update \
     nodejs \
     npm \
     podman \
+    libreoffice-writer-nogui \
     && rm -rf /var/lib/apt/lists/*
 
 # Copia il venv (contiene tutti i pacchetti Python + console scripts)
diff --git a/docker/backend-entrypoint.sh b/docker/backend-entrypoint.sh
index 1ffd25ae..ab39b34c 100755
--- a/docker/backend-entrypoint.sh
+++ b/docker/backend-entrypoint.sh
@@ -8,6 +8,10 @@ if [ "${AION_SYNC_ON_BOOT:-1}" = "1" ]; then
   python scripts/sync_config.py --force
   echo "[aion-entrypoint] Syncing mcp_servers_std -> mcp_servers ..."
   python scripts/sync_mcp_servers.py --force
+  if [ -f scripts/merge_mcp_registry_from_std.py ]; then
+    echo "[aion-entrypoint] Merging new MCP slugs from config_std -> config/mcp_registry.yaml ..."
+    python scripts/merge_mcp_registry_from_std.py
+  fi
   echo "[aion-entrypoint] Reconciling .env <-> data/runtime.env ..."
   python scripts/sync_runtime_env.py
 else
diff --git a/docs/api-and-runtime/rest-api.md b/docs/api-and-runtime/rest-api.md
index 6ca0ddb4..5837a3d7 100644
--- a/docs/api-and-runtime/rest-api.md
+++ b/docs/api-and-runtime/rest-api.md
@@ -325,7 +325,29 @@ Sends a cancellation signal to immediately stop the generation of the response i
 `POST /v1/conversations/{conversation_id}/files` (Requires `files:write`)
 
 Allows multipart/form-data sending of files to be analyzed.
-Returns an array of attachments saved in the `uploads/` folder of the session:
+Returns an array of attachments saved in the `uploads/` folder of the session.
+For legacy **`.doc`** uploads, the API host may also set conversion metadata (LibreOffice on the API process — see [Office and legacy Word](../configuration/office-and-legacy-word.md)):
+
+```json
+{
+  "attachments": [
+    {
+      "relative_path": "uploads/01907a5e_report.doc",
+      "original_relative_path": "uploads/report.doc",
+      "name": "01907a5e_report.doc",
+      "original_name": "report.doc",
+      "size_bytes": 18780160,
+      "mime": "application/msword",
+      "legacy_word": true,
+      "conversion_status": "ok",
+      "converted_docx_path": "derived/converted/report.docx"
+    }
+  ]
+}
+```
+
+Plain text upload (no conversion):
+
 ```json
 {
   "attachments": [
diff --git a/docs/architecture/source-tree.md b/docs/architecture/source-tree.md
index 4b345fe5..1c957765 100644
--- a/docs/architecture/source-tree.md
+++ b/docs/architecture/source-tree.md
@@ -59,7 +59,7 @@ The APIs represent the "boundary" that separates the agent's business logic from
 | [cron_admin.py](src/api/cron_admin.py) & [cron_user.py](src/api/cron_user.py) | Cron Job scheduling APIs | Endpoints to create, monitor, and delete periodic/scheduled tasks of the agent. |
 | [research.py](src/api/research.py) | Deep Research APIs | Support for external queries for running deep research cycles. |
 | [history.py](src/api/history.py) | STM & FTS data layer | Provides services to retrieve chat history and full-text searches on old messages. |
-| [session_uploads.py](src/api/session_uploads.py) | File upload management | Dedicated endpoint for uploading attachments (PDFs, images) to be stored in the session. |
+| [session_uploads.py](src/api/session_uploads.py) | File upload management | Upload attachments to `uploads/`; triggers PDF auto-ingest and legacy `.doc` → `.docx` conversion on the API host. |
 | [admin.py](src/api/admin.py) | Administrative CRUD dashboard | Endpoints for centralized management of profiles, users, sessions, and installed skills. |
 | [admin_agent_db.py](src/api/admin_agent_db.py) | Personal Agents Database CRUD | Administration and export of the isolated SQLite databases of each user. |
 | [admin_profile_memory.py](src/api/admin_profile_memory.py) | SOUL/MEMORY/USER CRUD | Management of persistent profile files for agents (legacy endpoints). |
@@ -144,6 +144,8 @@ Contains the Python wrappers of the tools exposed to the agent.
 - [skill_materialize.py](src/tools/skill_materialize.py): Physically materializes distilled skills on disk.
 - [promo_capture.py](src/tools/promo_capture.py): Performs graphic capture (screenshots) of HTML reports and dashboards using integrated Chromium (Playwright).
 - [prometheus_tools.py](src/tools/prometheus_tools.py) and [grafana_tools.py](src/tools/grafana_tools.py): PromQL queries and interaction with Grafana.
+- [office_convert.py](src/tools/office_convert.py) and [office_auto_convert.py](src/tools/office_auto_convert.py): Legacy `.doc` → `.docx` via LibreOffice on upload.
+- [pdf_evidence.py](src/tools/pdf_evidence.py): PDF page crop for Word report evidence images (MCP `pdf_evidence_crop`).
 
 #### `src/a2a/` and `src/plan_execution/` — Inter-agent protocol and Execution
 
diff --git a/docs/clients/chat-ui.md b/docs/clients/chat-ui.md
index 2cdbedad..ef29f4b4 100644
--- a/docs/clients/chat-ui.md
+++ b/docs/clients/chat-ui.md
@@ -77,6 +77,7 @@ Path: `/integrations`. Panel for personal credentials on servers with `credentia
 | `presentation_preview` | Yes |
 | `/db` → Agent DB iframe | Partial (component + BFF exist but trigger commented out in ChatWorkspace) |
 | Upload + merge session attachments | Yes |
+| Legacy `.doc` → `.docx` on upload (API host; fields `converted_docx_path`, `conversion_status`) | Yes — see [Office and legacy Word](../configuration/office-and-legacy-word.md) |
 | Post-turn charts | Yes (Recharts, data from `/sessions/.../charts`) |
 | New session files (uploads/workspace/derived) | Yes |
 | Profile + reasoning effort | Yes |
diff --git a/docs/configuration/document-evidence.md b/docs/configuration/document-evidence.md
new file mode 100644
index 00000000..6926c39f
--- /dev/null
+++ b/docs/configuration/document-evidence.md
@@ -0,0 +1,104 @@
+---
+sidebar_position: 7
+title: PDF evidence images for Word reports
+description: MCP pdf_evidence_crop, QA gate, and report template for high-quality Word deliverables with PDF screenshots.
+---
+
+# PDF evidence images for Word reports
+
+## Problem
+
+Agents often embed **full-page PDF screenshots** (`pdftoppm`, `convert_pdf_to_images.py`) in Word
+reports. The result looks unprofessional compared to targeted crops with captions and document
+chrome (headers, scadenziario, figure appendix).
+
+The fix is **orchestration**, not a different LLM: deterministic crop via MCP, protocol rules,
+and optional proprietary report scripts.
+
+```mermaid
+flowchart LR
+  PDF[uploads PDF] --> Ingest[doc_ingest]
+  Ingest --> Grep[sandbox_grep]
+  Grep --> Crop[pdf_evidence_crop]
+  Crop --> PNG[derived/docs/slug/evidence]
+  PNG --> Docx[build_evidence_report]
+  Docx --> QA[qa_evidence_images]
+  QA --> Out[workspace report.docx]
+```
+
+---
+
+## MCP tool: `pdf_evidence_crop`
+
+Server: **`ocr`** (`mcp_servers/ocr_mcp/`). Requires `AION_CHAT_SESSION_ID` (session-scoped pool).
+
+| Argument | Description |
+|----------|-------------|
+| `relative_path` | Session path to PDF (e.g. `uploads/decreto.pdf`) |
+| `page` | 1-based page number |
+| `bbox` | Optional clip `{x0, y0, x1, y1}` in PDF points |
+| `full_page` | When true and no bbox, skip auto-trim (still subject to white-ratio guard) |
+| `dpi` | Render resolution (default `AION_PDF_EVIDENCE_DPI`, usually 200) |
+| `caption` | Required caption for the figure |
+
+**Output:** `derived/docs/<slug>/evidence/eNNN.png` + `eNNN.json` sidecar with `page`, `bbox`,
+`white_ratio`, `cropped`, `caption`, `source_path`.
+
+**Guard:** if `white_ratio` exceeds `AION_PDF_EVIDENCE_MAX_WHITE_RATIO` (default `0.90`), returns
+`ok: false` / `too_much_whitespace` so the agent cannot ship a blank full-page dump. Pages with
+a text layer are auto-cropped to text blocks first; sparse but real content pages get a slightly
+higher ceiling than blank scans.
+
+Implementation: `src/tools/pdf_evidence.py` (PyMuPDF render + Pillow auto-trim).
+
+---
+
+## Agent protocol
+
+See skill **`long_document_protocol`** (no new slug):
+
+1. After grep + read hits, call `pdf_evidence_crop` for each cited page.
+2. Never use full-page `pdftoppm` for evidence figures.
+3. Build Word from `workspace/<slug>_findings.json` + evidence PNGs.
+4. Run QA before delivery.
+
+Skill **`docx`** documents embedding PNGs from `derived/.../evidence/`.
+
+---
+
+## Proprietary report scripts (optional)
+
+After `skill_view("docx")`, when proprietary config is synced:
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/report/build_evidence_report.py` | Client-ready relazione: cover, sintesi esecutiva, quadro obblighi, prescrizioni numerate, figure, scadenziario |
+| `scripts/report/report_style.py` | Navy theme, styled tables, header/footer |
+| `scripts/report/qa_evidence_images.py` | Fail on high white-ratio, full-page aspect, or natural display height ≥6.5″ |
+| `scripts/report/evidence_layout.py` | Shared max-width/max-height picture sizing for python-docx |
+
+If proprietary packages are absent, MCP + OSS protocol still apply; template scripts are best-effort.
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AION_PDF_EVIDENCE_DPI` | `200` | Default render DPI for `pdf_evidence_crop` |
+| `AION_PDF_EVIDENCE_MAX_WHITE_RATIO` | `0.90` | Reject crops above this white pixel ratio |
+
+---
+
+## Eval
+
+CI smoke: `evals/document_evidence/cases/smoke.yaml` — synthetic PDF crop + sidecar checks
+(`python -m pytest src/test/test_document_evidence_eval.py -v`).
+
+---
+
+## Related
+
+- [Office files and legacy Word](./office-and-legacy-word.md) — `.doc` conversion on upload
+- [Skills and system prompt](./skills-and-prompts.md) — `long_document_protocol`, `docx`
+- [MCP registry](../mcp/registry.md) — `ocr` server tools
diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md
index 59ccf9ca..7d0fd8b2 100644
--- a/docs/configuration/environment.md
+++ b/docs/configuration/environment.md
@@ -91,9 +91,19 @@ These variables **enable/disable** advanced features:
 | `AION_AGENT_MIN_REASONING_CHARS_WITHOUT_TOOL` | `6000` | SSE `turn_status` if many reasoning characters without tool (0=off) |
 | `AION_AGENT_MAX_REASONING_WITHOUT_TOOL` | `0` | Optional: threshold on SSE reasoning chunk (0=ignore; prefer chars) |
 | `AION_REASONING_HARD_STOP` | `0` | If `1`, interrupts the turn when it exceeds **both** `AION_REASONING_MAX_*` (not recommended: empty response) |
-| `AION_SQL_QM_PARAMETERIZE` | `1` | Literals → `?` before save SQL QueryMemory |
+| `AION_UPLOAD_MAX_BYTES` | `52428800` | Max size per uploaded file (session `uploads/`) |
+| `AION_OFFICE_AUTO_CONVERT_LEGACY_WORD` | `1` | Auto-convert legacy `.doc` → `.docx` on upload via LibreOffice on the API host |
+| `AION_SOFFICE_PATH` | *(auto)* | Path to `soffice` if not on `PATH` (macOS: LibreOffice.app bundle) |
+| `AION_OFFICE_CONVERT_TIMEOUT_SEC` | `90` | Timeout for `.doc` conversion |
+| `AION_DOC_AUTO_INGEST` | `1` | Background PDF text extraction on upload (PyMuPDF) |
+| `AION_GEOCODING_NOMINATIM_URL` | `https://nominatim.openstreetmap.org` | Nominatim base URL for MCP `geocoding` |
+| `AION_GEOCODING_USER_AGENT` | *(required for Nominatim)* | User-Agent string for geocoding requests |
+| `AION_GEOCODING_MIN_INTERVAL_SEC` | `1.1` | Min interval between Nominatim calls (rate limit) |
+| `AION_PDF_EVIDENCE_DPI` | `200` | Default DPI for MCP `pdf_evidence_crop` |
+| `AION_PDF_EVIDENCE_MAX_WHITE_RATIO` | `0.90` | Reject evidence crops above this white pixel ratio |
+
+Session uploads, legacy Word conversion, and PDF auto-ingest are documented in [Office files and legacy Word](./office-and-legacy-word.md). PDF evidence crops for Word reports: [PDF evidence images](./document-evidence.md).
 
-Mnemos LTM has additional knobs (ranking weights, dream schedule, embedding scan limits). See [Mnemos Architectural Hardening](../memory/mnemos-hardening.md#environment-variables) and `.env.example`.
 
 ### 🔵 Observability and Telemetry Variables (V3)
 
diff --git a/docs/configuration/office-and-legacy-word.md b/docs/configuration/office-and-legacy-word.md
new file mode 100644
index 00000000..0861abf4
--- /dev/null
+++ b/docs/configuration/office-and-legacy-word.md
@@ -0,0 +1,132 @@
+---
+sidebar_position: 6
+title: Office files and legacy Word (.doc)
+description: Auto-conversion of Word 97–2003 binaries on upload via LibreOffice on the API host.
+---
+
+# Office files and legacy Word (.doc)
+
+## Why conversion on the API host?
+
+Legacy **`.doc`** files (Word 97–2003, OLE binary) are **not** OpenXML ZIP archives. Tools that work on `.docx` — `unpack.py`, `docx2txt`, docx-js — **cannot** read them.
+
+**Design choice:** convert once at **upload time on the API process** (same host as FastAPI), not in the session sandbox:
+
+| Approach | Problem |
+|----------|---------|
+| Sandbox `soffice.py` | LibreOffice is not installed in the sandbox; agent must discover conversion and often fails |
+| `docx2txt` / `unpack` on `.doc` | Wrong format — expects ZIP/OpenXML |
+| User manual re-save | Poor UX for chat uploads |
+
+Production Docker images ship **`libreoffice-writer-nogui`** in `docker/Dockerfile.backend`. Local dev on macOS: `brew install --cask libreoffice`.
+
+Conversion runs in **`src/tools/office_convert.py`**, triggered from **`src/api/session_uploads.py`** and **`src/api/v1/files.py`** via **`apply_legacy_word_conversion()`**.
+
+---
+
+## Upload flow
+
+```mermaid
+flowchart LR
+    UI[chat-ui upload] --> API[POST /sessions/.../upload]
+    API --> Save[save_upload uploads/]
+    Save --> Conv{legacy .doc?}
+    Conv -->|no| Done[return meta]
+    Conv -->|yes| LO[soffice --convert-to docx]
+    LO --> Out[derived/converted/name.docx]
+    Out --> Manifest[derived/converted/upload.json]
+    Manifest --> Done
+```
+
+1. File is stored under `uploads/<uuid>_<name>` (plus stable alias `uploads/<original_name>`).
+2. If extension/MIME indicates legacy Word, **`soffice`** converts to **`derived/converted/<stem>.docx`**.
+3. Response JSON and chat **`attachments`** / **`turn_attachments`** include:
+   - `legacy_word: true`
+   - `conversion_status`: `ok` | `unavailable` | `failed`
+   - `converted_docx_path`: e.g. `derived/converted/report.docx` (when `ok`)
+4. **`AgentPipeline._format_attachments_block`** injects a prompt block telling the agent to use **only** the `.docx` path (never unpack the binary `.doc`).
+
+Misnamed files (`.doc` extension but ZIP/OpenXML payload) are **copied** to `.docx` without LibreOffice.
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AION_OFFICE_AUTO_CONVERT_LEGACY_WORD` | `1` | Enable auto-conversion on upload |
+| `AION_SOFFICE_PATH` | *(auto)* | Explicit path to `soffice` if not on `PATH` |
+| `AION_OFFICE_CONVERT_TIMEOUT_SEC` | `90` | Max seconds per conversion |
+
+**macOS dev example:**
+
+```bash
+AION_SOFFICE_PATH=/Applications/LibreOffice.app/Contents/MacOS/soffice
+```
+
+**Ubuntu / Docker:** `soffice` is on `PATH` after `libreoffice-writer-nogui` is installed.
+
+---
+
+## Agent workflow
+
+1. User uploads `report.doc`.
+2. Agent sees in the attachments block: **`derived/converted/report.docx`**.
+3. `skill_view("docx")` → unpack/edit/pack on the **`.docx`** path only.
+4. Deliver corrected file from `workspace/` or `uploads/` after pack.
+
+Do **not** run `scripts/office/soffice.py --convert-to docx` in the sandbox for uploads — conversion is already done (or failed with a clear `conversion_status`).
+
+See also [Skills and system prompt](./skills-and-prompts.md) (`docx` skill) and [Filesystem policy](./filesystem-policy-and-promo.md) (allowlisted `python` for office scripts on **`.docx`** only).
+
+---
+
+## MCP registry merge (new builtins)
+
+`config/mcp_registry.yaml` is **never overwritten** by `sync_config.py --force` (local marketplace servers stay intact). New std servers (e.g. `geocoding`) are merged with:
+
+```bash
+python scripts/merge_mcp_registry_from_std.py
+```
+
+This runs automatically from:
+
+- `scripts/dev-api.sh`
+- `scripts/setup_core.py` (after `sync_mcp_servers.py`)
+- `docker/backend-entrypoint.sh` (with `AION_SYNC_ON_BOOT=1`)
+
+Use `--dry-run` to list slugs that would be added.
+
+---
+
+## Troubleshooting
+
+### `conversion_status: unavailable`
+
+LibreOffice not found on the **API host** (not the sandbox).
+
+- **Docker:** rebuild backend image (`docker compose build backend`) so `libreoffice-writer-nogui` is present.
+- **macOS dev:** `brew install --cask libreoffice` and optionally set `AION_SOFFICE_PATH`.
+- **Re-upload** the `.doc` after fixing the host (or send a new chat message — retry runs if manifest was `unavailable`).
+
+### Agent still calls `soffice` in sandbox
+
+Reload profile/skill or restart backend after upgrading; proprietary `docx` skill documents API-side conversion. Ensure `converted_docx_path` is present in `turn_attachments` (chat-ui passes upload response fields).
+
+### New MCP missing in Admin → Profiles
+
+Run `python scripts/merge_mcp_registry_from_std.py` and restart the API.
+
+For PDF → Word reports with evidence screenshots, see [PDF evidence images](./document-evidence.md).
+
+---
+
+## Related source files
+
+| File | Role |
+|------|------|
+| `src/tools/office_convert.py` | LibreOffice conversion logic |
+| `src/tools/office_auto_convert.py` | Async wrapper + manifest persistence |
+| `src/agent_pipeline.py` | Attachments block hints for legacy Word |
+| `docker/Dockerfile.backend` | `libreoffice-writer-nogui` package |
+| `scripts/merge_mcp_registry_from_std.py` | Merge new MCP slugs from `config_std` |
diff --git a/docs/configuration/skills-and-prompts.md b/docs/configuration/skills-and-prompts.md
index 3b033858..6b119650 100644
--- a/docs/configuration/skills-and-prompts.md
+++ b/docs/configuration/skills-and-prompts.md
@@ -23,7 +23,9 @@ Extended tool descriptions for sandbox write/edit/patch live in `config_std/tool
 
 The curated skill **`artifact_protocol`** (`config_std/skills/artifact_protocol.md`, v8) is the single source for file-delivery rules. Legacy per-strategy skills (`artifact_protocol_tool`, `artifact_protocol_xml`, `artifact_protocol_markdown`) were removed — delivery is always via sandbox tools unless `AION_ARTIFACT_STREAM_LEGACY=1`.
 
-Companion skill **`docx`** documents the docx-js workflow (`skill_view` → `sandbox_install_npm_packages` → write script → `sandbox_run_node_file`).
+Companion skill **`docx`** documents the docx-js workflow (`skill_view` → `sandbox_install_npm_packages` → write script → `sandbox_run_node_file`). Legacy **`.doc`** (Word 97–2003) is converted to `.docx` on the API host at upload — see [Office files and legacy Word](./office-and-legacy-word.md).
+
+For multi-page PDF → Word reports with screenshots, skill **`long_document_protocol`** requires MCP **`pdf_evidence_crop`** (server `ocr`) instead of full-page `pdftoppm`. See [PDF evidence images](./document-evidence.md).
 
 ## Skill file format
 
diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md
index 8fadd30a..395ca7c0 100644
--- a/docs/deployment/docker.md
+++ b/docs/deployment/docker.md
@@ -79,6 +79,9 @@ per l'installazione dei pacchetti Python:
 `/app/data/chroma_embedding_cache` (build + warmup al boot). Con volume `aion_data` vuoto al
 primo deploy, il warmup lifespan ripopola la cache sul volume persistente. Variabili:
 `AION_MEMPALACE_WARMUP`, `AION_CHROMA_SHARED_EMBEDDING_CACHE`, `AION_SSE_KEEPALIVE_SEC`.
+- **Legacy Word (.doc):** immagine backend include `libreoffice-writer-nogui` per conversione
+  automatica all'upload (`derived/converted/*.docx`). Vedi
+  [Office e Word legacy](../configuration/office-and-legacy-word.md).
 - Risolutore deterministico (no problemi di metadata caching pip)
 - Binario statico copiato da `ghcr.io/astral-sh/uv:${UV_VERSION}` (no Rust toolchain
   richiesta nel builder; versione configurabile in `.env` → `docker-compose.yml`)
@@ -116,7 +119,7 @@ Dopo `git pull` che aggiorna solo profili/skill/MCP standard:
 docker compose restart backend    # prod o dev — niente rebuild immagine
 ```
 
-Rebuild serve solo per cambi a `src/`, `requirements.txt` o Dockerfile. `sync_config --force` non sovrascrive `mcp_registry.yaml` / `mcp_registry.local.yaml` (overlay locale).
+Rebuild serve solo per cambi a `src/`, `requirements.txt` o Dockerfile. `sync_config --force` non sovrascrive `mcp_registry.yaml` / `mcp_registry.local.yaml` (overlay locale). Per aggiungere **nuovi** server MCP da `config_std` (es. `geocoding`) senza toccare i custom, l'entrypoint esegue anche `scripts/merge_mcp_registry_from_std.py`.
 
 **Profili (dev e Docker):** un solo percorso, `config/profiles/` (bind mount `./config` in compose).
 L'admin UI scrive lì; in locale e in container vedi gli stessi file.
@@ -263,7 +266,7 @@ Alembic e' sincrono: l'URL viene convertito al driver sync equivalente
 
 ```
 docker/
-├── Dockerfile.backend     # Python 3.13 + tesseract + poppler + tini; COPY *_std + entrypoint sync
+├── Dockerfile.backend     # Python 3.13 + tesseract + poppler + libreoffice-writer-nogui + tini; COPY *_std + entrypoint sync
 ├── backend-entrypoint.sh  # sync config_std/mcp_servers_std → runtime dirs at boot
 ├── Dockerfile.chat-ui     # Next.js standalone (output: 'standalone')
 ├── Dockerfile.admin-ui    # Next.js standalone + basePath=/admin
diff --git a/docs/mcp/registry.md b/docs/mcp/registry.md
index b108da8c..53ab945a 100644
--- a/docs/mcp/registry.md
+++ b/docs/mcp/registry.md
@@ -56,7 +56,7 @@ graph TD
 
 | Registro | Contenuto | Versionato | Scopo |
 |----------|-----------|------------|-------|
-| `mcp_registry.yaml` | Server standard (prometheus, grafana, etc.) | Template in `config_std/` | Copiato in `config/` al primo sync; **non** sovrascritto da `sync_config.py --force` |
+| `mcp_registry.yaml` | Server standard (prometheus, grafana, etc.) | Template in `config_std/` | Copiato in `config/` al primo sync; **non** sovrascritto da `sync_config.py --force`. Nuovi slug da std: `scripts/merge_mcp_registry_from_std.py` (setup, upgrade, Docker entrypoint, `dev-api.sh`) |
 | `mcp_registry.local.yaml` | Overlay flat (stile AION) | ❌ No | Specifico per deployment (es. `toolbox-mysql`) |
 | `mcp_registry.local.json` | Overlay standard `{ "mcpServers": { ... } }` | ❌ No | Stesso merge del `.local.yaml`; formato Claude/Cursor/VS Code |
 
@@ -316,7 +316,8 @@ python -m src.mcp_import -i claude_desktop_config.json -o config/mcp_registry.lo
 | `skills_hub` | `mcp_servers/skills_hub/` | Skill search, list, view |
 | `code` | `mcp_servers/code_executor/` | Execute code in sandbox |
 | `session_sandbox` | `mcp_servers/session_sandbox/` | Session workspace operations |
-| `ocr` | `mcp_servers/ocr_mcp/` | OCR processing |
+| `ocr` | `mcp_servers/ocr_mcp/` | OCR + document ingest (`doc_ingest`, `ocr_file`, **`pdf_evidence_crop`**) |
+| `geocoding` | `mcp_servers/geocoding/` | Forward/reverse geocode via OpenStreetMap Nominatim (`geocode_place`, `reverse_geocode`) |
 | `promo_render` | `mcp_servers/promo_render/` | Promotional graphics React/HTML → PNG |
 | `agent_db` | `mcp_servers/agent_db/` | Agent SQLite database for structured memory |
 | `aion_subagents` | `mcp_servers/aion_subagents/` | Delegate tasks to isolated subagents |
@@ -465,5 +466,6 @@ custom_server:
 
 - [Albero dei sorgenti](../architecture/source-tree.md) - Struttura directory
 - [Variabili ambiente](../configuration/environment.md) - Configurazioni
+- [Office e Word legacy](../configuration/office-and-legacy-word.md) - Conversione `.doc` e merge registry MCP
 - [Profili agente](../configuration/profiles.md) - Come i profili usano MCP servers
 - [Orchestrazione e HITL](./orchestration.md) — `mark_task_completed` built-in su tutti i profili; server `orchestration` (`type: in_process`), approve API, UI TaskPlanManager
diff --git a/evals/document_evidence/cases/smoke.yaml b/evals/document_evidence/cases/smoke.yaml
new file mode 100644
index 00000000..dbe829f8
--- /dev/null
+++ b/evals/document_evidence/cases/smoke.yaml
@@ -0,0 +1,37 @@
+title: Document evidence — smoke (CI)
+description: >
+  Pipeline eval for pdf_evidence_crop: synthetic PDF page crop, sidecar JSON,
+  and white-ratio guard (no golden visual comparison).
+tier: ci
+cases:
+  - id: synthetic_evidence_crop
+    pdf:
+      source: synthetic
+      profile: rumore_decreto
+      pages: 10
+      prescription_page: 5
+      pmc_page: 8
+    crop:
+      page: 5
+      caption: "decreto / PIC [53] / pag. 5"
+    expect:
+      ok: true
+      max_white_ratio: 0.90
+      min_width: 50
+      sidecar_required: true
+      cropped: true
+
+  - id: synthetic_full_page_rejected
+    pdf:
+      source: synthetic
+      profile: rumore_decreto
+      pages: 3
+      prescription_page: 1
+      pmc_page: 2
+    crop:
+      page: 1
+      full_page: true
+      caption: "full page dump test"
+    expect:
+      ok: false
+      error: too_much_whitespace
diff --git a/evals/geocoding/cases/inari_shrines_jp.yaml b/evals/geocoding/cases/inari_shrines_jp.yaml
new file mode 100644
index 00000000..fa4f4f03
--- /dev/null
+++ b/evals/geocoding/cases/inari_shrines_jp.yaml
@@ -0,0 +1,96 @@
+title: Inari shrines Japan — geocoding golden set
+description: >
+  Ten famous Inari shrines across Japan. Reference coordinates from OSM Nominatim
+  (Japanese queries) and Wikipedia where noted. Use max_distance_km tolerance per case.
+tier: manual
+cases:
+  - id: fushimi_inari
+    query: "Fushimi Inari Taisha, Kyoto, Japan"
+    query_ja: "伏見稲荷大社, 京都府"
+    prefecture: Kyoto
+    lat: 34.967519
+    lon: 135.779710
+    max_distance_km: 0.5
+    notes: "English query works on Nominatim."
+
+  - id: kasama_inari
+    query: "Kasama Inari Jinja, Ibaraki, Japan"
+    query_ja: "笠間稲荷神社, 茨城県"
+    prefecture: Ibaraki
+    lat: 36.3854725
+    lon: 140.2543843
+    max_distance_km: 0.5
+    notes: "English romanization often misses; Japanese name required."
+
+  - id: yutoku_inari
+    query: "Yūtoku Inari Jinja, Saga, Japan"
+    query_ja: "祐徳稲荷神社, 佐賀県"
+    prefecture: Saga
+    lat: 33.074398
+    lon: 130.108065
+    max_distance_km: 0.5
+
+  - id: toyokawa_inari
+    query: "Toyokawa Inari, Myōgon-ji, Aichi, Japan"
+    query_ja: "豊川稲荷, 豊川市, 愛知県"
+    prefecture: Aichi
+    lat: 34.8258196
+    lon: 137.3922658
+    max_distance_km: 0.5
+    notes: "Buddhist temple name (Myōgon-ji) + shrine; city Toyokawa disambiguates."
+
+  - id: saijo_inari
+    query: "Saijō Inari, Myōkyō-ji, Okayama, Japan"
+    query_ja: "最上稲荷, 岡山市, 岡山県"
+    prefecture: Okayama
+    lat: 34.7099376
+    lon: 133.8319529
+    max_distance_km: 0.5
+    notes: "Must use Okayama city, not Kurashiki homonym."
+
+  - id: taikodani_inari
+    query: "Taikodani Inari Jinja, Shimane, Japan"
+    query_ja: "太皷谷稲成神社, 津和野町, 島根県"
+    prefecture: Shimane
+    lat: 34.4633957
+    lon: 131.7678723
+    max_distance_km: 1.0
+    notes: "OSM uses 稲成 variant; town Tsuwano required."
+
+  - id: takekoma_jinja
+    query: "Takekoma Jinja, Miyagi, Japan"
+    query_ja: "竹駒神社, 岩沼市, 宮城県"
+    prefecture: Miyagi
+    lat: 38.1049802
+    lon: 140.8619439
+    max_distance_km: 0.5
+    notes: "Iwanuma city disambiguates from Sendai area homonyms."
+
+  - id: kusado_inari
+    query: "Kusado Inari Jinja, Hiroshima, Japan"
+    query_ja: "草戸稲荷神社, 広島県"
+    prefecture: Hiroshima
+    lat: 34.4795347
+    lon: 133.3464400
+    max_distance_km: 0.5
+    notes: "Fukuyama area; prefecture alone is enough in JA."
+
+  - id: chiyobo_inari
+    query: "Chiyobo Inari Jinja, Gifu, Japan"
+    query_ja: "千代保稲荷神社, 岐阜県"
+    prefecture: Gifu
+    lat: 35.2635572
+    lon: 136.6464304
+    max_distance_km: 0.5
+    notes: "Romanization Chiyobo vs 千代保; near Seki/Kaisen."
+
+  - id: takahashi_inari
+    query: "Takahashi Inari Jinja, Kumamoto, Japan"
+    query_ja: "高橋稲荷神社, 熊本市西区, 熊本県"
+    prefecture: Kumamoto
+    lat: 32.7830
+    lon: 130.6586
+    max_distance_km: 0.5
+    notes: >
+      Dangerous homonym: query「高橋稲荷, 熊本市」without 神社 returned a salon in Akita.
+      Always include shrine type + ward/city.
diff --git a/evals/long_document/cases/altomonte_rumore.yaml b/evals/long_document/cases/altomonte_rumore.yaml
new file mode 100644
index 00000000..a8f59091
--- /dev/null
+++ b/evals/long_document/cases/altomonte_rumore.yaml
@@ -0,0 +1,97 @@
+title: Altomonte — prescrizioni rumore PIC + PMC
+description: >
+  Golden set from the production failure case (decreto IPPC ~200 pagine).
+  Requires the real PDF via AION_EVAL_ALTOMONTE_PDF; skipped in CI when unset.
+  Validate page numbers against your copy before tightening min_recall.
+tier: manual
+cases:
+  - id: altomonte_rumore_pic_pmc
+    skip_if_pdf_missing: true
+    min_recall: 0.85
+    pdf:
+      source: env
+      path_env: AION_EVAL_ALTOMONTE_PDF
+    ingest:
+      ocr_mode: auto
+      budget_sec: 90
+    identity:
+      must_contain:
+        - altomonte
+      must_not_contain: []
+    required_hits:
+      - label: PIC prescrizione 53
+        grep_pattern: "\\[53\\]"
+        page: 101
+        must_contain:
+          - "[53]"
+      - label: PIC prescrizione 54
+        grep_pattern: "\\[54\\]"
+        page: 101
+        must_contain:
+          - "[54]"
+      - label: PIC prescrizione 55
+        grep_pattern: "\\[55\\]"
+        page: 101
+        must_contain:
+          - "[55]"
+      - label: PIC prescrizione 56
+        grep_pattern: "\\[56\\]"
+        page: 102
+        must_contain:
+          - "[56]"
+      - label: PIC prescrizione 57
+        grep_pattern: "\\[57\\]"
+        page: 102
+        must_contain:
+          - "[57]"
+      - label: PIC prescrizione 58
+        grep_pattern: "\\[58\\]"
+        page: 102
+        must_contain:
+          - "[58]"
+      - label: PIC prescrizione 59
+        grep_pattern: "\\[59\\]"
+        page: 102
+        must_contain:
+          - "[59]"
+      - label: PMC sezione Rumore
+        grep_pattern: "(?i)rumor"
+        page: null
+        must_contain:
+          - "monitoraggio"
+    agent_expectations:
+      user_query: >
+        ESTRAI DA DECRETO - PIC E PMC LE PRESCRIZIONI AUTORIZZATIVE RELATIVE AL RUMORE.
+        Genera un elenco con documento, riferimento e pagina.
+      output_must_contain:
+        - "[53]"
+        - "PIC"
+        - "PMC"
+        - "101"
+      output_must_not_contain:
+        - "presenzano"
+
+  - id: altomonte_wrong_plant_guard
+    skip_if_pdf_missing: true
+    min_recall: 1.0
+    pdf:
+      source: env
+      path_env: AION_EVAL_ALTOMONTE_PDF
+    ingest:
+      ocr_mode: auto
+      budget_sec: 90
+    identity:
+      must_contain:
+        - altomonte
+      must_not_contain:
+        - presenzano
+    required_hits: []
+    agent_expectations:
+      user_query: >
+        Estrai le prescrizioni rumore per l'impianto PRESENZANO da questo decreto.
+      output_must_not_contain:
+        - "[53]"
+        - "altomonte"
+      notes: >
+        If the PDF is Altomonte, a correct agent must refuse or ask for the right
+        document instead of fabricating Presenzano prescriptions.
diff --git a/evals/long_document/cases/synthetic_smoke.yaml b/evals/long_document/cases/synthetic_smoke.yaml
new file mode 100644
index 00000000..cc1c3a99
--- /dev/null
+++ b/evals/long_document/cases/synthetic_smoke.yaml
@@ -0,0 +1,39 @@
+title: Long document — synthetic smoke (CI)
+description: >
+  Pipeline eval without LLM: doc_ingest on a 200-page synthetic decree, then
+  grep for PIC [53] and PMC rumore markers on known pages.
+tier: ci
+cases:
+  - id: synthetic_rumore_smoke
+    min_recall: 1.0
+    pdf:
+      source: synthetic
+      profile: rumore_decreto
+      pages: 200
+      prescription_page: 101
+      pmc_page: 150
+    ingest:
+      ocr_mode: never
+      budget_sec: 600
+    identity:
+      must_contain: []
+      must_not_contain: []
+    required_hits:
+      - label: PIC prescrizione 53
+        grep_pattern: "\\[53\\]"
+        page: 101
+        must_contain:
+          - "[53]"
+          - "rumore"
+      - label: PIC sezione 8.9 Rumore
+        grep_pattern: "8\\.9 Rumore"
+        page: 101
+        must_contain:
+          - "Parere Istruttorio Conclusivo"
+      - label: PMC tabella rumore
+        grep_pattern: "Piano di Monitoraggio"
+        page: 150
+        must_contain:
+          - "Rumore"
+          - "monitoraggio acustico"
+    nl_query: prescrizioni autorizzative relative al rumore PIC e PMC monitoraggio acustico
diff --git a/mcp_servers_std/geocoding/server.py b/mcp_servers_std/geocoding/server.py
new file mode 100644
index 00000000..a92fd5eb
--- /dev/null
+++ b/mcp_servers_std/geocoding/server.py
@@ -0,0 +1,84 @@
+"""
+MCP geocoding: forward geocode via OpenStreetMap Nominatim.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../")))
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("AION Geocoding")
+
+
+@mcp.tool()
+async def geocode_place(
+    query: str,
+    fallback_query: str = "",
+    country_code: str = "",
+    validate_contains: str = "",
+    limit: int = 5,
+) -> str:
+    """
+    Resolve a place name to WGS84 coordinates using OpenStreetMap Nominatim.
+
+    Use for addresses, landmarks, shrines, plants — never invent lat/lon from memory.
+
+    Args:
+        query: Primary search string (e.g. "Fushimi Inari Taisha, Kyoto, Japan").
+        fallback_query: Second query if the first returns no good hit (e.g. Japanese name).
+        country_code: ISO 3166-1 alpha-2 filter (e.g. "jp", "it").
+        validate_contains: Substring that must appear in the resolved display_name
+            (e.g. prefecture name) or the result is marked validated=false.
+        limit: Max Nominatim candidates (1–10).
+
+    Returns JSON with ok, lat, lon, display_name, validated, candidates, source.
+    """
+    import asyncio
+
+    from src.tools.geocode import geocode_place_sync
+
+    result = await asyncio.to_thread(
+        geocode_place_sync,
+        query,
+        fallback_query=fallback_query,
+        country_code=country_code,
+        validate_contains=validate_contains,
+        limit=limit,
+    )
+    return json.dumps(result, ensure_ascii=False)
+
+
+@mcp.tool()
+async def reverse_geocode(lat: float, lon: float) -> str:
+    """
+    Reverse geocode WGS84 coordinates to a human-readable address (sanity check).
+
+    Use after geocode_place to confirm the point matches the expected region.
+    """
+    import asyncio
+
+    from src.tools.geocode import reverse_geocode_sync
+
+    result = await asyncio.to_thread(reverse_geocode_sync, lat, lon)
+    return json.dumps(result, ensure_ascii=False)
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    from mcp.server.stdio import stdio_server
+
+    async def main():
+        async with stdio_server() as (read_stream, write_stream):
+            await mcp._mcp_server.run(
+                read_stream,
+                write_stream,
+                mcp._mcp_server.create_initialization_options(),
+            )
+
+    asyncio.run(main())
diff --git a/mcp_servers_std/ocr_mcp/server.py b/mcp_servers_std/ocr_mcp/server.py
index edad4b1c..de11911f 100644
--- a/mcp_servers_std/ocr_mcp/server.py
+++ b/mcp_servers_std/ocr_mcp/server.py
@@ -145,16 +145,115 @@ async def _ocr_via_api_async(
     return content if isinstance(content, str) else str(content)
 
 
+def _clamp_ingest_budget(requested: float) -> float:
+    """Keep the internal deadline safely below the MCP bridge timeout."""
+    bridge = _env_float("AION_MCP_TOOL_RESULT_TIMEOUT", 120.0)
+    ceiling = max(10.0, bridge - 25.0)
+    try:
+        value = float(requested)
+    except (TypeError, ValueError):
+        value = 90.0
+    if value <= 0:
+        value = ceiling
+    return min(max(value, 10.0), ceiling)
+
+
+@mcp.tool()
+async def doc_ingest(
+    relative_path: str,
+    first_page: int = 1,
+    last_page: int = 0,
+    ocr_mode: str = "auto",
+    budget_sec: float = 90.0,
+    force: bool = False,
+    write_full: bool = False,
+) -> str:
+    """
+    Extract a PDF into one text file per page under derived/docs/<slug>/pages/.
+
+    This is the entry point for ANY multi-page document. Prefer it over ocr_file and
+    over custom extraction scripts: it never loads the whole document in memory, it
+    skips pages already extracted, and if it runs out of time it returns
+    ``partial: true`` with ``resume_from`` so the next call continues where it stopped.
+
+    ``ocr_mode``: ``auto`` runs OCR only on pages with no usable text layer (cheap on
+    born-digital PDFs), ``never`` disables it, ``always`` forces OCR on every page.
+    ``write_full`` additionally concatenates everything into ``full.txt``; leave it off
+    unless you need sequential reading, because a single large file is skipped by
+    ``sandbox_grep_content`` above AION_GREP_MAX_FILE_BYTES.
+
+    Returns a small JSON manifest: page counts, empty pages, the grep pattern to use,
+    and an excerpt of the first page to confirm the document is the one requested.
+    """
+    import json
+
+    from src.session_workspace import ensure_session_dirs, safe_resolve, session_root
+    from src.tools.doc_ingest import ingest_document
+
+    sid = _require_session()
+    ensure_session_dirs(sid)
+    try:
+        path = safe_resolve(sid, relative_path, must_exist=True)
+    except Exception as e:
+        return json.dumps(
+            {"ok": False, "error": "path_error", "message": str(e)},
+            ensure_ascii=False,
+        )
+
+    async def _ocr_page(page_no: int, image_bytes: bytes, mime: str) -> str:
+        return await _ocr_via_api_async(
+            image_bytes,
+            mime,
+            f"Page {page_no}: Extract all visible text. Preserve reading order.",
+        )
+
+    use_ocr = ocr_mode != "never" and _is_advanced_ocr_enabled()
+
+    try:
+        manifest = await ingest_document(
+            path,
+            session_root(sid),
+            first_page=first_page,
+            last_page=last_page,
+            ocr_mode=ocr_mode,
+            budget_sec=_clamp_ingest_budget(budget_sec),
+            force=force,
+            write_full=write_full,
+            ocr_page=_ocr_page if use_ocr else None,
+        )
+    except Exception as e:
+        logger.exception("doc_ingest failed for %s", relative_path)
+        return json.dumps(
+            {"ok": False, "error": "ingest_failed", "message": str(e)},
+            ensure_ascii=False,
+        )
+
+    if manifest.get("ok") and not use_ocr and manifest.get("empty_pages_count"):
+        manifest["warning"] = (
+            f"{manifest['empty_pages_count']} page(s) have no text layer and OCR is "
+            "unavailable (ocr_mode=never or OCR service not configured). Those pages "
+            "are empty in the extraction."
+        )
+    return json.dumps(manifest, ensure_ascii=False)
+
+
 @mcp.tool()
 async def ocr_file(
     relative_path: str,
     instruction: str = "Extract all visible text. Preserve reading order.",
     max_pages: int = 20,
+    first_page: int = 1,
+    last_page: int = 0,
 ) -> str:
     """
-    Extract text from a session file (uploads/, derived/, workspace/).
-    ALWAYS use the vision-based OCR model (vLLM/OpenAI) per la massima precisione.
-    Per i PDF, elabora le pagine in parallelo.
+    Extract text from a session file (uploads/, derived/, workspace/) via vision OCR.
+
+    For multi-page PDFs prefer ``doc_ingest``: it is far cheaper, writes one file per
+    page and resumes after a timeout. Use ``ocr_file`` for single images or a small
+    page range of a scanned PDF.
+
+    Page range (PDF only): ``first_page``/``last_page`` are 1-based and inclusive.
+    Leave ``last_page=0`` to read ``max_pages`` pages starting at ``first_page``.
     """
     from src.session_workspace import ensure_session_dirs, safe_resolve
     import asyncio
@@ -207,8 +306,15 @@ async def ocr_file(
             from pdf2image import convert_from_path
 
             # Carichiamo le impostazioni o usiamo il parametro
-            limit = _env_int("AION_OCR_PDF_MAX_PAGES", max_pages)
-            images = convert_from_path(str(path), first_page=1, last_page=limit)
+            span = _env_int("AION_OCR_PDF_MAX_PAGES", max_pages)
+            start = max(1, int(first_page or 1))
+            if last_page and int(last_page) >= start:
+                end = int(last_page)
+            else:
+                end = start + max(1, span) - 1
+            # Never let an explicit range exceed the configured per-call page budget.
+            end = min(end, start + max(1, span) - 1)
+            images = convert_from_path(str(path), first_page=start, last_page=end)
 
             # Limit parallel calls to avoid overloading the OCR server
             sem = asyncio.Semaphore(5)
@@ -223,20 +329,26 @@ async def limited_ocr(img_data, mime, page_instr):
                 img.save(buf, format="JPEG", quality=85)
                 img_data = buf.getvalue()
                 tasks.append(
-                    limited_ocr(img_data, "image/jpeg", f"Page {i + 1}: {instruction}")
+                    limited_ocr(
+                        img_data, "image/jpeg", f"Page {start + i}: {instruction}"
+                    )
                 )
 
             logger.info(
-                f"Starting parallel OCR (limit 5) for {len(tasks)} pages of {path.name}"
+                "Starting parallel OCR (limit 5) for pages %d-%d of %s",
+                start,
+                start + len(tasks) - 1,
+                path.name,
             )
             results = await asyncio.gather(*tasks, return_exceptions=True)
 
             all_text = []
             for i, res in enumerate(results):
+                page_no = start + i
                 if isinstance(res, Exception):
-                    all_text.append(f"--- PAGE {i + 1} ERROR ---\n{res}")
+                    all_text.append(f"--- PAGE {page_no} ERROR ---\n{res}")
                 else:
-                    all_text.append(f"--- PAGE {i + 1} ---\n{res}")
+                    all_text.append(f"--- PAGE {page_no} ---\n{res}")
 
             return "\n\n".join(all_text)
         except Exception as e:
@@ -259,6 +371,91 @@ async def limited_ocr(img_data, mime, page_instr):
     return f"MIME type not supported for OCR: {mime}. Use images (png, jpeg, webp, tiff) o PDF."
 
 
+@mcp.tool()
+async def pdf_evidence_crop(
+    relative_path: str,
+    page: int,
+    bbox: dict | None = None,
+    full_page: bool = False,
+    dpi: int = 0,
+    caption: str = "",
+) -> str:
+    """
+    Crop a PDF page region into a PNG evidence image for Word report deliverables.
+
+    Writes ``derived/docs/<slug>/evidence/eNNN.png`` plus a JSON sidecar with page,
+    bbox, dpi, white_ratio, and caption. Use after ``doc_ingest`` + grep when you need
+    a screenshot for a cited page — never attach a full-page ``pdftoppm`` dump as evidence.
+
+    Args:
+        relative_path: Session path to the PDF (e.g. ``uploads/decreto.pdf``).
+        page: 1-based page number.
+        bbox: Optional clip in PDF points ``{x0, y0, x1, y1}``. When omitted and
+            ``full_page`` is false, the page is rendered then auto-trimmed to content.
+        full_page: When true (and no bbox), keep the entire page without auto-trim.
+        dpi: Render resolution (default from ``AION_PDF_EVIDENCE_DPI``, usually 200).
+        caption: Required caption for the figure (e.g. ``decreto / §8.9 / pag. 101``).
+
+    Returns JSON with ``ok``, ``png_path``, ``sidecar_path``, ``white_ratio``. Fails with
+    ``too_much_whitespace`` when the result is mostly blank (full-page dump guard).
+    """
+    import asyncio
+    import json
+
+    from src.session_workspace import ensure_session_dirs, safe_resolve, session_root
+    from src.tools.pdf_evidence import default_dpi, pdf_evidence_crop_sync
+
+    sid = _require_session()
+    ensure_session_dirs(sid)
+    try:
+        path = safe_resolve(sid, relative_path, must_exist=True)
+    except FileNotFoundError:
+        from src.session_workspace import list_dir
+
+        pdfs = [
+            row["relative_path"]
+            for row in list_dir(sid, subdir="uploads")
+            if str(row.get("mime", "")).endswith("pdf")
+            or str(row.get("name", "")).lower().endswith(".pdf")
+        ]
+        hint = "Call sandbox_list_files(subdir='uploads') to list uploaded files."
+        if pdfs:
+            hint = (
+                f"PDF not found at {relative_path!r}. Available uploads: "
+                + ", ".join(pdfs[:8])
+                + (" …" if len(pdfs) > 8 else "")
+            )
+        return json.dumps(
+            {
+                "ok": False,
+                "error": "path_error",
+                "message": f"file not found: {relative_path}",
+                "hint": hint,
+                "upload_pdfs": pdfs[:12],
+            },
+            ensure_ascii=False,
+        )
+    except Exception as e:
+        return json.dumps(
+            {"ok": False, "error": "path_error", "message": str(e)},
+            ensure_ascii=False,
+        )
+
+    render_dpi = dpi if dpi and dpi > 0 else default_dpi()
+    result = await asyncio.to_thread(
+        pdf_evidence_crop_sync,
+        path,
+        session_root(sid),
+        page=page,
+        bbox=bbox,
+        full_page=full_page,
+        dpi=render_dpi,
+        caption=caption,
+        source_relative_path=relative_path.strip().lstrip("/"),
+    )
+    return json.dumps(result, ensure_ascii=False)
+
+
 if __name__ == "__main__":
     import asyncio
     import traceback
diff --git a/mcp_servers_std/session_sandbox/server.py b/mcp_servers_std/session_sandbox/server.py
index 9eebf813..a18c03db 100644
--- a/mcp_servers_std/session_sandbox/server.py
+++ b/mcp_servers_std/session_sandbox/server.py
@@ -24,7 +24,11 @@ def _sid() -> str:
 
 @mcp.tool()
 def sandbox_list_files(subdir: str = "uploads", recursive: bool = False) -> str:
-    """List files under uploads/, derived/, workspace/ o unpacked/. Con recursive=True include sottocartelle."""
+    """List files under uploads/, derived/, workspace/ (or nested paths like workspace/screenshots/).
+
+    Use subdir="uploads" to find uploaded PDFs. For nested folders, pass the full relative
+    path (e.g. subdir="workspace/screenshots") or set recursive=True on a top-level root.
+    """
     import json
     import mimetypes
 
diff --git a/scripts/dev-api.sh b/scripts/dev-api.sh
index 16c5731c..3e91b853 100755
--- a/scripts/dev-api.sh
+++ b/scripts/dev-api.sh
@@ -30,6 +30,9 @@ if [[ ! -f "$ROOT/mcp_servers/agent_db/db_manager.py" ]] && [[ -f "$ROOT/scripts
   echo "[AION] mcp_servers/ incompleta — sync da mcp_servers_std/"
   python "$ROOT/scripts/sync_mcp_servers.py"
 fi
+if [[ -f "$ROOT/scripts/merge_mcp_registry_from_std.py" ]]; then
+  python "$ROOT/scripts/merge_mcp_registry_from_std.py"
+fi
 echo "[AION] venv attivo: $(python -c 'import sys; print(sys.prefix)')"
 echo "[AION] Avvio API dev con --reload (watch: src, config, .env*)"
 
diff --git a/scripts/ensure_skill_packages.py b/scripts/ensure_skill_packages.py
index 152bda8f..fe42e820 100644
--- a/scripts/ensure_skill_packages.py
+++ b/scripts/ensure_skill_packages.py
@@ -49,7 +49,8 @@ def ensure_skill_packages(
     if SYNC_PROPRIETARY.is_file():
         rc = _run([py_exec, str(SYNC_PROPRIETARY), "--force"], dry_run=dry_run)
         if rc != 0:
-            print("[warn] sync_proprietary_config failed", file=sys.stderr)
+            print("[error] sync_proprietary_config failed", file=sys.stderr)
+            return rc
 
     if SYNC_MCP.is_file():
         cmd = [py_exec, str(SYNC_MCP)]
diff --git a/scripts/merge_mcp_registry_from_std.py b/scripts/merge_mcp_registry_from_std.py
new file mode 100644
index 00000000..6608baee
--- /dev/null
+++ b/scripts/merge_mcp_registry_from_std.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""
+Merge missing MCP server entries from config_std/mcp_registry.yaml into config/mcp_registry.yaml.
+
+config/mcp_registry.yaml is never force-overwritten by sync_config (local customizations).
+This script adds only *new* server slugs from the std template so upgrades ship new builtins
+(e.g. geocoding) without clobbering installed marketplace servers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import yaml
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+from src.mcp_registry_io import load_registry_file  # noqa: E402
+
+_SKIP_KEYS = frozenset({"_removed"})
+
+
+def merge_mcp_registry_from_std(
+    *,
+    root: Path | None = None,
+    dry_run: bool = False,
+) -> list[str]:
+    root = root or _REPO_ROOT
+    std_path = root / "config_std" / "mcp_registry.yaml"
+    dst_path = root / "config" / "mcp_registry.yaml"
+
+    if not std_path.is_file():
+        print(f"ERRORE: template non trovato: {std_path}")
+        sys.exit(1)
+
+    std = load_registry_file(str(std_path))
+    if dst_path.is_file():
+        local = load_registry_file(str(dst_path))
+    else:
+        local = {}
+        if not dry_run:
+            dst_path.parent.mkdir(parents=True, exist_ok=True)
+            dst_path.write_text(
+                "# Local MCP registry (merged from config_std on first run)\n",
+                encoding="utf-8",
+            )
+
+    missing = [
+        slug
+        for slug in sorted(std.keys())
+        if slug not in _SKIP_KEYS and slug not in local
+    ]
+    if not missing:
+        print("MCP registry: nessuna voce mancante da config_std.")
+        return []
+
+    print(f"MCP registry: aggiungo {len(missing)} voce/i da config_std: {', '.join(missing)}")
+    if dry_run:
+        return missing
+
+    blocks: list[str] = []
+    for slug in missing:
+        payload = {slug: std[slug]}
+        block = yaml.safe_dump(
+            payload,
+            allow_unicode=True,
+            sort_keys=False,
+            default_flow_style=False,
+        ).rstrip()
+        blocks.append(block)
+
+    separator = "\n\n" if dst_path.stat().st_size > 0 else ""
+    with dst_path.open("a", encoding="utf-8") as fh:
+        if separator:
+            fh.write(separator)
+        fh.write("\n\n".join(blocks))
+        fh.write("\n")
+
+    return missing
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Mostra le voci che verrebbero aggiunte senza scrivere.",
+    )
+    args = ap.parse_args()
+    merge_mcp_registry_from_std(dry_run=args.dry_run)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/setup_core.py b/scripts/setup_core.py
index e8cf9085..bfdf643b 100644
--- a/scripts/setup_core.py
+++ b/scripts/setup_core.py
@@ -12,6 +12,7 @@
 SETUP_PY = ROOT / "scripts" / "setup_aion_env.py"
 SYNC_CONFIG = ROOT / "scripts" / "sync_config.py"
 SYNC_MCP_SERVERS = ROOT / "scripts" / "sync_mcp_servers.py"
+MERGE_MCP_REGISTRY = ROOT / "scripts" / "merge_mcp_registry_from_std.py"
 SYNC_RUNTIME_ENV = ROOT / "scripts" / "sync_runtime_env.py"
 RUNTIME_EXTRAS = ROOT / "scripts" / "runtime_extras_setup.py"
 ENSURE_SKILL_PACKAGES = ROOT / "scripts" / "ensure_skill_packages.py"
@@ -119,6 +120,10 @@ def main() -> int:
             rc = _run([py_exec, str(SYNC_MCP_SERVERS)])
             if rc != 0:
                 return rc
+            if MERGE_MCP_REGISTRY.is_file():
+                rc = _run([py_exec, str(MERGE_MCP_REGISTRY)])
+                if rc != 0:
+                    print("[warn] merge_mcp_registry_from_std failed", file=sys.stderr)
             if SYNC_RUNTIME_ENV.is_file():
                 rc = _run([py_exec, str(SYNC_RUNTIME_ENV)])
                 if rc != 0:
diff --git a/scripts/sync_proprietary_config.py b/scripts/sync_proprietary_config.py
index 0b4c285d..f0657b86 100755
--- a/scripts/sync_proprietary_config.py
+++ b/scripts/sync_proprietary_config.py
@@ -112,6 +112,11 @@ def sync_proprietary_config(
         f"\nSync proprietario completato. "
         f"Copiati: {copied}  Sovrascritti: {overwritten}  Saltati: {skipped}\n"
     )
+    if copied == 0 and skipped > 0 and not force:
+        print(
+            "Suggerimento: nuovi file in config_proprietary/ non copiati (modalità safe). "
+            "Esegui: python scripts/sync_proprietary_config.py --force\n"
+        )
     return 0
 
 
diff --git a/scripts/upgrade_core.py b/scripts/upgrade_core.py
index 1616a965..b59ed62d 100644
--- a/scripts/upgrade_core.py
+++ b/scripts/upgrade_core.py
@@ -1686,6 +1686,7 @@ def main() -> int:
             ROOT / "scripts/setup_core.py",
             ROOT / "scripts/sync_config.py",
             ROOT / "scripts/sync_mcp_servers.py",
+            ROOT / "scripts/merge_mcp_registry_from_std.py",
             ROOT / "scripts/init_unified_db.py",
             ROOT / "scripts/check_env_example_coverage.py",
         ]
diff --git a/src/agent_pipeline.py b/src/agent_pipeline.py
index 49a26082..ed44a17d 100644
--- a/src/agent_pipeline.py
+++ b/src/agent_pipeline.py
@@ -645,21 +645,110 @@ def _format_attachments_block(
                     "You MUST read, analyze, and consider ALL of these newly uploaded documents to answer the current request. "
                     "CRITICAL RULES:\n"
                     "- NEVER process documents in parallel\n"
-                    "- ALWAYS process documents sequentially by using OCR tool.\n"
-                    "- Call ocr_file on one document at a time\n"
-                    "- Wait for the ocr_file call to complete before processing the next document\n"
-                    "- Do not ignore any of these newly uploaded documents\n"
-                    "Ensure you use your tools (like read_file, ocr, or custom scripts) to inspect all of them."
+                    "- For PDFs, check the extraction manifest below before calling doc_ingest\n"
+                    "- Process documents sequentially\n"
+                    "- Do not ignore any of these newly uploaded documents"
                 )
             else:
                 lines.append(
                     "IMPORTANT: A new document has been uploaded in this prompt. "
                     "You MUST read, analyze, and consider this document to answer the current request."
-                    "Always use OCR tools to read the document."
-                    "If OCR tools are not available, try to read the document anyway using any "
-                    "available tool."
                 )
 
+            from src.tools.doc_auto_ingest import load_manifest
+            from src.tools.doc_ingest import slugify_document_name
+            from src.tools.office_auto_convert import (
+                load_conversion_manifest,
+                retry_legacy_word_conversion,
+            )
+
+            for a in new_files:
+                rp = a.get("relative_path", "")
+                mime = (a.get("mime") or "").lower()
+                if not mime.startswith("application/pdf") and not rp.lower().endswith(
+                    ".pdf"
+                ):
+                    continue
+                slug = slugify_document_name(a.get("original_name") or Path(rp).name)
+                manifest = load_manifest(self.session_id, rp)
+                if manifest and manifest.get("ok"):
+                    lines.append(f"\n### PDF extraction ready: `{slug}`")
+                    lines.append(
+                        f"- pages_total: {manifest.get('pages_total')}, "
+                        f"written: {manifest.get('pages_written')}, "
+                        f"partial: {manifest.get('partial')}"
+                    )
+                    if manifest.get("partial") and manifest.get("resume_from"):
+                        lines.append(
+                            f"- INCOMPLETE: call doc_ingest(first_page={manifest['resume_from']}) to resume"
+                        )
+                    if manifest.get("empty_pages_count"):
+                        lines.append(
+                            f"- empty_pages (no text layer): {manifest.get('empty_pages_count')} "
+                            "— use doc_ingest(ocr_mode='auto') or ocr_file on those pages"
+                        )
+                    excerpt = (manifest.get("first_page_excerpt") or "").strip()
+                    if excerpt:
+                        lines.append(f"- first_page_excerpt: {excerpt[:300]}")
+                    hint = manifest.get("grep_hint") or (
+                        f"sandbox_grep_content(pattern=..., relative_root='derived', "
+                        f"glob_filter='docs/{slug}/pages/*.txt')"
+                    )
+                    lines.append(f"- search: {hint}")
+                elif mime.startswith("application/pdf") or rp.lower().endswith(".pdf"):
+                    lines.append(
+                        f"\n### PDF `{slug}`: extraction in progress or not started. "
+                        "If pages are missing after a few seconds, call doc_ingest(relative_path=...)."
+                    )
+
+                on = (a.get("original_name") or Path(rp).name).lower()
+                is_legacy = (
+                    a.get("legacy_word")
+                    or on.endswith(".doc")
+                    or on.endswith(".dot")
+                    or (mime or "").startswith("application/msword")
+                )
+                if is_legacy:
+                    conv = a.get("converted_docx_path") or ""
+                    status = a.get("conversion_status") or ""
+                    manifest = load_conversion_manifest(self.session_id, rp)
+                    if manifest:
+                        conv = conv or str(manifest.get("converted_docx_path") or "")
+                        status = status or str(manifest.get("conversion_status") or "")
+                    elif not conv and not status:
+                        retried = retry_legacy_word_conversion(self.session_id, rp)
+                        if retried.get("conversion_status") == "ok":
+                            conv = str(retried.get("converted_docx_path") or "")
+                            status = "ok"
+                    if conv and status == "ok":
+                        lines.append(f"\n### Legacy Word → DOCX ready for `{on}`")
+                        lines.append(
+                            f"- Original (binary .doc): `{rp}` — do NOT unpack or docx2txt on this file"
+                        )
+                        lines.append(
+                            f"- **Use this path for editing**: `{conv}` (OpenXML .docx)"
+                        )
+                        lines.append(
+                            "- Workflow: `skill_view('docx')` then unpack/edit/pack on the .docx path"
+                        )
+                    elif status == "unavailable":
+                        lines.append(
+                            f"\n### Legacy Word `{on}`: conversion unavailable on server "
+                            "(LibreOffice/soffice missing). Ask admin to install LibreOffice "
+                            "or set AION_SOFFICE_PATH."
+                        )
+                    elif status == "failed":
+                        err = a.get("conversion_error") or "unknown error"
+                        lines.append(
+                            f"\n### Legacy Word `{on}`: auto-conversion failed ({err}). "
+                            "Re-upload after fixing the file or convert manually to .docx."
+                        )
+                    else:
+                        lines.append(
+                            f"\n### Legacy Word `{on}`: conversion pending or not started. "
+                            "Wait a moment; the server converts .doc → .docx on upload."
+                        )
+
             if old_files:
                 lines.append(
                     "NOTE: The historical files listed above are available in your sandbox but were uploaded in previous turns. "
diff --git a/src/api/main.py b/src/api/main.py
index dc9a10fe..8e88c303 100644
--- a/src/api/main.py
+++ b/src/api/main.py
@@ -599,6 +599,9 @@ class AttachmentRef(BaseModel):
     relative_path: str
     original_name: Optional[str] = None
     mime: Optional[str] = None
+    converted_docx_path: Optional[str] = None
+    legacy_word: Optional[bool] = None
+    conversion_status: Optional[str] = None
 
 
 ReasoningEffort = Literal["min", "medium", "max"]
diff --git a/src/api/session_uploads.py b/src/api/session_uploads.py
index 72b84b2e..6b91b9cf 100644
--- a/src/api/session_uploads.py
+++ b/src/api/session_uploads.py
@@ -13,6 +13,8 @@
 from sse_starlette.sse import EventSourceResponse
 
 from src.session_workspace import list_dir, save_upload
+from src.tools.doc_auto_ingest import schedule_auto_ingest
+from src.tools.office_auto_convert import apply_legacy_word_conversion
 from .auth_login import ChatAuthIdentity, require_chat_auth
 
 logger = logging.getLogger(__name__)
@@ -69,6 +71,8 @@ async def upload_session_files(
             for f in files:
                 data = await f.read()
                 meta = save_upload(session_id, f.filename or "upload", data)
+                meta = await apply_legacy_word_conversion(session_id, meta)
+                schedule_auto_ingest(session_id, meta)
                 out.append(meta)
 
             logger.info(
diff --git a/src/api/v1/chat.py b/src/api/v1/chat.py
index 4655af8e..a4194b30 100644
--- a/src/api/v1/chat.py
+++ b/src/api/v1/chat.py
@@ -192,6 +192,9 @@ class AttachmentRef(BaseModel):
     relative_path: str
     original_name: Optional[str] = None
     mime: Optional[str] = None
+    converted_docx_path: Optional[str] = None
+    legacy_word: Optional[bool] = None
+    conversion_status: Optional[str] = None
 
 
 class ChatStreamBody(BaseModel):
diff --git a/src/api/v1/files.py b/src/api/v1/files.py
index bedfd7e6..a220e02a 100644
--- a/src/api/v1/files.py
+++ b/src/api/v1/files.py
@@ -11,6 +11,8 @@
 from src.api.auth import AuthContext, Scope, require_scope
 from src.session_workspace import save_upload
 from src.storage import get_storage_backend
+from src.tools.doc_auto_ingest import schedule_auto_ingest
+from src.tools.office_auto_convert import apply_legacy_word_conversion
 
 router = APIRouter()
 
@@ -29,6 +31,8 @@ async def upload_files(
     for f in files:
         data = await f.read()
         meta = save_upload(conversation_id, f.filename or "upload", data)
+        meta = await apply_legacy_word_conversion(conversation_id, meta)
+        schedule_auto_ingest(conversation_id, meta)
         key = f"{tenant}/conversations/{conversation_id}/uploads/{uuid.uuid4().hex[:12]}_{meta.get('name', 'file')}"
         try:
             backend.put_bytes(key, data, meta.get("mime") or "application/octet-stream")
diff --git a/src/benchmarks/cli.py b/src/benchmarks/cli.py
index 16709cbb..7fa3c252 100644
--- a/src/benchmarks/cli.py
+++ b/src/benchmarks/cli.py
@@ -12,6 +12,7 @@
 
 from .general_agent import run_general_agent_benchmark
 from .longmemeval_v2.runner import run_longmemeval_v2_small
+from .long_document.runner import run_long_document_pipeline_eval
 from .mnemos_bench.runner import run_mnemos_bench
 from .registry import register_benchmark, BenchmarkSpec, catalog_entries
 from .longmemeval_v2.prepare import is_dataset_ready
@@ -45,6 +46,15 @@ def _register_defaults() -> None:
         ),
         _run_mnemos_wrapper,
     )
+    register_benchmark(
+        BenchmarkSpec(
+            id="long_document_pipeline",
+            title="Long document pipeline eval",
+            description="doc_ingest + grep golden cases (no LLM); see evals/long_document/cases/",
+            tier="ci",
+        ),
+        _run_long_document_wrapper,
+    )
 
 
 async def _run_general_wrapper(
@@ -95,6 +105,19 @@ async def _run_mnemos_wrapper(
     )
 
 
+async def _run_long_document_wrapper(
+    run_id: str,
+    profile_name: str,
+    config: dict | None = None,
+    dataset_path: str | None = None,
+    **_: object,
+) -> dict:
+    del run_id, profile_name, config  # pipeline eval is profile-agnostic
+    if not dataset_path:
+        dataset_path = "evals/long_document/cases/synthetic_smoke.yaml"
+    return await run_long_document_pipeline_eval(dataset_path)
+
+
 async def _async_main(args: argparse.Namespace) -> int:
     set_event_loop(asyncio.get_running_loop())
     _register_defaults()
@@ -139,6 +162,9 @@ async def _async_main(args: argparse.Namespace) -> int:
                 dataset_path=dataset,
                 config=config,
             )
+        elif args.benchmark == "long_document_pipeline":
+            dataset = args.dataset or "evals/long_document/cases/synthetic_smoke.yaml"
+            metrics = await run_long_document_pipeline_eval(dataset)
         else:
             raise ValueError(f"unknown benchmark: {args.benchmark}")
         if (
diff --git a/src/benchmarks/long_document/__init__.py b/src/benchmarks/long_document/__init__.py
new file mode 100644
index 00000000..ea91672b
--- /dev/null
+++ b/src/benchmarks/long_document/__init__.py
@@ -0,0 +1,5 @@
+"""Long-document benchmark package."""
+
+from .runner import run_long_document_pipeline_eval
+
+__all__ = ["run_long_document_pipeline_eval"]
diff --git a/src/benchmarks/long_document/runner.py b/src/benchmarks/long_document/runner.py
new file mode 100644
index 00000000..0efe3792
--- /dev/null
+++ b/src/benchmarks/long_document/runner.py
@@ -0,0 +1,215 @@
+"""Long-document eval runner: doc_ingest + grep against YAML golden cases."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from src.tools.doc_ingest import ingest_document
+
+from .scoring import score_identity_gate, score_required_hits
+from .synthetic import build_rumore_decreto_pdf
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+DEFAULT_CASES_DIR = REPO_ROOT / "evals" / "long_document" / "cases"
+
+
+def load_dataset(path: str | Path) -> dict[str, Any]:
+    p = Path(path)
+    raw = p.read_text(encoding="utf-8")
+    if p.suffix in {".yaml", ".yml"}:
+        data = yaml.safe_load(raw) or {}
+    else:
+        data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError(f"dataset must be a mapping: {p}")
+    return data
+
+
+def _resolve_pdf(case: dict[str, Any], work_dir: Path) -> Path | None:
+    pdf = case.get("pdf") or {}
+    source = str(pdf.get("source") or "synthetic")
+
+    if source == "synthetic":
+        profile = str(pdf.get("profile") or "rumore_decreto")
+        if profile != "rumore_decreto":
+            raise ValueError(f"unknown synthetic pdf profile: {profile}")
+        out = work_dir / str(pdf.get("filename") or "synthetic_decreto.pdf")
+        return build_rumore_decreto_pdf(
+            out,
+            pages=int(pdf.get("pages") or 200),
+            prescription_page=int(pdf.get("prescription_page") or 101),
+            pmc_page=int(pdf.get("pmc_page") or 150),
+        )
+
+    if source == "env":
+        env_name = str(pdf.get("path_env") or "AION_EVAL_LONG_DOC_PDF")
+        raw = os.environ.get(env_name, "").strip()
+        if not raw:
+            return None
+        path = Path(raw).expanduser()
+        return path if path.is_file() else None
+
+    if source == "path":
+        path = Path(str(pdf.get("path") or "")).expanduser()
+        return path if path.is_file() else None
+
+    raise ValueError(f"unsupported pdf.source: {source}")
+
+
+async def _ingest_until_complete(
+    pdf_path: Path,
+    session_root: Path,
+    ingest_cfg: dict[str, Any],
+) -> dict[str, Any]:
+    """Call doc_ingest until ``partial`` is false (resume-friendly)."""
+    first = int(ingest_cfg.get("first_page") or 1)
+    last = int(ingest_cfg.get("last_page") or 0)
+    budget = float(ingest_cfg.get("budget_sec") or 600)
+    ocr_mode = str(ingest_cfg.get("ocr_mode") or "never")
+    force = bool(ingest_cfg.get("force") or False)
+    write_full = bool(ingest_cfg.get("write_full") or False)
+
+    manifest: dict[str, Any] = {"ok": False}
+    resume_from = first
+    for _ in range(50):
+        manifest = await ingest_document(
+            pdf_path,
+            session_root,
+            first_page=resume_from,
+            last_page=last,
+            ocr_mode=ocr_mode,
+            budget_sec=budget,
+            force=force,
+            write_full=write_full,
+        )
+        if not manifest.get("ok"):
+            return manifest
+        if not manifest.get("partial"):
+            return manifest
+        nxt = manifest.get("resume_from")
+        if not nxt or int(nxt) <= resume_from:
+            return manifest
+        resume_from = int(nxt)
+    manifest["warning"] = "ingest stopped after 50 resume iterations"
+    return manifest
+
+
+async def run_pipeline_case(
+    case: dict[str, Any],
+    *,
+    work_dir: Path,
+) -> dict[str, Any]:
+    """Run ingest + scoring for a single YAML case."""
+    case_id = str(case.get("id") or "case")
+    pdf_path = _resolve_pdf(case, work_dir)
+    if pdf_path is None:
+        skipped = bool(case.get("skip_if_pdf_missing", True))
+        return {
+            "case_id": case_id,
+            "skipped": skipped,
+            "reason": "pdf not available (set env or path)",
+            "recall": None,
+            "passed": None if skipped else False,
+        }
+
+    session_root = work_dir / "session"
+    session_root.mkdir(parents=True, exist_ok=True)
+    uploads = session_root / "uploads"
+    uploads.mkdir(parents=True, exist_ok=True)
+    linked = uploads / pdf_path.name
+    if not linked.exists():
+        try:
+            linked.hardlink_to(pdf_path)
+        except OSError:
+            import shutil
+
+            shutil.copy2(pdf_path, linked)
+
+    ingest_cfg = case.get("ingest") or {}
+    manifest = await _ingest_until_complete(linked, session_root, ingest_cfg)
+    if not manifest.get("ok"):
+        return {
+            "case_id": case_id,
+            "skipped": False,
+            "passed": False,
+            "recall": 0.0,
+            "error": manifest,
+        }
+
+    slug = str(manifest["slug"])
+    hit_score = score_required_hits(
+        session_root,
+        slug,
+        list(case.get("required_hits") or []),
+    )
+    identity_score = score_identity_gate(manifest, case.get("identity") or {})
+
+    passed = (
+        hit_score["recall"] >= float(case.get("min_recall") or 1.0)
+        and identity_score["passed"]
+    )
+    return {
+        "case_id": case_id,
+        "skipped": False,
+        "passed": passed,
+        "recall": hit_score["recall"],
+        "slug": slug,
+        "manifest": {
+            "pages_total": manifest.get("pages_total"),
+            "pages_written": manifest.get("pages_written"),
+            "partial": manifest.get("partial"),
+            "title_guess": manifest.get("title_guess"),
+        },
+        "hits": hit_score,
+        "identity": identity_score,
+    }
+
+
+async def run_long_document_pipeline_eval(
+    dataset_path: str | Path,
+    *,
+    work_dir: Path | None = None,
+) -> dict[str, Any]:
+    """Evaluate all cases in a dataset directory or single YAML file."""
+    path = Path(dataset_path)
+    if path.is_dir():
+        case_files = sorted(path.glob("*.yaml")) + sorted(path.glob("*.yml"))
+    else:
+        case_files = [path]
+
+    root_work = work_dir or (REPO_ROOT / "data" / "eval_runs" / "long_document")
+    root_work.mkdir(parents=True, exist_ok=True)
+
+    results: list[dict[str, Any]] = []
+    for case_file in case_files:
+        dataset = load_dataset(case_file)
+        cases = dataset.get("cases")
+        if cases is None:
+            cases = [dataset]
+        for case in cases:
+            case_work = root_work / str(case.get("id") or case_file.stem)
+            case_work.mkdir(parents=True, exist_ok=True)
+            row = await run_pipeline_case(case, work_dir=case_work)
+            row["dataset"] = str(case_file)
+            results.append(row)
+
+    scored = [r for r in results if not r.get("skipped")]
+    skipped = [r for r in results if r.get("skipped")]
+    passed = [r for r in scored if r.get("passed")]
+    recall_vals = [float(r["recall"]) for r in scored if r.get("recall") is not None]
+
+    metrics = {
+        "case_count": len(results),
+        "scored_count": len(scored),
+        "skipped_count": len(skipped),
+        "passed_count": len(passed),
+        "accuracy_overall": (len(passed) / len(scored)) if scored else 1.0,
+        "mean_recall": (sum(recall_vals) / len(recall_vals)) if recall_vals else 1.0,
+        "results": results,
+    }
+    return metrics
diff --git a/src/benchmarks/long_document/scoring.py b/src/benchmarks/long_document/scoring.py
new file mode 100644
index 00000000..997d40df
--- /dev/null
+++ b/src/benchmarks/long_document/scoring.py
@@ -0,0 +1,149 @@
+"""Scoring helpers for long-document pipeline evals (ingest + grep, no LLM)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from src.tools.session_fs_tools import grep_content
+
+
+def page_no_from_hit_file(file_path: str) -> int | None:
+    """Extract page number from ``derived/docs/<slug>/pages/p0101.txt``."""
+    name = Path(file_path.replace("\\", "/")).name
+    m = re.match(r"^p(\d{4})\.txt$", name)
+    return int(m.group(1)) if m else None
+
+
+def grep_pages(
+    session_root: Path,
+    slug: str,
+    pattern: str,
+    *,
+    max_matches: int = 500,
+) -> list[dict]:
+    return grep_content(
+        session_root,
+        session_root / "derived",
+        pattern,
+        glob_filter=f"docs/{slug}/pages/*.txt",
+        max_matches=max_matches,
+    )
+
+
+def score_required_hits(
+    session_root: Path,
+    slug: str,
+    required_hits: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Score PIC/PMC-style expectations after ``doc_ingest``."""
+    details: list[dict[str, Any]] = []
+    passed = 0
+
+    for item in required_hits:
+        label = str(item.get("label") or item.get("id") or "hit")
+        pattern = str(item["grep_pattern"])
+        expected_page = item.get("page")
+        must_contain = [str(s) for s in (item.get("must_contain") or [])]
+
+        hits = grep_pages(session_root, slug, pattern)
+        page_hits = [h for h in hits if page_no_from_hit_file(h["file"]) is not None]
+        on_page = (
+            [
+                h
+                for h in page_hits
+                if page_no_from_hit_file(h["file"]) == int(expected_page)
+            ]
+            if expected_page is not None
+            else page_hits
+        )
+
+        row: dict[str, Any] = {
+            "label": label,
+            "grep_pattern": pattern,
+            "expected_page": expected_page,
+            "hit_count": len(hits),
+            "hits_on_expected_page": len(on_page),
+            "passed": False,
+            "reason": "",
+        }
+
+        if not hits:
+            row["reason"] = "no grep hits"
+            details.append(row)
+            continue
+
+        if expected_page is not None and not on_page:
+            found_pages = sorted(
+                {page_no_from_hit_file(h["file"]) for h in page_hits} - {None}
+            )
+            row["reason"] = f"hits on pages {found_pages}, expected {expected_page}"
+            details.append(row)
+            continue
+
+        target_hit = on_page[0] if on_page else hits[0]
+        page_no = page_no_from_hit_file(target_hit["file"])
+        page_path = session_root / target_hit["file"]
+        body = page_path.read_text(encoding="utf-8", errors="replace")
+        missing = [s for s in must_contain if s not in body]
+        if missing:
+            row["reason"] = f"missing substrings on page {page_no}: {missing}"
+            row["page"] = page_no
+            details.append(row)
+            continue
+
+        row["passed"] = True
+        row["page"] = page_no
+        row["file"] = target_hit["file"]
+        passed += 1
+        details.append(row)
+
+    total = len(required_hits)
+    return {
+        "required_total": total,
+        "required_passed": passed,
+        "recall": (passed / total) if total else 1.0,
+        "details": details,
+    }
+
+
+def score_identity_gate(
+    manifest: dict[str, Any], identity: dict[str, Any]
+) -> dict[str, Any]:
+    """Check title/excerpt against must / must-not lists."""
+    haystack = " ".join(
+        [
+            str(manifest.get("title_guess") or ""),
+            str(manifest.get("first_page_excerpt") or ""),
+            str(manifest.get("source") or ""),
+        ]
+    ).lower()
+
+    must = [str(s).lower() for s in (identity.get("must_contain") or [])]
+    must_not = [str(s).lower() for s in (identity.get("must_not_contain") or [])]
+
+    missing = [s for s in must if s not in haystack]
+    forbidden = [s for s in must_not if s in haystack]
+    passed = not missing and not forbidden
+    return {
+        "passed": passed,
+        "missing": missing,
+        "forbidden": forbidden,
+    }
+
+
+def score_agent_output(text: str, expectations: dict[str, Any]) -> dict[str, Any]:
+    """Lightweight substring checks on a final agent answer (opt-in LLM eval)."""
+    low = (text or "").lower()
+    must = [str(s) for s in (expectations.get("output_must_contain") or [])]
+    must_not = [str(s) for s in (expectations.get("output_must_not_contain") or [])]
+
+    missing = [s for s in must if s.lower() not in low]
+    forbidden = [s for s in must_not if s.lower() in low]
+    passed = not missing and not forbidden
+    return {
+        "passed": passed,
+        "missing": missing,
+        "forbidden": forbidden,
+    }
diff --git a/src/benchmarks/long_document/synthetic.py b/src/benchmarks/long_document/synthetic.py
new file mode 100644
index 00000000..286bbd40
--- /dev/null
+++ b/src/benchmarks/long_document/synthetic.py
@@ -0,0 +1,48 @@
+"""Synthetic PDF fixtures for long-document eval cases (no external assets)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_FILLER = (
+    "Commissione Istruttoria IPPC - Centrale termoelettrica - testo di riempimento "
+    "per riprodurre la densita tipica di una pagina di decreto autorizzativo."
+)
+
+
+def build_rumore_decreto_pdf(
+    path: Path,
+    *,
+    pages: int = 200,
+    prescription_page: int = 101,
+    pmc_page: int = 150,
+    blank_pages: frozenset[int] | None = None,
+) -> Path:
+    """Born-digital decree-like PDF with PIC + PMC noise markers on known pages."""
+    from reportlab.lib.pagesizes import A4
+    from reportlab.pdfgen import canvas
+
+    blanks = blank_pages if blank_pages is not None else frozenset({7, 42})
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    c = canvas.Canvas(str(path), pagesize=A4)
+    for page_no in range(1, pages + 1):
+        if page_no not in blanks:
+            c.drawString(72, 780, f"PAGINA {page_no} marcatore acustico")
+            for row, offset in enumerate(range(750, 690, -15)):
+                c.drawString(72, offset, f"{_FILLER} riga {row}")
+            if page_no == prescription_page:
+                c.drawString(
+                    72,
+                    660,
+                    "[53] Il Gestore e tenuto al rispetto dei valori limite di rumore",
+                )
+                c.drawString(72, 645, "8.9 Rumore - Parere Istruttorio Conclusivo")
+            if page_no == pmc_page:
+                c.drawString(72, 660, "Piano di Monitoraggio e Controllo (PMC)")
+                c.drawString(
+                    72, 645, "Tabella parametri Rumore e monitoraggio acustico"
+                )
+        c.showPage()
+    c.save()
+    return path
diff --git a/src/main.py b/src/main.py
index 5c8aeec0..f532e6df 100644
--- a/src/main.py
+++ b/src/main.py
@@ -621,17 +621,11 @@ def _emit_tool_outcome(*, is_error: bool, body: str) -> str:
             )
             err_text = format_exception_for_tool(tool_name, e)
             if isinstance(e, TimeoutError):
-                pg_cap = os.getenv("AION_PG_QUERY_TIMEOUT_SEC", "60")
+                from src.runtime.mcp_tool_result import build_timeout_message
+
                 err_text = format_exception_for_tool(
                     tool_name,
-                    TimeoutError(
-                        f"Query timed out ({server_name}/{tool_name}). "
-                        f"PostgreSQL cap AION_PG_QUERY_TIMEOUT_SEC={pg_cap}s; "
-                        f"MCP bridge cap AION_MCP_TOOL_RESULT_TIMEOUT="
-                        f"{os.getenv('AION_MCP_TOOL_RESULT_TIMEOUT', '120')}s. "
-                        "Heavy JOINs may need indexes or a narrower filter (e.g. codice_ditta). "
-                        "The MCP worker was recycled; retry with a simpler query."
-                    ),
+                    TimeoutError(build_timeout_message(server_name, tool_name)),
                 )
             mark_sql_exec_tool_failed(session_id, tool_name)
 
diff --git a/src/runtime/mcp_tool_result.py b/src/runtime/mcp_tool_result.py
index 5be4d026..476a7e12 100644
--- a/src/runtime/mcp_tool_result.py
+++ b/src/runtime/mcp_tool_result.py
@@ -180,3 +180,45 @@ def format_exception_for_tool(tool_name: str, exc: BaseException) -> str:
         "tool": tool_name,
     }
     return json.dumps(payload, ensure_ascii=False)
+
+
+_DOC_TOOL_NAMES = frozenset({"ocr_file", "doc_ingest"})
+
+
+def build_timeout_message(server_name: str, tool_name: str) -> str:
+    """Timeout guidance tailored to the tool family.
+
+    A generic message that mentions PostgreSQL derails the model when the tool
+    that timed out is an OCR or document call, so each family gets the remedy
+    that actually applies to it.
+    """
+    import os
+
+    from src.runtime.pg_query_guard import is_postgres_query_tool
+
+    mcp_cap = os.getenv("AION_MCP_TOOL_RESULT_TIMEOUT", "120")
+    head = f"Tool timed out ({server_name}/{tool_name}). MCP bridge cap AION_MCP_TOOL_RESULT_TIMEOUT={mcp_cap}s."
+
+    if is_postgres_query_tool(server_name, tool_name):
+        pg_cap = os.getenv("AION_PG_QUERY_TIMEOUT_SEC", "60")
+        return (
+            f"{head} PostgreSQL cap AION_PG_QUERY_TIMEOUT_SEC={pg_cap}s. "
+            "Heavy JOINs may need indexes or a narrower filter (e.g. codice_ditta). "
+            "The MCP worker was recycled; retry with a simpler query."
+        )
+
+    base_tool = (tool_name or "").split("-")[-1]
+    if base_tool in _DOC_TOOL_NAMES:
+        return (
+            f"{head} Document extraction is too slow for the whole file in one call. "
+            "Use doc_ingest(relative_path, first_page=..., last_page=...) to process a page "
+            "range: it writes one file per page under derived/docs/<slug>/pages/, skips pages "
+            "already done, and can be called again to resume. Do NOT retry the same call "
+            "unchanged, and do NOT fall back to a custom extraction script."
+        )
+
+    return (
+        f"{head} The call exceeded the budget. Retry with a narrower scope "
+        "(fewer items, a smaller range, or a more specific filter) rather than repeating "
+        "the same arguments."
+    )
diff --git a/src/session_workspace.py b/src/session_workspace.py
index 05f4dafe..c1f27274 100644
--- a/src/session_workspace.py
+++ b/src/session_workspace.py
@@ -151,44 +151,66 @@ def list_dir(session_id: str, subdir: str = "uploads") -> List[Dict[str, Any]]:
     sub = subdir.strip().replace("\\", "/").strip("/")
     if sub == ".":
         sub = ""
-    if sub not in LISTABLE_SUBDIRS:
+    if sub in LISTABLE_SUBDIRS:
+        if sub == "tool_results":
+            return _list_tool_results_files(session_id)
+        d = root / sub
+        if not d.is_dir():
+            return []
+        all_names = set(p.name for p in d.iterdir() if p.is_file())
+        out: List[Dict[str, Any]] = []
+        for p in sorted(d.iterdir()):
+            if p.is_file():
+                if p.name.startswith("."):
+                    continue
+                if sub == "uploads":
+                    is_alias = False
+                    for name in all_names:
+                        if (
+                            name != p.name
+                            and name.endswith("_" + p.name)
+                            and len(name) == len(p.name) + 11
+                        ):
+                            is_alias = True
+                            break
+                    if is_alias:
+                        continue
+
+                rel = f"{subdir}/{p.name}".replace("\\", "/").lstrip("/")
+                mime, _ = mimetypes.guess_type(p.name)
+                out.append(
+                    {
+                        "name": p.name,
+                        "relative_path": rel,
+                        "size_bytes": p.stat().st_size,
+                        "mime": mime or "application/octet-stream",
+                    }
+                )
+        return out
+
+    # Nested paths under a known session root (e.g. workspace/screenshots).
+    top = sub.split("/", 1)[0]
+    if top not in SESSION_CONTENT_ROOTS - {""}:
         raise ValueError(
             f"subdir deve essere uno tra: {', '.join(sorted(LISTABLE_SUBDIRS))}"
         )
-    if sub == "tool_results":
-        return _list_tool_results_files(session_id)
     d = root / sub
     if not d.is_dir():
         return []
-    all_names = set(p.name for p in d.iterdir() if p.is_file())
-    out: List[Dict[str, Any]] = []
+    out = []
     for p in sorted(d.iterdir()):
-        if p.is_file():
-            if p.name.startswith("."):
-                continue
-            if sub == "uploads":
-                is_alias = False
-                for name in all_names:
-                    if (
-                        name != p.name
-                        and name.endswith("_" + p.name)
-                        and len(name) == len(p.name) + 11
-                    ):
-                        is_alias = True
-                        break
-                if is_alias:
-                    continue
-
-            rel = f"{subdir}/{p.name}".replace("\\", "/").lstrip("/")
-            mime, _ = mimetypes.guess_type(p.name)
-            out.append(
-                {
-                    "name": p.name,
-                    "relative_path": rel,
-                    "size_bytes": p.stat().st_size,
-                    "mime": mime or "application/octet-stream",
-                }
-            )
+        if not p.is_file() or p.name.startswith("."):
+            continue
+        rel = str(p.relative_to(root)).replace("\\", "/")
+        mime, _ = mimetypes.guess_type(p.name)
+        out.append(
+            {
+                "name": p.name,
+                "relative_path": rel,
+                "size_bytes": p.stat().st_size,
+                "mime": mime or "application/octet-stream",
+            }
+        )
     return out
 
 
diff --git a/src/test/test_config_std_profile_skills.py b/src/test/test_config_std_profile_skills.py
index 36658b1a..57591020 100644
--- a/src/test/test_config_std_profile_skills.py
+++ b/src/test/test_config_std_profile_skills.py
@@ -17,6 +17,40 @@ def _artifact_skill_loaded(reg: SkillRegistry) -> bool:
     return bool(reg.get_skill_full("artifact_protocol"))
 
 
+def _profiles() -> list[tuple[Path, dict]]:
+    profiles_dir = _repo_root() / "config_std" / "profiles"
+    out = []
+    for path in sorted(profiles_dir.glob("*.yaml")):
+        out.append((path, yaml.safe_load(path.read_text(encoding="utf-8")) or {}))
+    return out
+
+
+def test_long_document_protocol_skill_exists():
+    reg = SkillRegistry()
+    reg.reload()
+    assert reg.get_skill_full("long_document_protocol"), (
+        "config_std/skills/long_document_protocol.md must be loadable"
+    )
+
+
+def test_profiles_with_ocr_declare_long_document_protocol():
+    """A profile that can ingest documents must carry the protocol for long ones.
+
+    Without it the model falls back to ocr_file on the whole PDF, which times out.
+    """
+    # Image-only workflows do not need the multi-page protocol.
+    exempt = {"graphic_designer.yaml"}
+    for path, data in _profiles():
+        if path.name in exempt:
+            continue
+        if "ocr" not in (data.get("mcp_servers") or []):
+            continue
+        assert "long_document_protocol" in (data.get("skills") or []), (
+            f"{path.name} mounts the ocr MCP server but does not list "
+            "long_document_protocol"
+        )
+
+
 def test_config_std_profile_skills_resolve():
     reg = SkillRegistry()
     reg.reload()
diff --git a/src/test/test_doc_auto_ingest.py b/src/test/test_doc_auto_ingest.py
new file mode 100644
index 00000000..32346c7f
--- /dev/null
+++ b/src/test/test_doc_auto_ingest.py
@@ -0,0 +1,90 @@
+"""Tests for automatic PDF ingest on upload."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+from fastapi import UploadFile
+from io import BytesIO
+
+from src.benchmarks.long_document.synthetic import build_rumore_decreto_pdf
+from src.session_workspace import save_upload, session_root
+from src.tools.doc_auto_ingest import (
+    auto_ingest_enabled,
+    load_manifest,
+    run_auto_ingest_background,
+    schedule_auto_ingest,
+)
+from src.tools.doc_ingest import slugify_document_name
+
+
+@pytest.fixture()
+def data_dir(tmp_path, monkeypatch):
+    monkeypatch.setenv("AION_DATA_DIR", str(tmp_path))
+    return tmp_path
+
+
+@pytest.mark.asyncio
+async def test_run_auto_ingest_writes_pages(data_dir):
+    sid = "sess_auto_ingest"
+    pdf_bytes = BytesIO()
+    path = build_rumore_decreto_pdf(data_dir / "src.pdf", pages=30)
+    meta = save_upload(sid, "decreto.pdf", path.read_bytes())
+
+    await run_auto_ingest_background(sid, meta["relative_path"], meta["mime"])
+
+    slug = slugify_document_name("decreto.pdf")
+    pages = session_root(sid) / "derived" / "docs" / slug / "pages"
+    assert len(list(pages.glob("p*.txt"))) == 30
+
+    manifest = load_manifest(sid, meta["relative_path"])
+    assert manifest is not None
+    assert manifest.get("ok") is True
+    assert manifest.get("pages_total") == 30
+
+
+@pytest.mark.asyncio
+async def test_schedule_auto_ingest_skips_non_pdf(data_dir):
+    sid = "sess_txt"
+    meta = save_upload(sid, "note.txt", b"hello world")
+
+    async def _noop():
+        return None
+
+    # Should not raise; schedules only PDFs
+    schedule_auto_ingest(sid, meta)
+    await asyncio.sleep(0.05)
+    slug_dir = session_root(sid) / "derived" / "docs"
+    assert not slug_dir.exists() or not any(slug_dir.rglob("pages"))
+
+
+@pytest.mark.asyncio
+async def test_upload_endpoint_schedules_ingest(data_dir, monkeypatch):
+    monkeypatch.setenv("AION_DOC_AUTO_INGEST", "1")
+    from src.api.session_uploads import upload_session_files
+    from src.api.auth_login import ChatAuthIdentity
+
+    sid = "sess_upload_ep"
+    pdf = build_rumore_decreto_pdf(data_dir / "u.pdf", pages=15)
+    upload = UploadFile(filename="decreto.pdf", file=BytesIO(pdf.read_bytes()))
+
+    class _Auth:
+        identifier = "tester"
+
+    result = await upload_session_files(sid, files=[upload], _auth=_Auth())
+    assert len(result["files"]) == 1
+
+    # Background task needs a tick
+    await asyncio.sleep(0.5)
+
+    rel = result["files"][0]["relative_path"]
+    manifest = load_manifest(sid, rel)
+    assert manifest is not None
+    assert manifest.get("pages_total") == 15
+
+
+def test_auto_ingest_disabled_by_env(monkeypatch):
+    monkeypatch.setenv("AION_DOC_AUTO_INGEST", "0")
+    assert auto_ingest_enabled() is False
diff --git a/src/test/test_doc_ingest.py b/src/test/test_doc_ingest.py
new file mode 100644
index 00000000..5202ead0
--- /dev/null
+++ b/src/test/test_doc_ingest.py
@@ -0,0 +1,343 @@
+"""Deterministic coverage for src.tools.doc_ingest (no LLM, no MCP, no OCR service).
+
+The regression these tests protect against is the one seen in production: a
+200-page decree that could not be extracted, and a concatenated text file that
+grep silently skips once it grows past AION_GREP_MAX_FILE_BYTES.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from src.tools.doc_ingest import ingest_document, slugify_document_name
+
+PAGE_COUNT = 200
+# Sentinel reproducing the real task: a numbered prescription on a known page.
+PRESCRIPTION_PAGE = 101
+PRESCRIPTION_TEXT = "[53] Il Gestore e tenuto al rispetto dei valori limite di rumore"
+BLANK_PAGES = {7, 42}
+
+
+_FILLER = (
+    "Commissione Istruttoria IPPC - Centrale termoelettrica - testo di riempimento "
+    "per riprodurre la densita tipica di una pagina di decreto autorizzativo."
+)
+
+
+def _build_pdf(path: Path, pages: int = PAGE_COUNT) -> Path:
+    from reportlab.lib.pagesizes import A4
+    from reportlab.pdfgen import canvas
+
+    c = canvas.Canvas(str(path), pagesize=A4)
+    for page_no in range(1, pages + 1):
+        if page_no not in BLANK_PAGES:
+            c.drawString(72, 780, f"PAGINA {page_no} marcatore acustico")
+            # Real pages carry hundreds of characters; a sparse fixture would
+            # trip the missing-text-layer heuristic for the wrong reason.
+            for row, offset in enumerate(range(750, 690, -15)):
+                c.drawString(72, offset, f"{_FILLER} riga {row}")
+            if page_no == PRESCRIPTION_PAGE:
+                c.drawString(72, 660, PRESCRIPTION_TEXT)
+        c.showPage()
+    c.save()
+    return path
+
+
+@pytest.fixture(scope="module")
+def sample_pdf(tmp_path_factory) -> Path:
+    root = tmp_path_factory.mktemp("docsrc")
+    return _build_pdf(root / "08b3392800_DECRETOCOMPLETO.pdf")
+
+
+@pytest.fixture()
+def session_root(tmp_path) -> Path:
+    return tmp_path
+
+
+def _pages_dir(session_root: Path, slug: str) -> Path:
+    return session_root / "derived" / "docs" / slug / "pages"
+
+
+def test_slugify_strips_upload_prefix():
+    assert slugify_document_name("08b3392800_DECRETOCOMPLETO.pdf") == "decretocompleto"
+    assert slugify_document_name("esempio per ai.pdf") == "esempio_per_ai"
+    assert slugify_document_name("___.pdf") == "document"
+
+
+@pytest.mark.asyncio
+async def test_writes_one_file_per_page(sample_pdf, session_root):
+    manifest = await ingest_document(sample_pdf, session_root, budget_sec=600)
+
+    assert manifest["ok"] is True
+    assert manifest["partial"] is False
+    assert manifest["pages_total"] == PAGE_COUNT
+    assert manifest["pages_written"] == PAGE_COUNT
+
+    pages = sorted(_pages_dir(session_root, manifest["slug"]).glob("p*.txt"))
+    assert len(pages) == PAGE_COUNT
+    assert pages[0].name == "p0001.txt"
+    assert pages[-1].name == "p0200.txt"
+
+    target = _pages_dir(session_root, manifest["slug"]) / "p0101.txt"
+    assert "[53]" in target.read_text(encoding="utf-8")
+
+
+@pytest.mark.asyncio
+async def test_manifest_is_persisted_and_small(sample_pdf, session_root):
+    manifest = await ingest_document(sample_pdf, session_root, budget_sec=600)
+
+    on_disk = (
+        session_root / "derived" / "docs" / manifest["slug"] / "manifest.json"
+    ).read_text(encoding="utf-8")
+    assert json.loads(on_disk)["slug"] == manifest["slug"]
+    # Must stay well under the tool-offload threshold (8000 chars) so the model
+    # sees the manifest inline instead of a pointer to a file.
+    assert len(json.dumps(manifest, ensure_ascii=False)) < 4000
+
+
+@pytest.mark.asyncio
+async def test_page_files_stay_greppable(sample_pdf, session_root):
+    """Every page must sit below the grep size cap that silently skips files."""
+    from src.tools.session_fs_tools import _grep_max_file_bytes, grep_content
+
+    manifest = await ingest_document(sample_pdf, session_root, budget_sec=600)
+    pages_dir = _pages_dir(session_root, manifest["slug"])
+
+    cap = _grep_max_file_bytes()
+    assert all(p.stat().st_size < cap for p in pages_dir.glob("p*.txt"))
+
+    hits = grep_content(
+        session_root,
+        session_root / "derived",
+        "marcatore acustico",
+        glob_filter=f"docs/{manifest['slug']}/pages/*.txt",
+        max_matches=PAGE_COUNT + 10,
+    )
+    assert len(hits) == PAGE_COUNT - len(BLANK_PAGES)
+
+
+@pytest.mark.asyncio
+async def test_grep_hit_filename_carries_page_number(sample_pdf, session_root):
+    from src.tools.session_fs_tools import grep_content
+
+    manifest = await ingest_document(sample_pdf, session_root, budget_sec=600)
+    hits = grep_content(
+        session_root,
+        session_root / "derived",
+        r"\[53\]",
+        glob_filter=f"docs/{manifest['slug']}/pages/*.txt",
+    )
+    assert len(hits) == 1
+    assert hits[0]["file"].endswith(f"p{PRESCRIPTION_PAGE:04d}.txt")
+
+
+@pytest.mark.asyncio
+async def test_partial_run_reports_resume_point(sample_pdf, session_root):
+    ticks = iter(range(0, 10_000))
+    manifest = await ingest_document(
+        sample_pdf, session_root, budget_sec=5, clock=lambda: float(next(ticks))
+    )
+
+    assert manifest["partial"] is True
+    assert manifest["resume_from"] == 5
+    assert manifest["pages_written"] == 4
+    assert "doc_ingest again with first_page=5" in manifest["next_step"]
+
+
+@pytest.mark.asyncio
+async def test_second_call_resumes_and_skips_existing(sample_pdf, session_root):
+    ticks = iter(range(0, 10_000))
+    first = await ingest_document(
+        sample_pdf, session_root, budget_sec=5, clock=lambda: float(next(ticks))
+    )
+    assert first["partial"] is True
+
+    second = await ingest_document(sample_pdf, session_root, budget_sec=600)
+
+    assert second["partial"] is False
+    assert second["pages_skipped_existing"] == first["pages_written"]
+    assert second["pages_written"] == PAGE_COUNT - first["pages_written"]
+    assert (
+        len(list(_pages_dir(session_root, second["slug"]).glob("p*.txt"))) == PAGE_COUNT
+    )
+
+
+@pytest.mark.asyncio
+async def test_ocr_runs_only_on_pages_without_text_layer(sample_pdf, session_root):
+    seen: list[int] = []
+
+    async def fake_ocr(page_no: int, image_bytes: bytes, mime: str) -> str:
+        seen.append(page_no)
+        assert image_bytes[:4] == b"\x89PNG"
+        assert mime == "image/png"
+        return f"OCR PAGINA {page_no}"
+
+    manifest = await ingest_document(
+        sample_pdf, session_root, budget_sec=600, ocr_page=fake_ocr
+    )
+
+    assert sorted(seen) == sorted(BLANK_PAGES)
+    assert manifest["ocr_pages"] == len(BLANK_PAGES)
+    assert manifest["text_layer_pages"] == PAGE_COUNT - len(BLANK_PAGES)
+    assert manifest["empty_pages"] == []
+
+    recovered = _pages_dir(session_root, manifest["slug"]) / "p0007.txt"
+    assert recovered.read_text(encoding="utf-8") == "OCR PAGINA 7"
+
+
+@pytest.mark.asyncio
+async def test_min_text_chars_controls_the_ocr_trigger(sample_pdf, session_root):
+    """A page is sent to OCR only when its text layer is below the threshold."""
+    seen: list[int] = []
+
+    async def fake_ocr(page_no: int, image_bytes: bytes, mime: str) -> str:
+        seen.append(page_no)
+        return f"OCR PAGINA {page_no}"
+
+    await ingest_document(
+        sample_pdf,
+        session_root,
+        budget_sec=600,
+        last_page=5,
+        ocr_page=fake_ocr,
+        min_text_chars=10_000,
+    )
+    assert seen == [1, 2, 3, 4, 5]
+
+
+@pytest.mark.asyncio
+async def test_ocr_mode_always_bypasses_the_text_layer(sample_pdf, session_root):
+    seen: list[int] = []
+
+    async def fake_ocr(page_no: int, image_bytes: bytes, mime: str) -> str:
+        seen.append(page_no)
+        return f"OCR PAGINA {page_no}"
+
+    manifest = await ingest_document(
+        sample_pdf,
+        session_root,
+        budget_sec=600,
+        last_page=3,
+        ocr_mode="always",
+        ocr_page=fake_ocr,
+    )
+
+    assert seen == [1, 2, 3]
+    assert manifest["ocr_pages"] == 3
+    assert manifest["text_layer_pages"] == 0
+
+
+@pytest.mark.asyncio
+async def test_ocr_failure_keeps_the_text_layer(sample_pdf, session_root):
+    async def failing_ocr(page_no, image_bytes, mime):
+        raise RuntimeError("OCR service unreachable")
+
+    manifest = await ingest_document(
+        sample_pdf, session_root, budget_sec=600, ocr_page=failing_ocr
+    )
+
+    # Pages with text are untouched; the blank ones are reported as failed rather
+    # than silently counted as successfully extracted.
+    assert manifest["ocr_pages"] == 0
+    assert manifest["text_layer_pages"] == PAGE_COUNT - len(BLANK_PAGES)
+    assert manifest["ocr_failed_pages"] == sorted(BLANK_PAGES)
+    assert manifest["ocr_failed_pages_count"] == len(BLANK_PAGES)
+    blank = _pages_dir(session_root, manifest["slug"]) / "p0007.txt"
+    assert "OCR failed for page 7" in blank.read_text(encoding="utf-8")
+
+
+@pytest.mark.asyncio
+async def test_ocr_mode_never_reports_empty_pages(sample_pdf, session_root):
+    async def unexpected_ocr(page_no, image_bytes, mime):  # pragma: no cover
+        raise AssertionError("OCR must not run with ocr_mode='never'")
+
+    manifest = await ingest_document(
+        sample_pdf,
+        session_root,
+        budget_sec=600,
+        ocr_mode="never",
+        ocr_page=unexpected_ocr,
+    )
+
+    assert manifest["ocr_pages"] == 0
+    assert manifest["empty_pages"] == sorted(BLANK_PAGES)
+    assert manifest["empty_pages_count"] == len(BLANK_PAGES)
+
+
+@pytest.mark.asyncio
+async def test_full_text_is_opt_in(sample_pdf, session_root):
+    default = await ingest_document(sample_pdf, session_root, budget_sec=600)
+    root = session_root / "derived" / "docs" / default["slug"]
+    assert not (root / "full.txt").exists()
+    assert default["full_text"] is None
+
+    with_full = await ingest_document(
+        sample_pdf, session_root, budget_sec=600, write_full=True
+    )
+    full = root / "full.txt"
+    assert full.exists()
+    assert with_full["full_text"].endswith("full.txt")
+    body = full.read_text(encoding="utf-8")
+    assert "=== PAGE 101 ===" in body
+    assert "[53]" in body
+
+
+@pytest.mark.asyncio
+async def test_force_reextracts_pages(sample_pdf, session_root):
+    manifest = await ingest_document(sample_pdf, session_root, budget_sec=600)
+    stale = _pages_dir(session_root, manifest["slug"]) / "p0101.txt"
+    stale.write_text("contenuto obsoleto", encoding="utf-8")
+
+    refreshed = await ingest_document(
+        sample_pdf,
+        session_root,
+        budget_sec=600,
+        last_page=PRESCRIPTION_PAGE,
+        force=True,
+    )
+
+    assert refreshed["pages_skipped_existing"] == 0
+    assert "[53]" in stale.read_text(encoding="utf-8")
+
+
+@pytest.mark.asyncio
+async def test_page_range_limits_extraction(sample_pdf, session_root):
+    manifest = await ingest_document(
+        sample_pdf, session_root, budget_sec=600, first_page=10, last_page=12
+    )
+
+    assert manifest["range"] == [10, 12]
+    assert manifest["pages_written"] == 3
+    names = sorted(
+        p.name for p in _pages_dir(session_root, manifest["slug"]).glob("*.txt")
+    )
+    assert names == ["p0010.txt", "p0011.txt", "p0012.txt"]
+
+
+@pytest.mark.asyncio
+async def test_first_page_excerpt_supports_identity_check(sample_pdf, session_root):
+    manifest = await ingest_document(sample_pdf, session_root, budget_sec=600)
+    assert "PAGINA 1" in manifest["first_page_excerpt"]
+
+
+@pytest.mark.asyncio
+async def test_invalid_inputs_return_structured_errors(
+    sample_pdf, session_root, tmp_path
+):
+    bad_mode = await ingest_document(sample_pdf, session_root, ocr_mode="sometimes")
+    assert bad_mode == {
+        "ok": False,
+        "error": "invalid_ocr_mode",
+        "message": "ocr_mode must be auto|never|always, got 'sometimes'",
+    }
+
+    missing = await ingest_document(tmp_path / "nope.pdf", session_root)
+    assert missing["error"] == "not_a_file"
+
+    out_of_range = await ingest_document(
+        sample_pdf, session_root, first_page=PAGE_COUNT + 5, budget_sec=600
+    )
+    assert out_of_range["error"] == "empty_range"
diff --git a/src/test/test_document_evidence_eval.py b/src/test/test_document_evidence_eval.py
new file mode 100644
index 00000000..c1177702
--- /dev/null
+++ b/src/test/test_document_evidence_eval.py
@@ -0,0 +1,82 @@
+"""CI eval for document evidence crop (synthetic PDF, no network)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import yaml
+
+from src.benchmarks.long_document.synthetic import build_rumore_decreto_pdf
+from src.tools.pdf_evidence import pdf_evidence_crop_sync
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SMOKE_CASES = REPO_ROOT / "evals" / "document_evidence" / "cases" / "smoke.yaml"
+
+
+def _load_cases(path: Path) -> list[dict]:
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return list(data.get("cases") or [])
+
+
+def _build_pdf(case: dict, work_dir: Path) -> Path:
+    pdf_cfg = case.get("pdf") or {}
+    assert pdf_cfg.get("source") == "synthetic"
+    return build_rumore_decreto_pdf(
+        work_dir / f"{case['id']}.pdf",
+        pages=int(pdf_cfg.get("pages") or 10),
+        prescription_page=int(pdf_cfg.get("prescription_page") or 5),
+        pmc_page=int(pdf_cfg.get("pmc_page") or 8),
+    )
+
+
+@pytest.mark.parametrize("path", [SMOKE_CASES])
+def test_document_evidence_dataset_schema(path: Path):
+    assert path.is_file(), f"missing {path}"
+    cases = _load_cases(path)
+    assert cases, "no cases"
+    ids = [c["id"] for c in cases]
+    assert len(ids) == len(set(ids)), "duplicate case ids"
+    for case in cases:
+        assert case.get("crop"), f"{case['id']}: missing crop block"
+        assert case.get("expect"), f"{case['id']}: missing expect block"
+
+
+@pytest.mark.parametrize("case", _load_cases(SMOKE_CASES), ids=lambda c: c["id"])
+def test_document_evidence_pipeline_case(case: dict, tmp_path, monkeypatch):
+    monkeypatch.setenv("AION_PDF_EVIDENCE_MAX_WHITE_RATIO", "0.90")
+    pdf = _build_pdf(case, tmp_path)
+    session = tmp_path / "session"
+    session.mkdir()
+
+    crop_cfg = case["crop"]
+    out = pdf_evidence_crop_sync(
+        pdf,
+        session,
+        page=int(crop_cfg["page"]),
+        full_page=bool(crop_cfg.get("full_page")),
+        caption=str(crop_cfg.get("caption") or ""),
+        source_relative_path=f"uploads/{pdf.name}",
+    )
+
+    expect = case["expect"]
+    if expect.get("ok") is True:
+        assert out["ok"] is True, out
+        if expect.get("max_white_ratio") is not None:
+            assert out["ok"] is True
+            assert out["white_ratio"] <= float(expect["max_white_ratio"]) + 0.01
+        if expect.get("min_width"):
+            png = session / out["png_path"]
+            from PIL import Image
+
+            with Image.open(png) as img:
+                assert img.width >= int(expect["min_width"])
+        if expect.get("sidecar_required"):
+            sidecar = session / out["sidecar_path"]
+            assert sidecar.is_file()
+        if expect.get("cropped") is not None:
+            assert out.get("cropped") is expect["cropped"]
+    else:
+        assert out["ok"] is False, out
+        if expect.get("error"):
+            assert out.get("error") == expect["error"]
diff --git a/src/test/test_evidence_layout.py b/src/test/test_evidence_layout.py
new file mode 100644
index 00000000..a538e755
--- /dev/null
+++ b/src/test/test_evidence_layout.py
@@ -0,0 +1,46 @@
+"""Tests for Word evidence figure layout helpers."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+_SCRIPTS = (
+    Path(__file__).resolve().parents[2]
+    / "config_proprietary"
+    / "skills"
+    / "docx"
+    / "scripts"
+)
+sys.path.insert(0, str(_SCRIPTS))
+
+from report.evidence_layout import (  # noqa: E402
+    DEFAULT_MAX_HEIGHT_IN,
+    DEFAULT_MAX_WIDTH_IN,
+    estimated_display_height_inches,
+    fit_image_width_inches,
+)
+
+
+def test_fit_image_width_caps_tall_portrait(tmp_path):
+    # Simulate full-page decree screenshot (aspect ~1.4)
+    path = tmp_path / "tall.png"
+    Image.new("RGB", (1000, 1400), color=(255, 255, 255)).save(path)
+    w = fit_image_width_inches(path)
+    h = estimated_display_height_inches(path)
+    assert w <= DEFAULT_MAX_WIDTH_IN
+    assert h <= DEFAULT_MAX_HEIGHT_IN + 0.01
+
+
+def test_fit_image_width_preserves_wide_crop(tmp_path):
+    path = tmp_path / "wide.png"
+    img = Image.new("RGB", (1200, 400), color=(255, 255, 255))
+    for x in range(100, 1100):
+        for y in range(150, 250):
+            img.putpixel((x, y), (0, 0, 0))
+    img.save(path)
+    w = fit_image_width_inches(path)
+    assert w == pytest.approx(DEFAULT_MAX_WIDTH_IN, rel=0.01)
diff --git a/src/test/test_geocode.py b/src/test/test_geocode.py
new file mode 100644
index 00000000..f56e7ba2
--- /dev/null
+++ b/src/test/test_geocode.py
@@ -0,0 +1,94 @@
+"""Unit tests for geocode tool (mocked Nominatim)."""
+
+from __future__ import annotations
+
+import pytest
+
+from src.tools.geocode import geocode_place_sync, haversine_km
+
+
+def test_haversine_km_same_point():
+    assert haversine_km(35.0, 139.0, 35.0, 139.0) == 0.0
+
+
+def test_geocode_place_picks_worship_over_shop(monkeypatch):
+    worship = {
+        "lat": "32.7830",
+        "lon": "130.6586",
+        "display_name": "高橋稲荷神社, 熊本市西区, 熊本県, 日本",
+        "type": "place_of_worship",
+        "class": "amenity",
+        "importance": 0.4,
+    }
+    shop = {
+        "lat": "39.2291",
+        "lon": "140.1435",
+        "display_name": "高橋美容室, 秋田県, 日本",
+        "type": "hairdresser",
+        "class": "shop",
+        "importance": 0.2,
+    }
+
+    def fake_search(query, *, country_code, limit, client=None):
+        return [shop, worship]
+
+    monkeypatch.setattr("src.tools.geocode._nominatim_search", fake_search)
+    monkeypatch.setattr("src.tools.geocode._rate_limit", lambda: None)
+
+    out = geocode_place_sync(
+        "Takahashi Inari Jinja, Kumamoto, Japan",
+        country_code="jp",
+        validate_contains="熊本",
+    )
+    assert out["ok"] is True
+    assert out["lat"] == pytest.approx(32.7830)
+    assert out["validated"] is True
+
+
+def test_geocode_place_uses_fallback(monkeypatch):
+    calls: list[str] = []
+
+    def fake_search(query, *, country_code, limit, client=None):
+        calls.append(query)
+        if "笠間稲荷" in query:
+            return [
+                {
+                    "lat": "36.3854725",
+                    "lon": "140.2543843",
+                    "display_name": "笠間稲荷神社, 茨城県",
+                    "type": "place_of_worship",
+                    "importance": 0.5,
+                }
+            ]
+        return []
+
+    monkeypatch.setattr("src.tools.geocode._nominatim_search", fake_search)
+    monkeypatch.setattr("src.tools.geocode._rate_limit", lambda: None)
+
+    out = geocode_place_sync(
+        "Kasama Inari Jinja, Ibaraki, Japan",
+        fallback_query="笠間稲荷神社, 茨城県",
+        country_code="jp",
+    )
+    assert out["ok"] is True
+    assert len(calls) >= 2
+    assert "笠間稲荷" in out["query_used"]
+
+
+def test_geocode_rejects_point_outside_country_bbox(monkeypatch):
+    def fake_search(query, *, country_code, limit, client=None):
+        return [
+            {
+                "lat": "48.8566",
+                "lon": "2.3522",
+                "display_name": "Paris, France",
+                "type": "city",
+                "importance": 0.9,
+            }
+        ]
+
+    monkeypatch.setattr("src.tools.geocode._nominatim_search", fake_search)
+    monkeypatch.setattr("src.tools.geocode._rate_limit", lambda: None)
+
+    out = geocode_place_sync("Paris", country_code="jp")
+    assert out["ok"] is False
diff --git a/src/test/test_geocoding_eval.py b/src/test/test_geocoding_eval.py
new file mode 100644
index 00000000..ae764427
--- /dev/null
+++ b/src/test/test_geocoding_eval.py
@@ -0,0 +1,60 @@
+"""Live geocoding eval against evals/geocoding/cases/*.yaml (requires network)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+import yaml
+
+from src.tools.geocode import geocode_place_sync, haversine_km
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+INARI_CASES = REPO_ROOT / "evals" / "geocoding" / "cases" / "inari_shrines_jp.yaml"
+
+
+def _load_cases(path: Path) -> list[dict]:
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return list(data.get("cases") or [])
+
+
+@pytest.mark.skipif(
+    not os.getenv("AION_GEOCODING_LIVE"),
+    reason="Set AION_GEOCODING_LIVE=1 for live Nominatim eval",
+)
+def test_inari_shrines_golden_live():
+    cases = _load_cases(INARI_CASES)
+    assert len(cases) >= 10
+
+    passed = 0
+    rows: list[str] = []
+    for case in cases:
+        cid = case["id"]
+        ref_lat = float(case["lat"])
+        ref_lon = float(case["lon"])
+        max_km = float(case.get("max_distance_km") or 0.5)
+
+        out = geocode_place_sync(
+            str(case.get("query") or ""),
+            fallback_query=str(case.get("query_ja") or ""),
+            country_code="jp",
+        )
+        if not out.get("ok"):
+            rows.append(f"FAIL {cid}: {out.get('error')}")
+            continue
+
+        dist = haversine_km(ref_lat, ref_lon, float(out["lat"]), float(out["lon"]))
+        ok = dist <= max_km and out.get("validated", True)
+        if ok:
+            passed += 1
+        mark = "PASS" if ok else "FAIL"
+        rows.append(
+            f"{mark} {cid}: {dist:.2f}km validated={out.get('validated')} "
+            f"| {out.get('display_name', '')[:60]}"
+        )
+
+    summary = f"{passed}/{len(cases)} within tolerance"
+    print("\n".join(rows))
+    print(summary)
+    assert passed >= len(cases) - 1, summary
diff --git a/src/test/test_long_document_eval.py b/src/test/test_long_document_eval.py
new file mode 100644
index 00000000..efcebea4
--- /dev/null
+++ b/src/test/test_long_document_eval.py
@@ -0,0 +1,152 @@
+"""Eval harness tests for long-document extraction (pipeline + dataset schema)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+import yaml
+
+from src.benchmarks.long_document.runner import (
+    DEFAULT_CASES_DIR,
+    load_dataset,
+    run_long_document_pipeline_eval,
+    run_pipeline_case,
+)
+from src.benchmarks.long_document.scoring import (
+    page_no_from_hit_file,
+    score_identity_gate,
+    score_required_hits,
+)
+from src.benchmarks.long_document.synthetic import build_rumore_decreto_pdf
+from src.tools.doc_ingest import ingest_document
+
+SYNTHETIC = DEFAULT_CASES_DIR / "synthetic_smoke.yaml"
+ALTOMONTE = DEFAULT_CASES_DIR / "altomonte_rumore.yaml"
+
+
+def _validate_case(case: dict, *, path: Path) -> None:
+    assert case.get("id"), f"{path}: case missing id"
+    pdf = case.get("pdf") or {}
+    assert pdf.get("source") in {"synthetic", "env", "path"}, (
+        f"{case['id']}: invalid pdf.source"
+    )
+    for hit in case.get("required_hits") or []:
+        assert hit.get("grep_pattern"), f"{case['id']}: hit missing grep_pattern"
+
+
+@pytest.mark.parametrize("path", [SYNTHETIC, ALTOMONTE])
+def test_long_document_dataset_schema(path: Path):
+    assert path.is_file(), f"missing {path}"
+    data = load_dataset(path)
+    cases = data.get("cases") or [data]
+    assert cases, f"{path}: no cases"
+    ids = [c["id"] for c in cases]
+    assert len(ids) == len(set(ids)), f"{path}: duplicate case ids"
+    for case in cases:
+        _validate_case(case, path=path)
+
+
+def test_page_no_from_hit_file():
+    assert page_no_from_hit_file("derived/docs/foo/pages/p0101.txt") == 101
+    assert page_no_from_hit_file("p0042.txt") == 42
+    assert page_no_from_hit_file("readme.txt") is None
+
+
+@pytest.mark.asyncio
+async def test_synthetic_smoke_pipeline_eval_passes(tmp_path):
+    metrics = await run_long_document_pipeline_eval(SYNTHETIC, work_dir=tmp_path)
+    assert metrics["scored_count"] == 1
+    assert metrics["passed_count"] == 1
+    assert metrics["accuracy_overall"] == 1.0
+    assert metrics["mean_recall"] == 1.0
+
+
+@pytest.mark.asyncio
+async def test_altomonte_cases_skip_without_pdf(tmp_path, monkeypatch):
+    monkeypatch.delenv("AION_EVAL_ALTOMONTE_PDF", raising=False)
+    metrics = await run_long_document_pipeline_eval(ALTOMONTE, work_dir=tmp_path)
+    assert metrics["case_count"] == 2
+    assert metrics["skipped_count"] == 2
+    assert metrics["scored_count"] == 0
+
+
+@pytest.mark.asyncio
+async def test_scoring_required_hits_on_ingested_pages(tmp_path):
+    pdf = build_rumore_decreto_pdf(
+        tmp_path / "decreto.pdf", pages=20, prescription_page=10, pmc_page=15
+    )
+    session = tmp_path / "session"
+    manifest = await ingest_document(pdf, session, ocr_mode="never", budget_sec=60)
+    assert manifest["ok"]
+
+    score = score_required_hits(
+        session,
+        manifest["slug"],
+        [
+            {
+                "label": "pic53",
+                "grep_pattern": "\\[53\\]",
+                "page": 10,
+                "must_contain": ["[53]", "rumore"],
+            }
+        ],
+    )
+    assert score["recall"] == 1.0
+    assert score["details"][0]["passed"]
+
+
+def test_identity_gate_detects_wrong_plant():
+    manifest = {
+        "title_guess": "Decreto impianto Altomonte",
+        "first_page_excerpt": "Centrale termoelettrica Altomonte",
+        "source": "decreto.pdf",
+    }
+    ok = score_identity_gate(
+        manifest,
+        {"must_contain": ["altomonte"], "must_not_contain": ["presenzano"]},
+    )
+    assert ok["passed"] is True
+
+    bad = score_identity_gate(
+        manifest,
+        {"must_contain": ["presenzano"], "must_not_contain": []},
+    )
+    assert bad["passed"] is False
+    assert "presenzano" in bad["missing"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(
+    not os.getenv("AION_EVAL_LLM"),
+    reason="Set AION_EVAL_LLM=1 to run agentic long-document eval",
+)
+async def test_agentic_altomonte_optional(tmp_path):
+    """End-to-end agent eval — requires LLM, OCR service, and AION_EVAL_ALTOMONTE_PDF."""
+    from src.agent_pipeline import AgentPipeline
+    from src.benchmarks.long_document.scoring import score_agent_output
+    from src.main import get_agent, set_event_loop
+
+    pdf_env = os.getenv("AION_EVAL_ALTOMONTE_PDF", "").strip()
+    if not pdf_env or not Path(pdf_env).is_file():
+        pytest.skip("AION_EVAL_ALTOMONTE_PDF not set")
+
+    data = yaml.safe_load(ALTOMONTE.read_text(encoding="utf-8"))
+    case = data["cases"][0]
+    session_id = f"eval_{case['id']}"
+    set_event_loop(__import__("asyncio").get_event_loop())
+
+    # Seed session with ingested PDF via pipeline eval helper first.
+    await run_pipeline_case(case, work_dir=tmp_path / "seed")
+
+    agent, profile = await get_agent(
+        "document_extractor", session_id=session_id, user_id="eval"
+    )
+    pipeline = AgentPipeline(
+        agent, session_id=session_id, profile_name=profile, user_id="eval"
+    )
+    agent_cfg = case.get("agent_expectations") or {}
+    res = await pipeline.run(str(agent_cfg.get("user_query") or ""))
+    scored = score_agent_output(res.get("text", ""), agent_cfg)
+    assert scored["passed"], scored
diff --git a/src/test/test_mcp_tool_result.py b/src/test/test_mcp_tool_result.py
index 3141608e..84e457a9 100644
--- a/src/test/test_mcp_tool_result.py
+++ b/src/test/test_mcp_tool_result.py
@@ -5,6 +5,7 @@
 import json
 
 from src.runtime.mcp_tool_result import (
+    build_timeout_message,
     classify_tool_result_text,
     format_exception_for_tool,
 )
@@ -54,6 +55,36 @@ def test_format_exception_for_tool():
     assert "connection reset" in data["message"]
 
 
+def test_timeout_message_for_postgres_keeps_sql_guidance():
+    msg = build_timeout_message("toolbox-postgres", "query")
+    assert "PostgreSQL cap" in msg
+    assert "Heavy JOINs" in msg
+
+
+def test_timeout_message_for_document_tools_is_not_about_sql():
+    """A PostgreSQL hint on an OCR timeout actively derails the model."""
+    for tool in ("ocr_file", "doc_ingest"):
+        msg = build_timeout_message("ocr", tool)
+        assert "PostgreSQL" not in msg
+        assert "JOIN" not in msg
+        assert "doc_ingest" in msg
+        assert "first_page" in msg
+
+
+def test_timeout_message_generic_tool_has_no_sql_or_false_recycle_claim():
+    msg = build_timeout_message("session_sandbox", "sandbox_run_python_file")
+    assert "PostgreSQL" not in msg
+    # Only the Postgres path actually restarts the worker.
+    assert "recycled" not in msg
+    assert "AION_MCP_TOOL_RESULT_TIMEOUT" in msg
+
+
+def test_timeout_message_handles_prefixed_tool_names():
+    msg = build_timeout_message("ocr", "ocr-doc_ingest")
+    assert "doc_ingest" in msg
+    assert "PostgreSQL" not in msg
+
+
 def test_classify_skill_view_not_error_despite_keywords():
     raw = "Plane Project Management. Error: this tool failed sometimes due to Pydantic Validation exception."
     is_err, body = classify_tool_result_text(raw, "skill_view")
diff --git a/src/test/test_merge_mcp_registry.py b/src/test/test_merge_mcp_registry.py
new file mode 100644
index 00000000..1ddcdf60
--- /dev/null
+++ b/src/test/test_merge_mcp_registry.py
@@ -0,0 +1,38 @@
+"""Tests for merge_mcp_registry_from_std.py."""
+
+from __future__ import annotations
+
+import yaml
+
+from scripts.merge_mcp_registry_from_std import merge_mcp_registry_from_std
+
+
+def test_merge_adds_missing_slug(tmp_path):
+    std_dir = tmp_path / "config_std"
+    cfg_dir = tmp_path / "config"
+    std_dir.mkdir()
+    cfg_dir.mkdir()
+    (std_dir / "mcp_registry.yaml").write_text(
+        yaml.safe_dump(
+            {
+                "alpha": {"command": "python", "args": ["-u", "alpha/server.py"]},
+                "beta": {"command": "python", "args": ["-u", "beta/server.py"]},
+            }
+        ),
+        encoding="utf-8",
+    )
+    (cfg_dir / "mcp_registry.yaml").write_text(
+        yaml.safe_dump(
+            {"alpha": {"command": "python", "args": ["-u", "alpha/server.py"]}}
+        ),
+        encoding="utf-8",
+    )
+
+    added = merge_mcp_registry_from_std(root=tmp_path)
+    assert added == ["beta"]
+
+    merged = yaml.safe_load((cfg_dir / "mcp_registry.yaml").read_text(encoding="utf-8"))
+    assert "beta" in merged
+    assert "alpha" in merged
+
+    assert merge_mcp_registry_from_std(root=tmp_path) == []
diff --git a/src/test/test_office_convert.py b/src/test/test_office_convert.py
new file mode 100644
index 00000000..a01f4452
--- /dev/null
+++ b/src/test/test_office_convert.py
@@ -0,0 +1,104 @@
+"""Tests for legacy Word (.doc) conversion on upload."""
+
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from src.session_workspace import save_upload, session_root
+from src.tools.office_convert import (
+    convert_legacy_word_sync,
+    find_soffice,
+    is_legacy_word_upload,
+    is_misnamed_docx,
+)
+
+
+def test_is_legacy_word_upload_by_extension():
+    assert is_legacy_word_upload("report.doc", "application/octet-stream")
+    assert not is_legacy_word_upload("report.docx", "application/octet-stream")
+
+
+def test_is_misnamed_docx_detects_zip():
+    buf = b"PK\x03\x04" + b"0" * 100
+    assert is_misnamed_docx("file.doc", buf) is True
+    assert is_misnamed_docx("file.doc", b"\xd0\xcf\x11\xe0" + b"0" * 100) is False
+
+
+def test_convert_misnamed_docx_copies_as_docx(tmp_path, monkeypatch):
+    sid = "test-legacy-word-01"
+    monkeypatch.setenv("AION_DATA_DIR", str(tmp_path))
+
+    minimal_docx = tmp_path / "mini.docx"
+    with zipfile.ZipFile(minimal_docx, "w") as zf:
+        zf.writestr("[Content_Types].xml", "<Types/>")
+        zf.writestr("word/document.xml", "<w:document/>")
+
+    meta = save_upload(sid, "report.doc", minimal_docx.read_bytes())
+    out = convert_legacy_word_sync(sid, meta)
+
+    assert out.get("conversion_status") == "ok"
+    assert out.get("conversion_method") == "rename_zip"
+    conv = out.get("converted_docx_path")
+    assert conv and conv.endswith(".docx")
+    conv_path = session_root(sid) / conv
+    assert conv_path.is_file()
+    with zipfile.ZipFile(conv_path) as zf:
+        assert "word/document.xml" in zf.namelist()
+
+
+def test_convert_legacy_word_unavailable_without_soffice(tmp_path, monkeypatch):
+    sid = "test-legacy-word-02"
+    monkeypatch.setenv("AION_DATA_DIR", str(tmp_path))
+    monkeypatch.delenv("AION_SOFFICE_PATH", raising=False)
+
+    ole_doc = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1" + b"\x00" * 512
+    meta = save_upload(sid, "legacy.doc", ole_doc)
+
+    with patch("src.tools.office_convert.find_soffice", return_value=None):
+        out = convert_legacy_word_sync(sid, meta)
+
+    assert out.get("conversion_status") == "unavailable"
+    assert "LibreOffice" in (out.get("conversion_error") or "")
+
+
+def test_convert_legacy_word_with_soffice_mock(tmp_path, monkeypatch):
+    sid = "test-legacy-word-03"
+    monkeypatch.setenv("AION_DATA_DIR", str(tmp_path))
+
+    ole_doc = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1" + b"\x00" * 512
+    meta = save_upload(sid, "report.doc", ole_doc)
+
+    def fake_run(cmd, **kwargs):
+        outdir = Path(cmd[cmd.index("--outdir") + 1])
+        src = Path(cmd[-1])
+        (outdir / f"{src.stem}.docx").write_bytes(b"PK\x03\x04" + b"fake-docx-bytes")
+
+        class R:
+            returncode = 0
+            stdout = ""
+            stderr = ""
+
+        return R()
+
+    with patch(
+        "src.tools.office_convert.find_soffice", return_value="/usr/bin/soffice"
+    ):
+        with patch("src.tools.office_convert.subprocess.run", side_effect=fake_run):
+            out = convert_legacy_word_sync(sid, meta)
+
+    assert out.get("conversion_status") == "ok"
+    assert out.get("converted_docx_path", "").endswith("report.docx")
+    conv_path = session_root(sid) / str(out["converted_docx_path"])
+    assert conv_path.is_file()
+
+
+@pytest.mark.skipif(
+    find_soffice() is None,
+    reason="LibreOffice not installed — skip live conversion",
+)
+def test_find_soffice_live():
+    assert find_soffice()
diff --git a/src/test/test_pdf_evidence.py b/src/test/test_pdf_evidence.py
new file mode 100644
index 00000000..3f8bde81
--- /dev/null
+++ b/src/test/test_pdf_evidence.py
@@ -0,0 +1,170 @@
+"""Unit tests for pdf_evidence crop tool."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+from src.benchmarks.long_document.synthetic import build_rumore_decreto_pdf
+from src.tools.pdf_evidence import (
+    auto_trim_image,
+    compute_white_ratio,
+    max_white_ratio,
+    pdf_evidence_crop_sync,
+)
+
+
+def test_compute_white_ratio_all_white():
+    img = Image.new("RGB", (100, 100), color=(255, 255, 255))
+    assert compute_white_ratio(img) == pytest.approx(1.0)
+
+
+def test_compute_white_ratio_mixed():
+    img = Image.new("RGB", (10, 10), color=(255, 255, 255))
+    for x in range(5):
+        for y in range(10):
+            img.putpixel((x, y), (0, 0, 0))
+    assert compute_white_ratio(img) == pytest.approx(0.5)
+
+
+def test_auto_trim_crops_whitespace():
+    img = Image.new("RGB", (200, 200), color=(255, 255, 255))
+    for x in range(40, 80):
+        for y in range(50, 90):
+            img.putpixel((x, y), (10, 10, 10))
+    trimmed = auto_trim_image(img, padding=2)
+    assert trimmed.width < img.width
+    assert trimmed.height < img.height
+    assert compute_white_ratio(trimmed) < 0.95
+
+
+def test_pdf_evidence_crop_writes_png_and_sidecar(tmp_path, monkeypatch):
+    monkeypatch.setenv("AION_PDF_EVIDENCE_MAX_WHITE_RATIO", "0.99")
+    pdf = build_rumore_decreto_pdf(
+        tmp_path / "decreto.pdf", pages=5, prescription_page=3, pmc_page=4
+    )
+    session = tmp_path / "session"
+    session.mkdir()
+
+    out = pdf_evidence_crop_sync(
+        pdf,
+        session,
+        page=3,
+        caption="decreto / §8.9 / pag. 3",
+        source_relative_path="uploads/decreto.pdf",
+    )
+    assert out["ok"] is True
+    assert out["page"] == 3
+    assert out["caption"] == "decreto / §8.9 / pag. 3"
+    assert out["cropped"] is True
+    assert out["crop_method"] in {"text_blocks", "auto_trim"}
+    assert out["white_ratio"] < 0.99
+
+    png = session / out["png_path"]
+    sidecar = session / out["sidecar_path"]
+    assert png.is_file()
+    assert sidecar.is_file()
+    meta = json.loads(sidecar.read_text(encoding="utf-8"))
+    assert meta["page"] == 3
+    assert meta["png_path"] == out["png_path"]
+
+
+def test_pdf_evidence_crop_rejects_whitespace_heavy_full_page(tmp_path, monkeypatch):
+    monkeypatch.setenv("AION_PDF_EVIDENCE_MAX_WHITE_RATIO", "0.90")
+    pdf = build_rumore_decreto_pdf(
+        tmp_path / "sparse.pdf",
+        pages=1,
+        prescription_page=99,
+        pmc_page=99,
+        blank_pages=frozenset({1}),
+    )
+    session = tmp_path / "session"
+    session.mkdir()
+
+    out = pdf_evidence_crop_sync(
+        pdf,
+        session,
+        page=1,
+        full_page=True,
+        caption="full page test",
+    )
+    assert out["ok"] is False
+    assert out["error"] == "too_much_whitespace"
+    assert out["white_ratio"] > max_white_ratio()
+
+
+def test_pdf_evidence_crop_with_bbox(tmp_path, monkeypatch):
+    monkeypatch.setenv("AION_PDF_EVIDENCE_MAX_WHITE_RATIO", "0.99")
+    pdf = build_rumore_decreto_pdf(
+        tmp_path / "decreto.pdf", pages=3, prescription_page=2, pmc_page=3
+    )
+    session = tmp_path / "session"
+    session.mkdir()
+
+    out = pdf_evidence_crop_sync(
+        pdf,
+        session,
+        page=2,
+        # PyMuPDF origin is top-left; ReportLab synthetic text at y≈660pt from bottom → ~182pt from top
+        bbox={"x0": 60, "y0": 160, "x1": 500, "y1": 220},
+        caption="PIC [53]",
+    )
+    assert out["ok"] is True
+    assert out["cropped"] is False
+    assert len(out["bbox"]) == 4
+
+
+def test_pdf_evidence_crop_increments_index(tmp_path, monkeypatch):
+    monkeypatch.setenv("AION_PDF_EVIDENCE_MAX_WHITE_RATIO", "0.99")
+    pdf = build_rumore_decreto_pdf(
+        tmp_path / "decreto.pdf", pages=2, prescription_page=1, pmc_page=2
+    )
+    session = tmp_path / "session"
+    session.mkdir()
+
+    first = pdf_evidence_crop_sync(pdf, session, page=1, caption="a")
+    second = pdf_evidence_crop_sync(pdf, session, page=2, caption="b")
+    assert first["ok"] and second["ok"]
+    assert first["png_path"].endswith("e001.png")
+    assert second["png_path"].endswith("e002.png")
+
+
+def test_pdf_evidence_crop_uses_text_blocks_at_default_threshold(tmp_path, monkeypatch):
+    monkeypatch.setenv("AION_PDF_EVIDENCE_MAX_WHITE_RATIO", "0.90")
+    pdf = build_rumore_decreto_pdf(
+        tmp_path / "decreto.pdf",
+        pages=5,
+        prescription_page=3,
+        pmc_page=4,
+    )
+    session = tmp_path / "session"
+    session.mkdir()
+
+    out = pdf_evidence_crop_sync(
+        pdf,
+        session,
+        page=3,
+        caption="decreto / §8.9 / pag. 3",
+    )
+    assert out["ok"] is True
+    assert out["crop_method"] == "text_blocks"
+    assert out["text_chars"] >= 80
+
+
+def test_pdf_evidence_crop_invalid_page(tmp_path):
+    pdf = build_rumore_decreto_pdf(
+        tmp_path / "decreto.pdf", pages=2, prescription_page=1, pmc_page=2
+    )
+    session = tmp_path / "session"
+    session.mkdir()
+
+    out = pdf_evidence_crop_sync(pdf, session, page=0, caption="x")
+    assert out["ok"] is False
+    assert out["error"] == "invalid_page"
+
+    out2 = pdf_evidence_crop_sync(pdf, session, page=99, caption="x")
+    assert out2["ok"] is False
+    assert out2["error"] == "page_out_of_range"
diff --git a/src/tools/doc_auto_ingest.py b/src/tools/doc_auto_ingest.py
new file mode 100644
index 00000000..c5dfc1f2
--- /dev/null
+++ b/src/tools/doc_auto_ingest.py
@@ -0,0 +1,153 @@
+"""Fire-and-forget PDF text-layer extraction triggered on upload.
+
+Runs ``ingest_document`` in a worker thread so PyMuPDF does not block the FastAPI
+event loop (mandatory with ``--workers 1``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from src.session_workspace import safe_resolve, session_root
+from src.tools.doc_ingest import DOCS_SUBDIR, ingest_document, slugify_document_name
+
+logger = logging.getLogger("aion.doc_auto_ingest")
+
+_PDF_MIME = "application/pdf"
+
+
+def auto_ingest_enabled() -> bool:
+    return os.getenv("AION_DOC_AUTO_INGEST", "1").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+
+
+def _auto_ingest_max_pages() -> int:
+    try:
+        return max(1, int(os.getenv("AION_DOC_AUTO_INGEST_MAX_PAGES", "500")))
+    except ValueError:
+        return 500
+
+
+def _auto_ingest_budget_sec() -> float:
+    try:
+        return float(os.getenv("AION_DOC_AUTO_INGEST_BUDGET_SEC", "120"))
+    except ValueError:
+        return 120.0
+
+
+def manifest_path(session_id: str, slug: str) -> Path:
+    return session_root(session_id) / DOCS_SUBDIR / slug / "manifest.json"
+
+
+def load_manifest(session_id: str, relative_path: str) -> dict[str, Any] | None:
+    """Return ingest manifest for an uploaded PDF if extraction has run."""
+    slug = slugify_document_name(Path(relative_path).name)
+    path = manifest_path(session_id, slug)
+    if not path.is_file():
+        return None
+    try:
+        import json
+
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def _ingest_sync(session_id: str, relative_path: str) -> dict[str, Any]:
+    """Blocking ingest loop with resume until complete or page cap."""
+    import asyncio
+
+    path = safe_resolve(session_id, relative_path, must_exist=True)
+    root = session_root(session_id)
+    max_pages = _auto_ingest_max_pages()
+    budget = _auto_ingest_budget_sec()
+    resume_from = 1
+    manifest: dict[str, Any] = {"ok": False}
+
+    async def _run_once(start: int) -> dict[str, Any]:
+        return await ingest_document(
+            path,
+            root,
+            first_page=start,
+            last_page=max_pages,
+            ocr_mode="never",
+            budget_sec=budget,
+            force=False,
+            write_full=False,
+        )
+
+    for _ in range(50):
+        manifest = asyncio.run(_run_once(resume_from))
+        if not manifest.get("ok"):
+            return manifest
+        if not manifest.get("partial"):
+            break
+        nxt = manifest.get("resume_from")
+        if not nxt or int(nxt) <= resume_from:
+            break
+        resume_from = int(nxt)
+
+    return manifest
+
+
+async def run_auto_ingest_background(
+    session_id: str, relative_path: str, mime: str
+) -> None:
+    """Schedule-safe background ingest for one uploaded PDF."""
+    if not auto_ingest_enabled():
+        return
+    if (mime or "").split(";")[0].strip().lower() != _PDF_MIME:
+        return
+
+    try:
+        manifest = await asyncio.to_thread(_ingest_sync, session_id, relative_path)
+    except Exception as exc:
+        logger.exception(
+            "auto_ingest failed session=%s path=%s: %s",
+            session_id[:8],
+            relative_path,
+            exc,
+        )
+        return
+
+    if manifest.get("ok"):
+        slug = str(manifest.get("slug") or "")
+        logger.info(
+            "auto_ingest complete session=%s slug=%s pages=%s partial=%s",
+            session_id[:8],
+            slug,
+            manifest.get("pages_written"),
+            manifest.get("partial"),
+        )
+    else:
+        logger.warning(
+            "auto_ingest error session=%s path=%s: %s",
+            session_id[:8],
+            relative_path,
+            manifest,
+        )
+
+
+def schedule_auto_ingest(
+    session_id: str,
+    upload_meta: dict[str, Any],
+) -> None:
+    """Fire-and-forget task for a single ``save_upload`` result."""
+    mime = str(upload_meta.get("mime") or "")
+    rel = str(upload_meta.get("relative_path") or "")
+    if not rel:
+        return
+    try:
+        asyncio.get_running_loop().create_task(
+            run_auto_ingest_background(session_id, rel, mime)
+        )
+    except RuntimeError:
+        logger.debug("no running loop; skip auto_ingest for %s", rel)
diff --git a/src/tools/doc_ingest.py b/src/tools/doc_ingest.py
new file mode 100644
index 00000000..2a861240
--- /dev/null
+++ b/src/tools/doc_ingest.py
@@ -0,0 +1,277 @@
+"""Page-by-page ingestion of documents into the session ``derived/docs`` tree.
+
+The artefact layout is one text file per page. That single choice is what makes
+large documents workable:
+
+* ``sandbox_grep_content`` silently skips files above ``AION_GREP_MAX_FILE_BYTES``
+  (500 KB); single pages stay orders of magnitude below it, so a long decree can
+  never be searched into a false negative.
+* The page number travels in the file name, so a grep hit already carries the
+  citation the caller needs.
+* ``read_file_chunk`` loads a whole file before slicing it, so reading one page
+  costs kilobytes instead of the entire document.
+
+Extraction is idempotent and deadline-aware: pages already on disk are skipped and
+a run that hits ``budget_sec`` returns ``partial`` plus ``resume_from`` instead of
+being killed by the MCP bridge timeout.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from pathlib import Path
+from typing import Awaitable, Callable, Optional
+
+__all__ = ["ingest_document", "slugify_document_name", "DOCS_SUBDIR"]
+
+DOCS_SUBDIR = "derived/docs"
+
+# Uploads are stored with a random hex prefix; it carries no meaning for the slug.
+_UPLOAD_PREFIX_RE = re.compile(r"^[0-9a-f]{6,}_")
+_NON_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+# Below this many characters a page is treated as having no usable text layer.
+DEFAULT_MIN_TEXT_CHARS = 60
+DEFAULT_OCR_DPI = 200
+_EXCERPT_CHARS = 400
+_MAX_LISTED_EMPTY_PAGES = 50
+
+OcrCallback = Callable[[int, bytes, str], Awaitable[str]]
+
+
+def slugify_document_name(name: str) -> str:
+    """Stable, filesystem-safe slug for a document file name."""
+    stem = Path(name).stem
+    stem = _UPLOAD_PREFIX_RE.sub("", stem)
+    slug = _NON_SLUG_RE.sub("_", stem.lower()).strip("_")
+    return slug or "document"
+
+
+def _page_filename(page_no: int) -> str:
+    return f"p{page_no:04d}.txt"
+
+
+def _open_pdf(path: Path):
+    try:
+        import pymupdf  # type: ignore
+    except ImportError:  # pragma: no cover - older PyMuPDF only exposes `fitz`
+        import fitz as pymupdf  # type: ignore
+    return pymupdf.open(str(path))
+
+
+def _rebuild_full_text(
+    pages_dir: Path, full_path: Path, page_numbers: list[int]
+) -> int:
+    """Concatenate page files with explicit markers, streaming to avoid buffering."""
+    written = 0
+    with full_path.open("w", encoding="utf-8") as out:
+        for page_no in page_numbers:
+            page_file = pages_dir / _page_filename(page_no)
+            if not page_file.is_file():
+                continue
+            header = f"\n=== PAGE {page_no} ===\n"
+            out.write(header)
+            body = page_file.read_text(encoding="utf-8", errors="replace")
+            out.write(body)
+            written += len(body)
+    return written
+
+
+async def ingest_document(
+    src_path: Path,
+    session_root: Path,
+    *,
+    first_page: int = 1,
+    last_page: int = 0,
+    ocr_mode: str = "auto",
+    budget_sec: float = 90.0,
+    force: bool = False,
+    write_full: bool = False,
+    ocr_page: Optional[OcrCallback] = None,
+    min_text_chars: int = DEFAULT_MIN_TEXT_CHARS,
+    ocr_dpi: int = DEFAULT_OCR_DPI,
+    clock: Callable[[], float] = time.monotonic,
+) -> dict:
+    """Extract ``src_path`` into ``<session_root>/derived/docs/<slug>/pages``.
+
+    ``ocr_mode`` is one of ``auto`` (OCR only pages whose text layer is shorter
+    than ``min_text_chars``), ``never`` or ``always``. OCR is performed through
+    ``ocr_page``; when it is not supplied, pages without a text layer are written
+    empty and reported in ``empty_pages``.
+    """
+    started = clock()
+
+    if ocr_mode not in ("auto", "never", "always"):
+        return {
+            "ok": False,
+            "error": "invalid_ocr_mode",
+            "message": f"ocr_mode must be auto|never|always, got {ocr_mode!r}",
+        }
+    if not src_path.is_file():
+        return {
+            "ok": False,
+            "error": "not_a_file",
+            "message": f"{src_path.name} is not a readable file",
+        }
+
+    slug = slugify_document_name(src_path.name)
+    root = session_root / DOCS_SUBDIR / slug
+    pages_dir = root / "pages"
+    pages_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        doc = _open_pdf(src_path)
+    except Exception as exc:  # noqa: BLE001 - surfaced to the model as JSON
+        return {
+            "ok": False,
+            "error": "open_failed",
+            "message": f"Cannot open {src_path.name}: {exc}",
+        }
+
+    try:
+        pages_total = doc.page_count
+        start = max(1, int(first_page or 1))
+        end = int(last_page) if last_page and int(last_page) > 0 else pages_total
+        end = min(end, pages_total)
+        if start > end:
+            return {
+                "ok": False,
+                "error": "empty_range",
+                "message": f"first_page={start} is past the last page ({pages_total})",
+            }
+
+        title_guess = ""
+        try:
+            title_guess = (doc.metadata or {}).get("title") or ""
+        except Exception:  # noqa: BLE001 - metadata is best effort
+            title_guess = ""
+
+        written = 0
+        skipped = 0
+        text_layer_pages = 0
+        ocr_pages = 0
+        chars_total = 0
+        empty_pages: list[int] = []
+        ocr_failed_pages: list[int] = []
+        first_excerpt = ""
+        partial = False
+        resume_from: Optional[int] = None
+
+        for page_no in range(start, end + 1):
+            if clock() - started >= budget_sec:
+                partial = True
+                resume_from = page_no
+                break
+
+            target = pages_dir / _page_filename(page_no)
+            if target.is_file() and not force:
+                skipped += 1
+                body = target.read_text(encoding="utf-8", errors="replace")
+                chars_total += len(body)
+                if not body.strip():
+                    empty_pages.append(page_no)
+                if page_no == start and not first_excerpt:
+                    first_excerpt = body.strip()[:_EXCERPT_CHARS]
+                continue
+
+            page = doc.load_page(page_no - 1)
+            text = ""
+            if ocr_mode != "always":
+                try:
+                    text = page.get_text("text") or ""
+                except Exception:  # noqa: BLE001 - fall through to OCR / empty
+                    text = ""
+
+            used_ocr = False
+            ocr_failed = False
+            needs_ocr = ocr_mode == "always" or (
+                ocr_mode == "auto" and len(text.strip()) < min_text_chars
+            )
+            if needs_ocr and ocr_page is not None:
+                try:
+                    pixmap = page.get_pixmap(dpi=ocr_dpi)
+                    ocr_text = await ocr_page(
+                        page_no, pixmap.tobytes("png"), "image/png"
+                    )
+                    if ocr_text and ocr_text.strip():
+                        text = ocr_text
+                        used_ocr = True
+                except Exception as exc:  # noqa: BLE001 - keep the text layer we have
+                    if not text.strip():
+                        # A placeholder must never be mistaken for extracted content:
+                        # the page is reported as failed, not as a text-layer page.
+                        text = f"[OCR failed for page {page_no}: {exc}]"
+                        ocr_failed = True
+
+            target.write_text(text, encoding="utf-8")
+            written += 1
+            chars_total += len(text)
+            if ocr_failed:
+                ocr_failed_pages.append(page_no)
+            elif used_ocr:
+                ocr_pages += 1
+            elif text.strip():
+                text_layer_pages += 1
+            else:
+                empty_pages.append(page_no)
+            if page_no == start and not first_excerpt:
+                first_excerpt = text.strip()[:_EXCERPT_CHARS]
+
+        rel_root = f"{DOCS_SUBDIR}/{slug}"
+        full_rel = None
+        if write_full and not partial:
+            full_path = root / "full.txt"
+            _rebuild_full_text(pages_dir, full_path, list(range(start, end + 1)))
+            full_rel = f"{rel_root}/full.txt"
+
+        manifest = {
+            "ok": True,
+            "slug": slug,
+            "source": src_path.name,
+            "title_guess": title_guess,
+            "root": rel_root,
+            "pages_total": pages_total,
+            "range": [start, end],
+            "pages_written": written,
+            "pages_skipped_existing": skipped,
+            "text_layer_pages": text_layer_pages,
+            "ocr_pages": ocr_pages,
+            "empty_pages": empty_pages[:_MAX_LISTED_EMPTY_PAGES],
+            "empty_pages_count": len(empty_pages),
+            "ocr_failed_pages": ocr_failed_pages[:_MAX_LISTED_EMPTY_PAGES],
+            "ocr_failed_pages_count": len(ocr_failed_pages),
+            "chars_total": chars_total,
+            "partial": partial,
+            "resume_from": resume_from,
+            "page_file_pattern": f"{rel_root}/pages/pNNNN.txt",
+            "full_text": full_rel,
+            "grep_hint": (
+                "sandbox_grep_content(pattern=<regex>, relative_root='derived', "
+                f"glob_filter='docs/{slug}/pages/*.txt', max_matches=200) — the file "
+                "name of each hit is the page number."
+            ),
+            "first_page_excerpt": first_excerpt,
+        }
+        if partial:
+            manifest["next_step"] = (
+                f"Budget of {budget_sec:.0f}s reached at page {resume_from}. Call "
+                f"doc_ingest again with first_page={resume_from} to resume; pages "
+                "already written are skipped."
+            )
+        else:
+            manifest["next_step"] = (
+                "Verify the document identity against the user request using "
+                "title_guess/first_page_excerpt, then grep the pages as per grep_hint."
+            )
+
+        (root / "manifest.json").write_text(
+            json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+        return manifest
+    finally:
+        try:
+            doc.close()
+        except Exception:  # noqa: BLE001 - best effort
+            pass
diff --git a/src/tools/geocode.py b/src/tools/geocode.py
new file mode 100644
index 00000000..ced2d4eb
--- /dev/null
+++ b/src/tools/geocode.py
@@ -0,0 +1,424 @@
+"""Geocoding via OpenStreetMap Nominatim (deterministic, no LLM)."""
+
+from __future__ import annotations
+
+import logging
+import math
+import os
+import re
+import threading
+import time
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+logger = logging.getLogger("aion.geocode")
+
+_last_request_at = 0.0
+_rate_lock = threading.Lock()
+
+# Rough WGS84 bounding boxes (lat_min, lat_max, lon_min, lon_max)
+_COUNTRY_BBOX: dict[str, tuple[float, float, float, float]] = {
+    "jp": (24.0, 46.5, 122.0, 154.0),
+    "it": (35.0, 48.0, 6.0, 19.5),
+}
+
+_PLACE_OF_WORSHIP = frozenset(
+    {
+        "place_of_worship",
+        "religious",
+        "temple",
+        "shrine",
+        "church",
+        "chapel",
+        "monastery",
+    }
+)
+
+_UNRELIABLE_TYPES = frozenset(
+    {
+        "hairdresser",
+        "beauty",
+        "shop",
+        "retail",
+        "company",
+        "office",
+    }
+)
+
+_SHRINE_HINT_RE = re.compile(
+    r"(jinja|taisha|shrine|inari|神社|稲荷|神宮|大社)",
+    re.IGNORECASE,
+)
+
+_REGION_TOKEN_RE = re.compile(
+    r"[\w\u3040-\u30ff\u4e00-\u9fff]+(?:県|府|道|市|区|町|村)",
+)
+
+_INARI_NEARBY_TYPES = frozenset(
+    {
+        "bus_stop",
+        "station",
+        "stop",
+        "neighbourhood",
+        "suburb",
+        "quarter",
+    }
+)
+
+
+def haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    r = 6371.0
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dphi = math.radians(lat2 - lat1)
+    dlmb = math.radians(lon2 - lon1)
+    a = math.sin(dphi / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dlmb / 2) ** 2
+    return 2 * r * math.asin(math.sqrt(a))
+
+
+def _nominatim_base_url() -> str:
+    return (
+        os.getenv("AION_GEOCODING_NOMINATIM_URL", "https://nominatim.openstreetmap.org")
+        .strip()
+        .rstrip("/")
+    )
+
+
+def _user_agent() -> str:
+    return (
+        os.getenv("AION_GEOCODING_USER_AGENT", "").strip()
+        or "AION-Agent/1.0 (+https://github.com/aion-agent; geocoding-mcp)"
+    )
+
+
+def _min_interval_sec() -> float:
+    try:
+        return max(0.0, float(os.getenv("AION_GEOCODING_MIN_INTERVAL_SEC", "1.1")))
+    except ValueError:
+        return 1.1
+
+
+def _rate_limit() -> None:
+    global _last_request_at
+    interval = _min_interval_sec()
+    with _rate_lock:
+        now = time.monotonic()
+        wait = interval - (now - _last_request_at)
+        if wait > 0:
+            time.sleep(wait)
+        _last_request_at = time.monotonic()
+
+
+def _in_bbox(lat: float, lon: float, cc: str) -> bool:
+    box = _COUNTRY_BBOX.get(cc.lower())
+    if not box:
+        return True
+    lat_min, lat_max, lon_min, lon_max = box
+    return lat_min <= lat <= lat_max and lon_min <= lon <= lon_max
+
+
+def _display_text(hit: dict[str, Any]) -> str:
+    return str(hit.get("display_name") or "")
+
+
+def _region_hints(*queries: str) -> set[str]:
+    hints: set[str] = set()
+    for query in queries:
+        for token in _REGION_TOKEN_RE.findall(query or ""):
+            token = token.strip()
+            if not token:
+                continue
+            hints.add(token)
+            if token.endswith(("県", "府", "道")):
+                hints.add(token[:-1])
+    return hints
+
+
+def _extra_queries(primary: str, fallback: str, *, shrine_query: bool) -> list[str]:
+    extras: list[str] = []
+    seen: set[str] = set()
+
+    def add(q: str) -> None:
+        q = re.sub(r"\s+", " ", (q or "").strip())
+        if q and q not in seen:
+            seen.add(q)
+            extras.append(q)
+
+    for q in (primary, fallback):
+        if "," in q:
+            add(q.replace(",", " "))
+
+    if shrine_query and fallback:
+        parts = [p.strip() for p in re.split(r"[,、]", fallback) if p.strip()]
+        if len(parts) >= 2:
+            name = parts[0]
+            loc = parts[-1]
+            loc_short = re.sub(r"(県|府|道)$", "", loc)
+            stem = re.split(r"(神社|稲荷|神宮|大社)", name, maxsplit=1)[0].strip()
+            if stem and loc_short:
+                add(f"{stem} {loc_short} 稲荷")
+
+    return extras
+
+
+def _score_hit(
+    hit: dict[str, Any],
+    *,
+    validate_contains: str,
+    shrine_query: bool,
+    region_hints: set[str],
+) -> float:
+    score = float(hit.get("importance") or 0.0)
+    typ = str(hit.get("type") or hit.get("class") or "").lower()
+    disp = _display_text(hit)
+    disp_lower = disp.lower()
+
+    if typ in _PLACE_OF_WORSHIP:
+        score += 0.35
+    elif (
+        shrine_query
+        and typ in _INARI_NEARBY_TYPES
+        and any(k in disp for k in ("稲荷", "inari", "神社"))
+    ):
+        score += 0.2
+    if typ in _UNRELIABLE_TYPES:
+        score -= 1.0
+    if validate_contains and validate_contains.lower() in disp_lower:
+        score += 0.5
+    if shrine_query and any(
+        k in disp_lower for k in ("神社", "稲荷", "jinja", "inari", "shrine")
+    ):
+        score += 0.15
+
+    if region_hints:
+        matched = [h for h in region_hints if h in disp]
+        if matched:
+            score += 0.25 * min(len(matched), 3)
+        else:
+            score -= 0.45
+
+    return score
+
+
+def _nominatim_search(
+    query: str,
+    *,
+    country_code: str,
+    limit: int,
+    client: httpx.Client | None = None,
+) -> list[dict[str, Any]]:
+    q = (query or "").strip()
+    if not q:
+        return []
+
+    params: dict[str, str | int] = {
+        "q": q,
+        "format": "json",
+        "limit": max(1, min(limit, 10)),
+        "addressdetails": 1,
+    }
+    cc = (country_code or "").strip().lower()
+    if cc:
+        params["countrycodes"] = cc
+
+    url = f"{_nominatim_base_url()}/search?{urlencode(params)}"
+    headers = {"User-Agent": _user_agent(), "Accept": "application/json"}
+
+    _rate_limit()
+    if client is not None:
+        resp = client.get(url, headers=headers, timeout=30.0)
+    else:
+        with httpx.Client() as c:
+            resp = c.get(url, headers=headers, timeout=30.0)
+    resp.raise_for_status()
+    data = resp.json()
+    if not isinstance(data, list):
+        return []
+    return [h for h in data if isinstance(h, dict)]
+
+
+def _pick_best(
+    hits: list[dict[str, Any]],
+    *,
+    country_code: str,
+    validate_contains: str,
+    shrine_query: bool,
+    region_hints: set[str],
+) -> dict[str, Any] | None:
+    cc = (country_code or "").strip().lower()
+    scored: list[tuple[float, dict[str, Any]]] = []
+    for hit in hits:
+        try:
+            lat = float(hit["lat"])
+            lon = float(hit["lon"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        if cc and not _in_bbox(lat, lon, cc):
+            continue
+        scored.append(
+            (
+                _score_hit(
+                    hit,
+                    validate_contains=validate_contains,
+                    shrine_query=shrine_query,
+                    region_hints=region_hints,
+                ),
+                hit,
+            )
+        )
+    if not scored:
+        return None
+    scored.sort(key=lambda x: x[0], reverse=True)
+    best_score, best = scored[0]
+    if best_score < -0.5:
+        return None
+    return best
+
+
+def _format_hit(hit: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "lat": float(hit["lat"]),
+        "lon": float(hit["lon"]),
+        "display_name": _display_text(hit),
+        "type": hit.get("type"),
+        "class": hit.get("class"),
+        "importance": hit.get("importance"),
+        "osm_type": hit.get("osm_type"),
+        "osm_id": hit.get("osm_id"),
+    }
+
+
+def geocode_place_sync(
+    query: str,
+    *,
+    fallback_query: str = "",
+    country_code: str = "",
+    validate_contains: str = "",
+    limit: int = 5,
+    client: httpx.Client | None = None,
+) -> dict[str, Any]:
+    """Forward geocode a place name via Nominatim with optional fallback query."""
+    primary = (query or "").strip()
+    fallback = (fallback_query or "").strip()
+    if not primary and not fallback:
+        return {"ok": False, "error": "empty_query"}
+
+    shrine_query = bool(
+        _SHRINE_HINT_RE.search(primary) or _SHRINE_HINT_RE.search(fallback)
+    )
+    validate = (validate_contains or "").strip()
+    cc = (country_code or "").strip().lower()
+    region_hints = _region_hints(primary, fallback)
+
+    attempts: list[dict[str, Any]] = []
+    all_candidates: list[dict[str, Any]] = []
+    merged_hits: list[tuple[str, dict[str, Any]]] = []
+    seen_osm: set[str] = set()
+
+    query_plan: list[tuple[str, str]] = []
+    if primary:
+        query_plan.append(("primary", primary))
+    if fallback:
+        query_plan.append(("fallback", fallback))
+    for extra in _extra_queries(primary, fallback, shrine_query=shrine_query):
+        query_plan.append(("extra", extra))
+
+    for label, q in query_plan:
+        try:
+            hits = _nominatim_search(q, country_code=cc, limit=limit, client=client)
+        except Exception as exc:
+            logger.warning("nominatim search failed query=%s: %s", q[:80], exc)
+            attempts.append({"query": q, "label": label, "error": str(exc)})
+            continue
+
+        attempts.append({"query": q, "label": label, "hit_count": len(hits)})
+        for h in hits:
+            all_candidates.append({**_format_hit(h), "query_used": q})
+            osm_type = h.get("osm_type")
+            osm_id = h.get("osm_id")
+            if osm_type and osm_id:
+                osm_key = f"{osm_type}:{osm_id}"
+            else:
+                osm_key = f"{h.get('lat')}:{h.get('lon')}:{h.get('display_name')}"
+            if osm_key in seen_osm:
+                continue
+            seen_osm.add(osm_key)
+            merged_hits.append((q, h))
+
+    best = _pick_best(
+        [h for _, h in merged_hits],
+        country_code=cc,
+        validate_contains=validate,
+        shrine_query=shrine_query,
+        region_hints=region_hints,
+    )
+    if best is not None:
+        formatted = _format_hit(best)
+        query_used = ""
+        for q, h in merged_hits:
+            if h is best:
+                query_used = q
+                break
+        validated = True
+        reason = ""
+        disp = formatted["display_name"].lower()
+        if validate and validate.lower() not in disp:
+            validated = False
+            reason = f"validate_contains '{validate}' not in display_name"
+
+        typ = str(formatted.get("type") or "").lower()
+        if shrine_query and typ in _UNRELIABLE_TYPES:
+            validated = False
+            reason = f"unreliable type '{typ}' for shrine-like query"
+
+        return {
+            "ok": True,
+            "query_used": query_used,
+            "validated": validated,
+            "validation_note": reason,
+            **formatted,
+            "candidates": all_candidates[:10],
+            "source": "nominatim",
+        }
+
+    return {
+        "ok": False,
+        "error": "no_suitable_hit",
+        "attempts": attempts,
+        "candidates": all_candidates[:10],
+        "source": "nominatim",
+    }
+
+
+def reverse_geocode_sync(
+    lat: float,
+    lon: float,
+    *,
+    client: httpx.Client | None = None,
+) -> dict[str, Any]:
+    """Reverse geocode coordinates (sanity check)."""
+    params = {
+        "lat": lat,
+        "lon": lon,
+        "format": "json",
+        "addressdetails": 1,
+    }
+    url = f"{_nominatim_base_url()}/reverse?{urlencode(params)}"
+    headers = {"User-Agent": _user_agent(), "Accept": "application/json"}
+    _rate_limit()
+    if client is not None:
+        resp = client.get(url, headers=headers, timeout=30.0)
+    else:
+        with httpx.Client() as c:
+            resp = c.get(url, headers=headers, timeout=30.0)
+    resp.raise_for_status()
+    data = resp.json()
+    if not isinstance(data, dict):
+        return {"ok": False, "error": "invalid_response"}
+    return {
+        "ok": True,
+        "display_name": data.get("display_name"),
+        "address": data.get("address"),
+        "source": "nominatim",
+    }
diff --git a/src/tools/office_auto_convert.py b/src/tools/office_auto_convert.py
new file mode 100644
index 00000000..f0ed7ffe
--- /dev/null
+++ b/src/tools/office_auto_convert.py
@@ -0,0 +1,97 @@
+"""Apply legacy Word conversion after session upload (blocking, API host)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+from src.tools.office_convert import (
+    conversion_manifest_path,
+    convert_legacy_word_sync,
+    is_legacy_word_upload,
+    office_auto_convert_enabled,
+    retry_legacy_word_conversion,
+)
+
+logger = logging.getLogger("aion.office_auto_convert")
+
+
+def _persist_manifest(session_id: str, upload_meta: dict[str, Any]) -> None:
+    rel = str(upload_meta.get("relative_path") or "")
+    if not rel:
+        return
+    path = conversion_manifest_path(session_id, rel)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "relative_path": rel,
+        "original_name": upload_meta.get("original_name"),
+        "legacy_word": upload_meta.get("legacy_word"),
+        "conversion_status": upload_meta.get("conversion_status"),
+        "converted_docx_path": upload_meta.get("converted_docx_path"),
+        "conversion_error": upload_meta.get("conversion_error"),
+        "conversion_note": upload_meta.get("conversion_note"),
+    }
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def load_conversion_manifest(session_id: str, upload_rel: str) -> dict[str, Any] | None:
+    path = conversion_manifest_path(session_id, upload_rel)
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    status = str(data.get("conversion_status") or "")
+    conv = data.get("converted_docx_path")
+    if status != "ok" or not conv:
+        retried = retry_legacy_word_conversion(session_id, upload_rel)
+        _persist_manifest(session_id, retried)
+        if retried.get("conversion_status") == "ok":
+            return {
+                "relative_path": upload_rel,
+                "original_name": retried.get("original_name"),
+                "legacy_word": True,
+                "conversion_status": "ok",
+                "converted_docx_path": retried.get("converted_docx_path"),
+                "conversion_note": retried.get("conversion_note"),
+            }
+        return data
+    return data
+
+
+async def apply_legacy_word_conversion(
+    session_id: str,
+    upload_meta: dict[str, Any],
+) -> dict[str, Any]:
+    if not office_auto_convert_enabled():
+        return upload_meta
+    name = str(upload_meta.get("original_name") or "")
+    mime = str(upload_meta.get("mime") or "")
+    if not is_legacy_word_upload(name, mime):
+        return upload_meta
+    try:
+        meta = await asyncio.to_thread(
+            convert_legacy_word_sync, session_id, dict(upload_meta)
+        )
+        await asyncio.to_thread(_persist_manifest, session_id, meta)
+        return meta
+    except Exception as exc:
+        logger.exception(
+            "legacy_word_conversion failed session=%s path=%s",
+            session_id[:8],
+            upload_meta.get("relative_path"),
+        )
+        upload_meta = dict(upload_meta)
+        upload_meta.update(
+            {
+                "legacy_word": True,
+                "conversion_status": "failed",
+                "conversion_error": str(exc),
+            }
+        )
+        return upload_meta
diff --git a/src/tools/office_convert.py b/src/tools/office_convert.py
new file mode 100644
index 00000000..2103fe56
--- /dev/null
+++ b/src/tools/office_convert.py
@@ -0,0 +1,263 @@
+"""Convert legacy Word binaries (.doc) to .docx on the API host via LibreOffice."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from src.session_workspace import safe_resolve, session_root
+
+logger = logging.getLogger("aion.office_convert")
+
+_OLE_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+_ZIP_MAGIC = b"PK\x03\x04"
+
+_LEGACY_WORD_EXTS = frozenset({".doc", ".dot", ".wps"})
+_LEGACY_WORD_MIMES = frozenset(
+    {
+        "application/msword",
+        "application/vnd.ms-word",
+        "application/vnd.ms-word.document.macroenabled.12",
+    }
+)
+
+_CONVERTED_SUBDIR = "derived/converted"
+
+
+def office_auto_convert_enabled() -> bool:
+    return os.getenv("AION_OFFICE_AUTO_CONVERT_LEGACY_WORD", "1").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+
+
+def _convert_timeout_sec() -> float:
+    try:
+        return max(5.0, float(os.getenv("AION_OFFICE_CONVERT_TIMEOUT_SEC", "90")))
+    except ValueError:
+        return 90.0
+
+
+def is_legacy_word_upload(filename: str, mime: str, data: bytes | None = None) -> bool:
+    name = (filename or "").lower()
+    ext = Path(name).suffix
+    mime_l = (mime or "").split(";")[0].strip().lower()
+    if ext in _LEGACY_WORD_EXTS or mime_l in _LEGACY_WORD_MIMES:
+        return True
+    if data is not None and ext == ".doc":
+        head = data[:8]
+        if head.startswith(_OLE_MAGIC):
+            return True
+        if head.startswith(_ZIP_MAGIC):
+            return False
+    return False
+
+
+def is_misnamed_docx(filename: str, data: bytes) -> bool:
+    """`.doc` extension but OpenXML zip payload."""
+    if not (filename or "").lower().endswith(".doc"):
+        return False
+    return data[:4] == _ZIP_MAGIC
+
+
+def find_soffice() -> str | None:
+    explicit = (os.getenv("AION_SOFFICE_PATH") or "").strip()
+    if explicit and Path(explicit).is_file():
+        return explicit
+    found = shutil.which("soffice")
+    if found:
+        return found
+    for candidate in (
+        "/Applications/LibreOffice.app/Contents/MacOS/soffice",
+        "/usr/bin/soffice",
+        "/usr/local/bin/soffice",
+    ):
+        if Path(candidate).is_file():
+            return candidate
+    return None
+
+
+def _safe_stem(filename: str) -> str:
+    stem = Path(filename).stem or "document"
+    stem = re.sub(r"[^\w.\-]+", "_", stem).strip("._")
+    return stem or "document"
+
+
+def _copy_as_docx(session_id: str, src_rel: str, original_name: str) -> dict[str, Any]:
+    src = safe_resolve(session_id, src_rel, must_exist=True)
+    out_name = f"{_safe_stem(original_name)}.docx"
+    out_rel = f"{_CONVERTED_SUBDIR}/{out_name}"
+    out_path = safe_resolve(session_id, out_rel, must_exist=False)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, out_path)
+    return {
+        "legacy_word": True,
+        "conversion_status": "ok",
+        "conversion_method": "rename_zip",
+        "converted_docx_path": out_rel,
+        "conversion_note": (
+            "File had a .doc extension but is already OpenXML; copied as .docx."
+        ),
+    }
+
+
+def convert_legacy_word_sync(
+    session_id: str,
+    upload_meta: dict[str, Any],
+) -> dict[str, Any]:
+    """
+    Convert a legacy Word upload to docx under derived/converted/ via LibreOffice.
+
+    Mutates and returns ``upload_meta`` with conversion fields.
+    """
+    rel = str(upload_meta.get("relative_path") or "")
+    original_name = str(upload_meta.get("original_name") or Path(rel).name)
+    mime = str(upload_meta.get("mime") or "")
+
+    if not rel:
+        return upload_meta
+
+    if not is_legacy_word_upload(original_name, mime):
+        return upload_meta
+
+    src = safe_resolve(session_id, rel, must_exist=True)
+    data = src.read_bytes()
+
+    if is_misnamed_docx(original_name, data):
+        upload_meta.update(_copy_as_docx(session_id, rel, original_name))
+        return upload_meta
+
+    soffice = find_soffice()
+    if not soffice:
+        upload_meta.update(
+            {
+                "legacy_word": True,
+                "conversion_status": "unavailable",
+                "conversion_error": (
+                    "LibreOffice (soffice) not found on the API host. "
+                    "Install libreoffice-writer-nogui (Docker/Ubuntu) or set AION_SOFFICE_PATH."
+                ),
+            }
+        )
+        return upload_meta
+
+    out_name = f"{_safe_stem(original_name)}.docx"
+    out_rel = f"{_CONVERTED_SUBDIR}/{out_name}"
+    out_path = safe_resolve(session_id, out_rel, must_exist=False)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.TemporaryDirectory(prefix="aion-lo-") as tmp:
+        tmp_in = Path(tmp) / Path(original_name).name
+        tmp_in.write_bytes(data)
+        cmd = [
+            soffice,
+            "--headless",
+            "--norestore",
+            "--invisible",
+            "--convert-to",
+            "docx",
+            "--outdir",
+            tmp,
+            str(tmp_in),
+        ]
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=_convert_timeout_sec(),
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            upload_meta.update(
+                {
+                    "legacy_word": True,
+                    "conversion_status": "failed",
+                    "conversion_error": "LibreOffice conversion timed out",
+                }
+            )
+            return upload_meta
+        except OSError as exc:
+            upload_meta.update(
+                {
+                    "legacy_word": True,
+                    "conversion_status": "failed",
+                    "conversion_error": str(exc),
+                }
+            )
+            return upload_meta
+
+        if proc.returncode != 0:
+            err = (proc.stderr or proc.stdout or "").strip()[:500]
+            logger.warning(
+                "soffice convert failed session=%s file=%s rc=%s err=%s",
+                session_id[:8],
+                original_name,
+                proc.returncode,
+                err,
+            )
+            upload_meta.update(
+                {
+                    "legacy_word": True,
+                    "conversion_status": "failed",
+                    "conversion_error": err or f"soffice exit {proc.returncode}",
+                }
+            )
+            return upload_meta
+
+        produced = sorted(Path(tmp).glob("*.docx"))
+        if not produced:
+            upload_meta.update(
+                {
+                    "legacy_word": True,
+                    "conversion_status": "failed",
+                    "conversion_error": "LibreOffice produced no .docx output",
+                }
+            )
+            return upload_meta
+
+        shutil.copy2(produced[0], out_path)
+
+    upload_meta.update(
+        {
+            "legacy_word": True,
+            "conversion_status": "ok",
+            "conversion_method": "libreoffice",
+            "converted_docx_path": out_rel,
+            "conversion_note": (
+                f"Legacy Word converted to `{out_rel}`. "
+                "Use the .docx path with skill_view('docx') / unpack workflow; "
+                "do not run unpack on the original .doc binary."
+            ),
+        }
+    )
+    logger.info(
+        "legacy_word_converted session=%s src=%s out=%s",
+        session_id[:8],
+        rel,
+        out_rel,
+    )
+    return upload_meta
+
+
+def retry_legacy_word_conversion(session_id: str, upload_rel: str) -> dict[str, Any]:
+    """Re-attempt conversion (e.g. after a prior unavailable manifest)."""
+    meta = {
+        "relative_path": upload_rel,
+        "original_name": Path(upload_rel).name,
+        "mime": "application/msword",
+    }
+    return convert_legacy_word_sync(session_id, meta)
+
+
+def conversion_manifest_path(session_id: str, upload_rel: str) -> Path:
+    slug = re.sub(r"[^\w.\-]+", "_", Path(upload_rel).name).strip("._") or "upload"
+    return session_root(session_id) / "derived" / "converted" / f"{slug}.json"
diff --git a/src/tools/pdf_evidence.py b/src/tools/pdf_evidence.py
new file mode 100644
index 00000000..dafae1c2
--- /dev/null
+++ b/src/tools/pdf_evidence.py
@@ -0,0 +1,383 @@
+"""Crop PDF pages into evidence PNGs for Word report deliverables.
+
+Renders a page (or clip region) via PyMuPDF, optionally auto-trims whitespace with
+Pillow, and writes PNG + JSON sidecar under ``derived/docs/<slug>/evidence/``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Optional
+
+from src.tools.doc_ingest import DOCS_SUBDIR, slugify_document_name
+
+__all__ = ["pdf_evidence_crop_sync", "compute_white_ratio", "auto_trim_image"]
+
+_EVIDENCE_RE = re.compile(r"^e(\d+)\.png$")
+_DEFAULT_DPI = 200
+_DEFAULT_MAX_WHITE_RATIO = 0.90
+_DEFAULT_TRIM_THRESHOLD = 250
+_DEFAULT_TRIM_PADDING = 8
+
+
+def _env_int(name: str, default: int) -> int:
+    val = os.getenv(name, "").strip()
+    if not val:
+        return default
+    try:
+        return int(val)
+    except ValueError:
+        return default
+
+
+def _env_float(name: str, default: float) -> float:
+    val = os.getenv(name, "").strip()
+    if not val:
+        return default
+    try:
+        return float(val)
+    except ValueError:
+        return default
+
+
+def default_dpi() -> int:
+    return max(72, _env_int("AION_PDF_EVIDENCE_DPI", _DEFAULT_DPI))
+
+
+def max_white_ratio() -> float:
+    return min(
+        1.0,
+        max(
+            0.0,
+            _env_float("AION_PDF_EVIDENCE_MAX_WHITE_RATIO", _DEFAULT_MAX_WHITE_RATIO),
+        ),
+    )
+
+
+def _open_pdf(path: Path):
+    try:
+        import pymupdf  # type: ignore
+    except ImportError:  # pragma: no cover
+        import fitz as pymupdf  # type: ignore
+    return pymupdf.open(str(path))
+
+
+def _pymupdf_module():
+    try:
+        import pymupdf  # type: ignore
+    except ImportError:  # pragma: no cover
+        import fitz as pymupdf  # type: ignore
+    return pymupdf
+
+
+def _text_blocks_clip(pdf_page, *, padding: int = 12):
+    """Union bounding box of text blocks on a PDF page (PyMuPDF points)."""
+    pymupdf = _pymupdf_module()
+    blocks = [
+        block
+        for block in pdf_page.get_text("blocks")
+        if len(block) >= 7 and block[6] == 0 and str(block[4] or "").strip()
+    ]
+    if not blocks:
+        return None
+    x0 = min(block[0] for block in blocks)
+    y0 = min(block[1] for block in blocks)
+    x1 = max(block[2] for block in blocks)
+    y1 = max(block[3] for block in blocks)
+    clip = (
+        pymupdf.Rect(x0 - padding, y0 - padding, x1 + padding, y1 + padding)
+        & pdf_page.rect
+    )
+    return None if clip.is_empty else clip
+
+
+def _page_text_char_count(pdf_page) -> int:
+    return len((pdf_page.get_text("text") or "").strip())
+
+
+def _pixmap_to_image(pixmap):
+    """Convert a PyMuPDF pixmap to PIL Image (handles colorspace variants)."""
+    from io import BytesIO
+
+    from PIL import Image
+
+    return Image.open(BytesIO(pixmap.tobytes("png")))
+
+
+def _iter_rgb_pixels(rgb_image):
+    """Yield ``(r, g, b)`` regardless of Pillow pixel API version."""
+    if hasattr(rgb_image, "get_flattened_data"):
+        data = rgb_image.get_flattened_data()
+        if not data:
+            return
+        if isinstance(data[0], (tuple, list)):
+            for px in data:
+                yield int(px[0]), int(px[1]), int(px[2])
+            return
+        for i in range(0, len(data), 3):
+            yield int(data[i]), int(data[i + 1]), int(data[i + 2])
+        return
+    for r, g, b in rgb_image.getdata():
+        yield int(r), int(g), int(b)
+
+
+def compute_white_ratio(image, *, threshold: int = _DEFAULT_TRIM_THRESHOLD) -> float:
+    """Fraction of pixels at or above ``threshold`` on all RGB channels."""
+    from PIL import Image
+
+    if not isinstance(image, Image.Image):
+        raise TypeError("image must be a PIL.Image")
+    rgb = image.convert("RGB")
+    total = 0
+    white = 0
+    for r, g, b in _iter_rgb_pixels(rgb):
+        total += 1
+        if r >= threshold and g >= threshold and b >= threshold:
+            white += 1
+    return (white / total) if total else 1.0
+
+
+def auto_trim_image(
+    image,
+    *,
+    padding: int = _DEFAULT_TRIM_PADDING,
+    threshold: int = _DEFAULT_TRIM_THRESHOLD,
+):
+    """Crop to the bounding box of non-white content."""
+    from PIL import Image
+
+    if not isinstance(image, Image.Image):
+        raise TypeError("image must be a PIL.Image")
+    gray = image.convert("L")
+    mask = gray.point(lambda p: 255 if p < threshold else 0)
+    bbox = mask.getbbox()
+    if not bbox:
+        return image
+    x0, y0, x1, y1 = bbox
+    x0 = max(0, x0 - padding)
+    y0 = max(0, y0 - padding)
+    x1 = min(image.width, x1 + padding)
+    y1 = min(image.height, y1 + padding)
+    return image.crop((x0, y0, x1, y1))
+
+
+def _next_evidence_index(evidence_dir: Path) -> int:
+    max_idx = 0
+    for path in evidence_dir.glob("e*.png"):
+        match = _EVIDENCE_RE.match(path.name)
+        if match:
+            max_idx = max(max_idx, int(match.group(1)))
+    return max_idx + 1
+
+
+def _parse_bbox(raw: Any) -> Optional[tuple[float, float, float, float]]:
+    if raw is None:
+        return None
+    if isinstance(raw, (list, tuple)) and len(raw) == 4:
+        return tuple(float(v) for v in raw)
+    if isinstance(raw, dict):
+        keys = ("x0", "y0", "x1", "y1")
+        if all(k in raw for k in keys):
+            return tuple(float(raw[k]) for k in keys)
+    raise ValueError("bbox must be {x0,y0,x1,y1} or [x0,y0,x1,y1]")
+
+
+def _relative_to_session(session_root: Path, path: Path) -> str:
+    try:
+        return path.resolve().relative_to(session_root.resolve()).as_posix()
+    except ValueError:
+        # Unit tests and out-of-session paths: keep a stable relative label.
+        return path.name
+
+
+def pdf_evidence_crop_sync(
+    pdf_path: Path,
+    session_root: Path,
+    *,
+    page: int,
+    bbox: Any = None,
+    full_page: bool = False,
+    dpi: Optional[int] = None,
+    caption: str = "",
+    source_relative_path: str = "",
+) -> dict:
+    """Render a PDF page clip to PNG + JSON sidecar under derived/docs/<slug>/evidence/."""
+    if page < 1:
+        return {
+            "ok": False,
+            "error": "invalid_page",
+            "message": f"page must be >= 1, got {page}",
+        }
+    if not pdf_path.is_file():
+        return {
+            "ok": False,
+            "error": "not_a_file",
+            "message": f"{pdf_path.name} is not a readable file",
+        }
+
+    render_dpi = dpi if dpi is not None else default_dpi()
+    render_dpi = max(72, min(render_dpi, 600))
+    white_limit = max_white_ratio()
+
+    try:
+        clip = _parse_bbox(bbox)
+    except ValueError as exc:
+        return {"ok": False, "error": "invalid_bbox", "message": str(exc)}
+
+    slug = slugify_document_name(pdf_path.name)
+    evidence_dir = session_root / DOCS_SUBDIR / slug / "evidence"
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+    index = _next_evidence_index(evidence_dir)
+    stem = f"e{index:03d}"
+    png_path = evidence_dir / f"{stem}.png"
+    sidecar_path = evidence_dir / f"{stem}.json"
+
+    try:
+        doc = _open_pdf(pdf_path)
+    except Exception as exc:
+        return {
+            "ok": False,
+            "error": "pdf_open_failed",
+            "message": str(exc),
+        }
+
+    try:
+        if page > doc.page_count:
+            return {
+                "ok": False,
+                "error": "page_out_of_range",
+                "message": f"page {page} exceeds document page count {doc.page_count}",
+                "page_count": doc.page_count,
+            }
+
+        pdf_page = doc[page - 1]
+        page_rect = pdf_page.rect
+        pymupdf = _pymupdf_module()
+        crop_method = "full_page" if full_page and clip is None else "bbox"
+        text_chars = _page_text_char_count(pdf_page)
+
+        def _render_clip(clip_rect, *, method: str):
+            nonlocal crop_method
+            if clip_rect is None or clip_rect.is_empty:
+                return None
+            crop_method = method
+            bbox_used = [clip_rect.x0, clip_rect.y0, clip_rect.x1, clip_rect.y1]
+            pix = pdf_page.get_pixmap(dpi=render_dpi, clip=clip_rect, alpha=False)
+            return bbox_used, pix
+
+        used_bbox = [page_rect.x0, page_rect.y0, page_rect.x1, page_rect.y1]
+        pixmap = None
+        cropped = False
+
+        if clip is not None:
+            x0, y0, x1, y1 = clip
+            clip_rect = pymupdf.Rect(x0, y0, x1, y1) & page_rect
+            if clip_rect.is_empty:
+                return {
+                    "ok": False,
+                    "error": "empty_clip",
+                    "message": "bbox does not intersect the page",
+                }
+            rendered = _render_clip(clip_rect, method="bbox")
+            if rendered is None:
+                return {
+                    "ok": False,
+                    "error": "empty_clip",
+                    "message": "bbox does not intersect the page",
+                }
+            used_bbox, pixmap = rendered
+        elif not full_page:
+            text_clip = _text_blocks_clip(pdf_page)
+            if text_clip is not None:
+                rendered = _render_clip(text_clip, method="text_blocks")
+                if rendered is not None:
+                    used_bbox, pixmap = rendered
+                    cropped = True
+            if pixmap is None:
+                pixmap = pdf_page.get_pixmap(dpi=render_dpi, alpha=False)
+                used_bbox = [page_rect.x0, page_rect.y0, page_rect.x1, page_rect.y1]
+                crop_method = "auto_trim"
+        else:
+            pixmap = pdf_page.get_pixmap(dpi=render_dpi, alpha=False)
+            used_bbox = [page_rect.x0, page_rect.y0, page_rect.x1, page_rect.y1]
+
+        image = _pixmap_to_image(pixmap)
+        if clip is None and not full_page and crop_method == "auto_trim":
+            image = auto_trim_image(image)
+            cropped = True
+
+        white_ratio = compute_white_ratio(image)
+        # Pages with a real text layer may stay visually sparse after trim; allow a
+        # slightly higher ceiling than blank full-page dumps.
+        effective_white_limit = white_limit
+        if crop_method in {"text_blocks", "auto_trim"} and text_chars >= 80:
+            effective_white_limit = min(0.97, white_limit + 0.07)
+        rel_png = _relative_to_session(session_root, png_path)
+        rel_sidecar = _relative_to_session(session_root, sidecar_path)
+        rel_source = source_relative_path or _relative_to_session(
+            session_root, pdf_path
+        )
+
+        sidecar = {
+            "page": page,
+            "bbox": used_bbox,
+            "dpi": render_dpi,
+            "white_ratio": round(white_ratio, 4),
+            "cropped": cropped,
+            "crop_method": crop_method,
+            "text_chars": text_chars,
+            "caption": caption,
+            "source_path": rel_source,
+            "png_path": rel_png,
+            "full_page": bool(full_page and clip is None),
+        }
+
+        if white_ratio > effective_white_limit:
+            hint = (
+                "Provide an explicit bbox around the prescription block, or confirm the page "
+                "has visible content."
+            )
+            if text_chars < 20:
+                hint = (
+                    "Page has little or no extractable text — verify page number and PDF path "
+                    f"({rel_source})."
+                )
+            sidecar["warning"] = (
+                f"white_ratio {white_ratio:.2f} exceeds limit {effective_white_limit:.2f}; "
+                "image looks like a full-page dump — provide a tighter bbox or verify content."
+            )
+            return {
+                "ok": False,
+                "error": "too_much_whitespace",
+                "white_ratio": round(white_ratio, 4),
+                "max_white_ratio": effective_white_limit,
+                "warning": sidecar["warning"],
+                "hint": hint,
+                "png_path": rel_png,
+                "sidecar_path": rel_sidecar,
+                **sidecar,
+            }
+
+        image.save(png_path, format="PNG", optimize=True)
+        sidecar_path.write_text(
+            json.dumps(sidecar, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+
+        return {
+            "ok": True,
+            "png_path": rel_png,
+            "sidecar_path": rel_sidecar,
+            "slug": slug,
+            **sidecar,
+        }
+    except Exception as exc:
+        return {
+            "ok": False,
+            "error": "crop_failed",
+            "message": str(exc),
+        }
+    finally:
+        doc.close()
diff --git a/website/sidebars.ts b/website/sidebars.ts
index 45cd068c..e8bef8af 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -35,6 +35,8 @@ const sidebars: SidebarsConfig = {
         'configuration/web-search-and-fetch',
         'configuration/profiles',
         'configuration/skills-and-prompts',
+        'configuration/office-and-legacy-word',
+        'configuration/document-evidence',
         'configuration/soul-memory-user',
       ],
     },