feat: root agent hierarchy at Level 1 from both orchestrators

Gemini and OpenAI orchestrators now inject _agent_level=1 into spawn_agent
args so the full 3-level chain works: Persona (L1) → Specialist (L2) →
Support (L3, cannot delegate further).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

cortex/openai_orchestrator.py

@@ -509,6 +509,8 @@ async def _execute_tool(
         args = json.loads(arguments_json)
     except json.JSONDecodeError:
         args = {}
+    if name == "spawn_agent":
+        args = {**args, "_agent_level": 1}
     try:
         return await call_tool(name, args, callables)
     except Exception as e:
@@ -524,6 +526,8 @@ async def _execute_tool_dict(
 ) -> str:
     """Execute a tool from a pre-parsed args dict."""
     _, callables = get_tools_for_role(user_role, tool_list)
+    if name == "spawn_agent":
+        args = {**args, "_agent_level": 1}
     try:
         return await call_tool(name, args, callables)
     except Exception as e:

cortex/orchestrator_engine.py

@@ -468,6 +468,8 @@ async def _claude_handoff(
 
 async def _execute_tool(name: str, args: dict, callables: dict | None = None) -> str:
     """Execute a single tool call, catching all exceptions."""
+    if name == "spawn_agent":
+        args = {**args, "_agent_level": 1}
     try:
         return await call_tool(name, args, callables)
     except Exception as e:

documentation/ROADMAP.md

@@ -77,3 +77,4 @@
 - **RAG via Open WebUI** — feed Nextcloud docs into local knowledge collections; possible complement to AE Journals search
 - **Multi-host local models** — per-user config already supports multiple hosts; routing logic TBD
 - **WhatsApp** — requires Business API account or a bridge; not started
+- **Docling** (https://github.com/docling-project/docling) — IBM Research doc parser; converts PDF/DOCX/PPTX/images → clean Markdown/JSON for LLM ingestion; would enhance file attachments and the knowledge import pipeline

documentation/TODO__Agents.md

@@ -97,10 +97,10 @@ pipelines) unusable without freezing the orchestrator.
 - [x] **L2→L3 boundary enforcement** — `spawn_agent` param `_agent_level` (default 2);
       when `child_level >= 3`, auto-adds `spawn_agent` + `aider_run` to deny_tools so
       Level 3 children cannot delegate; level stored in AgentRecord — 2026-06-03
-- [ ] **`_agent_level=1` from main orchestrators** — Gemini and OpenAI orchestrators
-      should pass `_agent_level=1` when calling spawn_agent so the hierarchy is rooted
-      correctly; currently defaults to 2 (children become Level 3, which is safe but
-      means Level 1 cannot spawn Level 2 that itself spawns Level 3)
+- [x] **`_agent_level=1` from main orchestrators** — Gemini and OpenAI orchestrators
+      inject `_agent_level=1` into args in `_execute_tool` / `_execute_tool_dict` so the
+      hierarchy is rooted correctly; Persona spawns Level 2 agents that can themselves
+      spawn Level 3 — 2026-06-16
 
 **Phase 3 — `aider_run` async:**
 - [x] **`aider_run` background mode** — added `background: bool = False` and
@@ -313,6 +313,22 @@ and lint commands; model/key come from env vars (not committed).
 - `cortex/routers/` already has pattern; add `gitea.py`
 - Gitea Actions (CI) for "run tests on push" — simpler than custom runner
 
+### [Intelligence] Docling — document parsing for LLM ingestion
+https://github.com/docling-project/docling
+
+IBM Research library that converts PDF, DOCX, PPTX, XLSX, images, HTML, and more into
+clean Markdown or structured JSON ready for LLM consumption. Two integration points:
+
+- **File attachment enrichment** — today, non-text attachments are limited; Docling would
+  let Cortex extract structured content from PDFs and Office docs before injecting into context
+- **Knowledge ingestion pipeline** — convert Nextcloud files (meeting notes, contracts, reports)
+  into AE Journal entries or a local RAG corpus; complements the existing markdown import script
+- **`file_read` / `web_read` enhancement** — optionally route binary file types through Docling
+  for clean extraction instead of raw binary handling
+
+Install: `pip install docling`; GPU-accelerated OCR support available.
+No design started — evaluate before integrating.
+
 ### [Local] RAG via Open WebUI
 Open WebUI has a full RAG pipeline (file upload → embed → knowledge collections →
 reference in chat). Could feed Nextcloud docs or session logs into a local knowledge