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

README.md

@@ -1,2 +1,60 @@
-# Beaver Gateway
-[![AI Slop Inside](https://sladge.net/badge.svg)](https://sladge.net)
+# beaver-gateway
+
+A gateway for personal agents built on the Claude Agent SDK: conversations
+with a lifecycle, windows to talk through, jobs, memory hooks, and a policy
+boundary - without an opinion about what the agent is for. A setup is one
+`config.py` (or a package next to it) that assembles a `Gateway`; this repo
+holds the primitives, [beaver-agent](https://git.kotikot.com/beaver/beaver-agent)
+is a full setup built on them.
+
+## What it gives a setup
+
+- **agents/** - what an agent is: a Claude agent with a prompt per
+  conversation kind, skill sets per kind, gateway tools, a `PreToolUse`
+  policy; a Raycast agent for cheap fast answers.
+- **backends/** - how a turn runs: the Claude Agent SDK subprocess with a
+  session pool, transcripts and session stores; the Raycast wire.
+- **conversations/** - the model of a conversation: kinds (master, branch,
+  deep, job, fork), rows and windows, the inject queue with priorities,
+  seeds, turns, questions, closing through a distiller, master rotation,
+  the envelope, the in-process gateway tools.
+- **jobs/** - cron, webhook and event jobs on pgqueuer, deferred injects,
+  the subscription budget.
+- **frontends/** - the windows: Telegram (master = General, topic = branch),
+  markdown files in a vault, `/api` + the admin SPA, an Anthropic-compatible
+  `/anthropic/v1/messages`, MCP re-exposure at `/mcp/<name>`.
+- **mcp/** - MCP servers a setup declares (stdio, http, python tools),
+  aggregated in-process and handed to agents by name.
+- **vault/** - watching a directory of notes for the envelope.
+- **security/** - bearer tokens, the audit log, credential redaction.
+- **events/** - the in-process bus every frontend taps, and the stream
+  event protocol backends emit.
+- **storage/** - SQLModel tables and the Postgres session store.
+
+`config.py` defines `Gateway` and loads a setup; `app.py` builds the runtime
+from it; `cli.py` is the entrypoint. Every string the gateway puts in front of
+a model or a user has an English default and is overridable
+(`ConversationTexts`, `TelegramTexts`).
+
+## Run
+
+```sh
+uv sync                       # python
+cd ui && bun install && cd .. # admin + panel SPA, built into ui/build
+cp examples/config.py /config/config.py
+DATABASE_URL=postgresql+psycopg://... CONFIG_PATH=/config/config.py uv run beaver-gateway
+```
+
+`examples/config.py` is the smallest setup that starts. The setup's own
+secrets come from `.env` (`load_dotenv` runs before the config is executed).
+
+## Develop
+
+```sh
+make check   # ruff format --check, ruff check, ty, pytest
+make fix
+```
+
+No comments in code: modules carry a one-line docstring saying what they are
+for, public configuration fields carry a one-line docstring saying what they
+mean; everything else is the code.