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

src/beaver_gateway/settings.py

@@ -1,8 +1,8 @@
 """Process-wide configuration loaded from environment (`.env`).
 
-Everything that varies between deployments (creds, paths, ports) lives here.
-User-facing agent/MCP/frontend definitions live in ``/config/config.py``
-and are loaded by ``config_loader`` (Phase 0.3).
+Everything that varies between deployments (creds, paths, ports) lives
+here. User-facing agent/MCP/frontend definitions live in ``config_path``
+and are loaded by :mod:`beaver_gateway.config`.
 """
 
 from __future__ import annotations
@@ -20,12 +20,22 @@ class Settings(BaseSettings):
     )
 
     database_url: str
+    """SQLAlchemy async URL for the gateway's database."""
+
     admin_user: str
+    """Username for the admin UI login."""
+
     admin_pass: str
+    """Password for the admin UI login."""
+
     session_secret: str
+    """Secret used to sign admin UI session cookies."""
 
     internal_mcp_port: int = 8765
+    """Port the gateway's own internal MCP server listens on."""
+
     config_path: Path = Path("/config/config.py")
+    """Where the user-facing agent/MCP/frontend config module lives."""
 
     claude_runner_user: str | None = None
     """Unix user the claude subprocess runs as. Needs the gateway to be root."""
@@ -34,23 +44,19 @@ class Settings(BaseSettings):
     """``HOME`` for the claude subprocess (its ``~/.claude`` lives there)."""
 
     raycast_bearer: str | None = None
+    """Bearer token the gateway presents to the Raycast API."""
+
     raycast_config_path: Path = Path("/config/raycast.json")
+    """Where cached Raycast API config (fetched on first use) is stored."""
+
     raycast_device_id: str | None = None
-    """64-hex-char stable per-install id. Required when any ``RaycastAgent``
-    is configured — generate once via ``secrets.token_hex(32)`` and keep
-    in ``.env`` so Raycast doesn't see every restart as a new device."""
+    """Stable per-install id (``secrets.token_hex(32)``); required when any
+    ``RaycastAgent`` is configured, so restarts don't look like a new device."""
 
     raycast_locale: str = "en-US"
-    """``Accept-Language`` header sent by the shared ``raycast_api.Client``
-    and the default locale used to render auto ``UserPreferences``. One
-    value per gateway since we open one Client total."""
+    """``Accept-Language`` sent to the Raycast API and the default locale for
+    auto ``UserPreferences``. One value per gateway (one shared Client)."""
 
     bootstrap_tokens: str = ""
-    """Out-of-band token seed: ``name1:value1,name2:value2``. Empty is
-    fine — DB-issued tokens (admin UI) carry steady-state auth.
-
-    This env channel layers alongside the DB store and is kept for
-    first-run setup, disaster recovery (admin password lost), and
-    ``examples/`` smoke tests. Bootstrap tokens implicitly carry
-    scope ``"*"`` and never get a ``last_used_at`` stamp (no DB row).
-    """
+    """Out-of-band token seed: ``name1:value1,name2:value2``. Layers
+    alongside DB-issued tokens; used for first-run setup and recovery."""