chore(automation): trim docstrings to intent only

Cut the docstrings and Field(description=...) text across the entire
automations/ tree down to single-line intent statements, matching the
multi_agent_chat conciseness style:

- Module docstrings: one line stating what the file is.
- Class docstrings: deleted when the class name + module docstring
  already cover intent; kept only where they add a constraint or
  rationale not visible in the signature.
- Pydantic Field descriptions: short noun phrases / clauses, not
  full sentences. Reasoning that belonged in the design plan moved
  out of the code.
- Enum values: per-value docstrings replaced with terse inline
  comments where the meaning isn't obvious from the name.

Behaviour is unchanged. The same 33 files, same public surface, same
imports — verified by re-running the 10-point registry smoke test and
the 8-point schema round-trip / constraint suite from commits 9 and
10.

LOC: 1180 → 691 (-42%).

surfsense_backend/app/automations/persistence/__init__.py

@@ -1,4 +1,4 @@
-"""Persistence layer: SQLAlchemy enums under ``enums/`` and models under ``models/``."""
+"""SQLAlchemy models and enums for the automation tables."""
 
 from __future__ import annotations
 

surfsense_backend/app/automations/persistence/enums/__init__.py

@@ -1,4 +1,4 @@
-"""SQLAlchemy / Python enums backing the three automation tables."""
+"""Enums for the automation tables."""
 
 from __future__ import annotations
 

surfsense_backend/app/automations/persistence/enums/automation_status.py

@@ -1,4 +1,4 @@
-"""``AutomationStatus`` — lifecycle of a stored automation definition."""
+"""Automation lifecycle status."""
 
 from __future__ import annotations
 
@@ -6,13 +6,6 @@ from enum import StrEnum
 
 
 class AutomationStatus(StrEnum):
-    """Status of an automation in the registry.
-
-    ``active``   — eligible to fire from its triggers.
-    ``paused``   — definition retained, triggers do not fire.
-    ``archived`` — kept for run history only; no edits, no fires.
-    """
-
-    ACTIVE = "active"
-    PAUSED = "paused"
-    ARCHIVED = "archived"
+    ACTIVE = "active"  # eligible to fire
+    PAUSED = "paused"  # kept, but triggers don't fire
+    ARCHIVED = "archived"  # read-only history

surfsense_backend/app/automations/persistence/enums/run_status.py

@@ -1,4 +1,4 @@
-"""``RunStatus`` — the state machine of a single ``AutomationRun``."""
+"""AutomationRun state machine: pending → running → (succeeded|failed|cancelled|timed_out)."""
 
 from __future__ import annotations
 
@@ -6,20 +6,6 @@ from enum import StrEnum
 
 
 class RunStatus(StrEnum):
-    """Lifecycle states of an ``AutomationRun`` row.
-
-    Transitions are linear with three terminal branches:
-
-        pending → running → (succeeded | failed | cancelled | timed_out)
-
-    ``pending``    — row created, executor task enqueued, work not started.
-    ``running``    — executor has picked up the run.
-    ``succeeded``  — terminal: plan completed without error.
-    ``failed``     — terminal: at least one step raised an unrecoverable error.
-    ``cancelled``  — terminal: caller asked for cancellation.
-    ``timed_out``  — terminal: run exceeded its configured timeout.
-    """
-
     PENDING = "pending"
     RUNNING = "running"
     SUCCEEDED = "succeeded"

surfsense_backend/app/automations/persistence/enums/trigger_type.py

@@ -1,4 +1,4 @@
-"""``TriggerType`` — the trigger-kind discriminator (v1 = schedule, manual)."""
+"""Trigger-kind discriminator. v1: schedule | manual; webhook/event in Phase 2/3."""
 
 from __future__ import annotations
 
@@ -6,16 +6,5 @@ from enum import StrEnum
 
 
 class TriggerType(StrEnum):
-    """Kind of trigger an ``AutomationTrigger`` row represents.
-
-    v1 ships two kinds:
-
-    ``schedule`` — fires on a cron expression managed by Celery Beat.
-    ``manual``   — fires on demand from the UI's "Run now" affordance.
-
-    ``webhook`` and ``event`` are deferred to Phase 2 and Phase 3
-    respectively; adding them is an enum-value extension only.
-    """
-
     SCHEDULE = "schedule"
     MANUAL = "manual"

