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

AGENTS.md

@@ -1,5 +1,44 @@
 # Agents
 
+Kirche Einfach — AI-assisted church administration. FastAPI backend (`backend/`, Python 3.12, SQLModel, SQLite) + React 19/Vite frontend (`frontend/`). Flow definitions live as JSON files in `backend/flows/` (source of truth); the DB is derived by the sync engine.
+
+## Commands
+
+Backend (run from `backend/`):
+- `uv sync` — install dependencies
+- `uv run pytest` — full test suite (throwaway SQLite file, no external DB needed)
+- `uv run alembic upgrade head` — migrate the dev database (`backend/data/`, gitignored)
+- `uv run python scripts/sync_flows.py --sync` — reconcile `backend/flows/` into DB + LFX
+- `uv run uvicorn app.main:app --port 8000` — run the API (paths resolve from repo root, CWD-independent)
+
+Frontend (run from `frontend/`): `npm install`, `npm run dev`, `npm run build` (typecheck + build).
+
+## Definition of done
+
+- New behavior has tests; `uv run pytest` is green before reporting completion.
+- `npm run build` is green when frontend code changed.
+- Schema changes ship as a new Alembic revision — never edit an applied migration.
+
+## Architecture rules
+
+- `backend/flows/*.json` is the source of truth (one Langflow export per file). Never write flow JSON anywhere else.
+- Only `backend/app/flows/sync.py` reconciles files into the DB. CLI, `POST /api/flows/sync`, and the embedded watcher must call it — never duplicate its logic.
+- All DB access goes through `backend/app/flows/store.py`. Keep API handlers thin.
+- Talk to LFX only via `LfxClient`, to Langflow only via `LangflowClient`.
+- Flow JSON must stay a valid Langflow export (`store` requires `data.nodes`/`data.edges`).
+
+```python
+from app.flows.sync import sync_from_directory
+report = await sync_from_directory(session, lfx, settings.flows_dir)
+```
+
+## Boundaries
+
+- Never commit secrets. `.env` is gitignored; only `.env.example` is tracked.
+- Never edit `backend/data/*` (runtime SQLite files) or `__pycache__`.
+- Never add a second file-watcher or a second sync path.
+- Deleting `backend/flows/<name>.json` deletes the flow including its runs from the DB (by design).
+
 ## Git
 
-When committing: `git add -A && git commit -m "<message>"`. When pushing: `git push` (branch is tracking `origin/main`).
+When committing: `git add -A && git commit -m "<message>"` (conventional commits: `feat:`, `fix:`, `chore:`, `docs:`). When pushing: `git push` (branch is tracking `origin/main`).