diff --git a/surfsense_backend/app/automations/persistence/models/run.py b/surfsense_backend/app/automations/persistence/models/run.py
index 43a1de07d..45da6a39d 100644
--- a/surfsense_backend/app/automations/persistence/models/run.py
+++ b/surfsense_backend/app/automations/persistence/models/run.py
@@ -1,9 +1,4 @@
-"""``automation_runs`` table — immutable per-fire execution record.
-
-Per-step metadata (incl. any LangGraph session id for an ``agent_task`` step)
-lives inside ``step_results[i]``, since a single run may contain zero, one,
-or N agent steps.
-"""
+"""``automation_runs`` table — immutable per-fire execution record."""
 
 from __future__ import annotations
 
@@ -51,6 +46,8 @@ class AutomationRun(BaseModel, TimestampMixin):
 
     trigger_payload = Column(JSONB, nullable=True)
     resolved_inputs = Column(JSONB, nullable=False, server_default="{}")
+    # one entry per executed step; agent_task entries carry their own
+    # `agent_session_id` (LangGraph thread reference) inside this JSONB
     step_results = Column(JSONB, nullable=False, server_default="[]")
     output = Column(JSONB, nullable=True)
     artifacts = Column(JSONB, nullable=False, server_default="[]")
diff --git a/surfsense_backend/app/automations/schemas/definition/envelope.py b/surfsense_backend/app/automations/schemas/definition/envelope.py
index ccd76d612..ffc45a0cd 100644
--- a/surfsense_backend/app/automations/schemas/definition/envelope.py
+++ b/surfsense_backend/app/automations/schemas/definition/envelope.py
@@ -12,7 +12,7 @@ from .trigger_spec import TriggerSpec
 
 
 class AutomationDefinition(BaseModel):
-    """Top-level shape of an automation. See automation-design-plan.md §5."""
+    """Top-level shape of an automation."""
 
     model_config = ConfigDict(extra="forbid")