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/schemas/definition/envelope.py

@@ -1,4 +1,4 @@
-"""``AutomationDefinition`` — the top-level envelope persisted in ``automations.definition``."""
+"""``AutomationDefinition`` — top-level envelope persisted in ``automations.definition``."""
 
 from __future__ import annotations
 
@@ -12,78 +12,15 @@ from .trigger_spec import TriggerSpec
 
 
 class AutomationDefinition(BaseModel):
-    """The top-level JSON shape stored in ``automations.definition``.
-
-    This is the editable spec a user authors (or the NL generator
-    produces). The envelope is structural only — every nested
-    discriminator (``triggers[].type``, ``plan[].action``) is resolved
-    against the registries at validation time, so adding a new
-    trigger or action type does not require touching this schema.
-
-    See ``automation-design-plan.md`` §5 for the worked example and
-    rationale.
-    """
+    """Top-level shape of an automation. See automation-design-plan.md §5."""
 
     model_config = ConfigDict(extra="forbid")
 
-    schema_version: str = Field(
-        default="1.0",
-        description=(
-            "Schema version of the envelope itself. Migrations bump "
-            "this when the envelope shape changes; nested per-type "
-            "configs evolve independently via the registries."
-        ),
-    )
-    name: str = Field(
-        ...,
-        description="Short, user-facing name shown in lists.",
-        min_length=1,
-        max_length=200,
-    )
-    goal: str | None = Field(
-        default=None,
-        description=(
-            "Optional plain-language statement of what the "
-            "automation is for. Used by the NL generator's review "
-            "pass and by the UI's run dialog."
-        ),
-    )
-    inputs: InputsBlock | None = Field(
-        default=None,
-        description=(
-            "Optional input contract. When omitted, the automation "
-            "accepts no inputs at fire time."
-        ),
-    )
-    triggers: list[TriggerSpec] = Field(
-        default_factory=list,
-        description=(
-            "Triggers that fire this automation. Empty list means "
-            "the automation is only runnable via the manual "
-            "``Run now`` path."
-        ),
-    )
-    plan: list[PlanStep] = Field(
-        ...,
-        description=(
-            "Ordered sequence of steps. Executed in array order — "
-            "no parallelism, no DAGs, no loops at the envelope "
-            "level."
-        ),
-        min_length=1,
-    )
-    execution: ExecutionBlock = Field(
-        default_factory=ExecutionBlock,
-        description=(
-            "Execution defaults (timeouts, retries, concurrency, "
-            "budget). All fields default to safe values; the block "
-            "may be omitted entirely."
-        ),
-    )
-    metadata: MetadataBlock = Field(
-        default_factory=MetadataBlock,
-        description=(
-            "Free-form metadata (tags, NL-generator breadcrumbs, "
-            "UI annotations). Tolerates unknown keys by design."
-        ),
-    )
+    schema_version: str = "1.0"
+    name: str = Field(..., min_length=1, max_length=200)
+    goal: str | None = None
+    inputs: InputsBlock | None = None
+    triggers: list[TriggerSpec] = Field(default_factory=list)
+    plan: list[PlanStep] = Field(..., min_length=1)
+    execution: ExecutionBlock = Field(default_factory=ExecutionBlock)
+    metadata: MetadataBlock = Field(default_factory=MetadataBlock)