diff --git a/src/backend/app/agent/__init__.py b/src/backend/app/agent/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/backend/app/agent/chat/__init__.py b/src/backend/app/agent/chat/__init__.py
new file mode 100644
index 00000000..74d52246
--- /dev/null
+++ b/src/backend/app/agent/chat/__init__.py
@@ -0,0 +1,5 @@
+"""Chat completion and message-adjacent agent types (shared API + runner)."""
+
+from app.agent.chat.completion_params import ChatCompletionParams
+
+__all__ = ["ChatCompletionParams"]
diff --git a/src/backend/app/agent/chat/completion_params.py b/src/backend/app/agent/chat/completion_params.py
new file mode 100644
index 00000000..966baf5d
--- /dev/null
+++ b/src/backend/app/agent/chat/completion_params.py
@@ -0,0 +1,36 @@
+"""LLM call parameters for chat turns (REST and executor share this model)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ChatCompletionParams(BaseModel):
+    """
+    Overrides for a single assistant generation.
+    Omitted fields fall back to `AgentConfig` / provider defaults.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    provider: str | None = Field(
+        default=None,
+        description="Registered provider name, e.g. openai",
+    )
+    model: str | None = Field(
+        default=None,
+        description="Provider model id, e.g. gpt-4o-mini",
+    )
+    temperature: float | None = Field(default=None, ge=0.0, le=2.0)
+    max_tokens: int | None = Field(default=None, ge=1, le=128_000)
+    top_p: float | None = Field(default=None, ge=0.0, le=1.0)
+    frequency_penalty: float | None = Field(default=None, ge=-2.0, le=2.0)
+    presence_penalty: float | None = Field(default=None, ge=-2.0, le=2.0)
+    stop: list[str] | None = Field(default=None, max_length=8)
+
+    def provider_create_kwargs(self) -> dict:
+        """Keyword args for `LLMFactory.create` / ChatOpenAI (excluding provider+model)."""
+        return self.model_dump(
+            exclude={"provider", "model"},
+            exclude_none=True,
+        )
diff --git a/src/backend/app/agent/config.py b/src/backend/app/agent/config.py
new file mode 100644
index 00000000..e5982af0
--- /dev/null
+++ b/src/backend/app/agent/config.py
@@ -0,0 +1,33 @@
+import os
+from functools import lru_cache
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class AgentConfig(BaseSettings):
+    # LLM defaults
+    default_provider: str = "openai"
+    default_model: str = "gpt-4o"
+    openai_api_key: str = ""
+
+    # Agent behavior
+    max_iterations: int = Field(default=10, ge=1, le=1000)
+    max_total_tokens: int = Field(default=128_000, ge=1024)
+
+    # VectorLink
+    vectorlink_url: str = "http://localhost:8080"
+
+    model_config = SettingsConfigDict(
+        env_prefix="AGENT_",
+        env_file=os.environ.get("ENV_FILE", ".env"),
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+
+@lru_cache()
+def get_agent_settings() -> AgentConfig:
+    return AgentConfig()
+
+
+settings = get_agent_settings()
diff --git a/src/backend/app/agent/context/__init__.py b/src/backend/app/agent/context/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/backend/app/agent/context/context_builder.py b/src/backend/app/agent/context/context_builder.py
new file mode 100644
index 00000000..9cb51ecc
--- /dev/null
+++ b/src/backend/app/agent/context/context_builder.py
@@ -0,0 +1,57 @@
+from app.agent.context.graph_traversal import GraphTraversal
+from app.agent.context.vectorlink_client import VectorLinkClient
+from app.agent.context.token_tracker import TokenTracker
+
+
+class ContextBUilder:
+    """Assemble prompt context from multiple sources within a token budget."""
+
+    def __init__(self,
+                 graph: GraphTraversal,
+                 vectorlink: VectorLinkClient,
+                 budget: TokenTracker):
+        self.graph = graph
+        self.vectorlink = vectorlink
+        self.budget = budget
+
+    async def build_context(
+        self,
+        *,
+        node_id: str | None = None,
+        query: str | None = None,
+        include_code: bool = False,
+        traversal_direction: str = "down",
+        traversal_depth: int = 2,
+        vector_top_k: int = 5,
+    ):
+        """
+        Build context by:
+        1. Graph traversal from node_id (if provided)
+        2. Vector search for query (if provided)
+        3. Merge, deduplicate, rank by relevance
+        4. Truncate to fit token budget
+        5. Optionally attach code content
+        """
+        context_items = []
+
+        # Step 1: Graph traversal
+        if node_id:
+            if traversal_direction == "down":
+                nodes = await self.graph.traverse_down(node_id, traversal_depth)
+            else:
+                nodes = await self.graph.traverse_up(node_id, traversal_depth)
+            context_items.extend(nodes)
+
+        # Step 2: Vector search
+        if query:
+            results = await self.vectorlink.search(
+                db="...",  # from ProjectUoW
+                query=query,
+                top_k=vector_top_k,
+            )
+            context_items.extend(results)
+
+        # Step 3-5: Deduplicate, budget-check, enrich
+        ...
+
+        return context_items
diff --git a/src/backend/app/agent/context/graph_traversal.py b/src/backend/app/agent/context/graph_traversal.py
new file mode 100644
index 00000000..c4784544
--- /dev/null
+++ b/src/backend/app/agent/context/graph_traversal.py
@@ -0,0 +1,189 @@
+from app.db.context import ProjectUoW
+from app.db.async_terminus_client import WOQLQuery as WQ
+from app.core.builder.tree_builder import TreeBuilder
+from app.core.services.code_element_service import CodeElementService
+
+
+class GraphTraversal:
+    """Walk and shape project graph data for workflow execution."""
+
+    EDGE_FIELDS = (
+        "folder_children",
+        "file_children",
+        "class_children",
+        "function_children",
+        "call_children",
+        "code_element_group",
+        "call_group",
+        "structure_group",
+    )
+    EDGE_PATTERN = "(" + "|".join(EDGE_FIELDS) + ")"
+
+    def __init__(self, uow: ProjectUoW):
+        self.uow = uow
+        self.repos = uow.get_project_repos()
+        self.code_service = CodeElementService(uow)
+
+    def _extract_children(self, doc: dict) -> list[str]:
+        children: list[str] = []
+        for edge in self.EDGE_FIELDS:
+            raw = doc.get(edge)
+            if raw is None:
+                continue
+            if isinstance(raw, (list, set, tuple)):
+                children.extend([str(item) for item in raw if item])
+            else:
+                children.append(str(raw))
+        return list(set(children))
+
+    @staticmethod
+    def _normalize_type_name(type_name: str | None) -> str:
+        if not type_name:
+            return ""
+        return type_name.replace("Schema", "")
+
+    def _normalize_doc(self, doc: dict) -> dict:
+        normalized = dict(doc)
+        normalized["id"] = normalized.get("@id")
+        normalized["type"] = normalized.get("@type")
+        normalized["children"] = self._extract_children(doc)
+        return normalized
+
+    def _dedupe_nodes(self, nodes: list[dict]) -> list[dict]:
+        unique: dict[str, dict] = {}
+        for node in nodes:
+            node_id = node.get("id") or node.get("@id")
+            if not node_id:
+                continue
+            unique[node_id] = node
+        return list(unique.values())
+
+    # TODO: Make imporve type filtering
+    async def traverse_down(
+        self,
+        node_id: str | None,
+        max_depth: int = 5,
+        node_types: list[str] | None = None,
+    ) -> list[dict]:
+        """
+        Get all descendants from node_id and include the start node.
+        Returns full node docs with normalized `id`, `type`, and `children`.
+        """
+        if not node_id:
+            all_nodes, _ = await self.repos.project_repo.get_children(
+                exclude_types=[])
+            normalized_nodes = [
+                self._normalize_doc(node.model_dump())
+                for node in all_nodes
+            ]
+            return self._dedupe_nodes(normalized_nodes)
+
+        pattern = "+" if max_depth <= 0 else f"{{1,{max_depth}}}"
+        query = (
+            WQ()
+            .eq("v:start", node_id)
+            .path("v:start", f"{self.EDGE_PATTERN}{pattern}", "v:child")
+            .read_document("v:child", "v:child_doc")
+        )
+
+        allowed_types = None
+        if node_types:
+            allowed_types = {
+                self._normalize_type_name(node_type) for node_type in node_types
+            }
+
+        nodes: list[dict] = []
+        if self.repos.client:
+            result = await self.repos.client.query(query)
+            for row in result.get("bindings", []):
+                doc = row.get("child_doc", {})
+                if allowed_types:
+                    doc_type = self._normalize_type_name(doc.get("@type"))
+                    if doc_type not in allowed_types:
+                        continue
+                nodes.append(self._normalize_doc(doc))
+
+            start_result = await self.repos.client.get_document(node_id)
+            if start_result:
+                nodes.append(self._normalize_doc(start_result))
+
+        return self._dedupe_nodes(nodes)
+
+    async def traverse_up(
+        self,
+        node_id: str,
+        max_depth: int = 5,
+    ) -> list[dict]:
+        """
+        Get all ancestors from node_id and include the start node.
+        Returns full node docs with normalized `id`, `type`, and `children`.
+        """
+        pattern = "+" if max_depth <= 0 else f"{{1,{max_depth}}}"
+        query = (
+            WQ()
+            .eq("v:start", node_id)
+            .path("v:start", f"<{self.EDGE_PATTERN}{pattern}", "v:parent")
+            .read_document("v:parent", "v:parent_doc")
+        )
+
+        nodes: list[dict] = []
+        if self.repos.client:
+            result = await self.repos.client.query(query)
+            for row in result.get("bindings", []):
+                doc = row.get("parent_doc", {})
+                nodes.append(self._normalize_doc(doc))
+
+            start_result = await self.repos.client.get_document(node_id)
+            if start_result:
+                nodes.append(self._normalize_doc(start_result))
+
+        return self._dedupe_nodes(nodes)
+
+    async def build_tree(self, node_id: str | None, node_types: list[str] | None = None, max_depth: int = 5):
+        """Build nested tree nodes for subtree rooted at `node_id`."""
+        nodes = await self.traverse_down(node_id=node_id, node_types=node_types, max_depth=max_depth)
+        tree = TreeBuilder(base_nodes=nodes).build()
+        return tree
+
+    async def get_siblings(self, node_id: str) -> list[dict]:
+        """Get nodes at the same level (same parent)."""
+        parents = await self.traverse_up(node_id, max_depth=1)
+        if not parents:
+            return []
+
+        parent_id = parents[0]["id"] if parents[0]["id"] != node_id else (
+            parents[1]["id"] if len(parents) > 1 else None
+        )
+        if not parent_id:
+            return []
+
+        children = await self.traverse_down(parent_id, max_depth=1)
+        return [c for c in children if c["id"] not in {node_id, parent_id}]
+
+    async def get_node_with_code(self, node_id: str) -> dict:
+        """Fetch node and hydrate code via CodeElementService.get_code."""
+        if not self.repos.client:
+            return {}
+
+        doc = await self.repos.client.get_document(node_id)
+        if not doc:
+            return {}
+
+        try:
+            code_payload = await self.code_service.get_code(node_id)
+            if code_payload and code_payload.get("code"):
+                doc["code_content_data"] = code_payload["code"]
+        except Exception:
+            # Keep workflow robust for nodes that don't have code ranges.
+            doc["code_content_data"] = ""
+        return doc
+
+    async def get_code_content(self, node_id: str) -> str:
+        """Fetch only code content for a node without hydrating full doc."""
+        try:
+            code_payload = await self.code_service.get_code(node_id)
+            if code_payload and code_payload.get("code"):
+                return code_payload["code"]
+        except Exception:
+            return ""
+        return ""
diff --git a/src/backend/app/agent/context/token_tracker.py b/src/backend/app/agent/context/token_tracker.py
new file mode 100644
index 00000000..4a8fb7ec
--- /dev/null
+++ b/src/backend/app/agent/context/token_tracker.py
@@ -0,0 +1,38 @@
+from langchain_core.callbacks import BaseCallbackHandler
+from pydantic import BaseModel
+from typing import Optional
+
+
+class TokenUsage(BaseModel):
+    """Accumulated token usage for a single run."""
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    model: Optional[str] = None
+
+
+class TokenTracker(BaseCallbackHandler):
+    """LangChain callback handler that accumulates token usage across calls."""
+
+    def __init__(self, max_total_tokens: int = 128_000):
+        self.max_total_tokens = max_total_tokens
+        self.usage = TokenUsage()
+
+    def on_llm_end(self, response, **kwargs):
+        """Called after each LLM invocation — accumulates usage."""
+        if hasattr(response, "llm_output") and response.llm_output:
+            usage = response.llm_output.get("token_usage", {})
+            self.usage.prompt_tokens += usage.get("prompt_tokens", 0)
+            self.usage.completion_tokens += usage.get("completion_tokens", 0)
+            self.usage.total_tokens += usage.get("total_tokens", 0)
+
+    @property
+    def remaining(self) -> int:
+        return self.max_total_tokens - self.usage.total_tokens
+
+    @property
+    def over_budget(self) -> bool:
+        return self.usage.total_tokens >= self.max_total_tokens
+
+    def get_usage(self) -> TokenUsage:
+        return self.usage.model_copy()
diff --git a/src/backend/app/agent/context/vectorlink_client.py b/src/backend/app/agent/context/vectorlink_client.py
new file mode 100644
index 00000000..1275728c
--- /dev/null
+++ b/src/backend/app/agent/context/vectorlink_client.py
@@ -0,0 +1,60 @@
+import json
+import httpx
+from typing import Optional
+
+
+class VectorLinkClient:
+    """Async HTTP client for the VectorLink semantic indexer."""
+
+    def __init__(self, base_url: str = "http://localhost:8080"):
+        self.base_url = base_url
+        self.headers = {
+            "Content-Type": "application/json",
+            "VECTORLINK_EMBEDDING_API_KEY": 'openai secreate',
+        }
+        self._client = httpx.AsyncClient(
+            base_url=base_url, headers=self.headers, timeout=30.0)
+
+    async def index_document(
+        self,
+        db: str,
+        commit_id: str,
+        branch: str = "main",
+    ) -> str:
+        """Trigger vectorlink to start indexing and return the task id."""
+
+        try:
+            response = await self._client.get(
+                f"/api/index",
+                params={"domain": f"admin/{db}",
+                        "commit": commit_id},
+            )
+            task_id = response.text
+            return task_id
+        except httpx.HTTPStatusError as e:
+            raise RuntimeError(f"Failed to index document: {e}") from e
+
+    async def search(
+        self,
+        db: str,
+        commit_id: str,
+        query: str,
+        branch: str = "main",
+    ) -> list[dict]:
+        """Search the vectorlink index and return the results."""
+
+        try:
+            response = await self._client.post(
+                f"/api/search",
+                params={"domain": f"admin/{db}",
+                        "commit": commit_id},
+                json={"search": query},
+            )
+            if response.status_code != 200:
+                raise RuntimeError(f"Failed to search: {response.text}")
+
+            return json.loads(response.text)
+        except httpx.HTTPStatusError as e:
+            raise RuntimeError(f"Failed to search: {e}") from e
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f"Failed to parse search response: {e}") from e
diff --git a/src/backend/app/agent/conversation_store.py b/src/backend/app/agent/conversation_store.py
new file mode 100644
index 00000000..0767eadb
--- /dev/null
+++ b/src/backend/app/agent/conversation_store.py
@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from app.core.model.conversation_domain import (
+    Conversation,
+    ConversationMessage,
+    ConversationSummary,
+    TaskPart,
+)
+from app.core.repository.conversation import (
+    ConversationRepo,
+    terminus_ids_match,
+)
+
+
+class ConversationStore(Protocol):
+    async def create_conversation(
+        self,
+        title: str,
+        description: str = "",
+        metadata: dict | None = None,
+    ) -> str:
+        ...
+
+    async def add_message(
+        self,
+        conversation_id: str,
+        message: ConversationMessage,
+    ) -> str | None:
+        ...
+
+    async def get_conversation(
+        self, conversation_id: str
+    ) -> Conversation | None:
+        ...
+
+    async def get_conversation_metadata(
+        self, conversation_id: str
+    ) -> ConversationSummary | None:
+        ...
+
+    async def list_conversations(
+        self, limit: int = 50, cursor: str | None = None
+    ) -> list[ConversationSummary]:
+        ...
+
+    async def list_messages(
+        self,
+        conversation_id: str,
+        cursor: int = 0,
+        limit: int = 50,
+    ) -> list[ConversationMessage]:
+        ...
+
+    async def upsert_task_part(
+        self,
+        conversation_id: str,
+        task_part: TaskPart,
+    ) -> None:
+        ...
+
+
+class TerminusConversationStore:
+    """Conversation persistence backed by TerminusDB via `ConversationRepo`."""
+
+    def __init__(self, repo: ConversationRepo):
+        self._repo = repo
+
+    async def create_conversation(
+        self,
+        title: str,
+        description: str = "",
+        metadata: dict | None = None,
+    ) -> str:
+        cid = await self._repo.create_conversation(
+            title, description, metadata
+        )
+        if cid is None:
+            raise RuntimeError(
+                "Failed to create conversation in TerminusDB"
+            )
+        return cid
+
+    async def add_message(
+        self,
+        conversation_id: str,
+        message: ConversationMessage,
+    ) -> str | None:
+        mid = await self._repo.add_message(conversation_id, message)
+        if mid is None:
+            raise ValueError(
+                f"Failed to add message to conversation {conversation_id!r}"
+            )
+        return mid
+
+    async def get_conversation(
+        self, conversation_id: str
+    ) -> Conversation | None:
+        return await self._repo.get_conversation(conversation_id)
+
+    async def get_conversation_metadata(
+        self, conversation_id: str
+    ) -> ConversationSummary | None:
+        return await self._repo.get_conversation_summary(conversation_id)
+
+    async def list_conversations(
+        self, limit: int = 50, cursor: str | None = None
+    ) -> list[ConversationSummary]:
+        return await self._repo.list_conversations(limit=limit, cursor=cursor)
+
+    async def list_messages(
+        self,
+        conversation_id: str,
+        cursor: int = 0,
+        limit: int = 50,
+    ) -> list[ConversationMessage]:
+        return await self._repo.get_messages(
+            conversation_id, cursor=cursor, limit=limit
+        )
+
+    async def upsert_task_part(
+        self,
+        conversation_id: str,
+        task_part: TaskPart,
+    ) -> None:
+        conv = await self._repo.get_conversation(conversation_id)
+        if conv is None:
+            raise ValueError(f"Conversation not found: {conversation_id}")
+
+        for message in reversed(conv.messages):
+            for idx, part in enumerate(message.parts):
+                if isinstance(part, TaskPart) and terminus_ids_match(
+                    part.task_id, task_part.task_id
+                ):
+                    new_parts = list(message.parts)
+                    new_parts[idx] = task_part
+                    updated = message.model_copy(update={"parts": new_parts})
+                    ok = await self._repo.update_message(
+                        conversation_id, updated
+                    )
+                    if not ok:
+                        raise ValueError(
+                            f"Failed to update message {message.id} "
+                            f"for task part"
+                        )
+                    return
+
+        raise ValueError(
+            f"TaskPart not found for task_id={task_part.task_id} "
+            f"in conversation={conversation_id}"
+        )
diff --git a/src/backend/app/agent/graph/__init__.py b/src/backend/app/agent/graph/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/backend/app/agent/graph/builder.py b/src/backend/app/agent/graph/builder.py
new file mode 100644
index 00000000..72730d8e
--- /dev/null
+++ b/src/backend/app/agent/graph/builder.py
@@ -0,0 +1,30 @@
+
+from langgraph.graph import StateGraph, END
+from .state import AgentState
+from .nodes import planner, executor, reflector, responder
+from .edges import after_planner, after_reflector
+
+
+def build_agent_graph() -> StateGraph:
+    graph = StateGraph(AgentState)
+
+    graph.add_node("planner", planner)
+    graph.add_node("executor", executor)
+    graph.add_node("reflector", reflector)
+    graph.add_node("responder", responder)
+
+    graph.set_entry_point("planner")
+
+    graph.add_conditional_edges("planner", after_planner, {
+        "executor": "executor",
+        "responder": "responder",
+        "end": END,
+    })
+    graph.add_edge("executor", "reflector")
+    graph.add_conditional_edges("reflector", after_reflector, {
+        "responder": "responder",
+        "planner": "planner",
+    })
+    graph.add_edge("responder", END)
+
+    return graph.compile()
diff --git a/src/backend/app/agent/graph/edges.py b/src/backend/app/agent/graph/edges.py
new file mode 100644
index 00000000..d4b5d7cd
--- /dev/null
+++ b/src/backend/app/agent/graph/edges.py
@@ -0,0 +1,15 @@
+from app.agent.graph.state import AgentState
+
+
+def after_planner(state: AgentState) -> str:
+    if state["should_finish"]:
+        return "end"
+    if state["selected_tool"]:
+        return "executor"
+    return "responder"
+
+
+def after_reflector(state: AgentState) -> str:
+    if state["should_finish"] or state["iteration_count"] >= state["max_iterations"]:
+        return "responder"
+    return "planner"
diff --git a/src/backend/app/agent/graph/nodes.py b/src/backend/app/agent/graph/nodes.py
new file mode 100644
index 00000000..f7642f2b
--- /dev/null
+++ b/src/backend/app/agent/graph/nodes.py
@@ -0,0 +1,37 @@
+from app.agent.graph.state import AgentState
+from app.agent.llm import factory
+
+
+async def planner(state: AgentState) -> AgentState:
+    """
+    Given messages + context, produce a plan.
+    Decides: use a tool, answer directly, or give up.
+    Populates: plan, selected_tool, tool_input.
+    """
+    llm = factory.create()
+    response = await llm.invoke(state["messages"])
+
+
+async def executor(state: AgentState) -> AgentState:
+    """
+    Look up selected_tool in ToolRegistry, call execute().
+    Populates: tool_results (appends).
+    """
+    ...
+
+
+async def reflector(state: AgentState) -> AgentState:
+    """
+    Review tool results. Decide if we have enough context to answer,
+    or if we need another tool call.
+    Populates: should_finish, context_docs.
+    """
+    ...
+
+
+async def responder(state: AgentState) -> AgentState:
+    """
+    Generate the final response from accumulated context.
+    Appends an assistant message to messages.
+    """
+    ...
diff --git a/src/backend/app/agent/graph/state.py b/src/backend/app/agent/graph/state.py
new file mode 100644
index 00000000..a25212e6
--- /dev/null
+++ b/src/backend/app/agent/graph/state.py
@@ -0,0 +1,40 @@
+from typing import TypedDict, Annotated, Sequence, Optional
+from langchain_core.messages import BaseMessage
+from langgraph.graph.message import add_messages
+
+
+class ToolResult(TypedDict):
+    tool_name: str
+    tool_input: dict
+    output: str  # serialized result
+    error: Optional[str]
+
+
+class AgentState(TypedDict):
+    """Shared state flowing through the LangGraph."""
+    messages: Annotated[Sequence[BaseMessage], add_messages]
+
+    # Planning
+    plan: Optional[str]                  # high-level plan text
+    current_step: int                    # index in plan steps
+
+    # Tool execution
+    selected_tool: Optional[str]
+    tool_input: Optional[dict]
+    tool_results: list[ToolResult]
+
+    # Context
+    # retrieved graph nodes / vector results
+    context_docs: list[dict]
+    token_budget_remaining: int
+
+    # Control
+    iteration_count: int
+    max_iterations: int
+    should_finish: bool
+
+    # Workflow-specific (used by subgraphs)
+    target_node_id: Optional[str]        # node being documented
+    traversal_direction: Optional[str]   # "up" | "down"
+    # "description" | "documentation" | "both"
+    generation_mode: Optional[str]
diff --git a/src/backend/app/agent/llm/factory.py b/src/backend/app/agent/llm/factory.py
new file mode 100644
index 00000000..12a5622e
--- /dev/null
+++ b/src/backend/app/agent/llm/factory.py
@@ -0,0 +1,42 @@
+from app.agent.llm.provider import LLMProvider
+from app.agent.config import AgentConfig
+
+
+class LLMFactory:
+    """Create LLM provider instances based on configuration."""
+
+    def __init__(self, config: AgentConfig):
+        self.config = config
+        self._providers: dict[str, type[LLMProvider]] = {}
+        self._provider_defaults: dict[str, dict] = {}
+
+    def register_provider(
+        self,
+        name: str,
+        provider_cls: type[LLMProvider],
+        **defaults,
+    ):
+        self._providers[name] = provider_cls
+        if defaults:
+            self._provider_defaults[name] = defaults
+
+    def create(
+        self,
+        *,
+        provider: str | None = None,
+        model: str | None = None,
+        **kwargs,
+    ) -> LLMProvider:
+        provider = provider or self.config.default_provider  # e.g. "openai"
+        model = model or self.config.default_model            # e.g. "gpt-4o"
+        provider_cls = self._providers[provider]
+        merged = {**self._provider_defaults.get(provider, {}), **kwargs}
+
+        return provider_cls(model=model, **merged)
+
+    def list_available(self) -> list[dict]:
+        """List registered providers and their supported models."""
+        return [
+            {"provider": name, "models": cls.supported_models()}
+            for name, cls in self._providers.items()
+        ]
diff --git a/src/backend/app/agent/llm/gateway.py b/src/backend/app/agent/llm/gateway.py
new file mode 100644
index 00000000..dee59c2b
--- /dev/null
+++ b/src/backend/app/agent/llm/gateway.py
@@ -0,0 +1,47 @@
+# agent/llm/gateway.py
+
+from dataclasses import dataclass
+from app.agent.chat.completion_params import ChatCompletionParams
+from app.agent.config import settings
+
+
+@dataclass
+class ResolvedLLM:
+    provider: object  # the LangChain-compatible provider
+    model: str
+    provider_name: str
+
+
+class LLMGateway:
+    """Single responsibility: resolve params → usable LLM instance."""
+
+    def __init__(self, llm_factory):
+        self._factory = llm_factory
+
+    @property
+    def factory(self):
+        """Underlying LLMFactory (for workflow construction)."""
+        return self._factory
+
+    def resolve(
+        self, params: ChatCompletionParams | None = None
+    ) -> ResolvedLLM:
+        params = params or ChatCompletionParams()
+        model = params.model or settings.default_model
+        provider_name = params.provider or settings.default_provider
+        extra = params.provider_create_kwargs()
+
+        mt = extra.get("max_tokens")
+        if mt is not None and mt > settings.max_total_tokens:
+            extra["max_tokens"] = settings.max_total_tokens
+
+        llm = self._factory.create(
+            provider=provider_name, model=model, **extra
+        )
+        return ResolvedLLM(
+            provider=llm, model=model, provider_name=provider_name
+        )
+
+    def create_mini(self) -> object:
+        """Cheap model for metadata generation."""
+        return self._factory.create(model="gpt-4o-mini")
diff --git a/src/backend/app/agent/llm/provider.py b/src/backend/app/agent/llm/provider.py
new file mode 100644
index 00000000..df082e4e
--- /dev/null
+++ b/src/backend/app/agent/llm/provider.py
@@ -0,0 +1,38 @@
+from abc import ABC, abstractmethod
+from typing import Any, AsyncIterator
+from langchain_core.messages import BaseMessage
+
+
+class LLMProvider(ABC):
+    """Abstract interface for an LLM provider."""
+
+    name: str       # e.g. "openai", "anthropic", "local"
+    model: str      # e.g. "gpt-4o", "claude-3-sonnet"
+
+    @abstractmethod
+    async def invoke(
+        self,
+        messages: list[BaseMessage],
+        **kwargs,
+    ) -> BaseMessage:
+        """Single-shot invocation. Returns one complete message."""
+        ...
+
+    @abstractmethod
+    async def stream(
+        self,
+        messages: list[BaseMessage],
+        **kwargs,
+    ) -> AsyncIterator[str]:
+        """Streaming invocation. Yields token chunks."""
+        ...
+
+    @abstractmethod
+    def supports_tools(self) -> bool:
+        """Does this provider support native tool/function calling?"""
+        ...
+
+    @abstractmethod
+    def max_context_tokens(self) -> int:
+        """Maximum context window size for this model."""
+        ...
diff --git a/src/backend/app/agent/llm/providers/openai_provider.py b/src/backend/app/agent/llm/providers/openai_provider.py
new file mode 100644
index 00000000..da251f99
--- /dev/null
+++ b/src/backend/app/agent/llm/providers/openai_provider.py
@@ -0,0 +1,45 @@
+from langchain_openai import ChatOpenAI
+from app.agent.llm.provider import LLMProvider
+from typing import AsyncIterator
+from langchain_core.messages import BaseMessage
+
+
+class OpenAIProvider(LLMProvider):
+    name = "openai"
+
+    MODEL_CONTEXTS = {
+        "gpt-4o": 128_000,
+        "gpt-4o-mini": 128_000,
+        "gpt-4-turbo": 128_000,
+        "gpt-3.5-turbo": 16_385,
+    }
+
+    def __init__(self, model: str = "gpt-4o-mini", **kwargs):
+        self.model = model
+        self._llm = ChatOpenAI(model=model, **kwargs)
+
+    async def invoke(
+        self,
+        messages: list[BaseMessage],
+        **kwargs,
+    ) -> BaseMessage:
+        return await self._llm.ainvoke(messages, **kwargs)
+
+    async def stream(
+        self,
+        messages: list[BaseMessage],
+        **kwargs,
+    ):
+        async for chunk in self._llm.astream(messages, **kwargs):
+            if chunk.content:
+                yield chunk.content
+
+    def supports_tools(self) -> bool:
+        return True
+
+    def max_context_tokens(self) -> int:
+        return self.MODEL_CONTEXTS.get(self.model, 128_000)
+
+    @classmethod
+    def supported_models(cls) -> list[str]:
+        return list(cls.MODEL_CONTEXTS.keys())
diff --git a/src/backend/app/agent/runner/__init__.py b/src/backend/app/agent/runner/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/backend/app/agent/runner/patch_builder.py b/src/backend/app/agent/runner/patch_builder.py
new file mode 100644
index 00000000..e2116cb2
--- /dev/null
+++ b/src/backend/app/agent/runner/patch_builder.py
@@ -0,0 +1,59 @@
+"""RFC 6902 JSON Patch fragments for client conversation state."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ConversationPatchBuilder:
+    """Builds JSON Patch arrays for conversation state mutations."""
+
+    def __init__(self) -> None:
+        self._patches: list[dict[str, Any]] = []
+
+    def add(self, path: str, value: Any) -> ConversationPatchBuilder:
+        self._patches.append({"op": "add", "path": path, "value": value})
+        return self
+
+    def replace(self, path: str, value: Any) -> ConversationPatchBuilder:
+        self._patches.append({"op": "replace", "path": path, "value": value})
+        return self
+
+    def remove(self, path: str) -> ConversationPatchBuilder:
+        self._patches.append({"op": "remove", "path": path})
+        return self
+
+    def build(self) -> list[dict[str, Any]]:
+        return list(self._patches)
+
+    def task_progress(
+        self, task_id: str, progress: float, message: str = ""
+    ) -> ConversationPatchBuilder:
+        self.replace(f"/tasks/{task_id}/progress", progress)
+        if message:
+            self.replace(f"/tasks/{task_id}/progress_message", message)
+        return self
+
+    def add_message_wire(self, message: dict) -> ConversationPatchBuilder:
+        self.add("/messages/-", message)
+        return self
+
+    def finalize_assistant_text_part(
+        self,
+        message_index: int,
+        text: str,
+        *,
+        message_id: str | None = None,
+        sequence: int | None = None,
+    ) -> ConversationPatchBuilder:
+        base = f"/messages/{message_index}"
+        self.replace(f"{base}/parts/0/text", text)
+        if message_id is not None:
+            self.replace(f"{base}/id", message_id)
+        if sequence is not None:
+            self.replace(f"{base}/sequence", sequence)
+        return self
+
+    def message_count(self, n: int) -> ConversationPatchBuilder:
+        self.replace("/message_count", n)
+        return self
diff --git a/src/backend/app/agent/runner/stream_buffer.py b/src/backend/app/agent/runner/stream_buffer.py
new file mode 100644
index 00000000..18218028
--- /dev/null
+++ b/src/backend/app/agent/runner/stream_buffer.py
@@ -0,0 +1,84 @@
+"""In-memory LLM stream chunks with replay for WebSocket resume."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class StreamBuffer:
+    """Accumulates LLM token chunks with sequence numbers."""
+
+    def __init__(self, stream_id: str, conversation_id: str):
+        self.stream_id = stream_id
+        self.conversation_id = conversation_id
+        self._chunks: list[str] = []
+        self._finished = False
+        self._final_text: str | None = None
+        self._message_id: str | None = None
+
+    @property
+    def next_seq(self) -> int:
+        return len(self._chunks)
+
+    def append(self, delta: str) -> int:
+        seq = self.next_seq
+        self._chunks.append(delta)
+        return seq
+
+    def get_chunks_since(self, from_seq: int) -> list[tuple[int, str]]:
+        start = max(0, int(from_seq))
+        return [(i, self._chunks[i]) for i in range(start, len(self._chunks))]
+
+    def finish(self) -> str:
+        self._finished = True
+        self._final_text = "".join(self._chunks)
+        return self._final_text
+
+    def set_message_id(self, message_id: str) -> None:
+        self._message_id = message_id
+
+    @property
+    def message_id(self) -> str | None:
+        return self._message_id
+
+    @property
+    def is_finished(self) -> bool:
+        return self._finished
+
+
+class StreamRegistry:
+    """Tracks active streams; keeps finished buffers briefly for replay."""
+
+    def __init__(self, replay_ttl_s: float = 60.0):
+        self._active: dict[str, StreamBuffer] = {}
+        self.replay_ttl_s = replay_ttl_s
+
+    def create(self, stream_id: str, conversation_id: str) -> StreamBuffer:
+        buf = StreamBuffer(stream_id, conversation_id)
+        self._active[stream_id] = buf
+        return buf
+
+    def get(self, stream_id: str) -> StreamBuffer | None:
+        return self._active.get(stream_id)
+
+    def remove(self, stream_id: str) -> None:
+        self._active.pop(stream_id, None)
+
+    def schedule_remove(self, stream_id: str) -> None:
+        ttl = self.replay_ttl_s
+
+        async def _delayed() -> None:
+            try:
+                await asyncio.sleep(ttl)
+            except asyncio.CancelledError:
+                return
+            self.remove(stream_id)
+
+        try:
+            asyncio.create_task(_delayed())
+        except RuntimeError:
+            logger.warning("Could not schedule stream buffer cleanup (no loop)")
+
diff --git a/src/backend/app/agent/runner/task_context.py b/src/backend/app/agent/runner/task_context.py
new file mode 100644
index 00000000..ffa02d3f
--- /dev/null
+++ b/src/backend/app/agent/runner/task_context.py
@@ -0,0 +1,131 @@
+# app/agent/runner/task_context.py
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from app.core.model.conversation_enums import SubTaskState, TaskState
+from app.core.model.conversation_nodes import SubTask, Task
+
+
+class SubtaskHandle:
+    """Lightweight handle a workflow uses to report on one subtask."""
+
+    def __init__(self, subtask: SubTask, parent: TaskContext):
+        self._sub = subtask
+        self._parent = parent
+
+    @property
+    def id(self) -> str:
+        return self._sub.id
+
+    def start(self, message: str = "") -> None:
+        self._sub.state = SubTaskState.RUNNING
+        self._sub.started_at = datetime.now(timezone.utc)
+        if message:
+            self._sub.description = message
+        self._parent._recompute_progress()
+
+    def update(self, message: str = "") -> None:
+        if message:
+            self._sub.description = message
+
+    def complete(self, message: str = "") -> None:
+        self._sub.state = SubTaskState.COMPLETED
+        self._sub.finished_at = datetime.now(timezone.utc)
+        if message:
+            self._sub.description = message
+        self._parent._recompute_progress()
+
+    def fail(self, error: str) -> None:
+        self._sub.state = SubTaskState.FAILED
+        self._sub.error = error
+        self._sub.finished_at = datetime.now(timezone.utc)
+        self._parent._recompute_progress()
+
+
+class TaskContext:
+    """
+    The ONLY interface workflows use to report progress.
+
+    Tracks subtasks in memory. The WorkflowService reads
+    snapshots for frontend pushes and final DB flush.
+    """
+
+    def __init__(self, task: Task | None = None):
+        self._task: Task | None = task
+        self._subtasks: list[SubTask] = []
+        self._seq = 0
+
+    def bind(self, task: Task) -> None:
+        """Bind to the in-memory Task created by TaskManager."""
+        self._task = task
+
+    # -- progress ---------------------------------------------------------
+
+    def update_progress(
+        self, progress: float, message: str = ""
+    ) -> None:
+        if self._task:
+            self._task.progress = max(0.0, min(1.0, progress))
+            if message:
+                self._task.progress_message = message
+
+    def _recompute_progress(self) -> None:
+        if not self._task or not self._subtasks:
+            return
+        done = sum(
+            1
+            for s in self._subtasks
+            if s.state
+            in {SubTaskState.COMPLETED, SubTaskState.FAILED}
+        )
+        self._task.progress = done / len(self._subtasks)
+        self._task.sub_task_count = len(self._subtasks)
+
+    # -- subtask management -----------------------------------------------
+
+    def subtask(
+        self,
+        name: str,
+        subtask_id: str | None = None,
+        touched_node_ids: list[str] | None = None,
+    ) -> SubtaskHandle:
+        import json
+
+        sid = subtask_id or str(uuid.uuid4())
+        now = datetime.now(timezone.utc)
+        st = SubTask(
+            id=sid,
+            task_id=self._task.id if self._task else "",
+            name=name,
+            state=SubTaskState.PENDING,
+            sequence=self._seq,
+            touched_node_ids_json=json.dumps(
+                touched_node_ids or []
+            ),
+            created_at=now,
+            updated_at=now,
+        )
+        self._seq += 1
+        self._subtasks.append(st)
+        self._recompute_progress()
+        return SubtaskHandle(st, self)
+
+    # -- snapshots for external consumers ---------------------------------
+
+    @property
+    def subtask_snapshots(self) -> list[SubTask]:
+        return [s.model_copy(deep=True) for s in self._subtasks]
+
+    @property
+    def subtask_count(self) -> int:
+        return len(self._subtasks)
+
+    # -- noop for tests / optional ----------------------------------------
+
+    @classmethod
+    def noop(cls) -> TaskContext:
+        return cls(task=None)
diff --git a/src/backend/app/agent/runner/task_manager.py b/src/backend/app/agent/runner/task_manager.py
new file mode 100644
index 00000000..1146ea69
--- /dev/null
+++ b/src/backend/app/agent/runner/task_manager.py
@@ -0,0 +1,125 @@
+# app/agent/runner/task_manager.py
+
+import asyncio
+import inspect
+import json
+import uuid
+import logging
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional, Union
+
+from app.core.model.conversation_enums import TaskState
+from app.core.model.conversation_nodes import Task
+
+logger = logging.getLogger(__name__)
+
+_STATUS_INTERVAL_S = 0.5
+
+
+class TaskManager:
+
+    def __init__(self):
+        self._tasks: dict[str, Task] = {}
+        self._asyncio_tasks: dict[str, asyncio.Task] = {}
+
+    def submit(
+        self,
+        name: str,
+        coro_factory: Callable[..., Any],
+        on_status_update: Optional[
+            Callable[[Task], Union[None, Any]]
+        ] = None,
+        *,
+        task_id: Optional[str] = None,
+        **kwargs,
+    ) -> str:
+        tid = task_id if task_id is not None else str(uuid.uuid4())
+        if tid in self._tasks:
+            raise ValueError(f"task_id already in use: {tid!r}")
+        task_id = tid
+        now = datetime.now(timezone.utc)
+        status = Task(
+            id=task_id,
+            name=name,
+            state=TaskState.PENDING,
+            created_at=now,
+            updated_at=now,
+        )
+        self._tasks[task_id] = status
+
+        async def _emit():
+            if not on_status_update:
+                return
+            try:
+                out = on_status_update(status.model_copy(deep=True))
+                if inspect.isawaitable(out):
+                    await out
+            except Exception:
+                logger.debug(
+                    "status callback error", exc_info=True
+                )
+
+        async def _wrapper():
+            status.state = TaskState.RUNNING
+            status.started_at = datetime.now(timezone.utc)
+            await _emit()
+
+            reporter: asyncio.Task | None = None
+            if on_status_update:
+
+                async def _reporter():
+                    while status.state == TaskState.RUNNING:
+                        await _emit()
+                        await asyncio.sleep(_STATUS_INTERVAL_S)
+
+                reporter = asyncio.create_task(_reporter())
+
+            try:
+                run_kwargs = dict(kwargs)
+                # TaskManager injects task_status; task_context
+                # is passed through from the caller's kwargs.
+                run_kwargs.setdefault("task_status", status)
+                result = await coro_factory(**run_kwargs)
+                status.state = TaskState.COMPLETED
+                status.result_json = (
+                    json.dumps(result, default=str)
+                    if result is not None
+                    else None
+                )
+            except asyncio.CancelledError:
+                status.state = TaskState.CANCELLED
+            except Exception as e:
+                status.state = TaskState.FAILED
+                status.error = str(e)
+                logger.exception("Task %s failed", task_id)
+            finally:
+                status.finished_at = datetime.now(timezone.utc)
+                if reporter:
+                    reporter.cancel()
+                    try:
+                        await reporter
+                    except asyncio.CancelledError:
+                        pass
+                await _emit()
+
+        atask = asyncio.get_running_loop().create_task(_wrapper())
+        self._asyncio_tasks[task_id] = atask
+        return task_id
+
+    def get_status(self, task_id: str) -> Optional[Task]:
+        return self._tasks.get(task_id)
+
+    async def join(self, task_id: str) -> None:
+        atask = self._asyncio_tasks.get(task_id)
+        if atask:
+            await atask
+
+    def cancel(self, task_id: str) -> bool:
+        atask = self._asyncio_tasks.get(task_id)
+        if atask and not atask.done():
+            atask.cancel()
+            return True
+        return False
+
+    def list_tasks(self) -> list[Task]:
+        return list(self._tasks.values())
diff --git a/src/backend/app/agent/runner/task_persistence.py b/src/backend/app/agent/runner/task_persistence.py
new file mode 100644
index 00000000..795b915b
--- /dev/null
+++ b/src/backend/app/agent/runner/task_persistence.py
@@ -0,0 +1,140 @@
+# app/agent/runner/task_persistence.py
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from app.core.model.conversation_enums import TaskState
+from app.core.model.conversation_nodes import SubTask, Task
+from app.db.async_terminus_client import WOQLQuery as WQ
+
+try:
+    from terminusdb_client.woqlquery.woql_query import Doc
+except ImportError:  # pragma: no cover
+    Doc = dict  # type: ignore
+
+from app.core.model.schemas.conversation_schema import (
+    SubTaskSchema,
+    TaskSchema,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TaskPersistence:
+    """
+    Encapsulates all DB operations for Task and SubTask documents.
+
+    Workflows never touch the DB directly for task tracking.
+    """
+
+    def __init__(self, client: Any):
+        self._client = client
+
+    # -- Task CRUD --------------------------------------------------------
+
+    async def create_task(self, task: Task) -> str:
+        schema = TaskSchema.from_pydantic(task)
+
+        await self._client.insert_document(
+            schema,
+            commit_msg=f"Create task {task.id}",
+        )
+
+        return task.id
+
+    async def update_task_state(
+        self,
+        task_id: str,
+        *,
+        state: TaskState,
+        progress: float = 0.0,
+        progress_message: str = "",
+        error: str | None = None,
+        result_json: str | None = None,
+        started_at: datetime | None = None,
+        finished_at: datetime | None = None,
+        sub_task_count: int = 0,
+    ) -> None:
+        now = datetime.now(timezone.utc)
+        updates: list = []
+
+        field_map = {
+            "state": state.value,
+            "progress": progress,
+            "progress_message": progress_message,
+            "sub_task_count": sub_task_count,
+            "updated_at": now,
+        }
+        if error is not None:
+            field_map["error"] = error
+        if result_json is not None:
+            field_map["result_json"] = result_json
+        if started_at is not None:
+            field_map["started_at"] = started_at
+        if finished_at is not None:
+            field_map["finished_at"] = finished_at
+
+        for field, value in field_map.items():
+            var = f"v:old_{field}"
+            updates.extend(
+                [
+                    WQ().opt(
+                        WQ()
+                        .triple(task_id, field, var)
+                        .delete_triple(task_id, field, var)
+                    ),
+                    WQ().add_triple(
+                        task_id,
+                        field,
+                        self._woql_value(value),
+                    ),
+                ]
+            )
+
+        if updates:
+            await self._client.query(
+                WQ().woql_and(*updates),
+                commit_msg=f"Update task {task_id} → {state.value}",
+            )
+
+    # -- SubTask batch upsert ---------------------------------------------
+
+    async def flush_subtasks(
+        self, task_id: str, subtasks: list[SubTask]
+    ) -> None:
+        if not subtasks:
+            return
+
+        documents = []
+        for st in subtasks:
+            schema = SubTaskSchema.from_pydantic(
+                st.model_copy(update={"task_id": task_id})
+            )
+            raw = schema._obj_to_dict()[0]
+            documents.append(raw)
+
+        await self._client.insert_document(
+            documents,
+            commit_msg=(
+                f"Flush {len(subtasks)} subtasks for task {task_id}"
+            ),
+        )
+    # -- helpers -----------------------------------------------------------
+
+    @staticmethod
+    def _woql_value(value: Any):
+        if isinstance(value, str):
+            return WQ().string(value)
+        if isinstance(value, bool):
+            return WQ().boolean(value)
+        if isinstance(value, int):
+            return WQ().iri(str(value))  # or integer helper
+        if isinstance(value, float):
+            return WQ().string(str(value))
+        if isinstance(value, datetime):
+            return value
+        return WQ().string(str(value))
diff --git a/src/backend/app/agent/service/chat_service.py b/src/backend/app/agent/service/chat_service.py
new file mode 100644
index 00000000..23b9da44
--- /dev/null
+++ b/src/backend/app/agent/service/chat_service.py
@@ -0,0 +1,189 @@
+import uuid
+import asyncio
+import logging
+
+from langchain_core.messages import AIMessage, HumanMessage
+
+from app.agent.conversation_store import ConversationStore
+from app.agent.llm.gateway import LLMGateway
+from app.agent.streaming.manager import StreamManager, StreamHandle
+from app.agent.streaming import (
+    conversation_message_to_wire,
+    emit_conversation_patch,
+)
+from app.agent.runner.patch_builder import ConversationPatchBuilder
+from app.agent.runner.task_manager import TaskManager
+from app.agent.chat.completion_params import ChatCompletionParams
+from app.core.model.conversation_domain import (
+    ConversationMessage,
+    TextPart,
+)
+from app.core.model.conversation_enums import MessageRole
+
+logger = logging.getLogger(__name__)
+
+
+class ChatService:
+    def __init__(
+        self,
+        task_manager: TaskManager,
+        llm_gateway: LLMGateway,
+        stream_manager: StreamManager,
+    ):
+        self._tasks = task_manager
+        self._llm = llm_gateway
+        self._streams = stream_manager
+
+    async def send_message(
+        self,
+        conversation_id: str,
+        user_message: ConversationMessage,
+        *,
+        store: ConversationStore,
+        completion_params: ChatCompletionParams | None = None,
+        client_ref: str | None = None,
+    ) -> dict:
+        # 1. Persist user message
+        user_mid = await store.add_message(
+            conversation_id, user_message
+        )
+        meta = await store.get_conversation_metadata(conversation_id)
+        if meta is None:
+            raise ValueError(f"Conversation not found: {conversation_id}")
+
+        # 2. Broadcast user message patch
+        await self._emit_user_patch(
+            conversation_id, user_message, user_mid, meta
+        )
+
+        # 3. Open stream + submit background generation
+        handle = self._streams.open(conversation_id)
+        task_id = self._tasks.submit(
+            name="chat:response",
+            coro_factory=self._generate,
+            store=store,
+            conversation_id=conversation_id,
+            handle=handle,
+            completion_params=completion_params,
+            client_ref=client_ref,
+        )
+
+        return {
+            "conversation_id": conversation_id,
+            "message_id": user_mid,
+            "task_id": task_id,
+            "stream_id": handle.stream_id,
+            "client_ref": client_ref,
+        }
+
+    async def _generate(
+        self,
+        *,
+        store: ConversationStore,
+        conversation_id: str,
+        handle: StreamHandle,
+        completion_params: ChatCompletionParams | None = None,
+        client_ref: str | None = None,
+        task_status=None,
+    ) -> None:
+        resolved = self._llm.resolve(completion_params)
+
+        await self._streams.emit_start(
+            handle,
+            model=resolved.model,
+            provider=resolved.provider_name,
+            task_id=getattr(task_status, "id", None),
+            client_ref=client_ref,
+        )
+        try:
+            history = await store.list_messages(
+                conversation_id, cursor=0, limit=500
+            )
+            lc_messages = self._to_langchain(history) or [
+                HumanMessage(content="")
+            ]
+
+            async for delta in resolved.provider.stream(lc_messages):
+                if delta:
+                    await self._streams.push_chunk(handle, delta)
+
+            full_text = self._streams.finish(handle)
+            final_id = await self._persist_assistant(
+                store, conversation_id, full_text, resolved.model
+            )
+            self._streams.set_message_id(handle, final_id)
+
+            await self._emit_assistant_patch(
+                store, conversation_id, full_text, final_id
+            )
+            await self._streams.emit_end(handle, final_id)
+
+        except asyncio.CancelledError:
+            await self._streams.emit_error(handle, "cancelled")
+            raise
+        except Exception as e:
+            logger.exception("chat:response failed")
+            await self._streams.emit_error(handle, str(e))
+            raise
+
+    async def _emit_user_patch(
+        self, cid, msg, mid, meta
+    ) -> None:
+        wire = conversation_message_to_wire(
+            msg.model_copy(
+                update={
+                    "id": mid or msg.id,
+                    "sequence": meta.message_count - 1,
+                }
+            )
+        )
+        patches = (
+            ConversationPatchBuilder()
+            .add_message_wire(wire)
+            .message_count(meta.message_count)
+            .build()
+        )
+        await emit_conversation_patch(cid, patches)
+
+    async def _persist_assistant(
+        self, store, cid, text, model
+    ) -> str:
+        aid = str(uuid.uuid4())
+        msg = ConversationMessage(
+            id=aid,
+            role=MessageRole.ASSISTANT,
+            parts=[TextPart(text=text)],
+            model=model,
+        )
+        saved = await store.add_message(cid, msg)
+        return saved or aid
+
+    async def _emit_assistant_patch(
+        self, store, cid, text, final_id
+    ) -> None:
+        meta = await store.get_conversation_metadata(cid)
+        if meta is None:
+            return
+        idx = meta.message_count - 1
+        patches = (
+            ConversationPatchBuilder()
+            .finalize_assistant_text_part(
+                idx, text, message_id=final_id, sequence=idx
+            )
+            .message_count(meta.message_count)
+            .build()
+        )
+        await emit_conversation_patch(cid, patches)
+
+    @staticmethod
+    def _to_langchain(messages):
+        out = []
+        for m in messages:
+            text = "\n".join(
+                p.text for p in m.parts if isinstance(p, TextPart)
+            )
+            if m.role == MessageRole.USER:
+                out.append(HumanMessage(content=text))
+            elif m.role == MessageRole.ASSISTANT:
+                out.append(AIMessage(content=text))
+        return out
diff --git a/src/backend/app/agent/service/title_generator.py b/src/backend/app/agent/service/title_generator.py
new file mode 100644
index 00000000..cc17065f
--- /dev/null
+++ b/src/backend/app/agent/service/title_generator.py
@@ -0,0 +1,73 @@
+# agent/services/title_generator.py
+
+from langchain_core.messages import HumanMessage, SystemMessage
+from pydantic import BaseModel, Field
+from app.agent.llm.gateway import LLMGateway
+
+
+class TitleOutput(BaseModel):
+    title: str = Field(min_length=3, max_length=80)
+    description: str = Field(min_length=8, max_length=220)
+
+
+async def generate_conversation_title(
+    llm: LLMGateway, workflow, params: dict
+) -> tuple[str, str]:
+    name = getattr(workflow, "name", "workflow")
+    fallback_title = name.replace("_", " ").strip().title() + " Run"
+    fallback_desc = f"Run `{name}` with the provided parameters."
+
+    try:
+        mini = llm.create_mini()
+        base = getattr(mini, "_llm", None)
+        if base is None:
+            return fallback_title, fallback_desc
+
+        preview = ", ".join(
+            f"{k}={repr(v)[:77]}" for k, v in list(params.items())[:8]
+        ) or "None"
+
+        result = await base.with_structured_output(TitleOutput).ainvoke([
+            SystemMessage(content=(
+                "Generate concise conversation metadata for a "
+                "backend workflow run. No markdown or quotes."
+            )),
+            HumanMessage(content=(
+                f"Workflow: {name}\n"
+                f"Description: {getattr(workflow, 'description', '')}\n"
+                f"Params: {preview}\n\n"
+                "Return title (3-8 words) and description (one sentence)."
+            )),
+        ])
+        return (
+            result.title.strip().strip("\"'") or fallback_title,
+            result.description.strip().strip("\"'") or fallback_desc,
+        )
+    except Exception:
+        return fallback_title, fallback_desc
+
+
+class _BatchWorkflowMeta:
+    """Minimal stand-in for `generate_conversation_title` when starting batch runs."""
+
+    name = "workflow_batch"
+    description = (
+        "Runs multiple agent workflows sequentially in one conversation."
+    )
+
+
+async def generate_batch_conversation_title(
+    llm: LLMGateway,
+    steps: list[dict],
+) -> tuple[str, str]:
+    """
+    Same LLM-based naming as single-workflow runs, using step names as context.
+    """
+    preview_names = [str(s.get("workflow_name", "?")) for s in steps[:12]]
+    params = {
+        "step_count": len(steps),
+        "workflows": ", ".join(preview_names) or "none",
+    }
+    return await generate_conversation_title(
+        llm, _BatchWorkflowMeta(), params
+    )
diff --git a/src/backend/app/agent/service/workflow_service.py b/src/backend/app/agent/service/workflow_service.py
new file mode 100644
index 00000000..edbe565f
--- /dev/null
+++ b/src/backend/app/agent/service/workflow_service.py
@@ -0,0 +1,468 @@
+# app/agent/service/workflow_service.py
+
+from __future__ import annotations
+
+import uuid
+import logging
+from typing import Any
+
+from app.agent.conversation_store import ConversationStore
+from app.agent.llm.gateway import LLMGateway
+from app.agent.runner.task_context import TaskContext
+from app.agent.runner.task_manager import TaskManager
+from app.agent.runner.task_persistence import TaskPersistence
+from app.agent.service.title_generator import (
+    generate_batch_conversation_title,
+    generate_conversation_title,
+)
+from app.agent.workflows.base import BaseWorkflow
+from app.core.repository.conversation._common import new_doc_id
+from app.core.model.conversation_domain import (
+    ConversationMessage,
+    TaskPart,
+    TextPart,
+)
+from app.core.model.conversation_enums import (
+    MessageRole,
+    TaskState,
+    TaskState as ConversationTaskState,
+)
+from app.core.model.conversation_nodes import Task
+
+logger = logging.getLogger(__name__)
+
+_TERMINAL_STATES = {
+    TaskState.COMPLETED,
+    TaskState.FAILED,
+    TaskState.CANCELLED,
+}
+
+
+class WorkflowService:
+    def __init__(
+        self,
+        task_manager: TaskManager,
+        llm_gateway: LLMGateway,
+        db_client: Any = None,
+    ):
+        self._tasks = task_manager
+        self._llm = llm_gateway
+        self._db_client = db_client
+        self._task_part_cache: dict[str, TaskPart] = {}
+        # Keep reference to TaskContext per task_id so the
+        # status callback can read subtask snapshots.
+        self._task_contexts: dict[str, TaskContext] = {}
+
+    @property
+    def llm_factory(self):
+        return self._llm.factory
+
+    async def join_task(self, task_id: str) -> None:
+        await self._tasks.join(task_id)
+
+    # -- single workflow --------------------------------------------------
+
+    async def run(
+        self,
+        workflow: BaseWorkflow,
+        *,
+        store: ConversationStore,
+        conversation_id: str | None = None,
+        **params,
+    ) -> tuple[str, str]:
+        workflow_params = dict(params)
+        # API fields are misnamed: these label the workflow run (Task), not the chat.
+        task_label = (workflow_params.pop(
+            "conversation_title", None) or "").strip()
+        task_summary = (
+            workflow_params.pop("conversation_description", None) or ""
+        ).strip()
+
+        # 1. Ensure conversation (LLM metadata for the thread, same idea as batch)
+        if conversation_id is None:
+            gen_title, gen_desc = await generate_conversation_title(
+                self._llm, workflow, workflow_params
+            )
+            conversation_id = await store.create_conversation(
+                gen_title, gen_desc
+            )
+
+        # 2. Timeline: text + TaskPart ref (task_id == Task document @id)
+        message_id = str(uuid.uuid4())
+        task_id = new_doc_id("TaskSchema")
+        task_part = TaskPart(task_id=task_id)
+        await store.add_message(
+            conversation_id,
+            ConversationMessage(
+                id=message_id,
+                role=MessageRole.ASSISTANT,
+                parts=[
+                    TextPart(
+                        text=f"Starting {workflow.name}..."
+                    ),
+                    task_part,
+                ],
+            ),
+        )
+
+        task_display_name = task_label or f"workflow:{workflow.name}"
+        task_display_desc = task_summary
+
+        await self._create_task_in_db(
+            task_id=task_id,
+            conversation_id=conversation_id,
+            message_id=message_id,
+            workflow=workflow,
+            workflow_params=workflow_params,
+            name=task_display_name,
+            description=task_display_desc,
+        )
+
+        # 3. Create TaskContext (WorkflowService owns it)
+        ctx = TaskContext()
+        task_id_holder: list[str] = []
+
+        async def _on_status(status: Task) -> None:
+            if not task_id_holder:
+                return
+            task_id = task_id_holder[0]
+            subtask_snapshots = ctx.subtask_snapshots
+            await self._sync_task_part(
+                store,
+                conversation_id,
+                task_id,
+                status,
+                subtask_snapshots,
+            )
+            # On terminal state → flush to DB
+            if status.state in _TERMINAL_STATES:
+                await self._flush_to_db(
+                    task_id=task_id,
+                    conversation_id=conversation_id,
+                    message_id=message_id,
+                    status=status,
+                    ctx=ctx,
+                    workflow=workflow,
+                    workflow_params=workflow_params,
+                )
+
+        # 4. Submit — TaskManager runs workflow.run() in background
+        # Do not let client params override the runner task_id.
+        submit_kw = {
+            k: v for k, v in workflow_params.items() if k != "task_id"
+        }
+        self._tasks.submit(
+            name=f"workflow:{workflow.name}",
+            coro_factory=workflow.run,
+            on_status_update=_on_status,
+            task_context=ctx,
+            task_id=task_id,
+            **submit_kw,
+        )
+        task_id_holder.append(task_id)
+        self._task_contexts[task_id] = ctx
+
+        # In-memory / stream: keep human task label; persisted message is ref-only.
+        self._task_part_cache[task_id] = TaskPart(
+            task_id=task_id,
+            title=task_display_name,
+            workflow_name=workflow.name,
+        )
+        if not self._db_client:
+            await store.upsert_task_part(
+                conversation_id, self._task_part_cache[task_id]
+            )
+
+        # 7. Push initial state
+        initial = self._tasks.get_status(task_id)
+        if initial:
+            await self._sync_task_part(
+                store, conversation_id, task_id, initial, []
+            )
+
+        return conversation_id, task_id
+
+    # -- batch (non-blocking) ---------------------------------------------
+
+    async def run_batch(
+        self,
+        steps: list[dict[str, Any]],
+        *,
+        workflow_factory: Any,
+        store: ConversationStore,
+        conversation_id: str | None = None,
+        conversation_title: str | None = None,
+        conversation_description: str | None = None,
+    ) -> tuple[str, str]:
+        """
+        Submit an entire batch as ONE background task.
+        Steps run sequentially inside the background task.
+        Returns immediately with (conversation_id, parent_task_id).
+
+        ``conversation_title`` / ``conversation_description`` (API name) set the
+        **batch task** label in Terminus, not the chat thread; thread metadata
+        is always LLM-generated when creating a new conversation.
+        """
+        if conversation_id is None:
+            gen_title, gen_desc = await generate_batch_conversation_title(
+                self._llm, steps
+            )
+            conversation_id = await store.create_conversation(
+                gen_title, gen_desc
+            )
+
+        task_label = (conversation_title or "").strip()
+        task_summary = (conversation_description or "").strip()
+        task_display_name = task_label or "Batch workflow"
+        task_display_desc = task_summary
+
+        message_id = str(uuid.uuid4())
+        task_id = new_doc_id("TaskSchema")
+        task_part = TaskPart(task_id=task_id)
+        await store.add_message(
+            conversation_id,
+            ConversationMessage(
+                id=message_id,
+                role=MessageRole.ASSISTANT,
+                parts=[
+                    TextPart(text="Starting batch workflow..."),
+                    task_part,
+                ],
+            ),
+        )
+
+        await self._create_task_in_db(
+            task_id=task_id,
+            conversation_id=conversation_id,
+            message_id=message_id,
+            workflow=None,
+            workflow_params={"step_count": len(steps)},
+            name=task_display_name,
+            description=task_display_desc,
+        )
+
+        ctx = TaskContext()
+        task_id_holder: list[str] = []
+
+        async def _on_status(status: Task) -> None:
+            if not task_id_holder:
+                return
+            tid = task_id_holder[0]
+            await self._sync_task_part(
+                store,
+                conversation_id,
+                tid,
+                status,
+                ctx.subtask_snapshots,
+            )
+            if status.state in _TERMINAL_STATES:
+                await self._flush_to_db(
+                    task_id=tid,
+                    conversation_id=conversation_id,
+                    message_id=message_id,
+                    status=status,
+                    ctx=ctx,
+                    workflow=None,
+                    workflow_params={
+                        "step_count": len(steps)
+                    },
+                )
+
+        async def _batch_runner(
+            task_status: Task | None = None,
+            task_context: TaskContext | None = None,
+            **_kw,
+        ):
+            effective_ctx = task_context or TaskContext.noop()
+            if task_status:
+                effective_ctx.bind(task_status)
+
+            results = []
+            total = len(steps)
+            for i, step in enumerate(steps):
+                wf = workflow_factory(step)
+                st = effective_ctx.subtask(
+                    name=f"{wf.name}",
+                    subtask_id=f"step-{i}-{wf.name}",
+                )
+                st.start(
+                    f"Running {wf.name} ({i + 1}/{total})"
+                )
+                try:
+                    # Each step gets its own nested context
+                    step_ctx = TaskContext.noop()
+                    result = await wf.execute(
+                        step_ctx, **step["params"]
+                    )
+                    results.append(result)
+                    st.complete(f"Completed {wf.name}")
+                except Exception as exc:
+                    st.fail(str(exc))
+                    raise
+
+            return {"batch_results": results}
+
+        self._tasks.submit(
+            name="workflow:batch",
+            coro_factory=_batch_runner,
+            on_status_update=_on_status,
+            task_context=ctx,
+            task_id=task_id,
+        )
+        task_id_holder.append(task_id)
+        self._task_contexts[task_id] = ctx
+
+        self._task_part_cache[task_id] = TaskPart(
+            task_id=task_id,
+            title=task_display_name,
+            workflow_name="batch",
+        )
+        if not self._db_client:
+            await store.upsert_task_part(
+                conversation_id, self._task_part_cache[task_id]
+            )
+
+        return conversation_id, task_id
+
+    # -- DB persistence ---------------------------------------------------
+
+    async def _create_task_in_db(
+        self,
+        *,
+        task_id: str,
+        conversation_id: str,
+        message_id: str,
+        workflow: BaseWorkflow | None,
+        workflow_params: dict,
+        name: str | None = None,
+        description: str = "",
+    ) -> None:
+        if not self._db_client:
+            return
+        import json
+
+        persistence = TaskPersistence(self._db_client)
+        default_name = (
+            f"workflow:{workflow.name}" if workflow else "workflow:batch"
+        )
+        task_doc = Task(
+            id=task_id,
+            name=(name or default_name).strip() or default_name,
+            description=description,
+            conversation_id=conversation_id,
+            message_id=message_id,
+            state=TaskState.PENDING,
+            workflow_name=workflow.name if workflow else "batch",
+            workflow_params_json=json.dumps(
+                workflow_params, default=str
+            ),
+        )
+
+        try:
+            await persistence.create_task(task_doc)
+        except Exception:
+            logger.exception(
+                "Failed to persist task %s to DB", task_id
+            )
+
+    async def _flush_to_db(
+        self,
+        *,
+        task_id: str,
+        conversation_id: str,
+        message_id: str,
+        status: Task,
+        ctx: TaskContext,
+        workflow: BaseWorkflow | None,
+        workflow_params: dict,
+    ) -> None:
+        if not self._db_client:
+            return
+
+        persistence = TaskPersistence(self._db_client)
+
+        try:
+            await persistence.update_task_state(
+                task_id,
+                state=status.state,
+                progress=status.progress,
+                progress_message=status.progress_message,
+                error=status.error,
+                result_json=status.result_json,
+                started_at=status.started_at,
+                finished_at=status.finished_at,
+                sub_task_count=ctx.subtask_count,
+            )
+        except Exception:
+            logger.exception(
+                "Failed to update task %s in DB", task_id
+            )
+
+        try:
+            await persistence.flush_subtasks(
+                task_id, ctx.subtask_snapshots
+            )
+        except Exception:
+            logger.exception(
+                "Failed to flush subtasks for task %s", task_id
+            )
+
+        # Cleanup
+        self._task_contexts.pop(task_id, None)
+        self._task_part_cache.pop(task_id, None)
+
+    # -- TaskPart sync (frontend updates) ---------------------------------
+
+    async def _sync_task_part(
+        self,
+        store: ConversationStore,
+        conversation_id: str,
+        task_id: str,
+        status: Task | None,
+        subtask_snapshots: list | None = None,
+    ) -> None:
+        if status is None:
+            return
+        base = self._task_part_cache.get(
+            task_id,
+            TaskPart(task_id=task_id),
+        )
+        snaps = list(subtask_snapshots or [])
+        st_count = int(getattr(status, "sub_task_count", 0) or 0)
+        updated = base.model_copy(
+            update={
+                "title": base.title or status.name,
+                "state": ConversationTaskState(
+                    status.state.value
+                ),
+                "progress": status.progress,
+                "description": status.progress_message or "",
+                "started_at": status.started_at,
+                "finished_at": status.finished_at,
+                "sub_tasks": snaps,
+                "sub_task_count": max(len(snaps), st_count),
+            }
+        )
+        self._task_part_cache[task_id] = updated
+
+        if self._db_client:
+            persistence = TaskPersistence(self._db_client)
+            try:
+                await persistence.update_task_state(
+                    task_id,
+                    state=status.state,
+                    progress=status.progress,
+                    progress_message=status.progress_message,
+                    error=status.error,
+                    result_json=status.result_json,
+                    started_at=status.started_at,
+                    finished_at=status.finished_at,
+                    sub_task_count=max(len(snaps), st_count),
+                )
+            except Exception:
+                logger.exception(
+                    "Failed to persist live task state for %s", task_id
+                )
+            return
+
+        await store.upsert_task_part(conversation_id, updated)
diff --git a/src/backend/app/agent/streaming/__init__.py b/src/backend/app/agent/streaming/__init__.py
new file mode 100644
index 00000000..e8199ee2
--- /dev/null
+++ b/src/backend/app/agent/streaming/__init__.py
@@ -0,0 +1,15 @@
+"""WebSocket payloads and domain → client wire shapes for conversations."""
+
+from app.agent.streaming.conversation_events import (
+    conversation_room,
+    emit_conversation_patch,
+    emit_to_conversation,
+)
+from app.agent.streaming.wire import conversation_message_to_wire
+
+__all__ = [
+    "conversation_message_to_wire",
+    "conversation_room",
+    "emit_conversation_patch",
+    "emit_to_conversation",
+]
diff --git a/src/backend/app/agent/streaming/conversation_events.py b/src/backend/app/agent/streaming/conversation_events.py
new file mode 100644
index 00000000..011ad51d
--- /dev/null
+++ b/src/backend/app/agent/streaming/conversation_events.py
@@ -0,0 +1,38 @@
+"""Socket.IO helpers for conversation rooms and patch envelopes."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.socket.manager import get_socket_manager
+
+logger = logging.getLogger(__name__)
+
+
+def conversation_room(conversation_id: str) -> str:
+    return f"conv:{conversation_id}"
+
+
+async def emit_to_conversation(
+    conversation_id: str,
+    event: str,
+    data: dict[str, Any],
+) -> None:
+    mgr = get_socket_manager()
+    room = conversation_room(conversation_id)
+    try:
+        await mgr.server.emit(event, data, room=room)
+    except Exception as e:
+        logger.error("emit_to_conversation failed: %s", e)
+
+
+async def emit_conversation_patch(
+    conversation_id: str,
+    patches: list[dict[str, Any]],
+) -> None:
+    await emit_to_conversation(
+        conversation_id,
+        "conversation:patch",
+        {"conversation_id": conversation_id, "patches": patches},
+    )
diff --git a/src/backend/app/agent/streaming/manager.py b/src/backend/app/agent/streaming/manager.py
new file mode 100644
index 00000000..00d186fa
--- /dev/null
+++ b/src/backend/app/agent/streaming/manager.py
@@ -0,0 +1,111 @@
+# agent/streaming/manager.py
+
+import uuid
+import logging
+from dataclasses import dataclass
+
+from app.agent.streaming import emit_to_conversation
+from app.agent.runner.stream_buffer import StreamRegistry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StreamHandle:
+    stream_id: str
+    conversation_id: str
+
+
+class StreamManager:
+    def __init__(self, registry: StreamRegistry | None = None):
+        self._registry = registry or StreamRegistry()
+
+    def open(self, conversation_id: str) -> StreamHandle:
+        stream_id = str(uuid.uuid4())
+        self._registry.create(stream_id, conversation_id)
+        return StreamHandle(
+            stream_id=stream_id,
+            conversation_id=conversation_id,
+        )
+
+    async def emit_start(
+        self,
+        handle: StreamHandle,
+        *,
+        model: str,
+        provider: str,
+        task_id: str | None = None,
+        client_ref: str | None = None,
+    ) -> None:
+        payload = {
+            "stream_id": handle.stream_id,
+            "conversation_id": handle.conversation_id,
+            "model": model,
+            "provider": provider,
+        }
+        if task_id:
+            payload["task_id"] = task_id
+        if client_ref:
+            payload["client_ref"] = client_ref
+        await emit_to_conversation(
+            handle.conversation_id, "stream:start", payload
+        )
+
+    async def push_chunk(
+        self, handle: StreamHandle, delta: str
+    ) -> int | None:
+        buf = self._registry.get(handle.stream_id)
+        if buf is None:
+            return None
+        seq = buf.append(delta)
+        await emit_to_conversation(
+            handle.conversation_id,
+            "stream:chunk",
+            {
+                "stream_id": handle.stream_id,
+                "seq": seq,
+                "delta": delta,
+            },
+        )
+        return seq
+
+    def finish(self, handle: StreamHandle) -> str:
+        buf = self._registry.get(handle.stream_id)
+        if buf is None:
+            return ""
+        return buf.finish()
+
+    def set_message_id(
+        self, handle: StreamHandle, message_id: str
+    ) -> None:
+        buf = self._registry.get(handle.stream_id)
+        if buf:
+            buf.set_message_id(message_id)
+
+    def next_seq(self, handle: StreamHandle) -> int:
+        buf = self._registry.get(handle.stream_id)
+        return buf.next_seq if buf else 0
+
+    async def emit_end(
+        self, handle: StreamHandle, message_id: str
+    ) -> None:
+        await emit_to_conversation(
+            handle.conversation_id,
+            "stream:end",
+            {
+                "stream_id": handle.stream_id,
+                "message_id": message_id,
+                "total_seq": self.next_seq(handle),
+            },
+        )
+        self._registry.schedule_remove(handle.stream_id)
+
+    async def emit_error(
+        self, handle: StreamHandle, error: str
+    ) -> None:
+        await emit_to_conversation(
+            handle.conversation_id,
+            "stream:error",
+            {"stream_id": handle.stream_id, "error": error},
+        )
+        self._registry.schedule_remove(handle.stream_id)
diff --git a/src/backend/app/agent/streaming/wire.py b/src/backend/app/agent/streaming/wire.py
new file mode 100644
index 00000000..a07e5fc9
--- /dev/null
+++ b/src/backend/app/agent/streaming/wire.py
@@ -0,0 +1,68 @@
+"""Map domain models to the JSON shape the client keeps for patches / API responses."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.core.model.conversation_domain import (
+    ConversationMessage,
+    ConversationSummary,
+    MessagePart,
+    TaskPart,
+    TextPart,
+    ToolCallPart,
+)
+
+
+def _part_to_wire(part: MessagePart) -> dict[str, Any]:
+    if isinstance(part, TextPart):
+        return {"type": "text", "text": part.text}
+    if isinstance(part, TaskPart):
+        return {
+            "type": "task",
+            "task_id": part.task_id,
+            "title": part.title,
+            "description": part.description,
+            "state": part.state.value,
+            "progress": part.progress,
+            "sub_tasks": [st.model_dump(mode="json") for st in part.sub_tasks],
+            "sub_task_count": max(
+                int(part.sub_task_count or 0),
+                len(part.sub_tasks),
+            ),
+            "workflow_name": part.workflow_name,
+        }
+    if isinstance(part, ToolCallPart):
+        d: dict[str, Any] = {
+            "type": "tool_call",
+            "tool_name": part.tool_name,
+            "tool_input": part.tool_input,
+        }
+        if part.tool_output is not None:
+            d["tool_output"] = part.tool_output
+        return d
+    return part.model_dump(mode="json")  # event / future parts
+
+
+def conversation_message_to_wire(msg: ConversationMessage) -> dict[str, Any]:
+    return {
+        "id": msg.id,
+        "role": msg.role.value if hasattr(msg.role, "value") else str(msg.role),
+        "sequence": msg.sequence,
+        "parts": [_part_to_wire(p) for p in msg.parts],
+        "created_at": msg.created_at.isoformat(),
+        "token_count": msg.token_count,
+        "model": msg.model,
+    }
+
+
+def conversation_summary_to_wire(s: ConversationSummary) -> dict[str, Any]:
+    return {
+        "id": s.id,
+        "title": s.title,
+        "description": s.description,
+        "message_count": s.message_count,
+        "has_active_task": s.has_active_task,
+        "created_at": s.created_at.isoformat(),
+        "updated_at": s.updated_at.isoformat(),
+    }
diff --git a/src/backend/app/agent/tools/__init__.py b/src/backend/app/agent/tools/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/backend/app/agent/tools/base.py b/src/backend/app/agent/tools/base.py
new file mode 100644
index 00000000..98306b59
--- /dev/null
+++ b/src/backend/app/agent/tools/base.py
@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+from typing import Any
+from app.agent.tools.tool_card import ToolCard
+
+
+class BaseTool(ABC):
+    """Abstract base class for all agent tools."""
+
+    @abstractmethod
+    def get_card(self) -> ToolCard:
+        """Return the tool's self-describing metadata."""
+        ...
+
+    @abstractmethod
+    async def execute(self, **kwargs) -> Any:
+        """Run the tool with validated inputs. Returns structured output."""
+        ...
+
+    def validate_inputs(self, **kwargs) -> dict:
+        """Optional input validation hook. Override to add custom checks."""
+        return kwargs
diff --git a/src/backend/app/agent/tools/tool_card.py b/src/backend/app/agent/tools/tool_card.py
new file mode 100644
index 00000000..f28c52a8
--- /dev/null
+++ b/src/backend/app/agent/tools/tool_card.py
@@ -0,0 +1,23 @@
+from pydantic import BaseModel
+from typing import Optional
+
+
+class ToolCard(BaseModel):
+    """Self-describing metadata for a tool (OctoTools-style tool card)."""
+    name: str                            # e.g. "graph_search"
+    description: str                     # Human-readable purpose
+    version: str = "1.0.0"
+
+    # Schema for inputs / outputs
+    input_schema: dict                   # JSON-Schema dict for execute() kwargs
+    output_type: str                     # Human-readable output type description
+
+    # Usage hints (fed to the planner LLM)
+    demo_commands: list[dict] = []       # Example invocations
+    limitations: Optional[str] = None
+    best_practice: Optional[str] = None
+
+    # Runtime flags
+    requires_llm: bool = False           # Does this tool need an LLM engine internally?
+    requires_vectorlink: bool = False    # Needs VectorLink client?
+    requires_db: bool = False            # Needs TerminusDB client?
diff --git a/src/backend/app/agent/tools/tool_registry.py b/src/backend/app/agent/tools/tool_registry.py
new file mode 100644
index 00000000..41704d89
--- /dev/null
+++ b/src/backend/app/agent/tools/tool_registry.py
@@ -0,0 +1,24 @@
+from app.agent.tools.base import BaseTool
+from app.agent.tools.tool_card import ToolCard
+
+
+class ToolRegistry:
+    """Discover, register, enable/disable tools at runtime."""
+
+    def __init__(self):
+        self._tools: dict[str, BaseTool] = {}
+
+    def register(self, tool: BaseTool) -> None:
+        card = tool.get_card()
+        self._tools[card.name] = tool
+
+    def get(self, name: str) -> BaseTool:
+        return self._tools[name]
+
+    def list_cards(self, enabled_only: bool = True) -> list[ToolCard]:
+        """Return tool cards (useful for feeding to the LLM planner)."""
+        return [t.get_card() for t in self._tools.values()]
+
+    def auto_discover(self, package_path: str = "app.agent.tools") -> None:
+        """Walk subpackages, import any BaseTool subclass, register it."""
+        ...
diff --git a/src/backend/app/agent/workflows/__init__.py b/src/backend/app/agent/workflows/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/backend/app/agent/workflows/base.py b/src/backend/app/agent/workflows/base.py
new file mode 100644
index 00000000..f6a9e12a
--- /dev/null
+++ b/src/backend/app/agent/workflows/base.py
@@ -0,0 +1,43 @@
+# app/agent/workflows/base.py
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from app.core.model.conversation_nodes import Task
+from app.agent.runner.task_context import TaskContext
+
+
+class BaseWorkflow(ABC):
+    """
+    Template Method base for all workflows.
+
+    Subclasses implement `validate()` and `execute()`.
+    The framework calls `run()`.
+    """
+
+    name: str
+    description: str
+
+    async def validate(self, **kwargs) -> None:
+        """Override to reject invalid params before execution."""
+
+    @abstractmethod
+    async def execute(self, ctx: TaskContext, **kwargs) -> Any:
+        """Implement workflow logic here."""
+        ...
+
+    async def run(
+        self,
+        task_status: Task | None = None,
+        task_context: TaskContext | None = None,
+        **kwargs,
+    ) -> Any:
+        """
+        Template method — called by TaskManager.
+        Do NOT override in subclasses.
+        """
+        ctx = task_context or TaskContext.noop()
+        if task_status:
+            ctx.bind(task_status)
+        await self.validate(**kwargs)
+        return await self.execute(ctx, **kwargs)
diff --git a/src/backend/app/agent/workflows/description_gen.py b/src/backend/app/agent/workflows/description_gen.py
new file mode 100644
index 00000000..a56f554f
--- /dev/null
+++ b/src/backend/app/agent/workflows/description_gen.py
@@ -0,0 +1,236 @@
+# app/agent/workflows/description_gen.py
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import HumanMessage
+
+from app.agent.context.graph_traversal import GraphTraversal
+from app.agent.runner.task_context import TaskContext
+from app.agent.workflows.base import BaseWorkflow
+from app.agent.workflows.node_persistence import NodePersistence
+from app.agent.workflows.traversal_helpers import ordered_nodes
+
+_NODE_TYPES = [
+    "FileSchema",
+    "FunctionSchema",
+    "ClassSchema",
+    "FolderSchema",
+]
+
+
+class DescriptionGeneratorWorkflow(BaseWorkflow):
+    name = "description_generator"
+    description = "Generate descriptions recursively from a tree"
+
+    def __init__(
+        self,
+        graph: GraphTraversal | None = None,
+        llm_factory=None,
+    ):
+        self.graph = graph
+        self.llm_factory = llm_factory
+
+    async def validate(self, **kwargs) -> None:
+        if self.graph is None:
+            raise ValueError(
+                "GraphTraversal is required for description workflow."
+            )
+        if self.llm_factory is None:
+            raise ValueError(
+                "LLM factory is required for description workflow."
+            )
+        direction = kwargs.get("direction", "down")
+        if direction not in {"up", "down"}:
+            raise ValueError(f"Invalid direction: {direction}")
+
+    async def execute(self, ctx: TaskContext, **kwargs) -> dict:
+        self._read_llm_options(kwargs)
+        node_id = kwargs.get("node_id")
+        direction = kwargs.get("direction", "down")
+        max_depth = kwargs.get("max_depth", 5)
+        description_mode = kwargs.pop("description_mode", "always")
+
+        ctx.update_progress(0.0, "Building tree...")
+
+        roots = await self.graph.build_tree(
+            node_id=node_id,
+            node_types=_NODE_TYPES,
+            max_depth=max_depth,
+        )
+        nodes = ordered_nodes(roots, direction)
+
+        if description_mode == "skip_if_present":
+            nodes = [
+                n
+                for n in nodes
+                if not (
+                    getattr(n, "description", None) or ""
+                ).strip()
+            ]
+
+        if not nodes:
+            return {"processed": 0, "results": {}}
+
+        generated: dict[str, str] = {}
+        node_updates: dict[str, Any] = {}
+
+        for index, tree_node in enumerate(nodes):
+            nid = getattr(tree_node, "id", None)
+            if not nid:
+                continue
+
+            node_doc = self._tree_node_to_prompt_doc(tree_node)
+            node_doc["code_content_data"] = (
+                await self.graph.get_code_content(nid)
+            )
+
+            node_name = node_doc.get("name", nid)
+
+            # -- register subtask --
+            st = ctx.subtask(
+                name=node_name,
+                subtask_id=nid,
+                touched_node_ids=[nid],
+            )
+            st.start(f"Generating description for {node_name}")
+
+            child_descs = self._gather_child_values(
+                tree_node, generated, attr="description"
+            )
+            prompt = self._build_description_prompt(
+                node_doc=node_doc,
+                child_descriptions=child_descs,
+            )
+
+            try:
+                text = await self._invoke_llm(prompt)
+
+                generated[nid] = text
+                node_updates[nid] = tree_node.model_copy(
+                    update={"description": text}
+                )
+                st.complete(f"Done: {node_name}")
+            except Exception as exc:
+                st.fail(str(exc))
+                raise
+
+        persistence = NodePersistence(self.graph)
+        await persistence.flush_descriptions(node_updates)
+
+        return {
+            "processed": len(generated),
+            "direction": direction,
+            "description_results": generated,
+        }
+
+    # -- shared helpers ---------------------------------------------------
+
+    def _read_llm_options(self, kwargs: dict) -> None:
+        self._invoke_model = (
+            kwargs.pop("model", None) or "gpt-4o-mini"
+        )
+        self._invoke_provider = kwargs.pop("provider", None)
+
+    @staticmethod
+    def _tree_node_to_prompt_doc(tree_node: Any) -> dict:
+        node_type = tree_node.__class__.__name__.replace(
+            "TreeNode", "Schema"
+        )
+        return {
+            "@id": getattr(tree_node, "id", None),
+            "@type": node_type,
+            "name": getattr(tree_node, "name", ""),
+            "description": getattr(tree_node, "description", ""),
+        }
+
+    @staticmethod
+    def _gather_child_values(
+        tree_node: Any,
+        generated_values: dict[str, str],
+        attr: str = "description",
+    ) -> list[str]:
+        """
+        Collect child values, preferring freshly generated
+        values over the tree node's original attribute.
+        """
+        values: list[str] = []
+        for child in getattr(tree_node, "children", []) or []:
+            child_id = getattr(child, "id", None)
+            if not child_id:
+                continue
+            # Freshly generated wins
+            val = generated_values.get(child_id)
+            if not val:
+                val = getattr(child, attr, None)
+            if val and isinstance(val, str) and val.strip():
+                values.append(val)
+        return values
+
+    @staticmethod
+    def _extract_code_context(node_doc: dict) -> str:
+        node_type = (
+            (node_doc.get("@type") or "").replace("Schema", "")
+        )
+        if node_type not in {"File", "Function", "Class"}:
+            return ""
+        code = node_doc.get("code_content_data")
+        if isinstance(code, str) and code.strip():
+            return code
+        return ""
+
+    def _build_description_prompt(
+        self,
+        *,
+        node_doc: dict,
+        child_descriptions: list[str],
+    ) -> str:
+        child_ctx = (
+            "\n".join(f"- {d}" for d in child_descriptions)
+            if child_descriptions
+            else "None"
+        )
+        code_ctx = (
+            self._extract_code_context(node_doc)
+            or "No direct code content found."
+        )
+        return (
+            "Task: description\n"
+            "Write a concise technical description of this "
+            "node in 1-5 sentences.\n"
+            "Use child descriptions for context and avoid "
+            "repetition.\n\n"
+            f"Node id: {node_doc.get('@id')}\n"
+            f"Node type: {node_doc.get('@type')}\n"
+            f"Node name: {node_doc.get('name')}\n"
+            f"Current description: "
+            f"{node_doc.get('description', '')}\n\n"
+            f"Code context:\n{code_ctx}\n\n"
+            f"Child descriptions:\n{child_ctx}\n"
+        )
+
+    async def _invoke_llm(self, prompt: str) -> str:
+
+        model = (
+            getattr(self, "_invoke_model", None) or "gpt-4o-mini"
+        )
+        provider = getattr(self, "_invoke_provider", None)
+        llm = self.llm_factory.create(
+            provider=provider, model=model
+        )
+        response = await llm.invoke(
+            [HumanMessage(content=prompt)]
+        )
+        content = getattr(response, "content", "")
+        if isinstance(content, str):
+            return content.strip()
+        if isinstance(content, list):
+            parts = []
+            for item in content:
+                if isinstance(item, dict):
+                    text = item.get("text")
+                    if text:
+                        parts.append(text)
+            return "\n".join(parts).strip()
+        return str(content).strip()
diff --git a/src/backend/app/agent/workflows/documentation_gen.py b/src/backend/app/agent/workflows/documentation_gen.py
new file mode 100644
index 00000000..d865777b
--- /dev/null
+++ b/src/backend/app/agent/workflows/documentation_gen.py
@@ -0,0 +1,174 @@
+# app/agent/workflows/documentation_gen.py
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.agent.context.graph_traversal import GraphTraversal
+from app.agent.runner.task_context import TaskContext
+from app.agent.workflows.description_gen import (
+    DescriptionGeneratorWorkflow,
+    _NODE_TYPES,
+)
+from app.agent.workflows.node_persistence import NodePersistence
+from app.agent.workflows.traversal_helpers import ordered_nodes
+
+
+class DocumentationGeneratorWorkflow(DescriptionGeneratorWorkflow):
+    """Recursive doc generation; persisted as markdown with empty ``data`` (see ``NodePersistence``)."""
+
+    name = "documentation_generator"
+    description = (
+        "Generate documentation recursively from a tree"
+    )
+
+    def __init__(
+        self,
+        graph: GraphTraversal | None = None,
+        llm_factory=None,
+    ):
+        super().__init__(graph=graph, llm_factory=llm_factory)
+
+    async def execute(self, ctx: TaskContext, **kwargs) -> dict:
+        self._read_llm_options(kwargs)
+        kwargs.pop("description_mode", None)
+        documentation_mode = kwargs.pop(
+            "documentation_mode", "upsert"
+        )
+
+        node_id = kwargs.get("node_id")
+        direction = kwargs.get("direction", "down")
+        max_depth = kwargs.get("max_depth", 5)
+
+        ctx.update_progress(0.0, "Building tree...")
+
+        roots = await self.graph.build_tree(
+            node_id=node_id,
+            node_types=_NODE_TYPES,
+            max_depth=max_depth,
+        )
+        nodes = ordered_nodes(roots, direction)
+
+        if not nodes:
+            return {
+                "processed": 0,
+                "documentation_results": {},
+                "upserted_document_ids": [],
+            }
+
+        persistence = NodePersistence(self.graph)
+
+        if documentation_mode == "insert_only":
+            filtered = []
+            for n in nodes:
+                nid = getattr(n, "id", None)
+                if nid and not await persistence.check_document_exists(
+                    nid
+                ):
+                    filtered.append(n)
+            nodes = filtered
+
+        if not nodes:
+            return {
+                "processed": 0,
+                "documentation_results": {},
+                "upserted_document_ids": [],
+            }
+
+        doc_values: dict[str, str] = {}
+        processed_nodes: dict[str, Any] = {}
+
+        for index, tree_node in enumerate(nodes):
+            nid = getattr(tree_node, "id", None)
+            if not nid:
+                continue
+
+            node_doc = self._tree_node_to_prompt_doc(tree_node)
+            node_doc["code_content_data"] = (
+                await self.graph.get_code_content(nid)
+            )
+            node_name = node_doc.get("name", nid)
+
+            st = ctx.subtask(
+                name=node_name,
+                subtask_id=nid,
+                touched_node_ids=[nid],
+            )
+            st.start(f"Generating documentation for {node_name}")
+
+            # Use freshly generated docs for child context
+            child_docs = self._gather_child_values(
+                tree_node, doc_values, attr="description"
+            )
+            # Use tree descriptions for child descriptions
+            child_descs = self._gather_child_values(
+                tree_node, {}, attr="description"
+            )
+
+            prompt = self._build_documentation_prompt(
+                node_doc=node_doc,
+                node_description=(
+                    getattr(tree_node, "description", "") or ""
+                ),
+                child_documentations=child_docs,
+                child_descriptions=child_descs,
+            )
+
+            try:
+                text = await self._invoke_llm(prompt)
+                doc_values[nid] = text
+                processed_nodes[nid] = tree_node
+                st.complete(f"Done: {node_name}")
+            except Exception as exc:
+                st.fail(str(exc))
+                raise
+
+        upserted_ids = (
+            await persistence.flush_documentation_batch(
+                doc_values, processed_nodes
+            )
+        )
+
+        return {
+            "processed": len(doc_values),
+            "direction": direction,
+            "documentation_results": doc_values,
+            "upserted_document_ids": upserted_ids,
+        }
+
+    def _build_documentation_prompt(
+        self,
+        *,
+        node_doc: dict,
+        node_description: str,
+        child_documentations: list[str],
+        child_descriptions: list[str],
+    ) -> str:
+        child_doc_ctx = (
+            "\n".join(f"- {d}" for d in child_documentations)
+            if child_documentations
+            else "None"
+        )
+        child_desc_ctx = (
+            "\n".join(f"- {d}" for d in child_descriptions)
+            if child_descriptions
+            else "None"
+        )
+        code_ctx = (
+            self._extract_code_context(node_doc)
+            or "No direct code content found."
+        )
+        return (
+            "Task: documentation\n"
+            "Write practical technical documentation for this "
+            "node.\n"
+            "Use node description and child outputs to keep "
+            "hierarchy-consistent docs.\n\n"
+            f"Node id: {node_doc.get('@id')}\n"
+            f"Node type: {node_doc.get('@type')}\n"
+            f"Node name: {node_doc.get('name')}\n"
+            f"Node description: {node_description}\n\n"
+            f"Code context:\n{code_ctx}\n\n"
+            f"Child documentations:\n{child_doc_ctx}\n\n"
+            f"Child descriptions:\n{child_desc_ctx}\n"
+        )
diff --git a/src/backend/app/agent/workflows/node_persistence.py b/src/backend/app/agent/workflows/node_persistence.py
new file mode 100644
index 00000000..c24df22d
--- /dev/null
+++ b/src/backend/app/agent/workflows/node_persistence.py
@@ -0,0 +1,193 @@
+# app/agent/workflows/node_persistence.py
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from app.agent.context.graph_traversal import GraphTraversal
+from app.core.model.schemas import DocumentSchema
+from app.db.async_terminus_client import WOQLQuery as WQ
+
+try:
+    from terminusdb_client.woqlquery.woql_query import Doc
+except ImportError:  # pragma: no cover
+    Doc = dict  # type: ignore
+
+logger = logging.getLogger(__name__)
+
+
+class NodePersistence:
+    """
+    All DB write operations for workflows.
+
+    Keeps workflow classes focused on orchestration + LLM calls.
+    """
+
+    def __init__(self, graph: GraphTraversal):
+        self._graph = graph
+
+    @property
+    def _client(self):
+        return self._graph.repos.client
+
+    # -- descriptions -----------------------------------------------------
+
+    async def flush_descriptions(
+        self,
+        node_updates: dict[str, Any],
+    ) -> None:
+        if not self._client or not node_updates:
+            return
+
+        for node in node_updates.values():
+            node_id = getattr(node, "id", None)
+            if not node_id:
+                continue
+
+            queries = []
+            if hasattr(node, "description"):
+                queries.extend(
+                    [
+                        WQ().opt(
+                            WQ()
+                            .triple(
+                                node_id,
+                                "description",
+                                "v:old_description",
+                            )
+                            .delete_triple(
+                                node_id,
+                                "description",
+                                "v:old_description",
+                            )
+                        ),
+                        WQ().add_triple(
+                            node_id,
+                            "description",
+                            WQ().string(
+                                getattr(node, "description", "") or ""
+                            ),
+                        ),
+                    ]
+                )
+
+            if hasattr(node, "documents"):
+                for doc_id in set(getattr(node, "documents") or set()):
+                    queries.append(
+                        WQ().opt(
+                            WQ().add_triple(
+                                node_id, "documents", doc_id
+                            )
+                        )
+                    )
+
+            if queries:
+                await self._client.query(
+                    WQ().woql_and(*queries),
+                    commit_msg=f"Workflow: update node {node_id}",
+                )
+
+    # -- documentation documents ------------------------------------------
+
+    @staticmethod
+    def documentation_doc_id(node_id: str) -> str:
+        safe = node_id.replace("/", "_").replace(":", "_")
+        return f"DocumentSchema/{safe}_workflow_documentation"
+
+    async def flush_documentation_batch(
+        self,
+        documentation_values: dict[str, str],
+        processed_nodes: dict[str, Any],
+    ) -> list[str]:
+        if not self._client or not documentation_values:
+            return []
+
+        now = datetime.now(timezone.utc)
+        doc_ids = [
+            self.documentation_doc_id(nid)
+            for nid in documentation_values
+        ]
+
+        existing_docs: dict[str, dict] = {}
+        try:
+            existing = await self._client.get_documents(doc_ids)
+            existing_docs = {
+                doc.get("@id"): doc for doc in existing
+            }
+        except Exception:
+            existing_docs = {}
+
+        document_queries = []
+        link_queries = []
+
+        for node_id, content in documentation_values.items():
+            doc_id = self.documentation_doc_id(node_id)
+            created_at = existing_docs.get(doc_id, {}).get(
+                "created_at", now
+            )
+
+            # Store generated text as markdown only; leave data empty so the
+            # editor loads from markdown (BlockNote) instead of JSON blocks.
+            schema = DocumentSchema(
+                _id=doc_id,
+                name="Overview ",
+                description="Generated by documentation workflow.",
+                data="",
+                markdown=content,
+                created_at=created_at,
+                updated_at=now,
+            )
+            document_queries.append(
+                WQ().insert_document(Doc(schema._obj_to_dict()[0]))
+            )
+
+            tree_node = processed_nodes.get(node_id)
+            tree_node_id = (
+                getattr(tree_node, "id", None)
+                if tree_node
+                else None
+            )
+            if tree_node_id:
+                link_queries.append(
+                    WQ().opt(
+                        WQ().add_triple(
+                            tree_node_id, "documents", doc_id
+                        )
+                    )
+                )
+
+        if document_queries:
+            await self._client.query(
+                WQ().woql_and(*document_queries),
+                commit_msg=(
+                    f"Workflow: upsert {len(document_queries)} "
+                    "generated documents"
+                ),
+            )
+        if link_queries:
+            await self._client.query(
+                WQ().woql_and(*link_queries),
+                commit_msg=(
+                    f"Workflow: link {len(link_queries)} "
+                    "documents to nodes"
+                ),
+            )
+
+        return doc_ids
+
+    async def check_document_exists(self, node_id: str) -> bool:
+        if not self._client:
+            return False
+        doc_id = self.documentation_doc_id(node_id)
+        try:
+            existing = await self._client.get_documents([doc_id])
+            if not existing:
+                return False
+            row = existing[0]
+            has_data = bool((row.get("data") or "").strip())
+            has_md = bool((row.get("markdown") or "").strip())
+            return has_data or has_md
+        except Exception:
+            return False
diff --git a/src/backend/app/agent/workflows/traversal_helpers.py b/src/backend/app/agent/workflows/traversal_helpers.py
new file mode 100644
index 00000000..4504dcdb
--- /dev/null
+++ b/src/backend/app/agent/workflows/traversal_helpers.py
@@ -0,0 +1,35 @@
+# app/agent/workflows/traversal_helpers.py
+
+from collections import deque
+from typing import Any
+
+
+def collect_levels(roots: list[Any]) -> list[list[Any]]:
+    if not roots:
+        return []
+    levels: list[list[Any]] = []
+    queue: deque[tuple[Any, int]] = deque()
+    visited: set[str] = set()
+    for root in roots:
+        rid = getattr(root, "id", None)
+        if rid and rid not in visited:
+            visited.add(rid)
+            queue.append((root, 0))
+    while queue:
+        node, depth = queue.popleft()
+        while len(levels) <= depth:
+            levels.append([])
+        levels[depth].append(node)
+        for child in getattr(node, "children", []) or []:
+            cid = getattr(child, "id", None)
+            if cid and cid not in visited:
+                visited.add(cid)
+                queue.append((child, depth + 1))
+    return levels
+
+
+def ordered_nodes(roots: list[Any], direction: str) -> list[Any]:
+    levels = collect_levels(roots)
+    if direction == "up":
+        levels = list(reversed(levels))
+    return [n for level in levels for n in level]
diff --git a/src/backend/app/api/dependencies.py b/src/backend/app/api/dependencies.py
index 2d58d3aa..e19aa74c 100644
--- a/src/backend/app/api/dependencies.py
+++ b/src/backend/app/api/dependencies.py
@@ -1,5 +1,7 @@
+from app.agent.llm.gateway import LLMGateway
 from typing import Optional
-from fastapi import Depends, Header, HTTPException, Query, status
+from fastapi import Depends, Header, HTTPException, Query, Request, status
+from app.agent.conversation_store import TerminusConversationStore
 from app.core.services.project_service import ProjectService
 from app.core.services.code_element_service import CodeElementService
 
@@ -9,10 +11,13 @@
 from app.core.services.document_service import DocumentService
 from app.core.services.test_service import TestService
 from app.core.services.play_ground_service import PlayGroundService
+from app.core.repository.conversation import ConversationRepo
 from app.db.client import get_terminus_client
 from app.db.async_terminus_client import AsyncClient
 from app.core.model.nodes import ProjectNode
 from app.db.context import RequestDbContext, ProjectUoW
+from app.agent.service.chat_service import ChatService
+from app.agent.service.workflow_service import WorkflowService
 
 
 def get_project_service(
@@ -111,3 +116,46 @@ def get_play_ground_service(
     uow: ProjectUoW = Depends(get_project_uow),
 ) -> PlayGroundService:
     return PlayGroundService(uow)
+
+
+def get_project_conversation_repo(
+    uow: ProjectUoW = Depends(get_project_uow),
+) -> ConversationRepo:
+    """Conversation/task documents in the project Terminus DB (branch/ref from request context)."""
+    return uow.get_project_repos().conversation_repo
+
+
+def get_project_conversation_store(
+    uow: ProjectUoW = Depends(get_project_uow),
+) -> TerminusConversationStore:
+    repo = uow.get_project_repos().conversation_repo
+    return TerminusConversationStore(repo)
+
+
+def get_llm_gateway(request: Request) -> LLMGateway:
+    factory = getattr(request.app.state, "llm_factory", None)
+    if factory is None:
+        raise RuntimeError("llm_factory not initialized on app.state")
+    return LLMGateway(llm_factory=factory)
+
+
+def get_chat_service(request: Request) -> ChatService:
+    tm = getattr(request.app.state, "task_manager", None)
+    sm = getattr(request.app.state, "stream_manager", None)
+    if tm is None or sm is None:
+        raise RuntimeError("task_manager or stream_manager not on app.state")
+    return ChatService(
+        task_manager=tm,
+        llm_gateway=get_llm_gateway(request),
+        stream_manager=sm,
+    )
+
+
+def get_workflow_service(request: Request) -> WorkflowService:
+    tm = getattr(request.app.state, "task_manager", None)
+    if tm is None:
+        raise RuntimeError("task_manager not initialized on app.state")
+    return WorkflowService(
+        task_manager=tm,
+        llm_gateway=get_llm_gateway(request),
+    )
diff --git a/src/backend/app/api/root.py b/src/backend/app/api/root.py
index 97c24da8..2a82a9dd 100755
--- a/src/backend/app/api/root.py
+++ b/src/backend/app/api/root.py
@@ -9,6 +9,13 @@
 from .v1.versioning import router as versioning_router
 # from .v1 import call_routes
 from .v1 import group_routes
+from .v1.conversations import chat_router as conversations_chat_router
+from .v1.conversations import conversation_router as conversations_router
+from .v1.conversations import (
+    conversation_tasks_router as conversation_scoped_tasks_router,
+)
+from .v1.conversations import task_router as conversation_tasks_router
+from .v1.conversations import workflow_router as agent_workflows_router
 
 router = APIRouter()
 
@@ -48,3 +55,9 @@ def get_root():
 # router.include_router(call_routes.router, prefix="/calls", tags=["calls"])
 
 router.include_router(group_routes.router, prefix="/groups", tags=["groups"])
+
+router.include_router(conversations_router)
+router.include_router(conversations_chat_router)
+router.include_router(conversation_scoped_tasks_router)
+router.include_router(conversation_tasks_router)
+router.include_router(agent_workflows_router, prefix="/agent")
diff --git a/src/backend/app/api/v1/conversations/__init__.py b/src/backend/app/api/v1/conversations/__init__.py
new file mode 100644
index 00000000..48f9e0b7
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/__init__.py
@@ -0,0 +1,15 @@
+from app.api.v1.conversations.routes import (
+    chat_router,
+    conversation_router,
+    conversation_tasks_router,
+    task_router,
+    workflow_router,
+)
+
+__all__ = [
+    "chat_router",
+    "conversation_router",
+    "conversation_tasks_router",
+    "task_router",
+    "workflow_router",
+]
diff --git a/src/backend/app/api/v1/conversations/deps.py b/src/backend/app/api/v1/conversations/deps.py
new file mode 100644
index 00000000..425fe2a0
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/deps.py
@@ -0,0 +1,35 @@
+"""FastAPI dependencies for conversation + task APIs."""
+
+from __future__ import annotations
+
+from fastapi import Depends, Request
+
+from app.agent.context.graph_traversal import GraphTraversal
+from app.agent.runner.task_manager import TaskManager
+from app.api.dependencies import (
+    get_project_conversation_repo as get_conversation_repo,
+    get_project_conversation_store as get_conversation_store,
+    get_project_uow,
+)
+from app.db.context import ProjectUoW
+
+__all__ = [
+    "get_conversation_repo",
+    "get_conversation_store",
+    "get_graph_traversal",
+    "get_task_manager",
+]
+
+
+def get_task_manager(request: Request) -> TaskManager:
+    tm = getattr(request.app.state, "task_manager", None)
+    if tm is None:
+        raise RuntimeError("task_manager not initialized on app.state")
+    return tm
+
+
+def get_graph_traversal(
+    uow: ProjectUoW = Depends(get_project_uow),
+) -> GraphTraversal:
+    """Graph access scoped to the resolved project, branch, and ref."""
+    return GraphTraversal(uow)
diff --git a/src/backend/app/api/v1/conversations/mappers.py b/src/backend/app/api/v1/conversations/mappers.py
new file mode 100644
index 00000000..8330122e
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/mappers.py
@@ -0,0 +1,21 @@
+"""Map validated API DTOs to domain models."""
+
+from __future__ import annotations
+
+from fastapi import HTTPException, status
+
+from app.api.v1.conversations.schemas.parts import TextPartIn
+from app.core.model.conversation_domain import MessagePart, TextPart
+
+
+def message_parts_to_domain(parts: list) -> list[MessagePart]:
+    out: list[MessagePart] = []
+    for p in parts:
+        if isinstance(p, TextPartIn):
+            out.append(TextPart(text=p.text))
+        else:
+            raise HTTPException(
+                status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail=f"Unsupported message part: {type(p).__name__}",
+            )
+    return out
diff --git a/src/backend/app/api/v1/conversations/params.py b/src/backend/app/api/v1/conversations/params.py
new file mode 100644
index 00000000..d1eb4e54
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/params.py
@@ -0,0 +1,27 @@
+"""Reusable FastAPI Query declarations for TerminusDB document ids (may contain `/`)."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Query
+
+ConversationIdQuery = Annotated[
+    str,
+    Query(
+        ...,
+        min_length=1,
+        max_length=512,
+        description="Full TerminusDB id (e.g. ConversationSchema/uuid). URL-encode `/` as %2F.",
+    ),
+]
+
+TaskIdQuery = Annotated[
+    str,
+    Query(
+        ...,
+        min_length=1,
+        max_length=512,
+        description="Full task document id or in-memory task id. URL-encode `/` as %2F.",
+    ),
+]
diff --git a/src/backend/app/api/v1/conversations/routes/__init__.py b/src/backend/app/api/v1/conversations/routes/__init__.py
new file mode 100644
index 00000000..eba30835
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/routes/__init__.py
@@ -0,0 +1,17 @@
+from app.api.v1.conversations.routes.chat import router as chat_router
+from app.api.v1.conversations.routes.conversation import (
+    router as conversation_router,
+)
+from app.api.v1.conversations.routes.task import (
+    conversation_tasks_router,
+    router as task_router,
+)
+from app.api.v1.conversations.routes.workflows import router as workflow_router
+
+__all__ = [
+    "chat_router",
+    "conversation_router",
+    "conversation_tasks_router",
+    "task_router",
+    "workflow_router",
+]
diff --git a/src/backend/app/api/v1/conversations/routes/chat.py b/src/backend/app/api/v1/conversations/routes/chat.py
new file mode 100644
index 00000000..6624be7d
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/routes/chat.py
@@ -0,0 +1,85 @@
+"""Conversation messages and agent chat HTTP API."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.agent.conversation_store import ConversationStore
+from app.agent.streaming.wire import conversation_message_to_wire
+from app.agent.service.chat_service import ChatService
+from app.api.dependencies import get_chat_service
+from app.api.v1.conversations.deps import get_conversation_store
+from app.api.v1.conversations.mappers import message_parts_to_domain
+from app.api.v1.conversations.params import ConversationIdQuery
+from app.api.v1.conversations.schemas import (
+    PaginatedItems,
+    PostMessageResponse,
+    SendConversationMessageRequest,
+)
+from app.core.model.conversation_domain import ConversationMessage
+from app.core.model.conversation_enums import MessageRole
+
+router = APIRouter(prefix="/conversations", tags=["chat"])
+
+
+@router.get("/messages")
+async def list_messages(
+    conversation_id: ConversationIdQuery,
+    cursor: int = Query(default=0, ge=0),
+    limit: int = Query(default=50, ge=1, le=200),
+    store: ConversationStore = Depends(get_conversation_store),
+) -> PaginatedItems:
+    meta = await store.get_conversation_metadata(conversation_id)
+    if meta is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail="Not found")
+    rows = await store.list_messages(
+        conversation_id, cursor=cursor, limit=limit + 1
+    )
+    has_more = len(rows) > limit
+    page = rows[:limit]
+    next_c: int | None = None
+    if has_more and page:
+        next_c = page[-1].sequence + 1
+    return PaginatedItems(
+        items=[conversation_message_to_wire(m) for m in page],
+        next_cursor=next_c,
+        has_more=has_more,
+    )
+
+
+@router.post(
+    "/messages",
+    status_code=status.HTTP_202_ACCEPTED,
+)
+async def post_message(
+    body: SendConversationMessageRequest,
+    chat: ChatService = Depends(get_chat_service),
+    store: ConversationStore = Depends(get_conversation_store),
+) -> PostMessageResponse:
+    cid = body.conversation_id
+    meta = await store.get_conversation_metadata(cid)
+    if meta is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail="Not found")
+
+    domain_parts = message_parts_to_domain(body.parts)
+    user_msg = ConversationMessage(
+        id=str(uuid.uuid4()),
+        role=MessageRole.USER,
+        parts=domain_parts,
+    )
+    out = await chat.send_message(
+        cid,
+        user_msg,
+        store=store,
+        completion_params=body.generation,
+        client_ref=body.client_ref,
+    )
+    return PostMessageResponse(
+        message_id=out.get("message_id"),
+        task_id=out["task_id"],
+        conversation_id=out["conversation_id"],
+        stream_id=out["stream_id"],
+        client_ref=body.client_ref,
+    )
diff --git a/src/backend/app/api/v1/conversations/routes/conversation.py b/src/backend/app/api/v1/conversations/routes/conversation.py
new file mode 100644
index 00000000..ffc8ae4d
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/routes/conversation.py
@@ -0,0 +1,105 @@
+"""Conversation metadata HTTP API (Phase 4).
+
+TerminusDB @id values often contain `/` (e.g. ConversationSchema/uuid), which breaks
+path segments. Resource ids are passed as query parameters instead.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.agent.conversation_store import ConversationStore
+from app.api.v1.conversations.deps import get_conversation_store
+from app.api.v1.conversations.params import ConversationIdQuery
+from app.api.v1.conversations.schemas import (
+    ConversationMetaResponse,
+    CreateConversationRequest,
+    PaginatedItems,
+)
+
+router = APIRouter(prefix="/conversations", tags=["conversations"])
+
+
+@router.post("", status_code=status.HTTP_201_CREATED)
+async def create_conversation(
+    body: CreateConversationRequest,
+    store: ConversationStore = Depends(get_conversation_store),
+) -> ConversationMetaResponse:
+    cid = await store.create_conversation(body.title, body.description)
+    meta = await store.get_conversation_metadata(cid)
+    if meta is None:
+        raise HTTPException(
+            status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Conversation created but not readable",
+        )
+    return ConversationMetaResponse(
+        id=meta.id,
+        title=meta.title,
+        description=meta.description,
+        message_count=meta.message_count,
+        has_active_task=meta.has_active_task,
+        created_at=meta.created_at,
+        updated_at=meta.updated_at,
+        metadata={},
+    )
+
+
+@router.get("")
+async def list_conversations(
+    limit: int = Query(default=50, ge=1, le=200),
+    cursor: str | None = None,
+    store: ConversationStore = Depends(get_conversation_store),
+) -> PaginatedItems:
+    items = await store.list_conversations(limit=limit + 1, cursor=cursor)
+    has_more = len(items) > limit
+    page = items[:limit]
+    next_cursor = page[-1].id if has_more and page else None
+    return PaginatedItems(
+        items=[
+            ConversationMetaResponse(
+                id=s.id,
+                title=s.title,
+                description=s.description,
+                message_count=s.message_count,
+                has_active_task=s.has_active_task,
+                created_at=s.created_at,
+                updated_at=s.updated_at,
+                metadata={},
+            )
+            for s in page
+        ],
+        next_cursor=next_cursor,
+        has_more=has_more,
+    )
+
+
+@router.get("/meta")
+async def get_conversation(
+    conversation_id: ConversationIdQuery,
+    store: ConversationStore = Depends(get_conversation_store),
+) -> ConversationMetaResponse:
+    meta = await store.get_conversation_metadata(conversation_id)
+    if meta is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail="Not found")
+    full = await store.get_conversation(conversation_id)
+    md = full.metadata if full else {}
+    return ConversationMetaResponse(
+        id=meta.id,
+        title=meta.title,
+        description=meta.description,
+        message_count=meta.message_count,
+        has_active_task=meta.has_active_task,
+        created_at=meta.created_at,
+        updated_at=meta.updated_at,
+        metadata=md,
+    )
+
+
+@router.delete("")
+async def delete_conversation(
+    conversation_id: ConversationIdQuery,
+) -> None:
+    raise HTTPException(
+        status.HTTP_501_NOT_IMPLEMENTED,
+        detail="Not implemented for this storage backend",
+    )
diff --git a/src/backend/app/api/v1/conversations/routes/task.py b/src/backend/app/api/v1/conversations/routes/task.py
new file mode 100644
index 00000000..3f37b69d
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/routes/task.py
@@ -0,0 +1,106 @@
+"""Agent task and subtask HTTP API."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+
+from app.agent.conversation_store import ConversationStore
+from app.agent.runner.task_manager import TaskManager
+from app.api.v1.conversations.deps import (
+    get_conversation_repo,
+    get_conversation_store,
+    get_task_manager,
+)
+from app.api.v1.conversations.params import ConversationIdQuery, TaskIdQuery
+from app.api.v1.conversations.schemas import (
+    PaginatedItems,
+    subtask_to_wire,
+    task_to_wire,
+)
+from app.core.repository.conversation._common import task_document_lookup_ids
+
+router = APIRouter(prefix="/tasks", tags=["tasks"])
+
+conversation_tasks_router = APIRouter(prefix="/conversations", tags=["tasks"])
+
+
+@conversation_tasks_router.get("/tasks")
+async def list_conversation_tasks(
+    conversation_id: ConversationIdQuery,
+    cursor: int = Query(default=0, ge=0),
+    limit: int = Query(default=50, ge=1, le=200),
+    repo=Depends(get_conversation_repo),
+    store: ConversationStore = Depends(get_conversation_store),
+) -> PaginatedItems:
+    meta = await store.get_conversation_metadata(conversation_id)
+    if meta is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail="Not found")
+    tasks = await repo.list_tasks_for_conversation(
+        conversation_id, limit=limit + 1, cursor=cursor
+    )
+    has_more = len(tasks) > limit
+    page = tasks[:limit]
+    next_c = cursor + len(page) if has_more else None
+    return PaginatedItems(
+        items=[task_to_wire(t) for t in page],
+        next_cursor=next_c,
+        has_more=has_more,
+    )
+
+
+@router.get("/detail")
+async def get_task(
+    task_id: TaskIdQuery,
+    repo=Depends(get_conversation_repo),
+    tm: TaskManager = Depends(get_task_manager),
+):
+    t = await repo.get_task(task_id)
+    if t is not None:
+        return task_to_wire(t)
+    mem = tm.get_status(task_id)
+    if mem is not None:
+        return task_to_wire(mem)
+    raise HTTPException(status.HTTP_404_NOT_FOUND, detail="Not found")
+
+
+@router.get("/subtasks")
+async def list_subtasks(
+    task_id: TaskIdQuery,
+    cursor: int = Query(default=0, ge=0),
+    limit: int = Query(default=50, ge=1, le=200),
+    repo=Depends(get_conversation_repo),
+    tm: TaskManager = Depends(get_task_manager),
+) -> PaginatedItems:
+    t = await repo.get_task(task_id)
+    if t is None:
+        in_memory = any(
+            tm.get_status(cand) is not None
+            for cand in task_document_lookup_ids(task_id)
+        )
+        if not in_memory:
+            raise HTTPException(
+                status.HTTP_404_NOT_FOUND, detail="Task not found"
+            )
+        return PaginatedItems(items=[], next_cursor=None, has_more=False)
+    rows = await repo.get_subtasks(t.id, cursor=cursor, limit=limit + 1)
+    has_more = len(rows) > limit
+    page = rows[:limit]
+    next_c = page[-1].sequence + 1 if has_more and page else None
+    return PaginatedItems(
+        items=[subtask_to_wire(s) for s in page],
+        next_cursor=next_c,
+        has_more=has_more,
+    )
+
+
+@router.post("/cancel", status_code=status.HTTP_204_NO_CONTENT)
+async def cancel_task(
+    task_id: TaskIdQuery,
+    tm: TaskManager = Depends(get_task_manager),
+) -> Response:
+    if not tm.cancel(task_id):
+        raise HTTPException(
+            status.HTTP_404_NOT_FOUND,
+            detail="Task not running or unknown",
+        )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
diff --git a/src/backend/app/api/v1/conversations/routes/workflows.py b/src/backend/app/api/v1/conversations/routes/workflows.py
new file mode 100644
index 00000000..84b81f64
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/routes/workflows.py
@@ -0,0 +1,242 @@
+# app/api/v1/agent/workflows/router.py
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from app.agent.context.graph_traversal import GraphTraversal
+from app.agent.conversation_store import ConversationStore
+from app.agent.service.workflow_service import WorkflowService
+from app.agent.workflows.base import BaseWorkflow
+from app.agent.workflows.description_gen import (
+    DescriptionGeneratorWorkflow,
+)
+from app.agent.workflows.documentation_gen import (
+    DocumentationGeneratorWorkflow,
+)
+from app.api.dependencies import (
+    get_project_conversation_store,
+    get_workflow_service,
+)
+from app.api.v1.conversations.deps import get_graph_traversal
+
+router = APIRouter(
+    prefix="/workflows", tags=["Agent Workflows"]
+)
+
+_WORKFLOW_CLASSES: dict[str, Type[BaseWorkflow]] = {
+    "documentation_generator": DocumentationGeneratorWorkflow,
+    "description_generator": DescriptionGeneratorWorkflow,
+}
+
+
+class RunWorkflowRequest(BaseModel):
+    workflow_name: str
+    params: dict[str, Any]
+    conversation_id: Optional[str] = None
+    # Persisted on the Task row (display name / notes), not the conversation thread.
+    conversation_title: Optional[str] = None
+    conversation_description: Optional[str] = None
+
+
+class RunWorkflowResponse(BaseModel):
+    conversation_id: str
+    task_id: str
+    status: str
+
+
+class WorkflowBatchStep(BaseModel):
+    workflow_name: str
+    params: dict[str, Any]
+
+
+class RunWorkflowBatchRequest(BaseModel):
+    steps: list[WorkflowBatchStep]
+    conversation_id: Optional[str] = None
+    # Labels the batch parent Task; chat title/description are always LLM-generated.
+    conversation_title: Optional[str] = None
+    conversation_description: Optional[str] = None
+
+
+class RunWorkflowBatchResponse(BaseModel):
+    conversation_id: str
+    task_id: str  # single parent task
+    status: str
+
+
+@router.post(
+    "/run",
+    response_model=RunWorkflowResponse,
+    status_code=202,
+)
+async def run_workflow(
+    req: RunWorkflowRequest,
+    workflow_service: WorkflowService = Depends(get_workflow_service),
+    graph: GraphTraversal = Depends(get_graph_traversal),
+    store: ConversationStore = Depends(get_project_conversation_store),
+):
+    workflow_cls = _WORKFLOW_CLASSES.get(req.workflow_name)
+    if not workflow_cls:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown workflow: {req.workflow_name}",
+        )
+
+    workflow = workflow_cls(
+        graph=graph,
+        llm_factory=workflow_service.llm_factory,
+    )
+
+    try:
+        params = dict(req.params or {})
+        # Remove mode if present (legacy cleanup)
+        params.pop("mode", None)
+
+        if req.conversation_title is not None:
+            params["conversation_title"] = req.conversation_title
+        if req.conversation_description is not None:
+            params["conversation_description"] = req.conversation_description
+
+        conv_id, task_id = await workflow_service.run(
+            workflow,
+            store=store,
+            conversation_id=req.conversation_id,
+            **params,
+        )
+
+        return RunWorkflowResponse(
+            conversation_id=conv_id,
+            task_id=task_id,
+            status="accepted_and_running",
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    except Exception as e:
+        # logger.exception("Workflow run failed")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to start workflow: {e}",
+        ) from e
+
+
+@router.post(
+    "/run-batch",
+    response_model=RunWorkflowBatchResponse,
+    status_code=202,
+)
+async def run_workflow_batch(
+    req: RunWorkflowBatchRequest,
+    workflow_service: WorkflowService = Depends(get_workflow_service),
+    graph: GraphTraversal = Depends(get_graph_traversal),
+    store: ConversationStore = Depends(get_project_conversation_store),
+):
+    """
+    Run multiple workflows sequentially as a single background task.
+
+    Returns immediately (202 Accepted) with a task_id. The workflows
+    run in the background. Do NOT await completion here.
+    """
+    if not req.steps:
+        raise HTTPException(
+            status_code=400,
+            detail="steps must not be empty"
+        )
+
+    # Validate all workflow names upfront to fail fast
+    for step in req.steps:
+        if step.workflow_name not in _WORKFLOW_CLASSES:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Unknown workflow: {step.workflow_name}",
+            )
+
+    def _make_workflow(step: dict) -> BaseWorkflow:
+        """Factory function to instantiate workflows."""
+        cls = _WORKFLOW_CLASSES[step["workflow_name"]]
+        return cls(
+            graph=graph,
+            llm_factory=workflow_service.llm_factory,
+        )
+
+    try:
+        # Prepare steps with cleaned params
+        steps = []
+        for step in req.steps:
+            params = dict(step.params or {})
+            params.pop("mode", None)  # legacy cleanup
+            steps.append({
+                "workflow_name": step.workflow_name,
+                "params": params,
+            })
+
+        # Submit batch - returns immediately, runs in background
+        conv_id, task_id = await workflow_service.run_batch(
+            steps=steps,
+            workflow_factory=_make_workflow,
+            store=store,
+            conversation_id=req.conversation_id,
+            conversation_title=req.conversation_title,
+            conversation_description=req.conversation_description,
+        )
+
+        return RunWorkflowBatchResponse(
+            conversation_id=conv_id,
+            task_id=task_id,
+            status="accepted_and_running",
+        )
+
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    except Exception as e:
+        logger.exception("Batch workflow submission failed")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to start workflow batch: {e}",
+        ) from e
+
+
+# Optional: Endpoint to check batch progress or wait (for clients that want to poll)
+@router.get("/{task_id}/status")
+async def get_task_status(
+    task_id: str,
+    workflow_service: WorkflowService = Depends(get_workflow_service),
+):
+    """
+    Get current status of a workflow task including subtasks.
+    """
+    status = workflow_service.get_task_status(task_id)
+    if not status:
+        raise HTTPException(status_code=404, detail="Task not found")
+
+    return {
+        "task_id": status.id,
+        "state": status.state.value,
+        "progress": status.progress,
+        "progress_message": status.progress_message,
+        "sub_task_count": status.sub_task_count,
+        "started_at": status.started_at,
+        "finished_at": status.finished_at,
+        "error": status.error,
+    }
+
+
+@router.post("/{task_id}/cancel")
+async def cancel_task(
+    task_id: str,
+    workflow_service: WorkflowService = Depends(get_workflow_service),
+):
+    """
+    Cancel a running workflow task.
+    """
+    cancelled = workflow_service.cancel_task(task_id)
+    if not cancelled:
+        raise HTTPException(
+            status_code=400,
+            detail="Task not found or already completed"
+        )
+    return {"task_id": task_id, "status": "cancelled"}
diff --git a/src/backend/app/api/v1/conversations/schemas/__init__.py b/src/backend/app/api/v1/conversations/schemas/__init__.py
new file mode 100644
index 00000000..2d2c8114
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/schemas/__init__.py
@@ -0,0 +1,25 @@
+"""Conversation API DTOs (pagination, parts, requests, responses)."""
+
+from app.api.v1.conversations.schemas.pagination import PaginatedItems
+from app.api.v1.conversations.schemas.parts import MessagePartIn, TextPartIn
+from app.api.v1.conversations.schemas.requests import (
+    CreateConversationRequest,
+    SendConversationMessageRequest,
+)
+from app.api.v1.conversations.schemas.responses import (
+    ConversationMetaResponse,
+    PostMessageResponse,
+)
+from app.api.v1.conversations.schemas.tasks import subtask_to_wire, task_to_wire
+
+__all__ = [
+    "ConversationMetaResponse",
+    "CreateConversationRequest",
+    "MessagePartIn",
+    "PaginatedItems",
+    "PostMessageResponse",
+    "SendConversationMessageRequest",
+    "TextPartIn",
+    "subtask_to_wire",
+    "task_to_wire",
+]
diff --git a/src/backend/app/api/v1/conversations/schemas/pagination.py b/src/backend/app/api/v1/conversations/schemas/pagination.py
new file mode 100644
index 00000000..cd039c34
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/schemas/pagination.py
@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class PaginatedItems(BaseModel):
+    items: list[Any] = Field(default_factory=list)
+    next_cursor: str | int | None = None
+    has_more: bool = False
diff --git a/src/backend/app/api/v1/conversations/schemas/parts.py b/src/backend/app/api/v1/conversations/schemas/parts.py
new file mode 100644
index 00000000..4298ee2d
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/schemas/parts.py
@@ -0,0 +1,20 @@
+"""
+API message parts.
+
+Use a discriminated union when more than one `type` exists (see Pydantic docs).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class TextPartIn(BaseModel):
+    type: Literal["text"] = "text"
+    text: str = Field(..., min_length=1, max_length=1_000_000)
+
+
+# Alias so request models and OpenAPI stay stable when new part types ship.
+MessagePartIn = TextPartIn
diff --git a/src/backend/app/api/v1/conversations/schemas/requests.py b/src/backend/app/api/v1/conversations/schemas/requests.py
new file mode 100644
index 00000000..70ce4907
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/schemas/requests.py
@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from app.agent.chat.completion_params import ChatCompletionParams
+from app.api.v1.conversations.schemas.parts import TextPartIn
+
+
+class CreateConversationRequest(BaseModel):
+    title: str = Field(default="New conversation", min_length=1, max_length=200)
+    description: str = Field(default="", max_length=2000)
+
+
+class SendConversationMessageRequest(BaseModel):
+    """
+    Submit a user turn and schedule streamed assistant generation.
+
+    `conversation_id` is the full TerminusDB document id (may contain `/`);
+    clients should URL-encode it when passed as a query parameter elsewhere.
+    """
+
+    conversation_id: str = Field(
+        ...,
+        min_length=1,
+        max_length=512,
+        description="Full conversation document id, e.g. ConversationSchema/<uuid>",
+    )
+    role: Literal["user"] = "user"
+    parts: list[TextPartIn] = Field(
+        ...,
+        min_length=1,
+        max_length=64,
+        description="Ordered segments; schema uses `type` for forward-compatible unions.",
+    )
+    generation: ChatCompletionParams | None = Field(
+        default=None,
+        description="Optional per-request LLM overrides.",
+    )
+    client_ref: str | None = Field(
+        default=None,
+        max_length=128,
+        description="Optional idempotency or correlation key for the client.",
+    )
+    metadata: dict[str, Any] | None = Field(
+        default=None,
+        description="Opaque envelope; not interpreted by the runner today.",
+    )
diff --git a/src/backend/app/api/v1/conversations/schemas/responses.py b/src/backend/app/api/v1/conversations/schemas/responses.py
new file mode 100644
index 00000000..7b938c20
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/schemas/responses.py
@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class PostMessageResponse(BaseModel):
+    message_id: str | None
+    task_id: str
+    conversation_id: str
+    stream_id: str
+    client_ref: str | None = None
+
+
+class ConversationMetaResponse(BaseModel):
+    id: str
+    title: str
+    description: str
+    message_count: int
+    has_active_task: bool
+    created_at: datetime
+    updated_at: datetime
+    metadata: dict[str, Any] = Field(default_factory=dict)
diff --git a/src/backend/app/api/v1/conversations/schemas/tasks.py b/src/backend/app/api/v1/conversations/schemas/tasks.py
new file mode 100644
index 00000000..fcd86ee3
--- /dev/null
+++ b/src/backend/app/api/v1/conversations/schemas/tasks.py
@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def task_to_wire(t: Any) -> dict[str, Any]:
+    return t.model_dump(mode="json")
+
+
+def subtask_to_wire(st: Any) -> dict[str, Any]:
+    return st.model_dump(mode="json")
diff --git a/src/backend/app/api/v1/document_routes.py b/src/backend/app/api/v1/document_routes.py
index 1cef3979..8c359aaf 100644
--- a/src/backend/app/api/v1/document_routes.py
+++ b/src/backend/app/api/v1/document_routes.py
@@ -26,6 +26,7 @@ class UpdateDocumentRequest(BaseModel):
     name: Optional[str] = Field(None, min_length=1)
     description: Optional[str] = Field(None, min_length=1)
     data: Optional[str] = None
+    markdown: Optional[str] = None
 
 
 @router.post(
@@ -73,6 +74,8 @@ async def update_document(
         existing.description = request.description
     if request.data is not None:
         existing.data = request.data
+    if request.markdown is not None:
+        existing.markdown = request.markdown
 
     response = await document_service.update(existing)
 
@@ -131,8 +134,9 @@ async def get_documents_for_node(
             for compare_doc in compare_by_id.values():
                 merged_documents.append(
                     DocumentResponse(
-                        **compare_doc.model_dump(exclude={"data"}),
+                        **compare_doc.model_dump(exclude={"data", "markdown"}),
                         data="",
+                        markdown="",
                         status="removed",
                         compare_to=compare_doc,
                     )
diff --git a/src/backend/app/api/v1/play_ground_routes.py b/src/backend/app/api/v1/play_ground_routes.py
index ea8ca26e..3bd3deea 100644
--- a/src/backend/app/api/v1/play_ground_routes.py
+++ b/src/backend/app/api/v1/play_ground_routes.py
@@ -1,7 +1,7 @@
 from datetime import datetime
 from typing import Optional
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 from pydantic import BaseModel, Field
 
 from app.api.dependencies import get_play_ground_service
@@ -18,8 +18,6 @@ class PlayGroundResponse(BaseModel):
     relative_path: str
     code: str
     executable_path: Optional[str] = None
-    examples_path: Optional[str] = None
-    command_prefix: Optional[str] = None
     filename: Optional[str] = None
     owner_function: Optional[str] = None
     owner_class: Optional[str] = None
@@ -35,8 +33,6 @@ class CreatePlayGroundRequest(BaseModel):
     relative_path: str = Field(..., min_length=1)
     code: str = Field(..., min_length=1)
     executable_path: Optional[str] = None
-    examples_path: Optional[str] = None
-    command_prefix: Optional[str] = None
     filename: Optional[str] = None
     owner_function: Optional[str] = None
     owner_class: Optional[str] = None
@@ -50,8 +46,6 @@ class UpdatePlayGroundRequest(BaseModel):
     relative_path: Optional[str] = Field(default=None, min_length=1)
     code: Optional[str] = Field(default=None, min_length=1)
     executable_path: Optional[str] = None
-    examples_path: Optional[str] = None
-    command_prefix: Optional[str] = None
     filename: Optional[str] = None
 
 
@@ -82,8 +76,6 @@ def _to_response(raw: dict) -> PlayGroundResponse:
         relative_path=raw.get("relative_path", ""),
         code=raw.get("code", ""),
         executable_path=raw.get("executable_path"),
-        examples_path=raw.get("examples_path"),
-        command_prefix=raw.get("command_prefix"),
         filename=raw.get("filename"),
         owner_function=raw.get("owner_function"),
         owner_class=raw.get("owner_class"),
@@ -125,8 +117,6 @@ async def create_playground(
             relative_path=request.relative_path,
             code=request.code,
             executable_path=request.executable_path,
-            examples_path=request.examples_path,
-            command_prefix=request.command_prefix,
             filename=request.filename,
             owner_function=request.owner_function,
             owner_class=request.owner_class,
@@ -173,8 +163,6 @@ async def update_playground(
         and request.relative_path is None
         and request.code is None
         and request.executable_path is None
-        and request.examples_path is None
-        and request.command_prefix is None
         and request.filename is None
     ):
         raise HTTPException(
@@ -189,8 +177,6 @@ async def update_playground(
         relative_path=request.relative_path,
         code=request.code,
         executable_path=request.executable_path,
-        examples_path=request.examples_path,
-        command_prefix=request.command_prefix,
         filename=request.filename,
     )
     if not updated:
@@ -216,52 +202,20 @@ async def delete_playground(
 
 
 @router.get(
-    "/owners/function/{owner_function_id}",
+    "/owners",
     response_model=list[PlayGroundResponse],
 )
-async def get_playgrounds_by_owner_function_id(
-    owner_function_id: str,
+async def get_playgrounds_by_owner_node_id(
+    node_id: str = Query(..., min_length=1),
     play_ground_service: PlayGroundService = Depends(get_play_ground_service),
 ) -> list[PlayGroundResponse]:
-    items = await play_ground_service.get_by_owner_function_id(
-        owner_function_id
-    )
-    return [_to_response(item) for item in items]
-
-
-@router.get(
-    "/owners/class/{owner_class_id}",
-    response_model=list[PlayGroundResponse],
-)
-async def get_playgrounds_by_owner_class_id(
-    owner_class_id: str,
-    play_ground_service: PlayGroundService = Depends(get_play_ground_service),
-) -> list[PlayGroundResponse]:
-    items = await play_ground_service.get_by_owner_class_id(owner_class_id)
-    return [_to_response(item) for item in items]
-
-
-@router.get(
-    "/owners/file/{owner_file_id}",
-    response_model=list[PlayGroundResponse],
-)
-async def get_playgrounds_by_owner_file_id(
-    owner_file_id: str,
-    play_ground_service: PlayGroundService = Depends(get_play_ground_service),
-) -> list[PlayGroundResponse]:
-    items = await play_ground_service.get_by_owner_file_id(owner_file_id)
-    return [_to_response(item) for item in items]
-
-
-@router.get(
-    "/owners/folder/{owner_folder_id}",
-    response_model=list[PlayGroundResponse],
-)
-async def get_playgrounds_by_owner_folder_id(
-    owner_folder_id: str,
-    play_ground_service: PlayGroundService = Depends(get_play_ground_service),
-) -> list[PlayGroundResponse]:
-    items = await play_ground_service.get_by_owner_folder_id(owner_folder_id)
+    try:
+        items = await play_ground_service.get_by_owner_node_id(node_id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        ) from exc
     return [_to_response(item) for item in items]
 
 
diff --git a/src/backend/app/api/v1/project_routes.py b/src/backend/app/api/v1/project_routes.py
index 69d962b0..af8a223d 100644
--- a/src/backend/app/api/v1/project_routes.py
+++ b/src/backend/app/api/v1/project_routes.py
@@ -83,7 +83,7 @@ async def create_project(
         raise
 
     project_service.uow = uow
-    children = await project_service.get_children()
+    children, _ = await project_service.get_children()
 
     tree_builder = TreeBuilder(children)
     tree = tree_builder.build()
diff --git a/src/backend/app/config/settings.py b/src/backend/app/config/settings.py
index cf2a459a..bc60c4d5 100755
--- a/src/backend/app/config/settings.py
+++ b/src/backend/app/config/settings.py
@@ -5,7 +5,7 @@
 
 
 class Settings(BaseSettings):
-    APP_ENV: str
+    APP_ENV: str = "development"
 
     TERMINUS_HOST: str
     TERMINUS_USER: str
@@ -16,7 +16,7 @@ class Settings(BaseSettings):
     LOG_LEVEL: str = "INFO"
 
     model_config = SettingsConfigDict(
-        # Pydantic-Settings will automatically use the ENV_FILE env var if it exists.
+        # Pydantic-Settings will automatically use ENV_FILE when present.
         # Otherwise, it will fall back to ".env".
         env_file=os.environ.get("ENV_FILE", ".env"),
         env_file_encoding="utf-8",
@@ -38,7 +38,8 @@ def get_settings() -> Settings:
     """
     Returns a cached, singleton instance of the Settings.
     This function will only create the Settings object once.
-    It also ensures that the test environment variables are loaded if APP_ENV is set to 'test'.
+    It also ensures test environment variables are loaded
+    if APP_ENV is set to 'test'.
     """
     env_file = os.environ.get("ENV_FILE", ".env")
     if os.environ.get("APP_ENV") == "test":
diff --git a/src/backend/app/core/builder/tree_builder.py b/src/backend/app/core/builder/tree_builder.py
index 7c17f5ff..928662c2 100644
--- a/src/backend/app/core/builder/tree_builder.py
+++ b/src/backend/app/core/builder/tree_builder.py
@@ -1,3 +1,4 @@
+import logging
 from typing import Any, Dict, List, Optional, Set
 
 from pydantic import BaseModel
@@ -13,7 +14,10 @@
     ProjectTreeNode,
 )
 
-# Schema @type or Node class -> tree model (nodes have children as string IDs; tree nodes have nested objects)
+logger = logging.getLogger(__name__)
+
+# Schema @type or Node class -> tree model.
+# Nodes use children as string IDs; tree nodes use nested objects.
 SCHEMA_TO_TREE = {
     "ProjectSchema": ProjectTreeNode,
     "FolderSchema": FolderTreeNode,
@@ -220,7 +224,10 @@ def _inject_added_nodes(
         return list(merged.values())
 
     def _propagate_statuses(self, nodes_map: Dict[str, AnyTreeNode]) -> None:
-        """Bubble up changes: if child is added/removed/modified/moved, parent becomes modified."""
+        """
+        Bubble up changes:
+        if child is added/removed/modified/moved, parent becomes modified.
+        """
         changed_ids = {
             nid for nid, status in self.status_map.items()
             if status in ("added", "removed", "modified", "moved")
@@ -282,7 +289,10 @@ def build(self) -> List[AnyTreeNode]:
 
         return result
 
-    def _build_tree_from_dicts(self, node_dicts: List[Dict[str, Any]]) -> List[AnyTreeNode]:
+    def _build_tree_from_dicts(
+        self,
+        node_dicts: List[Dict[str, Any]],
+    ) -> List[AnyTreeNode]:
         """Build tree from prepared node dictionaries."""
         if not node_dicts:
             return []
diff --git a/src/backend/app/core/model/conversation_domain.py b/src/backend/app/core/model/conversation_domain.py
new file mode 100644
index 00000000..062cf502
--- /dev/null
+++ b/src/backend/app/core/model/conversation_domain.py
@@ -0,0 +1,115 @@
+"""Conversation UI/message models (parts, messages, aggregates)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from app.core.model.conversation_enums import MessageRole, TaskState
+from app.core.model.conversation_nodes import ConversationNode, SubTask
+
+
+class TextPart(BaseModel):
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ToolCallPart(BaseModel):
+    """Agent-side tool call record (not shown to user directly)."""
+    type: Literal["tool_call"] = "tool_call"
+    tool_name: str
+    tool_input: dict
+    tool_output: Optional[str] = None
+
+
+class EventPart(BaseModel):
+    """Replay event (mirrors frontend ReplayEvent)."""
+    type: Literal["event"] = "event"
+    at: int
+    event_type: str        # "wait" | "click" | "focus"
+    payload: dict = Field(default_factory=dict)
+
+
+class TaskPart(BaseModel):
+    """
+    Marker in the message timeline for a workflow run.
+
+    Persist a minimal row: ``task_id`` must match the Task document ``@id`` in
+    Terminus (e.g. ``TaskSchema/<uuid>``). Title, state, and progress are filled
+    when serving messages by loading the linked ``Task`` (see repository hydrate).
+    """
+
+    type: Literal["task"] = "task"
+    task_id: str
+    title: str = ""
+    description: str = ""
+    state: TaskState = TaskState.PENDING
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    started_at: Optional[datetime] = None
+    finished_at: Optional[datetime] = None
+    progress: float = 0.0
+    sub_tasks: list[SubTask] = Field(default_factory=list)
+    # Mirrors Task.sub_task_count when known; used when sub_tasks are not embedded.
+    sub_task_count: int = 0
+    touched_node_ids: list[str] = Field(default_factory=list)
+    workflow_name: Optional[str] = None
+    workflow_params: Optional[dict] = None
+
+
+MessagePart = Union[TextPart, ToolCallPart, EventPart, TaskPart]
+
+
+class ConversationMessage(BaseModel):
+    id: str
+    role: MessageRole
+    parts: list[MessagePart]
+    sequence: int = 0
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    token_count: Optional[int] = None
+    model: Optional[str] = None
+
+
+class ConversationSummary(BaseModel):
+    id: str
+    title: str
+    description: str = ""
+    created_at: datetime
+    updated_at: datetime
+    message_count: int = 0
+    has_active_task: bool = False
+
+    @classmethod
+    def from_conversation_node(
+        cls, node: ConversationNode
+    ) -> "ConversationSummary":
+        return cls(
+            id=node.id,
+            title=node.name,
+            description=node.description,
+            created_at=node.created_at,
+            updated_at=node.updated_at,
+            message_count=node.message_count,
+            has_active_task=node.has_active_task,
+        )
+
+
+class Conversation(ConversationSummary):
+    messages: list[ConversationMessage] = Field(default_factory=list)
+    metadata: dict = Field(default_factory=dict)
+
+    @classmethod
+    def from_conversation_node(
+        cls,
+        node: ConversationNode,
+        *,
+        messages: list[ConversationMessage],
+        metadata: dict,
+    ) -> "Conversation":
+        summary = ConversationSummary.from_conversation_node(node)
+        return cls(
+            **summary.model_dump(),
+            messages=messages,
+            metadata=metadata,
+        )
diff --git a/src/backend/app/core/model/conversation_enums.py b/src/backend/app/core/model/conversation_enums.py
new file mode 100644
index 00000000..4798c915
--- /dev/null
+++ b/src/backend/app/core/model/conversation_enums.py
@@ -0,0 +1,25 @@
+"""Enums shared by conversation, message, and task models."""
+
+from enum import Enum
+
+
+class MessageRole(str, Enum):
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+
+
+class SubTaskState(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class TaskState(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
diff --git a/src/backend/app/core/model/conversation_nodes.py b/src/backend/app/core/model/conversation_nodes.py
new file mode 100644
index 00000000..f53421cf
--- /dev/null
+++ b/src/backend/app/core/model/conversation_nodes.py
@@ -0,0 +1,206 @@
+"""Pydantic documents for agent data persisted in TerminusDB (single source types)."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import json
+
+from pydantic import BaseModel, Field, model_validator
+
+from app.core.model.conversation_enums import SubTaskState, TaskState
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _coerce_task_state(value: Any) -> TaskState:
+    if isinstance(value, TaskState):
+        return value
+    try:
+        return TaskState(str(value))
+    except ValueError:
+        return TaskState.PENDING
+
+
+def _coerce_subtask_state(value: Any) -> SubTaskState:
+    if isinstance(value, SubTaskState):
+        return value
+    try:
+        return SubTaskState(str(value))
+    except ValueError:
+        return SubTaskState.PENDING
+
+
+class ConversationNode(BaseModel):
+    id: str
+    name: str
+    description: str = ""
+    metadata_json: str = "{}"
+    message_count: int = 0
+    has_active_task: bool = False
+    created_at: datetime = Field(default_factory=_utc_now)
+    updated_at: datetime = Field(default_factory=_utc_now)
+
+    @staticmethod
+    def from_raw_dict(raw_dict: dict[str, Any]) -> "ConversationNode":
+        return ConversationNode(
+            id=raw_dict["@id"],
+            name=raw_dict["name"],
+            description=raw_dict.get("description") or "",
+            metadata_json=raw_dict.get("metadata_json") or "{}",
+            message_count=int(raw_dict.get("message_count") or 0),
+            has_active_task=_raw_bool(raw_dict.get("has_active_task")),
+            created_at=raw_dict["created_at"],
+            updated_at=raw_dict["updated_at"],
+        )
+
+
+class MessageNode(BaseModel):
+    id: str
+    conversation_id: str
+    role: str
+    parts_json: str
+    token_count: Optional[int] = None
+    model_name: Optional[str] = None
+    sequence: int = 0
+    created_at: datetime = Field(default_factory=_utc_now)
+    updated_at: datetime = Field(default_factory=_utc_now)
+
+    @staticmethod
+    def from_raw_dict(raw_dict: dict[str, Any]) -> "MessageNode":
+        conv = raw_dict.get("conversation")
+        conv_id = (
+            conv if isinstance(conv, str) else (conv or {}).get("@id", "")
+        )
+        return MessageNode(
+            id=raw_dict["@id"],
+            conversation_id=conv_id or "",
+            role=raw_dict["role"],
+            parts_json=raw_dict.get("parts_json") or "[]",
+            token_count=raw_dict.get("token_count"),
+            model_name=raw_dict.get("model_name"),
+            sequence=int(raw_dict.get("sequence") or 0),
+            created_at=raw_dict["created_at"],
+            updated_at=raw_dict["updated_at"],
+        )
+
+
+class TaskDocumentBase(BaseModel):
+    """Shared scalar fields for `Task` (persisted workflow run)."""
+
+    id: str = ""
+    name: str = ""
+    description: str = ""
+    conversation_id: str = ""
+    message_id: str = ""
+    progress: float = 0.0
+    progress_message: str = ""
+    workflow_name: Optional[str] = None
+    started_at: Optional[datetime] = None
+    finished_at: Optional[datetime] = None
+    error: Optional[str] = None
+    sub_task_count: int = 0
+    created_at: datetime = Field(default_factory=_utc_now)
+    updated_at: datetime = Field(default_factory=_utc_now)
+
+
+class Task(TaskDocumentBase):
+    state: TaskState = TaskState.PENDING
+    workflow_params_json: Optional[str] = None
+    result_json: Optional[str] = None
+
+    @staticmethod
+    def from_raw_dict(raw_dict: dict[str, Any]) -> "Task":
+        conv = raw_dict.get("conversation")
+        msg = raw_dict.get("message")
+        conv_id = (
+            conv if isinstance(conv, str) else (conv or {}).get("@id", "")
+        )
+        msg_id = msg if isinstance(msg, str) else (msg or {}).get("@id", "")
+        return Task(
+            id=raw_dict["@id"],
+            name=raw_dict["name"],
+            description=raw_dict.get("description") or "",
+            conversation_id=conv_id or "",
+            message_id=msg_id or "",
+            state=_coerce_task_state(raw_dict.get("state")),
+            progress=float(raw_dict.get("progress") or 0.0),
+            progress_message=raw_dict.get("progress_message") or "",
+            workflow_name=raw_dict.get("workflow_name"),
+            workflow_params_json=raw_dict.get("workflow_params_json"),
+            started_at=raw_dict.get("started_at"),
+            finished_at=raw_dict.get("finished_at"),
+            error=raw_dict.get("error"),
+            result_json=raw_dict.get("result_json"),
+            sub_task_count=int(raw_dict.get("sub_task_count") or 0),
+            created_at=raw_dict["created_at"],
+            updated_at=raw_dict["updated_at"],
+        )
+
+
+class SubTaskDocumentBase(BaseModel):
+    """Shared scalar fields for `SubTask` (workflow step under a task)."""
+
+    id: str = ""
+    name: str
+    description: str = ""
+    sequence: int = 0
+    started_at: Optional[datetime] = None
+    finished_at: Optional[datetime] = None
+    error: Optional[str] = None
+    created_at: datetime = Field(default_factory=_utc_now)
+    updated_at: datetime = Field(default_factory=_utc_now)
+
+
+class SubTask(SubTaskDocumentBase):
+    task_id: str = ""
+    state: SubTaskState = SubTaskState.PENDING
+    touched_node_ids_json: str = "[]"
+
+    @model_validator(mode="before")
+    @classmethod
+    def _legacy_touched_node_ids(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        if "touched_node_ids" in data:
+            data = dict(data)
+            data["touched_node_ids_json"] = json.dumps(
+                data.pop("touched_node_ids", [])
+            )
+        return data
+
+    @staticmethod
+    def from_raw_dict(raw_dict: dict[str, Any]) -> "SubTask":
+        parent = raw_dict.get("task")
+        task_id = (
+            parent
+            if isinstance(parent, str)
+            else (parent or {}).get("@id", "")
+        )
+        return SubTask(
+            id=raw_dict["@id"],
+            task_id=task_id or "",
+            name=raw_dict["name"],
+            description=raw_dict.get("description") or "",
+            state=_coerce_subtask_state(raw_dict.get("state")),
+            sequence=int(raw_dict.get("sequence") or 0),
+            started_at=raw_dict.get("started_at"),
+            finished_at=raw_dict.get("finished_at"),
+            error=raw_dict.get("error"),
+            touched_node_ids_json=(
+                raw_dict.get("touched_node_ids_json") or "[]"
+            ),
+            created_at=raw_dict["created_at"],
+            updated_at=raw_dict["updated_at"],
+        )
+
+
+def _raw_bool(value: Any) -> bool:
+    if value is True or value is False:
+        return value
+    if isinstance(value, str):
+        return value.lower() == "true"
+    return bool(value)
diff --git a/src/backend/app/core/model/nodes.py b/src/backend/app/core/model/nodes.py
index 208cba3a..b29f8d99 100644
--- a/src/backend/app/core/model/nodes.py
+++ b/src/backend/app/core/model/nodes.py
@@ -64,6 +64,10 @@ def from_raw_dict(raw_dict):
 
 class DocumentNode(BaseNode):
     data: str = Field(..., description="The data of the document.")
+    markdown: str = Field(
+        default="",
+        description="Markdown representation (e.g. for AI); may duplicate structured data until optimized.",
+    )
 
     @staticmethod
     def from_raw_dict(raw_dict):
@@ -71,6 +75,7 @@ def from_raw_dict(raw_dict):
         return DocumentNode(
             **base.model_dump(),
             data=raw_dict["data"],
+            markdown=raw_dict.get("markdown", "") or "",
         )
 
 
diff --git a/src/backend/app/core/model/schemas/__init__.py b/src/backend/app/core/model/schemas/__init__.py
index f73ac127..5230a819 100644
--- a/src/backend/app/core/model/schemas/__init__.py
+++ b/src/backend/app/core/model/schemas/__init__.py
@@ -22,6 +22,12 @@
     CodeContentSchema,
 )
 from .test_schema import TestConfigSchema, TestCaseSchema, TestLinkSchema
+from .conversation_schema import (
+    ConversationSchema,
+    MessageSchema,
+    TaskSchema,
+    SubTaskSchema,
+)
 
 __all__ = [
     "BaseSchema",
@@ -46,6 +52,10 @@
     "TestConfigSchema",
     "TestCaseSchema",
     "TestLinkSchema",
+    "ConversationSchema",
+    "MessageSchema",
+    "TaskSchema",
+    "SubTaskSchema",
 ]
 
 
@@ -88,6 +98,11 @@ async def ensure_schema(
     schema_obj.add_obj(TestCaseSchema.__name__, TestCaseSchema)
     schema_obj.add_obj(TestLinkSchema.__name__, TestLinkSchema)
 
+    schema_obj.add_obj(ConversationSchema.__name__, ConversationSchema)
+    schema_obj.add_obj(MessageSchema.__name__, MessageSchema)
+    schema_obj.add_obj(TaskSchema.__name__, TaskSchema)
+    schema_obj.add_obj(SubTaskSchema.__name__, SubTaskSchema)
+
     await schema_obj.commit(
         client,
         f"Initialize schema for {title}",
diff --git a/src/backend/app/core/model/schemas/code_element_schema.py b/src/backend/app/core/model/schemas/code_element_schema.py
index 08cbf8c8..a006e613 100644
--- a/src/backend/app/core/model/schemas/code_element_schema.py
+++ b/src/backend/app/core/model/schemas/code_element_schema.py
@@ -12,8 +12,6 @@ class PlayGroundSchema(BaseSchema):
     description: str
     relative_path: str
     executable_path: Optional[str] = None
-    examples_path: Optional[str] = None
-    command_prefix: Optional[str] = None
     filename: Optional[str] = None
     code: str
     owner_function: Optional[str] = None
diff --git a/src/backend/app/core/model/schemas/conversation_schema.py b/src/backend/app/core/model/schemas/conversation_schema.py
new file mode 100644
index 00000000..99d70aab
--- /dev/null
+++ b/src/backend/app/core/model/schemas/conversation_schema.py
@@ -0,0 +1,193 @@
+
+from datetime import datetime
+from typing import Optional
+
+from app.core.model.conversation_nodes import (
+    ConversationNode,
+    MessageNode,
+    SubTask,
+    Task,
+    _coerce_subtask_state,
+    _coerce_task_state,
+)
+from .base import BaseSchema, TerminusBase
+
+
+class ConversationSchema(BaseSchema):
+    """Root conversation document; messages point here via `conversation` edge."""
+
+    metadata_json: str
+    message_count: int
+    has_active_task: bool
+
+    @staticmethod
+    def from_pydantic(node: ConversationNode) -> "ConversationSchema":
+        return ConversationSchema(
+            _id=node.id,
+            name=node.name,
+            description=node.description,
+            metadata_json=node.metadata_json,
+            message_count=node.message_count,
+            has_active_task=node.has_active_task,
+            created_at=node.created_at,
+            updated_at=node.updated_at,
+        )
+
+    def to_pydantic(self) -> ConversationNode:
+        return ConversationNode(
+            id=self._id,
+            name=self.name,
+            description=self.description,
+            metadata_json=self.metadata_json or "{}",
+            message_count=int(self.message_count or 0),
+            has_active_task=bool(self.has_active_task),
+            created_at=self.created_at,
+            updated_at=self.updated_at,
+        )
+
+
+class MessageSchema(TerminusBase):
+    conversation: "ConversationSchema"
+    role: str
+    parts_json: str
+    token_count: Optional[int]
+    model_name: Optional[str]
+    sequence: int
+
+    @staticmethod
+    def from_pydantic(node: MessageNode) -> "MessageSchema":
+        return MessageSchema(
+            _id=node.id,
+            conversation=node.conversation_id,
+            role=node.role,
+            parts_json=node.parts_json,
+            token_count=node.token_count,
+            model_name=node.model_name,
+            sequence=node.sequence,
+            created_at=node.created_at,
+            updated_at=node.updated_at,
+        )
+
+    def to_pydantic(self) -> MessageNode:
+        conv = self.conversation
+        conv_id = conv if isinstance(conv, str) else getattr(conv, "_id", "")
+        return MessageNode(
+            id=self._id,
+            conversation_id=conv_id,
+            role=self.role,
+            parts_json=self.parts_json or "[]",
+            token_count=self.token_count,
+            model_name=self.model_name,
+            sequence=int(self.sequence or 0),
+            created_at=self.created_at,
+            updated_at=self.updated_at,
+        )
+
+
+class TaskSchema(BaseSchema):
+    conversation: Optional[ConversationSchema]
+    message: Optional[MessageSchema]
+    state: str
+    progress: float
+    progress_message: str
+    workflow_name: Optional[str]
+    workflow_params_json: Optional[str]
+    started_at: Optional[datetime]
+    finished_at: Optional[datetime]
+    error: Optional[str]
+    result_json: Optional[str]
+    sub_task_count: int
+
+    @staticmethod
+    def from_pydantic(node: Task) -> "TaskSchema":
+        return TaskSchema(
+            _id=node.id,
+            name=node.name,
+            description=node.description,
+            conversation=node.conversation_id,
+            message=f"MessageSchema/{node.message_id}" if node.message_id else None,
+            state=node.state.value,
+            progress=node.progress,
+            progress_message=node.progress_message,
+            workflow_name=node.workflow_name,
+            workflow_params_json=node.workflow_params_json,
+            started_at=node.started_at,
+            finished_at=node.finished_at,
+            error=node.error,
+            result_json=node.result_json,
+            sub_task_count=node.sub_task_count,
+            created_at=node.created_at,
+            updated_at=node.updated_at,
+        )
+
+    def to_pydantic(self) -> Task:
+        conv = self.conversation
+        msg = self.message
+        return Task(
+            id=self._id,
+            name=self.name,
+            description=self.description,
+            conversation_id=conv if isinstance(
+                conv, str) else getattr(conv, "_id", ""),
+            message_id=msg if isinstance(
+                msg, str) else getattr(msg, "_id", ""),
+            state=_coerce_task_state(self.state),
+            progress=float(self.progress or 0.0),
+            progress_message=self.progress_message or "",
+            workflow_name=self.workflow_name,
+            workflow_params_json=self.workflow_params_json,
+            started_at=self.started_at,
+            finished_at=self.finished_at,
+            error=self.error,
+            result_json=self.result_json,
+            sub_task_count=int(self.sub_task_count or 0),
+            created_at=self.created_at,
+            updated_at=self.updated_at,
+        )
+
+
+class SubTaskSchema(TerminusBase):
+    task: Optional[TaskSchema]
+    name: str
+    description: str
+    state: str
+    sequence: int
+    started_at: Optional[datetime]
+    finished_at: Optional[datetime]
+    error: Optional[str]
+    touched_node_ids_json: str
+
+    @staticmethod
+    def from_pydantic(node: SubTask) -> "SubTaskSchema":
+        return SubTaskSchema(
+            _id=node.id,
+            task=node.task_id,
+            name=node.name,
+            description=node.description,
+            state=node.state.value,
+            sequence=node.sequence,
+            started_at=node.started_at,
+            finished_at=node.finished_at,
+            error=node.error,
+            touched_node_ids_json=node.touched_node_ids_json,
+            created_at=node.created_at,
+            updated_at=node.updated_at,
+        )
+
+    def to_pydantic(self) -> SubTask:
+        parent = self.task
+        return SubTask(
+            id=self._id,
+            task_id=parent if isinstance(
+                parent, str) else getattr(parent, "_id", ""),
+            name=self.name,
+            description=self.description,
+            state=_coerce_subtask_state(self.state),
+            sequence=int(self.sequence or 0),
+            started_at=self.started_at,
+            finished_at=self.finished_at,
+            error=self.error,
+            touched_node_ids_json=self.touched_node_ids_json or "[]",
+            created_at=self.created_at,
+            updated_at=self.updated_at,
+        )
diff --git a/src/backend/app/core/model/schemas/metadata.py b/src/backend/app/core/model/schemas/metadata.py
index 4afa7c4c..d1d0d345 100644
--- a/src/backend/app/core/model/schemas/metadata.py
+++ b/src/backend/app/core/model/schemas/metadata.py
@@ -96,6 +96,7 @@ class DocumentSchema(DocumentTemplate):
     name: str
     description: str
     data: str
+    markdown: str
     created_at: datetime
     updated_at: datetime
 
@@ -106,6 +107,7 @@ def from_pydantic(document: DocumentNode):
             name=document.name,
             description=document.description,
             data=document.data,
+            markdown=document.markdown,
             created_at=document.created_at,
             updated_at=document.updated_at,
         )
@@ -116,6 +118,7 @@ def to_pydantic(self):
             name=self.name,
             description=self.description,
             data=self.data,
+            markdown=self.markdown,
             created_at=self.created_at,
             updated_at=self.updated_at,
         )
diff --git a/src/backend/app/core/repository/__init__.py b/src/backend/app/core/repository/__init__.py
index 83b320c2..87bed048 100644
--- a/src/backend/app/core/repository/__init__.py
+++ b/src/backend/app/core/repository/__init__.py
@@ -15,6 +15,7 @@
 from .code_elements.code_element_repo import CodeElementRepo
 from .code_elements.test_repo import TestRepo
 from .code_elements.play_ground_repo import PlayGroundRepo
+from .conversation import ConversationRepo
 
 
 class Repositories:
@@ -37,3 +38,4 @@ def __init__(self, client: AsyncClient):
         self.document_repo = DocumentRepo(client)
         self.test_repo = TestRepo(client)
         self.play_ground_repo = PlayGroundRepo(client)
+        self.conversation_repo = ConversationRepo(client)
diff --git a/src/backend/app/core/repository/code_elements/play_ground_repo.py b/src/backend/app/core/repository/code_elements/play_ground_repo.py
index bcc1229a..f01098f5 100644
--- a/src/backend/app/core/repository/code_elements/play_ground_repo.py
+++ b/src/backend/app/core/repository/code_elements/play_ground_repo.py
@@ -67,17 +67,3 @@ async def get_by_owner_field(
             return []
 
         return [row["playground_doc"] for row in result.get("bindings", [])]
-
-    async def get_by_owner_function_id(
-        self, owner_function_id: str
-    ) -> list[dict]:
-        return await self.get_by_owner_field("owner_function", owner_function_id)
-
-    async def get_by_owner_class_id(self, owner_class_id: str) -> list[dict]:
-        return await self.get_by_owner_field("owner_class", owner_class_id)
-
-    async def get_by_owner_file_id(self, owner_file_id: str) -> list[dict]:
-        return await self.get_by_owner_field("owner_file", owner_file_id)
-
-    async def get_by_owner_folder_id(self, owner_folder_id: str) -> list[dict]:
-        return await self.get_by_owner_field("owner_folder", owner_folder_id)
diff --git a/src/backend/app/core/repository/conversation/__init__.py b/src/backend/app/core/repository/conversation/__init__.py
new file mode 100644
index 00000000..c8075222
--- /dev/null
+++ b/src/backend/app/core/repository/conversation/__init__.py
@@ -0,0 +1,8 @@
+from ._common import terminus_doc_id_tail, terminus_ids_match
+from .repo import ConversationRepo
+
+__all__ = [
+    "ConversationRepo",
+    "terminus_doc_id_tail",
+    "terminus_ids_match",
+]
diff --git a/src/backend/app/core/repository/conversation/_common.py b/src/backend/app/core/repository/conversation/_common.py
new file mode 100644
index 00000000..161195b7
--- /dev/null
+++ b/src/backend/app/core/repository/conversation/_common.py
@@ -0,0 +1,86 @@
+"""Shared helpers and constants for conversation persistence."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from pydantic import TypeAdapter
+
+from app.core.model.conversation_domain import MessagePart
+from app.core.model.conversation_enums import TaskState
+
+MESSAGE_PARTS_ADAPTER = TypeAdapter(list[MessagePart])
+
+TERMINAL_TASK_STATES = frozenset(
+    {
+        TaskState.COMPLETED,
+        TaskState.FAILED,
+        TaskState.CANCELLED,
+    }
+)
+
+
+def new_doc_id(class_name: str) -> str:
+    return f"{class_name}/{uuid.uuid4()}"
+
+
+def terminus_doc_id_tail(doc_id: str) -> str:
+    """Segment after the last `/`, or the full string (bare ids, URLs)."""
+    s = (doc_id or "").strip()
+    if not s:
+        return s
+    return s.rsplit("/", 1)[-1]
+
+
+def task_document_lookup_ids(task_id: str) -> list[str]:
+    """
+    Terminus task document ids may be stored as `TaskSchema/<uuid>` while clients
+    sometimes pass a bare UUID. Return candidates to try with get_document / WOQL.
+    """
+    s = (task_id or "").strip()
+    if not s:
+        return []
+    out: list[str] = []
+    if "/" in s:
+        out.append(s)
+        tail = terminus_doc_id_tail(s)
+        prefixed = f"TaskSchema/{tail}" if tail else ""
+        if prefixed and prefixed not in out:
+            out.append(prefixed)
+    else:
+        out.append(f"TaskSchema/{s}")
+        out.append(s)
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for x in out:
+        if x not in seen:
+            seen.add(x)
+            ordered.append(x)
+    return ordered
+
+
+def terminus_ids_match(a: str, b: str) -> bool:
+    """
+    True if two Terminus document ids refer to the same document.
+
+    TerminusDB uses `ClassName/<uuid>` while in-memory code often holds
+    bare UUIDs; message parts and API payloads may use either form.
+    """
+    if a == b:
+        return True
+    if not a or not b:
+        return False
+    return terminus_doc_id_tail(a) == terminus_doc_id_tail(b)
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def parts_to_json(parts: list[MessagePart]) -> str:
+    return MESSAGE_PARTS_ADAPTER.dump_json(parts).decode("utf-8")
+
+
+def parts_from_json(parts_json: str) -> list[MessagePart]:
+    return MESSAGE_PARTS_ADAPTER.validate_json(parts_json.encode("utf-8"))
diff --git a/src/backend/app/core/repository/conversation/conversations.py b/src/backend/app/core/repository/conversation/conversations.py
new file mode 100644
index 00000000..cc5c6632
--- /dev/null
+++ b/src/backend/app/core/repository/conversation/conversations.py
@@ -0,0 +1,107 @@
+"""Conversation document CRUD and listing."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from app.core.model.conversation_domain import Conversation, ConversationSummary
+from app.core.model.conversation_nodes import ConversationNode
+from app.core.model.schemas.conversation_schema import ConversationSchema
+
+from ._common import new_doc_id, utcnow
+
+if TYPE_CHECKING:
+    from app.db.async_terminus_client import AsyncClient
+
+logger = logging.getLogger(__name__)
+
+
+class ConversationsMixin:
+    client: "AsyncClient"
+
+    async def create_conversation(
+        self,
+        title: str,
+        description: str = "",
+        metadata: dict | None = None,
+    ) -> str | None:
+        now = utcnow()
+        conv_id = new_doc_id("ConversationSchema")
+        node = ConversationNode(
+            id=conv_id,
+            name=title,
+            description=description,
+            metadata_json=json.dumps(metadata or {}),
+            message_count=0,
+            has_active_task=False,
+            created_at=now,
+            updated_at=now,
+        )
+        try:
+            await self.client.insert_document(
+                ConversationSchema.from_pydantic(node),
+                commit_msg=f"Creating conversation {title!r}",
+            )
+        except Exception:
+            logger.exception("TerminusDB insert_document failed for conversation")
+            return None
+        return conv_id
+
+    async def get_conversation(self, conversation_id: str) -> Conversation | None:
+        conv = await self._get_conversation_node(conversation_id)
+        if conv is None:
+            return None
+        messages = await self.get_messages(
+            conversation_id, cursor=0, limit=10_000
+        )
+        meta: dict[str, Any] = {}
+        try:
+            meta = json.loads(conv.metadata_json or "{}")
+        except json.JSONDecodeError:
+            meta = {}
+        return Conversation.from_conversation_node(
+            conv, messages=messages, metadata=meta
+        )
+
+    async def _get_conversation_node(
+        self, conversation_id: str
+    ) -> ConversationNode | None:
+        try:
+            raw = await self.client.get_document(conversation_id)
+        except Exception as exc:
+            print(exc)
+            return None
+        if not raw or "ConversationSchema" not in str(raw.get("@type", "")):
+            return None
+        return ConversationNode.from_raw_dict(raw)
+
+    async def list_conversations(
+        self,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> list[ConversationSummary]:
+        try:
+            items_raw = await self.client.get_all_documents(doc_type="ConversationSchema")
+        except Exception as exc:
+            print(exc)
+            return []
+        nodes = [ConversationNode.from_raw_dict(r) for r in items_raw]
+        nodes.sort(key=lambda n: n.updated_at, reverse=True)
+        if cursor:
+            idx = next((i for i, n in enumerate(nodes) if n.id == cursor), None)
+            if idx is not None:
+                nodes = nodes[idx + 1:]
+        cap = max(1, limit)
+        return [
+            ConversationSummary.from_conversation_node(n) for n in nodes[:cap]
+        ]
+
+    async def get_conversation_summary(
+        self, conversation_id: str
+    ) -> ConversationSummary | None:
+        conv = await self._get_conversation_node(conversation_id)
+        if conv is None:
+            return None
+        return ConversationSummary.from_conversation_node(conv)
diff --git a/src/backend/app/core/repository/conversation/messages.py b/src/backend/app/core/repository/conversation/messages.py
new file mode 100644
index 00000000..75527dd8
--- /dev/null
+++ b/src/backend/app/core/repository/conversation/messages.py
@@ -0,0 +1,228 @@
+"""Message documents: append and paginated read."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from app.core.model.conversation_domain import (
+    ConversationMessage,
+    TaskPart,
+)
+from app.core.model.conversation_enums import MessageRole
+from app.core.model.conversation_nodes import MessageNode
+from app.core.model.schemas.conversation_schema import (
+    ConversationSchema,
+    MessageSchema,
+)
+from app.db.async_terminus_client import WOQLQuery as WQ
+
+from ._common import (
+    new_doc_id,
+    parts_from_json,
+    parts_to_json,
+    terminus_ids_match,
+    utcnow,
+)
+
+if TYPE_CHECKING:
+    from app.db.async_terminus_client import AsyncClient
+
+
+class MessagesMixin:
+    client: "AsyncClient"
+
+    async def _hydrate_task_parts(
+        self, messages: list[ConversationMessage]
+    ) -> None:
+        """Merge Task document fields into ``TaskPart`` rows (ref-in-message pattern)."""
+        for mi, msg in enumerate(messages):
+            new_parts: list = []
+            changed = False
+            for p in msg.parts:
+                if isinstance(p, TaskPart):
+                    doc = await self.get_task(p.task_id)
+                    if doc is not None:
+                        desc = (
+                            (doc.progress_message or "").strip()
+                            or (doc.description or "").strip()
+                            or p.description
+                        )
+                        new_parts.append(
+                            p.model_copy(
+                                update={
+                                    "title": doc.name or p.title,
+                                    "description": desc,
+                                    "state": doc.state,
+                                    "progress": doc.progress,
+                                    "started_at": doc.started_at or p.started_at,
+                                    "finished_at": doc.finished_at or p.finished_at,
+                                    "sub_task_count": doc.sub_task_count,
+                                    "workflow_name": doc.workflow_name or p.workflow_name,
+                                }
+                            )
+                        )
+                        changed = True
+                    else:
+                        new_parts.append(p)
+                else:
+                    new_parts.append(p)
+            if changed:
+                messages[mi] = msg.model_copy(update={"parts": new_parts})
+
+    async def add_message(
+        self,
+        conversation_id: str,
+        message: ConversationMessage,
+    ) -> str | None:
+        conv = await self._get_conversation_node(conversation_id)
+        if conv is None:
+            return None
+        now = utcnow()
+        seq = conv.message_count
+        msg_id = message.id or new_doc_id("MessageSchema")
+        if isinstance(message.role, MessageRole):
+            role_val = message.role.value
+        else:
+            role_val = str(message.role)
+        msg_node = MessageNode(
+            id=msg_id,
+            conversation_id=conversation_id,
+            role=role_val,
+            parts_json=parts_to_json(message.parts),
+            token_count=message.token_count,
+            model_name=message.model,
+            sequence=seq,
+            created_at=message.created_at or now,
+            updated_at=now,
+        )
+        schmea = MessageSchema.from_pydantic(msg_node)
+        try:
+            await self.client.insert_document(
+                schmea,
+                commit_msg=f"Message in {conversation_id}",
+            )
+        except Exception as exc:
+            print(exc)
+            return None
+
+        conv.message_count = seq + 1
+        conv.updated_at = now
+        try:
+            await self.client.update_document(
+                ConversationSchema.from_pydantic(conv),
+                commit_msg=f"Bump message_count {conversation_id}",
+            )
+        except Exception as exc:
+            print(exc)
+            return None
+        return msg_id
+
+    async def get_messages(
+        self,
+        conversation_id: str,
+        cursor: int = 0,
+        limit: int = 50,
+    ) -> list[ConversationMessage]:
+        cursor = max(0, int(cursor))
+        cap = max(1, int(limit))
+        try:
+            filtered = WQ().woql_and(
+                WQ().triple("v:msg", "conversation", conversation_id),
+                WQ().triple("v:msg", "rdf:type", "@schema:MessageSchema"),
+                WQ().triple("v:msg", "sequence", "v:seq"),
+                WQ().greater("v:seq", WQ().literal(cursor - 1, "xsd:integer")),
+            )
+            ordered = WQ().order_by("v:seq", order="asc").limit(cap, filtered)
+            query = WQ().select("v:msg_doc").woql_and(
+                ordered,
+                WQ().read_document("v:msg", "v:msg_doc"),
+            )
+            result = await self.client.query(query)
+        except Exception as exc:
+            print(exc)
+            return []
+
+        out: list[ConversationMessage] = []
+        for row in result.get("bindings", []):
+            raw = row.get("msg_doc")
+            if not raw:
+                continue
+            node = MessageNode.from_raw_dict(raw)
+            parts = parts_from_json(node.parts_json)
+            out.append(
+                ConversationMessage(
+                    id=node.id,
+                    role=MessageRole(node.role),
+                    parts=parts,
+                    sequence=node.sequence,
+                    created_at=node.created_at,
+                    token_count=node.token_count,
+                    model=node.model_name,
+                )
+            )
+        await self._hydrate_task_parts(out)
+        return out
+
+    async def get_message(self, message_id: str) -> ConversationMessage | None:
+        try:
+            raw = await self.client.get_document(message_id)
+        except Exception as exc:
+            print(exc)
+            return None
+        if not raw or "MessageSchema" not in (raw.get("@type") or ""):
+            return None
+        node = MessageNode.from_raw_dict(raw)
+        parts = parts_from_json(node.parts_json)
+        msg = ConversationMessage(
+            id=node.id,
+            role=MessageRole(node.role),
+            parts=parts,
+            sequence=node.sequence,
+            created_at=node.created_at,
+            token_count=node.token_count,
+            model=node.model_name,
+        )
+        buf = [msg]
+        await self._hydrate_task_parts(buf)
+        return buf[0]
+
+    async def update_message(
+        self,
+        conversation_id: str,
+        message: ConversationMessage,
+    ) -> bool:
+        try:
+            raw = await self.client.get_document(message.id)
+        except Exception as exc:
+            print(exc)
+            return False
+        if not raw or "MessageSchema" not in str(raw.get("@type", "")):
+            return False
+        node = MessageNode.from_raw_dict(raw)
+        if not terminus_ids_match(node.conversation_id, conversation_id):
+            return False
+        now = utcnow()
+        if isinstance(message.role, MessageRole):
+            role_val = message.role.value
+        else:
+            role_val = str(message.role)
+        updated = MessageNode(
+            id=message.id,
+            conversation_id=conversation_id,
+            role=role_val,
+            parts_json=parts_to_json(message.parts),
+            token_count=message.token_count,
+            model_name=message.model,
+            sequence=node.sequence,
+            created_at=node.created_at,
+            updated_at=now,
+        )
+        try:
+            await self.client.update_document(
+                MessageSchema.from_pydantic(updated),
+                commit_msg=f"Update message {message.id}",
+            )
+        except Exception as exc:
+            print(exc)
+            return False
+        return True
diff --git a/src/backend/app/core/repository/conversation/repo.py b/src/backend/app/core/repository/conversation/repo.py
new file mode 100644
index 00000000..8b6f5d37
--- /dev/null
+++ b/src/backend/app/core/repository/conversation/repo.py
@@ -0,0 +1,22 @@
+"""Composed repository for conversations, messages, tasks, and subtasks."""
+
+from __future__ import annotations
+
+from app.db.async_terminus_client import AsyncClient
+
+from .conversations import ConversationsMixin
+from .messages import MessagesMixin
+from .subtasks import SubtasksMixin
+from .tasks import TasksMixin
+
+
+class ConversationRepo(
+    ConversationsMixin,
+    MessagesMixin,
+    TasksMixin,
+    SubtasksMixin,
+):
+    """TerminusDB: conversations, messages, tasks, and subtasks."""
+
+    def __init__(self, client: AsyncClient):
+        self.client = client
diff --git a/src/backend/app/core/repository/conversation/subtasks.py b/src/backend/app/core/repository/conversation/subtasks.py
new file mode 100644
index 00000000..b27dab4f
--- /dev/null
+++ b/src/backend/app/core/repository/conversation/subtasks.py
@@ -0,0 +1,139 @@
+"""SubTask documents under a task."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from app.core.model.conversation_nodes import SubTask, Task, _coerce_subtask_state
+from app.core.model.schemas.conversation_schema import (
+    SubTaskSchema,
+    TaskSchema,
+)
+from app.db.async_terminus_client import WOQLQuery as WQ
+
+from ._common import new_doc_id, utcnow
+
+if TYPE_CHECKING:
+    from app.db.async_terminus_client import AsyncClient
+
+
+class SubtasksMixin:
+    client: "AsyncClient"
+
+    async def append_subtask(
+        self, task_id: str, subtask: SubTask
+    ) -> str | None:
+        try:
+            task_raw = await self.client.get_document(task_id)
+        except Exception as exc:
+            print(exc)
+            return None
+        if not task_raw:
+            return None
+        task_node = Task.from_raw_dict(task_raw)
+        now = utcnow()
+        seq = task_node.sub_task_count
+        sub_id = subtask.id or new_doc_id("SubTaskSchema")
+        sub_node = subtask.model_copy(
+            update={
+                "id": sub_id,
+                "task_id": task_id,
+                "sequence": seq,
+                "created_at": now,
+                "updated_at": now,
+            }
+        )
+
+        try:
+            await self.client.insert_document(
+                SubTaskSchema.from_pydantic(sub_node),
+                commit_msg=f"Subtask on {task_id}",
+            )
+        except Exception as exc:
+            print(exc)
+            return None
+
+        task_node.sub_task_count = seq + 1
+        task_node.updated_at = now
+        try:
+            await self.client.update_document(
+                TaskSchema.from_pydantic(task_node),
+                commit_msg=f"Bump sub_task_count {task_id}",
+            )
+        except Exception as exc:
+            print(exc)
+            return None
+        return sub_id
+
+    async def update_subtask(self, subtask_id: str, **fields: Any) -> bool:
+        try:
+            raw = await self.client.get_document(subtask_id)
+        except Exception as exc:
+            print(exc)
+            return False
+        if not raw:
+            return False
+        node = SubTask.from_raw_dict(raw)
+
+        if "name" in fields:
+            node.name = fields["name"]
+        if "description" in fields:
+            node.description = fields["description"]
+        if "state" in fields:
+            node.state = _coerce_subtask_state(fields["state"])
+        if "sequence" in fields:
+            node.sequence = int(fields["sequence"])
+        if "started_at" in fields:
+            node.started_at = fields["started_at"]
+        if "finished_at" in fields:
+            node.finished_at = fields["finished_at"]
+        if "error" in fields:
+            node.error = fields["error"]
+        if "touched_node_ids" in fields:
+            node.touched_node_ids_json = json.dumps(fields["touched_node_ids"])
+
+        node.updated_at = utcnow()
+
+        try:
+            await self.client.update_document(
+                SubTaskSchema.from_pydantic(node),
+                commit_msg=f"Update subtask {subtask_id}",
+            )
+        except Exception as exc:
+            print(exc)
+            return False
+        return True
+
+    async def get_subtasks(
+        self,
+        task_id: str,
+        cursor: int = 0,
+        limit: int = 50,
+    ) -> list[SubTask]:
+        cursor = max(0, int(cursor))
+        cap = max(1, int(limit))
+        try:
+            filtered = WQ().woql_and(
+                WQ().triple("v:st", "task", task_id),
+                WQ().triple("v:st", "rdf:type", "@schema:SubTaskSchema"),
+                WQ().triple("v:st", "sequence", "v:seq"),
+                WQ().greater("v:seq", WQ().literal(cursor - 1, "xsd:integer")),
+            )
+            ordered = WQ().order_by("v:seq", order="asc").limit(cap, filtered)
+            query = WQ().select("v:st_doc").woql_and(
+                ordered,
+                WQ().read_document("v:st", "v:st_doc"),
+            )
+            result = await self.client.query(query)
+        except Exception as exc:
+            print(exc)
+            return []
+
+        out: list[SubTask] = []
+        for row in result.get("bindings", []):
+            raw = row.get("st_doc")
+            if not raw:
+                continue
+            out.append(SubTask.from_raw_dict(raw))
+        return out
diff --git a/src/backend/app/core/repository/conversation/tasks.py b/src/backend/app/core/repository/conversation/tasks.py
new file mode 100644
index 00000000..480c4415
--- /dev/null
+++ b/src/backend/app/core/repository/conversation/tasks.py
@@ -0,0 +1,224 @@
+"""Task documents and conversation active-task flag."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from app.core.model.conversation_enums import TaskState
+from app.core.model.conversation_nodes import Task, _coerce_task_state
+from app.core.model.schemas.conversation_schema import (
+    ConversationSchema,
+    TaskSchema,
+)
+from app.db.async_terminus_client import WOQLQuery as WQ
+
+from ._common import (
+    TERMINAL_TASK_STATES,
+    new_doc_id,
+    task_document_lookup_ids,
+    utcnow,
+)
+
+if TYPE_CHECKING:
+    from app.db.async_terminus_client import AsyncClient
+
+
+class TasksMixin:
+    client: "AsyncClient"
+
+    async def create_task(
+        self,
+        conversation_id: str,
+        message_id: str,
+        task: Task,
+    ) -> str | None:
+        conv = await self._get_conversation_node(conversation_id)
+        if conv is None:
+            return None
+        now = utcnow()
+        task_id = task.id or new_doc_id("TaskSchema")
+        node = task.model_copy(
+            update={
+                "id": task_id,
+                "conversation_id": conversation_id,
+                "message_id": message_id,
+                "created_at": task.created_at or now,
+                "updated_at": now,
+            }
+        )
+        try:
+            await self.client.insert_document(
+                TaskSchema.from_pydantic(node),
+                commit_msg=f"Task for conversation {conversation_id}",
+            )
+        except Exception as exc:
+            print(exc)
+            return None
+
+        conv.has_active_task = True
+        conv.updated_at = now
+        try:
+            await self.client.update_document(
+                ConversationSchema.from_pydantic(conv),
+                commit_msg=f"Mark active task {conversation_id}",
+            )
+        except Exception as exc:
+            print(exc)
+            return None
+        return task_id
+
+    async def update_task(self, task_id: str, **fields: Any) -> bool:
+        try:
+            raw = await self.client.get_document(task_id)
+        except Exception as exc:
+            print(exc)
+            return False
+        if not raw:
+            return False
+        node = Task.from_raw_dict(raw)
+        conv_id = node.conversation_id
+
+        if "name" in fields:
+            node.name = fields["name"]
+        if "description" in fields:
+            node.description = fields["description"]
+        if "state" in fields:
+            node.state = _coerce_task_state(fields["state"])
+        if "progress" in fields:
+            node.progress = float(fields["progress"])
+        if "progress_message" in fields:
+            node.progress_message = fields["progress_message"]
+        if "workflow_name" in fields:
+            node.workflow_name = fields["workflow_name"]
+        if "workflow_params" in fields:
+            wp = fields["workflow_params"]
+            node.workflow_params_json = (
+                json.dumps(wp) if wp is not None else None
+            )
+        if "started_at" in fields:
+            node.started_at = fields["started_at"]
+        if "finished_at" in fields:
+            node.finished_at = fields["finished_at"]
+        if "error" in fields:
+            node.error = fields["error"]
+        if "result" in fields:
+            r = fields["result"]
+            node.result_json = json.dumps(r) if r is not None else None
+        if "sub_task_count" in fields:
+            node.sub_task_count = int(fields["sub_task_count"])
+
+        node.updated_at = utcnow()
+
+        try:
+            await self.client.update_document(
+                TaskSchema.from_pydantic(node),
+                commit_msg=f"Update task {task_id}",
+            )
+        except Exception as exc:
+            print(exc)
+            return False
+
+        if node.state in TERMINAL_TASK_STATES and conv_id:
+            await self._maybe_clear_active_task(conv_id)
+        return True
+
+    async def _maybe_clear_active_task(self, conversation_id: str) -> None:
+        conv = await self._get_conversation_node(conversation_id)
+        if conv is None or not conv.has_active_task:
+            return
+        try:
+            open_tasks = await self._query_tasks_for_conversation(
+                conversation_id,
+                states=[
+                    TaskState.PENDING.value,
+                    TaskState.RUNNING.value,
+                ],
+            )
+        except Exception as exc:
+            print(exc)
+            return
+        if open_tasks:
+            return
+        conv.has_active_task = False
+        conv.updated_at = utcnow()
+        try:
+            await self.client.update_document(
+                ConversationSchema.from_pydantic(conv),
+                commit_msg=f"Clear active task flag {conversation_id}",
+            )
+        except Exception as exc:
+            print(exc)
+
+    async def _query_tasks_for_conversation(
+        self,
+        conversation_id: str,
+        states: list[str],
+    ) -> list[Task]:
+        if not states:
+            return []
+        query = (
+            WQ()
+            .select("v:task_doc")
+            .woql_and(
+                WQ().triple("v:task", "conversation", conversation_id),
+                WQ().triple("v:task", "rdf:type", "@schema:TaskSchema"),
+                WQ().triple("v:task", "state", "v:state"),
+                WQ().member("v:state", [WQ().string(s) for s in states]),
+                WQ().read_document("v:task", "v:task_doc"),
+            )
+        )
+        try:
+            result = await self.client.query(query)
+        except Exception as exc:
+            print(exc)
+            return []
+        out: list[Task] = []
+        for row in result.get("bindings", []):
+            raw = row.get("task_doc")
+            if raw:
+                out.append(Task.from_raw_dict(raw))
+        return out
+
+    async def get_task(self, task_id: str) -> Task | None:
+        for doc_id in task_document_lookup_ids(task_id):
+            try:
+                raw = await self.client.get_document(doc_id)
+            except Exception as exc:
+                print(exc)
+                continue
+            if raw:
+                return Task.from_raw_dict(raw)
+        return None
+
+    async def list_tasks_for_conversation(
+        self,
+        conversation_id: str,
+        *,
+        limit: int = 50,
+        cursor: int = 0,
+    ) -> list[Task]:
+        query = (
+            WQ()
+            .select("v:task_doc")
+            .woql_and(
+                WQ().triple("v:task", "conversation", conversation_id),
+                WQ().triple("v:task", "rdf:type", "@schema:TaskSchema"),
+                WQ().read_document("v:task", "v:task_doc"),
+            )
+        )
+        try:
+            result = await self.client.query(query)
+        except Exception as exc:
+            print(exc)
+            return []
+        out: list[Task] = []
+        for row in result.get("bindings", []):
+            raw = row.get("task_doc")
+            if raw:
+                out.append(Task.from_raw_dict(raw))
+        out.sort(key=lambda t: t.created_at, reverse=True)
+        cursor = max(0, int(cursor))
+        cap = max(1, int(limit))
+        slice_start = cursor
+        return out[slice_start : slice_start + cap]
diff --git a/src/backend/app/core/repository/project_repo.py b/src/backend/app/core/repository/project_repo.py
index c963e014..2d2461b1 100644
--- a/src/backend/app/core/repository/project_repo.py
+++ b/src/backend/app/core/repository/project_repo.py
@@ -158,7 +158,7 @@ async def get_children(self, exclude_types: list[str] = [], include_commit_id: b
             if include_commit_id:
                 return children, version
 
-            return children
+            return children, None
         except Exception as e:
             print(e)
-            return []
+            return [], None
diff --git a/src/backend/app/core/services/document_service.py b/src/backend/app/core/services/document_service.py
index f4109cd1..b9e455e2 100644
--- a/src/backend/app/core/services/document_service.py
+++ b/src/backend/app/core/services/document_service.py
@@ -41,6 +41,7 @@ async def create(self,
             name=name,
             description=description,
             data="",
+            markdown="",
         )
 
         created = await repos.document_repo.create_nodes(document, singular_name="document", plural_name="documents")
diff --git a/src/backend/app/core/services/play_ground_service.py b/src/backend/app/core/services/play_ground_service.py
index 40a8dcef..9d5bedd7 100644
--- a/src/backend/app/core/services/play_ground_service.py
+++ b/src/backend/app/core/services/play_ground_service.py
@@ -9,6 +9,13 @@
 
 
 class PlayGroundService:
+    OWNER_FIELD_BY_PREFIX = {
+        "FunctionSchema": "owner_function",
+        "ClassSchema": "owner_class",
+        "FileSchema": "owner_file",
+        "FolderSchema": "owner_folder",
+    }
+
     def __init__(self, uow: ProjectUoW):
         self.uow = uow
         self.repos = self.uow.get_project_repos()
@@ -35,8 +42,6 @@ async def create_playground(
         relative_path: str,
         code: str,
         executable_path: Optional[str] = None,
-        examples_path: Optional[str] = None,
-        command_prefix: Optional[str] = None,
         filename: Optional[str] = None,
         owner_function: Optional[str] = None,
         owner_class: Optional[str] = None,
@@ -62,8 +67,6 @@ async def create_playground(
             relative_path=relative_path,
             code=code,
             executable_path=executable_path,
-            examples_path=examples_path,
-            command_prefix=command_prefix,
             filename=filename,
             owner_function=owner_function,
             owner_class=owner_class,
@@ -88,8 +91,6 @@ async def update_playground(
         relative_path: Optional[str] = None,
         code: Optional[str] = None,
         executable_path: Optional[str] = None,
-        examples_path: Optional[str] = None,
-        command_prefix: Optional[str] = None,
         filename: Optional[str] = None,
     ) -> Optional[dict]:
         existing = await self.repos.play_ground_repo.get_by_id(playground_id)
@@ -110,12 +111,6 @@ async def update_playground(
             executable_path=existing.get("executable_path")
             if executable_path is None
             else executable_path,
-            examples_path=existing.get("examples_path")
-            if examples_path is None
-            else examples_path,
-            command_prefix=existing.get("command_prefix")
-            if command_prefix is None
-            else command_prefix,
             filename=existing.get("filename") if filename is None else filename,
             owner_function=existing.get("owner_function"),
             owner_class=existing.get("owner_class"),
@@ -132,17 +127,22 @@ async def update_playground(
     async def delete_playground(self, playground_id: str) -> bool:
         return await self.repos.play_ground_repo.delete(playground_id)
 
-    async def get_by_owner_function_id(self, owner_function_id: str) -> list[dict]:
-        return await self.repos.play_ground_repo.get_by_owner_function_id(owner_function_id)
-
-    async def get_by_owner_class_id(self, owner_class_id: str) -> list[dict]:
-        return await self.repos.play_ground_repo.get_by_owner_class_id(owner_class_id)
-
-    async def get_by_owner_file_id(self, owner_file_id: str) -> list[dict]:
-        return await self.repos.play_ground_repo.get_by_owner_file_id(owner_file_id)
+    @classmethod
+    def _owner_field_from_node_id(cls, node_id: str) -> str:
+        prefix = node_id.split("/", 1)[0]
+        owner_field = cls.OWNER_FIELD_BY_PREFIX.get(prefix)
+        if owner_field is None:
+            supported = ", ".join(sorted(cls.OWNER_FIELD_BY_PREFIX.keys()))
+            raise ValueError(
+                f"Unsupported node id prefix '{prefix}'. Supported prefixes: {supported}"
+            )
+        return owner_field
 
-    async def get_by_owner_folder_id(self, owner_folder_id: str) -> list[dict]:
-        return await self.repos.play_ground_repo.get_by_owner_folder_id(owner_folder_id)
+    async def get_by_owner_node_id(self, node_id: str) -> list[dict]:
+        owner_field = self._owner_field_from_node_id(node_id)
+        return await self.repos.play_ground_repo.get_by_owner_field(
+            owner_field, node_id
+        )
 
     async def run_code(self, playground_id: str) -> CodeResponse:
         playground = await self.repos.play_ground_repo.get_by_id(playground_id)
@@ -161,7 +161,5 @@ async def run_code(self, playground_id: str) -> CodeResponse:
             project_root_path=project_path,
             python_executable=playground.get("executable_path"),
             code=playground.get("code", ""),
-            examples_path=playground.get("examples_path"),
-            command_prefix=playground.get("command_prefix"),
             filename=playground.get("filename"),
         )
diff --git a/src/backend/app/core/socket/manager.py b/src/backend/app/core/socket/manager.py
index 79491343..2020fece 100644
--- a/src/backend/app/core/socket/manager.py
+++ b/src/backend/app/core/socket/manager.py
@@ -103,8 +103,13 @@ def __init__(self):
         # Prevent re-initialization
         if not hasattr(self, "initialized"):
             self.initialized = True
+            self._stream_registry = None
             self._setup_handlers()
 
+    def bind_stream_registry(self, registry) -> None:
+        """Process-wide stream buffers for `stream:resume` replay."""
+        self._stream_registry = registry
+
     def _setup_handlers(self):
         @self.server.event
         async def connect(sid, environ):
@@ -151,6 +156,69 @@ async def leave_project(sid, project_id: str):
             )
             await self.server.leave_room(sid, normalized_id)
 
+        @self.server.event
+        async def join_conversation(sid, conversation_id: str):
+            room = f"conv:{conversation_id}"
+            await self.server.enter_room(sid, room)
+            logger.info(
+                "Client %s... joined conversation room %s",
+                sid[:8],
+                conversation_id[:16],
+            )
+
+        @self.server.event
+        async def leave_conversation(sid, conversation_id: str):
+            room = f"conv:{conversation_id}"
+            await self.server.leave_room(sid, room)
+
+        @self.server.on("stream:resume")
+        async def stream_resume(sid, data):
+            await self._handle_stream_resume(sid, data)
+
+    async def _handle_stream_resume(self, sid, data: Any) -> None:
+        if not isinstance(data, dict):
+            await self.server.emit(
+                "stream:error",
+                {"stream_id": None, "error": "invalid_payload"},
+                to=sid,
+            )
+            return
+        stream_id = data.get("stream_id")
+        last_seq = data.get("last_seq", -1)
+        reg = self._stream_registry
+        if reg is None:
+            await self.server.emit(
+                "stream:error",
+                {"stream_id": stream_id, "error": "server_misconfigured"},
+                to=sid,
+            )
+            return
+        buf = reg.get(stream_id) if stream_id else None
+        if buf is None:
+            await self.server.emit(
+                "stream:error",
+                {"stream_id": stream_id, "error": "stream_expired"},
+                to=sid,
+            )
+            return
+        start = int(last_seq) + 1
+        for seq, delta in buf.get_chunks_since(start):
+            await self.server.emit(
+                "stream:chunk",
+                {"stream_id": stream_id, "seq": seq, "delta": delta},
+                to=sid,
+            )
+        if buf.is_finished and buf.message_id:
+            await self.server.emit(
+                "stream:end",
+                {
+                    "stream_id": stream_id,
+                    "message_id": buf.message_id,
+                    "total_seq": buf.next_seq,
+                },
+                to=sid,
+            )
+
     def _normalize_project_id(self, project_id: str) -> str:
         """Normalize project_id to key format (remove nodes/ prefix)."""
         # Extract key part if project_id has nodes/ prefix
diff --git a/src/backend/app/db/client.py b/src/backend/app/db/client.py
index f26f92e3..79e4443c 100755
--- a/src/backend/app/db/client.py
+++ b/src/backend/app/db/client.py
@@ -7,7 +7,16 @@
 
 from .async_terminus_client import AsyncClient
 from ..config.settings import get_settings
-from app.core.model.schemas import ProjectSchema, BaseSchema, TerminusBase, ThemeConfigSchema
+from app.core.model.schemas import (
+    BaseSchema,
+    ConversationSchema,
+    MessageSchema,
+    ProjectSchema,
+    SubTaskSchema,
+    TaskSchema,
+    TerminusBase,
+    ThemeConfigSchema,
+)
 from app.db.woqlschema import *
 
 _client: AsyncClient | None = None
@@ -23,6 +32,11 @@ async def migrate_base(client):
     schema_obj.add_obj(BaseSchema.__name__, BaseSchema)
     schema_obj.add_obj(ThemeConfigSchema.__name__, ThemeConfigSchema)
     schema_obj.add_obj(ProjectSchema.__name__, ProjectSchema)
+    # Hub DB includes conversation types for schema compatibility; live data uses project DBs.
+    schema_obj.add_obj(ConversationSchema.__name__, ConversationSchema)
+    schema_obj.add_obj(MessageSchema.__name__, MessageSchema)
+    schema_obj.add_obj(TaskSchema.__name__, TaskSchema)
+    schema_obj.add_obj(SubTaskSchema.__name__, SubTaskSchema)
     await schema_obj.commit(client, "Add ProjectSchema to schema", full_replace=True)
 
 
diff --git a/src/backend/app/main.py b/src/backend/app/main.py
index 5bf3f0c7..adbbd9db 100755
--- a/src/backend/app/main.py
+++ b/src/backend/app/main.py
@@ -4,6 +4,12 @@
 from fastapi.middleware.cors import CORSMiddleware
 
 from app.core.socket.manager import get_socket_manager
+from app.agent.config import settings as agent_settings
+from app.agent.runner.task_manager import TaskManager
+from app.agent.llm.factory import LLMFactory
+from app.agent.llm.providers.openai_provider import OpenAIProvider
+from app.agent.runner.stream_buffer import StreamRegistry
+from app.agent.streaming.manager import StreamManager
 
 from .api import root
 from .db.client import get_terminus_client, close_db_client
@@ -29,10 +35,27 @@ async def lifespan(app: FastAPI):
     watcher_service.set_event_loop(
         asyncio.get_running_loop()
     )
+
+    # 2. Initialize LLM Factory
+    llm_factory = LLMFactory(agent_settings)
+    if agent_settings.openai_api_key:
+        llm_factory.register_provider(
+            "openai",
+            OpenAIProvider,
+            api_key=agent_settings.openai_api_key,
+        )
+    task_manager = TaskManager()
+    stream_registry = StreamRegistry()
+    stream_manager = StreamManager(stream_registry)
+
+    app.state.llm_factory = llm_factory
+    app.state.task_manager = task_manager
+    app.state.stream_manager = stream_manager
     app.state.watcher_service = watcher_service
 
     # Init Socket Manager (creates the server instance)
-    _ = get_socket_manager()
+    socket_manager = get_socket_manager()
+    socket_manager.bind_stream_registry(stream_registry)
     print("🔌 Socket.IO server initialized and ready")
 
     yield
diff --git a/src/backend/docker-compose.yml b/src/backend/docker-compose.yml
index ff76b6f5..04799fa5 100755
--- a/src/backend/docker-compose.yml
+++ b/src/backend/docker-compose.yml
@@ -4,7 +4,6 @@ services:
   terminusdb:
     image: terminusdb/terminusdb-server:latest
     container_name: terminusdb-server
-    pull_policy: always
     ports:
       - "6363:6363"
     environment:
@@ -15,21 +14,21 @@ services:
     volumes:
       - terminusdb_storage:/app/terminusdb/storage
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:6363/ok"]
+      test: ["CMD", "curl", "-f", "http://localhost:6363/api/ok"]
       interval: 10s
       timeout: 5s
       retries: 5
 
   semantic_indexer:
-    image: terminusdb/vectorlink:latest
+    image: terminusdb/vectorlink
     container_name: terminusdb-semantic-indexer
     ports:
       - "8080:8080"
-    depends_on:
-      terminusdb:
-        condition: service_healthy
+    # depends_on:
+    #   terminusdb:
+    #     condition: service_healthy
     environment:
-      - TERMINUSDB_CONTENT_ENDPOINT=http://terminusdb:6363
+      - TERMINUSDB_CONTENT_ENDPOINT=http://terminusdb:6363/api/index
       - TERMINUSDB_USER_FORWARD_HEADER=X-User-Forward
       - OPENAI_KEY=${OPENAI_KEY}
     volumes:
diff --git a/src/backend/pyproject.toml b/src/backend/pyproject.toml
index 62c721c3..41b36cfd 100755
--- a/src/backend/pyproject.toml
+++ b/src/backend/pyproject.toml
@@ -32,6 +32,9 @@ dependencies = [
   "trio>=0.32.0",
   "python-slugify>=8.0.4",
   "coverage>=7.13.4",
+  "langgraph>=1.1.2",
+  "langchain>=1.2.12",
+  "langchain-openai>=1.1.11",
 ]
 
 [project.optional-dependencies]
diff --git a/src/backend/tests/e2e/conftest.py b/src/backend/tests/e2e/conftest.py
index 7f5fd01d..a8ea6164 100644
--- a/src/backend/tests/e2e/conftest.py
+++ b/src/backend/tests/e2e/conftest.py
@@ -8,6 +8,7 @@
 from app.db.client import get_terminus_client
 from app.core.services.project_service import ProjectService
 from app.db.async_terminus_client import AsyncClient as TerminusClient
+from app.db.context import ProjectUoW, RequestDbContext
 from app.core.parser.graph_builder.orchestrator import GraphBuilderOrchestrator
 
 
@@ -42,24 +43,26 @@ def sample_project_path(tmp_path):
 
 
 @pytest_asyncio.fixture
-async def built_sample_project(sample_project_path, create_repos, terminusdb_client):
+async def built_sample_project(sample_project_path, terminusdb_client):
     """Creates a project and runs GraphBuilder to populate structure (no API)."""
-    project_service = ProjectService(create_repos)
-    print(f"Creating sample project at: {create_repos.client.db}")
+    ctx = RequestDbContext()
+    project_uow = ProjectUoW(terminusdb_client, None, ctx)
+    project_service = ProjectService(project_uow)
+    print(f"Creating sample project at: {terminusdb_client.db}")
     project_node = await project_service.create(
         "sample_project",
         "A sample project for E2E tests",
         sample_project_path,
     )
 
-    clone_db = terminusdb_client.clone()
+    project_uow = ProjectUoW(terminusdb_client, project_node, ctx)
     orchestrator = GraphBuilderOrchestrator(
         project_node=project_node,
-        db=clone_db,
+        uow=project_uow,
         ignore_file_name=".gitignore",
     )
     await orchestrator.resync()
-    yield project_node, create_repos
+    yield project_node, project_uow
 
     await project_service.delete(project_node.id)
 
@@ -77,8 +80,10 @@ async def sample_project_node(empty_project_uow):
 
 
 @pytest_asyncio.fixture
-async def created_sample_project(create_repos):
-    project_service = ProjectService(create_repos)
+async def created_sample_project(terminusdb_client):
+    ctx = RequestDbContext()
+    project_uow = ProjectUoW(terminusdb_client, None, ctx)
+    project_service = ProjectService(project_uow)
     return await project_service.create(
         "sample_project",
         "A sample project for E2E tests",
diff --git a/src/backend/tests/unit/service/agent/conftest.py b/src/backend/tests/unit/service/agent/conftest.py
new file mode 100644
index 00000000..13905cf6
--- /dev/null
+++ b/src/backend/tests/unit/service/agent/conftest.py
@@ -0,0 +1,41 @@
+import pytest
+import shutil
+from pathlib import Path
+from app.db.context import RequestDbContext, ProjectUoW
+from app.core.services.project_service import ProjectService
+from app.core.parser.graph_builder.orchestrator import GraphBuilderOrchestrator
+import pytest_asyncio
+
+
+@pytest.fixture
+def sample_project_path(tmp_path):
+    """Returns the path to a temporary copy of the sample project directory for E2E tests."""
+    source_path = Path(__file__).parent / "sample_project"
+    project_path = tmp_path / "sample_project"
+    shutil.copytree(source_path, project_path)
+    return str(project_path)
+
+
+@pytest_asyncio.fixture
+async def built_sample_project(sample_project_path, terminusdb_client):
+    """Creates a project and runs GraphBuilder to populate structure (no API)."""
+    ctx = RequestDbContext()
+    project_uow = ProjectUoW(terminusdb_client, None, ctx)
+    project_service = ProjectService(project_uow)
+    print(f"Creating sample project at: {terminusdb_client.db}")
+    project_node = await project_service.create(
+        "sample_project",
+        "A sample project for E2E tests",
+        sample_project_path,
+    )
+
+    project_uow = ProjectUoW(terminusdb_client, project_node, ctx)
+    orchestrator = GraphBuilderOrchestrator(
+        project_node=project_node,
+        uow=project_uow,
+        ignore_file_name=".gitignore",
+    )
+    await orchestrator.resync()
+    yield project_node, project_uow
+
+    await project_service.delete(project_node.id)
diff --git a/src/backend/tests/unit/service/agent/sample_project/core/model/child.py b/src/backend/tests/unit/service/agent/sample_project/core/model/child.py
new file mode 100644
index 00000000..12165bf7
--- /dev/null
+++ b/src/backend/tests/unit/service/agent/sample_project/core/model/child.py
@@ -0,0 +1,8 @@
+from .parent import Parent
+
+class Child(Parent):
+    """ ID: e278aa7a-d358-4a4c-aa8e-d67668aefa96 """
+
+    def __init__(self, name: str):
+        """ ID: 709db811-a10e-441b-8159-dc8427f60cdd """
+        super().__init__(name)
\ No newline at end of file
diff --git a/src/backend/tests/unit/service/agent/sample_project/core/model/parent.py b/src/backend/tests/unit/service/agent/sample_project/core/model/parent.py
new file mode 100644
index 00000000..5b683a8c
--- /dev/null
+++ b/src/backend/tests/unit/service/agent/sample_project/core/model/parent.py
@@ -0,0 +1,10 @@
+class Parent:
+    """ ID: eafcb450-3ccf-4fd7-98e7-10c0abb7f429 """
+
+    def __init__(self, name: str):
+        """ ID: fbea723d-0b37-4320-82b7-f5086aafb9c8 """
+        self.name = name
+
+    def get_name(self):
+        """ ID: 86f5a508-7ccc-4009-b62a-6a3989800e93 """
+        return self.name
\ No newline at end of file
diff --git a/src/backend/tests/unit/service/agent/sample_project/core/utils/helper.py b/src/backend/tests/unit/service/agent/sample_project/core/utils/helper.py
new file mode 100644
index 00000000..7955e73e
--- /dev/null
+++ b/src/backend/tests/unit/service/agent/sample_project/core/utils/helper.py
@@ -0,0 +1,5 @@
+from ..model.child import Child
+
+def create_child():
+    """ ID: e9887730-19a8-45da-b40c-c63368d69571 """
+    return Child()
\ No newline at end of file
diff --git a/src/backend/tests/unit/service/agent/sample_project/main.py b/src/backend/tests/unit/service/agent/sample_project/main.py
new file mode 100644
index 00000000..3c860f50
--- /dev/null
+++ b/src/backend/tests/unit/service/agent/sample_project/main.py
@@ -0,0 +1,11 @@
+from .core.utils.helper import create_child
+
+
+def main():
+    """ ID: 64df7ee4-1a99-47ac-8134-0b1d6dffaef6 """
+    child = create_child()
+    print(child.get_name())
+
+
+if __name__ == '__main__':
+    main()
diff --git a/src/backend/tests/unit/service/agent/test_generation_workflows.py b/src/backend/tests/unit/service/agent/test_generation_workflows.py
new file mode 100644
index 00000000..be2977a3
--- /dev/null
+++ b/src/backend/tests/unit/service/agent/test_generation_workflows.py
@@ -0,0 +1,302 @@
+"""Integration tests for WorkflowService using the sample project graph and a fake LLM."""
+
+from __future__ import annotations
+
+import pytest
+
+from app.agent.context.graph_traversal import GraphTraversal
+from app.agent.conversation_store import TerminusConversationStore
+from app.agent.llm.gateway import LLMGateway
+from app.agent.runner.task_manager import TaskManager
+from app.agent.service.title_generator import TitleOutput
+from app.agent.service.workflow_service import WorkflowService
+from app.agent.workflows.description_gen import DescriptionGeneratorWorkflow
+from app.agent.workflows.documentation_gen import DocumentationGeneratorWorkflow
+from app.core.model.conversation_domain import TaskPart
+from app.core.model.conversation_enums import TaskState
+from app.core.repository.conversation import ConversationRepo
+from app.db.context import ProjectUoW, RequestDbContext
+
+
+# --- Fake LLM: workflow prompts (invoke) + title generator (structured output) ---
+
+
+class _FakeResponse:
+    def __init__(self, content: str):
+        self.content = content
+
+
+class _FakeStructuredRunnable:
+    """Feeds ``generate_conversation_title`` / ``generate_batch_conversation_title``."""
+
+    async def ainvoke(self, messages):
+        return TitleOutput(
+            title="Structured Test Chat Title",
+            description=(
+                "One sentence describing the structured test conversation."
+            ),
+        )
+
+
+class _FakeInnerLLM:
+    def with_structured_output(self, schema):
+        return _FakeStructuredRunnable()
+
+
+class _FakeLLMProvider:
+    def __init__(self) -> None:
+        self._llm = _FakeInnerLLM()
+
+    async def invoke(self, messages, **kwargs):
+        prompt = messages[-1].content if messages else ""
+        node_name = "unknown"
+        for line in prompt.splitlines():
+            if line.startswith("Node name: "):
+                node_name = line.replace("Node name: ", "").strip()
+                break
+
+        if "Task: documentation" in prompt:
+            return _FakeResponse(f"DOC::{node_name}")
+        return _FakeResponse(f"DESC::{node_name}")
+
+
+class FakeAgentLLMFactory:
+    """Matches ``LLMGateway.create_mini()`` and workflow ``llm_factory.create(...)``."""
+
+    def create(self, **kwargs):
+        return _FakeLLMProvider()
+
+
+def _doc_id_for_node(node_id: str) -> str:
+    safe = node_id.replace("/", "_").replace(":", "_")
+    return f"DocumentSchema/{safe}_workflow_documentation"
+
+
+async def _get_main_file_node(uow: ProjectUoW):
+    repos = uow.get_project_repos()
+    file_nodes = await repos.structure_repo.get_by_qnames(
+        ["sample_project.main"],
+        "FileSchema",
+    )
+    return file_nodes["sample_project.main"]
+
+
+def _workflow_params_for_main(main_node, **extra):
+    return {
+        "node_id": main_node.id,
+        "direction": "up",
+        "max_depth": 1,
+        **extra,
+    }
+
+
+@pytest.mark.asyncio
+async def test_workflow_service_run_description_workflow(
+    built_sample_project,
+    terminusdb_client,
+):
+    _, uow = built_sample_project
+    graph = GraphTraversal(uow)
+    llm_factory = FakeAgentLLMFactory()
+    gateway = LLMGateway(llm_factory)
+    workflow = DescriptionGeneratorWorkflow(
+        graph=graph,
+        llm_factory=llm_factory,
+    )
+    repo = ConversationRepo(terminusdb_client)
+    store = TerminusConversationStore(repo)
+    svc = WorkflowService(
+        TaskManager(),
+        gateway,
+        db_client=terminusdb_client,
+    )
+
+    main_node = await _get_main_file_node(uow)
+    conv_id, task_id = await svc.run(
+        workflow,
+        store=store,
+        **_workflow_params_for_main(main_node),
+    )
+    await svc.join_task(task_id)
+
+    meta = await store.get_conversation_metadata(conv_id)
+    assert meta is not None
+    assert meta.title == "Structured Test Chat Title"
+    assert "structured test conversation" in meta.description.lower()
+
+    conv = await store.get_conversation(conv_id)
+    assert conv is not None
+    task_parts = [
+        p
+        for m in conv.messages
+        for p in m.parts
+        if isinstance(p, TaskPart)
+    ]
+    assert len(task_parts) == 1
+    assert task_parts[0].task_id == task_id
+    assert task_id.startswith("TaskSchema/")
+
+    task_doc = await repo.get_task(task_id)
+    assert task_doc is not None
+    assert task_doc.state == TaskState.COMPLETED
+    assert task_doc.message_id
+    assert task_doc.name.startswith("workflow:")
+
+    sub_task = await repo.get_subtasks(task_id)
+
+    assert len(sub_task) == 2
+
+    repos = uow.get_project_repos()
+    raw_main = await repos.client.get_document(main_node.id)
+
+    assert raw_main["description"].startswith("DESC::")
+
+
+@pytest.mark.asyncio
+async def test_workflow_service_run_documentation_workflow(
+    built_sample_project,
+    terminusdb_client,
+):
+    _, uow = built_sample_project
+    graph = GraphTraversal(uow)
+    llm_factory = FakeAgentLLMFactory()
+    gateway = LLMGateway(llm_factory)
+    workflow = DocumentationGeneratorWorkflow(
+        graph=graph,
+        llm_factory=llm_factory,
+    )
+    repo = ConversationRepo(terminusdb_client)
+    store = TerminusConversationStore(repo)
+    svc = WorkflowService(
+        TaskManager(),
+        gateway,
+        db_client=terminusdb_client,
+    )
+
+    main_node = await _get_main_file_node(uow)
+    conv_id, task_id = await svc.run(
+        workflow,
+        store=store,
+        **_workflow_params_for_main(main_node),
+    )
+    await svc.join_task(task_id)
+
+    task_doc = await repo.get_task(task_id)
+    assert task_doc is not None
+    assert task_doc.state == TaskState.COMPLETED
+
+    repos = uow.get_project_repos()
+    raw_main = await repos.client.get_document(main_node.id)
+    expected_doc_id = _doc_id_for_node(main_node.id)
+    assert expected_doc_id in set(raw_main.get("documents", []))
+    generated = await repos.client.get_document(expected_doc_id)
+    assert generated["data"].startswith("DOC::")
+
+
+@pytest.mark.asyncio
+async def test_workflow_service_task_label_params_map_to_task_row(
+    built_sample_project,
+    terminusdb_client,
+):
+    _, uow = built_sample_project
+    graph = GraphTraversal(uow)
+    llm_factory = FakeAgentLLMFactory()
+    gateway = LLMGateway(llm_factory)
+    workflow = DescriptionGeneratorWorkflow(
+        graph=graph,
+        llm_factory=llm_factory,
+    )
+    repo = ConversationRepo(terminusdb_client)
+    store = TerminusConversationStore(repo)
+    svc = WorkflowService(
+        TaskManager(),
+        gateway,
+        db_client=terminusdb_client,
+    )
+
+    main_node = await _get_main_file_node(uow)
+    _, task_id = await svc.run(
+        workflow,
+        store=store,
+        conversation_title="Custom run label",
+        conversation_description="Notes for this workflow run",
+        **_workflow_params_for_main(main_node),
+    )
+    await svc.join_task(task_id)
+
+    task_doc = await repo.get_task(task_id)
+    assert task_doc is not None
+    assert task_doc.name == "Custom run label"
+    assert task_doc.description == "Notes for this workflow run"
+
+
+@pytest.mark.asyncio
+async def test_workflow_service_batch_description_then_documentation(
+    built_sample_project,
+    terminusdb_client,
+):
+    _, uow = built_sample_project
+    graph = GraphTraversal(uow)
+    llm_factory = FakeAgentLLMFactory()
+    gateway = LLMGateway(llm_factory)
+    main_node = await _get_main_file_node(uow)
+    base_params = _workflow_params_for_main(main_node)
+
+    def workflow_factory(step: dict):
+        name = step["workflow_name"]
+        if name == "description_generator":
+            return DescriptionGeneratorWorkflow(
+                graph=graph,
+                llm_factory=llm_factory,
+            )
+        if name == "documentation_generator":
+            return DocumentationGeneratorWorkflow(
+                graph=graph,
+                llm_factory=llm_factory,
+            )
+        raise AssertionError(f"unexpected workflow {name!r}")
+
+    repo = ConversationRepo(terminusdb_client)
+    store = TerminusConversationStore(repo)
+    svc = WorkflowService(
+        TaskManager(),
+        gateway,
+        db_client=terminusdb_client,
+    )
+
+    steps = [
+        {
+            "workflow_name": "description_generator",
+            "params": dict(base_params),
+        },
+        {
+            "workflow_name": "documentation_generator",
+            "params": dict(base_params),
+        },
+    ]
+
+    conv_id, task_id = await svc.run_batch(
+        steps,
+        workflow_factory=workflow_factory,
+        store=store,
+        conversation_title="Batch parent label",
+        conversation_description="Two-step batch test",
+    )
+    await svc.join_task(task_id)
+
+    meta = await store.get_conversation_metadata(conv_id)
+    assert meta is not None
+    assert meta.title == "Structured Test Chat Title"
+
+    task_doc = await repo.get_task(task_id)
+    assert task_doc is not None
+    assert task_doc.state == TaskState.COMPLETED
+    assert task_doc.name == "Batch parent label"
+    assert task_doc.description == "Two-step batch test"
+    assert task_doc.workflow_name == "batch"
+
+    repos = uow.get_project_repos()
+    raw_main = await repos.client.get_document(main_node.id)
+    assert raw_main["description"].startswith("DESC::")
+    expected_doc_id = _doc_id_for_node(main_node.id)
+    assert expected_doc_id in set(raw_main.get("documents", []))
diff --git a/src/backend/tree.json b/src/backend/tree.json
deleted file mode 100644
index 4995490b..00000000
--- a/src/backend/tree.json
+++ /dev/null
@@ -1 +0,0 @@
-[{"id": "FolderSchema/3d22733e-1c90-456b-ba1e-23b25e3773f1", "name": "examples", "description": "Folder examples", "created_at": "2026-03-02T13:26:09.779352Z", "updated_at": "2026-03-02T13:26:09.779353Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/examples", "qname": "sample_project2.examples", "children": [{"id": "FileSchema/54bc4038-6004-40fc-988c-3c863914e98d", "name": "__init__", "description": "File __init__", "created_at": "2026-03-02T13:26:09.907007Z", "updated_at": "2026-03-02T13:26:09.907007Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/examples/__init__.py", "qname": "sample_project2.examples.__init__", "documents": [], "theme_config": null, "hash": "80d9c527e809cc99728abc469c1cf6d2d34bdf579d7034002d3d30a141b31312", "children_by_type": {"class_children": [], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [], "node_type": "file"}], "documents": [], "children_by_type": {"folder_children": [], "file_children": ["FileSchema/54bc4038-6004-40fc-988c-3c863914e98d"], "structure_group": []}, "theme_config": null, "node_type": "folder"}, {"id": "FolderSchema/76e5c73d-e1bf-47b8-9d05-814dc171f10b", "name": "core", "description": "Folder core", "created_at": "2026-03-02T13:26:09.779106Z", "updated_at": "2026-03-02T13:26:09.779107Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core", "qname": "sample_project2.core", "children": [{"id": "FolderSchema/e14f9027-d43a-4701-aca9-442f61d5dc0d", "name": "utils", "description": "Folder utils", "created_at": "2026-03-02T13:26:09.779272Z", "updated_at": "2026-03-02T13:26:09.779272Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/utils", "qname": "sample_project2.core.utils", "children": [{"id": "FileSchema/8d48173b-d3c6-4264-9a45-a8bcabc8a17d", "name": "helper", "description": "File helper", "created_at": "2026-03-02T13:26:09.906969Z", "updated_at": "2026-03-02T13:26:09.906969Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/utils/helper.py", "qname": "sample_project2.core.utils.helper", "documents": [], "theme_config": null, "hash": "6fd86108098a2fc3d29460d8667fa7f9f24e0dfaebb881a700a1dbaaf9484091", "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/1a5b7f13-911d-450a-ad84-3ffe6b577edd", "FunctionSchema/6e445d46-a576-41e8-a8ee-223eadd6808b"], "code_element_group": [], "call_children": [], "call_group": []}, "children": [{"id": "FunctionSchema/1a5b7f13-911d-450a-ad84-3ffe6b577edd", "name": "create_child", "description": "Function create_child", "created_at": "2026-03-02T13:26:10.428977Z", "updated_at": "2026-03-02T13:26:10.428977Z", "qname": "sample_project2.core.utils.helper.create_child", "code_position": {"line_no": 9, "col_offset": 0, "end_line_no": 16, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [{"id": "CallSchema/2dee774d-27b7-404f-958f-18963182abb3", "name": "Child", "description": "call::model.child.Child", "created_at": "2026-03-02T13:26:12.529052Z", "updated_at": "2026-03-02T13:26:12.529101Z", "qname": "FunctionSchema/1a5b7f13-911d-450a-ad84-3ffe6b577edd::ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "target_function": "ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "children_by_type": {"call_children": ["CallSchema/c021ef6f-92ac-44a1-b4a3-bb76fce8a74d"], "call_group": []}, "children": [{"id": "CallSchema/c021ef6f-92ac-44a1-b4a3-bb76fce8a74d", "name": "__init__", "description": "call::model.child.Child.__init__", "created_at": "2026-03-02T13:26:12.529120Z", "updated_at": "2026-03-02T13:26:12.529120Z", "qname": "CallSchema/2dee774d-27b7-404f-958f-18963182abb3::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "name": "Child", "description": "Class Child", "created_at": "2026-03-02T13:26:10.443291Z", "updated_at": "2026-03-02T13:26:10.443291Z", "qname": "sample_project2.core.model.child.Child", "code_position": {"line_no": 6, "col_offset": 0, "end_line_no": 28, "end_col_offset": 0}, "documents": [], "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "FunctionSchema/2b10cd92-9cb3-40ed-828f-b446e99bfc90", "FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "FunctionSchema/fc638f7e-f2a8-4fbc-8ee8-037cbb8f35c2"], "code_element_group": []}, "children": [], "base_classes": ["sample_project2.core.model.parent.GrandParent", "sample_project2.core.model.child.Child", "sample_project2.core.model.parent.Uncle", "sample_project2.core.model.parent.Parent", "builtins.object"], "theme_config": null, "node_type": "function"}}], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/6e445d46-a576-41e8-a8ee-223eadd6808b", "name": "gg", "description": "Function gg", "created_at": "2026-03-02T13:26:10.428986Z", "updated_at": "2026-03-02T13:26:10.428986Z", "qname": "sample_project2.core.utils.helper.gg", "code_position": {"line_no": 18, "col_offset": 0, "end_line_no": 21, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}], "node_type": "file"}, {"id": "FolderSchema/058cc172-12ef-41c8-80b8-247ef2337813", "name": "__pycache__", "description": "Folder __pycache__", "created_at": "2026-03-02T13:26:09.779317Z", "updated_at": "2026-03-02T13:26:09.779317Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/utils/__pycache__", "qname": "sample_project2.core.utils.__pycache__", "children": [{"id": "FileSchema/10a1e587-1157-4b8f-b191-fbd1b50f14d6", "name": "__init__", "description": "File __init__", "created_at": "2026-03-02T13:26:09.906929Z", "updated_at": "2026-03-02T13:26:09.906929Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/utils/__pycache__/__init__.py", "qname": "sample_project2.core.utils.__pycache__.__init__", "documents": [], "theme_config": null, "hash": "ab7503b84b86a9f713beb5313850ca98b29b3be9cf8c8d0c361928de69ab76f2", "children_by_type": {"class_children": [], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [], "node_type": "file"}], "documents": [], "children_by_type": {"folder_children": [], "file_children": ["FileSchema/10a1e587-1157-4b8f-b191-fbd1b50f14d6"], "structure_group": []}, "theme_config": null, "node_type": "folder"}, {"id": "FileSchema/435e26f0-b71c-44f3-aa2b-79696098d670", "name": "__init__", "description": "File __init__", "created_at": "2026-03-02T13:26:09.906886Z", "updated_at": "2026-03-02T13:26:09.906887Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/utils/__init__.py", "qname": "sample_project2.core.utils.__init__", "documents": [], "theme_config": null, "hash": "1fddc5d2e9a38472a7742045cd7ee27f260c12692f29a48320f1ba0b39241f71", "children_by_type": {"class_children": [], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [], "node_type": "file"}], "documents": [], "children_by_type": {"folder_children": ["FolderSchema/058cc172-12ef-41c8-80b8-247ef2337813"], "file_children": ["FileSchema/8d48173b-d3c6-4264-9a45-a8bcabc8a17d", "FileSchema/435e26f0-b71c-44f3-aa2b-79696098d670"], "structure_group": []}, "theme_config": null, "node_type": "folder"}, {"id": "FileSchema/cbf0fded-9500-460a-9054-15124baebf48", "name": "__init__", "description": "File __init__", "created_at": "2026-03-02T13:26:09.906626Z", "updated_at": "2026-03-02T13:26:09.906626Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/__init__.py", "qname": "sample_project2.core.__init__", "documents": [], "theme_config": null, "hash": "6c509d059d23cdfdd2f3461bdba74025dd3e077b97fd61083fcc402ffa5be893", "children_by_type": {"class_children": [], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [], "node_type": "file"}, {"id": "FolderSchema/1ff2573f-25df-4952-8067-a5bd3544cb06", "name": "__pycache__", "description": "Folder __pycache__", "created_at": "2026-03-02T13:26:09.779151Z", "updated_at": "2026-03-02T13:26:09.779151Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/__pycache__", "qname": "sample_project2.core.__pycache__", "children": [{"id": "FileSchema/1760100c-b635-49c7-8617-9c2edceff84a", "name": "__init__", "description": "File __init__", "created_at": "2026-03-02T13:26:09.906672Z", "updated_at": "2026-03-02T13:26:09.906672Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/__pycache__/__init__.py", "qname": "sample_project2.core.__pycache__.__init__", "documents": [], "theme_config": null, "hash": "94f2066efc299954374d47b58983d7b5c20b34bb05730908df65444bd2c87e77", "children_by_type": {"class_children": [], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [], "node_type": "file"}], "documents": [], "children_by_type": {"folder_children": [], "file_children": ["FileSchema/1760100c-b635-49c7-8617-9c2edceff84a"], "structure_group": []}, "theme_config": null, "node_type": "folder"}, {"id": "FolderSchema/918c5c9e-e649-4866-aa7d-507947231cf6", "name": "model", "description": "Folder model", "created_at": "2026-03-02T13:26:09.779191Z", "updated_at": "2026-03-02T13:26:09.779192Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/model", "qname": "sample_project2.core.model", "children": [{"id": "FileSchema/a65973ab-fdae-448b-a241-eed927d0a84e", "name": "__init__", "description": "File __init__", "created_at": "2026-03-02T13:26:09.906716Z", "updated_at": "2026-03-02T13:26:09.906716Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/model/__init__.py", "qname": "sample_project2.core.model.__init__", "documents": [], "theme_config": null, "hash": "7676e96e7ac4f4cd04247c8a7d4b5d64deccd1ca9037d53dd1e4a1dc1305a3a6", "children_by_type": {"class_children": [], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [], "node_type": "file"}, {"id": "FolderSchema/01530536-7659-4cc0-92e7-c5a4dc7d9cf3", "name": "__pycache__", "description": "Folder __pycache__", "created_at": "2026-03-02T13:26:09.779234Z", "updated_at": "2026-03-02T13:26:09.779234Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/model/__pycache__", "qname": "sample_project2.core.model.__pycache__", "children": [{"id": "FileSchema/21159768-34c4-48a3-ad1b-a38b1805a0df", "name": "__init__", "description": "File __init__", "created_at": "2026-03-02T13:26:09.906763Z", "updated_at": "2026-03-02T13:26:09.906763Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/model/__pycache__/__init__.py", "qname": "sample_project2.core.model.__pycache__.__init__", "documents": [], "theme_config": null, "hash": "a1778df505e49d9619897713ed11c980f370c132ddb4668df26cc68829d22672", "children_by_type": {"class_children": [], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [], "node_type": "file"}], "documents": [], "children_by_type": {"folder_children": [], "file_children": ["FileSchema/21159768-34c4-48a3-ad1b-a38b1805a0df"], "structure_group": []}, "theme_config": null, "node_type": "folder"}, {"id": "FileSchema/4ea5dc9c-650e-4936-ace4-97d8dd11c1c6", "name": "parent", "description": "File parent", "created_at": "2026-03-02T13:26:09.906846Z", "updated_at": "2026-03-02T13:26:09.906847Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/model/parent.py", "qname": "sample_project2.core.model.parent", "documents": [], "theme_config": null, "hash": "c3a597a53d21e8aac2f963afa247e06925abecf1cb0f43644a496725347f5b87", "children_by_type": {"class_children": ["ClassSchema/e82dc2ba-b511-4096-91c2-c7f97f312c45", "ClassSchema/e61d4fc3-681d-4b64-9576-deb169ce1ba1", "ClassSchema/0aef4dcd-59eb-4b0a-82c1-dc3b71e55d22"], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [{"id": "ClassSchema/e82dc2ba-b511-4096-91c2-c7f97f312c45", "name": "Uncle", "description": "Class Uncle", "created_at": "2026-03-02T13:26:10.458623Z", "updated_at": "2026-03-02T13:26:10.458623Z", "qname": "sample_project2.core.model.parent.Uncle", "code_position": {"line_no": 24, "col_offset": 0, "end_line_no": 41, "end_col_offset": 0}, "documents": [], "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/2c33578a-b0ea-4c32-a707-ef8ee4be0fed", "FunctionSchema/6f0276d2-c919-4e74-9f0f-16b1c008ae28", "FunctionSchema/fab8038a-5741-42ce-8410-217dc4a1afc6"], "code_element_group": []}, "children": [{"id": "FunctionSchema/2c33578a-b0ea-4c32-a707-ef8ee4be0fed", "name": "run", "description": "Function run", "created_at": "2026-03-02T13:26:10.458639Z", "updated_at": "2026-03-02T13:26:10.458639Z", "qname": "sample_project2.core.model.parent.Uncle.run", "code_position": {"line_no": 38, "col_offset": 4, "end_line_no": 41, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/fab8038a-5741-42ce-8410-217dc4a1afc6", "name": "walk", "description": "Function walk", "created_at": "2026-03-02T13:26:10.458634Z", "updated_at": "2026-03-02T13:26:10.458634Z", "qname": "sample_project2.core.model.parent.Uncle.walk", "code_position": {"line_no": 33, "col_offset": 4, "end_line_no": 36, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/6f0276d2-c919-4e74-9f0f-16b1c008ae28", "name": "get_name", "description": "Function get_name", "created_at": "2026-03-02T13:26:10.458629Z", "updated_at": "2026-03-02T13:26:10.458629Z", "qname": "sample_project2.core.model.parent.Uncle.get_name", "code_position": {"line_no": 28, "col_offset": 4, "end_line_no": 31, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}], "base_classes": ["builtins.object", "sample_project2.core.model.parent.GrandParent", "sample_project2.core.model.parent.Uncle"], "theme_config": null, "node_type": "class"}, {"id": "ClassSchema/e61d4fc3-681d-4b64-9576-deb169ce1ba1", "name": "Parent", "description": "Class Parent", "created_at": "2026-03-02T13:26:10.458644Z", "updated_at": "2026-03-02T13:26:10.458644Z", "qname": "sample_project2.core.model.parent.Parent", "code_position": {"line_no": 43, "col_offset": 0, "end_line_no": 55, "end_col_offset": 0}, "documents": [], "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/a2755ca0-36f8-4766-a0f2-65578edeb4ba", "FunctionSchema/321fc4ad-2dab-43e1-80f6-349c0fbeee46"], "code_element_group": []}, "children": [{"id": "FunctionSchema/a2755ca0-36f8-4766-a0f2-65578edeb4ba", "name": "get_name", "description": "Function get_name", "created_at": "2026-03-02T13:26:10.458653Z", "updated_at": "2026-03-02T13:26:10.458653Z", "qname": "sample_project2.core.model.parent.Parent.get_name", "code_position": {"line_no": 52, "col_offset": 4, "end_line_no": 55, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/321fc4ad-2dab-43e1-80f6-349c0fbeee46", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.458648Z", "updated_at": "2026-03-02T13:26:10.458649Z", "qname": "sample_project2.core.model.parent.Parent.__init__", "code_position": {"line_no": 47, "col_offset": 4, "end_line_no": 50, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}], "base_classes": ["builtins.object", "sample_project2.core.model.parent.GrandParent", "sample_project2.core.model.parent.Parent"], "theme_config": null, "node_type": "class"}, {"id": "ClassSchema/0aef4dcd-59eb-4b0a-82c1-dc3b71e55d22", "name": "GrandParent", "description": "Class GrandParent", "created_at": "2026-03-02T13:26:10.458598Z", "updated_at": "2026-03-02T13:26:10.458599Z", "qname": "sample_project2.core.model.parent.GrandParent", "code_position": {"line_no": 5, "col_offset": 0, "end_line_no": 22, "end_col_offset": 0}, "documents": [], "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/f524bf69-3e1f-4d6d-906e-f8cdf912292b", "FunctionSchema/e3a37c00-22fd-490c-b94d-dd39e6d94859", "FunctionSchema/dfbbacc3-b91d-4e51-8e6c-72c6f9d93f66"], "code_element_group": []}, "children": [{"id": "FunctionSchema/f524bf69-3e1f-4d6d-906e-f8cdf912292b", "name": "get_name", "description": "Function get_name", "created_at": "2026-03-02T13:26:10.458605Z", "updated_at": "2026-03-02T13:26:10.458606Z", "qname": "sample_project2.core.model.parent.GrandParent.get_name", "code_position": {"line_no": 9, "col_offset": 4, "end_line_no": 12, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/e3a37c00-22fd-490c-b94d-dd39e6d94859", "name": "walk", "description": "Function walk", "created_at": "2026-03-02T13:26:10.458611Z", "updated_at": "2026-03-02T13:26:10.458612Z", "qname": "sample_project2.core.model.parent.GrandParent.walk", "code_position": {"line_no": 14, "col_offset": 4, "end_line_no": 17, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/dfbbacc3-b91d-4e51-8e6c-72c6f9d93f66", "name": "sleep", "description": "Function sleep", "created_at": "2026-03-02T13:26:10.458617Z", "updated_at": "2026-03-02T13:26:10.458617Z", "qname": "sample_project2.core.model.parent.GrandParent.sleep", "code_position": {"line_no": 19, "col_offset": 4, "end_line_no": 22, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}], "base_classes": ["builtins.object", "sample_project2.core.model.parent.GrandParent"], "theme_config": null, "node_type": "class"}], "node_type": "file"}, {"id": "FileSchema/e1f8d40d-0e99-45e4-ad7d-5d9140215da0", "name": "child", "description": "File child", "created_at": "2026-03-02T13:26:09.906805Z", "updated_at": "2026-03-02T13:26:09.906806Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/core/model/child.py", "qname": "sample_project2.core.model.child", "documents": [], "theme_config": null, "hash": "64ec72e2ee88770c87ff55c2ac475e3bc5b15a56a31c99051be701567d0e5ad2", "children_by_type": {"class_children": ["ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0"], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [{"id": "ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "name": "Child", "description": "Class Child", "created_at": "2026-03-02T13:26:10.443291Z", "updated_at": "2026-03-02T13:26:10.443291Z", "qname": "sample_project2.core.model.child.Child", "code_position": {"line_no": 6, "col_offset": 0, "end_line_no": 28, "end_col_offset": 0}, "documents": [], "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "FunctionSchema/2b10cd92-9cb3-40ed-828f-b446e99bfc90", "FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "FunctionSchema/fc638f7e-f2a8-4fbc-8ee8-037cbb8f35c2"], "code_element_group": []}, "children": [{"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [{"id": "CallSchema/5e424edb-664d-486e-93ff-676d16d52682", "name": "__init__", "description": "call::parent.Parent.__init__", "created_at": "2026-03-02T13:26:12.530042Z", "updated_at": "2026-03-02T13:26:12.530042Z", "qname": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326::FunctionSchema/321fc4ad-2dab-43e1-80f6-349c0fbeee46", "target_function": "FunctionSchema/321fc4ad-2dab-43e1-80f6-349c0fbeee46", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/321fc4ad-2dab-43e1-80f6-349c0fbeee46", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.458648Z", "updated_at": "2026-03-02T13:26:10.458649Z", "qname": "sample_project2.core.model.parent.Parent.__init__", "code_position": {"line_no": 47, "col_offset": 4, "end_line_no": 50, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/2b10cd92-9cb3-40ed-828f-b446e99bfc90", "name": "set_name", "description": "Function set_name", "created_at": "2026-03-02T13:26:10.443308Z", "updated_at": "2026-03-02T13:26:10.443309Z", "qname": "sample_project2.core.model.child.Child.set_name", "code_position": {"line_no": 21, "col_offset": 4, "end_line_no": 24, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "name": "get_name", "description": "Function get_name", "created_at": "2026-03-02T13:26:10.443304Z", "updated_at": "2026-03-02T13:26:10.443304Z", "qname": "sample_project2.core.model.child.Child.get_name", "code_position": {"line_no": 16, "col_offset": 4, "end_line_no": 19, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/fc638f7e-f2a8-4fbc-8ee8-037cbb8f35c2", "name": "fly", "description": "Function fly", "created_at": "2026-03-02T13:26:10.443313Z", "updated_at": "2026-03-02T13:26:10.443314Z", "qname": "sample_project2.core.model.child.Child.fly", "code_position": {"line_no": 25, "col_offset": 4, "end_line_no": 28, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}], "base_classes": ["sample_project2.core.model.parent.GrandParent", "sample_project2.core.model.child.Child", "sample_project2.core.model.parent.Uncle", "sample_project2.core.model.parent.Parent", "builtins.object"], "theme_config": null, "node_type": "class"}], "node_type": "file"}], "documents": [], "children_by_type": {"folder_children": ["FolderSchema/01530536-7659-4cc0-92e7-c5a4dc7d9cf3"], "file_children": ["FileSchema/4ea5dc9c-650e-4936-ace4-97d8dd11c1c6", "FileSchema/a65973ab-fdae-448b-a241-eed927d0a84e", "FileSchema/e1f8d40d-0e99-45e4-ad7d-5d9140215da0"], "structure_group": []}, "theme_config": null, "node_type": "folder"}], "documents": [], "children_by_type": {"folder_children": ["FolderSchema/e14f9027-d43a-4701-aca9-442f61d5dc0d", "FolderSchema/1ff2573f-25df-4952-8067-a5bd3544cb06", "FolderSchema/918c5c9e-e649-4866-aa7d-507947231cf6"], "file_children": ["FileSchema/cbf0fded-9500-460a-9054-15124baebf48"], "structure_group": []}, "theme_config": null, "node_type": "folder"}, {"id": "FolderSchema/f82bc8a6-37d5-426c-9113-b93b7d35d60b", "name": "__pycache__", "description": "Folder __pycache__", "created_at": "2026-03-02T13:26:09.779050Z", "updated_at": "2026-03-02T13:26:09.779054Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/__pycache__", "qname": "sample_project2.__pycache__", "children": [{"id": "FileSchema/e45bcf03-780a-4fa9-8f27-a8f47649f8f8", "name": "__init__", "description": "File __init__", "created_at": "2026-03-02T13:26:09.906580Z", "updated_at": "2026-03-02T13:26:09.906581Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/__pycache__/__init__.py", "qname": "sample_project2.__pycache__.__init__", "documents": [], "theme_config": null, "hash": "b172fe08b6a8f13192e597ae8a330cad4c64894da282e026521b71a5268ff8df", "children_by_type": {"class_children": [], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [], "node_type": "file"}], "documents": [], "children_by_type": {"folder_children": [], "file_children": ["FileSchema/e45bcf03-780a-4fa9-8f27-a8f47649f8f8"], "structure_group": []}, "theme_config": null, "node_type": "folder"}, {"id": "FileSchema/372f9c6e-7ea2-44ed-9678-b56a0ca8c3f1", "name": "main", "description": "File main", "created_at": "2026-03-02T13:26:09.907105Z", "updated_at": "2026-03-02T13:48:03.774381Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/main.py", "qname": "sample_project2.main", "documents": [], "theme_config": null, "hash": "6427c103950b47425509a6866acce7a74b06d3943886614004d65a9e19413f95", "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/08a9a5f5-aa69-4a67-bf4a-e10800e80e31", "FunctionSchema/11b1c19e-faa5-44f1-836a-c1ef80d43c87", "FunctionSchema/fb04a14a-2746-4212-8bdd-cb70779c416c"], "code_element_group": [], "call_children": ["CallSchema/921155ba-86ca-43f9-95e4-489f233dac16", "CallSchema/65834d2b-1f81-4c13-85e0-5f4416baba36"], "call_group": []}, "children": [{"id": "FunctionSchema/fb04a14a-2746-4212-8bdd-cb70779c416c", "name": "runner", "description": "Function runner", "created_at": "2026-03-02T13:26:10.466360Z", "updated_at": "2026-03-02T13:26:10.466360Z", "qname": "sample_project2.main.runner", "code_position": {"line_no": 16, "col_offset": 0, "end_line_no": 20, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "CallSchema/921155ba-86ca-43f9-95e4-489f233dac16", "name": "main", "description": "call::main.main", "created_at": "2026-03-02T13:26:12.529728Z", "updated_at": "2026-03-02T13:26:12.529729Z", "qname": "FileSchema/372f9c6e-7ea2-44ed-9678-b56a0ca8c3f1::FunctionSchema/11b1c19e-faa5-44f1-836a-c1ef80d43c87", "target_function": "FunctionSchema/11b1c19e-faa5-44f1-836a-c1ef80d43c87", "children_by_type": {"call_children": ["CallSchema/186ae128-9a0d-4312-9e32-c9410750a2f2", "CallSchema/5ec80657-2dc9-47ae-b4c6-fa65074992cb"], "call_group": []}, "children": [{"id": "CallSchema/186ae128-9a0d-4312-9e32-c9410750a2f2", "name": "create_child", "description": "call::core.utils.helper.create_child", "created_at": "2026-03-02T13:26:12.529748Z", "updated_at": "2026-03-02T13:26:12.529748Z", "qname": "CallSchema/921155ba-86ca-43f9-95e4-489f233dac16::FunctionSchema/1a5b7f13-911d-450a-ad84-3ffe6b577edd", "target_function": "FunctionSchema/1a5b7f13-911d-450a-ad84-3ffe6b577edd", "children_by_type": {"call_children": ["CallSchema/c216e1f6-e207-47be-a8c7-ac9ccbf52d89"], "call_group": []}, "children": [{"id": "CallSchema/c216e1f6-e207-47be-a8c7-ac9ccbf52d89", "name": "Child", "description": "call::sample_project2.core.model.child.Child", "created_at": "2026-03-02T13:48:04.296251Z", "updated_at": "2026-03-02T13:48:04.296252Z", "qname": "CallSchema/186ae128-9a0d-4312-9e32-c9410750a2f2::ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "target_function": "ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "children_by_type": {"call_children": ["CallSchema/40f90d8c-e69f-42df-b250-9a00a0ff09f1"], "call_group": []}, "children": [{"id": "CallSchema/40f90d8c-e69f-42df-b250-9a00a0ff09f1", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:48:04.296267Z", "updated_at": "2026-03-02T13:48:04.296268Z", "qname": "CallSchema/c216e1f6-e207-47be-a8c7-ac9ccbf52d89::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "name": "Child", "description": "Class Child", "created_at": "2026-03-02T13:26:10.443291Z", "updated_at": "2026-03-02T13:26:10.443291Z", "qname": "sample_project2.core.model.child.Child", "code_position": {"line_no": 6, "col_offset": 0, "end_line_no": 28, "end_col_offset": 0}, "documents": [], "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "FunctionSchema/2b10cd92-9cb3-40ed-828f-b446e99bfc90", "FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "FunctionSchema/fc638f7e-f2a8-4fbc-8ee8-037cbb8f35c2"], "code_element_group": []}, "children": [], "base_classes": ["sample_project2.core.model.parent.GrandParent", "sample_project2.core.model.child.Child", "sample_project2.core.model.parent.Uncle", "sample_project2.core.model.parent.Parent", "builtins.object"], "theme_config": null, "node_type": "function"}}], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/1a5b7f13-911d-450a-ad84-3ffe6b577edd", "name": "create_child", "description": "Function create_child", "created_at": "2026-03-02T13:26:10.428977Z", "updated_at": "2026-03-02T13:26:10.428977Z", "qname": "sample_project2.core.utils.helper.create_child", "code_position": {"line_no": 9, "col_offset": 0, "end_line_no": 16, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/5ec80657-2dc9-47ae-b4c6-fa65074992cb", "name": "get_name", "description": "call::core.model.child.Child.get_name", "created_at": "2026-03-02T13:26:12.529741Z", "updated_at": "2026-03-02T13:26:12.529742Z", "qname": "CallSchema/921155ba-86ca-43f9-95e4-489f233dac16::FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "target_function": "FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "name": "get_name", "description": "Function get_name", "created_at": "2026-03-02T13:26:10.443304Z", "updated_at": "2026-03-02T13:26:10.443304Z", "qname": "sample_project2.core.model.child.Child.get_name", "code_position": {"line_no": 16, "col_offset": 4, "end_line_no": 19, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/11b1c19e-faa5-44f1-836a-c1ef80d43c87", "name": "main", "description": "Function main", "created_at": "2026-03-02T13:26:10.466354Z", "updated_at": "2026-03-02T13:26:10.466354Z", "qname": "sample_project2.main.main", "code_position": {"line_no": 8, "col_offset": 0, "end_line_no": 13, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/65834d2b-1f81-4c13-85e0-5f4416baba36", "name": "dd", "description": "call::sample_project2.main.dd", "created_at": "2026-03-02T13:48:04.296215Z", "updated_at": "2026-03-02T13:48:04.296219Z", "qname": "FileSchema/372f9c6e-7ea2-44ed-9678-b56a0ca8c3f1::FunctionSchema/08a9a5f5-aa69-4a67-bf4a-e10800e80e31", "target_function": "FunctionSchema/08a9a5f5-aa69-4a67-bf4a-e10800e80e31", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/08a9a5f5-aa69-4a67-bf4a-e10800e80e31", "name": "dd", "description": "Function dd", "created_at": "2026-03-02T13:26:10.466365Z", "updated_at": "2026-03-02T13:26:10.466365Z", "qname": "sample_project2.main.dd", "code_position": {"line_no": 22, "col_offset": 0, "end_line_no": 26, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "FunctionSchema/08a9a5f5-aa69-4a67-bf4a-e10800e80e31", "name": "dd", "description": "Function dd", "created_at": "2026-03-02T13:26:10.466365Z", "updated_at": "2026-03-02T13:26:10.466365Z", "qname": "sample_project2.main.dd", "code_position": {"line_no": 22, "col_offset": 0, "end_line_no": 26, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}, {"id": "FunctionSchema/11b1c19e-faa5-44f1-836a-c1ef80d43c87", "name": "main", "description": "Function main", "created_at": "2026-03-02T13:26:10.466354Z", "updated_at": "2026-03-02T13:26:10.466354Z", "qname": "sample_project2.main.main", "code_position": {"line_no": 8, "col_offset": 0, "end_line_no": 13, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [{"id": "CallSchema/99e22f7e-4efe-4457-8b1b-fbb20002788d", "name": "get_name", "description": "call::core.model.child.Child.get_name", "created_at": "2026-03-02T13:26:12.642096Z", "updated_at": "2026-03-02T13:26:12.642098Z", "qname": "FunctionSchema/11b1c19e-faa5-44f1-836a-c1ef80d43c87::FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "target_function": "FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "name": "get_name", "description": "Function get_name", "created_at": "2026-03-02T13:26:10.443304Z", "updated_at": "2026-03-02T13:26:10.443304Z", "qname": "sample_project2.core.model.child.Child.get_name", "code_position": {"line_no": 16, "col_offset": 4, "end_line_no": 19, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/74062b63-0b55-40f5-a107-060e7aa546c2", "name": "create_child", "description": "call::core.utils.helper.create_child", "created_at": "2026-03-02T13:26:12.642113Z", "updated_at": "2026-03-02T13:26:12.642113Z", "qname": "FunctionSchema/11b1c19e-faa5-44f1-836a-c1ef80d43c87::FunctionSchema/1a5b7f13-911d-450a-ad84-3ffe6b577edd", "target_function": "FunctionSchema/1a5b7f13-911d-450a-ad84-3ffe6b577edd", "children_by_type": {"call_children": ["CallSchema/eeaa4f33-6b10-4c87-8e36-150d5a002786"], "call_group": []}, "children": [{"id": "CallSchema/eeaa4f33-6b10-4c87-8e36-150d5a002786", "name": "Child", "description": "call::sample_project2.core.model.child.Child", "created_at": "2026-03-02T13:48:04.318589Z", "updated_at": "2026-03-02T13:48:04.318593Z", "qname": "CallSchema/74062b63-0b55-40f5-a107-060e7aa546c2::ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "target_function": "ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "children_by_type": {"call_children": ["CallSchema/398eb955-92b5-4c98-9e37-6863a7cf277b"], "call_group": []}, "children": [{"id": "CallSchema/398eb955-92b5-4c98-9e37-6863a7cf277b", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:48:04.318610Z", "updated_at": "2026-03-02T13:48:04.318611Z", "qname": "CallSchema/eeaa4f33-6b10-4c87-8e36-150d5a002786::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "ClassSchema/db9ce2c7-4a05-4b99-8dbb-0b65024446d0", "name": "Child", "description": "Class Child", "created_at": "2026-03-02T13:26:10.443291Z", "updated_at": "2026-03-02T13:26:10.443291Z", "qname": "sample_project2.core.model.child.Child", "code_position": {"line_no": 6, "col_offset": 0, "end_line_no": 28, "end_col_offset": 0}, "documents": [], "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "FunctionSchema/2b10cd92-9cb3-40ed-828f-b446e99bfc90", "FunctionSchema/31705d6d-c950-41f5-96b5-4d2f01690c78", "FunctionSchema/fc638f7e-f2a8-4fbc-8ee8-037cbb8f35c2"], "code_element_group": []}, "children": [], "base_classes": ["sample_project2.core.model.parent.GrandParent", "sample_project2.core.model.child.Child", "sample_project2.core.model.parent.Uncle", "sample_project2.core.model.parent.Parent", "builtins.object"], "theme_config": null, "node_type": "function"}}], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/1a5b7f13-911d-450a-ad84-3ffe6b577edd", "name": "create_child", "description": "Function create_child", "created_at": "2026-03-02T13:26:10.428977Z", "updated_at": "2026-03-02T13:26:10.428977Z", "qname": "sample_project2.core.utils.helper.create_child", "code_position": {"line_no": 9, "col_offset": 0, "end_line_no": 16, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}], "documents": [], "theme_config": null, "node_type": "function"}], "node_type": "file"}, {"id": "FileSchema/bfeb3280-f24b-4556-ad17-d23e05102f12", "name": "__init__", "description": "File __init__", "created_at": "2026-03-02T13:26:09.906428Z", "updated_at": "2026-03-02T13:26:09.906432Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/__init__.py", "qname": "sample_project2.__init__", "documents": [], "theme_config": null, "hash": "e91a9e76a195d5a82f1b3f1abc9cb9729e1ac72de1ab898e5ecd37a0df9ca0ba", "children_by_type": {"class_children": [], "function_children": [], "code_element_group": [], "call_children": [], "call_group": []}, "children": [], "node_type": "file"}, {"id": "FileSchema/cb66b194-9ab0-4d9c-a126-66477c033786", "name": "hello", "description": "File hello", "created_at": "2026-03-02T13:26:09.907042Z", "updated_at": "2026-03-02T13:26:09.907042Z", "path": "/Users/yared/Documents/Programing/ide/playground/parser/sample_project2/hello.py", "qname": "sample_project2.hello", "documents": [], "theme_config": null, "hash": "746e294781781eee487d13a8ae6a73545e93c86b0eeea0b63a8497ff344a030c", "children_by_type": {"class_children": [], "function_children": ["FunctionSchema/f6c92d63-9951-4ddd-953e-755dfdc174f2"], "code_element_group": [], "call_children": [], "call_group": []}, "children": [{"id": "FunctionSchema/f6c92d63-9951-4ddd-953e-755dfdc174f2", "name": "runn", "description": "Function runn", "created_at": "2026-03-02T13:26:10.464700Z", "updated_at": "2026-03-02T13:26:10.464701Z", "qname": "sample_project2.hello.runn", "code_position": {"line_no": 4, "col_offset": 0, "end_line_no": 7, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}], "node_type": "file"}, {"id": "CallSchema/b7b895bd-8b2f-4e44-b05d-6100a9a695a7", "name": "__init__", "description": "call::core.model.child.Child.__init__", "created_at": "2026-03-02T13:26:12.529767Z", "updated_at": "2026-03-02T13:26:12.529768Z", "qname": "CallSchema/723f0443-2b2d-4747-84bf-1e442c0b3279::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/d5c05556-2c9b-4326-af6a-7f5cce7827b1", "name": "__init__", "description": "call::core.model.child.Child.__init__", "created_at": "2026-03-02T13:26:12.642137Z", "updated_at": "2026-03-02T13:26:12.642137Z", "qname": "CallSchema/5fbf36be-473b-4908-86dc-ef2a149f7e7a::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/5f446258-19a6-4b82-99e5-b2e3e2ba2580", "name": "__init__", "description": "call::core.model.child.Child.__init__", "created_at": "2026-03-02T13:26:33.926408Z", "updated_at": "2026-03-02T13:26:33.926409Z", "qname": "CallSchema/2d60eff6-5131-4e1d-8682-ce4cb0b1822f::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/c88620b5-2933-48cb-94b1-8791b41b2244", "name": "__init__", "description": "call::core.model.child.Child.__init__", "created_at": "2026-03-02T13:26:33.958871Z", "updated_at": "2026-03-02T13:26:33.958871Z", "qname": "CallSchema/c7a257ab-4625-415c-a1b1-5b5e55bd72ac::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/005eea45-e496-4593-8d1f-c445997a391e", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:29:43.791330Z", "updated_at": "2026-03-02T13:29:43.791331Z", "qname": "CallSchema/1366431e-7ec4-4118-9062-e98abd17a8f2::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/99ecf862-f66f-455e-b3b2-a08d52744a15", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:29:43.820557Z", "updated_at": "2026-03-02T13:29:43.820558Z", "qname": "CallSchema/2c271965-fdba-4981-866b-38a3d5149a7e::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/69e51916-6574-4100-92c1-f3addda5ae15", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:35:45.815735Z", "updated_at": "2026-03-02T13:35:45.815736Z", "qname": "CallSchema/2054d62e-90be-4dd6-a2bf-55f7bdee4e7b::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/fdca1add-d35d-4d05-a832-3c179ec08c27", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:35:45.860600Z", "updated_at": "2026-03-02T13:35:45.860604Z", "qname": "CallSchema/9ce6620d-a759-4d3b-8488-88236fbeffbd::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/bb61ff1e-d6d6-47a8-9c47-6931ec49683c", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:40:32.132279Z", "updated_at": "2026-03-02T13:40:32.132281Z", "qname": "CallSchema/6b4447de-bc24-4c4a-a24f-91e8fb4828fb::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/fbde7964-0d78-476d-b504-df3afb8cb5da", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:40:32.108887Z", "updated_at": "2026-03-02T13:40:32.108887Z", "qname": "CallSchema/41155d11-02c5-48c9-a412-8ad9d6dddd42::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/3813285e-f473-41b1-81a6-760ddc72a912", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:43:24.922822Z", "updated_at": "2026-03-02T13:43:24.922822Z", "qname": "CallSchema/f6149e92-cc6f-4f1b-82e1-3d37653328c8::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/d762eb1b-74da-44f6-9749-f38305313cfb", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:43:24.946721Z", "updated_at": "2026-03-02T13:43:24.946722Z", "qname": "CallSchema/ca3e33ea-3966-45e9-9364-513b5f8750fd::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/1a3c1ef4-e944-4ff8-82cc-36fac4d49a94", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:46:03.848060Z", "updated_at": "2026-03-02T13:46:03.848060Z", "qname": "CallSchema/2e431f06-2c91-4920-b1e0-674f965cd423::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}, {"id": "CallSchema/ca9f853f-0393-4ef3-b67e-46002012f6bb", "name": "__init__", "description": "call::sample_project2.core.model.child.Child.__init__", "created_at": "2026-03-02T13:46:03.810823Z", "updated_at": "2026-03-02T13:46:03.810824Z", "qname": "CallSchema/63fef3ab-ebb2-440b-8fcd-21a46cf69f44::FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "target_function": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "children_by_type": {"call_children": [], "call_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "call", "target": {"id": "FunctionSchema/f9b3e29d-ce9e-49ea-9599-ae4ce349f326", "name": "__init__", "description": "Function __init__", "created_at": "2026-03-02T13:26:10.443298Z", "updated_at": "2026-03-02T13:26:10.443298Z", "qname": "sample_project2.core.model.child.Child.__init__", "code_position": {"line_no": 10, "col_offset": 4, "end_line_no": 14, "end_col_offset": 0}, "children_by_type": {"class_children": [], "function_children": [], "code_element_group": []}, "children": [], "documents": [], "theme_config": null, "node_type": "function"}}]
\ No newline at end of file
diff --git a/src/backend/vector_storage/admin%2Fsir.vecs b/src/backend/vector_storage/admin%2Fsir.vecs
new file mode 100644
index 00000000..e1339607
Binary files /dev/null and b/src/backend/vector_storage/admin%2Fsir.vecs differ
diff --git a/src/backend/vector_storage/admin%2Fsir@1dagck3uovy24coiasr81il63rdrrq3.hnsw b/src/backend/vector_storage/admin%2Fsir@1dagck3uovy24coiasr81il63rdrrq3.hnsw
new file mode 100644
index 00000000..3b3bc476
--- /dev/null
+++ b/src/backend/vector_storage/admin%2Fsir@1dagck3uovy24coiasr81il63rdrrq3.hnsw
@@ -0,0 +1 @@
+{"metric":null,"zero":[[1,2,3,4,5,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615],[0,2,3,4,5,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615],[1,0,3,4,5,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615],[2,0,1,4,5,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615],[0,1,2,3,5,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615],[0,1,2,4,3,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615]],"features":[{"id":"terminusdb:///data/File/001","index":0},{"id":"terminusdb:///data/File/002","index":1},{"id":"terminusdb:///data/File/003","index":2},{"id":"terminusdb:///data/File/004","index":3},{"id":"terminusdb:///data/File/71","index":4},{"id":"terminusdb:///data/File/utils","index":5}],"layers":[],"prng":{"state":46084779743337481210624775610908566648,"increment":1},"params":{"ef_construction":400}}
\ No newline at end of file
diff --git a/src/backend/vector_storage/api%2Fdb%2Fadmin%2Fsir.vecs b/src/backend/vector_storage/api%2Fdb%2Fadmin%2Fsir.vecs
new file mode 100644
index 00000000..e69de29b
diff --git a/src/backend/vector_storage/api%2Fdocument%2Fadmin%2Fsir%2Flocal%2Fbranch%2Fmain.vecs b/src/backend/vector_storage/api%2Fdocument%2Fadmin%2Fsir%2Flocal%2Fbranch%2Fmain.vecs
new file mode 100644
index 00000000..e69de29b
diff --git a/src/backend/vector_storage/api%2Fdocument%2Fadmin%2Fsir.vecs b/src/backend/vector_storage/api%2Fdocument%2Fadmin%2Fsir.vecs
new file mode 100644
index 00000000..e69de29b
diff --git a/src/frontend/package.json b/src/frontend/package.json
index 17bb0126..e74f901e 100644
--- a/src/frontend/package.json
+++ b/src/frontend/package.json
@@ -54,20 +54,23 @@
     "date-fns": "^4.1.0",
     "diff": "^8.0.3",
     "driver.js": "^1.4.0",
+    "fast-json-patch": "^3.1.1",
     "immer": "^10.1.1",
     "lucide-react": "^0.532.0",
     "mermaid": "^11.9.0",
     "next-themes": "^0.4.6",
     "postcss": "^8.5.6",
-    "react": "^19.1.0",
+    "react": "^19.2.0",
     "react-day-picker": "^9.8.1",
-    "react-dom": "^19.1.0",
+    "react-dom": "^19.2.0",
     "react-hook-form": "^7.61.1",
     "react-icons": "^5.5.0",
+    "react-markdown": "^10.1.0",
     "react-resizable-panels": "^3.0.3",
     "react-router": "^7.12.0",
     "react-router-dom": "^7.12.0",
     "react-virtual": "^2.10.4",
+    "remark-gfm": "^4.0.1",
     "remeda": "^2.32.0",
     "socket.io-client": "^4.8.1",
     "sonner": "^2.0.6",
diff --git a/src/frontend/src/features/Dashboard/components/NodeContextMenu.tsx b/src/frontend/src/features/Dashboard/components/NodeContextMenu.tsx
index ec16c2ba..3c180d98 100644
--- a/src/frontend/src/features/Dashboard/components/NodeContextMenu.tsx
+++ b/src/frontend/src/features/Dashboard/components/NodeContextMenu.tsx
@@ -5,7 +5,15 @@ import {
   ContextMenuTrigger,
 } from "@/components/ui/context-menu";
 import { Separator } from "@/components/ui/separator";
-import { Crosshair, Expand, Group, Link, Trash, FileCode } from "lucide-react";
+import {
+  Crosshair,
+  Expand,
+  Group,
+  Link,
+  Trash,
+  FileCode,
+  Workflow,
+} from "lucide-react";
 
 interface NodeContextMenuProps {
   children: React.ReactNode;
@@ -41,6 +49,10 @@ export const NodeContextMenu = ({
           <FileCode className="mr-2 h-4 w-4" />
           Build Prompt
         </ContextMenuItem>
+        <ContextMenuItem onClick={() => onAction("start-workflow")}>
+          <Workflow className="mr-2 h-4 w-4" />
+          Start workflow
+        </ContextMenuItem>
         <Separator />
         {["function", "class", "call", "file"].includes(nodeType) && (
           <ContextMenuItem onClick={() => onAction("add-call")}>
diff --git a/src/frontend/src/features/Dashboard/components/SidebarDialogs.tsx b/src/frontend/src/features/Dashboard/components/SidebarDialogs.tsx
index 06d416c1..b75786d4 100644
--- a/src/frontend/src/features/Dashboard/components/SidebarDialogs.tsx
+++ b/src/frontend/src/features/Dashboard/components/SidebarDialogs.tsx
@@ -1,4 +1,5 @@
 import { useSidebarModalStore } from "@/features/Dashboard/store/useSidebarModalStore";
+import { StartWorkflowDialog } from "@/features/Dashboard/features/Agent/components/StartWorkflowDialog";
 import GroupDialog from "./GroupDialog";
 import SelectNodeDialog from "./SelectNodeDialog";
 import PromptBuilder from "@/components/PromptBuilder/PromptBuilder";
@@ -71,6 +72,13 @@ export function SidebarDialogs() {
         rootNode={targetNode as ContainerNodeTree}
         projectId={projectData?.id ?? ""}
       />
+
+      <StartWorkflowDialog
+        open={activeModal === "start-workflow"}
+        onOpenChange={(open) => !open && closeModal()}
+        targetNode={targetNode}
+        projectId={projectData?.id ?? ""}
+      />
     </>
   );
 }
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/AgentChatInput.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/AgentChatInput.tsx
index dba7563f..3a1ecee4 100644
--- a/src/frontend/src/features/Dashboard/features/Agent/components/AgentChatInput.tsx
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/AgentChatInput.tsx
@@ -1,8 +1,10 @@
 import { useState } from "react";
 import { SendHorizontal } from "lucide-react";
+import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { cn } from "@/lib/utils";
+import { useAgentChatSend } from "../hooks/useAgentChatSend";
 
 interface AgentChatInputProps {
   className?: string;
@@ -10,10 +12,20 @@ interface AgentChatInputProps {
 
 export function AgentChatInput({ className }: AgentChatInputProps) {
   const [value, setValue] = useState("");
+  const sendMessage = useAgentChatSend();
 
   const handleSubmit = () => {
-    // Input UI only for now; sending logic is intentionally out of scope.
-    setValue("");
+    const text = value.trim();
+    if (!text) return;
+
+    sendMessage.mutate(text, {
+      onSuccess: () => setValue(""),
+      onError: (e) => {
+        toast.error("Failed to send message", {
+          description: e instanceof Error ? e.message : String(e),
+        });
+      },
+    });
   };
 
   return (
@@ -21,14 +33,20 @@ export function AgentChatInput({ className }: AgentChatInputProps) {
       <Input
         value={value}
         onChange={(event) => setValue(event.target.value)}
-        placeholder="Ask AI about this code..."
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && !e.shiftKey) {
+            e.preventDefault();
+            handleSubmit();
+          }
+        }}
+        placeholder="Message…"
         className="h-9 text-xs"
       />
       <Button
         type="button"
         size="sm"
         onClick={handleSubmit}
-        disabled={!value.trim()}
+        disabled={!value.trim() || sendMessage.isPending}
         className="h-9 px-3"
         aria-label="Send message"
       >
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/AgentOverlay.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/AgentOverlay.tsx
index a38c7a31..220a44df 100644
--- a/src/frontend/src/features/Dashboard/features/Agent/components/AgentOverlay.tsx
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/AgentOverlay.tsx
@@ -1,5 +1,6 @@
+import { useQuery } from "@tanstack/react-query";
 import { useCallback, useEffect, useState } from "react";
-import { Clock3, X } from "lucide-react";
+import { Clock3, Plus, X } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { cn } from "@/lib/utils";
@@ -8,25 +9,59 @@ import {
   PopoverContent,
   PopoverTrigger,
 } from "@/components/ui/popover";
+import {
+  AGENT_UI_PREVIEW_CONVERSATION_ID,
+  createAgentUiPreviewWire,
+} from "../constants/agentPreviewConversation";
+import { useAgentLiveStore } from "../live/store/useAgentLiveStore";
 import { AgentSidebar } from "./AgentSidebar";
+import { useWalkthroughStore } from "../walkthrough/store/useWalkthroughStore";
 import { useAgentOverlayStore } from "../store/useAgentOverlayStore";
-import { useConversationStore } from "../store/useConversationStore";
+import { useAgentUiStore } from "../store/useAgentUiStore";
 import { useShallow } from "zustand/react/shallow";
+import { useVersioningStore } from "@/features/Dashboard/features/Versioning/store/useVersioningStore";
+import useProjectStore from "@/features/Dashboard/store/useProjectStore";
+import { agentConversationSummariesQueryOptions } from "@/services/agent";
 
 const MIN_WIDTH = 280;
 const DEFAULT_WIDTH = 360;
 const MAX_WIDTH = 720;
+const LIST_LIMIT = 50;
+
+function formatUpdatedAt(iso: string) {
+  try {
+    return new Date(iso).toLocaleString(undefined, {
+      dateStyle: "short",
+      timeStyle: "short",
+    });
+  } catch {
+    return "";
+  }
+}
 
 export function AgentOverlay() {
   const { isOpen, setOpen } = useAgentOverlayStore();
-  const [conversations, currentConversationId, setCurrentConversation] =
-    useConversationStore(
-      useShallow((state) => [
-        state.allConversations,
-        state.currentConversation?.id,
-        state.setCurrentConversation,
-      ]),
-    );
+  const playbackDetached = useWalkthroughStore((s) => s.playbackDetached);
+  const panelOpen = isOpen && !playbackDetached;
+  const [backendConversationId, setBackendConversationId] = useAgentUiStore(
+    useShallow((s) => [s.backendConversationId, s.setBackendConversationId]),
+  );
+
+  const projectId = useProjectStore((s) => s.projectData?.id ?? "");
+  const branch = useVersioningStore((s) => s.branch);
+  const ref = useVersioningStore((s) => s.checkedOutCommitId);
+  const compareTo = useVersioningStore((s) => s.compareToCommitId);
+
+  const serverQuery = useQuery(
+    agentConversationSummariesQueryOptions(
+      projectId,
+      branch,
+      ref,
+      compareTo,
+      LIST_LIMIT,
+    ),
+  );
+
   const [width, setWidth] = useState(DEFAULT_WIDTH);
   const [isResizing, setIsResizing] = useState(false);
   const [searchTerm, setSearchTerm] = useState("");
@@ -65,23 +100,32 @@ export function AgentOverlay() {
     };
   }, [isResizing]);
 
-  const filteredHistory = conversations.filter((item) => {
+  const serverItems = serverQuery.data?.items ?? [];
+  const filteredServer = serverItems.filter((item) => {
     const query = searchTerm.trim().toLowerCase();
     if (!query) return true;
     return (
       item.title.toLowerCase().includes(query) ||
-      item.date.toLowerCase().includes(query) ||
-      item.duration.toLowerCase().includes(query)
+      item.description.toLowerCase().includes(query)
     );
   });
 
+  const startNewChat = () => {
+    setBackendConversationId(null);
+  };
+
+  const loadUiSample = () => {
+    useAgentLiveStore.getState().setWire(createAgentUiPreviewWire());
+    setBackendConversationId(AGENT_UI_PREVIEW_CONVERSATION_ID);
+  };
+
   return (
     <div className="pointer-events-none absolute inset-0 z-30">
       <div
-        className="absolute bottom-24 right-0 top-0 h-full pointer-events-auto transition-transform duration-200"
+        className="pointer-events-auto absolute bottom-24 right-0 top-0 h-full transition-transform duration-200"
         style={{
           width,
-          transform: isOpen ? "translateX(0)" : "translateX(100%)",
+          transform: panelOpen ? "translateX(0)" : "translateX(100%)",
         }}
       >
         <div
@@ -92,6 +136,27 @@ export function AgentOverlay() {
           className="absolute left-0 top-0 h-full w-2 -translate-x-1 cursor-col-resize"
         />
         <div className="absolute right-2 top-2 z-10 flex items-center gap-1">
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            onClick={loadUiSample}
+            title="Load local markdown + task fixture (no API)"
+            className="h-7 px-2 text-[10px] font-medium"
+          >
+            Sample
+          </Button>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            onClick={startNewChat}
+            aria-label="Start new chat"
+            title="New chat"
+            className="h-7 w-7 text-muted-foreground hover:text-foreground"
+          >
+            <Plus size={14} />
+          </Button>
           <Popover>
             <PopoverTrigger asChild>
               <Button
@@ -105,41 +170,63 @@ export function AgentOverlay() {
               </Button>
             </PopoverTrigger>
             <PopoverContent align="end" side="bottom" className="w-80 p-2">
-              <div className="space-y-2">
-                <p className="px-2 pt-1 text-[11px] font-semibold uppercase tracking-wide text-muted-foreground">
-                  Chat history
-                </p>
+              <div className="space-y-3">
+                <div className="flex items-center justify-between px-2 pt-1">
+                  <p className="text-[11px] font-semibold uppercase tracking-wide text-muted-foreground">
+                    Chat history
+                  </p>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    className="h-7 gap-1 px-2 text-[11px]"
+                    onClick={startNewChat}
+                  >
+                    <Plus size={12} />
+                    New chat
+                  </Button>
+                </div>
                 <div className="px-2">
                   <Input
                     value={searchTerm}
                     onChange={(event) => setSearchTerm(event.target.value)}
-                    placeholder="Search chats..."
+                    placeholder="Search…"
                     className="h-8 text-xs"
                   />
                 </div>
+
                 <div className="max-h-72 space-y-1 overflow-auto px-1 pb-1">
-                  {filteredHistory.length > 0 ? (
-                    filteredHistory.map((item) => (
+                  {serverQuery.isError ? (
+                    <p className="px-2 py-2 text-xs text-destructive">
+                      Could not load conversations. Is the API running?
+                    </p>
+                  ) : serverQuery.isPending ? (
+                    <p className="px-2 py-2 text-xs text-muted-foreground">
+                      Loading…
+                    </p>
+                  ) : filteredServer.length > 0 ? (
+                    filteredServer.map((item) => (
                       <button
                         key={item.id}
                         type="button"
-                        onClick={() => setCurrentConversation(item.id)}
+                        onClick={() => setBackendConversationId(item.id)}
                         className={cn(
                           "w-full rounded-sm px-2 py-2 text-left transition hover:bg-muted",
-                          currentConversationId === item.id && "bg-muted",
+                          backendConversationId === item.id && "bg-muted",
                         )}
                       >
                         <p className="truncate text-xs font-medium text-foreground">
                           {item.title}
                         </p>
                         <p className="mt-1 text-[11px] text-muted-foreground">
-                          {item.date} · {item.duration}
+                          {formatUpdatedAt(item.updated_at)} ·{" "}
+                          {item.message_count} msgs
                         </p>
                       </button>
                     ))
                   ) : (
-                    <p className="px-2 py-4 text-center text-xs text-muted-foreground">
-                      No chat history found.
+                    <p className="px-2 py-2 text-xs text-muted-foreground">
+                      No conversations yet. Start a new chat and send a message.
                     </p>
                   )}
                 </div>
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/AgentSidebar.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/AgentSidebar.tsx
index 133fe01f..cb7afe7f 100644
--- a/src/frontend/src/features/Dashboard/features/Agent/components/AgentSidebar.tsx
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/AgentSidebar.tsx
@@ -1,24 +1,61 @@
+import { useQuery } from "@tanstack/react-query";
 import { cn } from "@/lib/utils";
-import { useConversationStore } from "../store/useConversationStore";
-import { selectMessageText } from "../store/selectors/conversationSelectors";
-import { useShallow } from "zustand/react/shallow";
+import { useVersioningStore } from "@/features/Dashboard/features/Versioning/store/useVersioningStore";
+import useProjectStore from "@/features/Dashboard/store/useProjectStore";
+import { agentConversationHydrationQueryOptions } from "@/services/agent";
+import { isAgentPreviewConversationId } from "../constants/agentPreviewConversation";
+import { useAgentUiStore } from "../store/useAgentUiStore";
+import { useAgentLiveStore } from "../live/store/useAgentLiveStore";
 import { AgentChatInput } from "./AgentChatInput";
-import { WalkthroughView } from "./WalkthroughView/WalkthroughView";
+import { ChatContainer } from "./chat";
+import { WalkthroughPlaybackBar } from "../walkthrough/components/WalkthroughPlaybackBar";
+import { useWalkthroughStore } from "../walkthrough/store/useWalkthroughStore";
 
 interface AgentSidebarProps {
   className?: string;
 }
 
 export function AgentSidebar({ className }: AgentSidebarProps) {
-  const [viewMode, setViewMode, currentConversation] = useConversationStore(
-    useShallow((state) => [
-      state.viewMode,
-      state.setViewMode,
-      state.currentConversation,
-    ]),
+  const playbackDetached = useWalkthroughStore((s) => s.playbackDetached);
+  const backendConversationId = useAgentUiStore((s) => s.backendConversationId);
+  const projectId = useProjectStore((s) => s.projectData?.id ?? "");
+  const branch = useVersioningStore((s) => s.branch);
+  const ref = useVersioningStore((s) => s.checkedOutCommitId);
+  const compareTo = useVersioningStore((s) => s.compareToCommitId);
+
+  const wire = useAgentLiveStore((s) => s.wire);
+  const activeStreams = useAgentLiveStore((s) => s.activeStreams);
+
+  const hydrationQuery = useQuery(
+    agentConversationHydrationQueryOptions(
+      projectId,
+      backendConversationId,
+      branch,
+      ref,
+      compareTo,
+    ),
+  );
+  /** Disabled queries (local preview id) stay `isPending` with no fetch — do not treat as loading. */
+  const isPreview = isAgentPreviewConversationId(backendConversationId);
+  const isLiveLoading =
+    Boolean(backendConversationId) &&
+    !isPreview &&
+    hydrationQuery.isPending;
+
+  const isLive =
+    Boolean(backendConversationId) && wire?.id === backendConversationId;
+
+  const streamingPlaceholderIds = new Set(
+    [...activeStreams].map((sid) => `stream:${sid}`),
   );
 
-  const messages = currentConversation?.messages;
+  const listMessages = isLive && wire ? wire.messages : [];
+
+  const title = !backendConversationId
+    ? "New chat"
+    : isLiveLoading
+      ? "Loading…"
+      : (wire?.title ?? "Conversation");
 
   return (
     <aside
@@ -30,72 +67,40 @@ export function AgentSidebar({ className }: AgentSidebarProps) {
       <div className="border-b border-border px-4 py-3">
         <div>
           <p className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
-            AI Cognitive Replay
-          </p>
-          <p className="mt-1 truncate text-xs text-foreground">
-            {currentConversation?.title ?? "No conversation selected"}
+            Agent
+            {isLive ? (
+              <span className="ml-2 font-normal normal-case text-primary">
+                · Live
+              </span>
+            ) : null}
           </p>
+          <p className="mt-1 truncate text-xs text-foreground">{title}</p>
         </div>
       </div>
 
       <div className="flex-1 space-y-4 overflow-auto p-4">
-        {viewMode === "chat" ? (
-          <section className="space-y-2">
-            {messages && messages.length > 0 ? (
-              messages.map((message) => (
-                <article
-                  key={message.id}
-                  className="rounded-md border border-border bg-muted/40 p-3"
-                >
-                  <p className="mb-2 text-[11px] font-semibold uppercase tracking-wide text-muted-foreground">
-                    {message.role}
-                  </p>
-                  <p className="text-xs leading-relaxed text-foreground">
-                    {selectMessageText(message.parts) || "No text content."}
-                  </p>
-                </article>
-              ))
-            ) : (
-              <p className="rounded-md border border-border bg-muted/40 p-3 text-xs text-muted-foreground">
-                No messages in this conversation.
-              </p>
-            )}
-          </section>
-        ) : (
-          <WalkthroughView conversation={currentConversation} />
-        )}
+        <section className="space-y-2">
+          {isLiveLoading ? (
+            <p className="rounded-md border border-border bg-muted/40 p-3 text-xs text-muted-foreground">
+              Loading conversation…
+            </p>
+          ) : (
+            <ChatContainer
+              messages={listMessages}
+              streamingMessageIds={streamingPlaceholderIds}
+              emptyLabel={
+                backendConversationId
+                  ? "No messages yet."
+                  : "New chat — your conversation is created when you send the first message."
+              }
+            />
+          )}
+        </section>
       </div>
 
-      <div className="border-t border-border p-3">
+      <div className="border-t border-border space-y-3 p-3">
+        {!playbackDetached ? <WalkthroughPlaybackBar /> : null}
         <AgentChatInput />
-        <div className="mt-3 flex justify-center">
-          <div className="rounded-md border border-border p-0.5">
-            <button
-              type="button"
-              onClick={() => setViewMode("chat")}
-              className={cn(
-                "rounded px-2 py-1 text-[11px] transition",
-                viewMode === "chat"
-                  ? "bg-primary text-primary-foreground"
-                  : "text-muted-foreground hover:bg-muted",
-              )}
-            >
-              Chat
-            </button>
-            <button
-              type="button"
-              onClick={() => setViewMode("walkthrough")}
-              className={cn(
-                "rounded px-2 py-1 text-[11px] transition",
-                viewMode === "walkthrough"
-                  ? "bg-primary text-primary-foreground"
-                  : "text-muted-foreground hover:bg-muted",
-              )}
-            >
-              Walkthrough
-            </button>
-          </div>
-        </div>
       </div>
     </aside>
   );
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/StartWorkflowDialog.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/StartWorkflowDialog.tsx
new file mode 100644
index 00000000..2e288842
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/StartWorkflowDialog.tsx
@@ -0,0 +1,413 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useMemo, useState } from "react";
+import { toast } from "sonner";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
+import {
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from "@/components/ui/tabs";
+import { Textarea } from "@/components/ui/textarea";
+import { useAgentUiStore } from "@/features/Dashboard/features/Agent/store/useAgentUiStore";
+import { useAgentOverlayStore } from "@/features/Dashboard/features/Agent/store/useAgentOverlayStore";
+import { useVersioningStore } from "@/features/Dashboard/features/Versioning/store/useVersioningStore";
+import queryKeys from "@/lib/queryKeys";
+import { AgentHttpError } from "@/lib/agentFetch";
+import {
+  agentConversationHydrationQueryOptions,
+  agentWorkflowsApi,
+} from "@/services/agent";
+import type { AnyNodeTree } from "@/types/project";
+import type {
+  DescriptionWorkflowMode,
+  DocumentationWorkflowMode,
+  RunWorkflowRequest,
+  StartAgentWorkflowsPayload,
+  WorkflowBatchStepWire,
+  WorkflowModelId,
+} from "@/types/agent/workflows";
+import { WORKFLOW_MODEL_OPTIONS } from "@/types/agent/workflows";
+
+type WorkflowKind = "description" | "documentation";
+
+function buildWorkflowSteps(args: {
+  kind: WorkflowKind;
+  nodeId: string;
+  descriptionModel: WorkflowModelId;
+  documentationModel: WorkflowModelId;
+  descriptionMode: DescriptionWorkflowMode;
+  documentationMode: DocumentationWorkflowMode;
+  direction: "up" | "down";
+  maxDepth: number;
+}): WorkflowBatchStepWire[] {
+  const base = {
+    node_id: args.nodeId,
+    direction: args.direction,
+    max_depth: args.maxDepth,
+  };
+  if (args.kind === "description") {
+    return [
+      {
+        workflow_name: "description_generator",
+        params: {
+          ...base,
+          model: args.descriptionModel,
+          description_mode: args.descriptionMode,
+        },
+      },
+    ];
+  }
+  return [
+    {
+      workflow_name: "documentation_generator",
+      params: {
+        ...base,
+        model: args.documentationModel,
+        documentation_mode: args.documentationMode,
+      },
+    },
+  ];
+}
+
+interface StartWorkflowDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  targetNode: AnyNodeTree;
+  projectId: string;
+}
+
+export function StartWorkflowDialog({
+  open,
+  onOpenChange,
+  targetNode,
+  projectId,
+}: StartWorkflowDialogProps) {
+  const queryClient = useQueryClient();
+  const branch = useVersioningStore((s) => s.branch);
+  const ref = useVersioningStore((s) => s.checkedOutCommitId);
+  const compareTo = useVersioningStore((s) => s.compareToCommitId);
+  const setAgentOpen = useAgentOverlayStore((s) => s.setOpen);
+  const setBackendConversationId = useAgentUiStore(
+    (s) => s.setBackendConversationId,
+  );
+
+  const [workflowKind, setWorkflowKind] =
+    useState<WorkflowKind>("description");
+  const [conversationTitle, setConversationTitle] = useState("");
+  const [conversationDescription, setConversationDescription] = useState("");
+  const [descriptionModel, setDescriptionModel] =
+    useState<WorkflowModelId>("gpt-4o-mini");
+  const [documentationModel, setDocumentationModel] =
+    useState<WorkflowModelId>("gpt-4o-mini");
+  const [descriptionMode, setDescriptionMode] =
+    useState<DescriptionWorkflowMode>("always");
+  const [documentationMode, setDocumentationMode] =
+    useState<DocumentationWorkflowMode>("upsert");
+  const [direction, setDirection] = useState<"up" | "down">("down");
+  const [maxDepth, setMaxDepth] = useState(5);
+
+  const nodeId = targetNode.id;
+
+  const resetForm = () => {
+    setWorkflowKind("description");
+    setConversationTitle("");
+    setConversationDescription("");
+    setDescriptionModel("gpt-4o-mini");
+    setDocumentationModel("gpt-4o-mini");
+    setDescriptionMode("always");
+    setDocumentationMode("upsert");
+    setDirection("down");
+    setMaxDepth(5);
+  };
+
+  const startWorkflowsMutation = useMutation({
+    mutationFn: async (body: StartAgentWorkflowsPayload) => {
+      const step = body.steps[0];
+      if (!step) {
+        throw new Error("No workflow step");
+      }
+      const title = (body.conversation_title ?? "").trim();
+      const description = (body.conversation_description ?? "").trim();
+      const req: RunWorkflowRequest = {
+        workflow_name: step.workflow_name,
+        params: step.params,
+      };
+      if (title) req.conversation_title = title;
+      if (description) req.conversation_description = description;
+      return agentWorkflowsApi.run(projectId, req);
+    },
+    onSuccess: async (data) => {
+      toast.success("Workflow started");
+      const cid = data.conversation_id;
+      setBackendConversationId(cid);
+      setAgentOpen(true);
+      void queryClient.prefetchQuery(
+        agentConversationHydrationQueryOptions(
+          projectId,
+          cid,
+          branch,
+          ref,
+          compareTo,
+          200,
+        ),
+      );
+      void queryClient.invalidateQueries({
+        queryKey: queryKeys.agent.conversations.all(),
+      });
+      onOpenChange(false);
+      resetForm();
+    },
+    onError: (err: unknown) => {
+      const msg =
+        err instanceof AgentHttpError
+          ? JSON.stringify(err.body) || err.message
+          : err instanceof Error
+            ? err.message
+            : "Failed to start workflow";
+      toast.error(msg);
+    },
+  });
+
+  const payload = useMemo((): StartAgentWorkflowsPayload | null => {
+    if (!nodeId) return null;
+    const steps = buildWorkflowSteps({
+      kind: workflowKind,
+      nodeId,
+      descriptionModel,
+      documentationModel,
+      descriptionMode,
+      documentationMode,
+      direction,
+      maxDepth,
+    });
+    const body: StartAgentWorkflowsPayload = { steps };
+    const t = conversationTitle.trim();
+    const d = conversationDescription.trim();
+    if (t) body.conversation_title = t;
+    if (d) body.conversation_description = d;
+    return body;
+  }, [
+    nodeId,
+    workflowKind,
+    descriptionModel,
+    documentationModel,
+    descriptionMode,
+    documentationMode,
+    direction,
+    maxDepth,
+    conversationTitle,
+    conversationDescription,
+  ]);
+
+  const handleSubmit = () => {
+    if (!payload?.steps.length) {
+      toast.error("Could not build workflow request");
+      return;
+    }
+    startWorkflowsMutation.mutate(payload);
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        onOpenChange(next);
+        if (!next) resetForm();
+      }}
+    >
+      <DialogContent className="max-h-[min(90vh,720px)] overflow-y-auto sm:max-w-lg">
+        <DialogHeader>
+          <DialogTitle>Start workflow</DialogTitle>
+          <p className="text-sm text-muted-foreground">
+            Root: <span className="font-medium text-foreground">{targetNode.name}</span>
+          </p>
+        </DialogHeader>
+
+        <div className="space-y-6 py-2">
+          <Tabs
+            value={workflowKind}
+            onValueChange={(v) => setWorkflowKind(v as WorkflowKind)}
+            className="gap-4"
+          >
+            <TabsList className="grid h-auto w-full grid-cols-2 p-1">
+              <TabsTrigger value="description" className="py-2">
+                Descriptions
+              </TabsTrigger>
+              <TabsTrigger value="documentation" className="py-2">
+                Documentation
+              </TabsTrigger>
+            </TabsList>
+
+            <TabsContent
+              value="description"
+              className="space-y-3 rounded-md border border-border/60 p-3"
+            >
+              <div className="space-y-2">
+                <Label htmlFor="wf-desc-model">Model</Label>
+                <select
+                  id="wf-desc-model"
+                  className="flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-xs outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]"
+                  value={descriptionModel}
+                  onChange={(e) =>
+                    setDescriptionModel(e.target.value as WorkflowModelId)
+                  }
+                >
+                  {WORKFLOW_MODEL_OPTIONS.map((m) => (
+                    <option key={m} value={m}>
+                      {m}
+                    </option>
+                  ))}
+                </select>
+              </div>
+              <div className="space-y-2">
+                <Label>Existing descriptions</Label>
+                <RadioGroup
+                  value={descriptionMode}
+                  onValueChange={(v) =>
+                    setDescriptionMode(v as DescriptionWorkflowMode)
+                  }
+                  className="flex flex-col gap-2"
+                >
+                  <label className="flex items-center gap-2 text-sm">
+                    <RadioGroupItem value="always" id="wf-desc-always" />
+                    <span>Regenerate all</span>
+                  </label>
+                  <label className="flex items-center gap-2 text-sm">
+                    <RadioGroupItem
+                      value="skip_if_present"
+                      id="wf-desc-skip"
+                    />
+                    <span>Skip nodes that already have a description</span>
+                  </label>
+                </RadioGroup>
+              </div>
+            </TabsContent>
+
+            <TabsContent
+              value="documentation"
+              className="space-y-3 rounded-md border border-border/60 p-3"
+            >
+              <div className="space-y-2">
+                <Label htmlFor="wf-doc-model">Model</Label>
+                <select
+                  id="wf-doc-model"
+                  className="flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-xs outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]"
+                  value={documentationModel}
+                  onChange={(e) =>
+                    setDocumentationModel(e.target.value as WorkflowModelId)
+                  }
+                >
+                  {WORKFLOW_MODEL_OPTIONS.map((m) => (
+                    <option key={m} value={m}>
+                      {m}
+                    </option>
+                  ))}
+                </select>
+              </div>
+              <div className="space-y-2">
+                <Label>Write mode</Label>
+                <RadioGroup
+                  value={documentationMode}
+                  onValueChange={(v) =>
+                    setDocumentationMode(v as DocumentationWorkflowMode)
+                  }
+                  className="flex flex-col gap-2"
+                >
+                  <label className="flex items-center gap-2 text-sm">
+                    <RadioGroupItem value="upsert" id="wf-doc-upsert" />
+                    <span>Upsert (replace generated doc content)</span>
+                  </label>
+                  <label className="flex items-center gap-2 text-sm">
+                    <RadioGroupItem value="insert_only" id="wf-doc-insert" />
+                    <span>Insert only if no generated doc exists yet</span>
+                  </label>
+                </RadioGroup>
+              </div>
+            </TabsContent>
+          </Tabs>
+
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div className="space-y-2">
+              <Label htmlFor="wf-direction">Traversal</Label>
+              <select
+                id="wf-direction"
+                className="flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-xs outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]"
+                value={direction}
+                onChange={(e) =>
+                  setDirection(e.target.value as "up" | "down")
+                }
+              >
+                <option value="down">Top-down</option>
+                <option value="up">Bottom-up</option>
+              </select>
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="wf-depth">Max depth</Label>
+              <Input
+                id="wf-depth"
+                type="number"
+                min={1}
+                max={32}
+                value={maxDepth}
+                onChange={(e) =>
+                  setMaxDepth(Math.max(1, Number(e.target.value) || 1))
+                }
+              />
+            </div>
+          </div>
+
+          <div className="space-y-3">
+            <p className="text-sm font-medium">Conversation (optional)</p>
+            <div className="space-y-2">
+              <Label htmlFor="wf-conv-title">Title</Label>
+              <Input
+                id="wf-conv-title"
+                placeholder="Defaults to an auto title if empty"
+                value={conversationTitle}
+                onChange={(e) => setConversationTitle(e.target.value)}
+              />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="wf-conv-desc">Description</Label>
+              <Textarea
+                id="wf-conv-desc"
+                placeholder="Defaults to an auto summary if empty"
+                rows={2}
+                value={conversationDescription}
+                onChange={(e) => setConversationDescription(e.target.value)}
+              />
+            </div>
+          </div>
+        </div>
+
+        <DialogFooter>
+          <Button
+            type="button"
+            variant="outline"
+            onClick={() => onOpenChange(false)}
+          >
+            Cancel
+          </Button>
+          <Button
+            type="button"
+            onClick={handleSubmit}
+            disabled={startWorkflowsMutation.isPending || !nodeId}
+          >
+            {startWorkflowsMutation.isPending ? "Starting…" : "Start"}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/ChatContainer.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/ChatContainer.tsx
new file mode 100644
index 00000000..22db4c8d
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/ChatContainer.tsx
@@ -0,0 +1,42 @@
+import type { WireMessage } from "@/types/agent";
+import { cn } from "@/lib/utils";
+import { MessageBubble } from "./MessageBubble";
+
+export interface ChatContainerProps {
+  messages: WireMessage[];
+  streamingMessageIds: Set<string>;
+  emptyLabel?: string;
+  className?: string;
+}
+
+export function ChatContainer({
+  messages,
+  streamingMessageIds,
+  emptyLabel = "No messages in this conversation.",
+  className,
+}: ChatContainerProps) {
+  if (messages.length === 0) {
+    return (
+      <p
+        className={cn(
+          "rounded-md border border-border bg-muted/40 p-3 text-xs text-muted-foreground",
+          className,
+        )}
+      >
+        {emptyLabel}
+      </p>
+    );
+  }
+
+  return (
+    <div className={cn("space-y-3", className)}>
+      {messages.map((m) => (
+        <MessageBubble
+          key={m.id}
+          message={m}
+          streaming={streamingMessageIds.has(m.id)}
+        />
+      ))}
+    </div>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/MessageBubble.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/MessageBubble.tsx
new file mode 100644
index 00000000..b3fb2a67
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/MessageBubble.tsx
@@ -0,0 +1,78 @@
+import { cn } from "@/lib/utils";
+import type { WireMessage } from "@/types/agent";
+import { wirePartType } from "./partTypes";
+import { PartRenderer } from "./PartRenderer";
+
+function firstTextPartIndex(parts: WireMessage["parts"]): number {
+  return parts.findIndex((p) => wirePartType(p) === "text");
+}
+
+function isUserRole(role: string): boolean {
+  return role.toLowerCase() === "user";
+}
+
+export interface MessageBubbleProps {
+  message: WireMessage;
+  streaming?: boolean;
+  className?: string;
+}
+
+export function MessageBubble({
+  message,
+  streaming,
+  className,
+}: MessageBubbleProps) {
+  const textIdx = firstTextPartIndex(message.parts);
+  const user = isUserRole(message.role);
+
+  return (
+    <div
+      className={cn(
+        "flex w-full min-w-0",
+        user ? "justify-end" : "justify-start",
+        className,
+      )}
+    >
+      <article
+        className={cn(
+          "min-w-0  rounded-2xl px-3.5 py-2.5 ",
+          user
+            ? " text-black"
+            : "rounded-bl-md border w-full border-border/80 bg-card text-card-foreground shadow-sm",
+          streaming && !user && "ring-1 ring-primary/35",
+        )}
+      >
+        <p
+          className={cn(
+            "mb-1.5 text-[10px] font-semibold uppercase tracking-wide",
+            user ? "text-black/65 " : "text-muted-foreground",
+          )}
+        >
+          {user ? "You" : message.role === "system" ? "System" : "Assistant"}
+          {streaming && !user ? " · streaming" : ""}
+        </p>
+        <div className="flex flex-col gap-2.5">
+          {message.parts.length === 0 ? (
+            <p
+              className={cn(
+                "text-xs",
+                user ? "text-primary-foreground/85" : "text-muted-foreground",
+              )}
+            >
+              No content.
+            </p>
+          ) : (
+            message.parts.map((part, index) => (
+              <PartRenderer
+                key={`${message.id}-part-${index}`}
+                part={part}
+                role={message.role}
+                streaming={streaming && index === textIdx}
+              />
+            ))
+          )}
+        </div>
+      </article>
+    </div>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/PartRenderer.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/PartRenderer.tsx
new file mode 100644
index 00000000..6f174b20
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/PartRenderer.tsx
@@ -0,0 +1,96 @@
+import type { FC } from "react";
+import type { WireMessagePart, WireTextPart } from "@/types/agent";
+import { wirePartType } from "./partTypes";
+import { TextPart } from "./parts/TextPart";
+import { ToolCallPart, type ToolCallWirePart } from "./parts/ToolCallPart";
+import { TaskPart, type TaskWirePart } from "./parts/task";
+import {
+  WalkthroughPart,
+  type WalkthroughWirePart,
+} from "./parts/walkthrough";
+import { UnknownPart } from "./parts/UnknownPart";
+
+export interface PartRendererProps {
+  part: WireMessagePart;
+  role: string;
+  streaming?: boolean;
+}
+
+function isTextPart(p: WireMessagePart): p is WireTextPart {
+  return (
+    typeof p === "object" &&
+    p !== null &&
+    typeof (p as WireTextPart).text === "string" &&
+    String((p as { type?: unknown }).type).toLowerCase() === "text"
+  );
+}
+
+function isToolCallPart(p: WireMessagePart): boolean {
+  return (
+    typeof p === "object" &&
+    p !== null &&
+    String((p as { type?: unknown }).type).toLowerCase() === "tool_call" &&
+    typeof (p as { tool_name?: unknown }).tool_name === "string"
+  );
+}
+
+function isTaskPart(p: WireMessagePart): boolean {
+  return (
+    typeof p === "object" &&
+    p !== null &&
+    String((p as { type?: unknown }).type).toLowerCase() === "task" &&
+    typeof (p as { task_id?: unknown }).task_id === "string"
+  );
+}
+
+function isWalkthroughPart(p: WireMessagePart): boolean {
+  if (typeof p !== "object" || p === null) return false;
+  if (String((p as { type?: unknown }).type).toLowerCase() !== "walkthrough") {
+    return false;
+  }
+  const w = (p as { walkthrough?: unknown }).walkthrough;
+  return (
+    typeof w === "object" &&
+    w !== null &&
+    typeof (w as { meta?: unknown }).meta === "object" &&
+    (w as { meta: object }).meta !== null &&
+    typeof (w as { meta: { id?: unknown } }).meta.id === "string" &&
+    Array.isArray((w as { steps?: unknown }).steps)
+  );
+}
+
+const REGISTRY: Record<string, FC<PartRendererProps>> = {
+  text: ({ part, role, streaming }) =>
+    isTextPart(part) ? (
+      <TextPart part={part} role={role} streaming={streaming} />
+    ) : (
+      <UnknownPart part={part} />
+    ),
+  tool_call: ({ part }) =>
+    isToolCallPart(part) ? (
+      <ToolCallPart part={part as unknown as ToolCallWirePart} />
+    ) : (
+      <UnknownPart part={part} />
+    ),
+  task: ({ part }) =>
+    isTaskPart(part) ? (
+      <TaskPart part={part as unknown as TaskWirePart} />
+    ) : (
+      <UnknownPart part={part} />
+    ),
+  walkthrough: ({ part }) =>
+    isWalkthroughPart(part) ? (
+      <WalkthroughPart part={part as unknown as WalkthroughWirePart} />
+    ) : (
+      <UnknownPart part={part} />
+    ),
+};
+
+export function PartRenderer(props: PartRendererProps) {
+  const t = wirePartType(props.part);
+  const C = REGISTRY[t];
+  if (!C) {
+    return <UnknownPart part={props.part} />;
+  }
+  return <C {...props} />;
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/index.ts b/src/frontend/src/features/Dashboard/features/Agent/components/chat/index.ts
new file mode 100644
index 00000000..9a97adcb
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/index.ts
@@ -0,0 +1,4 @@
+export { ChatContainer, type ChatContainerProps } from "./ChatContainer";
+export { MessageBubble, type MessageBubbleProps } from "./MessageBubble";
+export { PartRenderer, type PartRendererProps } from "./PartRenderer";
+export { wirePartType } from "./partTypes";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/partTypes.ts b/src/frontend/src/features/Dashboard/features/Agent/components/chat/partTypes.ts
new file mode 100644
index 00000000..de21e393
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/partTypes.ts
@@ -0,0 +1,9 @@
+import type { WireMessagePart } from "@/types/agent";
+
+export function wirePartType(part: WireMessagePart): string {
+  if (part && typeof part === "object" && "type" in part) {
+    const t = (part as { type: unknown }).type;
+    if (typeof t === "string" && t.length > 0) return t.toLowerCase();
+  }
+  return "unknown";
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/TextPart.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/TextPart.tsx
new file mode 100644
index 00000000..050a5830
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/TextPart.tsx
@@ -0,0 +1,45 @@
+import type { WireTextPart } from "@/types/agent";
+import { AssistantMarkdown } from "../../messages/Markdown";
+
+export interface TextPartProps {
+  part: WireTextPart;
+  role: string;
+  streaming?: boolean;
+}
+
+function markdownRole(role: string): boolean {
+  const r = role.toLowerCase();
+  return r === "assistant" || r === "system";
+}
+
+export function TextPart({ part, role, streaming }: TextPartProps) {
+  const text = part.text;
+  const isAssistant = markdownRole(role);
+
+  if (isAssistant) {
+    if (!text && !streaming) {
+      return (
+        <p className="text-xs leading-relaxed text-muted-foreground">
+          No text content.
+        </p>
+      );
+    }
+    return (
+      <div className="relative">
+        <AssistantMarkdown text={text || (streaming ? "…" : "")} />
+        {streaming && text ? (
+          <span
+            className="ml-0.5 inline-block h-3 w-0.5 animate-pulse bg-primary align-middle"
+            aria-hidden
+          />
+        ) : null}
+      </div>
+    );
+  }
+
+  return (
+    <p className="whitespace-pre-wrap text-xs leading-relaxed text-black">
+      {text || (streaming ? "…" : "No text content.")}
+    </p>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/ToolCallPart.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/ToolCallPart.tsx
new file mode 100644
index 00000000..64fb2e03
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/ToolCallPart.tsx
@@ -0,0 +1,61 @@
+import { ChevronDown } from "lucide-react";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+import { cn } from "@/lib/utils";
+
+export interface ToolCallWirePart {
+  type: "tool_call";
+  tool_name: string;
+  tool_input: unknown;
+  tool_output?: unknown;
+}
+
+function formatJson(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+export function ToolCallPart({ part }: { part: ToolCallWirePart }) {
+  return (
+    <div className="rounded-md border border-border bg-background/80 text-xs">
+      <Collapsible defaultOpen={false} className="group">
+        <CollapsibleTrigger className="flex w-full items-center justify-between gap-2 px-2 py-1.5 text-left font-medium text-foreground hover:bg-muted/50">
+          <span className="truncate font-mono text-[11px]">{part.tool_name}</span>
+          <ChevronDown className="h-3.5 w-3.5 shrink-0 text-muted-foreground transition-transform group-data-[state=open]:rotate-180" />
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <div className="space-y-2 border-t border-border px-2 py-2">
+            <div>
+              <p className="mb-1 text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
+                Input
+              </p>
+              <pre className="max-h-40 overflow-auto rounded bg-muted/60 p-2 font-mono text-[10px] leading-snug">
+                {formatJson(part.tool_input)}
+              </pre>
+            </div>
+            {part.tool_output !== undefined ? (
+              <div>
+                <p className="mb-1 text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
+                  Output
+                </p>
+                <pre
+                  className={cn(
+                    "max-h-48 overflow-auto rounded border border-border bg-muted/40 p-2 font-mono text-[10px] leading-snug",
+                  )}
+                >
+                  {formatJson(part.tool_output)}
+                </pre>
+              </div>
+            ) : null}
+          </div>
+        </CollapsibleContent>
+      </Collapsible>
+    </div>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/UnknownPart.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/UnknownPart.tsx
new file mode 100644
index 00000000..f0d9ae54
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/UnknownPart.tsx
@@ -0,0 +1,14 @@
+import type { WireMessagePart } from "@/types/agent";
+import { wirePartType } from "../partTypes";
+
+export function UnknownPart({ part }: { part: WireMessagePart }) {
+  const t = wirePartType(part);
+  return (
+    <div className="rounded-md border border-amber-500/40 bg-amber-500/5 p-2 text-xs text-amber-900 dark:text-amber-200">
+      <p className="mb-1 font-semibold">Unsupported part type: {t}</p>
+      <pre className="max-h-32 overflow-auto rounded bg-background/60 p-2 font-mono text-[10px] leading-snug">
+        {JSON.stringify(part, null, 2)}
+      </pre>
+    </div>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/SubTaskRow.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/SubTaskRow.tsx
new file mode 100644
index 00000000..b34bf47e
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/SubTaskRow.tsx
@@ -0,0 +1,25 @@
+import { subTaskLabel } from "./subTaskLabel";
+import { TaskStatusDot } from "./TaskStatusDot";
+import { toVisualStatus } from "./taskStatus";
+import type { TaskSubWire } from "./types";
+
+export function SubTaskRow({ sub }: { sub: TaskSubWire }) {
+  const status = toVisualStatus(sub.state);
+  return (
+    <div className="flex gap-2.5 rounded-lg border border-border/60 bg-background/50 py-2 pl-2 pr-2.5">
+      <div className="pt-0.5">
+        <TaskStatusDot status={status} />
+      </div>
+      <div className="min-w-0 flex-1">
+        <p className="text-[11px] font-semibold leading-snug text-foreground">
+          {subTaskLabel(sub)}
+        </p>
+        {sub.description ? (
+          <p className="mt-0.5 text-[10px] leading-snug text-muted-foreground">
+            {sub.description}
+          </p>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/TaskPart.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/TaskPart.tsx
new file mode 100644
index 00000000..663b3645
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/TaskPart.tsx
@@ -0,0 +1,188 @@
+import { useQuery } from "@tanstack/react-query";
+import type { LucideIcon } from "lucide-react";
+import { ChevronDown } from "lucide-react";
+import { useMemo, useState } from "react";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+import { isAgentPreviewTaskId } from "@/features/Dashboard/features/Agent/constants/agentPreviewConversation";
+import useProjectStore from "@/features/Dashboard/store/useProjectStore";
+import { useVersioningStore } from "@/features/Dashboard/features/Versioning/store/useVersioningStore";
+import { cn } from "@/lib/utils";
+import { agentTaskSubtasksQueryOptions } from "@/services/agent";
+import { resolveTaskIcon } from "./taskIcons";
+import { TaskStatusDot } from "./TaskStatusDot";
+import { TaskSubTaskList } from "./TaskSubTaskList";
+import { toVisualStatus } from "./taskStatus";
+import type { TaskSubWire, TaskWirePart } from "./types";
+
+function defaultExpanded(part: TaskWirePart): boolean {
+  const main = toVisualStatus(part.state);
+  if (main === "completed") return false;
+  if (main === "error") return true;
+  return true;
+}
+
+function TaskPartHeader({
+  part,
+  mainStatus,
+  MainIcon,
+  expandable,
+  open,
+}: {
+  part: TaskWirePart;
+  mainStatus: ReturnType<typeof toVisualStatus>;
+  MainIcon: LucideIcon;
+  expandable: boolean;
+  open: boolean;
+}) {
+  const inner = (
+    <>
+      <div
+        className={cn(
+          "flex h-9 w-9 shrink-0 items-center justify-center rounded-lg",
+          mainStatus === "completed" &&
+            "bg-emerald-500/10 text-emerald-700 dark:text-emerald-300",
+          mainStatus === "error" && "bg-destructive/10 text-destructive",
+          mainStatus === "pending" && "bg-primary/10 text-primary",
+        )}
+      >
+        <MainIcon className="h-4 w-4" strokeWidth={2} aria-hidden />
+      </div>
+      <div className="min-w-0 flex-1 text-left">
+        <div className="flex items-start justify-between gap-2">
+          <p className="text-[13px] font-semibold leading-tight tracking-tight text-foreground">
+            {part.title}
+          </p>
+          <div className="flex shrink-0 items-center gap-1.5">
+            {expandable ? (
+              <ChevronDown
+                className={cn(
+                  "h-4 w-4 text-muted-foreground transition-transform duration-200",
+                  open && "rotate-180",
+                )}
+                aria-hidden
+              />
+            ) : null}
+            <TaskStatusDot status={mainStatus} />
+          </div>
+        </div>
+        {part.description ? (
+          <p className="mt-1 text-[11px] leading-snug text-muted-foreground">
+            {part.description}
+          </p>
+        ) : null}
+        {part.workflow_name ? (
+          <p className="mt-1 font-mono text-[10px] text-muted-foreground/80">
+            {part.workflow_name}
+          </p>
+        ) : null}
+      </div>
+    </>
+  );
+
+  if (expandable) {
+    return (
+      <CollapsibleTrigger
+        className={cn(
+          "flex w-full gap-3 border-b border-border/60 px-3 py-2.5 text-left outline-none",
+          "hover:bg-muted/40 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        )}
+      >
+        {inner}
+      </CollapsibleTrigger>
+    );
+  }
+
+  return (
+    <div className="flex gap-3 border-b border-border/60 px-3 py-2.5">
+      {inner}
+    </div>
+  );
+}
+
+export function TaskPart({ part }: { part: TaskWirePart }) {
+  const projectId = useProjectStore((s) => s.projectData?.id ?? "");
+  const branch = useVersioningStore((s) => s.branch);
+  const ref = useVersioningStore((s) => s.checkedOutCommitId);
+  const compareTo = useVersioningStore((s) => s.compareToCommitId);
+
+  const embeddedSubTasks: TaskSubWire[] = useMemo(
+    () => part.sub_tasks ?? [],
+    [part.sub_tasks],
+  );
+  const expectSubtasks = useMemo(
+    () => embeddedSubTasks.length > 0 || (part.sub_task_count ?? 0) > 0,
+    [embeddedSubTasks.length, part.sub_task_count],
+  );
+
+  const fetchEnabled =
+    Boolean(projectId) && !isAgentPreviewTaskId(part.task_id);
+
+  const subtasksQuery = useQuery(
+    agentTaskSubtasksQueryOptions(
+      projectId,
+      part.task_id,
+      branch,
+      ref,
+      compareTo,
+      fetchEnabled,
+    ),
+  );
+
+  const subTasks: TaskSubWire[] = useMemo(() => {
+    const rows = subtasksQuery.data?.items;
+    if (subtasksQuery.isSuccess && rows && rows.length > 0) {
+      return rows;
+    }
+    return embeddedSubTasks;
+  }, [embeddedSubTasks, subtasksQuery.data?.items, subtasksQuery.isSuccess]);
+
+  const listLoading =
+    fetchEnabled && subtasksQuery.isPending && embeddedSubTasks.length === 0;
+
+  const MainIcon = resolveTaskIcon(part.icon);
+  const mainStatus = toVisualStatus(part.state);
+  const expandable = expectSubtasks || subTasks.length > 0;
+
+  const [open, setOpen] = useState(() => defaultExpanded(part));
+
+  if (!expandable) {
+    return (
+      <div className="overflow-hidden rounded-xl border border-border/80 bg-card text-card-foreground shadow-sm">
+        <TaskPartHeader
+          part={part}
+          mainStatus={mainStatus}
+          MainIcon={MainIcon}
+          expandable={false}
+          open={false}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <Collapsible
+      open={open}
+      onOpenChange={setOpen}
+      className="overflow-hidden rounded-xl border border-border/80 bg-card text-card-foreground shadow-sm"
+    >
+      <TaskPartHeader
+        part={part}
+        mainStatus={mainStatus}
+        MainIcon={MainIcon}
+        expandable
+        open={open}
+      />
+      <CollapsibleContent>
+        <TaskSubTaskList
+          taskId={part.task_id}
+          subTasks={subTasks}
+          loading={listLoading}
+        />
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/TaskStatusDot.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/TaskStatusDot.tsx
new file mode 100644
index 00000000..413ec1f2
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/TaskStatusDot.tsx
@@ -0,0 +1,22 @@
+import { CheckCircle2, Circle, XCircle } from "lucide-react";
+import type { VisualStatus } from "./taskStatus";
+
+export function TaskStatusDot({ status }: { status: VisualStatus }) {
+  if (status === "completed") {
+    return (
+      <CheckCircle2
+        className="h-4 w-4 shrink-0 text-emerald-600 dark:text-emerald-400"
+        aria-hidden
+      />
+    );
+  }
+  if (status === "error") {
+    return <XCircle className="h-4 w-4 shrink-0 text-destructive" aria-hidden />;
+  }
+  return (
+    <Circle
+      className="h-3.5 w-3.5 shrink-0 text-muted-foreground/70"
+      aria-hidden
+    />
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/TaskSubTaskList.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/TaskSubTaskList.tsx
new file mode 100644
index 00000000..3fd15447
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/TaskSubTaskList.tsx
@@ -0,0 +1,25 @@
+import { SubTaskRow } from "./SubTaskRow";
+import type { TaskSubWire } from "./types";
+
+/** Fixed viewport; inner list scrolls when there are many sub-tasks. */
+const SUB_LIST_HEIGHT = "h-40";
+
+export function TaskSubTaskList({
+  taskId,
+  subTasks,
+}: {
+  taskId: string;
+  subTasks: TaskSubWire[];
+}) {
+  if (subTasks.length === 0) return null;
+
+  return (
+    <div
+      className={`${SUB_LIST_HEIGHT} space-y-2 overflow-y-auto overscroll-contain px-3 py-2.5 [scrollbar-gutter:stable]`}
+    >
+      {subTasks.map((sub, i) => (
+        <SubTaskRow key={`${taskId}-sub-${i}`} sub={sub} />
+      ))}
+    </div>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/index.ts b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/index.ts
new file mode 100644
index 00000000..f263f71b
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/index.ts
@@ -0,0 +1,2 @@
+export { TaskPart } from "./TaskPart";
+export type { TaskSubWire, TaskWirePart } from "./types";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/subTaskLabel.ts b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/subTaskLabel.ts
new file mode 100644
index 00000000..99d1776c
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/subTaskLabel.ts
@@ -0,0 +1,5 @@
+import type { TaskSubWire } from "./types";
+
+export function subTaskLabel(sub: TaskSubWire): string {
+  return sub.title ?? sub.name ?? "Sub-task";
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/taskIcons.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/taskIcons.tsx
new file mode 100644
index 00000000..6ff04853
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/taskIcons.tsx
@@ -0,0 +1,16 @@
+import type { LucideIcon } from "lucide-react";
+import { Bot, Cpu, Layers, Sparkles, Workflow } from "lucide-react";
+
+const ICONS: Record<string, LucideIcon> = {
+  sparkles: Sparkles,
+  cpu: Cpu,
+  workflow: Workflow,
+  layers: Layers,
+  bot: Bot,
+};
+
+export function resolveTaskIcon(name?: string): LucideIcon {
+  if (!name?.trim()) return Layers;
+  const key = name.trim().toLowerCase();
+  return ICONS[key] ?? Layers;
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/taskStatus.ts b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/taskStatus.ts
new file mode 100644
index 00000000..504f1731
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/taskStatus.ts
@@ -0,0 +1,22 @@
+export type VisualStatus = "completed" | "error" | "pending";
+
+export function toVisualStatus(state: string | undefined): VisualStatus {
+  const s = (state ?? "").toLowerCase();
+  if (
+    s.includes("complete") ||
+    s === "done" ||
+    s.includes("success") ||
+    s === "skipped"
+  ) {
+    return "completed";
+  }
+  if (
+    s.includes("fail") ||
+    s.includes("error") ||
+    s.includes("cancel") ||
+    s === "failed"
+  ) {
+    return "error";
+  }
+  return "pending";
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/types.ts b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/types.ts
new file mode 100644
index 00000000..8565b26a
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/task/types.ts
@@ -0,0 +1,23 @@
+export interface TaskSubWire {
+  id?: string;
+  title?: string;
+  /** Backend `SubTask` wire uses `name`. */
+  name?: string;
+  description?: string;
+  state?: string;
+}
+
+export interface TaskWirePart {
+  type: "task";
+  task_id: string;
+  title: string;
+  description?: string;
+  state: string;
+  progress?: number;
+  workflow_name?: string;
+  /** Optional Lucide icon name (e.g. "sparkles", "cpu"). */
+  icon?: string;
+  sub_tasks?: TaskSubWire[];
+  /** Hint when sub-tasks exist in DB but are not embedded in the part. */
+  sub_task_count?: number;
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/walkthrough/WalkthroughPart.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/walkthrough/WalkthroughPart.tsx
new file mode 100644
index 00000000..cfd32c51
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/walkthrough/WalkthroughPart.tsx
@@ -0,0 +1,66 @@
+import { Map } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import { useWalkthroughStore } from "@/features/Dashboard/features/Agent/walkthrough/store/useWalkthroughStore";
+import type { WalkthroughWirePart } from "./types";
+
+export function WalkthroughPart({ part }: { part: WalkthroughWirePart }) {
+  const controls = useWalkthroughStore((s) => s.controls);
+  const status = useWalkthroughStore((s) => s.status);
+  const loadedId = useWalkthroughStore((s) => s.walkthrough?.meta.id);
+  const isLoaded = loadedId === part.walkthrough.meta.id;
+  const canStart = Boolean(controls);
+
+  return (
+    <div className="overflow-hidden rounded-lg border border-border bg-muted/25">
+      <div className="flex gap-3 border-b border-border/60 px-3 py-2.5">
+        <div className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-violet-500/10 text-violet-700 dark:text-violet-300">
+          <Map className="h-4 w-4" strokeWidth={2} aria-hidden />
+        </div>
+        <div className="min-w-0 flex-1 text-left">
+          <p className="text-[13px] font-semibold leading-tight tracking-tight text-foreground">
+            {part.title}
+          </p>
+          {part.description ? (
+            <p className="mt-1 text-[11px] leading-snug text-muted-foreground">
+              {part.description}
+            </p>
+          ) : null}
+          {part.workflow_name ? (
+            <p className="mt-1 font-mono text-[10px] text-muted-foreground/80">
+              {part.workflow_name}
+            </p>
+          ) : null}
+          <p className="mt-1 text-[10px] text-muted-foreground">
+            {part.walkthrough.steps.length} step
+            {part.walkthrough.steps.length === 1 ? "" : "s"} · Open the{" "}
+            <span className="font-medium text-foreground">Canvas</span> tab,
+            then play from the bar below.
+          </p>
+        </div>
+      </div>
+      <div className="flex flex-wrap items-center gap-2 px-3 py-2">
+        <Button
+          type="button"
+          size="sm"
+          variant="default"
+          disabled={!canStart}
+          className={cn("h-8 text-xs", !canStart && "opacity-60")}
+          onClick={() => void controls?.load(part.walkthrough)}
+          title={
+            canStart
+              ? "Load this tour into the walkthrough player"
+              : "Open a project canvas so the walkthrough engine is available"
+          }
+        >
+          Load tour
+        </Button>
+        {isLoaded ? (
+          <span className="text-[10px] text-muted-foreground tabular-nums">
+            Player: {status}
+          </span>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/walkthrough/index.ts b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/walkthrough/index.ts
new file mode 100644
index 00000000..5c600ad9
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/walkthrough/index.ts
@@ -0,0 +1,2 @@
+export { WalkthroughPart } from "./WalkthroughPart";
+export type { WalkthroughWirePart } from "./types";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/walkthrough/types.ts b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/walkthrough/types.ts
new file mode 100644
index 00000000..179fdd7d
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/chat/parts/walkthrough/types.ts
@@ -0,0 +1,12 @@
+import type { Walkthrough } from "@/features/Dashboard/features/Agent/walkthrough/types/walkthrough";
+
+export interface WalkthroughWirePart {
+  type: "walkthrough";
+  /** Optional stable id for analytics / future hydration */
+  tour_id?: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  workflow_name?: string;
+  walkthrough: Walkthrough;
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/messages/Markdown/AssistantMarkdown.tsx b/src/frontend/src/features/Dashboard/features/Agent/components/messages/Markdown/AssistantMarkdown.tsx
new file mode 100644
index 00000000..605ce5a8
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/messages/Markdown/AssistantMarkdown.tsx
@@ -0,0 +1,137 @@
+import { cn } from "@/lib/utils";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import type { Components } from "react-markdown";
+
+const markdownComponents: Components = {
+  p: ({ children, className, ...props }) => (
+    <p className={cn("mb-2 text-xs leading-relaxed last:mb-0", className)} {...props}>
+      {children}
+    </p>
+  ),
+  ul: ({ children, className, ...props }) => (
+    <ul className={cn("mb-2 list-disc pl-4 text-xs leading-relaxed last:mb-0", className)} {...props}>
+      {children}
+    </ul>
+  ),
+  ol: ({ children, className, ...props }) => (
+    <ol className={cn("mb-2 list-decimal pl-4 text-xs leading-relaxed last:mb-0", className)} {...props}>
+      {children}
+    </ol>
+  ),
+  li: ({ children, className, ...props }) => (
+    <li className={cn("mt-0.5", className)} {...props}>
+      {children}
+    </li>
+  ),
+  a: ({ href, children, className, ...props }) => {
+    const external = href?.startsWith("http://") || href?.startsWith("https://");
+    return (
+      <a
+        href={href}
+        className={cn("text-primary underline underline-offset-2 hover:opacity-90", className)}
+        target={external ? "_blank" : undefined}
+        rel={external ? "noopener noreferrer" : undefined}
+        {...props}
+      >
+        {children}
+      </a>
+    );
+  },
+  code: ({ className, children, ...props }) => {
+    const inline = !className;
+    if (inline) {
+      return (
+        <code
+          className={cn(
+            "rounded bg-muted px-1 py-0.5 font-mono text-[11px] text-foreground",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+        </code>
+      );
+    }
+    return (
+      <code className={cn("font-mono text-[11px]", className)} {...props}>
+        {children}
+      </code>
+    );
+  },
+  pre: ({ children, className, ...props }) => (
+    <pre
+      className={cn(
+        "mb-2 max-w-full overflow-x-auto rounded-md border border-border bg-muted/80 p-2 text-[11px] last:mb-0",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </pre>
+  ),
+  blockquote: ({ children, className, ...props }) => (
+    <blockquote
+      className={cn("mb-2 border-l-2 border-border pl-3 text-muted-foreground last:mb-0", className)}
+      {...props}
+    >
+      {children}
+    </blockquote>
+  ),
+  h1: ({ children, className, ...props }) => (
+    <h1 className={cn("mb-2 text-sm font-semibold last:mb-0", className)} {...props}>
+      {children}
+    </h1>
+  ),
+  h2: ({ children, className, ...props }) => (
+    <h2 className={cn("mb-2 text-xs font-semibold last:mb-0", className)} {...props}>
+      {children}
+    </h2>
+  ),
+  h3: ({ children, className, ...props }) => (
+    <h3 className={cn("mb-1.5 text-xs font-semibold last:mb-0", className)} {...props}>
+      {children}
+    </h3>
+  ),
+  table: ({ children, className, ...props }) => (
+    <div className="mb-2 max-w-full overflow-x-auto last:mb-0">
+      <table className={cn("w-full border-collapse border border-border text-xs", className)} {...props}>
+        {children}
+      </table>
+    </div>
+  ),
+  th: ({ children, className, ...props }) => (
+    <th className={cn("border border-border bg-muted/60 px-2 py-1 text-left font-semibold", className)} {...props}>
+      {children}
+    </th>
+  ),
+  td: ({ children, className, ...props }) => (
+    <td className={cn("border border-border px-2 py-1 align-top", className)} {...props}>
+      {children}
+    </td>
+  ),
+  hr: ({ className, ...props }) => (
+    <hr className={cn("my-3 border-border", className)} {...props} />
+  ),
+};
+
+export interface AssistantMarkdownProps {
+  text: string;
+  className?: string;
+}
+
+/** Renders assistant message body as GitHub-flavored Markdown. */
+export function AssistantMarkdown({ text, className }: AssistantMarkdownProps) {
+  return (
+    <div
+      className={cn(
+        "agent-markdown text-foreground [&>*:first-child]:mt-0",
+        className,
+      )}
+    >
+      <ReactMarkdown remarkPlugins={[remarkGfm]} components={markdownComponents}>
+        {text}
+      </ReactMarkdown>
+    </div>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/messages/Markdown/index.ts b/src/frontend/src/features/Dashboard/features/Agent/components/messages/Markdown/index.ts
new file mode 100644
index 00000000..8fd980c1
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/messages/Markdown/index.ts
@@ -0,0 +1 @@
+export { AssistantMarkdown, type AssistantMarkdownProps } from "./AssistantMarkdown";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/messages/index.ts b/src/frontend/src/features/Dashboard/features/Agent/components/messages/index.ts
new file mode 100644
index 00000000..dcbeff00
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/messages/index.ts
@@ -0,0 +1,2 @@
+export { wireMessagePlainText } from "./wireText";
+export { ChatContainer, type ChatContainerProps } from "../chat";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/components/messages/wireText.ts b/src/frontend/src/features/Dashboard/features/Agent/components/messages/wireText.ts
new file mode 100644
index 00000000..a2ea0ade
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/components/messages/wireText.ts
@@ -0,0 +1,14 @@
+import type { WireMessage, WireTextPart } from "@/types/agent";
+
+function isWireTextPart(p: unknown): p is WireTextPart {
+  return (
+    typeof p === "object" &&
+    p !== null &&
+    (p as WireTextPart).type === "text" &&
+    typeof (p as WireTextPart).text === "string"
+  );
+}
+
+export function wireMessagePlainText(message: WireMessage): string {
+  return message.parts.filter(isWireTextPart).map((p) => p.text).join("\n");
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/constants/agentPreviewConversation.ts b/src/frontend/src/features/Dashboard/features/Agent/constants/agentPreviewConversation.ts
new file mode 100644
index 00000000..c2ed6d6b
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/constants/agentPreviewConversation.ts
@@ -0,0 +1,268 @@
+import type { Walkthrough } from "@/features/Dashboard/features/Agent/walkthrough/types/walkthrough";
+import type { WireConversation } from "@/types/agent";
+
+/** Local-only conversation id: skips REST hydration and socket room join. */
+export const AGENT_UI_PREVIEW_CONVERSATION_ID = "__vnoc_agent_ui_preview__";
+
+/** Example canvas node ids for the preview walkthrough (must exist in the loaded project tree). */
+export const AGENT_PREVIEW_WALKTHROUGH_FILE_NODE_ID =
+  "FileSchema/372f9c6e-7ea2-44ed-9678-b56a0ca8c3f1";
+export const AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID =
+  "FunctionSchema/11b1c19e-faa5-44f1-836a-c1ef80d43c87";
+
+/**
+ * Sample tour: file node, function node, then Monaco line highlights (lines 3–5 and line 4).
+ * Line numbers assume a typical small function body (e.g. declaration on line 2, body from line 3).
+ */
+export const AGENT_PREVIEW_CANVAS_WALKTHROUGH: Walkthrough = {
+  meta: {
+    id: "preview-canvas-two-step",
+    title: "Canvas quick tour",
+    description:
+      "Sample walkthrough: file, function, then inline code highlights with line-anchored popovers.",
+    version: 2,
+  },
+  steps: [
+    {
+      id: "preview-step-file",
+      actions: [
+        {
+          type: "pan-canvas",
+          to: { nodeId: AGENT_PREVIEW_WALKTHROUGH_FILE_NODE_ID },
+        },
+        {
+          type: "focus-node",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FILE_NODE_ID,
+        },
+      ],
+      popover: {
+        title: "File node",
+        body: "This file sits in your project tree. Use the walkthrough bar on the Canvas tab to play or step through.",
+        anchor: {
+          type: "node",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FILE_NODE_ID,
+        },
+        side: "right",
+      },
+    },
+    {
+      id: "preview-step-function",
+      actions: [
+        { type: "clear-highlight" },
+        {
+          type: "pan-canvas",
+          to: { nodeId: AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID },
+        },
+        {
+          type: "focus-node",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID,
+        },
+      ],
+      popover: {
+        title: "Function node",
+        body: "This is the target function. Next we open its code and spotlight part of the body in the Monaco editor.",
+        anchor: {
+          type: "node",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID,
+        },
+        side: "right",
+      },
+    },
+    {
+      id: "preview-step-function-lines-3-5",
+      actions: [
+        { type: "clear-highlight" },
+        {
+          type: "focus-node",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID,
+        },
+        {
+          type: "show-code",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID,
+        },
+        {
+          type: "highlight-code",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID,
+          lines: [{ from: 3, to: 5 }],
+        },
+      ],
+      popover: {
+        title: "Function body (lines 3–5)",
+        body: "The walkthrough highlights the first lines of the function body. Monaco decorations mark the range; the amber frame tracks it while you scroll.",
+        anchor: {
+          type: "code-line",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID,
+          line: 4,
+        },
+        side: "right",
+      },
+    },
+    {
+      id: "preview-step-function-line-4",
+      actions: [
+        { type: "clear-highlight" },
+        {
+          type: "highlight-code",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID,
+          lines: [{ from: 4, to: 4 }],
+        },
+      ],
+      popover: {
+        title: "Line 4",
+        body: "A narrower highlight on a single line. The popover anchor follows this line in the editor viewport.",
+        anchor: {
+          type: "code-line",
+          nodeId: AGENT_PREVIEW_WALKTHROUGH_FUNCTION_NODE_ID,
+          line: 4,
+        },
+        side: "right",
+      },
+    },
+  ],
+};
+
+export function isAgentPreviewConversationId(id: string | null | undefined): boolean {
+  return id === AGENT_UI_PREVIEW_CONVERSATION_ID;
+}
+
+/** Preview task parts use synthetic ids; skip real task HTTP calls. */
+export function isAgentPreviewTaskId(taskId: string | null | undefined): boolean {
+  return Boolean(taskId && taskId.startsWith("preview-"));
+}
+
+const SAMPLE_MARKDOWN = `## Markdown check
+
+**Bold**, *italic*, and \`inline code\`.
+
+### Lists
+- First item
+- Second item
+- Third item
+
+### Code
+
+\`\`\`bash
+sudo apt-get install markdown-editor
+\`\`\`
+
+\`\`\`python
+print("Hello, World!")
+\`\`\`
+
+### Quote
+
+> Short blockquote for styling.
+
+---
+
+Plain paragraph after a rule.
+`;
+
+export function createAgentUiPreviewWire(): WireConversation {
+  const now = new Date().toISOString();
+  return {
+    id: AGENT_UI_PREVIEW_CONVERSATION_ID,
+    title: "UI preview (sample)",
+    description:
+      "Local fixture: canvas walkthrough, markdown, and task layout",
+    message_count: 4,
+    has_active_task: true,
+    created_at: now,
+    updated_at: now,
+    messages: [
+      {
+        id: "preview-user-1",
+        role: "user",
+        sequence: 0,
+        parts: [
+          {
+            type: "text",
+            text: "Show a canvas walkthrough, markdown formatting, and a task with sub-tasks.",
+          },
+        ],
+        created_at: now,
+      },
+      {
+        id: "preview-assistant-walkthrough",
+        role: "assistant",
+        sequence: 1,
+        parts: [
+          {
+            type: "walkthrough",
+            tour_id: "preview-canvas-two-step",
+            title: "Guided canvas tour",
+            description:
+              "File and function nodes, then Monaco highlights on lines 3–5 and line 4 with popovers. Load the tour, open Canvas, press play.",
+            icon: "map",
+            workflow_name: "walkthrough:canvas-preview",
+            walkthrough: AGENT_PREVIEW_CANVAS_WALKTHROUGH,
+          },
+        ],
+        created_at: now,
+        model: "preview",
+      },
+      {
+        id: "preview-assistant-1",
+        role: "assistant",
+        sequence: 2,
+        parts: [
+          { type: "text", text: SAMPLE_MARKDOWN },
+          {
+            type: "task",
+            task_id: "preview-task-1",
+            title: "API middleware construction",
+            description: "Secure routing and validation for public endpoints",
+            state: "running",
+            icon: "sparkles",
+            workflow_name: "workflow:build",
+            sub_task_count: 1,
+            sub_tasks: [
+              {
+                title: "Scan environment",
+                description: "Detect runtime, ports, and dependencies",
+                state: "completed",
+              },
+            ],
+          },
+        ],
+        created_at: now,
+        model: "preview",
+      },
+      {
+        id: "preview-assistant-2",
+        role: "assistant",
+        sequence: 3,
+        parts: [
+          {
+            type: "task",
+            task_id: "preview-task-1",
+            title: "API middleware construction",
+            description: "Secure routing and validation for public endpoints",
+            state: "running",
+            icon: "sparkles",
+            workflow_name: "workflow:build",
+            sub_task_count: 1,
+            sub_tasks: [
+              {
+                title: "Scan environment",
+                description: "Detect runtime, ports, and dependencies",
+                state: "completed",
+              },
+              {
+                title: "Generate secure logic",
+                description: "Apply authn / authz templates",
+                state: "pending",
+              },
+              {
+                title: "Validate deployment",
+                description: "Dry-run config against staging",
+                state: "failed",
+              },
+            ],
+          },
+        ],
+        created_at: now,
+      },
+    ],
+  };
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/fixtures/conversations.ts b/src/frontend/src/features/Dashboard/features/Agent/fixtures/conversations.ts
deleted file mode 100644
index 0cf38215..00000000
--- a/src/frontend/src/features/Dashboard/features/Agent/fixtures/conversations.ts
+++ /dev/null
@@ -1,173 +0,0 @@
-import type { Conversation } from "../types/conversation";
-
-export const conversationFixtures: Conversation[] = [
-  {
-    id: "chat-1",
-    title: "Analyze dependency graph",
-    date: "Feb 26, 2026",
-    duration: "18 min",
-    messages: [
-      {
-        id: "chat-1-user-1",
-        role: "user",
-        parts: [
-          {
-            type: "text",
-            text: "Can you inspect the dependency graph for cyclic modules?",
-          },
-        ],
-      },
-      {
-        id: "chat-1-assistant-1",
-        role: "assistant",
-        parts: [
-          { type: "text", text: "I found two circular dependency clusters." },
-          {
-            type: "event",
-            event: { at: 0, type: "focus", payload: { nodeId: "api/router" } },
-          },
-          {
-            type: "event",
-            event: { at: 1200, type: "click", payload: { nodeId: "utils/log" } },
-          },
-        ],
-      },
-    ],
-  },
-  {
-    id: "chat-2",
-    title: "Explain selected node changes",
-    date: "Feb 25, 2026",
-    duration: "1 hr 05 min",
-    messages: [
-      {
-        id: "chat-2-user-1",
-        role: "user",
-        parts: [
-          {
-            type: "text",
-            text: "Walk me through the selected node updates since last commit.",
-          },
-        ],
-      },
-      {
-        id: "chat-2-assistant-1",
-        role: "assistant",
-        parts: [
-          {
-            type: "text",
-            text: "The node had one interface rename and two dependency additions.",
-          },
-          {
-            type: "event",
-            event: { at: 0, type: "focus", payload: { nodeId: "services/auth" } },
-          },
-          {
-            type: "event",
-            event: { at: 850, type: "wait", payload: { ms: 1500 } },
-          },
-        ],
-      },
-    ],
-  },
-  {
-    id: "chat-3",
-    title: "Summarize version diff",
-    date: "Feb 24, 2026",
-    duration: "42 min",
-    messages: [
-      {
-        id: "chat-3-user-1",
-        role: "user",
-        parts: [
-          {
-            type: "text",
-            text: "Give me a concise summary for this version diff.",
-          },
-        ],
-      },
-      {
-        id: "chat-3-assistant-1",
-        role: "assistant",
-        parts: [
-          {
-            type: "text",
-            text: "This revision mostly removes dead paths and tightens typing.",
-          },
-          {
-            type: "event",
-            event: { at: 500, type: "click", payload: { nodeId: "hooks/useTree" } },
-          },
-        ],
-      },
-    ],
-  },
-  {
-    id: "chat-4",
-    title: "Node spotlight demo",
-    date: "Feb 26, 2026",
-    duration: "3 min",
-    messages: [
-      {
-        id: "chat-4-assistant-1",
-        role: "assistant",
-        parts: [
-          {
-            type: "text",
-            text: "File node highlight: `main` (node_type: file). ID: FileSchema/372f9c6e-7ea2-44ed-9678-b56a0ca8c3f1.",
-          },
-          {
-            type: "event",
-            event: {
-              at: 0,
-              type: "focus",
-              payload: {
-                nodeId: "FileSchema/372f9c6e-7ea2-44ed-9678-b56a0ca8c3f1",
-              },
-            },
-          },
-        ],
-      },
-      {
-        id: "chat-4-assistant-2",
-        role: "assistant",
-        parts: [
-          {
-            type: "text",
-            text: "Call node highlight: `main` (node_type: call). ID: CallSchema/9a1dc48d-1099-4fcb-8610-d266765bf6f8. Target function: FunctionSchema/11b1c19e-faa5-44f1-836a-c1ef80d43c87.",
-          },
-          {
-            type: "event",
-            event: {
-              at: 1200,
-              type: "focus",
-              payload: {
-                nodeId: "CallSchema/9a1dc48d-1099-4fcb-8610-d266765bf6f8",
-              },
-            },
-          },
-        ],
-      },
-      {
-        id: "chat-4-assistant-3",
-        role: "assistant",
-        parts: [
-          {
-            type: "text",
-            text: "Function node highlight: `runner` (node_type: function). ID: FunctionSchema/fb04a14a-2746-4212-8bdd-cb70779c416c. qname: sample_project.main.runner.",
-          },
-          {
-            type: "event",
-            event: {
-              at: 2400,
-              type: "focus",
-              payload: {
-                nodeId: "FunctionSchema/fb04a14a-2746-4212-8bdd-cb70779c416c",
-              },
-            },
-          },
-        ],
-      },
-    ],
-  },
-];
diff --git a/src/frontend/src/features/Dashboard/features/Agent/hooks/useAgentChatSend.ts b/src/frontend/src/features/Dashboard/features/Agent/hooks/useAgentChatSend.ts
new file mode 100644
index 00000000..ee3c552b
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/hooks/useAgentChatSend.ts
@@ -0,0 +1,63 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+import queryKeys from "@/lib/queryKeys";
+import useProjectStore from "@/features/Dashboard/store/useProjectStore";
+import { agentApi } from "@/services/agent/api";
+import { useSocket } from "@/services/socket";
+import { isAgentPreviewConversationId } from "../constants/agentPreviewConversation";
+import { useAgentLiveStore } from "../live/store/useAgentLiveStore";
+import { useAgentUiStore } from "../store/useAgentUiStore";
+
+/**
+ * Sends a user message. If there is no active conversation id (new chat), creates
+ * the conversation on the server first, hydrates wire state, joins the socket room,
+ * then posts the message.
+ */
+export function useAgentChatSend() {
+  const queryClient = useQueryClient();
+  const { socket } = useSocket();
+
+  return useMutation({
+    mutationFn: async (text: string) => {
+      const projectId = useProjectStore.getState().projectData?.id;
+      if (!projectId) {
+        throw new Error("No project loaded; cannot use agent chat.");
+      }
+
+      let cid = useAgentUiStore.getState().backendConversationId;
+      if (isAgentPreviewConversationId(cid)) {
+        toast.message("Exit the UI sample", {
+          description: "Start a new chat or pick a real conversation to send messages.",
+        });
+        throw new Error("Cannot send while viewing the local UI sample.");
+      }
+      if (!cid) {
+        const meta = await agentApi.createConversation(projectId, {
+          title: "New conversation",
+          description: "",
+        });
+        cid = meta.id;
+        useAgentUiStore.getState().setBackendConversationId(cid);
+        const wire = await agentApi.hydrateConversation(projectId, cid);
+        useAgentLiveStore.getState().setWire(wire);
+        if (socket?.connected) {
+          socket.emit("join_conversation", cid);
+        }
+        void queryClient.invalidateQueries({
+          queryKey: queryKeys.agent.conversations.all(),
+        });
+      }
+      return agentApi.sendMessage(projectId, {
+        conversation_id: cid,
+        parts: [{ type: "text", text }],
+      });
+    },
+    onSuccess: () => {
+      // Sidebar summaries only. Conversation detail stays live via `conversation:patch`
+      // and the live store; refetching detail here races with streaming and wipes placeholders.
+      void queryClient.invalidateQueries({
+        queryKey: queryKeys.agent.conversations.all(),
+      });
+    },
+  });
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/live/hooks/index.ts b/src/frontend/src/features/Dashboard/features/Agent/live/hooks/index.ts
new file mode 100644
index 00000000..0fb60110
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/live/hooks/index.ts
@@ -0,0 +1,3 @@
+export { useAgentChatSession } from "./useAgentChatSession";
+export { useAgentConversationSocket } from "./useAgentConversationSocket";
+export { useAgentConversationSync } from "./useAgentConversationSync";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/live/hooks/useAgentChatSession.ts b/src/frontend/src/features/Dashboard/features/Agent/live/hooks/useAgentChatSession.ts
new file mode 100644
index 00000000..d973df27
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/live/hooks/useAgentChatSession.ts
@@ -0,0 +1,13 @@
+import { useAgentConversationSocket } from "./useAgentConversationSocket";
+import { useAgentConversationSync } from "./useAgentConversationSync";
+
+/**
+ * Full live session: REST hydration + WebSocket room, patches, and streams.
+ */
+export function useAgentChatSession(
+  backendConversationId: string | null,
+  projectId: string,
+) {
+  useAgentConversationSync(backendConversationId, projectId);
+  useAgentConversationSocket(backendConversationId, projectId);
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/live/hooks/useAgentConversationSocket.ts b/src/frontend/src/features/Dashboard/features/Agent/live/hooks/useAgentConversationSocket.ts
new file mode 100644
index 00000000..140bef3d
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/live/hooks/useAgentConversationSocket.ts
@@ -0,0 +1,131 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { useEffect, useRef } from "react";
+import { useEffectEvent } from "@/lib/react/useEffectEvent";
+import { useConversationRoom, useSocket } from "@/services/socket";
+import type {
+  ConversationPatchPayload,
+  StreamChunkPayload,
+  StreamEndPayload,
+  StreamErrorPayload,
+  StreamStartPayload,
+} from "@/types/agent";
+import { useAgentLiveStore } from "../store/useAgentLiveStore";
+
+/**
+ * Subscribes to agent stream + patch events for one conversation.
+ * Uses `useEffectEvent` so handlers stay fresh without re-subscribing on every render.
+ */
+export function useAgentConversationSocket(
+  conversationId: string | null,
+  projectId: string,
+) {
+  const { socket } = useSocket();
+  const queryClient = useQueryClient();
+
+  useConversationRoom(conversationId ?? undefined);
+
+  const onPatch = useEffectEvent((payload: ConversationPatchPayload) => {
+    if (!conversationId || payload.conversation_id !== conversationId) return;
+    useAgentLiveStore.getState().applyServerPatches(payload.patches);
+  });
+
+  const onStreamStart = useEffectEvent((payload: StreamStartPayload) => {
+    if (!conversationId || payload.conversation_id !== conversationId) return;
+    useAgentLiveStore.getState().onStreamStart(payload);
+  });
+
+  const onStreamChunk = useEffectEvent((payload: StreamChunkPayload) => {
+    if (!conversationId) return;
+    useAgentLiveStore.getState().onStreamChunk(payload, conversationId);
+  });
+
+  const onStreamEnd = useEffectEvent((payload: StreamEndPayload) => {
+    if (!conversationId) return;
+    useAgentLiveStore.getState().onStreamEnd(payload, conversationId);
+  });
+
+  const onStreamError = useEffectEvent((payload: StreamErrorPayload) => {
+    if (!conversationId) return;
+    useAgentLiveStore.getState().onStreamError(payload, conversationId);
+  });
+
+  useEffect(() => {
+    if (!socket) return;
+
+    const patch = (p: ConversationPatchPayload) => onPatch(p);
+    const start = (p: StreamStartPayload) => onStreamStart(p);
+    const chunk = (p: StreamChunkPayload) => onStreamChunk(p);
+    const end = (p: StreamEndPayload) => onStreamEnd(p);
+    const err = (p: StreamErrorPayload) => onStreamError(p);
+
+    socket.on("conversation:patch", patch);
+    socket.on("stream:start", start);
+    socket.on("stream:chunk", chunk);
+    socket.on("stream:end", end);
+    socket.on("stream:error", err);
+
+    return () => {
+      socket.off("conversation:patch", patch);
+      socket.off("stream:start", start);
+      socket.off("stream:chunk", chunk);
+      socket.off("stream:end", end);
+      socket.off("stream:error", err);
+    };
+    // Handlers are `useEffectEvent` — stable; bind as soon as the client instance exists.
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- onPatch/onStream* are EffectEvents
+  }, [socket]);
+
+  const patchFailed = useAgentLiveStore((s) => s.patchApplyFailed);
+
+  useEffect(() => {
+    if (!patchFailed || !conversationId || !projectId) return;
+    void queryClient.invalidateQueries({
+      predicate: (q) => {
+        const k = q.queryKey;
+        return (
+          Array.isArray(k) &&
+          k[0] === "agent" &&
+          k[1] === "conversations" &&
+          k[2] === "detail" &&
+          k[3] === projectId &&
+          k[4] === conversationId
+        );
+      },
+    });
+    useAgentLiveStore.getState().clearPatchFailure();
+  }, [patchFailed, conversationId, projectId, queryClient]);
+
+  const sawDisconnect = useRef(false);
+  useEffect(() => {
+    if (!socket || !conversationId || !projectId) return;
+
+    const onDisconnect = () => {
+      sawDisconnect.current = true;
+    };
+
+    const onConnect = () => {
+      if (!sawDisconnect.current) return;
+      sawDisconnect.current = false;
+      void queryClient.invalidateQueries({
+        predicate: (q) => {
+          const k = q.queryKey;
+          return (
+            Array.isArray(k) &&
+            k[0] === "agent" &&
+            k[1] === "conversations" &&
+            k[2] === "detail" &&
+            k[3] === projectId &&
+            k[4] === conversationId
+          );
+        },
+      });
+    };
+
+    socket.on("disconnect", onDisconnect);
+    socket.on("connect", onConnect);
+    return () => {
+      socket.off("disconnect", onDisconnect);
+      socket.off("connect", onConnect);
+    };
+  }, [socket, conversationId, projectId, queryClient]);
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/live/hooks/useAgentConversationSync.ts b/src/frontend/src/features/Dashboard/features/Agent/live/hooks/useAgentConversationSync.ts
new file mode 100644
index 00000000..ddfad7af
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/live/hooks/useAgentConversationSync.ts
@@ -0,0 +1,55 @@
+import { useQuery } from "@tanstack/react-query";
+import { useEffect, useRef } from "react";
+import { useVersioningStore } from "@/features/Dashboard/features/Versioning/store/useVersioningStore";
+import { agentConversationHydrationQueryOptions } from "@/services/agent";
+import { useAgentLiveStore } from "../store/useAgentLiveStore";
+
+/**
+ * When leaving a live conversation, clear the store once.
+ */
+function useResetLiveWhenLeaving(conversationId: string | null) {
+  const prev = useRef<string | null>(null);
+
+  useEffect(() => {
+    const was = prev.current;
+    prev.current = conversationId;
+    if (was !== null && conversationId === null) {
+      useAgentLiveStore.getState().reset();
+    }
+  }, [conversationId]);
+}
+
+/**
+ * Push TanStack Query snapshot into the live store only when a fetch finishes
+ * (`dataUpdatedAt`), not on every `query.data` reference change.
+ */
+export function useAgentConversationSync(
+  conversationId: string | null,
+  projectId: string,
+) {
+  useResetLiveWhenLeaving(conversationId);
+
+  const branch = useVersioningStore((s) => s.branch);
+  const ref = useVersioningStore((s) => s.checkedOutCommitId);
+  const compareTo = useVersioningStore((s) => s.compareToCommitId);
+
+  const query = useQuery(
+    agentConversationHydrationQueryOptions(
+      projectId,
+      conversationId,
+      branch,
+      ref,
+      compareTo,
+    ),
+  );
+
+  useEffect(() => {
+    if (!conversationId) return;
+    const data = query.data;
+    if (!data || data.id !== conversationId) return;
+    const { activeStreams } = useAgentLiveStore.getState();
+    // Hydration from REST must not clobber in-flight streams (placeholder + patch indices).
+    if (activeStreams.size > 0) return;
+    useAgentLiveStore.getState().setWire(data);
+  }, [conversationId, query.dataUpdatedAt]);
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/live/index.ts b/src/frontend/src/features/Dashboard/features/Agent/live/index.ts
new file mode 100644
index 00000000..7b3a603d
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/live/index.ts
@@ -0,0 +1,2 @@
+export { useAgentLiveStore } from "./store/useAgentLiveStore";
+export * from "./hooks";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/live/store/useAgentLiveStore.ts b/src/frontend/src/features/Dashboard/features/Agent/live/store/useAgentLiveStore.ts
new file mode 100644
index 00000000..4501dc33
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/live/store/useAgentLiveStore.ts
@@ -0,0 +1,169 @@
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+import { applyConversationPatches } from "@/lib/jsonPatch/applyConversationPatches";
+import type { Operation } from "fast-json-patch";
+import type {
+  StreamChunkPayload,
+  StreamEndPayload,
+  StreamErrorPayload,
+  StreamStartPayload,
+} from "@/types/agent";
+import type { WireConversation, WireMessage, WireTextPart } from "@/types/agent";
+
+const STREAM_PLACEHOLDER = (streamId: string) => `stream:${streamId}`;
+
+function isTextPart(p: unknown): p is WireTextPart {
+  return (
+    typeof p === "object" &&
+    p !== null &&
+    (p as WireTextPart).type === "text" &&
+    typeof (p as WireTextPart).text === "string"
+  );
+}
+
+function appendDeltaToFirstTextPart(
+  message: WireMessage,
+  delta: string,
+): WireMessage {
+  const parts = [...message.parts];
+  if (parts.length === 0) {
+    return {
+      ...message,
+      parts: [{ type: "text", text: delta }],
+    };
+  }
+  const head = parts[0];
+  if (isTextPart(head)) {
+    parts[0] = { type: "text", text: head.text + delta };
+  } else {
+    parts.unshift({ type: "text", text: delta });
+  }
+  return { ...message, parts };
+}
+
+export interface AgentLiveState {
+  wire: WireConversation | null;
+  /** Stream ids currently receiving chunks for the active conversation */
+  activeStreams: Set<string>;
+  patchApplyFailed: boolean;
+  setWire: (wire: WireConversation | null) => void;
+  reset: () => void;
+  clearPatchFailure: () => void;
+  applyServerPatches: (patches: Operation[]) => void;
+  onStreamStart: (payload: StreamStartPayload) => void;
+  onStreamChunk: (payload: StreamChunkPayload, conversationId: string) => void;
+  onStreamEnd: (payload: StreamEndPayload, conversationId: string) => void;
+  onStreamError: (payload: StreamErrorPayload, conversationId: string) => void;
+}
+
+export const useAgentLiveStore = create<AgentLiveState>()(
+  devtools(
+    (set, get) => ({
+      wire: null,
+      activeStreams: new Set(),
+      patchApplyFailed: false,
+
+      setWire: (wire) =>
+        set((s) => {
+          if (s.wire === wire) return s;
+          return {
+            wire,
+            activeStreams: new Set(),
+            patchApplyFailed: false,
+          };
+        }),
+
+      reset: () =>
+        set((s) => {
+          if (
+            s.wire === null &&
+            s.activeStreams.size === 0 &&
+            !s.patchApplyFailed
+          ) {
+            return s;
+          }
+          return {
+            wire: null,
+            activeStreams: new Set(),
+            patchApplyFailed: false,
+          };
+        }),
+
+      clearPatchFailure: () =>
+        set((s) => (s.patchApplyFailed ? { patchApplyFailed: false } : s)),
+
+      applyServerPatches: (patches) => {
+        const { wire } = get();
+        if (!wire || patches.length === 0) return;
+        try {
+          const next = applyConversationPatches(wire, patches);
+          set({ wire: next, patchApplyFailed: false });
+        } catch {
+          set({ patchApplyFailed: true });
+        }
+      },
+
+      onStreamStart: (payload) => {
+        const { wire } = get();
+        if (!wire || wire.id !== payload.conversation_id) return;
+        const streamId = payload.stream_id;
+        const placeholderId = STREAM_PLACEHOLDER(streamId);
+        if (wire.messages.some((m) => m.id === placeholderId)) return;
+
+        const seq = wire.messages.length;
+        const placeholder: WireMessage = {
+          id: placeholderId,
+          role: "assistant",
+          sequence: seq,
+          parts: [{ type: "text", text: "" }],
+          created_at: new Date().toISOString(),
+          model: payload.model ?? null,
+        };
+
+        set({
+          wire: {
+            ...wire,
+            messages: [...wire.messages, placeholder],
+          },
+          activeStreams: new Set(get().activeStreams).add(streamId),
+        });
+      },
+
+      onStreamChunk: (payload, conversationId) => {
+        const { wire } = get();
+        if (!wire || wire.id !== conversationId) return;
+        const placeholderId = STREAM_PLACEHOLDER(payload.stream_id);
+        const idx = wire.messages.findIndex((m) => m.id === placeholderId);
+        if (idx < 0) return;
+        const nextMessages = [...wire.messages];
+        nextMessages[idx] = appendDeltaToFirstTextPart(
+          nextMessages[idx],
+          payload.delta,
+        );
+        set({ wire: { ...wire, messages: nextMessages } });
+      },
+
+      onStreamEnd: (payload, conversationId) => {
+        const { wire } = get();
+        if (wire && wire.id !== conversationId) return;
+        const next = new Set(get().activeStreams);
+        next.delete(payload.stream_id);
+        set({ activeStreams: next });
+      },
+
+      onStreamError: (payload, conversationId) => {
+        const { wire } = get();
+        if (!wire || wire.id !== conversationId) return;
+        const placeholderId = STREAM_PLACEHOLDER(payload.stream_id);
+        const messages = wire.messages.filter((m) => m.id !== placeholderId);
+        const next = new Set(get().activeStreams);
+        next.delete(payload.stream_id);
+        set({
+          wire: { ...wire, messages },
+          activeStreams: next,
+        });
+      },
+    }),
+    { name: "agent-live-store" },
+  ),
+);
diff --git a/src/frontend/src/features/Dashboard/features/Agent/store/selectors/conversationSelectors.ts b/src/frontend/src/features/Dashboard/features/Agent/store/selectors/conversationSelectors.ts
index 1e338a9c..44e56a6b 100644
--- a/src/frontend/src/features/Dashboard/features/Agent/store/selectors/conversationSelectors.ts
+++ b/src/frontend/src/features/Dashboard/features/Agent/store/selectors/conversationSelectors.ts
@@ -1,13 +1,4 @@
-import type { ConversationSummary, MessagePart } from "../../types/conversation";
-import type { ConversationState } from "../useConversationStore";
-import { toConversationSummary } from "../useConversationStore";
-
-export const selectConversationSummaries = (
-  state: ConversationState,
-): ConversationSummary[] => state.allConversations.map(toConversationSummary);
-
-export const selectMessages = (state: ConversationState) =>
-  state.currentConversation?.messages ?? [];
+import type { MessagePart } from "../../types/conversation";
 
 export const selectMessageText = (parts: MessagePart[]): string =>
   parts
@@ -16,12 +7,3 @@ export const selectMessageText = (parts: MessagePart[]): string =>
     })
     .map((part) => part.text)
     .join("");
-
-export const selectAllEvents = (state: ConversationState) =>
-  selectMessages(state).flatMap((message) =>
-    message.parts
-      .filter((part): part is Extract<MessagePart, { type: "event" }> => {
-        return part.type === "event";
-      })
-      .map((part) => part.event),
-  );
diff --git a/src/frontend/src/features/Dashboard/features/Agent/store/useAgentOverlayStore.ts b/src/frontend/src/features/Dashboard/features/Agent/store/useAgentOverlayStore.ts
index e1293c4e..86e49f73 100644
--- a/src/frontend/src/features/Dashboard/features/Agent/store/useAgentOverlayStore.ts
+++ b/src/frontend/src/features/Dashboard/features/Agent/store/useAgentOverlayStore.ts
@@ -1,13 +1,26 @@
 import { create } from "zustand";
 
+import { useWalkthroughStore } from "../walkthrough/store/useWalkthroughStore";
+
 interface AgentOverlayState {
   isOpen: boolean;
   toggleOpen: () => void;
   setOpen: (open: boolean) => void;
 }
 
-export const useAgentOverlayStore = create<AgentOverlayState>((set) => ({
+export const useAgentOverlayStore = create<AgentOverlayState>((set, get) => ({
   isOpen: false,
-  toggleOpen: () => set((state) => ({ isOpen: !state.isOpen })),
-  setOpen: (open) => set({ isOpen: open }),
+  toggleOpen: () => {
+    const next = !get().isOpen;
+    if (next) {
+      useWalkthroughStore.getState().setPlaybackDetached(false);
+    }
+    set({ isOpen: next });
+  },
+  setOpen: (open) => {
+    if (open) {
+      useWalkthroughStore.getState().setPlaybackDetached(false);
+    }
+    set({ isOpen: open });
+  },
 }));
diff --git a/src/frontend/src/features/Dashboard/features/Agent/store/useAgentUiStore.ts b/src/frontend/src/features/Dashboard/features/Agent/store/useAgentUiStore.ts
new file mode 100644
index 00000000..d369cf54
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/store/useAgentUiStore.ts
@@ -0,0 +1,21 @@
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+
+/**
+ * Which backend conversation is driving the live agent (patches + streams).
+ * `null` means a local “new chat” draft; the server conversation is created on first send.
+ */
+export interface AgentUiState {
+  backendConversationId: string | null;
+  setBackendConversationId: (id: string | null) => void;
+}
+
+export const useAgentUiStore = create<AgentUiState>()(
+  devtools(
+    (set) => ({
+      backendConversationId: null,
+      setBackendConversationId: (id) => set({ backendConversationId: id }),
+    }),
+    { name: "agent-ui-store" },
+  ),
+);
diff --git a/src/frontend/src/features/Dashboard/features/Agent/store/useConversationStore.ts b/src/frontend/src/features/Dashboard/features/Agent/store/useConversationStore.ts
index 3481d203..7f3bd27e 100644
--- a/src/frontend/src/features/Dashboard/features/Agent/store/useConversationStore.ts
+++ b/src/frontend/src/features/Dashboard/features/Agent/store/useConversationStore.ts
@@ -1,54 +1,22 @@
 import { create } from "zustand";
 import { devtools } from "zustand/middleware";
-import { conversationFixtures } from "../fixtures/conversations";
-import type {
-  Conversation,
-  ConversationSummary,
-  ViewMode,
-} from "../types/conversation";
+import type { Conversation } from "../types/conversation";
 
+/**
+ * Local conversation object for replay / walkthrough demos (optional).
+ * Live agent UI is driven by `useAgentUiStore.backendConversationId` + wire hydration.
+ */
 export interface ConversationState {
-  allConversations: Conversation[];
   currentConversation: Conversation | null;
-  viewMode: ViewMode;
-  setConversations: (conversations: Conversation[]) => void;
-  setCurrentConversation: (conversationId: string) => void;
   clearCurrentConversation: () => void;
-  setViewMode: (mode: ViewMode) => void;
 }
 
-const initialConversations = conversationFixtures;
-
 export const useConversationStore = create<ConversationState>()(
   devtools(
     (set) => ({
-      allConversations: initialConversations,
-      currentConversation: initialConversations[0] ?? null,
-      viewMode: "chat",
-      setConversations: (conversations) =>
-        set(() => ({
-          allConversations: conversations,
-          currentConversation: conversations[0] ?? null,
-        })),
-      setCurrentConversation: (conversationId) =>
-        set((state) => ({
-          currentConversation:
-            state.allConversations.find(
-              (conversation) => conversation.id === conversationId,
-            ) ?? state.currentConversation,
-        })),
+      currentConversation: null,
       clearCurrentConversation: () => set({ currentConversation: null }),
-      setViewMode: (mode) => set({ viewMode: mode }),
     }),
     { name: "conversation-store" },
   ),
 );
-
-export const toConversationSummary = (
-  conversation: Conversation,
-): ConversationSummary => ({
-  id: conversation.id,
-  title: conversation.title,
-  date: conversation.date,
-  duration: conversation.duration,
-});
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/ActionHandlerRegistry.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/ActionHandlerRegistry.ts
new file mode 100644
index 00000000..075db8c8
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/ActionHandlerRegistry.ts
@@ -0,0 +1,22 @@
+import type { ActionHandler } from "../adapters/actionContext";
+import type { Action } from "../types/walkthrough";
+
+export class ActionHandlerRegistry {
+  private handlers = new Map<string, ActionHandler>();
+
+  register<T extends Action>(
+    type: T["type"],
+    handler: ActionHandler<T>,
+  ): this {
+    this.handlers.set(type, handler as ActionHandler);
+    return this;
+  }
+
+  get(type: string): ActionHandler | undefined {
+    return this.handlers.get(type);
+  }
+
+  has(type: string): boolean {
+    return this.handlers.has(type);
+  }
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/createDefaultRegistry.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/createDefaultRegistry.ts
new file mode 100644
index 00000000..bc705773
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/createDefaultRegistry.ts
@@ -0,0 +1,27 @@
+import { ActionHandlerRegistry } from "./ActionHandlerRegistry";
+import { clearHighlightHandler } from "./handlers/clearHighlightHandler";
+import { closeCodeHandler } from "./handlers/closeCodeHandler";
+import { collapseNodeHandler } from "./handlers/collapseNodeHandler";
+import { createTabHandler } from "./handlers/createTabHandler";
+import { expandNodeHandler } from "./handlers/expandNodeHandler";
+import { focusNodeHandler } from "./handlers/focusNodeHandler";
+import { highlightCodeHandler } from "./handlers/highlightCodeHandler";
+import { panCanvasHandler } from "./handlers/panCanvasHandler";
+import { selectNodeHandler } from "./handlers/selectNodeHandler";
+import { showCodeHandler } from "./handlers/showCodeHandler";
+import { waitHandler } from "./handlers/waitHandler";
+
+export function createDefaultRegistry(): ActionHandlerRegistry {
+  return new ActionHandlerRegistry()
+    .register("focus-node", focusNodeHandler)
+    .register("expand-node", expandNodeHandler)
+    .register("collapse-node", collapseNodeHandler)
+    .register("show-code", showCodeHandler)
+    .register("close-code", closeCodeHandler)
+    .register("highlight-code", highlightCodeHandler)
+    .register("clear-highlight", clearHighlightHandler)
+    .register("pan-canvas", panCanvasHandler)
+    .register("select-node", selectNodeHandler)
+    .register("create-tab", createTabHandler)
+    .register("wait", waitHandler);
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/createNoopRegistry.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/createNoopRegistry.ts
new file mode 100644
index 00000000..54b52ca6
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/createNoopRegistry.ts
@@ -0,0 +1,28 @@
+import type { ActionHandler } from "../adapters/actionContext";
+import type { Action } from "../types/walkthrough";
+import { ActionHandlerRegistry } from "./ActionHandlerRegistry";
+
+const ACTION_TYPES: Action["type"][] = [
+  "focus-node",
+  "expand-node",
+  "collapse-node",
+  "show-code",
+  "close-code",
+  "highlight-code",
+  "clear-highlight",
+  "pan-canvas",
+  "select-node",
+  "create-tab",
+  "wait",
+];
+
+const noop: ActionHandler = async () => {};
+
+/** Registry where every action is a no-op — useful until real handlers are wired. */
+export function createNoopActionRegistry(): ActionHandlerRegistry {
+  const registry = new ActionHandlerRegistry();
+  for (const type of ACTION_TYPES) {
+    registry.register(type, noop);
+  }
+  return registry;
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/clearHighlightHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/clearHighlightHandler.ts
new file mode 100644
index 00000000..cae522a5
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/clearHighlightHandler.ts
@@ -0,0 +1,10 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { ClearHighlightAction } from "../../types/walkthrough";
+
+export async function clearHighlightHandler(
+  action: ClearHighlightAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+  ctx.adapter.clearHighlight(action.nodeId);
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/closeCodeHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/closeCodeHandler.ts
new file mode 100644
index 00000000..ab31e10a
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/closeCodeHandler.ts
@@ -0,0 +1,10 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { CloseCodeAction } from "../../types/walkthrough";
+
+export async function closeCodeHandler(
+  action: CloseCodeAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+  ctx.adapter.closeCode(action.nodeId);
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/collapseNodeHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/collapseNodeHandler.ts
new file mode 100644
index 00000000..f33fc991
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/collapseNodeHandler.ts
@@ -0,0 +1,10 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { CollapseNodeAction } from "../../types/walkthrough";
+
+export async function collapseNodeHandler(
+  action: CollapseNodeAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+  ctx.adapter.collapseNode(action.nodeId);
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/createTabHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/createTabHandler.ts
new file mode 100644
index 00000000..832e2bfc
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/createTabHandler.ts
@@ -0,0 +1,19 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { CreateTabAction } from "../../types/walkthrough";
+
+export async function createTabHandler(
+  action: CreateTabAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+
+  const prevTabId = ctx.adapter.getActiveTabId();
+  ctx.adapter.createTab(action.nodeId);
+
+  ctx.cleanup.push(() => {
+    ctx.adapter.destroyTab(action.nodeId);
+    if (prevTabId) {
+      ctx.adapter.setActiveTab(prevTabId);
+    }
+  });
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/expandNodeHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/expandNodeHandler.ts
new file mode 100644
index 00000000..6a58fc8a
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/expandNodeHandler.ts
@@ -0,0 +1,18 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { ExpandNodeAction } from "../../types/walkthrough";
+
+export async function expandNodeHandler(
+  action: ExpandNodeAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+
+  const wasExpanded = ctx.adapter.isNodeExpanded(action.nodeId);
+  ctx.adapter.expandNode(action.nodeId);
+
+  ctx.cleanup.push(() => {
+    if (!wasExpanded) {
+      ctx.adapter.collapseNode(action.nodeId);
+    }
+  });
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/focusNodeHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/focusNodeHandler.ts
new file mode 100644
index 00000000..34457171
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/focusNodeHandler.ts
@@ -0,0 +1,15 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { FocusNodeAction } from "../../types/walkthrough";
+
+export async function focusNodeHandler(
+  action: FocusNodeAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+
+  ctx.adapter.spotlightNode(action.nodeId);
+
+  ctx.cleanup.push(() => {
+    ctx.adapter.clearSpotlight();
+  });
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/highlightCodeHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/highlightCodeHandler.ts
new file mode 100644
index 00000000..d3091fda
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/highlightCodeHandler.ts
@@ -0,0 +1,15 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { HighlightCodeAction } from "../../types/walkthrough";
+
+export async function highlightCodeHandler(
+  action: HighlightCodeAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+
+  ctx.adapter.highlightLines(action.nodeId, action.lines, action.style);
+
+  ctx.cleanup.push(() => {
+    ctx.adapter.clearHighlight(action.nodeId);
+  });
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/panCanvasHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/panCanvasHandler.ts
new file mode 100644
index 00000000..651e9ce8
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/panCanvasHandler.ts
@@ -0,0 +1,11 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { PanCanvasAction } from "../../types/walkthrough";
+
+export async function panCanvasHandler(
+  action: PanCanvasAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+
+  await ctx.adapter.panToNode(action.to.nodeId, { duration: 300 });
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/selectNodeHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/selectNodeHandler.ts
new file mode 100644
index 00000000..00483fac
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/selectNodeHandler.ts
@@ -0,0 +1,18 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { SelectNodeAction } from "../../types/walkthrough";
+
+export async function selectNodeHandler(
+  action: SelectNodeAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+
+  const previousNodeId = ctx.adapter.getSelectedNodeId();
+  ctx.adapter.selectNode(action.nodeId, action.selectionType);
+
+  ctx.cleanup.push(() => {
+    if (previousNodeId) {
+      ctx.adapter.selectNode(previousNodeId, "primary");
+    }
+  });
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/showCodeHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/showCodeHandler.ts
new file mode 100644
index 00000000..928f1ad7
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/showCodeHandler.ts
@@ -0,0 +1,15 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { ShowCodeAction } from "../../types/walkthrough";
+
+export async function showCodeHandler(
+  action: ShowCodeAction,
+  ctx: ActionContext,
+): Promise<void> {
+  if (ctx.signal.aborted) return;
+
+  ctx.adapter.showCode(action.nodeId);
+
+  ctx.cleanup.push(() => {
+    ctx.adapter.closeCode(action.nodeId);
+  });
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/waitHandler.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/waitHandler.ts
new file mode 100644
index 00000000..afbe25f4
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/handlers/waitHandler.ts
@@ -0,0 +1,8 @@
+import type { ActionContext } from "../../adapters/actionContext";
+import type { WaitAction } from "../../types/walkthrough";
+
+/** Wall-clock wait is enforced by StepExecutor using `action.ms`. */
+export async function waitHandler(
+  _action: WaitAction,
+  _ctx: ActionContext,
+): Promise<void> {}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/index.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/index.ts
new file mode 100644
index 00000000..69dad83f
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/actions/index.ts
@@ -0,0 +1,3 @@
+export { ActionHandlerRegistry } from "./ActionHandlerRegistry";
+export { createDefaultRegistry } from "./createDefaultRegistry";
+export { createNoopActionRegistry } from "./createNoopRegistry";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/CanvasAdapter.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/CanvasAdapter.ts
new file mode 100644
index 00000000..4459cae1
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/CanvasAdapter.ts
@@ -0,0 +1,44 @@
+import type { HighlightStyle, LineRange } from "../types/walkthrough";
+
+export interface PanOptions {
+  duration?: number;
+  zoom?: number;
+}
+
+/**
+ * Boundary between the walkthrough engine and canvas / project state.
+ * Handlers call adapter methods only — never the DOM or stores directly.
+ */
+export interface CanvasAdapter {
+  spotlightNode(nodeId: string): void;
+  clearSpotlight(): void;
+
+  expandNode(nodeId: string): void;
+  collapseNode(nodeId: string): void;
+  isNodeExpanded(nodeId: string): boolean;
+
+  /** Open inline code panel for a node (walkthrough-driven). */
+  showCode(nodeId: string): void;
+  /** Close inline code panel for a node. */
+  closeCode(nodeId: string): void;
+
+  highlightLines(
+    nodeId: string,
+    lines: LineRange[],
+    style?: HighlightStyle,
+  ): void;
+  clearHighlight(nodeId?: string): void;
+
+  panToNode(nodeId: string, options?: PanOptions): Promise<void>;
+
+  selectNode(
+    nodeId: string,
+    selectionType: "primary" | "secondary" | "promote",
+  ): void;
+  getSelectedNodeId(): string | null;
+
+  createTab(callNodeId: string): void;
+  destroyTab(callNodeId: string): void;
+  getActiveTabId(): string;
+  setActiveTab(tabId: string): void;
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/ReactFlowCanvasAdapter.tsx b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/ReactFlowCanvasAdapter.tsx
new file mode 100644
index 00000000..992be0f7
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/ReactFlowCanvasAdapter.tsx
@@ -0,0 +1,151 @@
+import type { ReactFlowInstance } from "@xyflow/react";
+import { findNodeByKey } from "@/features/Dashboard/utils/findNode";
+import useProjectStore from "@/features/Dashboard/store/useProjectStore";
+import useTabStore from "@/features/Dashboard/store/useTabStore";
+import type { WalkthroughStoreApi } from "../store/useWalkthroughStore";
+import type { CanvasAdapter, PanOptions } from "./CanvasAdapter";
+import type { HighlightStyle, LineRange } from "../types/walkthrough";
+
+function mapSelectionType(
+  t: "primary" | "secondary" | "promote",
+): "primary" | "secondary" | "promte" {
+  return t === "promote" ? "promte" : t;
+}
+
+export class ReactFlowCanvasAdapter implements CanvasAdapter {
+  constructor(
+    private readonly getTabId: () => string,
+    private readonly getReactFlowInstance: () => ReactFlowInstance | null,
+    private readonly projectStore: typeof useProjectStore,
+    private readonly tabStore: typeof useTabStore,
+    private readonly walkthroughStore: WalkthroughStoreApi,
+  ) {}
+
+  spotlightNode(nodeId: string): void {
+    this.walkthroughStore.getState().setSpotlightNodeId(nodeId);
+  }
+
+  clearSpotlight(): void {
+    this.walkthroughStore.getState().setSpotlightNodeId(null);
+  }
+
+  expandNode(nodeId: string): void {
+    const tabId = this.getTabId();
+    this.projectStore.getState().expandNode(tabId, nodeId);
+  }
+
+  collapseNode(nodeId: string): void {
+    const tabId = this.getTabId();
+    this.projectStore.getState().collapseNode(tabId, nodeId);
+  }
+
+  isNodeExpanded(nodeId: string): boolean {
+    const tabId = this.getTabId();
+    const expanded = this.projectStore.getState().expandedNodeIds[tabId] ?? [];
+    return expanded.includes(nodeId);
+  }
+
+  showCode(nodeId: string): void {
+    this.walkthroughStore.getState().setForcedCodeOpen(nodeId, true);
+  }
+
+  closeCode(nodeId: string): void {
+    this.walkthroughStore.getState().setForcedCodeOpen(nodeId, false);
+  }
+
+  highlightLines(
+    nodeId: string,
+    lines: LineRange[],
+    style?: HighlightStyle,
+  ): void {
+    this.walkthroughStore.getState().setHighlight(nodeId, lines, style);
+  }
+
+  clearHighlight(nodeId?: string): void {
+    this.walkthroughStore.getState().clearHighlightStore(nodeId);
+  }
+
+  async panToNode(nodeId: string, options?: PanOptions): Promise<void> {
+    const instance = this.getReactFlowInstance();
+    if (!instance?.viewportInitialized) return;
+
+    const duration = options?.duration ?? 300;
+    const deadline = performance.now() + 12_000;
+
+    while (performance.now() < deadline) {
+      const target = instance.getNode(nodeId);
+      const w = target?.measured?.width;
+      if (target && w) {
+        const h = target.measured?.height ?? 0;
+        const zoom = options?.zoom ?? instance.getZoom();
+        instance.setCenter(
+          target.position.x + w / 2,
+          target.position.y + h / 2,
+          { zoom, duration },
+        );
+        await new Promise<void>((resolve) => {
+          globalThis.setTimeout(resolve, duration);
+        });
+        return;
+      }
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => resolve());
+      });
+    }
+  }
+
+  selectNode(
+    nodeId: string,
+    selectionType: "primary" | "secondary" | "promote",
+  ): void {
+    const tabId = this.getTabId();
+    const projectData = this.projectStore.getState().projectData;
+    if (!projectData) return;
+
+    const node = findNodeByKey(projectData, nodeId);
+    if (!node) return;
+
+    this.tabStore
+      .getState()
+      .handleNodeSelection(tabId, node, mapSelectionType(selectionType));
+  }
+
+  getSelectedNodeId(): string | null {
+    const tabId = this.getTabId();
+    return this.projectStore.getState().selectedNode[tabId]?.id ?? null;
+  }
+
+  createTab(callNodeId: string): void {
+    const tabId = this.getTabId();
+    const projectData = this.projectStore.getState().projectData;
+    if (!projectData) return;
+
+    const node = findNodeByKey(projectData, callNodeId);
+    if (!node) return;
+
+    this.tabStore.getState().handleNodeSelection(tabId, node, "promte");
+  }
+
+  destroyTab(callNodeId: string): void {
+    const tabId = this.getTabId();
+    const currentTab = this.tabStore.getState().tabs[tabId];
+    if (!currentTab) return;
+
+    const childId = currentTab.childrenIds.find((id) => {
+      const child = this.tabStore.getState().tabs[id];
+      return child?.sourceCallNodeId === callNodeId;
+    });
+
+    if (childId) {
+      this.tabStore.getState().destroyTabBranch(childId);
+    }
+  }
+
+  getActiveTabId(): string {
+    return this.tabStore.getState().activeTabId;
+  }
+
+  setActiveTab(tabId: string): void {
+    this.tabStore.getState().setActiveTabId(tabId);
+  }
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/actionContext.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/actionContext.ts
new file mode 100644
index 00000000..a2075f0c
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/actionContext.ts
@@ -0,0 +1,18 @@
+import type { Action } from "../types/walkthrough";
+import type { CanvasAdapter } from "./CanvasAdapter";
+
+/** Teardown sink passed into handlers (see engine `CleanupStack`). */
+export interface ActionCleanupSink {
+  push(fn: () => void): void;
+}
+
+export interface ActionContext {
+  adapter: CanvasAdapter;
+  signal: AbortSignal;
+  cleanup: ActionCleanupSink;
+}
+
+export type ActionHandler<T extends Action = Action> = (
+  action: T,
+  ctx: ActionContext,
+) => Promise<void>;
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/index.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/index.ts
new file mode 100644
index 00000000..01b21364
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/adapters/index.ts
@@ -0,0 +1,7 @@
+export type { CanvasAdapter, PanOptions } from "./CanvasAdapter";
+export type {
+  ActionCleanupSink,
+  ActionContext,
+  ActionHandler,
+} from "./actionContext";
+export { ReactFlowCanvasAdapter } from "./ReactFlowCanvasAdapter";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/PopoverLayer.tsx b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/PopoverLayer.tsx
new file mode 100644
index 00000000..75dd42aa
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/PopoverLayer.tsx
@@ -0,0 +1,81 @@
+import { useLayoutEffect, useRef } from "react";
+
+import {
+  Popover,
+  PopoverAnchor,
+  PopoverContent,
+} from "@/components/ui/popover";
+
+import {
+  usePopoverPosition,
+  WALKTHROUGH_POPOVER_GAP,
+} from "../hooks/usePopoverPosition";
+import { useWalkthroughStore } from "../store/useWalkthroughStore";
+
+const VIEWPORT_CENTER_ANCHOR = { type: "viewport-center" };
+
+export function PopoverLayer() {
+  const popover = useWalkthroughStore((s) => s.popover);
+  const visible = useWalkthroughStore((s) => s.popoverVisible);
+  const visibleText = useWalkthroughStore((s) => s.typewriter.visibleText);
+  const isTyping = useWalkthroughStore((s) => s.typewriter.isTyping);
+  const codeAnchorLayoutEpoch = useWalkthroughStore(
+    (s) => s.codeAnchorLayoutEpoch,
+  );
+
+  const anchor = popover?.anchor ?? VIEWPORT_CENTER_ANCHOR;
+  const { x, y, side } = usePopoverPosition(
+    anchor,
+    popover?.side,
+    anchor.type === "code-line" ? codeAnchorLayoutEpoch : undefined,
+  );
+
+  const scrollRef = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+  }, [visibleText]);
+
+  if (!popover || !visible) return null;
+
+  return (
+    <Popover open modal={false} onOpenChange={() => {}}>
+      <PopoverAnchor asChild>
+        <span
+          aria-hidden
+          className="pointer-events-none fixed block h-px w-px"
+          style={{ left: x, top: y }}
+        />
+      </PopoverAnchor>
+      <PopoverContent
+        side={side}
+        align="center"
+        sideOffset={WALKTHROUGH_POPOVER_GAP}
+        collisionPadding={12}
+        className="z-[60] flex w-[min(360px,calc(100vw-24px))] min-w-0 max-w-[min(360px,calc(100vw-24px))] flex-col gap-0 overflow-hidden p-0"
+        onOpenAutoFocus={(e) => e.preventDefault()}
+        onCloseAutoFocus={(e) => e.preventDefault()}
+      >
+        {popover.title ? (
+          <h3 className="walkthrough-popover__title text-popover-foreground shrink-0 border-b px-4 pt-3 pb-2">
+            {popover.title}
+          </h3>
+        ) : null}
+        <div
+          ref={scrollRef}
+          className="min-h-0 max-h-[min(280px,42vh)] overflow-y-auto overflow-x-hidden px-4 py-3"
+        >
+          <p className="walkthrough-popover__body text-popover-foreground m-0 max-w-full break-words">
+            {visibleText}
+            {isTyping ? (
+              <span className="walkthrough-popover__cursor" aria-hidden>
+                ▊
+              </span>
+            ) : null}
+          </p>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/SpotlightOverlay.tsx b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/SpotlightOverlay.tsx
new file mode 100644
index 00000000..079014ac
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/SpotlightOverlay.tsx
@@ -0,0 +1,89 @@
+import { useEffect } from "react";
+import { useWalkthroughStore } from "../store/useWalkthroughStore";
+
+const DIM_CLASS = "walkthrough-dimmed";
+const HIGHLIGHT_CLASS = "walkthrough-highlighted";
+const FLOW_FOCUS_CLASS = "walkthrough-focus-active";
+const MAX_FRAMES = 180;
+
+export function SpotlightOverlay() {
+  const spotlightNodeId = useWalkthroughStore((s) => s.spotlightNodeId);
+
+  useEffect(() => {
+    const allNodesStatic = () =>
+      Array.from(document.querySelectorAll<HTMLElement>(".react-flow__node"));
+
+    if (!spotlightNodeId) {
+      for (const node of allNodesStatic()) {
+        node.classList.remove(DIM_CLASS, HIGHLIGHT_CLASS);
+      }
+      document
+        .querySelector<HTMLElement>(".react-flow")
+        ?.classList.remove(FLOW_FOCUS_CLASS);
+      return;
+    }
+
+    let cancelled = false;
+    let frame = 0;
+    let rafId = 0;
+    const clearAll = () => {
+      for (const node of allNodesStatic()) {
+        node.classList.remove(DIM_CLASS, HIGHLIGHT_CLASS);
+      }
+      document
+        .querySelector<HTMLElement>(".react-flow")
+        ?.classList.remove(FLOW_FOCUS_CLASS);
+    };
+
+    const apply = (target: HTMLElement) => {
+      const flowRootLocal =
+        target.closest<HTMLElement>(".react-flow") ??
+        document.querySelector<HTMLElement>(".react-flow");
+
+      const allNodes = allNodesStatic();
+      for (const node of allNodes) {
+        if (node === target) {
+          node.classList.add(HIGHLIGHT_CLASS);
+          node.classList.remove(DIM_CLASS);
+        } else {
+          node.classList.add(DIM_CLASS);
+          node.classList.remove(HIGHLIGHT_CLASS);
+        }
+      }
+      flowRootLocal?.classList.add(FLOW_FOCUS_CLASS);
+      target.scrollIntoView({ behavior: "smooth", block: "center", inline: "center" });
+    };
+
+    const tick = () => {
+      if (cancelled) return;
+      const target = document.querySelector<HTMLElement>(
+        `.react-flow__node[data-id="${cssEscape(spotlightNodeId)}"]`,
+      );
+      if (target) {
+        apply(target);
+        return;
+      }
+      frame += 1;
+      if (frame < MAX_FRAMES) {
+        rafId = requestAnimationFrame(tick);
+      }
+    };
+
+    tick();
+
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(rafId);
+      clearAll();
+    };
+  }, [spotlightNodeId]);
+
+  return null;
+}
+
+function cssEscape(value: string): string {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+  return value.replace(/["\\]/g, "\\$&");
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/WalkthroughPlaybackBar.tsx b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/WalkthroughPlaybackBar.tsx
new file mode 100644
index 00000000..fcddbc59
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/WalkthroughPlaybackBar.tsx
@@ -0,0 +1,197 @@
+import {
+  PanelBottom,
+  PanelRight,
+  Pause,
+  Play,
+  SkipBack,
+  SkipForward,
+  Square,
+} from "lucide-react";
+import { cn } from "@/lib/utils";
+import { useShallow } from "zustand/react/shallow";
+import { useAgentOverlayStore } from "../../store/useAgentOverlayStore";
+import { useWalkthroughStore } from "../store/useWalkthroughStore";
+
+const SPEEDS = [0.5, 1, 1.5, 2] as const;
+
+export type WalkthroughPlaybackPlacement = "sidebar" | "floating";
+
+interface WalkthroughPlaybackBarProps {
+  placement?: WalkthroughPlaybackPlacement;
+}
+
+export function WalkthroughPlaybackBar({
+  placement = "sidebar",
+}: WalkthroughPlaybackBarProps) {
+  const [
+    status,
+    currentStepIndex,
+    totalSteps,
+    speed,
+    setSpeed,
+    timeline,
+    elapsedMs,
+    controls,
+    setPlaybackDetached,
+  ] = useWalkthroughStore(
+    useShallow((s) => [
+      s.status,
+      s.currentStepIndex,
+      s.totalSteps,
+      s.speed,
+      s.setSpeed,
+      s.timeline,
+      s.elapsedMs,
+      s.controls,
+      s.setPlaybackDetached,
+    ]),
+  );
+
+  const setAgentOpen = useAgentOverlayStore((s) => s.setOpen);
+
+  const totalMs = timeline?.totalDuration ?? 0;
+  const progressPct =
+    totalMs > 0 ? Math.min(100, (elapsedMs / totalMs) * 100) : 0;
+
+  const handlePlayPause = () => {
+    if (!controls) return;
+    if (status === "running") {
+      controls.pause();
+      return;
+    }
+    void controls.play();
+  };
+
+  if (!controls || totalSteps === 0) {
+    return (
+      <div className="rounded-md border border-border bg-muted/30 px-3 py-2 text-[11px] text-muted-foreground">
+        Walkthrough: load a tour via{" "}
+        <code className="rounded bg-muted px-1">controls.load()</code> (devtools)
+        or your agent flow.
+      </div>
+    );
+  }
+
+  const shellClass =
+    placement === "floating"
+      ? "space-y-2 rounded-lg border border-border bg-background/95 p-3 shadow-lg backdrop-blur-sm"
+      : "space-y-2 rounded-md border border-border bg-muted/20 p-3";
+
+  return (
+    <div className={shellClass}>
+      <p className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
+        Walkthrough
+      </p>
+      <div
+        role="slider"
+        aria-label="Walkthrough progress"
+        aria-valuemin={0}
+        aria-valuemax={totalMs}
+        aria-valuenow={Math.round(elapsedMs)}
+        className="relative h-2 w-full cursor-pointer rounded-full bg-muted"
+        onClick={(event) => {
+          if (totalMs <= 0) return;
+          const rect = event.currentTarget.getBoundingClientRect();
+          const pct = (event.clientX - rect.left) / rect.width;
+          void controls.seekToTime(pct * totalMs);
+        }}
+      >
+        <div
+          className="h-2 rounded-full bg-primary transition-[width]"
+          style={{ width: `${progressPct}%` }}
+        />
+      </div>
+
+      <div className="flex items-center justify-between text-xs">
+        <div className="flex items-center gap-1">
+          <button
+            type="button"
+            onClick={() => controls.stop()}
+            className="rounded-md p-1.5 hover:bg-muted"
+            aria-label="Stop"
+          >
+            <Square size={12} />
+          </button>
+          <button
+            type="button"
+            onClick={() => void controls.prev()}
+            disabled={currentStepIndex <= 0}
+            className="rounded-md p-1.5 hover:bg-muted disabled:opacity-30"
+            aria-label="Previous step"
+          >
+            <SkipBack size={12} />
+          </button>
+          <button
+            type="button"
+            onClick={handlePlayPause}
+            className="rounded-md bg-primary px-3 py-1.5 text-primary-foreground hover:bg-primary/90"
+            aria-label={status === "running" ? "Pause" : "Play"}
+          >
+            {status === "running" ? <Pause size={12} /> : <Play size={12} />}
+          </button>
+          <button
+            type="button"
+            onClick={() => void controls.next()}
+            disabled={currentStepIndex >= totalSteps - 1}
+            className="rounded-md p-1.5 hover:bg-muted disabled:opacity-30"
+            aria-label="Next step"
+          >
+            <SkipForward size={12} />
+          </button>
+        </div>
+
+        <span className="text-muted-foreground tabular-nums">
+          {currentStepIndex + 1} / {totalSteps} · {status}
+        </span>
+
+        <div className="flex items-center gap-1">
+          {SPEEDS.map((value) => (
+            <button
+              key={value}
+              type="button"
+              onClick={() => {
+                setSpeed(value);
+                controls.setSpeed(value);
+              }}
+              className={cn(
+                "rounded px-1.5 py-0.5",
+                speed === value
+                  ? "bg-primary text-primary-foreground"
+                  : "text-muted-foreground hover:bg-muted",
+              )}
+            >
+              {value}x
+            </button>
+          ))}
+          {placement === "sidebar" ? (
+            <button
+              type="button"
+              onClick={() => {
+                setPlaybackDetached(true);
+                setAgentOpen(false);
+              }}
+              className="ml-0.5 rounded-md p-1.5 text-muted-foreground hover:bg-muted hover:text-foreground"
+              aria-label="Detach walkthrough bar to canvas"
+              title="Detach to canvas"
+            >
+              <PanelBottom size={12} />
+            </button>
+          ) : (
+            <button
+              type="button"
+              onClick={() => {
+                setPlaybackDetached(false);
+                setAgentOpen(true);
+              }}
+              className="ml-0.5 rounded-md p-1.5 text-muted-foreground hover:bg-muted hover:text-foreground"
+              aria-label="Attach walkthrough bar to sidebar"
+              title="Attach to sidebar"
+            >
+              <PanelRight size={12} />
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/WalkthroughProvider.tsx b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/WalkthroughProvider.tsx
new file mode 100644
index 00000000..d9e7cf60
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/WalkthroughProvider.tsx
@@ -0,0 +1,31 @@
+import { useEffect } from "react";
+import { useWalkthrough } from "../hooks/useWalkthrough";
+import { useWalkthroughStore } from "../store/useWalkthroughStore";
+import { PopoverLayer } from "./PopoverLayer";
+import { SpotlightOverlay } from "./SpotlightOverlay";
+import { WalkthroughPlaybackBar } from "./WalkthroughPlaybackBar";
+import "./walkthrough.css";
+
+export function WalkthroughProvider({ tabId }: { tabId: string }) {
+  const controls = useWalkthrough(tabId);
+  const playbackDetached = useWalkthroughStore((s) => s.playbackDetached);
+
+  useEffect(() => {
+    useWalkthroughStore.getState().setControls(controls);
+    return () => useWalkthroughStore.getState().setControls(null);
+  }, [controls]);
+
+  return (
+    <>
+      <SpotlightOverlay />
+      <PopoverLayer />
+      {playbackDetached ? (
+        <div className="pointer-events-none absolute inset-x-0 bottom-8 z-45 flex justify-center px-4">
+          <div className="pointer-events-auto w-full max-w-md min-w-0">
+            <WalkthroughPlaybackBar placement="floating" />
+          </div>
+        </div>
+      ) : null}
+    </>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/index.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/index.ts
new file mode 100644
index 00000000..db606885
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/index.ts
@@ -0,0 +1,4 @@
+export { PopoverLayer } from "./PopoverLayer";
+export { SpotlightOverlay } from "./SpotlightOverlay";
+export { WalkthroughPlaybackBar } from "./WalkthroughPlaybackBar";
+export { WalkthroughProvider } from "./WalkthroughProvider";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/walkthrough.css b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/walkthrough.css
new file mode 100644
index 00000000..9ae6a3dd
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/components/walkthrough.css
@@ -0,0 +1,79 @@
+/* Spotlight: dim chrome + non-target nodes (see SpotlightOverlay) */
+.walkthrough-focus-active .react-flow__edges,
+.walkthrough-focus-active .react-flow__background,
+.walkthrough-focus-active .react-flow__controls {
+  opacity: 0.18;
+  transition: opacity 180ms ease;
+}
+
+.react-flow__node.walkthrough-dimmed {
+  opacity: 0.16 !important;
+  filter: blur(0.4px) saturate(0.7);
+  transition:
+    opacity 180ms ease,
+    filter 180ms ease,
+    transform 180ms ease;
+}
+
+.react-flow__node.walkthrough-highlighted {
+  opacity: 1 !important;
+  filter: none !important;
+  z-index: 50 !important;
+  transform: scale(1.03);
+  box-shadow:
+    0 0 0 3px rgba(251, 191, 36, 0.95),
+    0 0 22px rgba(251, 191, 36, 0.45);
+  transition:
+    opacity 180ms ease,
+    filter 180ms ease,
+    transform 180ms ease,
+    box-shadow 180ms ease;
+}
+
+.walkthrough-popover__title {
+  margin: 0;
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.walkthrough-popover__body {
+  font-size: 12px;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  word-break: break-word;
+}
+
+.walkthrough-popover__cursor {
+  display: inline-block;
+  margin-left: 1px;
+  animation: walkthrough-cursor-blink 1s step-end infinite;
+  color: rgb(251 191 36);
+}
+
+@keyframes walkthrough-cursor-blink {
+  50% {
+    opacity: 0;
+  }
+}
+
+/* Monaco walkthrough: spotlight rect + whole-line decorations (see useWalkthroughMonaco) */
+.walkthrough-monaco-spotlight {
+  position: absolute;
+  z-index: 10;
+  box-sizing: border-box;
+  pointer-events: none;
+  border: 2px solid rgba(251, 191, 36, 0.95);
+  border-radius: 4px;
+  background: rgba(251, 191, 36, 0.08);
+  transition:
+    top 0.15s ease-out,
+    height 0.15s ease-out,
+    left 0.15s ease-out,
+    width 0.15s ease-out,
+    opacity 0.15s ease-out;
+}
+
+.monaco-editor .walkthrough-monaco-line-deco {
+  background-color: rgba(251, 191, 36, 0.2) !important;
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/CleanupStack.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/CleanupStack.ts
new file mode 100644
index 00000000..a8dba952
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/CleanupStack.ts
@@ -0,0 +1,21 @@
+import type { ActionCleanupSink } from "../adapters/actionContext";
+
+/** LIFO teardown queue used by action handlers and the step executor. */
+export class CleanupStack implements ActionCleanupSink {
+  private fns: Array<() => void> = [];
+
+  push(fn: () => void): void {
+    this.fns.push(fn);
+  }
+
+  flush(): void {
+    while (this.fns.length > 0) {
+      const fn = this.fns.pop()!;
+      try {
+        fn();
+      } catch (err) {
+        console.error("Walkthrough cleanup error:", err);
+      }
+    }
+  }
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/StepExecutor.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/StepExecutor.ts
new file mode 100644
index 00000000..4c9b9f70
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/StepExecutor.ts
@@ -0,0 +1,126 @@
+import { ActionHandlerRegistry } from "../actions/ActionHandlerRegistry";
+import type { CanvasAdapter } from "../adapters/CanvasAdapter";
+import type { WalkthroughStep, WaitAction } from "../types/walkthrough";
+import { getDefaultDuration } from "../types/duration";
+import { abortableSleep } from "./abortableSleep";
+import { CleanupStack } from "./CleanupStack";
+
+const BUFFER_TICK_MS = 48;
+
+export interface StepExecutorContext {
+  registry: ActionHandlerRegistry;
+  adapter: CanvasAdapter;
+  signal: AbortSignal;
+  speed: number;
+  skipDuration?: boolean;
+  /**
+   * Called at the authored boundary of each action for timeline UI.
+   * `elapsedInAction` is 0 at the action start (timeline frozen here until handler finishes),
+   * then advances during the optional buffer phase, then equals `actionDuration` at end.
+   */
+  onActionProgress?: (actionIndex: number, elapsedInAction: number) => void;
+}
+
+export class StepExecutor {
+  private readonly cleanupStack = new CleanupStack();
+
+  constructor(
+    private readonly step: WalkthroughStep,
+    private readonly ctx: StepExecutorContext,
+  ) {}
+
+  cleanup(): void {
+    this.cleanupStack.flush();
+  }
+
+  /** Run all actions with duration pacing. */
+  async run(): Promise<void> {
+    const n = this.step.actions.length;
+    for (let i = 0; i < n; i++) {
+      await this.runActionAtIndex(i);
+    }
+  }
+
+  /**
+   * Run actions `0..upToIndex` inclusive. Used for seek fast-path.
+   * When `upToIndex < 0`, runs nothing.
+   */
+  async runUpTo(upToIndex: number): Promise<void> {
+    if (upToIndex < 0 || this.step.actions.length === 0) return;
+    const last = Math.min(upToIndex, this.step.actions.length - 1);
+    for (let i = 0; i <= last; i++) {
+      await this.runActionAtIndex(i, true);
+    }
+  }
+
+  private async runActionAtIndex(
+    i: number,
+    forceSkipDuration = false,
+  ): Promise<void> {
+    const { signal, registry, adapter, speed, skipDuration, onActionProgress } =
+      this.ctx;
+    if (signal.aborted) return;
+
+    const action = this.step.actions[i]!;
+    const actionDuration =
+      action.type === "wait"
+        ? (action as WaitAction).ms
+        : (action.duration ?? getDefaultDuration(action.type));
+
+    // Timeline stays at action start until the handler promise settles (freeze during slow work).
+    onActionProgress?.(i, 0);
+
+    const handlerStart = performance.now();
+
+    const handler = registry.get(action.type);
+    if (handler) {
+      await handler(action, {
+        adapter,
+        signal,
+        cleanup: this.cleanupStack,
+      });
+    }
+
+    if (signal.aborted) return;
+
+    const handlerWallMs = performance.now() - handlerStart;
+
+    const skip = forceSkipDuration || skipDuration;
+    if (skip) {
+      onActionProgress?.(i, actionDuration);
+      return;
+    }
+
+    const minWallMs = actionDuration / speed;
+    const bufferMs = Math.max(0, minWallMs - handlerWallMs);
+
+    if (bufferMs <= 0) {
+      onActionProgress?.(i, actionDuration);
+    } else {
+      await this.runBufferWithProgress(
+        bufferMs,
+        signal,
+        (frac) => onActionProgress?.(i, frac * actionDuration),
+      );
+    }
+  }
+
+  /** Advance buffer in small ticks so the timeline can move during intentional pacing only. */
+  private async runBufferWithProgress(
+    bufferMs: number,
+    signal: AbortSignal,
+    onFrac: (frac: number) => void,
+  ): Promise<void> {
+    if (bufferMs <= 0) return;
+
+    let elapsed = 0;
+    while (elapsed < bufferMs) {
+      if (signal.aborted) return;
+      const chunk = Math.min(BUFFER_TICK_MS, bufferMs - elapsed);
+      await abortableSleep(chunk, signal);
+      elapsed += chunk;
+      onFrac(Math.min(1, elapsed / bufferMs));
+    }
+    onFrac(1);
+  }
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/TimelineBuilder.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/TimelineBuilder.ts
new file mode 100644
index 00000000..06fd9639
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/TimelineBuilder.ts
@@ -0,0 +1,66 @@
+import {
+  DEFAULT_POST_POPOVER_PAUSE,
+  TYPEWRITER_MS_PER_CHAR,
+  getDefaultDuration,
+} from "../types/duration";
+import type {
+  ActionTimeline,
+  StepTimeline,
+  WaitAction,
+  Walkthrough,
+  WalkthroughTimeline,
+} from "../types/walkthrough";
+
+export class TimelineBuilder {
+  static build(walkthrough: Walkthrough): WalkthroughTimeline {
+    let cursor = 0;
+    const steps: StepTimeline[] = [];
+
+    for (let i = 0; i < walkthrough.steps.length; i++) {
+      const step = walkthrough.steps[i]!;
+      const stepStart = cursor;
+
+      let actionCursor = 0;
+      const actions: ActionTimeline[] = step.actions.map((action, j) => {
+        const duration =
+          action.type === "wait"
+            ? (action as WaitAction).ms
+            : (action.duration ?? getDefaultDuration(action.type));
+
+        const entry: ActionTimeline = {
+          actionIndex: j,
+          startMs: actionCursor,
+          endMs: actionCursor + duration,
+          duration,
+        };
+        actionCursor += duration;
+        return entry;
+      });
+
+      const actionsDuration = actionCursor;
+
+      const typewriterDuration = step.popover
+        ? step.popover.body.length * TYPEWRITER_MS_PER_CHAR
+        : 0;
+
+      const postPause = step.popover ? DEFAULT_POST_POPOVER_PAUSE : 0;
+
+      const totalStepDuration =
+        actionsDuration + typewriterDuration + postPause;
+
+      steps.push({
+        stepIndex: i,
+        stepId: step.id,
+        startMs: stepStart,
+        endMs: stepStart + totalStepDuration,
+        actionsDuration,
+        typewriterDuration,
+        actions,
+      });
+
+      cursor += totalStepDuration;
+    }
+
+    return { totalDuration: cursor, steps };
+  }
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/WalkthroughEngine.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/WalkthroughEngine.ts
new file mode 100644
index 00000000..82f70c43
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/WalkthroughEngine.ts
@@ -0,0 +1,328 @@
+import { ActionHandlerRegistry } from "../actions/ActionHandlerRegistry";
+import type { CanvasAdapter } from "../adapters/CanvasAdapter";
+import type { WalkthroughStoreApi } from "../store/useWalkthroughStore";
+import {
+  DEFAULT_POST_POPOVER_PAUSE,
+  TYPEWRITER_MS_PER_CHAR,
+} from "../types/duration";
+import { resolveTimelinePosition } from "../types/resolveTimelinePosition";
+import type {
+  EngineStatus,
+  PopoverConfig,
+  StepTimeline,
+  Walkthrough,
+  WalkthroughStep,
+  WalkthroughTimeline,
+} from "../types/walkthrough";
+import { abortableSleep } from "./abortableSleep";
+import { StepExecutor } from "./StepExecutor";
+import { TimelineBuilder } from "./TimelineBuilder";
+
+export interface EngineConfig {
+  registry: ActionHandlerRegistry;
+  adapter: CanvasAdapter;
+  store: WalkthroughStoreApi;
+}
+
+type InterruptKind = "none" | "pause" | "stop";
+
+/**
+ * Orchestrates walkthrough playback: timeline, steps, action pacing, popover typewriter.
+ * No React imports — inject {@link WalkthroughStoreApi} for UI sync.
+ */
+export class WalkthroughEngine {
+  private walkthrough: Walkthrough | null = null;
+  private timeline: WalkthroughTimeline | null = null;
+  private stepIndex = 0;
+  private status: EngineStatus = "idle";
+  private speed = 1;
+  private abortController: AbortController | null = null;
+  private elapsedMs = 0;
+  private currentExecutor: StepExecutor | null = null;
+  private interruptKind: InterruptKind = "none";
+
+  private readonly registry: ActionHandlerRegistry;
+  private readonly adapter: CanvasAdapter;
+  private readonly store: WalkthroughStoreApi;
+
+  constructor(config: EngineConfig) {
+    this.registry = config.registry;
+    this.adapter = config.adapter;
+    this.store = config.store;
+    this.speed = Math.max(0.05, this.store.getState().speed);
+  }
+
+  load(walkthrough: Walkthrough): void {
+    this.abortController?.abort();
+    this.walkthrough = walkthrough;
+    this.timeline = TimelineBuilder.build(walkthrough);
+    this.stepIndex = 0;
+    this.elapsedMs = 0;
+    this.currentExecutor?.cleanup();
+    this.currentExecutor = null;
+    this.interruptKind = "none";
+
+    this.setStatus("idle");
+    this.store.getState().setWalkthrough(walkthrough);
+    this.store.getState().setTimeline(this.timeline);
+    this.store.getState().setElapsedMs(0);
+    this.store.getState().setPopover(null);
+  }
+
+  async play(): Promise<void> {
+    if (this.status === "running") return;
+    if (!this.walkthrough || !this.timeline) return;
+
+    if (this.status === "complete") {
+      this.stepIndex = 0;
+      this.elapsedMs = 0;
+      this.store.getState().setElapsedMs(0);
+    }
+
+    this.speed = Math.max(0.05, this.store.getState().speed);
+    this.interruptKind = "none";
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+    this.setStatus("running");
+
+    try {
+      while (this.stepIndex < this.walkthrough.steps.length) {
+        if (signal.aborted) break;
+
+        const step = this.walkthrough.steps[this.stepIndex]!;
+        const stepTimeline = this.timeline.steps[this.stepIndex]!;
+        this.emitStep(step);
+
+        const executor = new StepExecutor(step, {
+          registry: this.registry,
+          adapter: this.adapter,
+          signal,
+          speed: this.speed,
+          onActionProgress: (actionIndex, elapsedInAction) => {
+            const actionMeta = stepTimeline.actions[actionIndex];
+            const start = actionMeta?.startMs ?? 0;
+            this.elapsedMs = stepTimeline.startMs + start + elapsedInAction;
+            this.emitProgress();
+          },
+        });
+
+        await executor.run();
+        this.currentExecutor = executor;
+
+        if (signal.aborted) break;
+
+        if (step.popover) {
+          this.emitPopover(step.popover);
+          await this.runTypewriter(step.popover.body, stepTimeline, signal);
+        }
+
+        if (signal.aborted) break;
+
+        if (step.popover) {
+          await abortableSleep(
+            DEFAULT_POST_POPOVER_PAUSE / this.speed,
+            signal,
+          );
+        }
+
+        if (signal.aborted) break;
+
+        this.stepIndex += 1;
+      }
+
+      if (!signal.aborted) {
+        this.setStatus("complete");
+        this.clearVisualChrome();
+      }
+    } finally {
+      if (signal.aborted && this.interruptKind === "pause") {
+        this.setStatus("paused");
+      }
+      this.interruptKind = "none";
+    }
+  }
+
+  pause(): void {
+    if (this.status !== "running") return;
+    this.interruptKind = "pause";
+    this.abortController?.abort();
+  }
+
+  stop(): void {
+    this.interruptKind = "stop";
+    this.abortController?.abort();
+    this.currentExecutor?.cleanup();
+    this.currentExecutor = null;
+    this.stepIndex = 0;
+    this.elapsedMs = 0;
+    this.store.getState().setElapsedMs(0);
+    this.clearVisualChrome();
+    this.setStatus("idle");
+  }
+
+  async seekToTime(ms: number): Promise<void> {
+    if (!this.walkthrough || !this.timeline) return;
+
+    this.interruptKind = "pause";
+    this.abortController?.abort();
+
+    const position = resolveTimelinePosition(this.timeline, ms);
+
+    this.currentExecutor?.cleanup();
+    this.currentExecutor = null;
+
+    this.store.getState().setPopover(null);
+
+    this.stepIndex = position.stepIndex;
+    this.elapsedMs = ms;
+
+    const step = this.walkthrough.steps[this.stepIndex];
+    if (!step) return;
+
+    this.emitStep(step);
+    const stepTimeline = this.timeline.steps[this.stepIndex]!;
+
+    const upToIndex =
+      position.phase === "actions"
+        ? (position.actionIndex ?? 0)
+        : step.actions.length - 1;
+
+    const executor = new StepExecutor(step, {
+      registry: this.registry,
+      adapter: this.adapter,
+      signal: new AbortController().signal,
+      speed: Number.POSITIVE_INFINITY,
+      skipDuration: true,
+    });
+
+    await executor.runUpTo(upToIndex);
+    this.currentExecutor = executor;
+
+    if (position.phase === "typewriter" && step.popover) {
+      this.emitPopover(step.popover);
+      this.store.getState().setTypewriter({
+        fullText: step.popover.body,
+        visibleText: step.popover.body.slice(0, position.charIndex ?? 0),
+        charIndex: position.charIndex ?? 0,
+        isTyping: false,
+      });
+    }
+
+    if (position.phase === "post-pause" && step.popover) {
+      this.emitPopover(step.popover);
+      this.store.getState().setTypewriter({
+        fullText: step.popover.body,
+        visibleText: step.popover.body,
+        charIndex: step.popover.body.length,
+        isTyping: false,
+      });
+    }
+
+    this.emitProgress();
+    this.setStatus("paused");
+  }
+
+  async seekToStep(stepId: string): Promise<void> {
+    if (!this.walkthrough || !this.timeline) return;
+    const idx = this.walkthrough.steps.findIndex((s) => s.id === stepId);
+    if (idx < 0) return;
+    const start = this.timeline.steps[idx]?.startMs ?? 0;
+    await this.seekToTime(start);
+  }
+
+  async next(): Promise<void> {
+    if (!this.walkthrough || !this.timeline) return;
+    const nextIdx = Math.min(
+      this.stepIndex + 1,
+      this.walkthrough.steps.length - 1,
+    );
+    const start = this.timeline.steps[nextIdx]?.startMs ?? 0;
+    await this.seekToTime(start);
+  }
+
+  async prev(): Promise<void> {
+    if (!this.timeline) return;
+    const prevIdx = Math.max(this.stepIndex - 1, 0);
+    const start = this.timeline.steps[prevIdx]?.startMs ?? 0;
+    await this.seekToTime(start);
+  }
+
+  setSpeed(speed: number): void {
+    this.speed = Math.max(0.05, speed);
+    this.store.getState().setSpeed(this.speed);
+  }
+
+  destroy(): void {
+    this.stop();
+    this.walkthrough = null;
+    this.timeline = null;
+  }
+
+  getStepIndex(): number {
+    return this.stepIndex;
+  }
+
+  getElapsedMs(): number {
+    return this.elapsedMs;
+  }
+
+  getStatus(): EngineStatus {
+    return this.status;
+  }
+
+  private async runTypewriter(
+    text: string,
+    stepTimeline: StepTimeline,
+    signal: AbortSignal,
+  ): Promise<void> {
+    const totalChars = text.length;
+    const msPerChar = TYPEWRITER_MS_PER_CHAR / this.speed;
+
+    this.store.getState().resetTypewriter(text);
+
+    for (let i = 0; i <= totalChars; i++) {
+      if (signal.aborted) break;
+
+      this.store.getState().setTypewriter({
+        charIndex: i,
+        visibleText: text.slice(0, i),
+        isTyping: i < totalChars,
+      });
+
+      this.elapsedMs =
+        stepTimeline.startMs +
+        stepTimeline.actionsDuration +
+        i * TYPEWRITER_MS_PER_CHAR;
+      this.emitProgress();
+
+      if (i < totalChars) {
+        await abortableSleep(msPerChar, signal);
+      }
+    }
+  }
+
+  private emitStep(step: WalkthroughStep): void {
+    this.store.getState().setCurrentStep(this.stepIndex, step.id);
+  }
+
+  private emitPopover(config: PopoverConfig): void {
+    this.store.getState().setPopover(config);
+  }
+
+  private emitProgress(): void {
+    this.store.getState().setElapsedMs(this.elapsedMs);
+  }
+
+  private setStatus(status: EngineStatus): void {
+    this.status = status;
+    this.store.getState().setStatus(status);
+  }
+
+  /** Clears popover, spotlight, code highlights, and forced code panels. */
+  private clearVisualChrome(): void {
+    this.store.getState().setPopover(null);
+    this.store.getState().setSpotlightNodeId(null);
+    this.store.getState().clearHighlightStore();
+    this.store.getState().clearForcedCodeOpen();
+  }
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/abortableSleep.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/abortableSleep.ts
new file mode 100644
index 00000000..8e72db85
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/abortableSleep.ts
@@ -0,0 +1,19 @@
+export function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  if (signal.aborted) return Promise.reject(new DOMException("Aborted", "AbortError"));
+
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(id);
+      signal.removeEventListener("abort", onAbort);
+      reject(new DOMException("Aborted", "AbortError"));
+    };
+
+    const id = globalThis.setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/index.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/index.ts
new file mode 100644
index 00000000..97ba527d
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/engine/index.ts
@@ -0,0 +1,5 @@
+export { abortableSleep } from "./abortableSleep";
+export { CleanupStack } from "./CleanupStack";
+export { StepExecutor, type StepExecutorContext } from "./StepExecutor";
+export { TimelineBuilder } from "./TimelineBuilder";
+export { WalkthroughEngine, type EngineConfig } from "./WalkthroughEngine";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/index.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/index.ts
new file mode 100644
index 00000000..e79aac78
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/index.ts
@@ -0,0 +1,3 @@
+export { usePopoverPosition } from "./usePopoverPosition";
+export { useTypewriter } from "./useTypewriter";
+export { useWalkthrough } from "./useWalkthrough";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/usePopoverPosition.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/usePopoverPosition.ts
new file mode 100644
index 00000000..1ebdb60c
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/usePopoverPosition.ts
@@ -0,0 +1,134 @@
+import { useMemo } from "react";
+import { useReactFlow } from "@xyflow/react";
+import type { PopoverAnchor } from "../types/walkthrough";
+
+/** Space between anchor (node edge) and popover content; keep in sync with PopoverContent `sideOffset`. */
+export const WALKTHROUGH_POPOVER_GAP = 12;
+
+function safeCssId(id: string): string {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(id);
+  }
+  return id.replace(/["\\]/g, "\\$&");
+}
+
+/** Midpoint on the node/canvas rect edge — Radix positions content on `side` with `sideOffset` beyond this point. */
+/** Anchor point on a small rect (e.g. one editor line) for Radix `side`. */
+function edgePointFromAnchorRect(
+  rect: DOMRect,
+  side: "top" | "bottom" | "left" | "right",
+): { x: number; y: number } {
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+  switch (side) {
+    case "top":
+      return { x: cx, y: rect.top };
+    case "bottom":
+      return { x: cx, y: rect.bottom };
+    case "left":
+      return { x: rect.left, y: cy };
+    case "right":
+    default:
+      return { x: rect.right, y: cy };
+  }
+}
+
+function edgePointFromRect(
+  rect: DOMRect,
+  side: "top" | "bottom" | "left" | "right",
+): { x: number; y: number } {
+  switch (side) {
+    case "top":
+      return { x: rect.left + rect.width / 2, y: rect.top };
+    case "bottom":
+      return { x: rect.left + rect.width / 2, y: rect.bottom };
+    case "left":
+      return { x: rect.left, y: rect.top + rect.height / 2 };
+    case "right":
+    default:
+      return { x: rect.right, y: rect.top + rect.height / 2 };
+  }
+}
+
+function viewportCenter(): { x: number; y: number } {
+  const pane =
+    document.querySelector<HTMLElement>(".react-flow__pane") ??
+    document.querySelector<HTMLElement>(".react-flow__viewport");
+  if (!pane) {
+    return {
+      x: globalThis.innerWidth / 2,
+      y: globalThis.innerHeight / 2,
+    };
+  }
+  const r = pane.getBoundingClientRect();
+  return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+}
+
+export interface PopoverAnchorPosition {
+  x: number;
+  y: number;
+  side: "top" | "bottom" | "left" | "right";
+}
+
+/**
+ * Resolves a Radix Popover anchor point (viewport px) and which side content opens on.
+ */
+export function usePopoverPosition(
+  anchor: PopoverAnchor,
+  preferredSide: "top" | "bottom" | "left" | "right" | undefined,
+  /** When set, recomputes `code-line` anchors after Monaco scroll/layout. */
+  codeAnchorLayoutEpoch?: number,
+): PopoverAnchorPosition {
+  const reactFlow = useReactFlow();
+
+  return useMemo(() => {
+    const side =
+      preferredSide ??
+      (anchor.type === "viewport-center" || anchor.type === "coordinates"
+        ? "bottom"
+        : "right");
+
+    switch (anchor.type) {
+      case "node": {
+        const el = document.querySelector<HTMLElement>(
+          `.react-flow__node[data-id="${safeCssId(anchor.nodeId)}"]`,
+        );
+        if (!el) return { ...viewportCenter(), side };
+        const rect = el.getBoundingClientRect();
+        return { ...edgePointFromRect(rect, side), side };
+      }
+      case "code-line": {
+        const marker = document.querySelector<HTMLElement>(
+          `[data-walkthrough-code-anchor][data-node-id="${safeCssId(anchor.nodeId)}"][data-line="${anchor.line}"]`,
+        );
+        if (marker) {
+          const r = marker.getBoundingClientRect();
+          if (r.width > 0 && r.height > 0) {
+            return { ...edgePointFromAnchorRect(r, side), side };
+          }
+        }
+        const el = document.querySelector<HTMLElement>(
+          `.react-flow__node[data-id="${safeCssId(anchor.nodeId)}"]`,
+        );
+        if (!el) return { ...viewportCenter(), side };
+        const rect = el.getBoundingClientRect();
+        return { ...edgePointFromRect(rect, side), side };
+      }
+      case "viewport-center":
+        return { ...viewportCenter(), side };
+      case "coordinates": {
+        try {
+          const p = reactFlow.flowToScreenPosition({
+            x: anchor.x,
+            y: anchor.y,
+          });
+          return { ...p, side };
+        } catch {
+          return { x: anchor.x, y: anchor.y, side };
+        }
+      }
+      default:
+        return { ...viewportCenter(), side: "bottom" };
+    }
+  }, [anchor, preferredSide, reactFlow, codeAnchorLayoutEpoch]);
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/useTypewriter.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/useTypewriter.ts
new file mode 100644
index 00000000..63d0f524
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/useTypewriter.ts
@@ -0,0 +1,6 @@
+/**
+ * Typewriter timing is driven by {@link WalkthroughEngine} (store updates each character).
+ * This hook is reserved for future client-side effects (e.g. reduced motion) without
+ * duplicating the engine loop.
+ */
+export function useTypewriter(): void {}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/useWalkthrough.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/useWalkthrough.ts
new file mode 100644
index 00000000..c2ad0337
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/hooks/useWalkthrough.ts
@@ -0,0 +1,68 @@
+import { useEffect, useMemo, useRef } from "react";
+import { useReactFlow } from "@xyflow/react";
+import { createDefaultRegistry } from "../actions/createDefaultRegistry";
+import { ReactFlowCanvasAdapter } from "../adapters/ReactFlowCanvasAdapter";
+import { WalkthroughEngine } from "../engine/WalkthroughEngine";
+import useProjectStore from "@/features/Dashboard/store/useProjectStore";
+import useTabStore from "@/features/Dashboard/store/useTabStore";
+import {
+  useWalkthroughStore,
+  type WalkthroughControls,
+} from "../store/useWalkthroughStore";
+import type { Walkthrough } from "../types/walkthrough";
+
+/**
+ * Builds engine + adapter for the canvas tab. Must run under ReactFlowProvider.
+ */
+export function useWalkthrough(canvasTabId: string): WalkthroughControls {
+  const reactFlow = useReactFlow();
+  const engineRef = useRef<WalkthroughEngine | null>(null);
+
+  const registry = useMemo(() => createDefaultRegistry(), []);
+
+  const adapter = useMemo(
+    () =>
+      new ReactFlowCanvasAdapter(
+        () => canvasTabId,
+        () => reactFlow,
+        useProjectStore,
+        useTabStore,
+        useWalkthroughStore,
+      ),
+    [canvasTabId, reactFlow],
+  );
+
+  useEffect(() => {
+    const engine = new WalkthroughEngine({
+      registry,
+      adapter,
+      store: useWalkthroughStore,
+    });
+    engineRef.current = engine;
+    return () => engine.destroy();
+  }, [registry, adapter]);
+
+  const speed = useWalkthroughStore((s) => s.speed);
+  useEffect(() => {
+    engineRef.current?.setSpeed(speed);
+  }, [speed]);
+
+  return useMemo(
+    (): WalkthroughControls => ({
+      load: (walkthrough: Walkthrough) => {
+        engineRef.current?.load(walkthrough);
+      },
+      play: () => engineRef.current?.play() ?? Promise.resolve(),
+      pause: () => engineRef.current?.pause(),
+      stop: () => engineRef.current?.stop(),
+      next: () => engineRef.current?.next() ?? Promise.resolve(),
+      prev: () => engineRef.current?.prev() ?? Promise.resolve(),
+      seekToStep: (stepId: string) =>
+        engineRef.current?.seekToStep(stepId) ?? Promise.resolve(),
+      seekToTime: (ms: number) =>
+        engineRef.current?.seekToTime(ms) ?? Promise.resolve(),
+      setSpeed: (s: number) => engineRef.current?.setSpeed(s),
+    }),
+    [],
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/index.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/index.ts
new file mode 100644
index 00000000..3da53ea4
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/index.ts
@@ -0,0 +1,7 @@
+export * from "./types";
+export * from "./adapters";
+export * from "./actions";
+export * from "./store";
+export * from "./engine";
+export * from "./hooks";
+export * from "./components";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/store/index.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/store/index.ts
new file mode 100644
index 00000000..e8d395e7
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/store/index.ts
@@ -0,0 +1,6 @@
+export {
+  useWalkthroughStore,
+  type WalkthroughControls,
+  type WalkthroughStoreApi,
+  type WalkthroughStoreState,
+} from "./useWalkthroughStore";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/store/useWalkthroughStore.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/store/useWalkthroughStore.ts
new file mode 100644
index 00000000..ace82ac8
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/store/useWalkthroughStore.ts
@@ -0,0 +1,230 @@
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+
+import type {
+  EngineStatus,
+  HighlightStyle,
+  LineRange,
+  PopoverConfig,
+  TypewriterState,
+  Walkthrough,
+  WalkthroughTimeline,
+} from "../types/walkthrough";
+
+export interface WalkthroughControls {
+  load: (walkthrough: Walkthrough) => void;
+  play: () => Promise<void>;
+  pause: () => void;
+  stop: () => void;
+  next: () => Promise<void>;
+  prev: () => Promise<void>;
+  seekToStep: (stepId: string) => Promise<void>;
+  seekToTime: (ms: number) => Promise<void>;
+  setSpeed: (speed: number) => void;
+}
+
+const initialTypewriter: TypewriterState = {
+  fullText: "",
+  visibleText: "",
+  isTyping: false,
+  charIndex: 0,
+};
+
+export interface WalkthroughStoreState {
+  status: EngineStatus;
+  walkthrough: Walkthrough | null;
+  timeline: WalkthroughTimeline | null;
+  elapsedMs: number;
+  currentStepIndex: number;
+  currentStepId: string | null;
+  totalSteps: number;
+  speed: number;
+
+  popover: PopoverConfig | null;
+  popoverVisible: boolean;
+
+  typewriter: TypewriterState;
+
+  spotlightNodeId: string | null;
+  highlights: Map<string, { lines: LineRange[]; style?: HighlightStyle }>;
+
+  /** Node ids whose inline code panel is forced open by the walkthrough adapter. */
+  forcedCodeOpen: Record<string, boolean>;
+
+  /**
+   * Bumped when an inline Monaco line anchor moves (scroll/layout) so PopoverLayer
+   * can re-read viewport coordinates for `code-line` anchors.
+   */
+  codeAnchorLayoutEpoch: number;
+
+  controls: WalkthroughControls | null;
+
+  /** When true, agent sidebar is hidden and the playback bar is shown on the canvas. */
+  playbackDetached: boolean;
+  setPlaybackDetached: (detached: boolean) => void;
+
+  setStatus: (status: EngineStatus) => void;
+  setWalkthrough: (wt: Walkthrough | null) => void;
+  setTimeline: (timeline: WalkthroughTimeline | null) => void;
+  setElapsedMs: (ms: number) => void;
+  setCurrentStep: (index: number, stepId: string | null) => void;
+  setSpeed: (speed: number) => void;
+
+  setPopover: (config: PopoverConfig | null) => void;
+  setPopoverVisible: (visible: boolean) => void;
+
+  setTypewriter: (partial: Partial<TypewriterState>) => void;
+  resetTypewriter: (fullText: string) => void;
+
+  setSpotlightNodeId: (nodeId: string | null) => void;
+
+  setHighlight: (
+    nodeId: string,
+    lines: LineRange[],
+    style?: HighlightStyle,
+  ) => void;
+  clearHighlightStore: (nodeId?: string) => void;
+
+  setForcedCodeOpen: (nodeId: string, open: boolean) => void;
+  clearForcedCodeOpen: () => void;
+
+  bumpCodeAnchorLayoutEpoch: () => void;
+
+  setControls: (controls: WalkthroughControls | null) => void;
+
+  reset: () => void;
+}
+
+export const useWalkthroughStore = create<WalkthroughStoreState>()(
+  devtools(
+    (set) => ({
+      status: "idle",
+      walkthrough: null,
+      timeline: null,
+      elapsedMs: 0,
+      currentStepIndex: 0,
+      currentStepId: null,
+      totalSteps: 0,
+      speed: 1,
+
+      popover: null,
+      popoverVisible: false,
+
+      typewriter: { ...initialTypewriter },
+
+      spotlightNodeId: null,
+      highlights: new Map(),
+
+      forcedCodeOpen: {},
+
+      codeAnchorLayoutEpoch: 0,
+
+      controls: null,
+
+      playbackDetached: false,
+      setPlaybackDetached: (detached) => set({ playbackDetached: detached }),
+
+      setStatus: (status) => set({ status }),
+
+      setWalkthrough: (wt) =>
+        set({
+          walkthrough: wt,
+          totalSteps: wt?.steps.length ?? 0,
+          currentStepIndex: 0,
+          currentStepId: wt?.steps[0]?.id ?? null,
+          forcedCodeOpen: {},
+        }),
+
+      setTimeline: (timeline) => set({ timeline }),
+
+      setElapsedMs: (ms) => set({ elapsedMs: Math.max(0, ms) }),
+
+      setCurrentStep: (index, stepId) =>
+        set({ currentStepIndex: index, currentStepId: stepId }),
+
+      setSpeed: (speed) => set({ speed }),
+
+      setPopover: (config) =>
+        set({
+          popover: config,
+          popoverVisible: config != null,
+        }),
+
+      setPopoverVisible: (visible) => set({ popoverVisible: visible }),
+
+      setTypewriter: (partial) =>
+        set((state) => ({
+          typewriter: { ...state.typewriter, ...partial },
+        })),
+
+      resetTypewriter: (fullText) =>
+        set({
+          typewriter: {
+            fullText,
+            visibleText: "",
+            isTyping: true,
+            charIndex: 0,
+          },
+        }),
+
+      setSpotlightNodeId: (nodeId) => set({ spotlightNodeId: nodeId }),
+
+      setHighlight: (nodeId, lines, style) =>
+        set((state) => {
+          const next = new Map(state.highlights);
+          next.set(nodeId, { lines, style });
+          return { highlights: next };
+        }),
+
+      clearHighlightStore: (nodeId) =>
+        set((state) => {
+          if (!nodeId) return { highlights: new Map() };
+          const next = new Map(state.highlights);
+          next.delete(nodeId);
+          return { highlights: next };
+        }),
+
+      setForcedCodeOpen: (nodeId, open) =>
+        set((state) => {
+          const next = { ...state.forcedCodeOpen };
+          if (open) {
+            next[nodeId] = true;
+          } else {
+            delete next[nodeId];
+          }
+          return { forcedCodeOpen: next };
+        }),
+
+      clearForcedCodeOpen: () => set({ forcedCodeOpen: {} }),
+
+      bumpCodeAnchorLayoutEpoch: () =>
+        set((s) => ({ codeAnchorLayoutEpoch: s.codeAnchorLayoutEpoch + 1 })),
+
+      setControls: (controls) => set({ controls }),
+
+      reset: () =>
+        set({
+          status: "idle",
+          walkthrough: null,
+          timeline: null,
+          elapsedMs: 0,
+          currentStepIndex: 0,
+          currentStepId: null,
+          totalSteps: 0,
+          speed: 1,
+          popover: null,
+          popoverVisible: false,
+          typewriter: { ...initialTypewriter },
+          spotlightNodeId: null,
+          highlights: new Map(),
+          forcedCodeOpen: {},
+          codeAnchorLayoutEpoch: 0,
+          controls: null,
+          playbackDetached: false,
+        }),
+    }),
+    { name: "walkthrough-store" },
+  ),
+);
+
+export type WalkthroughStoreApi = typeof useWalkthroughStore;
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/duration.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/duration.ts
new file mode 100644
index 00000000..6acb9a59
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/duration.ts
@@ -0,0 +1,54 @@
+import type { Action, WalkthroughStep } from "./walkthrough";
+
+export const TYPEWRITER_MS_PER_CHAR = 30;
+export const DEFAULT_POST_POPOVER_PAUSE = 500;
+
+export function getDefaultDuration(type: Action["type"]): number {
+  switch (type) {
+    case "focus-node":
+      return 500;
+    case "expand-node":
+      return 400;
+    case "collapse-node":
+      return 400;
+    case "show-code":
+      return 600;
+    case "close-code":
+      return 400;
+    case "highlight-code":
+      return 300;
+    case "clear-highlight":
+      return 200;
+    case "pan-canvas":
+      return 500;
+    case "select-node":
+      return 300;
+    case "create-tab":
+      return 800;
+    case "wait":
+      return 0;
+    default: {
+      const _exhaustive: never = type;
+      return _exhaustive;
+    }
+  }
+}
+
+/** Total duration of one step (actions + typewriter + post-popover pause). */
+export function computeStepDuration(step: WalkthroughStep): number {
+  const actionsDuration = step.actions.reduce((sum, action) => {
+    const d =
+      action.type === "wait"
+        ? action.ms
+        : (action.duration ?? getDefaultDuration(action.type));
+    return sum + d;
+  }, 0);
+
+  const typewriterDuration = step.popover
+    ? step.popover.body.length * TYPEWRITER_MS_PER_CHAR
+    : 0;
+
+  const postPause = step.popover ? DEFAULT_POST_POPOVER_PAUSE : 0;
+
+  return actionsDuration + typewriterDuration + postPause;
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/index.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/index.ts
new file mode 100644
index 00000000..772d63d3
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/index.ts
@@ -0,0 +1,3 @@
+export * from "./walkthrough";
+export * from "./duration";
+export { resolveTimelinePosition } from "./resolveTimelinePosition";
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/resolveTimelinePosition.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/resolveTimelinePosition.ts
new file mode 100644
index 00000000..692a5490
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/resolveTimelinePosition.ts
@@ -0,0 +1,47 @@
+import { TYPEWRITER_MS_PER_CHAR } from "./duration";
+import type { TimelinePosition, WalkthroughTimeline } from "./walkthrough";
+
+/**
+ * Map absolute timeline time (ms) to step phase, action index, or typewriter char.
+ */
+export function resolveTimelinePosition(
+  timeline: WalkthroughTimeline,
+  timeMs: number,
+): TimelinePosition {
+  if (timeline.steps.length === 0) {
+    return { stepIndex: 0, phase: "post-pause" };
+  }
+
+  const t = Math.max(0, Math.min(timeMs, timeline.totalDuration));
+
+  const step = timeline.steps.find((s) => t >= s.startMs && t < s.endMs);
+  if (!step) {
+    const last = timeline.steps[timeline.steps.length - 1]!;
+    return { stepIndex: last.stepIndex, phase: "post-pause" };
+  }
+
+  const elapsed = t - step.startMs;
+
+  if (elapsed < step.actionsDuration) {
+    const action = step.actions.find((a) => elapsed >= a.startMs && elapsed < a.endMs);
+    const actionIndex =
+      action?.actionIndex ??
+      (step.actions.length > 0 ? step.actions[step.actions.length - 1]!.actionIndex : 0);
+    const startMs = action?.startMs ?? 0;
+    return {
+      stepIndex: step.stepIndex,
+      phase: "actions",
+      actionIndex,
+      actionElapsedMs: elapsed - startMs,
+    };
+  }
+
+  const typewriterStart = step.actionsDuration;
+  if (elapsed < typewriterStart + step.typewriterDuration) {
+    const typewriterElapsed = elapsed - typewriterStart;
+    const charIndex = Math.floor(typewriterElapsed / TYPEWRITER_MS_PER_CHAR);
+    return { stepIndex: step.stepIndex, phase: "typewriter", charIndex };
+  }
+
+  return { stepIndex: step.stepIndex, phase: "post-pause" };
+}
diff --git a/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/walkthrough.ts b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/walkthrough.ts
new file mode 100644
index 00000000..9d4b24b6
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Agent/walkthrough/types/walkthrough.ts
@@ -0,0 +1,155 @@
+/** Root walkthrough document */
+export interface Walkthrough {
+  meta: WalkthroughMeta;
+  steps: WalkthroughStep[];
+}
+
+export interface WalkthroughMeta {
+  id: string;
+  title: string;
+  description?: string;
+  version: number;
+}
+
+export interface WalkthroughStep {
+  id: string;
+  actions: Action[];
+  popover?: PopoverConfig;
+}
+
+export interface ActionBase {
+  duration?: number;
+}
+
+export type Action =
+  | FocusNodeAction
+  | ExpandNodeAction
+  | CollapseNodeAction
+  | ShowCodeAction
+  | CloseCodeAction
+  | HighlightCodeAction
+  | ClearHighlightAction
+  | PanCanvasAction
+  | SelectNodeAction
+  | CreateTabAction
+  | WaitAction;
+
+export interface FocusNodeAction extends ActionBase {
+  type: "focus-node";
+  nodeId: string;
+}
+
+export interface ExpandNodeAction extends ActionBase {
+  type: "expand-node";
+  nodeId: string;
+}
+
+export interface CollapseNodeAction extends ActionBase {
+  type: "collapse-node";
+  nodeId: string;
+}
+
+export interface ShowCodeAction extends ActionBase {
+  type: "show-code";
+  nodeId: string;
+}
+
+export interface CloseCodeAction extends ActionBase {
+  type: "close-code";
+  nodeId: string;
+}
+
+export interface HighlightCodeAction extends ActionBase {
+  type: "highlight-code";
+  nodeId: string;
+  lines: LineRange[];
+  style?: HighlightStyle;
+}
+
+export interface ClearHighlightAction extends ActionBase {
+  type: "clear-highlight";
+  nodeId?: string;
+}
+
+export interface PanCanvasAction extends ActionBase {
+  type: "pan-canvas";
+  to: { nodeId: string };
+}
+
+export interface SelectNodeAction extends ActionBase {
+  type: "select-node";
+  nodeId: string;
+  selectionType: "primary" | "secondary" | "promote";
+}
+
+export interface CreateTabAction extends ActionBase {
+  type: "create-tab";
+  nodeId: string;
+}
+
+export interface WaitAction extends ActionBase {
+  type: "wait";
+  ms: number;
+}
+
+export interface LineRange {
+  from: number;
+  to: number;
+  label?: string;
+}
+
+export type HighlightStyle = "default" | "warning" | "added" | "removed" | "emphasis";
+
+export interface PopoverConfig {
+  title?: string;
+  body: string;
+  anchor: PopoverAnchor;
+  side?: "top" | "bottom" | "left" | "right";
+}
+
+export type PopoverAnchor =
+  | { type: "node"; nodeId: string }
+  | { type: "code-line"; nodeId: string; line: number }
+  | { type: "viewport-center" }
+  | { type: "coordinates"; x: number; y: number };
+
+/** Pre-computed timeline for the entire walkthrough */
+export interface WalkthroughTimeline {
+  totalDuration: number;
+  steps: StepTimeline[];
+}
+
+export interface StepTimeline {
+  stepIndex: number;
+  stepId: string;
+  startMs: number;
+  endMs: number;
+  actionsDuration: number;
+  typewriterDuration: number;
+  actions: ActionTimeline[];
+}
+
+export interface ActionTimeline {
+  actionIndex: number;
+  startMs: number;
+  endMs: number;
+  duration: number;
+}
+
+/** Resolved position within the walkthrough timeline */
+export interface TimelinePosition {
+  stepIndex: number;
+  phase: "actions" | "typewriter" | "post-pause";
+  actionIndex?: number;
+  actionElapsedMs?: number;
+  charIndex?: number;
+}
+
+export type EngineStatus = "idle" | "running" | "paused" | "complete";
+
+export interface TypewriterState {
+  fullText: string;
+  visibleText: string;
+  isTyping: boolean;
+  charIndex: number;
+}
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/EnhancedNode.tsx b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/EnhancedNode.tsx
index 8ed0ee33..5cfe6baa 100644
--- a/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/EnhancedNode.tsx
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/EnhancedNode.tsx
@@ -150,6 +150,7 @@ const EnhancedNode = memo(function EnhancedNode({
 
           {nodeCode.showCode && nodeCode.hasCode ? (
             <NodeCodeView
+              nodeId={data.nodeId}
               code={nodeCode.code}
               fileName={nodeCode.fileName}
               language={nodeCode.language}
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/NodeCodeView.tsx b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/NodeCodeView.tsx
index bcde1360..bc05b978 100644
--- a/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/NodeCodeView.tsx
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/NodeCodeView.tsx
@@ -2,6 +2,7 @@ import React, { memo, lazy, Suspense, useState } from "react";
 import { Save, Copy, Check, Maximize2 } from "lucide-react";
 import { DiffEditor } from "@monaco-editor/react";
 import { CodeViewDialog } from "./CodeViewDialog";
+import { useWalkthroughMonaco } from "./useWalkthroughMonaco";
 
 // Lazy load Monaco Editor
 const CodeEditor = lazy(() => import("@/components/CodeEditor"));
@@ -15,6 +16,8 @@ function CodeEditorSkeleton() {
 }
 
 interface NodeCodeViewProps {
+  /** Canvas node id — used for walkthrough Monaco highlights and line popover anchors. */
+  nodeId?: string;
   code: string;
   fileName: string;
   language: string;
@@ -33,6 +36,7 @@ interface NodeCodeViewProps {
 }
 
 export const NodeCodeView = memo(function NodeCodeView({
+  nodeId,
   code,
   fileName,
   language,
@@ -51,6 +55,10 @@ export const NodeCodeView = memo(function NodeCodeView({
 }: NodeCodeViewProps) {
   const [copied, setCopied] = useState(false);
   const [isExpanded, setIsExpanded] = useState(false);
+  const { onMount: walkthroughMonacoOnMount } = useWalkthroughMonaco(
+    nodeId,
+    showDiff,
+  );
 
   const handleCopy = (e: React.MouseEvent) => {
     e.stopPropagation();
@@ -165,8 +173,10 @@ export const NodeCodeView = memo(function NodeCodeView({
               value={code}
               onChange={onChange}
               isLoading={isLoading}
+              onMount={walkthroughMonacoOnMount}
               options={{
                 minimap: { enabled: false },
+                glyphMargin: true,
                 readOnly: false,
                 scrollBeyondLastLine: false,
                 fontSize: 12,
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/useNodeCode.ts b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/useNodeCode.ts
index a50f1175..362a3d5a 100644
--- a/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/useNodeCode.ts
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/useNodeCode.ts
@@ -4,6 +4,7 @@ import { useEditableCode } from "@/features/Dashboard/features/Main/components/C
 import { useCodeDiff } from "@/features/Dashboard/features/Main/components/Code/useCodeDiff";
 import { detectLanguage } from "@/components/CodeEditor/detectLanguage";
 import useProjectStore from "@/features/Dashboard/store/useProjectStore";
+import { useWalkthroughStore } from "@/features/Dashboard/features/Agent/walkthrough/store/useWalkthroughStore";
 
 export interface UseNodeCodeOptions {
   nodeId: string;
@@ -13,6 +14,9 @@ export interface UseNodeCodeOptions {
 
 export function useNodeCode({ nodeId, targetKey, nodeType }: UseNodeCodeOptions) {
   const [showCode, setShowCode] = useState(false);
+  const walkthroughForcesCode = useWalkthroughStore(
+    (s) => Boolean(nodeId && s.forcedCodeOpen[nodeId]),
+  );
   const { projectData } = useProjectStore();
   const projectId = projectData?.id;
 
@@ -25,8 +29,10 @@ export function useNodeCode({ nodeId, targetKey, nodeType }: UseNodeCodeOptions)
   // For call nodes, use the target's node type, otherwise use the node's type
   const effectiveNodeType = nodeType === "call" ? "call" : nodeType;
 
+  const revealCode = showCode || walkthroughForcesCode;
+
   const { data: codeData } = useCode(
-    showCode && shouldFetchCode ? effectiveNodeId : undefined,
+    revealCode && shouldFetchCode ? effectiveNodeId : undefined,
     effectiveNodeType,
     projectId
   );
@@ -64,7 +70,7 @@ export function useNodeCode({ nodeId, targetKey, nodeType }: UseNodeCodeOptions)
   const toggleCode = () => setShowCode((prev) => !prev);
 
   return {
-    showCode,
+    showCode: revealCode,
     toggleCode,
     hasCode,
     code: editorValue,
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/useWalkthroughMonaco.ts b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/useWalkthroughMonaco.ts
new file mode 100644
index 00000000..6bc350e9
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/components/nodes/useWalkthroughMonaco.ts
@@ -0,0 +1,175 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { editor } from "monaco-editor";
+import type { Monaco, OnMount } from "@monaco-editor/react";
+
+import { useWalkthroughStore } from "@/features/Dashboard/features/Agent/walkthrough/store/useWalkthroughStore";
+
+/**
+ * Walkthrough line highlights (Monaco decorations) + in-editor spotlight and
+ * a `data-walkthrough-code-anchor` node so PopoverLayer can anchor to a line.
+ * Mirrors Monaco tour patterns: getTopForLineNumber, scrollTop, getLayoutInfo content box.
+ */
+export function useWalkthroughMonaco(
+  nodeId: string | undefined,
+  showDiff: boolean,
+): { onMount: OnMount } {
+  const [editor, setEditor] = useState<editor.IStandaloneCodeEditor | null>(
+    null,
+  );
+  const monacoRef = useRef<Monaco | null>(null);
+  const decoIdsRef = useRef<string[]>([]);
+
+  const highlightsEntry = useWalkthroughStore((s) =>
+    nodeId ? s.highlights.get(nodeId) : undefined,
+  );
+  const popoverVisible = useWalkthroughStore((s) => s.popoverVisible);
+  const popover = useWalkthroughStore((s) => s.popover);
+
+  const onMount: OnMount = useCallback((ed, m) => {
+    monacoRef.current = m;
+    setEditor(ed);
+  }, []);
+
+  useEffect(() => {
+    if (!editor || showDiff || !monacoRef.current) return;
+    const m = monacoRef.current;
+    const model = editor.getModel();
+    if (!model) {
+      decoIdsRef.current = editor.deltaDecorations(decoIdsRef.current, []);
+      return;
+    }
+
+    const lines = highlightsEntry?.lines;
+    const decos =
+      lines?.flatMap((range) => {
+        const lc = model.getLineCount();
+        const from = Math.max(1, Math.min(range.from, lc));
+        const to = Math.max(from, Math.min(range.to, lc));
+        return {
+          range: new m.Range(from, 1, to, model.getLineMaxColumn(to)),
+          options: {
+            isWholeLine: true,
+            className: "walkthrough-monaco-line-deco",
+          },
+        };
+      }) ?? [];
+
+    decoIdsRef.current = editor.deltaDecorations(decoIdsRef.current, decos);
+    return () => {
+      decoIdsRef.current = editor.deltaDecorations(decoIdsRef.current, []);
+    };
+  }, [editor, showDiff, highlightsEntry]);
+
+  useEffect(() => {
+    if (!editor || showDiff || !highlightsEntry?.lines?.length) return;
+    const start = Math.min(...highlightsEntry.lines.map((l) => l.from));
+    const model = editor.getModel();
+    const lc = model?.getLineCount() ?? 0;
+    if (start >= 1 && start <= lc) {
+      editor.revealLineInCenter(start);
+    }
+  }, [editor, showDiff, highlightsEntry]);
+
+  useEffect(() => {
+    if (!editor || showDiff || !nodeId) return;
+    const root = editor.getDomNode();
+    if (!root) return;
+
+    const spotlight = document.createElement("div");
+    spotlight.className = "walkthrough-monaco-spotlight";
+    spotlight.setAttribute("aria-hidden", "true");
+
+    const anchorEl = document.createElement("div");
+    anchorEl.setAttribute("data-walkthrough-code-anchor", "");
+    anchorEl.setAttribute("data-node-id", nodeId);
+
+    root.appendChild(spotlight);
+    root.appendChild(anchorEl);
+
+    let bumpRaf = 0;
+    const bumpLayout = () => {
+      if (bumpRaf) return;
+      bumpRaf = requestAnimationFrame(() => {
+        bumpRaf = 0;
+        const st = useWalkthroughStore.getState();
+        const pa = st.popover?.anchor;
+        if (
+          st.popoverVisible &&
+          pa?.type === "code-line" &&
+          pa.nodeId === nodeId
+        ) {
+          st.bumpCodeAnchorLayoutEpoch();
+        }
+      });
+    };
+
+    const sync = () => {
+      const layout = editor.getLayoutInfo();
+      const model = editor.getModel();
+      const lc = model?.getLineCount() ?? 0;
+
+      const hl = highlightsEntry?.lines;
+      if (hl?.length && lc > 0) {
+        const start = Math.max(1, Math.min(Math.min(...hl.map((l) => l.from)), lc));
+        const end = Math.max(start, Math.min(Math.max(...hl.map((l) => l.to)), lc));
+        const top = editor.getTopForLineNumber(start) - editor.getScrollTop();
+        const bottom =
+          editor.getTopForLineNumber(end + 1) - editor.getScrollTop();
+        const height = Math.max(1, bottom - top);
+        spotlight.style.display = "block";
+        spotlight.style.top = `${top}px`;
+        spotlight.style.height = `${height}px`;
+        spotlight.style.left = `${layout.contentLeft}px`;
+        spotlight.style.width = `${layout.contentWidth}px`;
+      } else {
+        spotlight.style.display = "none";
+      }
+
+      const pa = popover?.anchor;
+      if (
+        popoverVisible &&
+        pa?.type === "code-line" &&
+        pa.nodeId === nodeId &&
+        lc > 0
+      ) {
+        const ln = Math.max(1, Math.min(pa.line, lc));
+        const top = editor.getTopForLineNumber(ln) - editor.getScrollTop();
+        const bottom = editor.getTopForLineNumber(ln + 1) - editor.getScrollTop();
+        const height = Math.max(1, bottom - top);
+        anchorEl.style.display = "block";
+        anchorEl.style.position = "absolute";
+        anchorEl.style.pointerEvents = "none";
+        anchorEl.style.top = `${top}px`;
+        anchorEl.style.height = `${height}px`;
+        anchorEl.style.left = `${layout.contentLeft}px`;
+        anchorEl.style.width = `${layout.contentWidth}px`;
+        anchorEl.setAttribute("data-line", String(pa.line));
+      } else {
+        anchorEl.style.display = "none";
+      }
+
+      bumpLayout();
+    };
+
+    const d1 = editor.onDidScrollChange(sync);
+    const d2 = editor.onDidLayoutChange(sync);
+    sync();
+
+    return () => {
+      if (bumpRaf) cancelAnimationFrame(bumpRaf);
+      d1.dispose();
+      d2.dispose();
+      spotlight.remove();
+      anchorEl.remove();
+    };
+  }, [
+    editor,
+    showDiff,
+    nodeId,
+    highlightsEntry,
+    popover,
+    popoverVisible,
+  ]);
+
+  return { onMount };
+}
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Canvas/index.tsx b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/index.tsx
index 98c2f7ea..d1ecd4ef 100644
--- a/src/frontend/src/features/Dashboard/features/Main/components/Canvas/index.tsx
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Canvas/index.tsx
@@ -1,7 +1,7 @@
 import React from "react";
 import { ReactFlowProvider } from "@xyflow/react";
 import CanvasView from "./components/CanvasView";
-// import useProjectStore from "@/features/Dashboard/store/useProjectStore";,
+import { WalkthroughProvider } from "@/features/Dashboard/features/Agent/walkthrough/components/WalkthroughProvider";
 
 interface CanvasProps {
   tabId: string;
@@ -9,11 +9,10 @@ interface CanvasProps {
 }
 
 const Canvas: React.FC<CanvasProps> = ({ tabId, projectId }) => {
-  // const { selectedNode, projectData, focusedNode } = useProjectStore();
-
   return (
     <ReactFlowProvider>
       <CanvasView tabId={tabId} projectId={projectId} />
+      <WalkthroughProvider tabId={tabId} />
     </ReactFlowProvider>
   );
 };
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Docs/DocumentEditor.tsx b/src/frontend/src/features/Dashboard/features/Main/components/Docs/DocumentEditor.tsx
index be1823d8..485f8027 100644
--- a/src/frontend/src/features/Dashboard/features/Main/components/Docs/DocumentEditor.tsx
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Docs/DocumentEditor.tsx
@@ -4,7 +4,7 @@ import { codeBlockOptions } from "@blocknote/code-block";
 import { useCreateBlockNote } from "@blocknote/react";
 import { BlockNoteView } from "@blocknote/shadcn";
 import "@blocknote/shadcn/style.css";
-import { BlockNoteSchema } from "@blocknote/core";
+import { BlockNoteSchema, type PartialBlock } from "@blocknote/core";
 
 import {
   SuggestionMenuController,
@@ -20,6 +20,42 @@ import type { DocumentData } from "@/services/documents";
 import { VersionDiffExtension } from "./Version";
 import { useDocumentDiff } from "./hooks/useDocumentDiff";
 
+/** Non-empty BlockNote JSON block array, or null to fall back to markdown / empty. */
+function parseBlockNoteJsonBlocks(trimmedJson: string): PartialBlock[] | null {
+  try {
+    const parsed: unknown = JSON.parse(trimmedJson);
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+      return null;
+    }
+    const valid = parsed.every(
+      (block: unknown) =>
+        block &&
+        typeof block === "object" &&
+        block !== null &&
+        "id" in block,
+    );
+    return valid ? (parsed as PartialBlock[]) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Stable key for skip-reload: prefer JSON blocks when valid, else markdown, else empty. */
+function documentContentFingerprint(jsonSource: string, markdownSource: string): string {
+  const jt = (jsonSource ?? "").trim();
+  if (jt) {
+    const blocks = parseBlockNoteJsonBlocks(jt);
+    if (blocks) {
+      return `j:${JSON.stringify(blocks)}`;
+    }
+  }
+  const mt = (markdownSource ?? "").trim();
+  if (mt) {
+    return `m:${mt}`;
+  }
+  return "e";
+}
+
 export interface DocumentEditorProps {
   /**
    * The document to edit. If undefined, shows empty state.
@@ -88,23 +124,29 @@ export function DocumentEditor({
     document,
     versionDiff,
   });
-  const editorData = isDiffActive
+  const jsonSource = isDiffActive
     ? (document?.compare_to?.data ?? document?.data ?? "")
     : (document?.data ?? "");
+  const markdownSource = isDiffActive
+    ? (document?.compare_to?.markdown ?? document?.markdown ?? "")
+    : (document?.markdown ?? "");
 
   // Debounced save function
   const saveDocumentDebounced = useMemo(
     () =>
       debounce(
-        (payload: { id: string; node_id: string; data: string }) => {
+        (payload: { id: string; node_id: string; data: string; markdown: string }) => {
           if (autoSave && nodeId && projectId) {
-            // Update lastAppliedDataRef to the data we're about to save
-            // This prevents reloading when cache updates with the same content
-            lastAppliedDataRef.current = payload.data;
+            // Match fingerprint logic in the load effect to avoid a reload flash after save
+            lastAppliedDataRef.current = documentContentFingerprint(
+              payload.data,
+              payload.markdown,
+            );
             updateMutation.mutate({
               id: payload.id,
               node_id: payload.node_id,
               data: payload.data,
+              markdown: payload.markdown,
             });
           }
         },
@@ -129,81 +171,39 @@ export function DocumentEditor({
       return;
     }
 
-    const data = editorData;
-
-    // Skip if we've already applied this exact content
-    // Compare by value, not reference, to handle cache updates with same content
-    if (lastAppliedDataRef.current === data) return;
-
-    // Also check if the content is semantically the same (normalized JSON comparison)
-    // This handles cases where cache updates might have slightly different formatting
-    if (lastAppliedDataRef.current && data) {
-      try {
-        const currentParsed = JSON.parse(lastAppliedDataRef.current);
-        const newParsed = JSON.parse(data);
-        // Deep equality check for JSON content
-        if (JSON.stringify(currentParsed) === JSON.stringify(newParsed)) {
-          // Content is the same, just update the ref and skip reloading
-          lastAppliedDataRef.current = data;
-          return;
-        }
-      } catch {
-        // If parsing fails, fall through to normal comparison
-      }
-    }
+    const fingerprint = documentContentFingerprint(jsonSource, markdownSource);
+    if (lastAppliedDataRef.current === fingerprint) return;
 
     applyingRemoteContent.current = true;
 
     const loadContent = async () => {
       try {
-        // Handle empty or whitespace-only data before parsing
-        const trimmed = (data ?? "").trim();
-        if (!trimmed) {
-          editor.replaceBlocks(editor.document, []);
-          lastAppliedDataRef.current = data;
+        const trimmedJson = (jsonSource ?? "").trim();
+        const blocksFromJson = trimmedJson
+          ? parseBlockNoteJsonBlocks(trimmedJson)
+          : null;
+
+        if (blocksFromJson) {
+          editor.replaceBlocks(editor.document, blocksFromJson);
+          lastAppliedDataRef.current = fingerprint;
           return;
         }
 
-        // Parse JSON (BlockNote blocks)
-        const parsedDocument = JSON.parse(trimmed);
-
-        // Validate that parsedDocument is an array of blocks
-        if (Array.isArray(parsedDocument)) {
-          // Validate blocks have required structure (if array is not empty)
-          if (parsedDocument.length === 0) {
-            // Empty content - clear editor
-            editor.replaceBlocks(editor.document, []);
-            lastAppliedDataRef.current = data;
-
-            return;
-          }
-
-          const isValidBlocks = parsedDocument.every(
-            (block: unknown) =>
-              block &&
-              typeof block === "object" &&
-              block !== null &&
-              "id" in block,
-          );
-
-          if (isValidBlocks) {
-            // Replace all blocks at once - BlockNote handles the replacement
-            editor.replaceBlocks(editor.document, parsedDocument);
-            lastAppliedDataRef.current = data;
-            return;
-          }
+        const trimmedMd = (markdownSource ?? "").trim();
+        if (trimmedMd) {
+          const mdBlocks = editor.tryParseMarkdownToBlocks(trimmedMd);
+          editor.replaceBlocks(editor.document, mdBlocks);
+          lastAppliedDataRef.current = fingerprint;
+          return;
         }
 
-        // If JSON parsing fails or invalid format, clear editor
-        console.error("Invalid block format, clearing editor");
         editor.replaceBlocks(editor.document, []);
-        lastAppliedDataRef.current = "";
-      } catch (jsonErr) {
-        // If JSON parsing fails, treat as empty and clear editor
-        console.error("Error parsing document JSON:", jsonErr);
+        lastAppliedDataRef.current = fingerprint;
+      } catch (err) {
+        console.error("Error loading document content:", err);
         try {
           editor.replaceBlocks(editor.document, []);
-          lastAppliedDataRef.current = "";
+          lastAppliedDataRef.current = fingerprint;
         } catch (clearErr) {
           console.error("Error clearing editor:", clearErr);
           lastAppliedDataRef.current = null;
@@ -217,13 +217,21 @@ export function DocumentEditor({
     };
 
     loadContent();
-  }, [editor, document, document?.id, document?.data, document?.compare_to?.data, editorData]);
+  }, [
+    editor,
+    document,
+    document?.id,
+    jsonSource,
+    markdownSource,
+    isDiffActive,
+  ]);
 
   // Handle content changes
   const handleChange = async (currentEditor: typeof editor) => {
     if (applyingRemoteContent.current) return;
 
     const jsonData = JSON.stringify(currentEditor.document);
+    const markdown = currentEditor.blocksToMarkdownLossy(currentEditor.document);
 
     // Call onChange callback immediately
     onChange?.(jsonData);
@@ -234,6 +242,7 @@ export function DocumentEditor({
         id: document.id,
         node_id: nodeId,
         data: jsonData,
+        markdown,
       });
     }
   };
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Docs/index.tsx b/src/frontend/src/features/Dashboard/features/Main/components/Docs/index.tsx
index 5bc16ecb..31c79ab0 100644
--- a/src/frontend/src/features/Dashboard/features/Main/components/Docs/index.tsx
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Docs/index.tsx
@@ -6,7 +6,7 @@ type DocumentsProps = {
    * Document to edit. Can be DocumentType or legacy format { id, data }.
    * If undefined, shows empty state.
    */
-  document?: DocumentData | { id: string; data?: string } | null;
+  document?: DocumentData | { id: string; data?: string; markdown?: string } | null;
 
   /**
    * Callback when document content changes.
@@ -29,8 +29,20 @@ type DocumentsProps = {
  * @deprecated Consider using DocumentEditor directly for new code.
  */
 const Documents = ({ document, onChange, nodeId }: DocumentsProps) => {
-  // Convert legacy format to DocumentType
-  const doc: DocumentData | null = document;
+  const doc: DocumentData | null =
+    !document
+      ? null
+      : "name" in document
+        ? document
+        : {
+            id: document.id,
+            name: "",
+            description: "",
+            data: document.data ?? "",
+            markdown: "markdown" in document ? (document.markdown ?? "") : "",
+            created_at: "",
+            updated_at: "",
+          };
 
   return (
     <DocumentEditor
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/components/PlaygroundFormDialog.tsx b/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/components/PlaygroundFormDialog.tsx
new file mode 100644
index 00000000..bd2632c4
--- /dev/null
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/components/PlaygroundFormDialog.tsx
@@ -0,0 +1,112 @@
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Label } from "@/components/ui/label";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+
+export interface PlaygroundFormValues {
+  name: string;
+  description: string;
+  relative_path: string;
+  executable_path: string;
+  filename: string;
+}
+
+interface PlaygroundFormDialogProps {
+  open: boolean;
+  isUpdate: boolean;
+  values: PlaygroundFormValues;
+  isSubmitting?: boolean;
+  onOpenChange: (open: boolean) => void;
+  onChange: (next: PlaygroundFormValues) => void;
+  onSubmit: () => void;
+}
+
+export default function PlaygroundFormDialog({
+  open,
+  isUpdate,
+  values,
+  isSubmitting = false,
+  onOpenChange,
+  onChange,
+  onSubmit,
+}: PlaygroundFormDialogProps) {
+  const title = isUpdate ? "Update Playground" : "Create Playground";
+  const submitLabel = isUpdate ? "Update" : "Create";
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+        </DialogHeader>
+        <div className="grid gap-4 py-2">
+          <div className="grid gap-2">
+            <Label htmlFor="playgroundName">Name</Label>
+            <Input
+              id="playgroundName"
+              value={values.name}
+              onChange={(e) => onChange({ ...values, name: e.target.value })}
+            />
+          </div>
+          <div className="grid gap-2">
+            <Label htmlFor="playgroundDescription">Description</Label>
+            <Input
+              id="playgroundDescription"
+              value={values.description}
+              onChange={(e) =>
+                onChange({ ...values, description: e.target.value })
+              }
+            />
+          </div>
+          <div className="grid gap-2">
+            <Label htmlFor="playgroundRelativePath">Relative path</Label>
+            <Input
+              id="playgroundRelativePath"
+              value={values.relative_path}
+              onChange={(e) =>
+                onChange({ ...values, relative_path: e.target.value })
+              }
+            />
+          </div>
+          <div className="grid gap-2">
+            <Label htmlFor="playgroundExecutablePath">Executable path</Label>
+            <Input
+              id="playgroundExecutablePath"
+              value={values.executable_path}
+              onChange={(e) =>
+                onChange({ ...values, executable_path: e.target.value })
+              }
+            />
+          </div>
+          <div className="grid gap-2">
+            <Label htmlFor="playgroundFilename">Filename</Label>
+            <Input
+              id="playgroundFilename"
+              value={values.filename}
+              onChange={(e) => onChange({ ...values, filename: e.target.value })}
+            />
+          </div>
+        </div>
+        <DialogFooter>
+          <Button
+            type="button"
+            variant="outline"
+            onClick={() => onOpenChange(false)}
+            disabled={isSubmitting}
+          >
+            Cancel
+          </Button>
+          <Button type="button" onClick={onSubmit} disabled={isSubmitting}>
+            {submitLabel}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/hooks/usePlaygroundState.ts b/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/hooks/usePlaygroundState.ts
index 0e300955..ce340f1a 100644
--- a/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/hooks/usePlaygroundState.ts
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/hooks/usePlaygroundState.ts
@@ -1,60 +1,265 @@
-import { useState, useMemo, useCallback } from "react";
+import { useState, useMemo, useCallback, useEffect, useRef } from "react";
 import { type SelectableItem } from "../components/SelectableList";
-import { useRunCode } from "@/features/Dashboard/features/Main/hooks/usePlayGround";
 import useProjectStore from "@/features/Dashboard/store/useProjectStore";
+import type { AnyNodeTree, CallNodeTree } from "@/types/project";
+import type { CreatePlaygroundPayload } from "@/types/playground";
+import {
+  useCreatePlayground,
+  useDeletePlayground,
+  usePlaygroundsByOwner,
+  useRunPlaygroundCode,
+  useUpdatePlayground,
+} from "@/services/playground";
+import { toast } from "sonner";
+import type { PlaygroundFormValues } from "../components/PlaygroundFormDialog";
 
 /**
  * Hook to manage Playground internal state.
  */
-export function usePlaygroundState(onRunningChange?: (isRunning: boolean) => void) {
+const DEFAULT_CODE = "# write your code here";
+
+function toEffectiveNode(
+  selectedNode: AnyNodeTree | null | undefined,
+  secondarySelectedNode: AnyNodeTree | null | undefined
+) {
+  if (secondarySelectedNode) {
+    if ((secondarySelectedNode as CallNodeTree).target) {
+      return (secondarySelectedNode as CallNodeTree).target;
+    }
+    return secondarySelectedNode;
+  }
+  if (selectedNode?.node_type === "call") {
+    return (selectedNode as CallNodeTree).target;
+  }
+  return selectedNode;
+}
+
+function getOwnerFieldPayload(
+  nodeId: string,
+  nodeType: string
+): Pick<
+  CreatePlaygroundPayload,
+  "owner_function" | "owner_class" | "owner_file" | "owner_folder"
+> {
+  if (nodeType === "function") return { owner_function: nodeId };
+  if (nodeType === "class") return { owner_class: nodeId };
+  if (nodeType === "file") return { owner_file: nodeId };
+  if (nodeType === "folder") return { owner_folder: nodeId };
+  throw new Error("Playground owner must be function, class, file, or folder");
+}
+
+export function usePlaygroundState(
+  tabId: string,
+  onRunningChange?: (isRunning: boolean) => void
+) {
   const [code, setCode] = useState("# write your code here");
-  const [items, setItems] = useState<SelectableItem[]>([
-    { id: "playground", label: "Playground" },
-  ]);
-  const [selectedId, setSelectedId] = useState<string | undefined>("playground");
+  const [selectedId, setSelectedId] = useState<string | undefined>();
   const [output, setOutput] = useState<string>("");
   const [settingsOpen, setSettingsOpen] = useState(false);
   const [examplesPath, setExamplesPath] = useState("");
   const [commandPrefix, setCommandPrefix] = useState("python");
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [editingPlaygroundId, setEditingPlaygroundId] = useState<string | null>(
+    null
+  );
+  const [formValues, setFormValues] = useState<PlaygroundFormValues>({
+    name: "",
+    description: "",
+    relative_path: "",
+    executable_path: "",
+    filename: "playground.py",
+  });
 
   const project = useProjectStore((s) => s.projectData);
-  const runCode = useRunCode(project?.id);
+  const selectedNode = useProjectStore((s) => s.selectedNode[tabId]);
+  const secondarySelectedNode = useProjectStore(
+    (s) => s.secondarySelectedNode[tabId]
+  );
+  const projectId = project?.id ?? "";
+  const effectiveNode = useMemo(
+    () => toEffectiveNode(selectedNode, secondarySelectedNode),
+    [selectedNode, secondarySelectedNode]
+  );
+  const ownerNodeId = effectiveNode?.id ?? null;
+
+  const { data: playgrounds = [] } = usePlaygroundsByOwner(ownerNodeId, projectId);
+  const createPlayground = useCreatePlayground(projectId);
+  const updatePlayground = useUpdatePlayground(projectId);
+  const deletePlayground = useDeletePlayground(projectId);
+  const runPlaygroundCode = useRunPlaygroundCode(projectId);
+  const codeUpdateTimer = useRef<number | null>(null);
+  const didHydrateCodeRef = useRef(false);
+
+  const items = useMemo<SelectableItem[]>(
+    () =>
+      playgrounds.map((item) => ({
+        id: item.id,
+        label: item.name || item.filename || "Untitled playground",
+      })),
+    [playgrounds]
+  );
+
+  const selectedPlayground = useMemo(
+    () => playgrounds.find((item) => item.id === selectedId) ?? null,
+    [playgrounds, selectedId]
+  );
+
+  useEffect(() => {
+    if (!playgrounds.length) {
+      setSelectedId(undefined);
+      setCode(DEFAULT_CODE);
+      didHydrateCodeRef.current = false;
+      return;
+    }
+
+    const currentExists = playgrounds.some((item) => item.id === selectedId);
+    if (!selectedId || !currentExists) {
+      setSelectedId(playgrounds[0].id);
+    }
+  }, [playgrounds, selectedId]);
+
+  useEffect(() => {
+    if (!selectedPlayground) return;
+    setCode(selectedPlayground.code || DEFAULT_CODE);
+    didHydrateCodeRef.current = true;
+  }, [selectedPlayground?.id]);
 
   const handleRun = useCallback(async () => {
+    if (!selectedPlayground) {
+      setOutput("Create or select a playground first.");
+      return;
+    }
     onRunningChange?.(true);
-    const relativeFile = selectedId === "playground" ? "playground.py" : `${selectedId}.py`;
-    const fullPath = `${examplesPath}/${relativeFile}`;
-    const runCommand = `${commandPrefix} ${fullPath}`;
-    setOutput(`Command: ${runCommand}`);
+    setOutput("Running playground...");
 
     try {
-      const resp = await runCode.mutateAsync({
-        code,
-        executable_path: null,
-        examples_path: examplesPath,
-        command_prefix: commandPrefix,
-        filename: relativeFile,
+      const resp = await runPlaygroundCode.mutateAsync({
+        playground_id: selectedPlayground.id,
       });
-      setOutput((prev) => `${prev}\n${resp.response}`);
+      setOutput(resp.response || "");
     } catch {
-      setOutput((prev) => `${prev}\nError running code`);
+      setOutput("Error running code");
     } finally {
       onRunningChange?.(false);
     }
-  }, [code, selectedId, examplesPath, commandPrefix, runCode, onRunningChange]);
+  }, [onRunningChange, runPlaygroundCode, selectedPlayground]);
+
+  useEffect(() => {
+    if (!selectedPlayground || !didHydrateCodeRef.current) return;
+    if (code === (selectedPlayground.code || "")) return;
+
+    if (codeUpdateTimer.current) {
+      window.clearTimeout(codeUpdateTimer.current);
+    }
+    codeUpdateTimer.current = window.setTimeout(() => {
+      void updatePlayground.mutateAsync({
+        playgroundId: selectedPlayground.id,
+        payload: { code },
+      });
+    }, 500);
+
+    return () => {
+      if (codeUpdateTimer.current) {
+        window.clearTimeout(codeUpdateTimer.current);
+      }
+    };
+  }, [code, selectedPlayground, updatePlayground]);
 
   const handleAddSnippet = useCallback(() => {
-    const newId = `snippet-${Math.random().toString(36).slice(2, 8)}`;
-    const newItem = { id: newId, label: `Snippet ${items.length}` };
-    setItems((prev) => [...prev, newItem]);
-    setSelectedId(newId);
-  }, [items.length]);
+    if (!effectiveNode?.id || !effectiveNode?.node_type) {
+      toast.error("Select a function, class, file, or folder first.");
+      return;
+    }
+    if (
+      !["function", "class", "file", "folder"].includes(effectiveNode.node_type)
+    ) {
+      toast.error("Playground owner must be function, class, file, or folder.");
+      return;
+    }
+    setEditingPlaygroundId(null);
+    setFormValues({
+      name: "",
+      description: "",
+      relative_path: "",
+      executable_path: "",
+      filename: "playground.py",
+    });
+    setDialogOpen(true);
+  }, [effectiveNode]);
+
+  const handleEditSnippet = useCallback(() => {
+    if (!selectedPlayground) return;
+    setEditingPlaygroundId(selectedPlayground.id);
+    setFormValues({
+      name: selectedPlayground.name || "",
+      description: selectedPlayground.description || "",
+      relative_path: selectedPlayground.relative_path || "",
+      executable_path: selectedPlayground.executable_path || "",
+      filename: selectedPlayground.filename || "",
+    });
+    setDialogOpen(true);
+  }, [selectedPlayground]);
+
+  const handleSubmitDialog = useCallback(async () => {
+    const name = formValues.name.trim();
+    const relativePath = formValues.relative_path.trim();
+    if (!name || !relativePath) {
+      toast.error("Name and relative path are required.");
+      return;
+    }
+
+    if (editingPlaygroundId) {
+      await updatePlayground.mutateAsync({
+        playgroundId: editingPlaygroundId,
+        payload: {
+          name,
+          description: formValues.description,
+          relative_path: relativePath,
+          executable_path: formValues.executable_path || null,
+          filename: formValues.filename || null,
+        },
+      });
+      setDialogOpen(false);
+      return;
+    }
+
+    if (!effectiveNode?.id || !effectiveNode?.node_type) {
+      toast.error("Select a valid owner node first.");
+      return;
+    }
+
+    let ownerFieldPayload: ReturnType<typeof getOwnerFieldPayload>;
+    try {
+      ownerFieldPayload = getOwnerFieldPayload(effectiveNode.id, effectiveNode.node_type);
+    } catch (error) {
+      toast.error((error as Error).message);
+      return;
+    }
+
+    const created = await createPlayground.mutateAsync({
+      name,
+      description: formValues.description,
+      relative_path: relativePath,
+      executable_path: formValues.executable_path || null,
+      filename: formValues.filename || null,
+      code: code || DEFAULT_CODE,
+      ...ownerFieldPayload,
+    });
+    setSelectedId(created.id);
+    setDialogOpen(false);
+  }, [
+    code,
+    createPlayground,
+    editingPlaygroundId,
+    effectiveNode,
+    formValues,
+    updatePlayground,
+  ]);
 
   const handleRemoveSnippet = useCallback((id: string) => {
-    if (id === "playground") return;
-    setItems((prev) => prev.filter((x) => x.id !== id));
-    if (selectedId === id) setSelectedId("playground");
-  }, [selectedId]);
+    void deletePlayground.mutateAsync(id);
+    if (selectedId === id) setSelectedId(undefined);
+  }, [deletePlayground, selectedId]);
 
   return {
     code,
@@ -70,8 +275,16 @@ export function usePlaygroundState(onRunningChange?: (isRunning: boolean) => voi
     setExamplesPath,
     commandPrefix,
     setCommandPrefix,
+    dialogOpen,
+    setDialogOpen,
+    formValues,
+    setFormValues,
+    editingPlaygroundId,
+    isDialogSubmitting: createPlayground.isPending || updatePlayground.isPending,
     handleRun,
     handleAddSnippet,
+    handleEditSnippet,
+    handleSubmitDialog,
     handleRemoveSnippet,
   };
 }
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/index.tsx b/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/index.tsx
index 14ea20b8..a7ae1a22 100644
--- a/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/index.tsx
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/features/Playground/index.tsx
@@ -8,8 +8,9 @@ import {
   ResizablePanelGroup,
   ResizableHandle,
 } from "@/components/ui/resizable";
-import { PlusIcon } from "lucide-react";
+import { PencilIcon, PlusIcon } from "lucide-react";
 import SettingsDialog from "./components/SettingsDialog";
+import PlaygroundFormDialog from "./components/PlaygroundFormDialog";
 
 export type PlayGroundHandle = {
   run: () => void;
@@ -17,6 +18,7 @@ export type PlayGroundHandle = {
 };
 
 interface PlaygroundProps {
+  tabId: string;
   onRunningChange?: (isRunning: boolean) => void;
 }
 
@@ -25,7 +27,7 @@ interface PlaygroundProps {
  * Orchestrates the code execution environment.
  */
 const Playground = forwardRef<PlayGroundHandle, PlaygroundProps>(
-  ({ onRunningChange }, ref) => {
+  ({ tabId, onRunningChange }, ref) => {
     const {
       code,
       setCode,
@@ -39,10 +41,18 @@ const Playground = forwardRef<PlayGroundHandle, PlaygroundProps>(
       setExamplesPath,
       commandPrefix,
       setCommandPrefix,
+      dialogOpen,
+      setDialogOpen,
+      formValues,
+      setFormValues,
+      editingPlaygroundId,
+      isDialogSubmitting,
       handleRun,
       handleAddSnippet,
+      handleEditSnippet,
+      handleSubmitDialog,
       handleRemoveSnippet,
-    } = usePlaygroundState(onRunningChange);
+    } = usePlaygroundState(tabId, onRunningChange);
 
     const language = useMemo(() => detectLanguage("snippet.py"), []);
 
@@ -61,13 +71,23 @@ const Playground = forwardRef<PlayGroundHandle, PlaygroundProps>(
             <div className="flex h-full flex-col gap-2 pr-2 rounded p-2 border bg-white">
               <div className="flex items-center justify-between border-b pb-2">
                 <div className="text-sm font-medium text-muted-foreground">Files</div>
-                <button
-                  type="button"
-                  onClick={handleAddSnippet}
-                  className="h-6 w-6 rounded border text-xs leading-6 flex justify-center items-center hover:bg-accent"
-                >
-                  <PlusIcon size={15} />
-                </button>
+                <div className="flex items-center gap-1">
+                  <button
+                    type="button"
+                    onClick={handleEditSnippet}
+                    disabled={!selectedId}
+                    className="h-6 w-6 rounded border text-xs leading-6 flex justify-center items-center hover:bg-accent disabled:opacity-50"
+                  >
+                    <PencilIcon size={14} />
+                  </button>
+                  <button
+                    type="button"
+                    onClick={handleAddSnippet}
+                    className="h-6 w-6 rounded border text-xs leading-6 flex justify-center items-center hover:bg-accent"
+                  >
+                    <PlusIcon size={15} />
+                  </button>
+                </div>
               </div>
               <SelectableList
                 items={items}
@@ -119,6 +139,17 @@ const Playground = forwardRef<PlayGroundHandle, PlaygroundProps>(
           onChangeExamplesPath={setExamplesPath}
           onChangeCommandPrefix={setCommandPrefix}
         />
+        <PlaygroundFormDialog
+          open={dialogOpen}
+          onOpenChange={setDialogOpen}
+          isUpdate={Boolean(editingPlaygroundId)}
+          values={formValues}
+          isSubmitting={isDialogSubmitting}
+          onChange={setFormValues}
+          onSubmit={() => {
+            void handleSubmitDialog();
+          }}
+        />
       </div>
     );
   }
diff --git a/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/index.tsx b/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/index.tsx
index f9e4773a..cc46c4c2 100644
--- a/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/index.tsx
+++ b/src/frontend/src/features/Dashboard/features/Main/components/Sandbox/index.tsx
@@ -72,7 +72,11 @@ export default function Sandbox({ tabId }: { tabId: string }) {
           value="playground"
           className="m-0 h-full overflow-hidden outline-none"
         >
-          <Playground ref={playgroundRef} onRunningChange={setIsRunning} />
+          <Playground
+            ref={playgroundRef}
+            tabId={tabId}
+            onRunningChange={setIsRunning}
+          />
         </TabsContent>
 
         <TabsContent
diff --git a/src/frontend/src/features/Dashboard/features/Navbar/components/Navbar.tsx b/src/frontend/src/features/Dashboard/features/Navbar/components/Navbar.tsx
index 46667042..2f806ef7 100644
--- a/src/frontend/src/features/Dashboard/features/Navbar/components/Navbar.tsx
+++ b/src/frontend/src/features/Dashboard/features/Navbar/components/Navbar.tsx
@@ -9,7 +9,7 @@ import {
 } from "@/components/ui/menubar";
 import { ProgressIndicator } from "./ProgressIndicator";
 import HistoryButton from "../../Versioning/components/HistoryButton";
-// import { AgentToggleButton } from "../../Agent/components/AgentToggleButton";
+import { AgentToggleButton } from "../../Agent/components/AgentToggleButton";
 
 interface NavbarProps {
   projectId?: string;
@@ -45,7 +45,7 @@ const Navbar = ({ projectId }: NavbarProps) => {
       </Menubar>
       <div className="flex items-center gap-2 mr-4">
         <ProgressIndicator projectId={projectId} />
-        {/* <AgentToggleButton /> */}
+        <AgentToggleButton />
         <HistoryButton />
       </div>
     </div>
diff --git a/src/frontend/src/features/Dashboard/hooks/useNodeHandlers.ts b/src/frontend/src/features/Dashboard/hooks/useNodeHandlers.ts
index 08566322..8bd2344a 100644
--- a/src/frontend/src/features/Dashboard/hooks/useNodeHandlers.ts
+++ b/src/frontend/src/features/Dashboard/hooks/useNodeHandlers.ts
@@ -81,6 +81,7 @@ export function useNodeHandlers(nodeId: string, tabId: string) {
       case 'manage-group':
       case 'add-call':
       case 'prompt-builder':
+      case 'start-workflow':
       case 'edit-virtual':
         openModal(action as any, node as AnyNodeTree);
         break;
diff --git a/src/frontend/src/features/Dashboard/store/useSidebarModalStore.ts b/src/frontend/src/features/Dashboard/store/useSidebarModalStore.ts
index 7992b9ed..17724941 100644
--- a/src/frontend/src/features/Dashboard/store/useSidebarModalStore.ts
+++ b/src/frontend/src/features/Dashboard/store/useSidebarModalStore.ts
@@ -7,6 +7,7 @@ type ModalType =
   | 'manage-group'
   | 'add-call'
   | 'prompt-builder'
+  | 'start-workflow'
   | 'edit-virtual-folder'
   | 'select-node'
   | null;
diff --git a/src/frontend/src/index.css b/src/frontend/src/index.css
index 5b563279..df1b6dc3 100755
--- a/src/frontend/src/index.css
+++ b/src/frontend/src/index.css
@@ -168,3 +168,81 @@
   background-color: rgb(255 255 255 / 0.06);
   box-shadow: inset 0 0 0 1px rgb(255 255 255 / 0.12);
 }
+
+/*
+ * Agent chat markdown: Tailwind preflight removes list bullets and heading sizes.
+ * Scope fixes under .agent-markdown only.
+ */
+@layer components {
+  .agent-markdown {
+    font-size: 0.8125rem;
+    line-height: 1.55;
+    color: inherit;
+  }
+
+  .agent-markdown :where(h1) {
+    font-size: 1.05rem;
+    font-weight: 600;
+    margin: 0.85rem 0 0.4rem;
+    line-height: 1.35;
+  }
+
+  .agent-markdown :where(h2) {
+    font-size: 0.95rem;
+    font-weight: 600;
+    margin: 0.75rem 0 0.35rem;
+    line-height: 1.35;
+  }
+
+  .agent-markdown :where(h3) {
+    font-size: 0.875rem;
+    font-weight: 600;
+    margin: 0.65rem 0 0.3rem;
+    line-height: 1.35;
+  }
+
+  .agent-markdown :where(ul) {
+    list-style-type: disc;
+    list-style-position: outside;
+    margin: 0.4rem 0;
+    padding-left: 1.35rem;
+  }
+
+  .agent-markdown :where(ol) {
+    list-style-type: decimal;
+    list-style-position: outside;
+    margin: 0.4rem 0;
+    padding-left: 1.35rem;
+  }
+
+  .agent-markdown :where(li) {
+    margin: 0.2rem 0;
+    display: list-item;
+  }
+
+  .agent-markdown :where(ul ul, ol ol, ul ol, ol ul) {
+    margin: 0.2rem 0;
+  }
+
+  .agent-markdown :where(blockquote) {
+    border-left-width: 3px;
+    padding-left: 0.75rem;
+    margin: 0.5rem 0;
+  }
+
+  .agent-markdown :where(hr) {
+    margin: 0.85rem 0;
+  }
+
+  .agent-markdown :where(p) {
+    margin: 0.35rem 0;
+  }
+
+  .agent-markdown :where(p:first-child) {
+    margin-top: 0;
+  }
+
+  .agent-markdown :where(p:last-child) {
+    margin-bottom: 0;
+  }
+}
diff --git a/src/frontend/src/lib/agentFetch.ts b/src/frontend/src/lib/agentFetch.ts
new file mode 100644
index 00000000..67245433
--- /dev/null
+++ b/src/frontend/src/lib/agentFetch.ts
@@ -0,0 +1,72 @@
+import { useVersioningStore } from "@/features/Dashboard/features/Versioning/store/useVersioningStore";
+
+const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || "/api/v1";
+
+export class AgentHttpError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly body: unknown,
+  ) {
+    super(message);
+    this.name = "AgentHttpError";
+  }
+}
+
+export type AgentFetchInit = Omit<RequestInit, "body"> & { body?: unknown };
+
+function normalizeCommitId(commitId?: string | null): string | undefined {
+  if (!commitId) return undefined;
+  return commitId.startsWith("branch:") ? commitId.slice("branch:".length) : commitId;
+}
+
+/** Append project + versioning query params (same contract as `@/lib/api`). */
+function appendProjectAndVersioningQuery(path: string, projectId: string): string {
+  const state = useVersioningStore.getState();
+  const ref = normalizeCommitId(state.checkedOutCommitId ?? undefined);
+  const compareTo = normalizeCommitId(state.compareToCommitId ?? undefined);
+
+  const params = new URLSearchParams();
+  params.set("project_id", projectId);
+  if (ref) params.set("ref", ref);
+  if (compareTo) params.set("compare_to", compareTo);
+
+  const suffix = params.toString();
+  const sep = path.includes("?") ? "&" : "?";
+  return `${path}${sep}${suffix}`;
+}
+
+export async function agentFetch<T>(
+  path: string,
+  init: AgentFetchInit = {},
+  projectId: string,
+): Promise<T> {
+  if (!projectId) {
+    throw new AgentHttpError("Missing projectId for agent request", 0, {});
+  }
+
+  const finalPath = appendProjectAndVersioningQuery(path, projectId);
+  const branch = useVersioningStore.getState().branch;
+
+  const { body, headers, ...rest } = init;
+  const res = await fetch(`${API_BASE_URL}${finalPath}`, {
+    ...rest,
+    headers: {
+      "Content-Type": "application/json",
+      ...(branch ? { "X-Vnoc-Branch": branch } : {}),
+      ...headers,
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const errBody = await res.json().catch(() => ({}));
+    throw new AgentHttpError(res.statusText, res.status, errBody);
+  }
+
+  if (res.status === 204) {
+    return undefined as T;
+  }
+
+  return res.json() as Promise<T>;
+}
diff --git a/src/frontend/src/lib/agentRoutes.ts b/src/frontend/src/lib/agentRoutes.ts
new file mode 100644
index 00000000..da0a5fd0
--- /dev/null
+++ b/src/frontend/src/lib/agentRoutes.ts
@@ -0,0 +1,4 @@
+/** Agent HTTP paths (mounted under `VITE_API_BASE_URL`, default `/api/v1`). */
+export const AGENT_ROUTES = {
+  WORKFLOWS_RUN: "/agent/workflows/run",
+} as const;
diff --git a/src/frontend/src/lib/agentSocket.ts b/src/frontend/src/lib/agentSocket.ts
new file mode 100644
index 00000000..af8829d4
--- /dev/null
+++ b/src/frontend/src/lib/agentSocket.ts
@@ -0,0 +1,17 @@
+/**
+ * Socket.io event names for agent conversations (chat + background workflows).
+ * Subscribe with `useConversationRoom(conversationId)` from `@/services/socket`.
+ * Payload types live in `@/types/agent/stream`.
+ */
+export const AGENT_SOCKET_SERVER_EVENTS = {
+  conversationPatch: "conversation:patch",
+  streamStart: "stream:start",
+  streamChunk: "stream:chunk",
+  streamEnd: "stream:end",
+  streamError: "stream:error",
+} as const;
+
+export const AGENT_SOCKET_CLIENT_EVENTS = {
+  joinConversation: "join_conversation",
+  leaveConversation: "leave_conversation",
+} as const;
diff --git a/src/frontend/src/lib/apiRoutes.ts b/src/frontend/src/lib/apiRoutes.ts
index bc366ef8..8f30e5ff 100644
--- a/src/frontend/src/lib/apiRoutes.ts
+++ b/src/frontend/src/lib/apiRoutes.ts
@@ -9,6 +9,7 @@ const API_ROUTES = {
     CALLS: '/calls/',
     VERSIONING: '/versioning',
     TESTS: '/tests',
+    PLAYGROUNDS: '/playgrounds',
 };
 
 export default API_ROUTES; 
\ No newline at end of file
diff --git a/src/frontend/src/lib/jsonPatch/applyConversationPatches.ts b/src/frontend/src/lib/jsonPatch/applyConversationPatches.ts
new file mode 100644
index 00000000..9c36b4a4
--- /dev/null
+++ b/src/frontend/src/lib/jsonPatch/applyConversationPatches.ts
@@ -0,0 +1,31 @@
+import { applyPatch, type Operation } from "fast-json-patch";
+
+export class ConversationPatchError extends Error {
+  constructor(
+    message: string,
+    readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "ConversationPatchError";
+  }
+}
+
+/**
+ * Immutable RFC 6902 apply for conversation documents.
+ * On failure, callers should refetch `GET /conversations/meta` + messages.
+ */
+export function applyConversationPatches<T extends object>(
+  document: T,
+  patches: Operation[],
+): T {
+  if (patches.length === 0) {
+    return document;
+  }
+  try {
+    const clone = structuredClone(document);
+    const { newDocument } = applyPatch(clone, patches, false, true);
+    return newDocument as T;
+  } catch (e) {
+    throw new ConversationPatchError("Failed to apply conversation patch", e);
+  }
+}
diff --git a/src/frontend/src/lib/queryKeys.ts b/src/frontend/src/lib/queryKeys.ts
index e9dfd516..1703eed9 100644
--- a/src/frontend/src/lib/queryKeys.ts
+++ b/src/frontend/src/lib/queryKeys.ts
@@ -25,6 +25,13 @@ const queryKeys = {
     cases: (projectId: string, nodeId: string) =>
       [...queryKeys.tests.all, 'cases', projectId, nodeId] as const,
   },
+  playgrounds: {
+    all: ['playgrounds'] as const,
+    detail: (projectId: string, playgroundId: string) =>
+      [...queryKeys.playgrounds.all, 'detail', projectId, playgroundId] as const,
+    byOwner: (projectId: string, nodeId: string) =>
+      [...queryKeys.playgrounds.all, 'owners', projectId, nodeId] as const,
+  },
   nodes: {
     all: ['nodes'] as const,
     detail: (nodeId: string) => [...queryKeys.nodes.all, nodeId] as const,
@@ -38,6 +45,60 @@ const queryKeys = {
     list: (nodeKey: string, projectKey?: string) => [...queryKeys.documents.all, 'list', nodeKey, projectKey ?? ''] as const,
     detail: (docId: string) => [...queryKeys.documents.all, 'detail', docId] as const,
   },
+  agent: {
+    all: ["agent"] as const,
+    conversations: {
+      all: () => [...queryKeys.agent.all, "conversations"] as const,
+      list: (
+        projectId: string,
+        limit: number,
+        branch?: string | null,
+        ref?: string | null,
+        compareTo?: string | null,
+      ) =>
+        [
+          ...queryKeys.agent.conversations.all(),
+          "list",
+          projectId,
+          limit,
+          branch ?? "main",
+          ref ?? "",
+          compareTo ?? "",
+        ] as const,
+      detail: (
+        projectId: string,
+        id: string,
+        branch?: string | null,
+        ref?: string | null,
+        compareTo?: string | null,
+      ) =>
+        [
+          ...queryKeys.agent.conversations.all(),
+          "detail",
+          projectId,
+          id,
+          branch ?? "main",
+          ref ?? "",
+          compareTo ?? "",
+        ] as const,
+    },
+    taskSubtasks: (
+      projectId: string,
+      taskId: string,
+      branch?: string | null,
+      ref?: string | null,
+      compareTo?: string | null,
+    ) =>
+      [
+        ...queryKeys.agent.all,
+        "task-subtasks",
+        projectId,
+        taskId,
+        branch ?? "main",
+        ref ?? "",
+        compareTo ?? "",
+      ] as const,
+  },
   versioning: {
     all: ['versioning'] as const,
     branches: (projectId: string, branch?: string | null, ref?: string | null) =>
diff --git a/src/frontend/src/lib/react/useEffectEvent.ts b/src/frontend/src/lib/react/useEffectEvent.ts
new file mode 100644
index 00000000..fa20d793
--- /dev/null
+++ b/src/frontend/src/lib/react/useEffectEvent.ts
@@ -0,0 +1,22 @@
+import * as React from "react";
+
+type AnyFn = (...args: never[]) => unknown;
+
+/**
+ * React 19.2+ `useEffectEvent`: stable callback that always sees latest props/state.
+ * Falls back to ref + `useCallback` on older React (same contract).
+ */
+export function useEffectEvent<T extends AnyFn>(fn: T): T {
+  const R = React as unknown as {
+    useEffectEvent?: <F extends AnyFn>(callback: F) => F;
+  };
+  if (typeof R.useEffectEvent === "function") {
+    return R.useEffectEvent(fn);
+  }
+  const ref = React.useRef(fn);
+  React.useInsertionEffect(() => {
+    ref.current = fn;
+  });
+  return React.useCallback(((...args: never[]) =>
+    ref.current(...args)) as T, []);
+}
diff --git a/src/frontend/src/pages/Dashboard.tsx b/src/frontend/src/pages/Dashboard.tsx
index 3fc97a43..14687810 100644
--- a/src/frontend/src/pages/Dashboard.tsx
+++ b/src/frontend/src/pages/Dashboard.tsx
@@ -19,6 +19,8 @@ import { SidebarDialogs } from "@/features/Dashboard/components/SidebarDialogs";
 import VersioningPanel from "@/features/Dashboard/features/Versioning/components/VersioningPanel";
 import { useVersioningStore } from "@/features/Dashboard/features/Versioning/store/useVersioningStore";
 import AgentOverlay from "@/features/Dashboard/features/Agent";
+import { useAgentChatSession } from "@/features/Dashboard/features/Agent/live";
+import { useAgentUiStore } from "@/features/Dashboard/features/Agent/store/useAgentUiStore";
 import VersioningStatusBanner from "@/features/Dashboard/features/Versioning/components/VersioningStatusBanner";
 
 /**
@@ -35,9 +37,14 @@ const Dashboard = () => {
   const tabStack = useTabStore(useShallow(selectTabStack));
   const isVersioningOpen = useVersioningStore((s) => s.isOpen);
 
+  const backendConversationId = useAgentUiStore((s) => s.backendConversationId);
+  const agentProjectId = useProjectStore((s) => s.projectData?.id ?? "");
+
   // Socket and Data Sync hooks
   useSocketSync();
   useProjectRoom(projectId);
+  /** One subscription only — every tab mounts AgentSidebar; duplicate listeners break JSON patches. */
+  useAgentChatSession(backendConversationId, agentProjectId);
 
   // Transformation hooks
   useGroupFlattening();
diff --git a/src/frontend/src/services/agent/api.ts b/src/frontend/src/services/agent/api.ts
new file mode 100644
index 00000000..8bbde253
--- /dev/null
+++ b/src/frontend/src/services/agent/api.ts
@@ -0,0 +1,115 @@
+import { agentFetch } from "@/lib/agentFetch";
+import type {
+  ConversationMetaWire,
+  CreateConversationPayload,
+  PaginatedResponse,
+  SendMessagePayload,
+  SendMessageResponse,
+  WireConversation,
+  WireMessage,
+  WireSubTask,
+} from "@/types/agent";
+
+const Q = (params: Record<string, string | number | undefined>) => {
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined) continue;
+    sp.set(k, String(v));
+  }
+  const q = sp.toString();
+  return q ? `?${q}` : "";
+};
+
+export const agentApi = {
+  createConversation: (projectId: string, body: CreateConversationPayload) =>
+    agentFetch<ConversationMetaWire>(
+      "/conversations",
+      {
+        method: "POST",
+        body,
+      },
+      projectId,
+    ),
+
+  listConversations: (projectId: string, limit = 50, cursor?: string) =>
+    agentFetch<PaginatedResponse<ConversationMetaWire>>(
+      `/conversations${Q({ limit, cursor })}`,
+      {},
+      projectId,
+    ),
+
+  getConversationMeta: (projectId: string, conversationId: string) =>
+    agentFetch<ConversationMetaWire>(
+      `/conversations/meta${Q({ conversation_id: conversationId })}`,
+      {},
+      projectId,
+    ),
+
+  listMessages: (
+    projectId: string,
+    conversationId: string,
+    cursor = 0,
+    limit = 50,
+  ) =>
+    agentFetch<PaginatedResponse<WireMessage>>(
+      `/conversations/messages${Q({
+        conversation_id: conversationId,
+        cursor,
+        limit,
+      })}`,
+      {},
+      projectId,
+    ),
+
+  /** Builds a full wire conversation for the client store (meta + first page of messages). */
+  hydrateConversation: async (
+    projectId: string,
+    conversationId: string,
+    messageLimit = 200,
+  ): Promise<WireConversation> => {
+    const meta = await agentApi.getConversationMeta(projectId, conversationId);
+    const page = await agentApi.listMessages(
+      projectId,
+      conversationId,
+      0,
+      messageLimit,
+    );
+    return {
+      id: meta.id,
+      title: meta.title,
+      description: meta.description,
+      message_count: meta.message_count,
+      has_active_task: meta.has_active_task,
+      created_at: meta.created_at,
+      updated_at: meta.updated_at,
+      metadata: meta.metadata ?? {},
+      messages: page.items,
+    };
+  },
+
+  sendMessage: (projectId: string, payload: SendMessagePayload) =>
+    agentFetch<SendMessageResponse>(
+      "/conversations/messages",
+      {
+        method: "POST",
+        body: payload,
+      },
+      projectId,
+    ),
+
+  listTaskSubtasks: (
+    projectId: string,
+    taskId: string,
+    cursor = 0,
+    limit = 200,
+  ) =>
+    agentFetch<PaginatedResponse<WireSubTask>>(
+      `/tasks/subtasks${Q({
+        task_id: taskId,
+        cursor,
+        limit,
+      })}`,
+      {},
+      projectId,
+    ),
+};
diff --git a/src/frontend/src/services/agent/index.ts b/src/frontend/src/services/agent/index.ts
new file mode 100644
index 00000000..6448600b
--- /dev/null
+++ b/src/frontend/src/services/agent/index.ts
@@ -0,0 +1,8 @@
+export { agentApi } from "./api";
+export { agentWorkflowsApi } from "./workflowsApi";
+export * from "./socket";
+export {
+  agentConversationHydrationQueryOptions,
+  agentConversationSummariesQueryOptions,
+  agentTaskSubtasksQueryOptions,
+} from "./queries";
diff --git a/src/frontend/src/services/agent/queries.ts b/src/frontend/src/services/agent/queries.ts
new file mode 100644
index 00000000..0e1d219b
--- /dev/null
+++ b/src/frontend/src/services/agent/queries.ts
@@ -0,0 +1,69 @@
+import { queryOptions } from "@tanstack/react-query";
+import { isAgentPreviewConversationId } from "@/features/Dashboard/features/Agent/constants/agentPreviewConversation";
+import queryKeys from "@/lib/queryKeys";
+import { agentApi } from "./api";
+
+export const agentConversationSummariesQueryOptions = (
+  projectId: string,
+  branch: string | null | undefined,
+  ref: string | null | undefined,
+  compareTo: string | null | undefined,
+  limit = 50,
+) =>
+  queryOptions({
+    queryKey: queryKeys.agent.conversations.list(
+      projectId,
+      limit,
+      branch,
+      ref,
+      compareTo,
+    ),
+    queryFn: () => agentApi.listConversations(projectId, limit),
+    enabled: Boolean(projectId),
+    staleTime: 30_000,
+  });
+
+export const agentConversationHydrationQueryOptions = (
+  projectId: string,
+  conversationId: string | null,
+  branch: string | null | undefined,
+  ref: string | null | undefined,
+  compareTo: string | null | undefined,
+  messageLimit = 200,
+) =>
+  queryOptions({
+    queryKey: queryKeys.agent.conversations.detail(
+      projectId,
+      conversationId ?? "",
+      branch,
+      ref,
+      compareTo,
+    ),
+    queryFn: () =>
+      agentApi.hydrateConversation(projectId, conversationId!, messageLimit),
+    enabled: Boolean(
+      projectId && conversationId && !isAgentPreviewConversationId(conversationId),
+    ),
+    staleTime: 10_000,
+  });
+
+export const agentTaskSubtasksQueryOptions = (
+  projectId: string,
+  taskId: string,
+  branch: string | null | undefined,
+  ref: string | null | undefined,
+  compareTo: string | null | undefined,
+  enabled: boolean,
+) =>
+  queryOptions({
+    queryKey: queryKeys.agent.taskSubtasks(
+      projectId,
+      taskId,
+      branch,
+      ref,
+      compareTo,
+    ),
+    queryFn: () => agentApi.listTaskSubtasks(projectId, taskId),
+    enabled: Boolean(projectId && taskId && enabled),
+    staleTime: 5_000,
+  });
diff --git a/src/frontend/src/services/agent/socket.ts b/src/frontend/src/services/agent/socket.ts
new file mode 100644
index 00000000..cd51ddb2
--- /dev/null
+++ b/src/frontend/src/services/agent/socket.ts
@@ -0,0 +1,10 @@
+/**
+ * Workflow runs attach tasks to a conversation; live updates use the same
+ * socket contract as chat (`conversation:patch`, `stream:*`).
+ * `useAgentChatSession` already calls `useConversationRoom` for the active conversation.
+ */
+export { useConversationRoom } from "@/services/socket";
+export {
+  AGENT_SOCKET_CLIENT_EVENTS,
+  AGENT_SOCKET_SERVER_EVENTS,
+} from "@/lib/agentSocket";
diff --git a/src/frontend/src/services/agent/workflowsApi.ts b/src/frontend/src/services/agent/workflowsApi.ts
new file mode 100644
index 00000000..de713a2b
--- /dev/null
+++ b/src/frontend/src/services/agent/workflowsApi.ts
@@ -0,0 +1,12 @@
+import { agentFetch } from "@/lib/agentFetch";
+import { AGENT_ROUTES } from "@/lib/agentRoutes";
+import type { RunWorkflowRequest, RunWorkflowResponse } from "@/types/agent/workflows";
+
+export const agentWorkflowsApi = {
+  run: (projectId: string, body: RunWorkflowRequest) =>
+    agentFetch<RunWorkflowResponse>(
+      AGENT_ROUTES.WORKFLOWS_RUN,
+      { method: "POST", body },
+      projectId,
+    ),
+};
diff --git a/src/frontend/src/services/documents/api.ts b/src/frontend/src/services/documents/api.ts
index 9b03f710..eeaca505 100644
--- a/src/frontend/src/services/documents/api.ts
+++ b/src/frontend/src/services/documents/api.ts
@@ -6,6 +6,8 @@ export interface DocumentData {
   name: string;
   description: string;
   data: string;
+  /** Markdown export for AI / text consumers; may mirror editor JSON until optimized. */
+  markdown: string;
   created_at: string;
   updated_at: string;
   status?: "added" | "removed" | "modified" | "unchanged" | "none";
@@ -24,6 +26,7 @@ export interface UpdateDocumentRequest {
   name?: string;
   description?: string;
   data?: string;
+  markdown?: string;
 }
 
 function buildQueryString(params: Record<string, string>): string {
@@ -41,6 +44,7 @@ interface BackendDocumentRaw {
   name: string;
   description: string;
   data: string;
+  markdown?: string;
   created_at: string;
   updated_at: string;
   status?: "added" | "removed" | "modified" | "unchanged" | "none";
@@ -59,6 +63,7 @@ const mapBackendDocument = (d: BackendDocumentRaw): DocumentData => {
     name: d.name,
     description: d.description,
     data: d.data,
+    markdown: d.markdown ?? "",
     created_at: d.created_at,
     updated_at: d.updated_at,
     status: d.status,
@@ -121,6 +126,7 @@ export const documentsApi = {
       name: payload.name,
       description: payload.description,
       data: payload.data,
+      markdown: payload.markdown,
     };
     const qs = buildQueryString({ document_id: payload.id, project_id: projectId });
     const response = await api(`${API_ROUTES.DOCUMENTS}${qs}`, {
diff --git a/src/frontend/src/services/documents/mutations.ts b/src/frontend/src/services/documents/mutations.ts
index eeded4e7..0610af37 100644
--- a/src/frontend/src/services/documents/mutations.ts
+++ b/src/frontend/src/services/documents/mutations.ts
@@ -57,6 +57,9 @@ export const useUpdateDocument = (nodeId: string, projectId: string) => {
               // Update fields from server response (source of truth)
               // Only update fields that were provided in the mutation
               ...(variables.data !== undefined && { data: updatedDocument.data }),
+              ...(variables.markdown !== undefined && {
+                markdown: updatedDocument.markdown,
+              }),
               ...(variables.name !== undefined && { name: updatedDocument.name }),
               ...(variables.description !== undefined && {
                 description: updatedDocument.description,
diff --git a/src/frontend/src/services/playground/api.ts b/src/frontend/src/services/playground/api.ts
new file mode 100644
index 00000000..f482a775
--- /dev/null
+++ b/src/frontend/src/services/playground/api.ts
@@ -0,0 +1,64 @@
+import { api } from "@/lib/api";
+import API_ROUTES from "@/lib/apiRoutes";
+import type {
+  CreatePlaygroundPayload,
+  Playground,
+  RunPlaygroundCodePayload,
+  RunPlaygroundCodeResponse,
+  UpdatePlaygroundPayload,
+} from "@/types/playground";
+
+function withProjectId(path: string, projectId: string): string {
+  const params = new URLSearchParams({ project_id: projectId });
+  return `${path}?${params.toString()}`;
+}
+
+function withProjectAndNodeId(
+  path: string,
+  projectId: string,
+  nodeId: string
+): string {
+  const params = new URLSearchParams({ project_id: projectId, node_id: nodeId });
+  return `${path}?${params.toString()}`;
+}
+
+export const playgroundApi = {
+  create: (
+    payload: CreatePlaygroundPayload,
+    projectId: string
+  ): Promise<Playground> =>
+    api(withProjectId(`${API_ROUTES.PLAYGROUNDS}/`, projectId), {
+      method: "POST",
+      body: payload,
+    }),
+
+  getById: (playgroundId: string, projectId: string): Promise<Playground> =>
+    api(withProjectId(`${API_ROUTES.PLAYGROUNDS}/${playgroundId}`, projectId)),
+
+  update: (
+    playgroundId: string,
+    payload: UpdatePlaygroundPayload,
+    projectId: string
+  ): Promise<Playground> =>
+    api(withProjectId(`${API_ROUTES.PLAYGROUNDS}/${playgroundId}`, projectId), {
+      method: "PUT",
+      body: payload,
+    }),
+
+  delete: (playgroundId: string, projectId: string): Promise<void> =>
+    api(withProjectId(`${API_ROUTES.PLAYGROUNDS}/${playgroundId}`, projectId), {
+      method: "DELETE",
+    }),
+
+  getByOwnerNodeId: (nodeId: string, projectId: string): Promise<Playground[]> =>
+    api(withProjectAndNodeId(`${API_ROUTES.PLAYGROUNDS}/owners`, projectId, nodeId)),
+
+  runCode: (
+    payload: RunPlaygroundCodePayload,
+    projectId: string
+  ): Promise<RunPlaygroundCodeResponse> =>
+    api(withProjectId(`${API_ROUTES.PLAYGROUNDS}/run-code`, projectId), {
+      method: "POST",
+      body: payload,
+    }),
+};
diff --git a/src/frontend/src/services/playground/index.ts b/src/frontend/src/services/playground/index.ts
new file mode 100644
index 00000000..663f8472
--- /dev/null
+++ b/src/frontend/src/services/playground/index.ts
@@ -0,0 +1,16 @@
+export { playgroundApi } from "./api";
+export { usePlayground, usePlaygroundsByOwner } from "./queries";
+export {
+  useCreatePlayground,
+  useUpdatePlayground,
+  useDeletePlayground,
+  useRunPlaygroundCode,
+} from "./mutations";
+export type {
+  Playground,
+  PlaygroundOwnerFields,
+  CreatePlaygroundPayload,
+  UpdatePlaygroundPayload,
+  RunPlaygroundCodePayload,
+  RunPlaygroundCodeResponse,
+} from "@/types/playground";
diff --git a/src/frontend/src/services/playground/mutations.ts b/src/frontend/src/services/playground/mutations.ts
new file mode 100644
index 00000000..4cb109f5
--- /dev/null
+++ b/src/frontend/src/services/playground/mutations.ts
@@ -0,0 +1,57 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import queryKeys from "@/lib/queryKeys";
+import { playgroundApi } from "./api";
+import type {
+  CreatePlaygroundPayload,
+  RunPlaygroundCodePayload,
+  UpdatePlaygroundPayload,
+} from "@/types/playground";
+
+function invalidatePlaygroundQueries(
+  queryClient: ReturnType<typeof useQueryClient>
+) {
+  queryClient.invalidateQueries({ queryKey: queryKeys.playgrounds.all });
+}
+
+export const useCreatePlayground = (projectId: string) => {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (payload: CreatePlaygroundPayload) =>
+      playgroundApi.create(payload, projectId),
+    onSuccess: () => {
+      invalidatePlaygroundQueries(queryClient);
+    },
+  });
+};
+
+export const useUpdatePlayground = (projectId: string) => {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      playgroundId,
+      payload,
+    }: {
+      playgroundId: string;
+      payload: UpdatePlaygroundPayload;
+    }) => playgroundApi.update(playgroundId, payload, projectId),
+    onSuccess: () => {
+      invalidatePlaygroundQueries(queryClient);
+    },
+  });
+};
+
+export const useDeletePlayground = (projectId: string) => {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (playgroundId: string) => playgroundApi.delete(playgroundId, projectId),
+    onSuccess: () => {
+      invalidatePlaygroundQueries(queryClient);
+    },
+  });
+};
+
+export const useRunPlaygroundCode = (projectId: string) =>
+  useMutation({
+    mutationFn: (payload: RunPlaygroundCodePayload) =>
+      playgroundApi.runCode(payload, projectId),
+  });
diff --git a/src/frontend/src/services/playground/queries.ts b/src/frontend/src/services/playground/queries.ts
new file mode 100644
index 00000000..a04bd5d1
--- /dev/null
+++ b/src/frontend/src/services/playground/queries.ts
@@ -0,0 +1,24 @@
+import { useQuery } from "@tanstack/react-query";
+import queryKeys from "@/lib/queryKeys";
+import { playgroundApi } from "./api";
+import type { Playground } from "@/types/playground";
+
+export const usePlayground = (playgroundId: string | null, projectId: string) =>
+  useQuery<Playground>({
+    queryKey: queryKeys.playgrounds.detail(projectId, playgroundId ?? ""),
+    queryFn: () => playgroundApi.getById(playgroundId!, projectId),
+    enabled: !!playgroundId && !!projectId,
+    retry: false,
+  });
+
+export const usePlaygroundsByOwner = (
+  nodeId: string | null,
+  projectId: string
+) =>
+  useQuery<Playground[]>({
+    queryKey: queryKeys.playgrounds.byOwner(projectId, nodeId ?? ""),
+    queryFn: () =>
+      nodeId ? playgroundApi.getByOwnerNodeId(nodeId, projectId) : Promise.resolve([]),
+    enabled: !!nodeId && !!projectId,
+    retry: false,
+  });
diff --git a/src/frontend/src/services/socket/SocketProvider.tsx b/src/frontend/src/services/socket/SocketProvider.tsx
index 5a188568..77e96192 100644
--- a/src/frontend/src/services/socket/SocketProvider.tsx
+++ b/src/frontend/src/services/socket/SocketProvider.tsx
@@ -2,7 +2,6 @@ import {
   createContext,
   useContext,
   useEffect,
-  useRef,
   useState,
   type ReactNode,
 } from "react";
@@ -27,37 +26,39 @@ interface SocketProviderProps {
 }
 
 export function SocketProvider({ children }: SocketProviderProps) {
+  const [socket, setSocket] = useState<Socket<
+    ServerToClientEvents,
+    ClientToServerEvents
+  > | null>(null);
   const [isConnected, setIsConnected] = useState(false);
-  const socketRef = useRef<Socket | null>(null);
 
   useEffect(() => {
-    const socket = createSocket();
-    socketRef.current = socket;
+    const s = createSocket();
+    setSocket(s);
 
     const onConnect = () => {
-      console.log("🔌 Socket connected:", socket.id);
       setIsConnected(true);
     };
 
-    const onDisconnect = (reason: string) => {
-      console.log("🔌 Socket disconnected:", reason);
+    const onDisconnect = () => {
       setIsConnected(false);
     };
 
-    socket.on("connect", onConnect);
-    socket.on("disconnect", onDisconnect);
-
-    setIsConnected(socket.connected);
+    s.on("connect", onConnect);
+    s.on("disconnect", onDisconnect);
+    setIsConnected(s.connected);
 
     return () => {
-      socket.off("connect", onConnect);
-      socket.off("disconnect", onDisconnect);
+      s.off("connect", onConnect);
+      s.off("disconnect", onDisconnect);
       disconnectSocket();
+      setSocket(null);
+      setIsConnected(false);
     };
   }, []);
 
   return (
-    <SocketContext.Provider value={{ socket: socketRef.current, isConnected }}>
+    <SocketContext.Provider value={{ socket, isConnected }}>
       {children}
     </SocketContext.Provider>
   );
diff --git a/src/frontend/src/services/socket/hooks.ts b/src/frontend/src/services/socket/hooks.ts
index ab68c474..f4c3f97d 100644
--- a/src/frontend/src/services/socket/hooks.ts
+++ b/src/frontend/src/services/socket/hooks.ts
@@ -1,29 +1,66 @@
-import { useEffect } from 'react';
-import { useSocketContext } from './SocketProvider';
+import { useEffect } from "react";
+import { isAgentPreviewConversationId } from "@/features/Dashboard/features/Agent/constants/agentPreviewConversation";
+import { useSocketContext } from "./SocketProvider";
 
 export const useSocket = () => {
   const { socket, isConnected } = useSocketContext();
   return { socket, isConnected };
 };
 
-
 /**
- * Join a project-specific room to receive updates
+ * Join a project-specific room to receive updates.
+ * Re-joins on every socket `connect` (reconnect); do not rely only on React `isConnected`
+ * to avoid missing the first join when state lags the handshake.
  */
 export const useProjectRoom = (projectId: string | undefined) => {
-  const { socket, isConnected } = useSocketContext();
+  const { socket } = useSocketContext();
+  useEffect(() => {
+    if (!socket || !projectId) return;
+
+    const join = () => {
+      if (socket.connected) {
+        socket.emit("join_project", projectId);
+      }
+    };
+
+    join();
+    socket.on("connect", join);
+
+    return () => {
+      socket.off("connect", join);
+      if (socket.connected) {
+        socket.emit("leave_project", projectId);
+      }
+    };
+  }, [socket, projectId]);
+};
+
+/**
+ * Join `conv:{conversationId}` for agent JSON patches and stream events.
+ */
+export const useConversationRoom = (
+  conversationId: string | undefined | null,
+) => {
+  const { socket } = useSocketContext();
   useEffect(() => {
-    console.log("Socket connected:", socket);
-    console.log("Is connected:", isConnected);
-    console.log("Project ID:", projectId);
-    if (!socket || !isConnected || !projectId) return;
+    if (!socket || !conversationId || isAgentPreviewConversationId(conversationId)) {
+      return;
+    }
+
+    const join = () => {
+      if (socket.connected) {
+        socket.emit("join_conversation", conversationId);
+      }
+    };
 
-    socket.emit("join_project", projectId);
-    console.log(`📦 Joined project room: ${projectId}`);
+    join();
+    socket.on("connect", join);
 
     return () => {
-      socket.emit("leave_project", projectId);
-      console.log(`📦 Left project room: ${projectId}`);
+      socket.off("connect", join);
+      if (socket.connected) {
+        socket.emit("leave_conversation", conversationId);
+      }
     };
-  }, [socket, isConnected, projectId]);
-}
+  }, [socket, conversationId]);
+};
diff --git a/src/frontend/src/services/socket/index.ts b/src/frontend/src/services/socket/index.ts
index c36970dc..8e497560 100644
--- a/src/frontend/src/services/socket/index.ts
+++ b/src/frontend/src/services/socket/index.ts
@@ -1,6 +1,6 @@
 export { SocketProvider, useSocketContext } from './SocketProvider';
 export { ProgressProvider, useProgressContext } from './ProgressProvider';
-export { useSocket, useProjectRoom } from './hooks';
+export { useSocket, useProjectRoom, useConversationRoom } from "./hooks";
 export { useSocketSync } from './useSocketSync';
 export { useProgress } from './useProgress';
 export { getSocket, disconnectSocket } from './socket';
diff --git a/src/frontend/src/services/socket/socket.ts b/src/frontend/src/services/socket/socket.ts
index 3c7d6c6f..759205af 100644
--- a/src/frontend/src/services/socket/socket.ts
+++ b/src/frontend/src/services/socket/socket.ts
@@ -1,13 +1,57 @@
-import io, { Socket } from 'socket.io-client';
-import type { ServerToClientEvents, ClientToServerEvents } from './types';
+import io, { Socket } from "socket.io-client";
+import type { ServerToClientEvents, ClientToServerEvents } from "./types";
 
 let socket: Socket<ServerToClientEvents, ClientToServerEvents> | null = null;
 
-const getConfig = () => {
-  const apiBase = import.meta.env.VITE_SOCKET_URL
+/**
+ * Browsers cannot connect to 0.0.0.0 — normalize to localhost.
+ * Also align socket origin with API origin when VITE_SOCKET_URL is unset.
+ */
+function normalizeBrowserOrigin(raw: string): string {
+  const trimmed = raw.replace(/\/$/, "");
+  try {
+    const u = new URL(trimmed);
+    if (u.hostname === "0.0.0.0") {
+      u.hostname = "localhost";
+    }
+    return u.origin;
+  } catch {
+    return trimmed;
+  }
+}
 
-  return { url: apiBase, path: '/ws/socket.io/' };
-};
+function socketOrigin(): string {
+  const explicit = import.meta.env.VITE_SOCKET_URL as string | undefined;
+  if (explicit?.trim()) {
+    return normalizeBrowserOrigin(explicit.trim());
+  }
+  const api = import.meta.env.VITE_API_BASE_URL as string | undefined;
+  if (api?.startsWith("http")) {
+    try {
+      return normalizeBrowserOrigin(new URL(api).origin);
+    } catch {
+      /* fall through */
+    }
+  }
+  if (typeof window !== "undefined") {
+    return window.location.origin;
+  }
+  return "";
+}
+
+/** Path must match FastAPI `mount("/ws", ...)` + Socket.IO (see backend `SocketIOMount`). */
+function socketPath(): string {
+  const fromEnv = (import.meta.env.VITE_SOCKET_IO_PATH as string | undefined)?.replace(
+    /\/?$/,
+    "",
+  );
+  return fromEnv || "/ws/socket.io";
+}
+
+const getConfig = () => ({
+  url: socketOrigin(),
+  path: socketPath(),
+});
 
 export const createSocket = (): Socket<ServerToClientEvents, ClientToServerEvents> => {
   if (socket?.connected) return socket;
@@ -15,18 +59,20 @@ export const createSocket = (): Socket<ServerToClientEvents, ClientToServerEvent
 
   socket = io<ServerToClientEvents, ClientToServerEvents>(config.url, {
     path: config.path,
-    transports: ['websocket', 'polling'],
+    transports: ["websocket", "polling"],
     reconnection: true,
     reconnectionDelay: 1000,
     reconnectionAttempts: 5,
+    autoConnect: true,
   });
 
   return socket;
 };
 
-export const getSocket = (): Socket<ServerToClientEvents, ClientToServerEvents> | null => socket;
+export const getSocket = (): Socket<ServerToClientEvents, ClientToServerEvents> | null =>
+  socket;
 
 export const disconnectSocket = (): void => {
   socket?.disconnect();
   socket = null;
-}
+};
diff --git a/src/frontend/src/services/socket/types.ts b/src/frontend/src/services/socket/types.ts
index 15c0a457..0c4f7582 100644
--- a/src/frontend/src/services/socket/types.ts
+++ b/src/frontend/src/services/socket/types.ts
@@ -1,4 +1,11 @@
 import { ProgressEventPayload } from "@/types/progress";
+import type {
+  ConversationPatchPayload,
+  StreamChunkPayload,
+  StreamEndPayload,
+  StreamErrorPayload,
+  StreamStartPayload,
+} from "@/types/agent/stream";
 
 /**
  * Socket event types for client-server communication
@@ -6,16 +13,23 @@ import { ProgressEventPayload } from "@/types/progress";
 export interface ServerToClientEvents {
   // Progress tracking
   "project:progress": (payload: ProgressEventPayload) => void;
-  
+
   // Code updates
   "code:updated": (data: { element_id: string }) => void;
-  
+
   // Logs updates
   "logs:new": (data: { node_id: string }) => void;
-  
+
   // Project updates
   "project:updated": (data: { project_id: string }) => void;
-  
+
+  // Agent / conversations (see doc/agentv2/07-chat-streaming.md, 08-json-patch-protocol.md)
+  "conversation:patch": (payload: ConversationPatchPayload) => void;
+  "stream:start": (payload: StreamStartPayload) => void;
+  "stream:chunk": (payload: StreamChunkPayload) => void;
+  "stream:end": (payload: StreamEndPayload) => void;
+  "stream:error": (payload: StreamErrorPayload) => void;
+
   // Connection events
   connect: () => void;
   disconnect: (reason: string) => void;
@@ -28,4 +42,11 @@ export interface ClientToServerEvents {
   // Project room management
   join_project: (projectId: string) => void;
   leave_project: (projectId: string) => void;
+
+  /** Subscribe to `conversation:*` and `stream:*` for one conversation */
+  join_conversation: (conversationId: string) => void;
+  leave_conversation: (conversationId: string) => void;
+
+  /** Replay chunks after reconnect (server event name `stream:resume`) */
+  "stream:resume": (data: { stream_id: string; last_seq: number }) => void;
 }
diff --git a/src/frontend/src/services/socket/useSocketSync.ts b/src/frontend/src/services/socket/useSocketSync.ts
index 0e8b62d5..8c9298aa 100644
--- a/src/frontend/src/services/socket/useSocketSync.ts
+++ b/src/frontend/src/services/socket/useSocketSync.ts
@@ -8,11 +8,11 @@ import { useSocketContext } from "./SocketProvider";
  * Call this once at app level (e.g., in Dashboard layout).
  */
 export function useSocketSync() {
-  const { socket, isConnected } = useSocketContext();
+  const { socket } = useSocketContext();
   const queryClient = useQueryClient();
 
   useEffect(() => {
-    if (!socket || !isConnected) return;
+    if (!socket) return;
 
     // When code is updated (from backend processing or another user)
     const onCodeUpdated = (data: { element_id: string }) => {
@@ -48,5 +48,5 @@ export function useSocketSync() {
       socket.off("logs:new", onLogsNew);
       socket.off("project:updated", onProjectUpdated);
     };
-  }, [socket, isConnected, queryClient])
+  }, [socket, queryClient]);
 }
diff --git a/src/frontend/src/types/agent/api.ts b/src/frontend/src/types/agent/api.ts
new file mode 100644
index 00000000..e1d8d71b
--- /dev/null
+++ b/src/frontend/src/types/agent/api.ts
@@ -0,0 +1,29 @@
+import type { ChatCompletionParams } from "./generation";
+
+export interface PaginatedResponse<T> {
+  items: T[];
+  next_cursor?: string | number | null;
+  has_more: boolean;
+}
+
+export interface SendMessagePayload {
+  conversation_id: string;
+  role?: "user";
+  parts: Array<{ type: "text"; text: string }>;
+  generation?: ChatCompletionParams | null;
+  client_ref?: string | null;
+  metadata?: Record<string, unknown> | null;
+}
+
+export interface SendMessageResponse {
+  message_id: string | null;
+  task_id: string;
+  conversation_id: string;
+  stream_id: string;
+  client_ref?: string | null;
+}
+
+export interface CreateConversationPayload {
+  title?: string;
+  description?: string;
+}
diff --git a/src/frontend/src/types/agent/conversation.ts b/src/frontend/src/types/agent/conversation.ts
new file mode 100644
index 00000000..68c20e76
--- /dev/null
+++ b/src/frontend/src/types/agent/conversation.ts
@@ -0,0 +1,54 @@
+/** Wire shapes aligned with backend `conversation_message_to_wire` + metadata. */
+
+export type WireMessageRole = "user" | "assistant" | "system" | string;
+
+export interface WireTextPart {
+  type: "text";
+  text: string;
+}
+
+/** Sub-task row from `GET /tasks/subtasks` or embedded in a task message part. */
+export interface WireSubTask {
+  id?: string;
+  name?: string;
+  title?: string;
+  description?: string;
+  state?: string;
+  sequence?: number;
+}
+
+export type WireMessagePart = WireTextPart | Record<string, unknown>;
+
+export interface WireMessage {
+  id: string;
+  role: WireMessageRole;
+  sequence: number;
+  parts: WireMessagePart[];
+  created_at?: string;
+  token_count?: number | null;
+  model?: string | null;
+}
+
+export interface WireConversation {
+  id: string;
+  title: string;
+  description: string;
+  message_count: number;
+  has_active_task: boolean;
+  created_at: string;
+  updated_at: string;
+  messages: WireMessage[];
+  metadata?: Record<string, unknown>;
+  tasks?: Record<string, unknown>;
+}
+
+export interface ConversationMetaWire {
+  id: string;
+  title: string;
+  description: string;
+  message_count: number;
+  has_active_task: boolean;
+  created_at: string;
+  updated_at: string;
+  metadata?: Record<string, unknown>;
+}
diff --git a/src/frontend/src/types/agent/generation.ts b/src/frontend/src/types/agent/generation.ts
new file mode 100644
index 00000000..0e00950d
--- /dev/null
+++ b/src/frontend/src/types/agent/generation.ts
@@ -0,0 +1,12 @@
+/** Mirrors backend `ChatCompletionParams` / REST `generation` object. */
+
+export interface ChatCompletionParams {
+  provider?: string | null;
+  model?: string | null;
+  temperature?: number | null;
+  max_tokens?: number | null;
+  top_p?: number | null;
+  frequency_penalty?: number | null;
+  presence_penalty?: number | null;
+  stop?: string[] | null;
+}
diff --git a/src/frontend/src/types/agent/index.ts b/src/frontend/src/types/agent/index.ts
new file mode 100644
index 00000000..84a0c922
--- /dev/null
+++ b/src/frontend/src/types/agent/index.ts
@@ -0,0 +1,5 @@
+export type * from "./api";
+export type * from "./conversation";
+export type * from "./generation";
+export type * from "./stream";
+export * from "./workflows";
diff --git a/src/frontend/src/types/agent/stream.ts b/src/frontend/src/types/agent/stream.ts
new file mode 100644
index 00000000..3ee44773
--- /dev/null
+++ b/src/frontend/src/types/agent/stream.ts
@@ -0,0 +1,36 @@
+import type { Operation } from "fast-json-patch";
+
+/** WebSocket payloads (server → client) for chat streaming. */
+
+export interface StreamStartPayload {
+  stream_id: string;
+  conversation_id: string;
+  task_id?: string | null;
+  model?: string;
+  provider?: string;
+  client_ref?: string | null;
+}
+
+export interface StreamChunkPayload {
+  stream_id: string;
+  seq: number;
+  delta: string;
+  /** Present when merged in the client (server may omit). */
+  conversation_id?: string;
+}
+
+export interface StreamEndPayload {
+  stream_id: string;
+  message_id: string;
+  total_seq: number;
+}
+
+export interface StreamErrorPayload {
+  stream_id: string;
+  error: string;
+}
+
+export interface ConversationPatchPayload {
+  conversation_id: string;
+  patches: Operation[];
+}
diff --git a/src/frontend/src/types/agent/workflows.ts b/src/frontend/src/types/agent/workflows.ts
new file mode 100644
index 00000000..b1108e95
--- /dev/null
+++ b/src/frontend/src/types/agent/workflows.ts
@@ -0,0 +1,44 @@
+/** Matches backend `OpenAIProvider.supported_models` defaults. */
+export const WORKFLOW_MODEL_OPTIONS = [
+  "gpt-4o",
+  "gpt-4o-mini",
+  "gpt-4-turbo",
+  "gpt-3.5-turbo",
+] as const;
+
+export type WorkflowModelId = (typeof WORKFLOW_MODEL_OPTIONS)[number];
+
+export type AgentWorkflowName =
+  | "description_generator"
+  | "documentation_generator";
+
+export type DescriptionWorkflowMode = "always" | "skip_if_present";
+
+export type DocumentationWorkflowMode = "upsert" | "insert_only";
+
+export interface WorkflowBatchStepWire {
+  workflow_name: AgentWorkflowName;
+  params: Record<string, unknown>;
+}
+
+/** Dialog payload: each step is started with `POST .../workflows/run` in order, reusing `conversation_id`. */
+export interface StartAgentWorkflowsPayload {
+  steps: WorkflowBatchStepWire[];
+  conversation_title?: string | null;
+  conversation_description?: string | null;
+}
+
+export interface RunWorkflowRequest {
+  workflow_name: AgentWorkflowName;
+  params: Record<string, unknown>;
+  conversation_id?: string | null;
+  message_id?: string | null;
+  conversation_title?: string | null;
+  conversation_description?: string | null;
+}
+
+export interface RunWorkflowResponse {
+  conversation_id: string;
+  task_id: string;
+  status: string;
+}
diff --git a/src/frontend/src/types/playground.ts b/src/frontend/src/types/playground.ts
new file mode 100644
index 00000000..952c505a
--- /dev/null
+++ b/src/frontend/src/types/playground.ts
@@ -0,0 +1,49 @@
+export interface PlaygroundOwnerFields {
+  owner_function?: string | null;
+  owner_class?: string | null;
+  owner_file?: string | null;
+  owner_folder?: string | null;
+}
+
+export interface Playground {
+  id: string;
+  name: string;
+  description: string;
+  relative_path: string;
+  code: string;
+  executable_path?: string | null;
+  filename?: string | null;
+  owner_function?: string | null;
+  owner_class?: string | null;
+  owner_file?: string | null;
+  owner_folder?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+export interface CreatePlaygroundPayload extends PlaygroundOwnerFields {
+  name: string;
+  description?: string;
+  relative_path: string;
+  code: string;
+  executable_path?: string | null;
+  filename?: string | null;
+}
+
+export interface UpdatePlaygroundPayload {
+  name?: string;
+  description?: string;
+  relative_path?: string;
+  code?: string;
+  executable_path?: string | null;
+  filename?: string | null;
+}
+
+export interface RunPlaygroundCodePayload {
+  playground_id: string;
+}
+
+export interface RunPlaygroundCodeResponse {
+  response: string;
+  has_error: boolean;
+}
diff --git a/src/frontend/vite.config.ts b/src/frontend/vite.config.ts
index 2e40f5e1..ec163b7f 100755
--- a/src/frontend/vite.config.ts
+++ b/src/frontend/vite.config.ts
@@ -6,6 +6,14 @@ import path from 'path';
 // https://vite.dev/config/
 export default defineConfig({
   plugins: [react(), tailwindcss()],
+  server: {
+    // Optional: use relative VITE_API_BASE_URL=/api/v1 + VITE_SOCKET_URL unset → same-origin;
+    // then these proxies forward to the API process (default uvicorn :8000).
+    proxy: {
+      "/api": { target: "http://127.0.0.1:8000", changeOrigin: true },
+      "/ws": { target: "http://127.0.0.1:8000", changeOrigin: true, ws: true },
+    },
+  },
   resolve: {
     alias: {
       "@": path.resolve(__dirname, "./src"),
diff --git a/src/frontend/yarn.lock b/src/frontend/yarn.lock
index afe20878..7cb90e88 100644
--- a/src/frontend/yarn.lock
+++ b/src/frontend/yarn.lock
@@ -3211,7 +3211,16 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/estree@npm:1.0.8, @types/estree@npm:^1.0.6":
+"@types/estree-jsx@npm:^1.0.0":
+  version: 1.0.5
+  resolution: "@types/estree-jsx@npm:1.0.5"
+  dependencies:
+    "@types/estree": "npm:*"
+  checksum: 10c0/07b354331516428b27a3ab99ee397547d47eb223c34053b48f84872fafb841770834b90cc1a0068398e7c7ccb15ec51ab00ec64b31dc5e3dbefd624638a35c6d
+  languageName: node
+  linkType: hard
+
+"@types/estree@npm:*, @types/estree@npm:1.0.8, @types/estree@npm:^1.0.0, @types/estree@npm:^1.0.6":
   version: 1.0.8
   resolution: "@types/estree@npm:1.0.8"
   checksum: 10c0/39d34d1afaa338ab9763f37ad6066e3f349444f9052b9676a7cc0252ef9485a41c6d81c9c4e0d26e9077993354edf25efc853f3224dd4b447175ef62bdcc86a5
@@ -3322,6 +3331,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/unist@npm:^2.0.0":
+  version: 2.0.11
+  resolution: "@types/unist@npm:2.0.11"
+  checksum: 10c0/24dcdf25a168f453bb70298145eb043cfdbb82472db0bc0b56d6d51cd2e484b9ed8271d4ac93000a80da568f2402e9339723db262d0869e2bf13bc58e081768d
+  languageName: node
+  linkType: hard
+
 "@types/use-sync-external-store@npm:1.5.0":
   version: 1.5.0
   resolution: "@types/use-sync-external-store@npm:1.5.0"
@@ -3773,6 +3789,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"character-reference-invalid@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "character-reference-invalid@npm:2.0.1"
+  checksum: 10c0/2ae0dec770cd8659d7e8b0ce24392d83b4c2f0eb4a3395c955dce5528edd4cc030a794cfa06600fcdd700b3f2de2f9b8e40e309c0011c4180e3be64a0b42e6a1
+  languageName: node
+  linkType: hard
+
 "chevrotain-allstar@npm:~0.3.0":
   version: 0.3.1
   resolution: "chevrotain-allstar@npm:0.3.1"
@@ -4825,6 +4848,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"estree-util-is-identifier-name@npm:^3.0.0":
+  version: 3.0.0
+  resolution: "estree-util-is-identifier-name@npm:3.0.0"
+  checksum: 10c0/d1881c6ed14bd588ebd508fc90bf2a541811dbb9ca04dec2f39d27dcaa635f85b5ed9bbbe7fc6fb1ddfca68744a5f7c70456b4b7108b6c4c52780631cc787c5b
+  languageName: node
+  linkType: hard
+
 "esutils@npm:^2.0.2":
   version: 2.0.3
   resolution: "esutils@npm:2.0.3"
@@ -4880,6 +4910,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fast-json-patch@npm:^3.1.1":
+  version: 3.1.1
+  resolution: "fast-json-patch@npm:3.1.1"
+  checksum: 10c0/8a0438b4818bb53153275fe5b38033610e8c9d9eb11869e6a7dc05eb92fa70f3caa57015e344eb3ae1e71c7a75ad4cc6bc2dc9e0ff281d6ed8ecd44505210ca8
+  languageName: node
+  linkType: hard
+
 "fast-json-stable-stringify@npm:^2.0.0":
   version: 2.1.0
   resolution: "fast-json-stable-stringify@npm:2.1.0"
@@ -5035,21 +5072,24 @@ __metadata:
     eslint: "npm:^9.30.1"
     eslint-plugin-react-hooks: "npm:^5.2.0"
     eslint-plugin-react-refresh: "npm:^0.4.20"
+    fast-json-patch: "npm:^3.1.1"
     globals: "npm:^16.3.0"
     immer: "npm:^10.1.1"
     lucide-react: "npm:^0.532.0"
     mermaid: "npm:^11.9.0"
     next-themes: "npm:^0.4.6"
     postcss: "npm:^8.5.6"
-    react: "npm:^19.1.0"
+    react: "npm:^19.2.0"
     react-day-picker: "npm:^9.8.1"
-    react-dom: "npm:^19.1.0"
+    react-dom: "npm:^19.2.0"
     react-hook-form: "npm:^7.61.1"
     react-icons: "npm:^5.5.0"
+    react-markdown: "npm:^10.1.0"
     react-resizable-panels: "npm:^3.0.3"
     react-router: "npm:^7.12.0"
     react-router-dom: "npm:^7.12.0"
     react-virtual: "npm:^2.10.4"
+    remark-gfm: "npm:^4.0.1"
     remeda: "npm:^2.32.0"
     socket.io-client: "npm:^4.8.1"
     sonner: "npm:^2.0.6"
@@ -5348,6 +5388,29 @@ __metadata:
   languageName: node
   linkType: hard
 
+"hast-util-to-jsx-runtime@npm:^2.0.0":
+  version: 2.3.6
+  resolution: "hast-util-to-jsx-runtime@npm:2.3.6"
+  dependencies:
+    "@types/estree": "npm:^1.0.0"
+    "@types/hast": "npm:^3.0.0"
+    "@types/unist": "npm:^3.0.0"
+    comma-separated-tokens: "npm:^2.0.0"
+    devlop: "npm:^1.0.0"
+    estree-util-is-identifier-name: "npm:^3.0.0"
+    hast-util-whitespace: "npm:^3.0.0"
+    mdast-util-mdx-expression: "npm:^2.0.0"
+    mdast-util-mdx-jsx: "npm:^3.0.0"
+    mdast-util-mdxjs-esm: "npm:^2.0.0"
+    property-information: "npm:^7.0.0"
+    space-separated-tokens: "npm:^2.0.0"
+    style-to-js: "npm:^1.0.0"
+    unist-util-position: "npm:^5.0.0"
+    vfile-message: "npm:^4.0.0"
+  checksum: 10c0/27297e02848fe37ef219be04a26ce708d17278a175a807689e94a821dcffc88aa506d62c3a85beed1f9a8544f7211bdcbcde0528b7b456a57c2e342c3fd11056
+  languageName: node
+  linkType: hard
+
 "hast-util-to-mdast@npm:^10.0.0":
   version: 10.1.2
   resolution: "hast-util-to-mdast@npm:10.1.2"
@@ -5404,6 +5467,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"html-url-attributes@npm:^3.0.0":
+  version: 3.0.1
+  resolution: "html-url-attributes@npm:3.0.1"
+  checksum: 10c0/496e4908aa8b77665f348b4b03521901794f648b8ac34a581022cd6f2c97934d5c910cd91bc6593bbf2994687549037bc2520fcdc769b31484f29ffdd402acd0
+  languageName: node
+  linkType: hard
+
 "html-void-elements@npm:^3.0.0":
   version: 3.0.0
   resolution: "html-void-elements@npm:3.0.0"
@@ -5492,6 +5562,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"inline-style-parser@npm:0.2.7":
+  version: 0.2.7
+  resolution: "inline-style-parser@npm:0.2.7"
+  checksum: 10c0/d884d76f84959517430ae6c22f0bda59bb3f58f539f99aac75a8d786199ec594ed648c6ab4640531f9fc244b0ed5cd8c458078e592d016ef06de793beb1debff
+  languageName: node
+  linkType: hard
+
 "internmap@npm:1 - 2":
   version: 2.0.3
   resolution: "internmap@npm:2.0.3"
@@ -5513,6 +5590,30 @@ __metadata:
   languageName: node
   linkType: hard
 
+"is-alphabetical@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "is-alphabetical@npm:2.0.1"
+  checksum: 10c0/932367456f17237533fd1fc9fe179df77957271020b83ea31da50e5cc472d35ef6b5fb8147453274ffd251134472ce24eb6f8d8398d96dee98237cdb81a6c9a7
+  languageName: node
+  linkType: hard
+
+"is-alphanumerical@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "is-alphanumerical@npm:2.0.1"
+  dependencies:
+    is-alphabetical: "npm:^2.0.0"
+    is-decimal: "npm:^2.0.0"
+  checksum: 10c0/4b35c42b18e40d41378293f82a3ecd9de77049b476f748db5697c297f686e1e05b072a6aaae2d16f54d2a57f85b00cbbe755c75f6d583d1c77d6657bd0feb5a2
+  languageName: node
+  linkType: hard
+
+"is-decimal@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "is-decimal@npm:2.0.1"
+  checksum: 10c0/8085dd66f7d82f9de818fba48b9e9c0429cb4291824e6c5f2622e96b9680b54a07a624cfc663b24148b8e853c62a1c987cfe8b0b5a13f5156991afaf6736e334
+  languageName: node
+  linkType: hard
+
 "is-extglob@npm:^2.1.1":
   version: 2.1.1
   resolution: "is-extglob@npm:2.1.1"
@@ -5536,6 +5637,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"is-hexadecimal@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "is-hexadecimal@npm:2.0.1"
+  checksum: 10c0/3eb60fe2f1e2bbc760b927dcad4d51eaa0c60138cf7fc671803f66353ad90c301605b502c7ea4c6bb0548e1c7e79dfd37b73b632652e3b76030bba603a7e9626
+  languageName: node
+  linkType: hard
+
 "is-number@npm:^7.0.0":
   version: 7.0.0
   resolution: "is-number@npm:7.0.0"
@@ -6121,6 +6229,54 @@ __metadata:
   languageName: node
   linkType: hard
 
+"mdast-util-mdx-expression@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "mdast-util-mdx-expression@npm:2.0.1"
+  dependencies:
+    "@types/estree-jsx": "npm:^1.0.0"
+    "@types/hast": "npm:^3.0.0"
+    "@types/mdast": "npm:^4.0.0"
+    devlop: "npm:^1.0.0"
+    mdast-util-from-markdown: "npm:^2.0.0"
+    mdast-util-to-markdown: "npm:^2.0.0"
+  checksum: 10c0/9a1e57940f66431f10312fa239096efa7627f375e7933b5d3162c0b5c1712a72ac87447aff2b6838d2bbd5c1311b188718cc90b33b67dc67a88550e0a6ef6183
+  languageName: node
+  linkType: hard
+
+"mdast-util-mdx-jsx@npm:^3.0.0":
+  version: 3.2.0
+  resolution: "mdast-util-mdx-jsx@npm:3.2.0"
+  dependencies:
+    "@types/estree-jsx": "npm:^1.0.0"
+    "@types/hast": "npm:^3.0.0"
+    "@types/mdast": "npm:^4.0.0"
+    "@types/unist": "npm:^3.0.0"
+    ccount: "npm:^2.0.0"
+    devlop: "npm:^1.1.0"
+    mdast-util-from-markdown: "npm:^2.0.0"
+    mdast-util-to-markdown: "npm:^2.0.0"
+    parse-entities: "npm:^4.0.0"
+    stringify-entities: "npm:^4.0.0"
+    unist-util-stringify-position: "npm:^4.0.0"
+    vfile-message: "npm:^4.0.0"
+  checksum: 10c0/3acadaf3b962254f7ad2990fed4729961dc0217ca31fde9917986e880843f3ecf3392b1f22d569235cacd180d50894ad266db7af598aedca69d330d33c7ac613
+  languageName: node
+  linkType: hard
+
+"mdast-util-mdxjs-esm@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "mdast-util-mdxjs-esm@npm:2.0.1"
+  dependencies:
+    "@types/estree-jsx": "npm:^1.0.0"
+    "@types/hast": "npm:^3.0.0"
+    "@types/mdast": "npm:^4.0.0"
+    devlop: "npm:^1.0.0"
+    mdast-util-from-markdown: "npm:^2.0.0"
+    mdast-util-to-markdown: "npm:^2.0.0"
+  checksum: 10c0/5bda92fc154141705af2b804a534d891f28dac6273186edf1a4c5e3f045d5b01dbcac7400d27aaf91b7e76e8dce007c7b2fdf136c11ea78206ad00bdf9db46bc
+  languageName: node
+  linkType: hard
+
 "mdast-util-phrasing@npm:^4.0.0":
   version: 4.1.0
   resolution: "mdast-util-phrasing@npm:4.1.0"
@@ -6833,6 +6989,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"parse-entities@npm:^4.0.0":
+  version: 4.0.2
+  resolution: "parse-entities@npm:4.0.2"
+  dependencies:
+    "@types/unist": "npm:^2.0.0"
+    character-entities-legacy: "npm:^3.0.0"
+    character-reference-invalid: "npm:^2.0.0"
+    decode-named-character-reference: "npm:^1.0.0"
+    is-alphanumerical: "npm:^2.0.0"
+    is-decimal: "npm:^2.0.0"
+    is-hexadecimal: "npm:^2.0.0"
+  checksum: 10c0/a13906b1151750b78ed83d386294066daf5fb559e08c5af9591b2d98cc209123103016a01df776f65f8219ad26652d6d6b210d0974d452049cddfc53a8916c34
+  languageName: node
+  linkType: hard
+
 "parse5@npm:^7.0.0":
   version: 7.3.0
   resolution: "parse5@npm:7.3.0"
@@ -7296,14 +7467,14 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react-dom@npm:^19.1.0":
-  version: 19.2.0
-  resolution: "react-dom@npm:19.2.0"
+"react-dom@npm:^19.2.0":
+  version: 19.2.4
+  resolution: "react-dom@npm:19.2.4"
   dependencies:
     scheduler: "npm:^0.27.0"
   peerDependencies:
-    react: ^19.2.0
-  checksum: 10c0/fa2cae05248d01288e91523b590ce4e7635b1e13f1344e225f850d722a8da037bf0782f63b1c1d46353334e0c696909b82e582f8cad607948fde6f7646cc18d9
+    react: ^19.2.4
+  checksum: 10c0/f0c63f1794dedb154136d4d0f59af00b41907f4859571c155940296808f4b94bf9c0c20633db75b5b2112ec13d8d7dd4f9bf57362ed48782f317b11d05a44f35
   languageName: node
   linkType: hard
 
@@ -7334,6 +7505,28 @@ __metadata:
   languageName: node
   linkType: hard
 
+"react-markdown@npm:^10.1.0":
+  version: 10.1.0
+  resolution: "react-markdown@npm:10.1.0"
+  dependencies:
+    "@types/hast": "npm:^3.0.0"
+    "@types/mdast": "npm:^4.0.0"
+    devlop: "npm:^1.0.0"
+    hast-util-to-jsx-runtime: "npm:^2.0.0"
+    html-url-attributes: "npm:^3.0.0"
+    mdast-util-to-hast: "npm:^13.0.0"
+    remark-parse: "npm:^11.0.0"
+    remark-rehype: "npm:^11.0.0"
+    unified: "npm:^11.0.0"
+    unist-util-visit: "npm:^5.0.0"
+    vfile: "npm:^6.0.0"
+  peerDependencies:
+    "@types/react": ">=18"
+    react: ">=18"
+  checksum: 10c0/4a5dc7d15ca6d05e9ee95318c1904f83b111a76f7588c44f50f1d54d4c97193b84e4f64c4b592057c989228238a2590306cedd0c4d398e75da49262b2b5ae1bf
+  languageName: node
+  linkType: hard
+
 "react-refresh@npm:^0.17.0":
   version: 0.17.0
   resolution: "react-refresh@npm:0.17.0"
@@ -7441,10 +7634,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react@npm:^19.1.0":
-  version: 19.2.0
-  resolution: "react@npm:19.2.0"
-  checksum: 10c0/1b6d64eacb9324725bfe1e7860cb7a6b8a34bc89a482920765ebff5c10578eb487e6b46b2f0df263bd27a25edbdae2c45e5ea5d81ae61404301c1a7192c38330
+"react@npm:^19.2.0":
+  version: 19.2.4
+  resolution: "react@npm:19.2.4"
+  checksum: 10c0/cd2c9ff67a720799cc3b38a516009986f7fc4cb8d3e15716c6211cf098d1357ee3e348ab05ad0600042bbb0fd888530ba92e329198c92eafa0994f5213396596
   languageName: node
   linkType: hard
 
@@ -7554,7 +7747,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"remark-rehype@npm:^11.1.2":
+"remark-rehype@npm:^11.0.0, remark-rehype@npm:^11.1.2":
   version: 11.1.2
   resolution: "remark-rehype@npm:11.1.2"
   dependencies:
@@ -7940,6 +8133,24 @@ __metadata:
   languageName: node
   linkType: hard
 
+"style-to-js@npm:^1.0.0":
+  version: 1.1.21
+  resolution: "style-to-js@npm:1.1.21"
+  dependencies:
+    style-to-object: "npm:1.0.14"
+  checksum: 10c0/94231aa80f58f442c3a5ae01a21d10701e5d62f96b4b3e52eab3499077ee52df203cc0df4a1a870707f5e99470859136ea8657b782a5f4ca7934e0ffe662a588
+  languageName: node
+  linkType: hard
+
+"style-to-object@npm:1.0.14":
+  version: 1.0.14
+  resolution: "style-to-object@npm:1.0.14"
+  dependencies:
+    inline-style-parser: "npm:0.2.7"
+  checksum: 10c0/854d9e9b77afc336e6d7b09348e7939f2617b34eb0895824b066d8cd1790284cb6d8b2ba36be88025b2595d715dba14b299ae76e4628a366541106f639e13679
+  languageName: node
+  linkType: hard
+
 "stylis@npm:^4.3.6":
   version: 4.3.6
   resolution: "stylis@npm:4.3.6"
diff --git a/uv.lock b/uv.lock
index a920f1e5..d167f513 100755
--- a/uv.lock
+++ b/uv.lock
@@ -235,6 +235,9 @@ dependencies = [
     { name = "httpx" },
     { name = "jedi" },
     { name = "kuzu" },
+    { name = "langchain" },
+    { name = "langchain-openai" },
+    { name = "langgraph" },
     { name = "libcst" },
     { name = "loguru" },
     { name = "parso" },
@@ -277,6 +280,9 @@ requires-dist = [
     { name = "httpx", marker = "extra == 'test'" },
     { name = "jedi", specifier = ">=0.19.2" },
     { name = "kuzu", specifier = ">=0.11.3" },
+    { name = "langchain", specifier = ">=1.2.12" },
+    { name = "langchain-openai", specifier = ">=1.1.11" },
+    { name = "langgraph", specifier = ">=1.1.2" },
     { name = "libcst", specifier = ">=1.7.0" },
     { name = "loguru", specifier = ">=0.7.3" },
     { name = "parso", specifier = ">=0.8.5" },
@@ -533,6 +539,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4e/8c/f3147f5c4b73e7550fe5f9352eaa956ae838d5c51eb58e7a25b9f3e2643b/decorator-5.2.1-py3-none-any.whl", hash = "sha256:d316bb415a2d9e2d2b3abcc4084c6502fc09240e292cd76a76afc106a1c8e04a", size = 9190 },
 ]
 
+[[package]]
+name = "distro"
+version = "1.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fc/f8/98eea607f65de6527f8a2e8885fc8015d3e6f5775df186e443e0964a11c3/distro-1.9.0.tar.gz", hash = "sha256:2fa77c6fd8940f116ee1d6b94a2f90b13b5ea8d019b98bc8bafdcabcdd9bdbed", size = 60722 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/12/b3/231ffd4ab1fc9d679809f356cebee130ac7daa00d6d6f3206dd4fd137e9e/distro-1.9.0-py3-none-any.whl", hash = "sha256:7bffd925d65168f85027d8da9af6bddab658135b840670a223589bc0c8ef02b2", size = 20277 },
+]
+
 [[package]]
 name = "dnspython"
 version = "2.7.0"
@@ -863,6 +878,90 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899 },
 ]
 
+[[package]]
+name = "jiter"
+version = "0.13.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0d/5e/4ec91646aee381d01cdb9974e30882c9cd3b8c5d1079d6b5ff4af522439a/jiter-0.13.0.tar.gz", hash = "sha256:f2839f9c2c7e2dffc1bc5929a510e14ce0a946be9365fd1219e7ef342dae14f4", size = 164847 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2e/30/7687e4f87086829955013ca12a9233523349767f69653ebc27036313def9/jiter-0.13.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:0a2bd69fc1d902e89925fc34d1da51b2128019423d7b339a45d9e99c894e0663", size = 307958 },
+    { url = "https://files.pythonhosted.org/packages/c3/27/e57f9a783246ed95481e6749cc5002a8a767a73177a83c63ea71f0528b90/jiter-0.13.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f917a04240ef31898182f76a332f508f2cc4b57d2b4d7ad2dbfebbfe167eb505", size = 318597 },
+    { url = "https://files.pythonhosted.org/packages/cf/52/e5719a60ac5d4d7c5995461a94ad5ef962a37c8bf5b088390e6fad59b2ff/jiter-0.13.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c1e2b199f446d3e82246b4fd9236d7cb502dc2222b18698ba0d986d2fecc6152", size = 348821 },
+    { url = "https://files.pythonhosted.org/packages/61/db/c1efc32b8ba4c740ab3fc2d037d8753f67685f475e26b9d6536a4322bcdd/jiter-0.13.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:04670992b576fa65bd056dbac0c39fe8bd67681c380cb2b48efa885711d9d726", size = 364163 },
+    { url = "https://files.pythonhosted.org/packages/55/8a/fb75556236047c8806995671a18e4a0ad646ed255276f51a20f32dceaeec/jiter-0.13.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5a1aff1fbdb803a376d4d22a8f63f8e7ccbce0b4890c26cc7af9e501ab339ef0", size = 483709 },
+    { url = "https://files.pythonhosted.org/packages/7e/16/43512e6ee863875693a8e6f6d532e19d650779d6ba9a81593ae40a9088ff/jiter-0.13.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:3b3fb8c2053acaef8580809ac1d1f7481a0a0bdc012fd7f5d8b18fb696a5a089", size = 370480 },
+    { url = "https://files.pythonhosted.org/packages/f8/4c/09b93e30e984a187bc8aaa3510e1ec8dcbdcd71ca05d2f56aac0492453aa/jiter-0.13.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bdaba7d87e66f26a2c45d8cbadcbfc4bf7884182317907baf39cfe9775bb4d93", size = 360735 },
+    { url = "https://files.pythonhosted.org/packages/1a/1b/46c5e349019874ec5dfa508c14c37e29864ea108d376ae26d90bee238cd7/jiter-0.13.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:7b88d649135aca526da172e48083da915ec086b54e8e73a425ba50999468cc08", size = 391814 },
+    { url = "https://files.pythonhosted.org/packages/15/9e/26184760e85baee7162ad37b7912797d2077718476bf91517641c92b3639/jiter-0.13.0-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:e404ea551d35438013c64b4f357b0474c7abf9f781c06d44fcaf7a14c69ff9e2", size = 513990 },
+    { url = "https://files.pythonhosted.org/packages/e9/34/2c9355247d6debad57a0a15e76ab1566ab799388042743656e566b3b7de1/jiter-0.13.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:1f4748aad1b4a93c8bdd70f604d0f748cdc0e8744c5547798acfa52f10e79228", size = 548021 },
+    { url = "https://files.pythonhosted.org/packages/ac/4a/9f2c23255d04a834398b9c2e0e665382116911dc4d06b795710503cdad25/jiter-0.13.0-cp312-cp312-win32.whl", hash = "sha256:0bf670e3b1445fc4d31612199f1744f67f889ee1bbae703c4b54dc097e5dd394", size = 203024 },
+    { url = "https://files.pythonhosted.org/packages/09/ee/f0ae675a957ae5a8f160be3e87acea6b11dc7b89f6b7ab057e77b2d2b13a/jiter-0.13.0-cp312-cp312-win_amd64.whl", hash = "sha256:15db60e121e11fe186c0b15236bd5d18381b9ddacdcf4e659feb96fc6c969c92", size = 205424 },
+    { url = "https://files.pythonhosted.org/packages/1b/02/ae611edf913d3cbf02c97cdb90374af2082c48d7190d74c1111dde08bcdd/jiter-0.13.0-cp312-cp312-win_arm64.whl", hash = "sha256:41f92313d17989102f3cb5dd533a02787cdb99454d494344b0361355da52fcb9", size = 186818 },
+    { url = "https://files.pythonhosted.org/packages/91/9c/7ee5a6ff4b9991e1a45263bfc46731634c4a2bde27dfda6c8251df2d958c/jiter-0.13.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:1f8a55b848cbabf97d861495cd65f1e5c590246fabca8b48e1747c4dfc8f85bf", size = 306897 },
+    { url = "https://files.pythonhosted.org/packages/7c/02/be5b870d1d2be5dd6a91bdfb90f248fbb7dcbd21338f092c6b89817c3dbf/jiter-0.13.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f556aa591c00f2c45eb1b89f68f52441a016034d18b65da60e2d2875bbbf344a", size = 317507 },
+    { url = "https://files.pythonhosted.org/packages/da/92/b25d2ec333615f5f284f3a4024f7ce68cfa0604c322c6808b2344c7f5d2b/jiter-0.13.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f7e1d61da332ec412350463891923f960c3073cf1aae93b538f0bb4c8cd46efb", size = 350560 },
+    { url = "https://files.pythonhosted.org/packages/be/ec/74dcb99fef0aca9fbe56b303bf79f6bd839010cb18ad41000bf6cc71eec0/jiter-0.13.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:3097d665a27bc96fd9bbf7f86178037db139f319f785e4757ce7ccbf390db6c2", size = 363232 },
+    { url = "https://files.pythonhosted.org/packages/1b/37/f17375e0bb2f6a812d4dd92d7616e41917f740f3e71343627da9db2824ce/jiter-0.13.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9d01ecc3a8cbdb6f25a37bd500510550b64ddf9f7d64a107d92f3ccb25035d0f", size = 483727 },
+    { url = "https://files.pythonhosted.org/packages/77/d2/a71160a5ae1a1e66c1395b37ef77da67513b0adba73b993a27fbe47eb048/jiter-0.13.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ed9bbc30f5d60a3bdf63ae76beb3f9db280d7f195dfcfa61af792d6ce912d159", size = 370799 },
+    { url = "https://files.pythonhosted.org/packages/01/99/ed5e478ff0eb4e8aa5fd998f9d69603c9fd3f32de3bd16c2b1194f68361c/jiter-0.13.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:98fbafb6e88256f4454de33c1f40203d09fc33ed19162a68b3b257b29ca7f663", size = 359120 },
+    { url = "https://files.pythonhosted.org/packages/16/be/7ffd08203277a813f732ba897352797fa9493faf8dc7995b31f3d9cb9488/jiter-0.13.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:5467696f6b827f1116556cb0db620440380434591e93ecee7fd14d1a491b6daa", size = 390664 },
+    { url = "https://files.pythonhosted.org/packages/d1/84/e0787856196d6d346264d6dcccb01f741e5f0bd014c1d9a2ebe149caf4f3/jiter-0.13.0-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:2d08c9475d48b92892583df9da592a0e2ac49bcd41fae1fec4f39ba6cf107820", size = 513543 },
+    { url = "https://files.pythonhosted.org/packages/65/50/ecbd258181c4313cf79bca6c88fb63207d04d5bf5e4f65174114d072aa55/jiter-0.13.0-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:aed40e099404721d7fcaf5b89bd3b4568a4666358bcac7b6b15c09fb6252ab68", size = 547262 },
+    { url = "https://files.pythonhosted.org/packages/27/da/68f38d12e7111d2016cd198161b36e1f042bd115c169255bcb7ec823a3bf/jiter-0.13.0-cp313-cp313-win32.whl", hash = "sha256:36ebfbcffafb146d0e6ffb3e74d51e03d9c35ce7c625c8066cdbfc7b953bdc72", size = 200630 },
+    { url = "https://files.pythonhosted.org/packages/25/65/3bd1a972c9a08ecd22eb3b08a95d1941ebe6938aea620c246cf426ae09c2/jiter-0.13.0-cp313-cp313-win_amd64.whl", hash = "sha256:8d76029f077379374cf0dbc78dbe45b38dec4a2eb78b08b5194ce836b2517afc", size = 202602 },
+    { url = "https://files.pythonhosted.org/packages/15/fe/13bd3678a311aa67686bb303654792c48206a112068f8b0b21426eb6851e/jiter-0.13.0-cp313-cp313-win_arm64.whl", hash = "sha256:bb7613e1a427cfcb6ea4544f9ac566b93d5bf67e0d48c787eca673ff9c9dff2b", size = 185939 },
+    { url = "https://files.pythonhosted.org/packages/49/19/a929ec002ad3228bc97ca01dbb14f7632fffdc84a95ec92ceaf4145688ae/jiter-0.13.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:fa476ab5dd49f3bf3a168e05f89358c75a17608dbabb080ef65f96b27c19ab10", size = 316616 },
+    { url = "https://files.pythonhosted.org/packages/52/56/d19a9a194afa37c1728831e5fb81b7722c3de18a3109e8f282bfc23e587a/jiter-0.13.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ade8cb6ff5632a62b7dbd4757d8c5573f7a2e9ae285d6b5b841707d8363205ef", size = 346850 },
+    { url = "https://files.pythonhosted.org/packages/36/4a/94e831c6bf287754a8a019cb966ed39ff8be6ab78cadecf08df3bb02d505/jiter-0.13.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9950290340acc1adaded363edd94baebcee7dabdfa8bee4790794cd5cfad2af6", size = 358551 },
+    { url = "https://files.pythonhosted.org/packages/a2/ec/a4c72c822695fa80e55d2b4142b73f0012035d9fcf90eccc56bc060db37c/jiter-0.13.0-cp313-cp313t-win_amd64.whl", hash = "sha256:2b4972c6df33731aac0742b64fd0d18e0a69bc7d6e03108ce7d40c85fd9e3e6d", size = 201950 },
+    { url = "https://files.pythonhosted.org/packages/b6/00/393553ec27b824fbc29047e9c7cd4a3951d7fbe4a76743f17e44034fa4e4/jiter-0.13.0-cp313-cp313t-win_arm64.whl", hash = "sha256:701a1e77d1e593c1b435315ff625fd071f0998c5f02792038a5ca98899261b7d", size = 185852 },
+    { url = "https://files.pythonhosted.org/packages/6e/f5/f1997e987211f6f9bd71b8083047b316208b4aca0b529bb5f8c96c89ef3e/jiter-0.13.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:cc5223ab19fe25e2f0bf2643204ad7318896fe3729bf12fde41b77bfc4fafff0", size = 308804 },
+    { url = "https://files.pythonhosted.org/packages/cd/8f/5482a7677731fd44881f0204981ce2d7175db271f82cba2085dd2212e095/jiter-0.13.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9776ebe51713acf438fd9b4405fcd86893ae5d03487546dae7f34993217f8a91", size = 318787 },
+    { url = "https://files.pythonhosted.org/packages/f3/b9/7257ac59778f1cd025b26a23c5520a36a424f7f1b068f2442a5b499b7464/jiter-0.13.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:879e768938e7b49b5e90b7e3fecc0dbec01b8cb89595861fb39a8967c5220d09", size = 353880 },
+    { url = "https://files.pythonhosted.org/packages/c3/87/719eec4a3f0841dad99e3d3604ee4cba36af4419a76f3cb0b8e2e691ad67/jiter-0.13.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:682161a67adea11e3aae9038c06c8b4a9a71023228767477d683f69903ebc607", size = 366702 },
+    { url = "https://files.pythonhosted.org/packages/d2/65/415f0a75cf6921e43365a1bc227c565cb949caca8b7532776e430cbaa530/jiter-0.13.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a13b68cd1cd8cc9de8f244ebae18ccb3e4067ad205220ef324c39181e23bbf66", size = 486319 },
+    { url = "https://files.pythonhosted.org/packages/54/a2/9e12b48e82c6bbc6081fd81abf915e1443add1b13d8fc586e1d90bb02bb8/jiter-0.13.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:87ce0f14c6c08892b610686ae8be350bf368467b6acd5085a5b65441e2bf36d2", size = 372289 },
+    { url = "https://files.pythonhosted.org/packages/4e/c1/e4693f107a1789a239c759a432e9afc592366f04e901470c2af89cfd28e1/jiter-0.13.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0c365005b05505a90d1c47856420980d0237adf82f70c4aff7aebd3c1cc143ad", size = 360165 },
+    { url = "https://files.pythonhosted.org/packages/17/08/91b9ea976c1c758240614bd88442681a87672eebc3d9a6dde476874e706b/jiter-0.13.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1317fdffd16f5873e46ce27d0e0f7f4f90f0cdf1d86bf6abeaea9f63ca2c401d", size = 389634 },
+    { url = "https://files.pythonhosted.org/packages/18/23/58325ef99390d6d40427ed6005bf1ad54f2577866594bcf13ce55675f87d/jiter-0.13.0-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:c05b450d37ba0c9e21c77fef1f205f56bcee2330bddca68d344baebfc55ae0df", size = 514933 },
+    { url = "https://files.pythonhosted.org/packages/5b/25/69f1120c7c395fd276c3996bb8adefa9c6b84c12bb7111e5c6ccdcd8526d/jiter-0.13.0-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:775e10de3849d0631a97c603f996f518159272db00fdda0a780f81752255ee9d", size = 548842 },
+    { url = "https://files.pythonhosted.org/packages/18/05/981c9669d86850c5fbb0d9e62bba144787f9fba84546ba43d624ee27ef29/jiter-0.13.0-cp314-cp314-win32.whl", hash = "sha256:632bf7c1d28421c00dd8bbb8a3bac5663e1f57d5cd5ed962bce3c73bf62608e6", size = 202108 },
+    { url = "https://files.pythonhosted.org/packages/8d/96/cdcf54dd0b0341db7d25413229888a346c7130bd20820530905fdb65727b/jiter-0.13.0-cp314-cp314-win_amd64.whl", hash = "sha256:f22ef501c3f87ede88f23f9b11e608581c14f04db59b6a801f354397ae13739f", size = 204027 },
+    { url = "https://files.pythonhosted.org/packages/fb/f9/724bcaaab7a3cd727031fe4f6995cb86c4bd344909177c186699c8dec51a/jiter-0.13.0-cp314-cp314-win_arm64.whl", hash = "sha256:07b75fe09a4ee8e0c606200622e571e44943f47254f95e2436c8bdcaceb36d7d", size = 187199 },
+    { url = "https://files.pythonhosted.org/packages/62/92/1661d8b9fd6a3d7a2d89831db26fe3c1509a287d83ad7838831c7b7a5c7e/jiter-0.13.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:964538479359059a35fb400e769295d4b315ae61e4105396d355a12f7fef09f0", size = 318423 },
+    { url = "https://files.pythonhosted.org/packages/4f/3b/f77d342a54d4ebcd128e520fc58ec2f5b30a423b0fd26acdfc0c6fef8e26/jiter-0.13.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e104da1db1c0991b3eaed391ccd650ae8d947eab1480c733e5a3fb28d4313e40", size = 351438 },
+    { url = "https://files.pythonhosted.org/packages/76/b3/ba9a69f0e4209bd3331470c723c2f5509e6f0482e416b612431a5061ed71/jiter-0.13.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:0e3a5f0cde8ff433b8e88e41aa40131455420fb3649a3c7abdda6145f8cb7202", size = 364774 },
+    { url = "https://files.pythonhosted.org/packages/b3/16/6cdb31fa342932602458dbb631bfbd47f601e03d2e4950740e0b2100b570/jiter-0.13.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:57aab48f40be1db920a582b30b116fe2435d184f77f0e4226f546794cedd9cf0", size = 487238 },
+    { url = "https://files.pythonhosted.org/packages/ed/b1/956cc7abaca8d95c13aa8d6c9b3f3797241c246cd6e792934cc4c8b250d2/jiter-0.13.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:7772115877c53f62beeb8fd853cab692dbc04374ef623b30f997959a4c0e7e95", size = 372892 },
+    { url = "https://files.pythonhosted.org/packages/26/c4/97ecde8b1e74f67b8598c57c6fccf6df86ea7861ed29da84629cdbba76c4/jiter-0.13.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1211427574b17b633cfceba5040de8081e5abf114f7a7602f73d2e16f9fdaa59", size = 360309 },
+    { url = "https://files.pythonhosted.org/packages/4b/d7/eabe3cf46715854ccc80be2cd78dd4c36aedeb30751dbf85a1d08c14373c/jiter-0.13.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:7beae3a3d3b5212d3a55d2961db3c292e02e302feb43fce6a3f7a31b90ea6dfe", size = 389607 },
+    { url = "https://files.pythonhosted.org/packages/df/2d/03963fc0804e6109b82decfb9974eb92df3797fe7222428cae12f8ccaa0c/jiter-0.13.0-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:e5562a0f0e90a6223b704163ea28e831bd3a9faa3512a711f031611e6b06c939", size = 514986 },
+    { url = "https://files.pythonhosted.org/packages/f6/6c/8c83b45eb3eb1c1e18d841fe30b4b5bc5619d781267ca9bc03e005d8fd0a/jiter-0.13.0-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:6c26a424569a59140fb51160a56df13f438a2b0967365e987889186d5fc2f6f9", size = 548756 },
+    { url = "https://files.pythonhosted.org/packages/47/66/eea81dfff765ed66c68fd2ed8c96245109e13c896c2a5015c7839c92367e/jiter-0.13.0-cp314-cp314t-win32.whl", hash = "sha256:24dc96eca9f84da4131cdf87a95e6ce36765c3b156fc9ae33280873b1c32d5f6", size = 201196 },
+    { url = "https://files.pythonhosted.org/packages/ff/32/4ac9c7a76402f8f00d00842a7f6b83b284d0cf7c1e9d4227bc95aa6d17fa/jiter-0.13.0-cp314-cp314t-win_amd64.whl", hash = "sha256:0a8d76c7524087272c8ae913f5d9d608bd839154b62c4322ef65723d2e5bb0b8", size = 204215 },
+    { url = "https://files.pythonhosted.org/packages/f9/8e/7def204fea9f9be8b3c21a6f2dd6c020cf56c7d5ff753e0e23ed7f9ea57e/jiter-0.13.0-cp314-cp314t-win_arm64.whl", hash = "sha256:2c26cf47e2cad140fa23b6d58d435a7c0161f5c514284802f25e87fddfe11024", size = 187152 },
+    { url = "https://files.pythonhosted.org/packages/79/b3/3c29819a27178d0e461a8571fb63c6ae38be6dc36b78b3ec2876bbd6a910/jiter-0.13.0-graalpy311-graalpy242_311_native-macosx_10_12_x86_64.whl", hash = "sha256:b1cbfa133241d0e6bdab48dcdc2604e8ba81512f6bbd68ec3e8e1357dd3c316c", size = 307016 },
+    { url = "https://files.pythonhosted.org/packages/eb/ae/60993e4b07b1ac5ebe46da7aa99fdbb802eb986c38d26e3883ac0125c4e0/jiter-0.13.0-graalpy311-graalpy242_311_native-macosx_11_0_arm64.whl", hash = "sha256:db367d8be9fad6e8ebbac4a7578b7af562e506211036cba2c06c3b998603c3d2", size = 305024 },
+    { url = "https://files.pythonhosted.org/packages/77/fa/2227e590e9cf98803db2811f172b2d6460a21539ab73006f251c66f44b14/jiter-0.13.0-graalpy311-graalpy242_311_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:45f6f8efb2f3b0603092401dc2df79fa89ccbc027aaba4174d2d4133ed661434", size = 339337 },
+    { url = "https://files.pythonhosted.org/packages/2d/92/015173281f7eb96c0ef580c997da8ef50870d4f7f4c9e03c845a1d62ae04/jiter-0.13.0-graalpy311-graalpy242_311_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:597245258e6ad085d064780abfb23a284d418d3e61c57362d9449c6c7317ee2d", size = 346395 },
+    { url = "https://files.pythonhosted.org/packages/80/60/e50fa45dd7e2eae049f0ce964663849e897300433921198aef94b6ffa23a/jiter-0.13.0-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:3d744a6061afba08dd7ae375dcde870cffb14429b7477e10f67e9e6d68772a0a", size = 305169 },
+    { url = "https://files.pythonhosted.org/packages/d2/73/a009f41c5eed71c49bec53036c4b33555afcdee70682a18c6f66e396c039/jiter-0.13.0-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:ff732bd0a0e778f43d5009840f20b935e79087b4dc65bd36f1cd0f9b04b8ff7f", size = 303808 },
+    { url = "https://files.pythonhosted.org/packages/c4/10/528b439290763bff3d939268085d03382471b442f212dca4ff5f12802d43/jiter-0.13.0-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ab44b178f7981fcaea7e0a5df20e773c663d06ffda0198f1a524e91b2fde7e59", size = 337384 },
+    { url = "https://files.pythonhosted.org/packages/67/8a/a342b2f0251f3dac4ca17618265d93bf244a2a4d089126e81e4c1056ac50/jiter-0.13.0-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7bb00b6d26db67a05fe3e12c76edc75f32077fb51deed13822dc648fa373bc19", size = 343768 },
+]
+
+[[package]]
+name = "jsonpatch"
+version = "1.33"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "jsonpointer" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/42/78/18813351fe5d63acad16aec57f94ec2b70a09e53ca98145589e185423873/jsonpatch-1.33.tar.gz", hash = "sha256:9fcd4009c41e6d12348b4a0ff2563ba56a2923a7dfee731d004e212e1ee5030c", size = 21699 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/73/07/02e16ed01e04a374e644b575638ec7987ae846d25ad97bcc9945a3ee4b0e/jsonpatch-1.33-py2.py3-none-any.whl", hash = "sha256:0ae28c0cd062bbd8b8ecc26d7d164fbbea9652a1a3693f3b956c1eae5145dade", size = 12898 },
+]
+
 [[package]]
 name = "jsonpickle"
 version = "4.1.1"
@@ -872,6 +971,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c1/73/04df8a6fa66d43a9fd45c30f283cc4afff17da671886e451d52af60bdc7e/jsonpickle-4.1.1-py3-none-any.whl", hash = "sha256:bb141da6057898aa2438ff268362b126826c812a1721e31cf08a6e142910dc91", size = 47125 },
 ]
 
+[[package]]
+name = "jsonpointer"
+version = "3.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6a/0a/eebeb1fa92507ea94016a2a790b93c2ae41a7e18778f85471dc54475ed25/jsonpointer-3.0.0.tar.gz", hash = "sha256:2b2d729f2091522d61c3b31f82e11870f60b68f43fbc705cb76bf4b832af59ef", size = 9114 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/71/92/5e77f98553e9e75130c78900d000368476aed74276eb8ae8796f65f00918/jsonpointer-3.0.0-py2.py3-none-any.whl", hash = "sha256:13e088adc14fca8b6aa8177c044e12701e6ad4b28ff10e65f2267a90109c9942", size = 7595 },
+]
+
 [[package]]
 name = "kuzu"
 version = "0.11.3"
@@ -896,6 +1004,129 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/06/be/5b4ff168718165c2ff5848ab79e22ecce72ad00522afee6820d390cb0753/kuzu-0.11.3-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:64c7ec822906bdee154eb38d93e64f184d8f94b30bbeaceaa252725f2b9efab3", size = 7620394 },
 ]
 
+[[package]]
+name = "langchain"
+version = "1.2.12"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "langchain-core" },
+    { name = "langgraph" },
+    { name = "pydantic" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d8/1d/1af2fc0ac084d4781778b7846b1aed62e05006bf2d73fdf84ac3a8f5225c/langchain-1.2.12.tar.gz", hash = "sha256:ed705b5b293799f7e3e394387f398a1b71707542758283206c8c21415759d991", size = 566444 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ca/51/09bb1cfb0b57ae9440ca56cc576e4dc792f83d030eef7637d2c516dcb0a0/langchain-1.2.12-py3-none-any.whl", hash = "sha256:60eff184b8f92c2610f5a4c9a97ad339a891adb01901e83e4df8e6c9c69cf852", size = 112373 },
+]
+
+[[package]]
+name = "langchain-core"
+version = "1.2.19"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "jsonpatch" },
+    { name = "langsmith" },
+    { name = "packaging" },
+    { name = "pydantic" },
+    { name = "pyyaml" },
+    { name = "tenacity" },
+    { name = "typing-extensions" },
+    { name = "uuid-utils" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ac/da/075720d37ebc668f48743bd540b047b2b08b8ba22b46d8f61166c5ad1d1c/langchain_core-1.2.19.tar.gz", hash = "sha256:87fa82c3eb4cc3d7a65f574cb447b5df09ec2131c8c2a0a02d4737ad02685438", size = 836647 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/aa/cb/8704b2a22c0987627ed29464d23a45fb15e10a28fb482f4d84c3bddcbf27/langchain_core-1.2.19-py3-none-any.whl", hash = "sha256:6e74cb0fb443a8046ee298c05c99b67abe54cc57fcbc6d1cd3b0f2485ee47574", size = 503456 },
+]
+
+[[package]]
+name = "langchain-openai"
+version = "1.1.11"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "langchain-core" },
+    { name = "openai" },
+    { name = "tiktoken" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/40/cd/439be2b8deb8bd0d4c470c7c7f66698a84d823e583c3d36a322483cb7cab/langchain_openai-1.1.11.tar.gz", hash = "sha256:44b003a2960d1f6699f23721196b3b97d0c420d2e04444950869213214b7a06a", size = 1088560 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f0/0f/e4cb42848c25f65969adfb500a06dea1a541831604250fd0d8aa6e54fef5/langchain_openai-1.1.11-py3-none-any.whl", hash = "sha256:a03596221405d38d6852fb865467cb0d9ff9e79f335905eb6a576e8c4874ac71", size = 87694 },
+]
+
+[[package]]
+name = "langgraph"
+version = "1.1.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "langchain-core" },
+    { name = "langgraph-checkpoint" },
+    { name = "langgraph-prebuilt" },
+    { name = "langgraph-sdk" },
+    { name = "pydantic" },
+    { name = "xxhash" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ca/a8/8494057db9149eb850258e5d4ae961a8dbda9a283e56e1b957393d9df0cd/langgraph-1.1.2.tar.gz", hash = "sha256:c4385ce349823a590891b3f6b1c46b54f51d0134164056866e95034985f047c9", size = 544288 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/52/38/3117cd90325635893a76132cdae74f5b1f53c93c33b3dc6124521cec9825/langgraph-1.1.2-py3-none-any.whl", hash = "sha256:5fd43c839ec2b5af564e9ae2d2d4f22ce0a006a0b58e800cc4e8de4dd9cbb643", size = 167543 },
+]
+
+[[package]]
+name = "langgraph-checkpoint"
+version = "4.0.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "langchain-core" },
+    { name = "ormsgpack" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/44/a8df45d1e8b4637e29789fa8bae1db022c953cc7ac80093cfc52e923547e/langgraph_checkpoint-4.0.1.tar.gz", hash = "sha256:b433123735df11ade28829e40ce25b9be614930cd50245ff2af60629234befd9", size = 158135 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/65/4c/09a4a0c42f5d2fc38d6c4d67884788eff7fd2cfdf367fdf7033de908b4c0/langgraph_checkpoint-4.0.1-py3-none-any.whl", hash = "sha256:e3adcd7a0e0166f3b48b8cf508ce0ea366e7420b5a73aa81289888727769b034", size = 50453 },
+]
+
+[[package]]
+name = "langgraph-prebuilt"
+version = "1.0.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "langchain-core" },
+    { name = "langgraph-checkpoint" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0d/06/dd61a5c2dce009d1b03b1d56f2a85b3127659fdddf5b3be5d8f1d60820fb/langgraph_prebuilt-1.0.8.tar.gz", hash = "sha256:0cd3cf5473ced8a6cd687cc5294e08d3de57529d8dd14fdc6ae4899549efcf69", size = 164442 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/dc/41/ec966424ad3f2ed3996d24079d3342c8cd6c0bd0653c12b2a917a685ec6c/langgraph_prebuilt-1.0.8-py3-none-any.whl", hash = "sha256:d16a731e591ba4470f3e313a319c7eee7dbc40895bcf15c821f985a3522a7ce0", size = 35648 },
+]
+
+[[package]]
+name = "langgraph-sdk"
+version = "0.3.11"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "httpx" },
+    { name = "orjson" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/35/cd/a019f1b1e97c519f2425593f9bccd3ac463a18fb5d2111cff59ce1ef62fe/langgraph_sdk-0.3.11.tar.gz", hash = "sha256:3640134835d89d2c7c8bb7de73bd10673d4b282db3ff0e2fdaf1cee9e50cb1eb", size = 190387 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/13/c8/b8d15d4b9a320a3f57a851030a371066b91dbd1420f097d3d0338da9adc9/langgraph_sdk-0.3.11-py3-none-any.whl", hash = "sha256:18905fd6248ade98b0995d859a98672d57c811fbfffc0d63d1c107a512351b26", size = 94887 },
+]
+
+[[package]]
+name = "langsmith"
+version = "0.7.20"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "httpx" },
+    { name = "orjson", marker = "platform_python_implementation != 'PyPy'" },
+    { name = "packaging" },
+    { name = "pydantic" },
+    { name = "requests" },
+    { name = "requests-toolbelt" },
+    { name = "uuid-utils" },
+    { name = "xxhash" },
+    { name = "zstandard" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/80/c6/cbdc6638207f68a3c61ec0b64fa593f6b11de3170d03c852238c31b54960/langsmith-0.7.20.tar.gz", hash = "sha256:fa983a74f75648ee0e80d3f9751162b6f9a438896d5f9bdb6cba9abda451e234", size = 1134732 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e8/46/9294d4f49de6a8f08e8b83907713ca545459d87d474c6add15d31a36f5dc/langsmith-0.7.20-py3-none-any.whl", hash = "sha256:0162faf791ea48d69009a12a3da917468556b99cf5d5fcacbb8cda064262e118", size = 359314 },
+]
+
 [[package]]
 name = "libcst"
 version = "1.7.0"
@@ -1199,6 +1430,117 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/62/5e/3a6a3e90f35cea3853c45e5d5fb9b7192ce4384616f932cf7591298ab6e1/numpydoc-1.10.0-py3-none-any.whl", hash = "sha256:3149da9874af890bcc2a82ef7aae5484e5aa81cb2778f08e3c307ba6d963721b", size = 69255 },
 ]
 
+[[package]]
+name = "openai"
+version = "2.29.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "distro" },
+    { name = "httpx" },
+    { name = "jiter" },
+    { name = "pydantic" },
+    { name = "sniffio" },
+    { name = "tqdm" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b4/15/203d537e58986b5673e7f232453a2a2f110f22757b15921cbdeea392e520/openai-2.29.0.tar.gz", hash = "sha256:32d09eb2f661b38d3edd7d7e1a2943d1633f572596febe64c0cd370c86d52bec", size = 671128 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d0/b1/35b6f9c8cf9318e3dbb7146cc82dab4cf61182a8d5406fc9b50864362895/openai-2.29.0-py3-none-any.whl", hash = "sha256:b7c5de513c3286d17c5e29b92c4c98ceaf0d775244ac8159aeb1bddf840eb42a", size = 1141533 },
+]
+
+[[package]]
+name = "orjson"
+version = "3.11.7"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/45/b268004f745ede84e5798b48ee12b05129d19235d0e15267aa57dcdb400b/orjson-3.11.7.tar.gz", hash = "sha256:9b1a67243945819ce55d24a30b59d6a168e86220452d2c96f4d1f093e71c0c49", size = 6144992 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/80/bf/76f4f1665f6983385938f0e2a5d7efa12a58171b8456c252f3bae8a4cf75/orjson-3.11.7-cp312-cp312-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:bd03ea7606833655048dab1a00734a2875e3e86c276e1d772b2a02556f0d895f", size = 228545 },
+    { url = "https://files.pythonhosted.org/packages/79/53/6c72c002cb13b5a978a068add59b25a8bdf2800ac1c9c8ecdb26d6d97064/orjson-3.11.7-cp312-cp312-macosx_15_0_arm64.whl", hash = "sha256:89e440ebc74ce8ab5c7bc4ce6757b4a6b1041becb127df818f6997b5c71aa60b", size = 125224 },
+    { url = "https://files.pythonhosted.org/packages/2c/83/10e48852865e5dd151bdfe652c06f7da484578ed02c5fca938e3632cb0b8/orjson-3.11.7-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5ede977b5fe5ac91b1dffc0a517ca4542d2ec8a6a4ff7b2652d94f640796342a", size = 128154 },
+    { url = "https://files.pythonhosted.org/packages/6e/52/a66e22a2b9abaa374b4a081d410edab6d1e30024707b87eab7c734afe28d/orjson-3.11.7-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:b7b1dae39230a393df353827c855a5f176271c23434cfd2db74e0e424e693e10", size = 123548 },
+    { url = "https://files.pythonhosted.org/packages/de/38/605d371417021359f4910c496f764c48ceb8997605f8c25bf1dfe58c0ebe/orjson-3.11.7-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ed46f17096e28fb28d2975834836a639af7278aa87c84f68ab08fbe5b8bd75fa", size = 129000 },
+    { url = "https://files.pythonhosted.org/packages/44/98/af32e842b0ffd2335c89714d48ca4e3917b42f5d6ee5537832e069a4b3ac/orjson-3.11.7-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:3726be79e36e526e3d9c1aceaadbfb4a04ee80a72ab47b3f3c17fefb9812e7b8", size = 141686 },
+    { url = "https://files.pythonhosted.org/packages/96/0b/fc793858dfa54be6feee940c1463370ece34b3c39c1ca0aa3845f5ba9892/orjson-3.11.7-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:0724e265bc548af1dedebd9cb3d24b4e1c1e685a343be43e87ba922a5c5fff2f", size = 130812 },
+    { url = "https://files.pythonhosted.org/packages/dc/91/98a52415059db3f374757d0b7f0f16e3b5cd5976c90d1c2b56acaea039e6/orjson-3.11.7-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e7745312efa9e11c17fbd3cb3097262d079da26930ae9ae7ba28fb738367cbad", size = 133440 },
+    { url = "https://files.pythonhosted.org/packages/dc/b6/cb540117bda61791f46381f8c26c8f93e802892830a6055748d3bb1925ab/orjson-3.11.7-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:f904c24bdeabd4298f7a977ef14ca2a022ca921ed670b92ecd16ab6f3d01f867", size = 138386 },
+    { url = "https://files.pythonhosted.org/packages/63/1a/50a3201c334a7f17c231eee5f841342190723794e3b06293f26e7cf87d31/orjson-3.11.7-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:b9fc4d0f81f394689e0814617aadc4f2ea0e8025f38c226cbf22d3b5ddbf025d", size = 408853 },
+    { url = "https://files.pythonhosted.org/packages/87/cd/8de1c67d0be44fdc22701e5989c0d015a2adf391498ad42c4dc589cd3013/orjson-3.11.7-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:849e38203e5be40b776ed2718e587faf204d184fc9a008ae441f9442320c0cab", size = 144130 },
+    { url = "https://files.pythonhosted.org/packages/0f/fe/d605d700c35dd55f51710d159fc54516a280923cd1b7e47508982fbb387d/orjson-3.11.7-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:4682d1db3bcebd2b64757e0ddf9e87ae5f00d29d16c5cdf3a62f561d08cc3dd2", size = 134818 },
+    { url = "https://files.pythonhosted.org/packages/e4/e4/15ecc67edb3ddb3e2f46ae04475f2d294e8b60c1825fbe28a428b93b3fbd/orjson-3.11.7-cp312-cp312-win32.whl", hash = "sha256:f4f7c956b5215d949a1f65334cf9d7612dde38f20a95f2315deef167def91a6f", size = 127923 },
+    { url = "https://files.pythonhosted.org/packages/34/70/2e0855361f76198a3965273048c8e50a9695d88cd75811a5b46444895845/orjson-3.11.7-cp312-cp312-win_amd64.whl", hash = "sha256:bf742e149121dc5648ba0a08ea0871e87b660467ef168a3a5e53bc1fbd64bb74", size = 125007 },
+    { url = "https://files.pythonhosted.org/packages/68/40/c2051bd19fc467610fed469dc29e43ac65891571138f476834ca192bc290/orjson-3.11.7-cp312-cp312-win_arm64.whl", hash = "sha256:26c3b9132f783b7d7903bf1efb095fed8d4a3a85ec0d334ee8beff3d7a4749d5", size = 126089 },
+    { url = "https://files.pythonhosted.org/packages/89/25/6e0e52cac5aab51d7b6dcd257e855e1dec1c2060f6b28566c509b4665f62/orjson-3.11.7-cp313-cp313-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:1d98b30cc1313d52d4af17d9c3d307b08389752ec5f2e5febdfada70b0f8c733", size = 228390 },
+    { url = "https://files.pythonhosted.org/packages/a5/29/a77f48d2fc8a05bbc529e5ff481fb43d914f9e383ea2469d4f3d51df3d00/orjson-3.11.7-cp313-cp313-macosx_15_0_arm64.whl", hash = "sha256:d897e81f8d0cbd2abb82226d1860ad2e1ab3ff16d7b08c96ca00df9d45409ef4", size = 125189 },
+    { url = "https://files.pythonhosted.org/packages/89/25/0a16e0729a0e6a1504f9d1a13cdd365f030068aab64cec6958396b9969d7/orjson-3.11.7-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:814be4b49b228cfc0b3c565acf642dd7d13538f966e3ccde61f4f55be3e20785", size = 128106 },
+    { url = "https://files.pythonhosted.org/packages/66/da/a2e505469d60666a05ab373f1a6322eb671cb2ba3a0ccfc7d4bc97196787/orjson-3.11.7-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d06e5c5fed5caedd2e540d62e5b1c25e8c82431b9e577c33537e5fa4aa909539", size = 123363 },
+    { url = "https://files.pythonhosted.org/packages/23/bf/ed73f88396ea35c71b38961734ea4a4746f7ca0768bf28fd551d37e48dd0/orjson-3.11.7-cp313-cp313-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:31c80ce534ac4ea3739c5ee751270646cbc46e45aea7576a38ffec040b4029a1", size = 129007 },
+    { url = "https://files.pythonhosted.org/packages/73/3c/b05d80716f0225fc9008fbf8ab22841dcc268a626aa550561743714ce3bf/orjson-3.11.7-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f50979824bde13d32b4320eedd513431c921102796d86be3eee0b58e58a3ecd1", size = 141667 },
+    { url = "https://files.pythonhosted.org/packages/61/e8/0be9b0addd9bf86abfc938e97441dcd0375d494594b1c8ad10fe57479617/orjson-3.11.7-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9e54f3808e2b6b945078c41aa8d9b5834b28c50843846e97807e5adb75fa9705", size = 130832 },
+    { url = "https://files.pythonhosted.org/packages/c9/ec/c68e3b9021a31d9ec15a94931db1410136af862955854ed5dd7e7e4f5bff/orjson-3.11.7-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a12b80df61aab7b98b490fe9e4879925ba666fccdfcd175252ce4d9035865ace", size = 133373 },
+    { url = "https://files.pythonhosted.org/packages/d2/45/f3466739aaafa570cc8e77c6dbb853c48bf56e3b43738020e2661e08b0ac/orjson-3.11.7-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:996b65230271f1a97026fd0e6a753f51fbc0c335d2ad0c6201f711b0da32693b", size = 138307 },
+    { url = "https://files.pythonhosted.org/packages/e1/84/9f7f02288da1ffb31405c1be07657afd1eecbcb4b64ee2817b6fe0f785fa/orjson-3.11.7-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:ab49d4b2a6a1d415ddb9f37a21e02e0d5dbfe10b7870b21bf779fc21e9156157", size = 408695 },
+    { url = "https://files.pythonhosted.org/packages/18/07/9dd2f0c0104f1a0295ffbe912bc8d63307a539b900dd9e2c48ef7810d971/orjson-3.11.7-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:390a1dce0c055ddf8adb6aa94a73b45a4a7d7177b5c584b8d1c1947f2ba60fb3", size = 144099 },
+    { url = "https://files.pythonhosted.org/packages/a5/66/857a8e4a3292e1f7b1b202883bcdeb43a91566cf59a93f97c53b44bd6801/orjson-3.11.7-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:1eb80451a9c351a71dfaf5b7ccc13ad065405217726b59fdbeadbcc544f9d223", size = 134806 },
+    { url = "https://files.pythonhosted.org/packages/0a/5b/6ebcf3defc1aab3a338ca777214966851e92efb1f30dc7fc8285216e6d1b/orjson-3.11.7-cp313-cp313-win32.whl", hash = "sha256:7477aa6a6ec6139c5cb1cc7b214643592169a5494d200397c7fc95d740d5fcf3", size = 127914 },
+    { url = "https://files.pythonhosted.org/packages/00/04/c6f72daca5092e3117840a1b1e88dfc809cc1470cf0734890d0366b684a1/orjson-3.11.7-cp313-cp313-win_amd64.whl", hash = "sha256:b9f95dcdea9d4f805daa9ddf02617a89e484c6985fa03055459f90e87d7a0757", size = 124986 },
+    { url = "https://files.pythonhosted.org/packages/03/ba/077a0f6f1085d6b806937246860fafbd5b17f3919c70ee3f3d8d9c713f38/orjson-3.11.7-cp313-cp313-win_arm64.whl", hash = "sha256:800988273a014a0541483dc81021247d7eacb0c845a9d1a34a422bc718f41539", size = 126045 },
+    { url = "https://files.pythonhosted.org/packages/e9/1e/745565dca749813db9a093c5ebc4bac1a9475c64d54b95654336ac3ed961/orjson-3.11.7-cp314-cp314-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:de0a37f21d0d364954ad5de1970491d7fbd0fb1ef7417d4d56a36dc01ba0c0a0", size = 228391 },
+    { url = "https://files.pythonhosted.org/packages/46/19/e40f6225da4d3aa0c8dc6e5219c5e87c2063a560fe0d72a88deb59776794/orjson-3.11.7-cp314-cp314-macosx_15_0_arm64.whl", hash = "sha256:c2428d358d85e8da9d37cba18b8c4047c55222007a84f97156a5b22028dfbfc0", size = 125188 },
+    { url = "https://files.pythonhosted.org/packages/9d/7e/c4de2babef2c0817fd1f048fd176aa48c37bec8aef53d2fa932983032cce/orjson-3.11.7-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3c4bc6c6ac52cdaa267552544c73e486fecbd710b7ac09bc024d5a78555a22f6", size = 128097 },
+    { url = "https://files.pythonhosted.org/packages/eb/74/233d360632bafd2197f217eee7fb9c9d0229eac0c18128aee5b35b0014fe/orjson-3.11.7-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bd0d68edd7dfca1b2eca9361a44ac9f24b078de3481003159929a0573f21a6bf", size = 123364 },
+    { url = "https://files.pythonhosted.org/packages/79/51/af79504981dd31efe20a9e360eb49c15f06df2b40e7f25a0a52d9ae888e8/orjson-3.11.7-cp314-cp314-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:623ad1b9548ef63886319c16fa317848e465a21513b31a6ad7b57443c3e0dcf5", size = 129076 },
+    { url = "https://files.pythonhosted.org/packages/67/e2/da898eb68b72304f8de05ca6715870d09d603ee98d30a27e8a9629abc64b/orjson-3.11.7-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:6e776b998ac37c0396093d10290e60283f59cfe0fc3fccbd0ccc4bd04dd19892", size = 141705 },
+    { url = "https://files.pythonhosted.org/packages/c5/89/15364d92acb3d903b029e28d834edb8780c2b97404cbf7929aa6b9abdb24/orjson-3.11.7-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:652c6c3af76716f4a9c290371ba2e390ede06f6603edb277b481daf37f6f464e", size = 130855 },
+    { url = "https://files.pythonhosted.org/packages/c2/8b/ecdad52d0b38d4b8f514be603e69ccd5eacf4e7241f972e37e79792212ec/orjson-3.11.7-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a56df3239294ea5964adf074c54bcc4f0ccd21636049a2cf3ca9cf03b5d03cf1", size = 133386 },
+    { url = "https://files.pythonhosted.org/packages/b9/0e/45e1dcf10e17d0924b7c9162f87ec7b4ca79e28a0548acf6a71788d3e108/orjson-3.11.7-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:bda117c4148e81f746655d5a3239ae9bd00cb7bc3ca178b5fc5a5997e9744183", size = 138295 },
+    { url = "https://files.pythonhosted.org/packages/63/d7/4d2e8b03561257af0450f2845b91fbd111d7e526ccdf737267108075e0ba/orjson-3.11.7-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:23d6c20517a97a9daf1d48b580fcdc6f0516c6f4b5038823426033690b4d2650", size = 408720 },
+    { url = "https://files.pythonhosted.org/packages/78/cf/d45343518282108b29c12a65892445fc51f9319dc3c552ceb51bb5905ed2/orjson-3.11.7-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:8ff206156006da5b847c9304b6308a01e8cdbc8cce824e2779a5ba71c3def141", size = 144152 },
+    { url = "https://files.pythonhosted.org/packages/a9/3a/d6001f51a7275aacd342e77b735c71fa04125a3f93c36fee4526bc8c654e/orjson-3.11.7-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:962d046ee1765f74a1da723f4b33e3b228fe3a48bd307acce5021dfefe0e29b2", size = 134814 },
+    { url = "https://files.pythonhosted.org/packages/1d/d3/f19b47ce16820cc2c480f7f1723e17f6d411b3a295c60c8ad3aa9ff1c96a/orjson-3.11.7-cp314-cp314-win32.whl", hash = "sha256:89e13dd3f89f1c38a9c9eba5fbf7cdc2d1feca82f5f290864b4b7a6aac704576", size = 127997 },
+    { url = "https://files.pythonhosted.org/packages/12/df/172771902943af54bf661a8d102bdf2e7f932127968080632bda6054b62c/orjson-3.11.7-cp314-cp314-win_amd64.whl", hash = "sha256:845c3e0d8ded9c9271cd79596b9b552448b885b97110f628fb687aee2eed11c1", size = 124985 },
+    { url = "https://files.pythonhosted.org/packages/6f/1c/f2a8d8a1b17514660a614ce5f7aac74b934e69f5abc2700cc7ced882a009/orjson-3.11.7-cp314-cp314-win_arm64.whl", hash = "sha256:4a2e9c5be347b937a2e0203866f12bba36082e89b402ddb9e927d5822e43088d", size = 126038 },
+]
+
+[[package]]
+name = "ormsgpack"
+version = "1.12.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/12/0c/f1761e21486942ab9bb6feaebc610fa074f7c5e496e6962dea5873348077/ormsgpack-1.12.2.tar.gz", hash = "sha256:944a2233640273bee67521795a73cf1e959538e0dfb7ac635505010455e53b33", size = 39031 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4c/36/16c4b1921c308a92cef3bf6663226ae283395aa0ff6e154f925c32e91ff5/ormsgpack-1.12.2-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:7a29d09b64b9694b588ff2f80e9826bdceb3a2b91523c5beae1fab27d5c940e7", size = 378618 },
+    { url = "https://files.pythonhosted.org/packages/c0/68/468de634079615abf66ed13bb5c34ff71da237213f29294363beeeca5306/ormsgpack-1.12.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0b39e629fd2e1c5b2f46f99778450b59454d1f901bc507963168985e79f09c5d", size = 203186 },
+    { url = "https://files.pythonhosted.org/packages/73/a9/d756e01961442688b7939bacd87ce13bfad7d26ce24f910f6028178b2cc8/ormsgpack-1.12.2-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:958dcb270d30a7cb633a45ee62b9444433fa571a752d2ca484efdac07480876e", size = 210738 },
+    { url = "https://files.pythonhosted.org/packages/7b/ba/795b1036888542c9113269a3f5690ab53dd2258c6fb17676ac4bd44fcf94/ormsgpack-1.12.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:58d379d72b6c5e964851c77cfedfb386e474adee4fd39791c2c5d9efb53505cc", size = 212569 },
+    { url = "https://files.pythonhosted.org/packages/6c/aa/bff73c57497b9e0cba8837c7e4bcab584b1a6dbc91a5dd5526784a5030c8/ormsgpack-1.12.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8463a3fc5f09832e67bdb0e2fda6d518dc4281b133166146a67f54c08496442e", size = 387166 },
+    { url = "https://files.pythonhosted.org/packages/d3/cf/f8283cba44bcb7b14f97b6274d449db276b3a86589bdb363169b51bc12de/ormsgpack-1.12.2-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:eddffb77eff0bad4e67547d67a130604e7e2dfbb7b0cde0796045be4090f35c6", size = 482498 },
+    { url = "https://files.pythonhosted.org/packages/05/be/71e37b852d723dfcbe952ad04178c030df60d6b78eba26bfd14c9a40575e/ormsgpack-1.12.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fcd55e5f6ba0dbce624942adf9f152062135f991a0126064889f68eb850de0dd", size = 425518 },
+    { url = "https://files.pythonhosted.org/packages/7a/0c/9803aa883d18c7ef197213cd2cbf73ba76472a11fe100fb7dab2884edf48/ormsgpack-1.12.2-cp312-cp312-win_amd64.whl", hash = "sha256:d024b40828f1dde5654faebd0d824f9cc29ad46891f626272dd5bfd7af2333a4", size = 117462 },
+    { url = "https://files.pythonhosted.org/packages/c8/9e/029e898298b2cc662f10d7a15652a53e3b525b1e7f07e21fef8536a09bb8/ormsgpack-1.12.2-cp312-cp312-win_arm64.whl", hash = "sha256:da538c542bac7d1c8f3f2a937863dba36f013108ce63e55745941dda4b75dbb6", size = 111559 },
+    { url = "https://files.pythonhosted.org/packages/eb/29/bb0eba3288c0449efbb013e9c6f58aea79cf5cb9ee1921f8865f04c1a9d7/ormsgpack-1.12.2-cp313-cp313-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:5ea60cb5f210b1cfbad8c002948d73447508e629ec375acb82910e3efa8ff355", size = 378661 },
+    { url = "https://files.pythonhosted.org/packages/6e/31/5efa31346affdac489acade2926989e019e8ca98129658a183e3add7af5e/ormsgpack-1.12.2-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f3601f19afdbea273ed70b06495e5794606a8b690a568d6c996a90d7255e51c1", size = 203194 },
+    { url = "https://files.pythonhosted.org/packages/eb/56/d0087278beef833187e0167f8527235ebe6f6ffc2a143e9de12a98b1ce87/ormsgpack-1.12.2-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:29a9f17a3dac6054c0dce7925e0f4995c727f7c41859adf9b5572180f640d172", size = 210778 },
+    { url = "https://files.pythonhosted.org/packages/1c/a2/072343e1413d9443e5a252a8eb591c2d5b1bffbe5e7bfc78c069361b92eb/ormsgpack-1.12.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:39c1bd2092880e413902910388be8715f70b9f15f20779d44e673033a6146f2d", size = 212592 },
+    { url = "https://files.pythonhosted.org/packages/a2/8b/a0da3b98a91d41187a63b02dda14267eefc2a74fcb43cc2701066cf1510e/ormsgpack-1.12.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:50b7249244382209877deedeee838aef1542f3d0fc28b8fe71ca9d7e1896a0d7", size = 387164 },
+    { url = "https://files.pythonhosted.org/packages/19/bb/6d226bc4cf9fc20d8eb1d976d027a3f7c3491e8f08289a2e76abe96a65f3/ormsgpack-1.12.2-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:5af04800d844451cf102a59c74a841324868d3f1625c296a06cc655c542a6685", size = 482516 },
+    { url = "https://files.pythonhosted.org/packages/fb/f1/bb2c7223398543dedb3dbf8bb93aaa737b387de61c5feaad6f908841b782/ormsgpack-1.12.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:cec70477d4371cd524534cd16472d8b9cc187e0e3043a8790545a9a9b296c258", size = 425539 },
+    { url = "https://files.pythonhosted.org/packages/7b/e8/0fb45f57a2ada1fed374f7494c8cd55e2f88ccd0ab0a669aa3468716bf5f/ormsgpack-1.12.2-cp313-cp313-win_amd64.whl", hash = "sha256:21f4276caca5c03a818041d637e4019bc84f9d6ca8baa5ea03e5cc8bf56140e9", size = 117459 },
+    { url = "https://files.pythonhosted.org/packages/7a/d4/0cfeea1e960d550a131001a7f38a5132c7ae3ebde4c82af1f364ccc5d904/ormsgpack-1.12.2-cp313-cp313-win_arm64.whl", hash = "sha256:baca4b6773d20a82e36d6fd25f341064244f9f86a13dead95dd7d7f996f51709", size = 111577 },
+    { url = "https://files.pythonhosted.org/packages/94/16/24d18851334be09c25e87f74307c84950f18c324a4d3c0b41dabdbf19c29/ormsgpack-1.12.2-cp314-cp314-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:bc68dd5915f4acf66ff2010ee47c8906dc1cf07399b16f4089f8c71733f6e36c", size = 378717 },
+    { url = "https://files.pythonhosted.org/packages/b5/a2/88b9b56f83adae8032ac6a6fa7f080c65b3baf9b6b64fd3d37bd202991d4/ormsgpack-1.12.2-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:46d084427b4132553940070ad95107266656cb646ea9da4975f85cb1a6676553", size = 203183 },
+    { url = "https://files.pythonhosted.org/packages/a9/80/43e4555963bf602e5bdc79cbc8debd8b6d5456c00d2504df9775e74b450b/ormsgpack-1.12.2-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:c010da16235806cf1d7bc4c96bf286bfa91c686853395a299b3ddb49499a3e13", size = 210814 },
+    { url = "https://files.pythonhosted.org/packages/78/e1/7cfbf28de8bca6efe7e525b329c31277d1b64ce08dcba723971c241a9d60/ormsgpack-1.12.2-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:18867233df592c997154ff942a6503df274b5ac1765215bceba7a231bea2745d", size = 212634 },
+    { url = "https://files.pythonhosted.org/packages/95/f8/30ae5716e88d792a4e879debee195653c26ddd3964c968594ddef0a3cc7e/ormsgpack-1.12.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:b009049086ddc6b8f80c76b3955df1aa22a5fbd7673c525cd63bf91f23122ede", size = 387139 },
+    { url = "https://files.pythonhosted.org/packages/dc/81/aee5b18a3e3a0e52f718b37ab4b8af6fae0d9d6a65103036a90c2a8ffb5d/ormsgpack-1.12.2-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:1dcc17d92b6390d4f18f937cf0b99054824a7815818012ddca925d6e01c2e49e", size = 482578 },
+    { url = "https://files.pythonhosted.org/packages/bd/17/71c9ba472d5d45f7546317f467a5fc941929cd68fb32796ca3d13dcbaec2/ormsgpack-1.12.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:f04b5e896d510b07c0ad733d7fce2d44b260c5e6c402d272128f8941984e4285", size = 425539 },
+    { url = "https://files.pythonhosted.org/packages/2e/a6/ac99cd7fe77e822fed5250ff4b86fa66dd4238937dd178d2299f10b69816/ormsgpack-1.12.2-cp314-cp314-win_amd64.whl", hash = "sha256:ae3aba7eed4ca7cb79fd3436eddd29140f17ea254b91604aa1eb19bfcedb990f", size = 117493 },
+    { url = "https://files.pythonhosted.org/packages/3a/67/339872846a1ae4592535385a1c1f93614138566d7af094200c9c3b45d1e5/ormsgpack-1.12.2-cp314-cp314-win_arm64.whl", hash = "sha256:118576ea6006893aea811b17429bfc561b4778fad393f5f538c84af70b01260c", size = 111579 },
+    { url = "https://files.pythonhosted.org/packages/49/c2/6feb972dc87285ad381749d3882d8aecbde9f6ecf908dd717d33d66df095/ormsgpack-1.12.2-cp314-cp314t-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:7121b3d355d3858781dc40dafe25a32ff8a8242b9d80c692fd548a4b1f7fd3c8", size = 378721 },
+    { url = "https://files.pythonhosted.org/packages/a3/9a/900a6b9b413e0f8a471cf07830f9cf65939af039a362204b36bd5b581d8b/ormsgpack-1.12.2-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4ee766d2e78251b7a63daf1cddfac36a73562d3ddef68cacfb41b2af64698033", size = 203170 },
+    { url = "https://files.pythonhosted.org/packages/87/4c/27a95466354606b256f24fad464d7c97ab62bce6cc529dd4673e1179b8fb/ormsgpack-1.12.2-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:292410a7d23de9b40444636b9b8f1e4e4b814af7f1ef476e44887e52a123f09d", size = 212816 },
+    { url = "https://files.pythonhosted.org/packages/73/cd/29cee6007bddf7a834e6cd6f536754c0535fcb939d384f0f37a38b1cddb8/ormsgpack-1.12.2-cp314-cp314t-win_amd64.whl", hash = "sha256:837dd316584485b72ef451d08dd3e96c4a11d12e4963aedb40e08f89685d8ec2", size = 117232 },
+]
+
 [[package]]
 name = "outcome"
 version = "1.3.0.post0"
@@ -1770,6 +2112,94 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341 },
 ]
 
+[[package]]
+name = "regex"
+version = "2026.2.28"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8b/71/41455aa99a5a5ac1eaf311f5d8efd9ce6433c03ac1e0962de163350d0d97/regex-2026.2.28.tar.gz", hash = "sha256:a729e47d418ea11d03469f321aaf67cdee8954cde3ff2cf8403ab87951ad10f2", size = 415184 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/07/42/9061b03cf0fc4b5fa2c3984cbbaed54324377e440a5c5a29d29a72518d62/regex-2026.2.28-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:fcf26c3c6d0da98fada8ae4ef0aa1c3405a431c0a77eb17306d38a89b02adcd7", size = 489574 },
+    { url = "https://files.pythonhosted.org/packages/77/83/0c8a5623a233015595e3da499c5a1c13720ac63c107897a6037bb97af248/regex-2026.2.28-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:02473c954af35dd2defeb07e44182f5705b30ea3f351a7cbffa9177beb14da5d", size = 291426 },
+    { url = "https://files.pythonhosted.org/packages/9e/06/3ef1ac6910dc3295ebd71b1f9bfa737e82cfead211a18b319d45f85ddd09/regex-2026.2.28-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:9b65d33a17101569f86d9c5966a8b1d7fbf8afdda5a8aa219301b0a80f58cf7d", size = 289200 },
+    { url = "https://files.pythonhosted.org/packages/dd/c9/8cc8d850b35ab5650ff6756a1cb85286e2000b66c97520b29c1587455344/regex-2026.2.28-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e71dcecaa113eebcc96622c17692672c2d104b1d71ddf7adeda90da7ddeb26fc", size = 796765 },
+    { url = "https://files.pythonhosted.org/packages/e9/5d/57702597627fc23278ebf36fbb497ac91c0ce7fec89ac6c81e420ca3e38c/regex-2026.2.28-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:481df4623fa4969c8b11f3433ed7d5e3dc9cec0f008356c3212b3933fb77e3d8", size = 863093 },
+    { url = "https://files.pythonhosted.org/packages/02/6d/f3ecad537ca2811b4d26b54ca848cf70e04fcfc138667c146a9f3157779c/regex-2026.2.28-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:64e7c6ad614573e0640f271e811a408d79a9e1fe62a46adb602f598df42a818d", size = 909455 },
+    { url = "https://files.pythonhosted.org/packages/9e/40/bb226f203caa22c1043c1ca79b36340156eca0f6a6742b46c3bb222a3a57/regex-2026.2.28-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d6b08a06976ff4fb0d83077022fde3eca06c55432bb997d8c0495b9a4e9872f4", size = 802037 },
+    { url = "https://files.pythonhosted.org/packages/44/7c/c6d91d8911ac6803b45ca968e8e500c46934e58c0903cbc6d760ee817a0a/regex-2026.2.28-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:864cdd1a2ef5716b0ab468af40139e62ede1b3a53386b375ec0786bb6783fc05", size = 775113 },
+    { url = "https://files.pythonhosted.org/packages/dc/8d/4a9368d168d47abd4158580b8c848709667b1cd293ff0c0c277279543bd0/regex-2026.2.28-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:511f7419f7afab475fd4d639d4aedfc54205bcb0800066753ef68a59f0f330b5", size = 784194 },
+    { url = "https://files.pythonhosted.org/packages/cc/bf/2c72ab5d8b7be462cb1651b5cc333da1d0068740342f350fcca3bca31947/regex-2026.2.28-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:b42f7466e32bf15a961cf09f35fa6323cc72e64d3d2c990b10de1274a5da0a59", size = 856846 },
+    { url = "https://files.pythonhosted.org/packages/7c/f4/6b65c979bb6d09f51bb2d2a7bc85de73c01ec73335d7ddd202dcb8cd1c8f/regex-2026.2.28-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:8710d61737b0c0ce6836b1da7109f20d495e49b3809f30e27e9560be67a257bf", size = 763516 },
+    { url = "https://files.pythonhosted.org/packages/8e/32/29ea5e27400ee86d2cc2b4e80aa059df04eaf78b4f0c18576ae077aeff68/regex-2026.2.28-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:4390c365fd2d45278f45afd4673cb90f7285f5701607e3ad4274df08e36140ae", size = 849278 },
+    { url = "https://files.pythonhosted.org/packages/1d/91/3233d03b5f865111cd517e1c95ee8b43e8b428d61fa73764a80c9bb6f537/regex-2026.2.28-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:cb3b1db8ff6c7b8bf838ab05583ea15230cb2f678e569ab0e3a24d1e8320940b", size = 790068 },
+    { url = "https://files.pythonhosted.org/packages/76/92/abc706c1fb03b4580a09645b206a3fc032f5a9f457bc1a8038ac555658ab/regex-2026.2.28-cp312-cp312-win32.whl", hash = "sha256:f8ed9a5d4612df9d4de15878f0bc6aa7a268afbe5af21a3fdd97fa19516e978c", size = 266416 },
+    { url = "https://files.pythonhosted.org/packages/fa/06/2a6f7dff190e5fa9df9fb4acf2fdf17a1aa0f7f54596cba8de608db56b3a/regex-2026.2.28-cp312-cp312-win_amd64.whl", hash = "sha256:01d65fd24206c8e1e97e2e31b286c59009636c022eb5d003f52760b0f42155d4", size = 277297 },
+    { url = "https://files.pythonhosted.org/packages/b7/f0/58a2484851fadf284458fdbd728f580d55c1abac059ae9f048c63b92f427/regex-2026.2.28-cp312-cp312-win_arm64.whl", hash = "sha256:c0b5ccbb8ffb433939d248707d4a8b31993cb76ab1a0187ca886bf50e96df952", size = 270408 },
+    { url = "https://files.pythonhosted.org/packages/87/f6/dc9ef48c61b79c8201585bf37fa70cd781977da86e466cd94e8e95d2443b/regex-2026.2.28-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:6d63a07e5ec8ce7184452cb00c41c37b49e67dc4f73b2955b5b8e782ea970784", size = 489311 },
+    { url = "https://files.pythonhosted.org/packages/95/c8/c20390f2232d3f7956f420f4ef1852608ad57aa26c3dd78516cb9f3dc913/regex-2026.2.28-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e59bc8f30414d283ae8ee1617b13d8112e7135cb92830f0ec3688cb29152585a", size = 291285 },
+    { url = "https://files.pythonhosted.org/packages/d2/a6/ba1068a631ebd71a230e7d8013fcd284b7c89c35f46f34a7da02082141b1/regex-2026.2.28-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:de0cf053139f96219ccfabb4a8dd2d217c8c82cb206c91d9f109f3f552d6b43d", size = 289051 },
+    { url = "https://files.pythonhosted.org/packages/1d/1b/7cc3b7af4c244c204b7a80924bd3d85aecd9ba5bc82b485c5806ee8cda9e/regex-2026.2.28-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fb4db2f17e6484904f986c5a657cec85574c76b5c5e61c7aae9ffa1bc6224f95", size = 796842 },
+    { url = "https://files.pythonhosted.org/packages/24/87/26bd03efc60e0d772ac1e7b60a2e6325af98d974e2358f659c507d3c76db/regex-2026.2.28-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:52b017b35ac2214d0db5f4f90e303634dc44e4aba4bd6235a27f97ecbe5b0472", size = 863083 },
+    { url = "https://files.pythonhosted.org/packages/ae/54/aeaf4afb1aa0a65e40de52a61dc2ac5b00a83c6cb081c8a1d0dda74f3010/regex-2026.2.28-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:69fc560ccbf08a09dc9b52ab69cacfae51e0ed80dc5693078bdc97db2f91ae96", size = 909412 },
+    { url = "https://files.pythonhosted.org/packages/12/2f/049901def913954e640d199bbc6a7ca2902b6aeda0e5da9d17f114100ec2/regex-2026.2.28-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e61eea47230eba62a31f3e8a0e3164d0f37ef9f40529fb2c79361bc6b53d2a92", size = 802101 },
+    { url = "https://files.pythonhosted.org/packages/7d/a5/512fb9ff7f5b15ea204bb1967ebb649059446decacccb201381f9fa6aad4/regex-2026.2.28-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:4f5c0b182ad4269e7381b7c27fdb0408399881f7a92a4624fd5487f2971dfc11", size = 775260 },
+    { url = "https://files.pythonhosted.org/packages/d1/a8/9a92935878aba19bd72706b9db5646a6f993d99b3f6ed42c02ec8beb1d61/regex-2026.2.28-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:96f6269a2882fbb0ee76967116b83679dc628e68eaea44e90884b8d53d833881", size = 784311 },
+    { url = "https://files.pythonhosted.org/packages/09/d3/fc51a8a738a49a6b6499626580554c9466d3ea561f2b72cfdc72e4149773/regex-2026.2.28-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:b5acd4b6a95f37c3c3828e5d053a7d4edaedb85de551db0153754924cb7c83e3", size = 856876 },
+    { url = "https://files.pythonhosted.org/packages/08/b7/2e641f3d084b120ca4c52e8c762a78da0b32bf03ef546330db3e2635dc5f/regex-2026.2.28-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2234059cfe33d9813a3677ef7667999caea9eeaa83fef98eb6ce15c6cf9e0215", size = 763632 },
+    { url = "https://files.pythonhosted.org/packages/fe/6d/0009021d97e79ee99f3d8641f0a8d001eed23479ade4c3125a5480bf3e2d/regex-2026.2.28-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:c15af43c72a7fb0c97cbc66fa36a43546eddc5c06a662b64a0cbf30d6ac40944", size = 849320 },
+    { url = "https://files.pythonhosted.org/packages/05/7a/51cfbad5758f8edae430cb21961a9c8d04bce1dae4d2d18d4186eec7cfa1/regex-2026.2.28-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9185cc63359862a6e80fe97f696e04b0ad9a11c4ac0a4a927f979f611bfe3768", size = 790152 },
+    { url = "https://files.pythonhosted.org/packages/90/3d/a83e2b6b3daa142acb8c41d51de3876186307d5cb7490087031747662500/regex-2026.2.28-cp313-cp313-win32.whl", hash = "sha256:fb66e5245db9652abd7196ace599b04d9c0e4aa7c8f0e2803938377835780081", size = 266398 },
+    { url = "https://files.pythonhosted.org/packages/85/4f/16e9ebb1fe5425e11b9596c8d57bf8877dcb32391da0bfd33742e3290637/regex-2026.2.28-cp313-cp313-win_amd64.whl", hash = "sha256:71a911098be38c859ceb3f9a9ce43f4ed9f4c6720ad8684a066ea246b76ad9ff", size = 277282 },
+    { url = "https://files.pythonhosted.org/packages/07/b4/92851335332810c5a89723bf7a7e35c7209f90b7d4160024501717b28cc9/regex-2026.2.28-cp313-cp313-win_arm64.whl", hash = "sha256:39bb5727650b9a0275c6a6690f9bb3fe693a7e6cc5c3155b1240aedf8926423e", size = 270382 },
+    { url = "https://files.pythonhosted.org/packages/24/07/6c7e4cec1e585959e96cbc24299d97e4437a81173217af54f1804994e911/regex-2026.2.28-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:97054c55db06ab020342cc0d35d6f62a465fa7662871190175f1ad6c655c028f", size = 492541 },
+    { url = "https://files.pythonhosted.org/packages/7c/13/55eb22ada7f43d4f4bb3815b6132183ebc331c81bd496e2d1f3b8d862e0d/regex-2026.2.28-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:0d25a10811de831c2baa6aef3c0be91622f44dd8d31dd12e69f6398efb15e48b", size = 292984 },
+    { url = "https://files.pythonhosted.org/packages/5b/11/c301f8cb29ce9644a5ef85104c59244e6e7e90994a0f458da4d39baa8e17/regex-2026.2.28-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:d6cfe798d8da41bb1862ed6e0cba14003d387c3c0c4a5d45591076ae9f0ce2f8", size = 291509 },
+    { url = "https://files.pythonhosted.org/packages/b5/43/aabe384ec1994b91796e903582427bc2ffaed9c4103819ed3c16d8e749f3/regex-2026.2.28-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fd0ce43e71d825b7c0661f9c54d4d74bd97c56c3fd102a8985bcfea48236bacb", size = 809429 },
+    { url = "https://files.pythonhosted.org/packages/04/b8/8d2d987a816720c4f3109cee7c06a4b24ad0e02d4fc74919ab619e543737/regex-2026.2.28-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:00945d007fd74a9084d2ab79b695b595c6b7ba3698972fadd43e23230c6979c1", size = 869422 },
+    { url = "https://files.pythonhosted.org/packages/fc/ad/2c004509e763c0c3719f97c03eca26473bffb3868d54c5f280b8cd4f9e3d/regex-2026.2.28-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:bec23c11cbbf09a4df32fe50d57cbdd777bc442269b6e39a1775654f1c95dee2", size = 915175 },
+    { url = "https://files.pythonhosted.org/packages/55/c2/fd429066da487ef555a9da73bf214894aec77fc8c66a261ee355a69871a8/regex-2026.2.28-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5cdcc17d935c8f9d3f4db5c2ebe2640c332e3822ad5d23c2f8e0228e6947943a", size = 812044 },
+    { url = "https://files.pythonhosted.org/packages/5b/ca/feedb7055c62a3f7f659971bf45f0e0a87544b6b0cf462884761453f97c5/regex-2026.2.28-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a448af01e3d8031c89c5d902040b124a5e921a25c4e5e07a861ca591ce429341", size = 782056 },
+    { url = "https://files.pythonhosted.org/packages/95/30/1aa959ed0d25c1dd7dd5047ea8ba482ceaef38ce363c401fd32a6b923e60/regex-2026.2.28-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:10d28e19bd4888e4abf43bd3925f3c134c52fdf7259219003588a42e24c2aa25", size = 798743 },
+    { url = "https://files.pythonhosted.org/packages/3b/1f/dadb9cf359004784051c897dcf4d5d79895f73a1bbb7b827abaa4814ae80/regex-2026.2.28-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:99985a2c277dcb9ccb63f937451af5d65177af1efdeb8173ac55b61095a0a05c", size = 864633 },
+    { url = "https://files.pythonhosted.org/packages/a7/f1/b9a25eb24e1cf79890f09e6ec971ee5b511519f1851de3453bc04f6c902b/regex-2026.2.28-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:e1e7b24cb3ae9953a560c563045d1ba56ee4749fbd05cf21ba571069bd7be81b", size = 770862 },
+    { url = "https://files.pythonhosted.org/packages/02/9a/c5cb10b7aa6f182f9247a30cc9527e326601f46f4df864ac6db588d11fcd/regex-2026.2.28-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:d8511a01d0e4ee1992eb3ba19e09bc1866fe03f05129c3aec3fdc4cbc77aad3f", size = 854788 },
+    { url = "https://files.pythonhosted.org/packages/0a/50/414ba0731c4bd40b011fa4703b2cc86879ec060c64f2a906e65a56452589/regex-2026.2.28-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:aaffaecffcd2479ce87aa1e74076c221700b7c804e48e98e62500ee748f0f550", size = 800184 },
+    { url = "https://files.pythonhosted.org/packages/69/50/0c7290987f97e7e6830b0d853f69dc4dc5852c934aae63e7fdcd76b4c383/regex-2026.2.28-cp313-cp313t-win32.whl", hash = "sha256:ef77bdde9c9eba3f7fa5b58084b29bbcc74bcf55fdbeaa67c102a35b5bd7e7cc", size = 269137 },
+    { url = "https://files.pythonhosted.org/packages/68/80/ef26ff90e74ceb4051ad6efcbbb8a4be965184a57e879ebcbdef327d18fa/regex-2026.2.28-cp313-cp313t-win_amd64.whl", hash = "sha256:98adf340100cbe6fbaf8e6dc75e28f2c191b1be50ffefe292fb0e6f6eefdb0d8", size = 280682 },
+    { url = "https://files.pythonhosted.org/packages/69/8b/fbad9c52e83ffe8f97e3ed1aa0516e6dff6bb633a41da9e64645bc7efdc5/regex-2026.2.28-cp313-cp313t-win_arm64.whl", hash = "sha256:2fb950ac1d88e6b6a9414381f403797b236f9fa17e1eee07683af72b1634207b", size = 271735 },
+    { url = "https://files.pythonhosted.org/packages/cf/03/691015f7a7cb1ed6dacb2ea5de5682e4858e05a4c5506b2839cd533bbcd6/regex-2026.2.28-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:78454178c7df31372ea737996fb7f36b3c2c92cccc641d251e072478afb4babc", size = 489497 },
+    { url = "https://files.pythonhosted.org/packages/c6/ba/8db8fd19afcbfa0e1036eaa70c05f20ca8405817d4ad7a38a6b4c2f031ac/regex-2026.2.28-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:5d10303dd18cedfd4d095543998404df656088240bcfd3cd20a8f95b861f74bd", size = 291295 },
+    { url = "https://files.pythonhosted.org/packages/5a/79/9aa0caf089e8defef9b857b52fc53801f62ff868e19e5c83d4a96612eba1/regex-2026.2.28-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:19a9c9e0a8f24f39d575a6a854d516b48ffe4cbdcb9de55cb0570a032556ecff", size = 289275 },
+    { url = "https://files.pythonhosted.org/packages/eb/26/ee53117066a30ef9c883bf1127eece08308ccf8ccd45c45a966e7a665385/regex-2026.2.28-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:09500be324f49b470d907b3ef8af9afe857f5cca486f853853f7945ddbf75911", size = 797176 },
+    { url = "https://files.pythonhosted.org/packages/05/1b/67fb0495a97259925f343ae78b5d24d4a6624356ae138b57f18bd43006e4/regex-2026.2.28-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:fb1c4ff62277d87a7335f2c1ea4e0387b8f2b3ad88a64efd9943906aafad4f33", size = 863813 },
+    { url = "https://files.pythonhosted.org/packages/a0/1d/93ac9bbafc53618091c685c7ed40239a90bf9f2a82c983f0baa97cb7ae07/regex-2026.2.28-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b8b3f1be1738feadc69f62daa250c933e85c6f34fa378f54a7ff43807c1b9117", size = 908678 },
+    { url = "https://files.pythonhosted.org/packages/c7/7a/a8f5e0561702b25239846a16349feece59712ae20598ebb205580332a471/regex-2026.2.28-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:dc8ed8c3f41c27acb83f7b6a9eb727a73fc6663441890c5cb3426a5f6a91ce7d", size = 801528 },
+    { url = "https://files.pythonhosted.org/packages/96/5d/ed6d4cbde80309854b1b9f42d9062fee38ade15f7eb4909f6ef2440403b5/regex-2026.2.28-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fa539be029844c0ce1114762d2952ab6cfdd7c7c9bd72e0db26b94c3c36dcc5a", size = 775373 },
+    { url = "https://files.pythonhosted.org/packages/6a/e9/6e53c34e8068b9deec3e87210086ecb5b9efebdefca6b0d3fa43d66dcecb/regex-2026.2.28-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7900157786428a79615a8264dac1f12c9b02957c473c8110c6b1f972dcecaddf", size = 784859 },
+    { url = "https://files.pythonhosted.org/packages/48/3c/736e1c7ca7f0dcd2ae33819888fdc69058a349b7e5e84bc3e2f296bbf794/regex-2026.2.28-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:0b1d2b07614d95fa2bf8a63fd1e98bd8fa2b4848dc91b1efbc8ba219fdd73952", size = 857813 },
+    { url = "https://files.pythonhosted.org/packages/6e/7c/48c4659ad9da61f58e79dbe8c05223e0006696b603c16eb6b5cbfbb52c27/regex-2026.2.28-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:b389c61aa28a79c2e0527ac36da579869c2e235a5b208a12c5b5318cda2501d8", size = 763705 },
+    { url = "https://files.pythonhosted.org/packages/cf/a1/bc1c261789283128165f71b71b4b221dd1b79c77023752a6074c102f18d8/regex-2026.2.28-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:f467cb602f03fbd1ab1908f68b53c649ce393fde056628dc8c7e634dab6bfc07", size = 848734 },
+    { url = "https://files.pythonhosted.org/packages/10/d8/979407faf1397036e25a5ae778157366a911c0f382c62501009f4957cf86/regex-2026.2.28-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:e8c8cb2deba42f5ec1ede46374e990f8adc5e6456a57ac1a261b19be6f28e4e6", size = 789871 },
+    { url = "https://files.pythonhosted.org/packages/03/23/da716821277115fcb1f4e3de1e5dc5023a1e6533598c486abf5448612579/regex-2026.2.28-cp314-cp314-win32.whl", hash = "sha256:9036b400b20e4858d56d117108d7813ed07bb7803e3eed766675862131135ca6", size = 271825 },
+    { url = "https://files.pythonhosted.org/packages/91/ff/90696f535d978d5f16a52a419be2770a8d8a0e7e0cfecdbfc31313df7fab/regex-2026.2.28-cp314-cp314-win_amd64.whl", hash = "sha256:1d367257cd86c1cbb97ea94e77b373a0bbc2224976e247f173d19e8f18b4afa7", size = 280548 },
+    { url = "https://files.pythonhosted.org/packages/69/f9/5e1b5652fc0af3fcdf7677e7df3ad2a0d47d669b34ac29a63bb177bb731b/regex-2026.2.28-cp314-cp314-win_arm64.whl", hash = "sha256:5e68192bb3a1d6fb2836da24aa494e413ea65853a21505e142e5b1064a595f3d", size = 273444 },
+    { url = "https://files.pythonhosted.org/packages/d3/eb/8389f9e940ac89bcf58d185e230a677b4fd07c5f9b917603ad5c0f8fa8fe/regex-2026.2.28-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:a5dac14d0872eeb35260a8e30bac07ddf22adc1e3a0635b52b02e180d17c9c7e", size = 492546 },
+    { url = "https://files.pythonhosted.org/packages/7b/c7/09441d27ce2a6fa6a61ea3150ea4639c1dcda9b31b2ea07b80d6937b24dd/regex-2026.2.28-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:ec0c608b7a7465ffadb344ed7c987ff2f11ee03f6a130b569aa74d8a70e8333c", size = 292986 },
+    { url = "https://files.pythonhosted.org/packages/fb/69/4144b60ed7760a6bd235e4087041f487aa4aa62b45618ce018b0c14833ea/regex-2026.2.28-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c7815afb0ca45456613fdaf60ea9c993715511c8d53a83bc468305cbc0ee23c7", size = 291518 },
+    { url = "https://files.pythonhosted.org/packages/2d/be/77e5426cf5948c82f98c53582009ca9e94938c71f73a8918474f2e2990bb/regex-2026.2.28-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b059e71ec363968671693a78c5053bd9cb2fe410f9b8e4657e88377ebd603a2e", size = 809464 },
+    { url = "https://files.pythonhosted.org/packages/45/99/2c8c5ac90dc7d05c6e7d8e72c6a3599dc08cd577ac476898e91ca787d7f1/regex-2026.2.28-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:b8cf76f1a29f0e99dcfd7aef1551a9827588aae5a737fe31442021165f1920dc", size = 869553 },
+    { url = "https://files.pythonhosted.org/packages/53/34/daa66a342f0271e7737003abf6c3097aa0498d58c668dbd88362ef94eb5d/regex-2026.2.28-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:180e08a435a0319e6a4821c3468da18dc7001987e1c17ae1335488dfe7518dd8", size = 915289 },
+    { url = "https://files.pythonhosted.org/packages/c5/c7/e22c2aaf0a12e7e22ab19b004bb78d32ca1ecc7ef245949935463c5567de/regex-2026.2.28-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1e496956106fd59ba6322a8ea17141a27c5040e5ee8f9433ae92d4e5204462a0", size = 812156 },
+    { url = "https://files.pythonhosted.org/packages/7f/bb/2dc18c1efd9051cf389cd0d7a3a4d90f6804b9fff3a51b5dc3c85b935f71/regex-2026.2.28-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:bba2b18d70eeb7b79950f12f633beeecd923f7c9ad6f6bae28e59b4cb3ab046b", size = 782215 },
+    { url = "https://files.pythonhosted.org/packages/17/1e/9e4ec9b9013931faa32226ec4aa3c71fe664a6d8a2b91ac56442128b332f/regex-2026.2.28-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6db7bfae0f8a2793ff1f7021468ea55e2699d0790eb58ee6ab36ae43aa00bc5b", size = 798925 },
+    { url = "https://files.pythonhosted.org/packages/71/57/a505927e449a9ccb41e2cc8d735e2abe3444b0213d1cf9cb364a8c1f2524/regex-2026.2.28-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:d0b02e8b7e5874b48ae0f077ecca61c1a6a9f9895e9c6dfb191b55b242862033", size = 864701 },
+    { url = "https://files.pythonhosted.org/packages/a6/ad/c62cb60cdd93e13eac5b3d9d6bd5d284225ed0e3329426f94d2552dd7cca/regex-2026.2.28-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:25b6eb660c5cf4b8c3407a1ed462abba26a926cc9965e164268a3267bcc06a43", size = 770899 },
+    { url = "https://files.pythonhosted.org/packages/3c/5a/874f861f5c3d5ab99633e8030dee1bc113db8e0be299d1f4b07f5b5ec349/regex-2026.2.28-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:5a932ea8ad5d0430351ff9c76c8db34db0d9f53c1d78f06022a21f4e290c5c18", size = 854727 },
+    { url = "https://files.pythonhosted.org/packages/6b/ca/d2c03b0efde47e13db895b975b2be6a73ed90b8ba963677927283d43bf74/regex-2026.2.28-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:1c2c95e1a2b0f89d01e821ff4de1be4b5d73d1f4b0bf679fa27c1ad8d2327f1a", size = 800366 },
+    { url = "https://files.pythonhosted.org/packages/14/bd/ee13b20b763b8989f7c75d592bfd5de37dc1181814a2a2747fedcf97e3ba/regex-2026.2.28-cp314-cp314t-win32.whl", hash = "sha256:bbb882061f742eb5d46f2f1bd5304055be0a66b783576de3d7eef1bed4778a6e", size = 274936 },
+    { url = "https://files.pythonhosted.org/packages/cb/e7/d8020e39414c93af7f0d8688eabcecece44abfd5ce314b21dfda0eebd3d8/regex-2026.2.28-cp314-cp314t-win_amd64.whl", hash = "sha256:6591f281cb44dc13de9585b552cec6fc6cf47fb2fe7a48892295ee9bc4a612f9", size = 284779 },
+    { url = "https://files.pythonhosted.org/packages/13/c0/ad225f4a405827486f1955283407cf758b6d2fb966712644c5f5aef33d1b/regex-2026.2.28-cp314-cp314t-win_arm64.whl", hash = "sha256:dee50f1be42222f89767b64b283283ef963189da0dda4a515aa54a5563c62dec", size = 275010 },
+]
+
 [[package]]
 name = "requests"
 version = "2.32.4"
@@ -2054,6 +2484,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/82/95/38ef0cd7fa11eaba6a99b3c4f5ac948d8bc6ff199aabd327a29cc000840c/starlette-0.47.1-py3-none-any.whl", hash = "sha256:5e11c9f5c7c3f24959edbf2dffdc01bba860228acf657129467d8a7468591527", size = 72747 },
 ]
 
+[[package]]
+name = "tenacity"
+version = "9.1.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/47/c6/ee486fd809e357697ee8a44d3d69222b344920433d3b6666ccd9b374630c/tenacity-9.1.4.tar.gz", hash = "sha256:adb31d4c263f2bd041081ab33b498309a57c77f9acf2db65aadf0898179cf93a", size = 49413 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d7/c1/eb8f9debc45d3b7918a32ab756658a0904732f75e555402972246b0b8e71/tenacity-9.1.4-py3-none-any.whl", hash = "sha256:6095a360c919085f28c6527de529e76a06ad89b23659fa881ae0649b867a9d55", size = 28926 },
+]
+
 [[package]]
 name = "terminusdb-client"
 version = "10.2.6"
@@ -2082,6 +2521,53 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a6/a5/c0b6468d3824fe3fde30dbb5e1f687b291608f9473681bbf7dabbf5a87d7/text_unidecode-1.3-py2.py3-none-any.whl", hash = "sha256:1311f10e8b895935241623731c2ba64f4c455287888b18189350b67134a822e8", size = 78154 },
 ]
 
+[[package]]
+name = "tiktoken"
+version = "0.12.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "regex" },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7d/ab/4d017d0f76ec3171d469d80fc03dfbb4e48a4bcaddaa831b31d526f05edc/tiktoken-0.12.0.tar.gz", hash = "sha256:b18ba7ee2b093863978fcb14f74b3707cdc8d4d4d3836853ce7ec60772139931", size = 37806 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a4/85/be65d39d6b647c79800fd9d29241d081d4eeb06271f383bb87200d74cf76/tiktoken-0.12.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:b97f74aca0d78a1ff21b8cd9e9925714c15a9236d6ceacf5c7327c117e6e21e8", size = 1050728 },
+    { url = "https://files.pythonhosted.org/packages/4a/42/6573e9129bc55c9bf7300b3a35bef2c6b9117018acca0dc760ac2d93dffe/tiktoken-0.12.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:2b90f5ad190a4bb7c3eb30c5fa32e1e182ca1ca79f05e49b448438c3e225a49b", size = 994049 },
+    { url = "https://files.pythonhosted.org/packages/66/c5/ed88504d2f4a5fd6856990b230b56d85a777feab84e6129af0822f5d0f70/tiktoken-0.12.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:65b26c7a780e2139e73acc193e5c63ac754021f160df919add909c1492c0fb37", size = 1129008 },
+    { url = "https://files.pythonhosted.org/packages/f4/90/3dae6cc5436137ebd38944d396b5849e167896fc2073da643a49f372dc4f/tiktoken-0.12.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:edde1ec917dfd21c1f2f8046b86348b0f54a2c0547f68149d8600859598769ad", size = 1152665 },
+    { url = "https://files.pythonhosted.org/packages/a3/fe/26df24ce53ffde419a42f5f53d755b995c9318908288c17ec3f3448313a3/tiktoken-0.12.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:35a2f8ddd3824608b3d650a000c1ef71f730d0c56486845705a8248da00f9fe5", size = 1194230 },
+    { url = "https://files.pythonhosted.org/packages/20/cc/b064cae1a0e9fac84b0d2c46b89f4e57051a5f41324e385d10225a984c24/tiktoken-0.12.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:83d16643edb7fa2c99eff2ab7733508aae1eebb03d5dfc46f5565862810f24e3", size = 1254688 },
+    { url = "https://files.pythonhosted.org/packages/81/10/b8523105c590c5b8349f2587e2fdfe51a69544bd5a76295fc20f2374f470/tiktoken-0.12.0-cp312-cp312-win_amd64.whl", hash = "sha256:ffc5288f34a8bc02e1ea7047b8d041104791d2ddbf42d1e5fa07822cbffe16bd", size = 878694 },
+    { url = "https://files.pythonhosted.org/packages/00/61/441588ee21e6b5cdf59d6870f86beb9789e532ee9718c251b391b70c68d6/tiktoken-0.12.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:775c2c55de2310cc1bc9a3ad8826761cbdc87770e586fd7b6da7d4589e13dab3", size = 1050802 },
+    { url = "https://files.pythonhosted.org/packages/1f/05/dcf94486d5c5c8d34496abe271ac76c5b785507c8eae71b3708f1ad9b45a/tiktoken-0.12.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a01b12f69052fbe4b080a2cfb867c4de12c704b56178edf1d1d7b273561db160", size = 993995 },
+    { url = "https://files.pythonhosted.org/packages/a0/70/5163fe5359b943f8db9946b62f19be2305de8c3d78a16f629d4165e2f40e/tiktoken-0.12.0-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:01d99484dc93b129cd0964f9d34eee953f2737301f18b3c7257bf368d7615baa", size = 1128948 },
+    { url = "https://files.pythonhosted.org/packages/0c/da/c028aa0babf77315e1cef357d4d768800c5f8a6de04d0eac0f377cb619fa/tiktoken-0.12.0-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:4a1a4fcd021f022bfc81904a911d3df0f6543b9e7627b51411da75ff2fe7a1be", size = 1151986 },
+    { url = "https://files.pythonhosted.org/packages/a0/5a/886b108b766aa53e295f7216b509be95eb7d60b166049ce2c58416b25f2a/tiktoken-0.12.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:981a81e39812d57031efdc9ec59fa32b2a5a5524d20d4776574c4b4bd2e9014a", size = 1194222 },
+    { url = "https://files.pythonhosted.org/packages/f4/f8/4db272048397636ac7a078d22773dd2795b1becee7bc4922fe6207288d57/tiktoken-0.12.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9baf52f84a3f42eef3ff4e754a0db79a13a27921b457ca9832cf944c6be4f8f3", size = 1255097 },
+    { url = "https://files.pythonhosted.org/packages/8e/32/45d02e2e0ea2be3a9ed22afc47d93741247e75018aac967b713b2941f8ea/tiktoken-0.12.0-cp313-cp313-win_amd64.whl", hash = "sha256:b8a0cd0c789a61f31bf44851defbd609e8dd1e2c8589c614cc1060940ef1f697", size = 879117 },
+    { url = "https://files.pythonhosted.org/packages/ce/76/994fc868f88e016e6d05b0da5ac24582a14c47893f4474c3e9744283f1d5/tiktoken-0.12.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:d5f89ea5680066b68bcb797ae85219c72916c922ef0fcdd3480c7d2315ffff16", size = 1050309 },
+    { url = "https://files.pythonhosted.org/packages/f6/b8/57ef1456504c43a849821920d582a738a461b76a047f352f18c0b26c6516/tiktoken-0.12.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:b4e7ed1c6a7a8a60a3230965bdedba8cc58f68926b835e519341413370e0399a", size = 993712 },
+    { url = "https://files.pythonhosted.org/packages/72/90/13da56f664286ffbae9dbcfadcc625439142675845baa62715e49b87b68b/tiktoken-0.12.0-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:fc530a28591a2d74bce821d10b418b26a094bf33839e69042a6e86ddb7a7fb27", size = 1128725 },
+    { url = "https://files.pythonhosted.org/packages/05/df/4f80030d44682235bdaecd7346c90f67ae87ec8f3df4a3442cb53834f7e4/tiktoken-0.12.0-cp313-cp313t-manylinux_2_28_x86_64.whl", hash = "sha256:06a9f4f49884139013b138920a4c393aa6556b2f8f536345f11819389c703ebb", size = 1151875 },
+    { url = "https://files.pythonhosted.org/packages/22/1f/ae535223a8c4ef4c0c1192e3f9b82da660be9eb66b9279e95c99288e9dab/tiktoken-0.12.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:04f0e6a985d95913cabc96a741c5ffec525a2c72e9df086ff17ebe35985c800e", size = 1194451 },
+    { url = "https://files.pythonhosted.org/packages/78/a7/f8ead382fce0243cb625c4f266e66c27f65ae65ee9e77f59ea1653b6d730/tiktoken-0.12.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:0ee8f9ae00c41770b5f9b0bb1235474768884ae157de3beb5439ca0fd70f3e25", size = 1253794 },
+    { url = "https://files.pythonhosted.org/packages/93/e0/6cc82a562bc6365785a3ff0af27a2a092d57c47d7a81d9e2295d8c36f011/tiktoken-0.12.0-cp313-cp313t-win_amd64.whl", hash = "sha256:dc2dd125a62cb2b3d858484d6c614d136b5b848976794edfb63688d539b8b93f", size = 878777 },
+    { url = "https://files.pythonhosted.org/packages/72/05/3abc1db5d2c9aadc4d2c76fa5640134e475e58d9fbb82b5c535dc0de9b01/tiktoken-0.12.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:a90388128df3b3abeb2bfd1895b0681412a8d7dc644142519e6f0a97c2111646", size = 1050188 },
+    { url = "https://files.pythonhosted.org/packages/e3/7b/50c2f060412202d6c95f32b20755c7a6273543b125c0985d6fa9465105af/tiktoken-0.12.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:da900aa0ad52247d8794e307d6446bd3cdea8e192769b56276695d34d2c9aa88", size = 993978 },
+    { url = "https://files.pythonhosted.org/packages/14/27/bf795595a2b897e271771cd31cb847d479073497344c637966bdf2853da1/tiktoken-0.12.0-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:285ba9d73ea0d6171e7f9407039a290ca77efcdb026be7769dccc01d2c8d7fff", size = 1129271 },
+    { url = "https://files.pythonhosted.org/packages/f5/de/9341a6d7a8f1b448573bbf3425fa57669ac58258a667eb48a25dfe916d70/tiktoken-0.12.0-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:d186a5c60c6a0213f04a7a802264083dea1bbde92a2d4c7069e1a56630aef830", size = 1151216 },
+    { url = "https://files.pythonhosted.org/packages/75/0d/881866647b8d1be4d67cb24e50d0c26f9f807f994aa1510cb9ba2fe5f612/tiktoken-0.12.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:604831189bd05480f2b885ecd2d1986dc7686f609de48208ebbbddeea071fc0b", size = 1194860 },
+    { url = "https://files.pythonhosted.org/packages/b3/1e/b651ec3059474dab649b8d5b69f5c65cd8fcd8918568c1935bd4136c9392/tiktoken-0.12.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:8f317e8530bb3a222547b85a58583238c8f74fd7a7408305f9f63246d1a0958b", size = 1254567 },
+    { url = "https://files.pythonhosted.org/packages/80/57/ce64fd16ac390fafde001268c364d559447ba09b509181b2808622420eec/tiktoken-0.12.0-cp314-cp314-win_amd64.whl", hash = "sha256:399c3dd672a6406719d84442299a490420b458c44d3ae65516302a99675888f3", size = 921067 },
+    { url = "https://files.pythonhosted.org/packages/ac/a4/72eed53e8976a099539cdd5eb36f241987212c29629d0a52c305173e0a68/tiktoken-0.12.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:c2c714c72bc00a38ca969dae79e8266ddec999c7ceccd603cc4f0d04ccd76365", size = 1050473 },
+    { url = "https://files.pythonhosted.org/packages/e6/d7/0110b8f54c008466b19672c615f2168896b83706a6611ba6e47313dbc6e9/tiktoken-0.12.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:cbb9a3ba275165a2cb0f9a83f5d7025afe6b9d0ab01a22b50f0e74fee2ad253e", size = 993855 },
+    { url = "https://files.pythonhosted.org/packages/5f/77/4f268c41a3957c418b084dd576ea2fad2e95da0d8e1ab705372892c2ca22/tiktoken-0.12.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:dfdfaa5ffff8993a3af94d1125870b1d27aed7cb97aa7eb8c1cefdbc87dbee63", size = 1129022 },
+    { url = "https://files.pythonhosted.org/packages/4e/2b/fc46c90fe5028bd094cd6ee25a7db321cb91d45dc87531e2bdbb26b4867a/tiktoken-0.12.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:584c3ad3d0c74f5269906eb8a659c8bfc6144a52895d9261cdaf90a0ae5f4de0", size = 1150736 },
+    { url = "https://files.pythonhosted.org/packages/28/c0/3c7a39ff68022ddfd7d93f3337ad90389a342f761c4d71de99a3ccc57857/tiktoken-0.12.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:54c891b416a0e36b8e2045b12b33dd66fb34a4fe7965565f1b482da50da3e86a", size = 1194908 },
+    { url = "https://files.pythonhosted.org/packages/ab/0d/c1ad6f4016a3968c048545f5d9b8ffebf577774b2ede3e2e352553b685fe/tiktoken-0.12.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5edb8743b88d5be814b1a8a8854494719080c28faaa1ccbef02e87354fe71ef0", size = 1253706 },
+    { url = "https://files.pythonhosted.org/packages/af/df/c7891ef9d2712ad774777271d39fdef63941ffba0a9d59b7ad1fd2765e57/tiktoken-0.12.0-cp314-cp314t-win_amd64.whl", hash = "sha256:f61c0aea5565ac82e2ec50a05e02a6c44734e91b51c10510b084ea1b8e633a71", size = 920667 },
+]
+
 [[package]]
 name = "tokenize-rt"
 version = "6.2.0"
@@ -2177,6 +2663,28 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a7/c2/fe1e52489ae3122415c51f387e221dd0773709bad6c6cdaa599e8a2c5185/urllib3-2.5.0-py3-none-any.whl", hash = "sha256:e6b01673c0fa6a13e374b50871808eb3bf7046c4b125b216f6bf1cc604cff0dc", size = 129795 },
 ]
 
+[[package]]
+name = "uuid-utils"
+version = "0.14.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7b/d1/38a573f0c631c062cf42fa1f5d021d4dd3c31fb23e4376e4b56b0c9fbbed/uuid_utils-0.14.1.tar.gz", hash = "sha256:9bfc95f64af80ccf129c604fb6b8ca66c6f256451e32bc4570f760e4309c9b69", size = 22195 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/43/b7/add4363039a34506a58457d96d4aa2126061df3a143eb4d042aedd6a2e76/uuid_utils-0.14.1-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:93a3b5dc798a54a1feb693f2d1cb4cf08258c32ff05ae4929b5f0a2ca624a4f0", size = 604679 },
+    { url = "https://files.pythonhosted.org/packages/dd/84/d1d0bef50d9e66d31b2019997c741b42274d53dde2e001b7a83e9511c339/uuid_utils-0.14.1-cp39-abi3-macosx_10_12_x86_64.whl", hash = "sha256:ccd65a4b8e83af23eae5e56d88034b2fe7264f465d3e830845f10d1591b81741", size = 309346 },
+    { url = "https://files.pythonhosted.org/packages/ef/ed/b6d6fd52a6636d7c3eddf97d68da50910bf17cd5ac221992506fb56cf12e/uuid_utils-0.14.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b56b0cacd81583834820588378e432b0696186683b813058b707aedc1e16c4b1", size = 344714 },
+    { url = "https://files.pythonhosted.org/packages/a8/a7/a19a1719fb626fe0b31882db36056d44fe904dc0cf15b06fdf56b2679cf7/uuid_utils-0.14.1-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bb3cf14de789097320a3c56bfdfdd51b1225d11d67298afbedee7e84e3837c96", size = 350914 },
+    { url = "https://files.pythonhosted.org/packages/1d/fc/f6690e667fdc3bb1a73f57951f97497771c56fe23e3d302d7404be394d4f/uuid_utils-0.14.1-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:60e0854a90d67f4b0cc6e54773deb8be618f4c9bad98d3326f081423b5d14fae", size = 482609 },
+    { url = "https://files.pythonhosted.org/packages/54/6e/dcd3fa031320921a12ec7b4672dea3bd1dd90ddffa363a91831ba834d559/uuid_utils-0.14.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ce6743ba194de3910b5feb1a62590cd2587e33a73ab6af8a01b642ceb5055862", size = 345699 },
+    { url = "https://files.pythonhosted.org/packages/04/28/e5220204b58b44ac0047226a9d016a113fde039280cc8732d9e6da43b39f/uuid_utils-0.14.1-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:043fb58fde6cf1620a6c066382f04f87a8e74feb0f95a585e4ed46f5d44af57b", size = 372205 },
+    { url = "https://files.pythonhosted.org/packages/c7/d9/3d2eb98af94b8dfffc82b6a33b4dfc87b0a5de2c68a28f6dde0db1f8681b/uuid_utils-0.14.1-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:c915d53f22945e55fe0d3d3b0b87fd965a57f5fd15666fd92d6593a73b1dd297", size = 521836 },
+    { url = "https://files.pythonhosted.org/packages/a8/15/0eb106cc6fe182f7577bc0ab6e2f0a40be247f35c5e297dbf7bbc460bd02/uuid_utils-0.14.1-cp39-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:0972488e3f9b449e83f006ead5a0e0a33ad4a13e4462e865b7c286ab7d7566a3", size = 625260 },
+    { url = "https://files.pythonhosted.org/packages/3c/17/f539507091334b109e7496830af2f093d9fc8082411eafd3ece58af1f8ba/uuid_utils-0.14.1-cp39-abi3-musllinux_1_2_i686.whl", hash = "sha256:1c238812ae0c8ffe77d8d447a32c6dfd058ea4631246b08b5a71df586ff08531", size = 587824 },
+    { url = "https://files.pythonhosted.org/packages/2e/c2/d37a7b2e41f153519367d4db01f0526e0d4b06f1a4a87f1c5dfca5d70a8b/uuid_utils-0.14.1-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:bec8f8ef627af86abf8298e7ec50926627e29b34fa907fcfbedb45aaa72bca43", size = 551407 },
+    { url = "https://files.pythonhosted.org/packages/65/36/2d24b2cbe78547c6532da33fb8613debd3126eccc33a6374ab788f5e46e9/uuid_utils-0.14.1-cp39-abi3-win32.whl", hash = "sha256:b54d6aa6252d96bac1fdbc80d26ba71bad9f220b2724d692ad2f2310c22ef523", size = 183476 },
+    { url = "https://files.pythonhosted.org/packages/83/92/2d7e90df8b1a69ec4cff33243ce02b7a62f926ef9e2f0eca5a026889cd73/uuid_utils-0.14.1-cp39-abi3-win_amd64.whl", hash = "sha256:fc27638c2ce267a0ce3e06828aff786f91367f093c80625ee21dad0208e0f5ba", size = 187147 },
+    { url = "https://files.pythonhosted.org/packages/d9/26/529f4beee17e5248e37e0bc17a2761d34c0fa3b1e5729c88adb2065bae6e/uuid_utils-0.14.1-cp39-abi3-win_arm64.whl", hash = "sha256:b04cb49b42afbc4ff8dbc60cf054930afc479d6f4dd7f1ec3bbe5dbfdde06b7a", size = 188132 },
+]
+
 [[package]]
 name = "uvicorn"
 version = "0.35.0"
@@ -2266,6 +2774,89 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a4/f5/10b68b7b1544245097b2a1b8238f66f2fc6dcaeb24ba5d917f52bd2eed4f/wsproto-1.3.2-py3-none-any.whl", hash = "sha256:61eea322cdf56e8cc904bd3ad7573359a242ba65688716b0710a5eb12beab584", size = 24405 },
 ]
 
+[[package]]
+name = "xxhash"
+version = "3.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/02/84/30869e01909fb37a6cc7e18688ee8bf1e42d57e7e0777636bd47524c43c7/xxhash-3.6.0.tar.gz", hash = "sha256:f0162a78b13a0d7617b2845b90c763339d1f1d82bb04a4b07f4ab535cc5e05d6", size = 85160 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/07/d9412f3d7d462347e4511181dea65e47e0d0e16e26fbee2ea86a2aefb657/xxhash-3.6.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:01362c4331775398e7bb34e3ab403bc9ee9f7c497bc7dee6272114055277dd3c", size = 32744 },
+    { url = "https://files.pythonhosted.org/packages/79/35/0429ee11d035fc33abe32dca1b2b69e8c18d236547b9a9b72c1929189b9a/xxhash-3.6.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b7b2df81a23f8cb99656378e72501b2cb41b1827c0f5a86f87d6b06b69f9f204", size = 30816 },
+    { url = "https://files.pythonhosted.org/packages/b7/f2/57eb99aa0f7d98624c0932c5b9a170e1806406cdbcdb510546634a1359e0/xxhash-3.6.0-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:dc94790144e66b14f67b10ac8ed75b39ca47536bf8800eb7c24b50271ea0c490", size = 194035 },
+    { url = "https://files.pythonhosted.org/packages/4c/ed/6224ba353690d73af7a3f1c7cdb1fc1b002e38f783cb991ae338e1eb3d79/xxhash-3.6.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:93f107c673bccf0d592cdba077dedaf52fe7f42dcd7676eba1f6d6f0c3efffd2", size = 212914 },
+    { url = "https://files.pythonhosted.org/packages/38/86/fb6b6130d8dd6b8942cc17ab4d90e223653a89aa32ad2776f8af7064ed13/xxhash-3.6.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2aa5ee3444c25b69813663c9f8067dcfaa2e126dc55e8dddf40f4d1c25d7effa", size = 212163 },
+    { url = "https://files.pythonhosted.org/packages/ee/dc/e84875682b0593e884ad73b2d40767b5790d417bde603cceb6878901d647/xxhash-3.6.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f7f99123f0e1194fa59cc69ad46dbae2e07becec5df50a0509a808f90a0f03f0", size = 445411 },
+    { url = "https://files.pythonhosted.org/packages/11/4f/426f91b96701ec2f37bb2b8cec664eff4f658a11f3fa9d94f0a887ea6d2b/xxhash-3.6.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:49e03e6fe2cac4a1bc64952dd250cf0dbc5ef4ebb7b8d96bce82e2de163c82a2", size = 193883 },
+    { url = "https://files.pythonhosted.org/packages/53/5a/ddbb83eee8e28b778eacfc5a85c969673e4023cdeedcfcef61f36731610b/xxhash-3.6.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:bd17fede52a17a4f9a7bc4472a5867cb0b160deeb431795c0e4abe158bc784e9", size = 210392 },
+    { url = "https://files.pythonhosted.org/packages/1e/c2/ff69efd07c8c074ccdf0a4f36fcdd3d27363665bcdf4ba399abebe643465/xxhash-3.6.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:6fb5f5476bef678f69db04f2bd1efbed3030d2aba305b0fc1773645f187d6a4e", size = 197898 },
+    { url = "https://files.pythonhosted.org/packages/58/ca/faa05ac19b3b622c7c9317ac3e23954187516298a091eb02c976d0d3dd45/xxhash-3.6.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:843b52f6d88071f87eba1631b684fcb4b2068cd2180a0224122fe4ef011a9374", size = 210655 },
+    { url = "https://files.pythonhosted.org/packages/d4/7a/06aa7482345480cc0cb597f5c875b11a82c3953f534394f620b0be2f700c/xxhash-3.6.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:7d14a6cfaf03b1b6f5f9790f76880601ccc7896aff7ab9cd8978a939c1eb7e0d", size = 414001 },
+    { url = "https://files.pythonhosted.org/packages/23/07/63ffb386cd47029aa2916b3d2f454e6cc5b9f5c5ada3790377d5430084e7/xxhash-3.6.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:418daf3db71e1413cfe211c2f9a528456936645c17f46b5204705581a45390ae", size = 191431 },
+    { url = "https://files.pythonhosted.org/packages/0f/93/14fde614cadb4ddf5e7cebf8918b7e8fac5ae7861c1875964f17e678205c/xxhash-3.6.0-cp312-cp312-win32.whl", hash = "sha256:50fc255f39428a27299c20e280d6193d8b63b8ef8028995323bf834a026b4fbb", size = 30617 },
+    { url = "https://files.pythonhosted.org/packages/13/5d/0d125536cbe7565a83d06e43783389ecae0c0f2ed037b48ede185de477c0/xxhash-3.6.0-cp312-cp312-win_amd64.whl", hash = "sha256:c0f2ab8c715630565ab8991b536ecded9416d615538be8ecddce43ccf26cbc7c", size = 31534 },
+    { url = "https://files.pythonhosted.org/packages/54/85/6ec269b0952ec7e36ba019125982cf11d91256a778c7c3f98a4c5043d283/xxhash-3.6.0-cp312-cp312-win_arm64.whl", hash = "sha256:eae5c13f3bc455a3bbb68bdc513912dc7356de7e2280363ea235f71f54064829", size = 27876 },
+    { url = "https://files.pythonhosted.org/packages/33/76/35d05267ac82f53ae9b0e554da7c5e281ee61f3cad44c743f0fcd354f211/xxhash-3.6.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:599e64ba7f67472481ceb6ee80fa3bd828fd61ba59fb11475572cc5ee52b89ec", size = 32738 },
+    { url = "https://files.pythonhosted.org/packages/31/a8/3fbce1cd96534a95e35d5120637bf29b0d7f5d8fa2f6374e31b4156dd419/xxhash-3.6.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:7d8b8aaa30fca4f16f0c84a5c8d7ddee0e25250ec2796c973775373257dde8f1", size = 30821 },
+    { url = "https://files.pythonhosted.org/packages/0c/ea/d387530ca7ecfa183cb358027f1833297c6ac6098223fd14f9782cd0015c/xxhash-3.6.0-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:d597acf8506d6e7101a4a44a5e428977a51c0fadbbfd3c39650cca9253f6e5a6", size = 194127 },
+    { url = "https://files.pythonhosted.org/packages/ba/0c/71435dcb99874b09a43b8d7c54071e600a7481e42b3e3ce1eb5226a5711a/xxhash-3.6.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:858dc935963a33bc33490128edc1c12b0c14d9c7ebaa4e387a7869ecc4f3e263", size = 212975 },
+    { url = "https://files.pythonhosted.org/packages/84/7a/c2b3d071e4bb4a90b7057228a99b10d51744878f4a8a6dd643c8bd897620/xxhash-3.6.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ba284920194615cb8edf73bf52236ce2e1664ccd4a38fdb543506413529cc546", size = 212241 },
+    { url = "https://files.pythonhosted.org/packages/81/5f/640b6eac0128e215f177df99eadcd0f1b7c42c274ab6a394a05059694c5a/xxhash-3.6.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:4b54219177f6c6674d5378bd862c6aedf64725f70dd29c472eaae154df1a2e89", size = 445471 },
+    { url = "https://files.pythonhosted.org/packages/5e/1e/3c3d3ef071b051cc3abbe3721ffb8365033a172613c04af2da89d5548a87/xxhash-3.6.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:42c36dd7dbad2f5238950c377fcbf6811b1cdb1c444fab447960030cea60504d", size = 193936 },
+    { url = "https://files.pythonhosted.org/packages/2c/bd/4a5f68381939219abfe1c22a9e3a5854a4f6f6f3c4983a87d255f21f2e5d/xxhash-3.6.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f22927652cba98c44639ffdc7aaf35828dccf679b10b31c4ad72a5b530a18eb7", size = 210440 },
+    { url = "https://files.pythonhosted.org/packages/eb/37/b80fe3d5cfb9faff01a02121a0f4d565eb7237e9e5fc66e73017e74dcd36/xxhash-3.6.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:b45fad44d9c5c119e9c6fbf2e1c656a46dc68e280275007bbfd3d572b21426db", size = 197990 },
+    { url = "https://files.pythonhosted.org/packages/d7/fd/2c0a00c97b9e18f72e1f240ad4e8f8a90fd9d408289ba9c7c495ed7dc05c/xxhash-3.6.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:6f2580ffab1a8b68ef2b901cde7e55fa8da5e4be0977c68f78fc80f3c143de42", size = 210689 },
+    { url = "https://files.pythonhosted.org/packages/93/86/5dd8076a926b9a95db3206aba20d89a7fc14dd5aac16e5c4de4b56033140/xxhash-3.6.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:40c391dd3cd041ebc3ffe6f2c862f402e306eb571422e0aa918d8070ba31da11", size = 414068 },
+    { url = "https://files.pythonhosted.org/packages/af/3c/0bb129170ee8f3650f08e993baee550a09593462a5cddd8e44d0011102b1/xxhash-3.6.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:f205badabde7aafd1a31e8ca2a3e5a763107a71c397c4481d6a804eb5063d8bd", size = 191495 },
+    { url = "https://files.pythonhosted.org/packages/e9/3a/6797e0114c21d1725e2577508e24006fd7ff1d8c0c502d3b52e45c1771d8/xxhash-3.6.0-cp313-cp313-win32.whl", hash = "sha256:2577b276e060b73b73a53042ea5bd5203d3e6347ce0d09f98500f418a9fcf799", size = 30620 },
+    { url = "https://files.pythonhosted.org/packages/86/15/9bc32671e9a38b413a76d24722a2bf8784a132c043063a8f5152d390b0f9/xxhash-3.6.0-cp313-cp313-win_amd64.whl", hash = "sha256:757320d45d2fbcce8f30c42a6b2f47862967aea7bf458b9625b4bbe7ee390392", size = 31542 },
+    { url = "https://files.pythonhosted.org/packages/39/c5/cc01e4f6188656e56112d6a8e0dfe298a16934b8c47a247236549a3f7695/xxhash-3.6.0-cp313-cp313-win_arm64.whl", hash = "sha256:457b8f85dec5825eed7b69c11ae86834a018b8e3df5e77783c999663da2f96d6", size = 27880 },
+    { url = "https://files.pythonhosted.org/packages/f3/30/25e5321c8732759e930c555176d37e24ab84365482d257c3b16362235212/xxhash-3.6.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:a42e633d75cdad6d625434e3468126c73f13f7584545a9cf34e883aa1710e702", size = 32956 },
+    { url = "https://files.pythonhosted.org/packages/9f/3c/0573299560d7d9f8ab1838f1efc021a280b5ae5ae2e849034ef3dee18810/xxhash-3.6.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:568a6d743219e717b07b4e03b0a828ce593833e498c3b64752e0f5df6bfe84db", size = 31072 },
+    { url = "https://files.pythonhosted.org/packages/7a/1c/52d83a06e417cd9d4137722693424885cc9878249beb3a7c829e74bf7ce9/xxhash-3.6.0-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:bec91b562d8012dae276af8025a55811b875baace6af510412a5e58e3121bc54", size = 196409 },
+    { url = "https://files.pythonhosted.org/packages/e3/8e/c6d158d12a79bbd0b878f8355432075fc82759e356ab5a111463422a239b/xxhash-3.6.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:78e7f2f4c521c30ad5e786fdd6bae89d47a32672a80195467b5de0480aa97b1f", size = 215736 },
+    { url = "https://files.pythonhosted.org/packages/bc/68/c4c80614716345d55071a396cf03d06e34b5f4917a467faf43083c995155/xxhash-3.6.0-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:3ed0df1b11a79856df5ffcab572cbd6b9627034c1c748c5566fa79df9048a7c5", size = 214833 },
+    { url = "https://files.pythonhosted.org/packages/7e/e9/ae27c8ffec8b953efa84c7c4a6c6802c263d587b9fc0d6e7cea64e08c3af/xxhash-3.6.0-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:0e4edbfc7d420925b0dd5e792478ed393d6e75ff8fc219a6546fb446b6a417b1", size = 448348 },
+    { url = "https://files.pythonhosted.org/packages/d7/6b/33e21afb1b5b3f46b74b6bd1913639066af218d704cc0941404ca717fc57/xxhash-3.6.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fba27a198363a7ef87f8c0f6b171ec36b674fe9053742c58dd7e3201c1ab30ee", size = 196070 },
+    { url = "https://files.pythonhosted.org/packages/96/b6/fcabd337bc5fa624e7203aa0fa7d0c49eed22f72e93229431752bddc83d9/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:794fe9145fe60191c6532fa95063765529770edcdd67b3d537793e8004cabbfd", size = 212907 },
+    { url = "https://files.pythonhosted.org/packages/4b/d3/9ee6160e644d660fcf176c5825e61411c7f62648728f69c79ba237250143/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:6105ef7e62b5ac73a837778efc331a591d8442f8ef5c7e102376506cb4ae2729", size = 200839 },
+    { url = "https://files.pythonhosted.org/packages/0d/98/e8de5baa5109394baf5118f5e72ab21a86387c4f89b0e77ef3e2f6b0327b/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:f01375c0e55395b814a679b3eea205db7919ac2af213f4a6682e01220e5fe292", size = 213304 },
+    { url = "https://files.pythonhosted.org/packages/7b/1d/71056535dec5c3177eeb53e38e3d367dd1d16e024e63b1cee208d572a033/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:d706dca2d24d834a4661619dcacf51a75c16d65985718d6a7d73c1eeeb903ddf", size = 416930 },
+    { url = "https://files.pythonhosted.org/packages/dc/6c/5cbde9de2cd967c322e651c65c543700b19e7ae3e0aae8ece3469bf9683d/xxhash-3.6.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:5f059d9faeacd49c0215d66f4056e1326c80503f51a1532ca336a385edadd033", size = 193787 },
+    { url = "https://files.pythonhosted.org/packages/19/fa/0172e350361d61febcea941b0cc541d6e6c8d65d153e85f850a7b256ff8a/xxhash-3.6.0-cp313-cp313t-win32.whl", hash = "sha256:1244460adc3a9be84731d72b8e80625788e5815b68da3da8b83f78115a40a7ec", size = 30916 },
+    { url = "https://files.pythonhosted.org/packages/ad/e6/e8cf858a2b19d6d45820f072eff1bea413910592ff17157cabc5f1227a16/xxhash-3.6.0-cp313-cp313t-win_amd64.whl", hash = "sha256:b1e420ef35c503869c4064f4a2f2b08ad6431ab7b229a05cce39d74268bca6b8", size = 31799 },
+    { url = "https://files.pythonhosted.org/packages/56/15/064b197e855bfb7b343210e82490ae672f8bc7cdf3ddb02e92f64304ee8a/xxhash-3.6.0-cp313-cp313t-win_arm64.whl", hash = "sha256:ec44b73a4220623235f67a996c862049f375df3b1052d9899f40a6382c32d746", size = 28044 },
+    { url = "https://files.pythonhosted.org/packages/7e/5e/0138bc4484ea9b897864d59fce9be9086030825bc778b76cb5a33a906d37/xxhash-3.6.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:a40a3d35b204b7cc7643cbcf8c9976d818cb47befcfac8bbefec8038ac363f3e", size = 32754 },
+    { url = "https://files.pythonhosted.org/packages/18/d7/5dac2eb2ec75fd771957a13e5dda560efb2176d5203f39502a5fc571f899/xxhash-3.6.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a54844be970d3fc22630b32d515e79a90d0a3ddb2644d8d7402e3c4c8da61405", size = 30846 },
+    { url = "https://files.pythonhosted.org/packages/fe/71/8bc5be2bb00deb5682e92e8da955ebe5fa982da13a69da5a40a4c8db12fb/xxhash-3.6.0-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:016e9190af8f0a4e3741343777710e3d5717427f175adfdc3e72508f59e2a7f3", size = 194343 },
+    { url = "https://files.pythonhosted.org/packages/e7/3b/52badfb2aecec2c377ddf1ae75f55db3ba2d321c5e164f14461c90837ef3/xxhash-3.6.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4f6f72232f849eb9d0141e2ebe2677ece15adfd0fa599bc058aad83c714bb2c6", size = 213074 },
+    { url = "https://files.pythonhosted.org/packages/a2/2b/ae46b4e9b92e537fa30d03dbc19cdae57ed407e9c26d163895e968e3de85/xxhash-3.6.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:63275a8aba7865e44b1813d2177e0f5ea7eadad3dd063a21f7cf9afdc7054063", size = 212388 },
+    { url = "https://files.pythonhosted.org/packages/f5/80/49f88d3afc724b4ac7fbd664c8452d6db51b49915be48c6982659e0e7942/xxhash-3.6.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3cd01fa2aa00d8b017c97eb46b9a794fbdca53fc14f845f5a328c71254b0abb7", size = 445614 },
+    { url = "https://files.pythonhosted.org/packages/ed/ba/603ce3961e339413543d8cd44f21f2c80e2a7c5cfe692a7b1f2cccf58f3c/xxhash-3.6.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0226aa89035b62b6a86d3c68df4d7c1f47a342b8683da2b60cedcddb46c4d95b", size = 194024 },
+    { url = "https://files.pythonhosted.org/packages/78/d1/8e225ff7113bf81545cfdcd79eef124a7b7064a0bba53605ff39590b95c2/xxhash-3.6.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c6e193e9f56e4ca4923c61238cdaced324f0feac782544eb4c6d55ad5cc99ddd", size = 210541 },
+    { url = "https://files.pythonhosted.org/packages/6f/58/0f89d149f0bad89def1a8dd38feb50ccdeb643d9797ec84707091d4cb494/xxhash-3.6.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:9176dcaddf4ca963d4deb93866d739a343c01c969231dbe21680e13a5d1a5bf0", size = 198305 },
+    { url = "https://files.pythonhosted.org/packages/11/38/5eab81580703c4df93feb5f32ff8fa7fe1e2c51c1f183ee4e48d4bb9d3d7/xxhash-3.6.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:c1ce4009c97a752e682b897aa99aef84191077a9433eb237774689f14f8ec152", size = 210848 },
+    { url = "https://files.pythonhosted.org/packages/5e/6b/953dc4b05c3ce678abca756416e4c130d2382f877a9c30a20d08ee6a77c0/xxhash-3.6.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:8cb2f4f679b01513b7adbb9b1b2f0f9cdc31b70007eaf9d59d0878809f385b11", size = 414142 },
+    { url = "https://files.pythonhosted.org/packages/08/a9/238ec0d4e81a10eb5026d4a6972677cbc898ba6c8b9dbaec12ae001b1b35/xxhash-3.6.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:653a91d7c2ab54a92c19ccf43508b6a555440b9be1bc8be553376778be7f20b5", size = 191547 },
+    { url = "https://files.pythonhosted.org/packages/f1/ee/3cf8589e06c2164ac77c3bf0aa127012801128f1feebf2a079272da5737c/xxhash-3.6.0-cp314-cp314-win32.whl", hash = "sha256:a756fe893389483ee8c394d06b5ab765d96e68fbbfe6fde7aa17e11f5720559f", size = 31214 },
+    { url = "https://files.pythonhosted.org/packages/02/5d/a19552fbc6ad4cb54ff953c3908bbc095f4a921bc569433d791f755186f1/xxhash-3.6.0-cp314-cp314-win_amd64.whl", hash = "sha256:39be8e4e142550ef69629c9cd71b88c90e9a5db703fecbcf265546d9536ca4ad", size = 32290 },
+    { url = "https://files.pythonhosted.org/packages/b1/11/dafa0643bc30442c887b55baf8e73353a344ee89c1901b5a5c54a6c17d39/xxhash-3.6.0-cp314-cp314-win_arm64.whl", hash = "sha256:25915e6000338999236f1eb68a02a32c3275ac338628a7eaa5a269c401995679", size = 28795 },
+    { url = "https://files.pythonhosted.org/packages/2c/db/0e99732ed7f64182aef4a6fb145e1a295558deec2a746265dcdec12d191e/xxhash-3.6.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:c5294f596a9017ca5a3e3f8884c00b91ab2ad2933cf288f4923c3fd4346cf3d4", size = 32955 },
+    { url = "https://files.pythonhosted.org/packages/55/f4/2a7c3c68e564a099becfa44bb3d398810cc0ff6749b0d3cb8ccb93f23c14/xxhash-3.6.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1cf9dcc4ab9cff01dfbba78544297a3a01dafd60f3bde4e2bfd016cf7e4ddc67", size = 31072 },
+    { url = "https://files.pythonhosted.org/packages/c6/d9/72a29cddc7250e8a5819dad5d466facb5dc4c802ce120645630149127e73/xxhash-3.6.0-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:01262da8798422d0685f7cef03b2bd3f4f46511b02830861df548d7def4402ad", size = 196579 },
+    { url = "https://files.pythonhosted.org/packages/63/93/b21590e1e381040e2ca305a884d89e1c345b347404f7780f07f2cdd47ef4/xxhash-3.6.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:51a73fb7cb3a3ead9f7a8b583ffd9b8038e277cdb8cb87cf890e88b3456afa0b", size = 215854 },
+    { url = "https://files.pythonhosted.org/packages/ce/b8/edab8a7d4fa14e924b29be877d54155dcbd8b80be85ea00d2be3413a9ed4/xxhash-3.6.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:b9c6df83594f7df8f7f708ce5ebeacfc69f72c9fbaaababf6cf4758eaada0c9b", size = 214965 },
+    { url = "https://files.pythonhosted.org/packages/27/67/dfa980ac7f0d509d54ea0d5a486d2bb4b80c3f1bb22b66e6a05d3efaf6c0/xxhash-3.6.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:627f0af069b0ea56f312fd5189001c24578868643203bca1abbc2c52d3a6f3ca", size = 448484 },
+    { url = "https://files.pythonhosted.org/packages/8c/63/8ffc2cc97e811c0ca5d00ab36604b3ea6f4254f20b7bc658ca825ce6c954/xxhash-3.6.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:aa912c62f842dfd013c5f21a642c9c10cd9f4c4e943e0af83618b4a404d9091a", size = 196162 },
+    { url = "https://files.pythonhosted.org/packages/4b/77/07f0e7a3edd11a6097e990f6e5b815b6592459cb16dae990d967693e6ea9/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:b465afd7909db30168ab62afe40b2fcf79eedc0b89a6c0ab3123515dc0df8b99", size = 213007 },
+    { url = "https://files.pythonhosted.org/packages/ae/d8/bc5fa0d152837117eb0bef6f83f956c509332ce133c91c63ce07ee7c4873/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:a881851cf38b0a70e7c4d3ce81fc7afd86fbc2a024f4cfb2a97cf49ce04b75d3", size = 200956 },
+    { url = "https://files.pythonhosted.org/packages/26/a5/d749334130de9411783873e9b98ecc46688dad5db64ca6e04b02acc8b473/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:9b3222c686a919a0f3253cfc12bb118b8b103506612253b5baeaac10d8027cf6", size = 213401 },
+    { url = "https://files.pythonhosted.org/packages/89/72/abed959c956a4bfc72b58c0384bb7940663c678127538634d896b1195c10/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:c5aa639bc113e9286137cec8fadc20e9cd732b2cc385c0b7fa673b84fc1f2a93", size = 417083 },
+    { url = "https://files.pythonhosted.org/packages/0c/b3/62fd2b586283b7d7d665fb98e266decadf31f058f1cf6c478741f68af0cb/xxhash-3.6.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5c1343d49ac102799905e115aee590183c3921d475356cb24b4de29a4bc56518", size = 193913 },
+    { url = "https://files.pythonhosted.org/packages/9a/9a/c19c42c5b3f5a4aad748a6d5b4f23df3bed7ee5445accc65a0fb3ff03953/xxhash-3.6.0-cp314-cp314t-win32.whl", hash = "sha256:5851f033c3030dd95c086b4a36a2683c2ff4a799b23af60977188b057e467119", size = 31586 },
+    { url = "https://files.pythonhosted.org/packages/03/d6/4cc450345be9924fd5dc8c590ceda1db5b43a0a889587b0ae81a95511360/xxhash-3.6.0-cp314-cp314t-win_amd64.whl", hash = "sha256:0444e7967dac37569052d2409b00a8860c2135cff05502df4da80267d384849f", size = 32526 },
+    { url = "https://files.pythonhosted.org/packages/0f/c9/7243eb3f9eaabd1a88a5a5acadf06df2d83b100c62684b7425c6a11bcaa8/xxhash-3.6.0-cp314-cp314t-win_arm64.whl", hash = "sha256:bb79b1e63f6fd84ec778a4b1916dfe0a7c3fdb986c06addd5db3a0d413819d95", size = 28898 },
+]
+
 [[package]]
 name = "yarl"
 version = "1.22.0"
@@ -2368,3 +2959,60 @@ sdist = { url = "https://files.pythonhosted.org/packages/e3/02/0f2892c661036d50e
 wheels = [
     { url = "https://files.pythonhosted.org/packages/2e/54/647ade08bf0db230bfea292f893923872fd20be6ac6f53b2b936ba839d75/zipp-3.23.0-py3-none-any.whl", hash = "sha256:071652d6115ed432f5ce1d34c336c0adfd6a884660d1e9712a256d3d3bd4b14e", size = 10276 },
 ]
+
+[[package]]
+name = "zstandard"
+version = "0.25.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fd/aa/3e0508d5a5dd96529cdc5a97011299056e14c6505b678fd58938792794b1/zstandard-0.25.0.tar.gz", hash = "sha256:7713e1179d162cf5c7906da876ec2ccb9c3a9dcbdffef0cc7f70c3667a205f0b", size = 711513 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/82/fc/f26eb6ef91ae723a03e16eddb198abcfce2bc5a42e224d44cc8b6765e57e/zstandard-0.25.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:7b3c3a3ab9daa3eed242d6ecceead93aebbb8f5f84318d82cee643e019c4b73b", size = 795738 },
+    { url = "https://files.pythonhosted.org/packages/aa/1c/d920d64b22f8dd028a8b90e2d756e431a5d86194caa78e3819c7bf53b4b3/zstandard-0.25.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:913cbd31a400febff93b564a23e17c3ed2d56c064006f54efec210d586171c00", size = 640436 },
+    { url = "https://files.pythonhosted.org/packages/53/6c/288c3f0bd9fcfe9ca41e2c2fbfd17b2097f6af57b62a81161941f09afa76/zstandard-0.25.0-cp312-cp312-manylinux2010_i686.manylinux2014_i686.manylinux_2_12_i686.manylinux_2_17_i686.whl", hash = "sha256:011d388c76b11a0c165374ce660ce2c8efa8e5d87f34996aa80f9c0816698b64", size = 5343019 },
+    { url = "https://files.pythonhosted.org/packages/1e/15/efef5a2f204a64bdb5571e6161d49f7ef0fffdbca953a615efbec045f60f/zstandard-0.25.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:6dffecc361d079bb48d7caef5d673c88c8988d3d33fb74ab95b7ee6da42652ea", size = 5063012 },
+    { url = "https://files.pythonhosted.org/packages/b7/37/a6ce629ffdb43959e92e87ebdaeebb5ac81c944b6a75c9c47e300f85abdf/zstandard-0.25.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:7149623bba7fdf7e7f24312953bcf73cae103db8cae49f8154dd1eadc8a29ecb", size = 5394148 },
+    { url = "https://files.pythonhosted.org/packages/e3/79/2bf870b3abeb5c070fe2d670a5a8d1057a8270f125ef7676d29ea900f496/zstandard-0.25.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:6a573a35693e03cf1d67799fd01b50ff578515a8aeadd4595d2a7fa9f3ec002a", size = 5451652 },
+    { url = "https://files.pythonhosted.org/packages/53/60/7be26e610767316c028a2cbedb9a3beabdbe33e2182c373f71a1c0b88f36/zstandard-0.25.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:5a56ba0db2d244117ed744dfa8f6f5b366e14148e00de44723413b2f3938a902", size = 5546993 },
+    { url = "https://files.pythonhosted.org/packages/85/c7/3483ad9ff0662623f3648479b0380d2de5510abf00990468c286c6b04017/zstandard-0.25.0-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:10ef2a79ab8e2974e2075fb984e5b9806c64134810fac21576f0668e7ea19f8f", size = 5046806 },
+    { url = "https://files.pythonhosted.org/packages/08/b3/206883dd25b8d1591a1caa44b54c2aad84badccf2f1de9e2d60a446f9a25/zstandard-0.25.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:aaf21ba8fb76d102b696781bddaa0954b782536446083ae3fdaa6f16b25a1c4b", size = 5576659 },
+    { url = "https://files.pythonhosted.org/packages/9d/31/76c0779101453e6c117b0ff22565865c54f48f8bd807df2b00c2c404b8e0/zstandard-0.25.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:1869da9571d5e94a85a5e8d57e4e8807b175c9e4a6294e3b66fa4efb074d90f6", size = 4953933 },
+    { url = "https://files.pythonhosted.org/packages/18/e1/97680c664a1bf9a247a280a053d98e251424af51f1b196c6d52f117c9720/zstandard-0.25.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:809c5bcb2c67cd0ed81e9229d227d4ca28f82d0f778fc5fea624a9def3963f91", size = 5268008 },
+    { url = "https://files.pythonhosted.org/packages/1e/73/316e4010de585ac798e154e88fd81bb16afc5c5cb1a72eeb16dd37e8024a/zstandard-0.25.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:f27662e4f7dbf9f9c12391cb37b4c4c3cb90ffbd3b1fb9284dadbbb8935fa708", size = 5433517 },
+    { url = "https://files.pythonhosted.org/packages/5b/60/dd0f8cfa8129c5a0ce3ea6b7f70be5b33d2618013a161e1ff26c2b39787c/zstandard-0.25.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:99c0c846e6e61718715a3c9437ccc625de26593fea60189567f0118dc9db7512", size = 5814292 },
+    { url = "https://files.pythonhosted.org/packages/fc/5f/75aafd4b9d11b5407b641b8e41a57864097663699f23e9ad4dbb91dc6bfe/zstandard-0.25.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:474d2596a2dbc241a556e965fb76002c1ce655445e4e3bf38e5477d413165ffa", size = 5360237 },
+    { url = "https://files.pythonhosted.org/packages/ff/8d/0309daffea4fcac7981021dbf21cdb2e3427a9e76bafbcdbdf5392ff99a4/zstandard-0.25.0-cp312-cp312-win32.whl", hash = "sha256:23ebc8f17a03133b4426bcc04aabd68f8236eb78c3760f12783385171b0fd8bd", size = 436922 },
+    { url = "https://files.pythonhosted.org/packages/79/3b/fa54d9015f945330510cb5d0b0501e8253c127cca7ebe8ba46a965df18c5/zstandard-0.25.0-cp312-cp312-win_amd64.whl", hash = "sha256:ffef5a74088f1e09947aecf91011136665152e0b4b359c42be3373897fb39b01", size = 506276 },
+    { url = "https://files.pythonhosted.org/packages/ea/6b/8b51697e5319b1f9ac71087b0af9a40d8a6288ff8025c36486e0c12abcc4/zstandard-0.25.0-cp312-cp312-win_arm64.whl", hash = "sha256:181eb40e0b6a29b3cd2849f825e0fa34397f649170673d385f3598ae17cca2e9", size = 462679 },
+    { url = "https://files.pythonhosted.org/packages/35/0b/8df9c4ad06af91d39e94fa96cc010a24ac4ef1378d3efab9223cc8593d40/zstandard-0.25.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:ec996f12524f88e151c339688c3897194821d7f03081ab35d31d1e12ec975e94", size = 795735 },
+    { url = "https://files.pythonhosted.org/packages/3f/06/9ae96a3e5dcfd119377ba33d4c42a7d89da1efabd5cb3e366b156c45ff4d/zstandard-0.25.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a1a4ae2dec3993a32247995bdfe367fc3266da832d82f8438c8570f989753de1", size = 640440 },
+    { url = "https://files.pythonhosted.org/packages/d9/14/933d27204c2bd404229c69f445862454dcc101cd69ef8c6068f15aaec12c/zstandard-0.25.0-cp313-cp313-manylinux2010_i686.manylinux2014_i686.manylinux_2_12_i686.manylinux_2_17_i686.whl", hash = "sha256:e96594a5537722fdfb79951672a2a63aec5ebfb823e7560586f7484819f2a08f", size = 5343070 },
+    { url = "https://files.pythonhosted.org/packages/6d/db/ddb11011826ed7db9d0e485d13df79b58586bfdec56e5c84a928a9a78c1c/zstandard-0.25.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:bfc4e20784722098822e3eee42b8e576b379ed72cca4a7cb856ae733e62192ea", size = 5063001 },
+    { url = "https://files.pythonhosted.org/packages/db/00/87466ea3f99599d02a5238498b87bf84a6348290c19571051839ca943777/zstandard-0.25.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:457ed498fc58cdc12fc48f7950e02740d4f7ae9493dd4ab2168a47c93c31298e", size = 5394120 },
+    { url = "https://files.pythonhosted.org/packages/2b/95/fc5531d9c618a679a20ff6c29e2b3ef1d1f4ad66c5e161ae6ff847d102a9/zstandard-0.25.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:fd7a5004eb1980d3cefe26b2685bcb0b17989901a70a1040d1ac86f1d898c551", size = 5451230 },
+    { url = "https://files.pythonhosted.org/packages/63/4b/e3678b4e776db00f9f7b2fe58e547e8928ef32727d7a1ff01dea010f3f13/zstandard-0.25.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8e735494da3db08694d26480f1493ad2cf86e99bdd53e8e9771b2752a5c0246a", size = 5547173 },
+    { url = "https://files.pythonhosted.org/packages/4e/d5/ba05ed95c6b8ec30bd468dfeab20589f2cf709b5c940483e31d991f2ca58/zstandard-0.25.0-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:3a39c94ad7866160a4a46d772e43311a743c316942037671beb264e395bdd611", size = 5046736 },
+    { url = "https://files.pythonhosted.org/packages/50/d5/870aa06b3a76c73eced65c044b92286a3c4e00554005ff51962deef28e28/zstandard-0.25.0-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:172de1f06947577d3a3005416977cce6168f2261284c02080e7ad0185faeced3", size = 5576368 },
+    { url = "https://files.pythonhosted.org/packages/5d/35/398dc2ffc89d304d59bc12f0fdd931b4ce455bddf7038a0a67733a25f550/zstandard-0.25.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:3c83b0188c852a47cd13ef3bf9209fb0a77fa5374958b8c53aaa699398c6bd7b", size = 4954022 },
+    { url = "https://files.pythonhosted.org/packages/9a/5c/36ba1e5507d56d2213202ec2b05e8541734af5f2ce378c5d1ceaf4d88dc4/zstandard-0.25.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:1673b7199bbe763365b81a4f3252b8e80f44c9e323fc42940dc8843bfeaf9851", size = 5267889 },
+    { url = "https://files.pythonhosted.org/packages/70/e8/2ec6b6fb7358b2ec0113ae202647ca7c0e9d15b61c005ae5225ad0995df5/zstandard-0.25.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:0be7622c37c183406f3dbf0cba104118eb16a4ea7359eeb5752f0794882fc250", size = 5433952 },
+    { url = "https://files.pythonhosted.org/packages/7b/01/b5f4d4dbc59ef193e870495c6f1275f5b2928e01ff5a81fecb22a06e22fb/zstandard-0.25.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:5f5e4c2a23ca271c218ac025bd7d635597048b366d6f31f420aaeb715239fc98", size = 5814054 },
+    { url = "https://files.pythonhosted.org/packages/b2/e5/fbd822d5c6f427cf158316d012c5a12f233473c2f9c5fe5ab1ae5d21f3d8/zstandard-0.25.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:4f187a0bb61b35119d1926aee039524d1f93aaf38a9916b8c4b78ac8514a0aaf", size = 5360113 },
+    { url = "https://files.pythonhosted.org/packages/8e/e0/69a553d2047f9a2c7347caa225bb3a63b6d7704ad74610cb7823baa08ed7/zstandard-0.25.0-cp313-cp313-win32.whl", hash = "sha256:7030defa83eef3e51ff26f0b7bfb229f0204b66fe18e04359ce3474ac33cbc09", size = 436936 },
+    { url = "https://files.pythonhosted.org/packages/d9/82/b9c06c870f3bd8767c201f1edbdf9e8dc34be5b0fbc5682c4f80fe948475/zstandard-0.25.0-cp313-cp313-win_amd64.whl", hash = "sha256:1f830a0dac88719af0ae43b8b2d6aef487d437036468ef3c2ea59c51f9d55fd5", size = 506232 },
+    { url = "https://files.pythonhosted.org/packages/d4/57/60c3c01243bb81d381c9916e2a6d9e149ab8627c0c7d7abb2d73384b3c0c/zstandard-0.25.0-cp313-cp313-win_arm64.whl", hash = "sha256:85304a43f4d513f5464ceb938aa02c1e78c2943b29f44a750b48b25ac999a049", size = 462671 },
+    { url = "https://files.pythonhosted.org/packages/3d/5c/f8923b595b55fe49e30612987ad8bf053aef555c14f05bb659dd5dbe3e8a/zstandard-0.25.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:e29f0cf06974c899b2c188ef7f783607dbef36da4c242eb6c82dcd8b512855e3", size = 795887 },
+    { url = "https://files.pythonhosted.org/packages/8d/09/d0a2a14fc3439c5f874042dca72a79c70a532090b7ba0003be73fee37ae2/zstandard-0.25.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:05df5136bc5a011f33cd25bc9f506e7426c0c9b3f9954f056831ce68f3b6689f", size = 640658 },
+    { url = "https://files.pythonhosted.org/packages/5d/7c/8b6b71b1ddd517f68ffb55e10834388d4f793c49c6b83effaaa05785b0b4/zstandard-0.25.0-cp314-cp314-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:f604efd28f239cc21b3adb53eb061e2a205dc164be408e553b41ba2ffe0ca15c", size = 5379849 },
+    { url = "https://files.pythonhosted.org/packages/a4/86/a48e56320d0a17189ab7a42645387334fba2200e904ee47fc5a26c1fd8ca/zstandard-0.25.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:223415140608d0f0da010499eaa8ccdb9af210a543fac54bce15babbcfc78439", size = 5058095 },
+    { url = "https://files.pythonhosted.org/packages/f8/ad/eb659984ee2c0a779f9d06dbfe45e2dc39d99ff40a319895df2d3d9a48e5/zstandard-0.25.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2e54296a283f3ab5a26fc9b8b5d4978ea0532f37b231644f367aa588930aa043", size = 5551751 },
+    { url = "https://files.pythonhosted.org/packages/61/b3/b637faea43677eb7bd42ab204dfb7053bd5c4582bfe6b1baefa80ac0c47b/zstandard-0.25.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:ca54090275939dc8ec5dea2d2afb400e0f83444b2fc24e07df7fdef677110859", size = 6364818 },
+    { url = "https://files.pythonhosted.org/packages/31/dc/cc50210e11e465c975462439a492516a73300ab8caa8f5e0902544fd748b/zstandard-0.25.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e09bb6252b6476d8d56100e8147b803befa9a12cea144bbe629dd508800d1ad0", size = 5560402 },
+    { url = "https://files.pythonhosted.org/packages/c9/ae/56523ae9c142f0c08efd5e868a6da613ae76614eca1305259c3bf6a0ed43/zstandard-0.25.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:a9ec8c642d1ec73287ae3e726792dd86c96f5681eb8df274a757bf62b750eae7", size = 4955108 },
+    { url = "https://files.pythonhosted.org/packages/98/cf/c899f2d6df0840d5e384cf4c4121458c72802e8bda19691f3b16619f51e9/zstandard-0.25.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:a4089a10e598eae6393756b036e0f419e8c1d60f44a831520f9af41c14216cf2", size = 5269248 },
+    { url = "https://files.pythonhosted.org/packages/1b/c0/59e912a531d91e1c192d3085fc0f6fb2852753c301a812d856d857ea03c6/zstandard-0.25.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:f67e8f1a324a900e75b5e28ffb152bcac9fbed1cc7b43f99cd90f395c4375344", size = 5430330 },
+    { url = "https://files.pythonhosted.org/packages/a0/1d/7e31db1240de2df22a58e2ea9a93fc6e38cc29353e660c0272b6735d6669/zstandard-0.25.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:9654dbc012d8b06fc3d19cc825af3f7bf8ae242226df5f83936cb39f5fdc846c", size = 5811123 },
+    { url = "https://files.pythonhosted.org/packages/f6/49/fac46df5ad353d50535e118d6983069df68ca5908d4d65b8c466150a4ff1/zstandard-0.25.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:4203ce3b31aec23012d3a4cf4a2ed64d12fea5269c49aed5e4c3611b938e4088", size = 5359591 },
+    { url = "https://files.pythonhosted.org/packages/c2/38/f249a2050ad1eea0bb364046153942e34abba95dd5520af199aed86fbb49/zstandard-0.25.0-cp314-cp314-win32.whl", hash = "sha256:da469dc041701583e34de852d8634703550348d5822e66a0c827d39b05365b12", size = 444513 },
+    { url = "https://files.pythonhosted.org/packages/3a/43/241f9615bcf8ba8903b3f0432da069e857fc4fd1783bd26183db53c4804b/zstandard-0.25.0-cp314-cp314-win_amd64.whl", hash = "sha256:c19bcdd826e95671065f8692b5a4aa95c52dc7a02a4c5a0cac46deb879a017a2", size = 516118 },
+    { url = "https://files.pythonhosted.org/packages/f0/ef/da163ce2450ed4febf6467d77ccb4cd52c4c30ab45624bad26ca0a27260c/zstandard-0.25.0-cp314-cp314-win_arm64.whl", hash = "sha256:d7541afd73985c630bafcd6338d2518ae96060075f9463d7dc14cfb33514383d", size = 476940 },
+]