docs: rewrite README and AGENTS.md, add admin sync button

README.md

@@ -1,17 +1,103 @@
 # Kirche Einfach
 
-KI-gestützte Verwaltungsplattform für Kirche.
+AI-assisted administration platform for church organizations.
 
-## Stack
+Staff describe a request in plain words. The platform guides them through the
+process, checks the rules automatically, and asks a human only when something
+needs judgment. Every step is documented and traceable.
 
-- **Backend:** Python 3.12, FastAPI, Django, uv
-- **Frontend:** React 19, TypeScript, Vite
-- **Dev:** Devcontainer, opencode
+## Features
+
+- **Visual flow authoring** — design decision flows in Langflow, then bring
+  them into the platform.
+- **Flows as files** — each flow lives as one JSON file under
+  `backend/flows/`. The directory is the source of truth: committed to git,
+  reviewable, diffable.
+- **Automatic sync** — the API watches `backend/flows/` and reconciles every
+  change into the database and the runtime: new files become flows, edits
+  become new versions, deleted files remove the flow (including its runs).
+  Same on every startup; also triggerable via `POST /api/flows/sync` or
+  `uv run python scripts/sync_flows.py --sync`.
+- **Versioned runtime** — every change creates an immutable version; versions
+  deploy to the lightweight LFX runtime and can run synchronously or streamed.
+- **Approvals** — a flow can pause and ask a human for a decision. Approving
+  can automatically start a follow-up ("continuation") flow.
+- **Web UI** — three tabs: *Vorgänge* (flows and runs), *Freigaben*
+  (approvals), *Administration* (import, sync, deploy).
+
+## Infrastructure
+
+```mermaid
+flowchart LR
+    subgraph Repo["Git repo — source of truth"]
+        FLOWS["backend/flows/*.json<br/>one Langflow export per flow"]
+    end
+    subgraph Stack["Compose stack (dev + prod)"]
+        UI["frontend — React UI (3000)"]
+        API["app — FastAPI (8000)<br/>+ embedded flow-watcher"]
+        DB[("app.db — SQLite file")]
+        LF["langflow — authoring UI (7860)<br/>langflow.db — SQLite file"]
+        LFX["lfx — flow runtime (6004)"]
+        WT["watchtower — nightly image updates"]
+    end
+    UI --> API
+    FLOWS -->|watch + sync| API
+    API -->|definitions · versions · runs · approvals| DB
+    API -->|pull / export| LF
+    API -->|upload · run · unregister| LFX
+    LFX -->|approval callbacks| API
+    WT -.->|updates :latest images| LF
+```
+
+| Service        | Purpose                              | URL                        |
+| -------------- | ------------------------------------ | -------------------------- |
+| React frontend | Web UI (Vite)                        | http://localhost:3000      |
+| FastAPI backend| API + flow orchestration             | http://localhost:8000      |
+| API docs       | Swagger UI                           | http://localhost:8000/api/docs |
+| Langflow       | Visual flow authoring                | http://localhost:7860      |
+| LFX            | Flow runtime (internal, no direct UI)| localhost:6004             |
+| SQLite files   | `backend/data/kirche.db` (app), Langflow keeps its own file | — |
+
+Why SQLite: a flow run needs only a handful of single-row statements, and
+Langflow itself runs on SQLite by default — so the whole stack works without
+a database server. Postgres can return later by changing `DATABASE_URL`
+(migrations stay portable).
 
 ## Getting Started
 
-Open in VS Code → "Reopen in Container".
+1. Copy `.env.example` to `.env` and fill in the secrets.
+2. Open the repo in VS Code → "Reopen in Container". Setup installs
+   dependencies, migrates the database, and syncs `backend/flows/`.
+3. Run the backend from `backend/`: `uv run uvicorn app.main:app --port 8000`.
+   Run the frontend from `frontend/`: `npm run dev`.
 
-Backend: `http://localhost:8000`
-Frontend: `http://localhost:3000`
-API Docs: `http://localhost:8000/api/docs`
+Production (self-hosted, internal use — no TLS/reverse proxy included):
+
+```sh
+docker compose -f compose.prod.yml up -d --build
+```
+
+## Development
+
+Backend (from `backend/`):
+
+- `uv run pytest` — full test suite (throwaway SQLite file, no external DB).
+- `uv run alembic upgrade head` — migrate the dev database.
+- `uv run python scripts/sync_flows.py --sync` — reconcile `backend/flows/`.
+- `uv run python scripts/sync_flows.py --pull` — export all Langflow flows
+  into `backend/flows/` first.
+- `uv run python scripts/deploy_flow.py --langflow-id <uuid>` — import one
+  Langflow flow via the API.
+- `uv run python scripts/make_flow_fixtures.py` — regenerate the bundled
+  flows (writes test fixtures and `backend/flows/`).
+- `uv run python scripts/smoke_e2e.py` — manual end-to-end smoke.
+
+Frontend (from `frontend/`): `npm install`, `npm run dev`, `npm run build`.
+
+Flow workflow: design in Langflow → export into `backend/flows/<name>.json`
+(`--pull`, or UI download) → commit → the watcher deploys it automatically.
+Deleting a file removes the flow including its runs (git keeps the JSON).
+
+Container updates: registry images (`langflowai/langflow:latest`)
+auto-update nightly via Watchtower (`nickfedor/watchtower`). Locally built
+images (`app`, `lfx`, `frontend`) update with `docker compose build --pull`.