Merge commit 'refs/phase3/pre-ajax/publication-tip' into integration/pre-ajax-release

# Conflicts:
#	routes/chat_routes.py
#	routes/session_routes.py
#	src/agent_loop.py
#	src/agent_tools/filesystem_tools.py
#	src/teacher_escalation.py
#	src/tool_capabilities.py
#	src/tool_execution.py
#	tests/test_mcp_add_server_args_validation.py
#	tests/test_token_cache_atomic_swap.py

tests/test_code_nav_tools.py

@@ -17,7 +17,10 @@ def _run(tool, content):
 @pytest.fixture
 def repo():
     # Built under /tmp, which is on the default tool-path allowlist.
-    root = tempfile.mkdtemp(dir="/tmp", prefix="codenav_")
+    # realpath because the code under test resolves the path it reports, and on
+    # macOS /tmp is a symlink to /private/tmp: comparing the unresolved path
+    # against the resolved one fails on a file both sides found correctly.
+    root = os.path.realpath(tempfile.mkdtemp(dir="/tmp", prefix="codenav_"))
     try:
         with open(os.path.join(root, "a.py"), "w") as f:
             f.write("import os\n# needle here\nprint('x')\n")
@@ -207,3 +210,49 @@ def test_read_file_plain_path_backcompat(repo):
     r = _run("read_file", os.path.join(repo, "a.py"))
     assert r["exit_code"] == 0
     assert "needle" in r["output"]
+
+
+def test_read_file_extracts_structured_documents(repo, monkeypatch):
+    p = os.path.join(repo, "report.docx")
+    with open(p, "wb") as f:
+        f.write(b"PK fake structured document")
+
+    calls = []
+
+    def _fake_extract(path, **kwargs):
+        calls.append((path, kwargs))
+        return "Heading\nFirst fact\nSecond fact\n"
+
+    monkeypatch.setattr(
+        "src.document_processor.extract_local_document",
+        _fake_extract,
+    )
+
+    r = _run("read_file", f'{{"path": "{p}", "offset": 2, "limit": 2}}')
+
+    assert r == {"output": "First fact\nSecond fact\n", "exit_code": 0}
+    assert calls == [(p, {
+        "display_name": "report.docx",
+        "analyze_embedded_images": False,
+    })]
+
+
+def test_read_file_extracts_legacy_word_documents(repo, monkeypatch):
+    p = os.path.join(repo, "report.doc")
+    with open(p, "wb") as f:
+        f.write(b"binary OLE document")
+
+    calls = []
+
+    def _fake_extract(path, **kwargs):
+        calls.append((path, kwargs))
+        return "Legacy Word content\nShipping price\n"
+
+    monkeypatch.setattr("src.document_processor.extract_local_document", _fake_extract)
+    r = _run("read_file", p)
+
+    assert r == {"output": "Legacy Word content\nShipping price\n", "exit_code": 0}
+    assert calls == [(p, {
+        "display_name": "report.doc",
+        "analyze_embedded_images": False,
+    })]