refactor: no comments left - one-line module docstrings, contracts on public fields only; jobs/job.py; example config and README

src/beaver_gateway/backends/base.py

@@ -2,18 +2,7 @@
 
 A backend turns an Anthropic-style turn (``messages`` + agent definition)
 into a stream of :class:`~beaver_gateway.events.stream.MessageStreamEvent`
-records. The frontend serializes whatever comes out straight to SSE, so
-backends are the only place where provider quirks are translated.
-
-Implementations are plain :class:`typing.Protocol` conformers - no ABC
-subclassing - to keep them swappable in tests with bare async generators.
-
-``**options`` is the one extension point. Known keys, all optional and
-ignored by backends that don't keep state: ``conversation_id`` (stable id
-the backend may pin a live session to), ``session_id`` (backend session to
-resume when nothing is live), ``capture`` (a
-:class:`~beaver_gateway.backends.capture.TurnCapture` the backend fills
-after the stream closes).
+records; provider quirks are translated here, not in the frontend.
 """
 
 from __future__ import annotations
@@ -40,5 +29,13 @@ class Backend(Protocol):
         system: str | None = None,
         **options: Any,
     ) -> AsyncIterator[MessageStreamEvent]:
-        """Yield Anthropic stream events for one turn against ``agent``."""
+        """Yield Anthropic stream events for one turn against ``agent``.
+
+        ``**options`` keys are optional and ignored by backends that don't
+        keep state: ``conversation_id`` (stable id the backend may pin a
+        live session to), ``session_id`` (backend session to resume when
+        nothing is live), ``capture`` (a
+        :class:`~beaver_gateway.backends.capture.TurnCapture` the backend
+        fills after the stream closes).
+        """
         ...