surfsense_backend/app/automations/persistence/models/__init__.py

@@ -1,4 +1,4 @@
-"""SQLAlchemy models: one file per table (``automation.py``, ``trigger.py``, ``run.py``)."""
+"""SQLAlchemy models, one per table."""
 
 from __future__ import annotations
 

surfsense_backend/app/automations/persistence/models/automation.py

@@ -1,4 +1,4 @@
-"""``Automation`` table — the editable, versioned automation definition."""
+"""``automations`` table — editable, versioned automation definition."""
 
 from __future__ import annotations
 
@@ -21,15 +21,6 @@ from ..enums.automation_status import AutomationStatus
 
 
 class Automation(BaseModel, TimestampMixin):
-    """The editable, versioned spec a user authors.
-
-    The ``definition`` JSON is what the user (or the NL generator) writes
-    and edits. Each save bumps ``version`` by one; the previous JSON is
-    not kept in this row — version history is reconstructed from the
-    ``definition_snapshot`` column on every ``AutomationRun`` that fired
-    against a given version.
-    """
-
     __tablename__ = "automations"
 
     search_space_id = Column(
@@ -59,12 +50,7 @@ class Automation(BaseModel, TimestampMixin):
 
     definition = Column(JSONB, nullable=False)
 
-    version = Column(
-        Integer,
-        nullable=False,
-        default=1,
-        server_default="1",
-    )
+    version = Column(Integer, nullable=False, default=1, server_default="1")
 
     updated_at = Column(
         TIMESTAMP(timezone=True),

surfsense_backend/app/automations/persistence/models/run.py

@@ -1,4 +1,4 @@
-"""``AutomationRun`` table — the immutable per-fire execution record."""
+"""``automation_runs`` table — immutable per-fire execution record."""
 
 from __future__ import annotations
 
@@ -18,16 +18,6 @@ from ..enums.run_status import RunStatus
 
 
 class AutomationRun(BaseModel, TimestampMixin):
-    """One execution of an automation.
-
-    Every fire of any trigger inserts exactly one row here. The row is
-    immutable from the user's perspective — the executor only updates
-    ``status``, ``step_results``, ``output``, ``artifacts``, ``error``,
-    ``started_at``, ``finished_at`` as the run progresses; the
-    ``definition_snapshot`` is locked at fire time so the user can always
-    see exactly what code path executed for any historical run.
-    """
-
     __tablename__ = "automation_runs"
 
     automation_id = Column(
@@ -52,18 +42,14 @@ class AutomationRun(BaseModel, TimestampMixin):
         index=True,
     )
 
+    # locked at fire time so historical runs always show the exact code path
     definition_snapshot = Column(JSONB, nullable=False)
 
     trigger_payload = Column(JSONB, nullable=True)
-
     resolved_inputs = Column(JSONB, nullable=False, server_default="{}")
-
     step_results = Column(JSONB, nullable=False, server_default="[]")
-
     output = Column(JSONB, nullable=True)
-
     artifacts = Column(JSONB, nullable=False, server_default="[]")
-
     error = Column(JSONB, nullable=True)
 
     started_at = Column(TIMESTAMP(timezone=True), nullable=True)

surfsense_backend/app/automations/persistence/models/trigger.py

@@ -1,4 +1,4 @@
-"""``AutomationTrigger`` table — one row per (automation, trigger-instance) pair."""
+"""``automation_triggers`` table — one row per (automation, trigger-instance) pair."""
 
 from __future__ import annotations
 
@@ -18,14 +18,6 @@ from ..enums.trigger_type import TriggerType
 
 
 class AutomationTrigger(BaseModel, TimestampMixin):
-    """One trigger attached to an automation.
-
-    An automation may have multiple triggers — e.g. a ``schedule`` trigger
-    for the autonomous path and a ``manual`` trigger backing the UI's
-    "Run now" affordance. Each trigger's ``config`` is validated against
-    the registered ``TriggerDefinition.config_schema`` for its ``type``.
-    """
-
     __tablename__ = "automation_triggers"
 
     automation_id = Column(
@@ -51,7 +43,4 @@ class AutomationTrigger(BaseModel, TimestampMixin):
         index=True,
     )
 
-    last_fired_at = Column(
-        TIMESTAMP(timezone=True),
-        nullable=True,
-    )
+    last_fired_at = Column(TIMESTAMP(timezone=True), nullable=True)