diff --git a/README.md b/README.md
index c1c8524..719eade 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,46 @@ record what a running service already does.
 
 Verified against **pi 0.84.3**. Re-run the probes after every `pi update`.
 
+## Gitea repository and push authentication
+
+Everything here — the runtime config, every scenario's agent config, and (for
+scenarios that run a service) the application backend — lives in a single Gitea
+repository: **`kai/pi-agent-config`** on the server at `192.168.50.45` (web UI on
+`:3000`, SSH on `:222`). There is no per-agent repository; a Pi agent is a
+directory under `scenarios/`, not a separate repo.
+
+Push and pull over **SSH key auth only** (no HTTP token). The Git user is `git`,
+not `kai`. `~/.ssh/config`:
+
+```bash
+Host gitea-45
+    HostName 192.168.50.45
+    User git
+    Port 222
+    IdentityFile ~/.ssh/id_ed25519_gitea
+    IdentitiesOnly yes
+```
+
+The remote is `origin -> gitea-45:kai/pi-agent-config.git` (branch `main`). Run
+Git from the repository root, never from a scenario subdirectory that might carry
+a different remote:
+
+```bash
+git pull --rebase origin main
+git push origin main
+```
+
+Verify access:
+
+```bash
+ssh -T gitea-45                             # "Hi there, kai! ... authenticated"
+git ls-remote gitea-45:kai/pi-agent-config.git
+```
+
+- The key file must be `0600`; never read or print its contents.
+- `gitea-pve`, if present in your SSH config, is a host login — not a Git remote.
+- The `verify-no-secrets.sh` pre-commit hook must pass; never use `--no-verify`.
+
 ## Scenarios
 
 | Scenario | Purpose | Service | Status |
diff --git a/scenarios/curator/README.md b/scenarios/curator/README.md
new file mode 100644
index 0000000..1688d5c
--- /dev/null
+++ b/scenarios/curator/README.md
@@ -0,0 +1,25 @@
+# curator — Pi agent scenario
+
+This directory is the **curator** Pi agent. It is tracked as part of the
+`pi-agent-config` repository — it is **not** a standalone repository.
+
+- Gitea repo: `kai/pi-agent-config` on `192.168.50.45` (web `:3000`, SSH `:222`).
+- Remote: `origin -> gitea-45:kai/pi-agent-config.git`, branch `main`.
+- Auth: SSH key only (`~/.ssh/id_ed25519_gitea`, Git user `git`); no HTTP token.
+- Push and pull from the repository root, not from here:
+
+```bash
+git pull --rebase origin main
+git push origin main
+```
+
+See the repository [`README.md`](../../README.md), section “Gitea repository and
+push authentication”, for the full SSH config and caveats.
+
+## Layout
+
+- `profile.toml` — the launch contract (single source of truth).
+- `workspace/` — the `.pi` configuration deployed into the live workspace.
+- `eval/` — recorded golden transcripts.
+- `backend/` — the authoritative Python service source; the live workspace checkout is a runtime copy.
+- `docs/` — scenario-specific documentation.
diff --git a/scenarios/memo-inbox/README.md b/scenarios/memo-inbox/README.md
index b1716a3..9867ffc 100644
--- a/scenarios/memo-inbox/README.md
+++ b/scenarios/memo-inbox/README.md
@@ -1,3 +1,27 @@
+# memo-inbox — Pi agent scenario
+
+This directory is the **memo-inbox** Pi agent. It is tracked as part of the
+`pi-agent-config` repository — it is **not** a standalone repository.
+
+- Gitea repo: `kai/pi-agent-config` on `192.168.50.45` (web `:3000`, SSH `:222`).
+- Remote: `origin -> gitea-45:kai/pi-agent-config.git`, branch `main`.
+- Auth: SSH key only (`~/.ssh/id_ed25519_gitea`, Git user `git`); no HTTP token.
+- Push and pull from the repository root, not from here:
+
+```bash
+git pull --rebase origin main
+git push origin main
+```
+
+See the repository [`README.md`](../../README.md), section “Gitea repository and
+push authentication”, for the full SSH config and caveats.
+
+## Layout
+
+- `profile.toml` — the launch contract; `deploy = "mirror"` records what the live service does.
+- `workspace/` — the mirrored live agent configuration.
+- `docs/` — scenario-specific documentation.
+
 # Scenario: memo-inbox
 
 Routes Kai's Telegram and WeChat messages into Google Calendar, today's Obsidian
diff --git a/scenarios/pi-grok/README.md b/scenarios/pi-grok/README.md
new file mode 100644
index 0000000..077984d
--- /dev/null
+++ b/scenarios/pi-grok/README.md
@@ -0,0 +1,21 @@
+# pi-grok — Pi agent scenario
+
+This directory is the **pi-grok** Pi agent. It is tracked as part of the
+`pi-agent-config` repository — it is **not** a standalone repository.
+
+- Gitea repo: `kai/pi-agent-config` on `192.168.50.45` (web `:3000`, SSH `:222`).
+- Remote: `origin -> gitea-45:kai/pi-agent-config.git`, branch `main`.
+- Auth: SSH key only (`~/.ssh/id_ed25519_gitea`, Git user `git`); no HTTP token.
+- Push and pull from the repository root, not from here:
+
+```bash
+git pull --rebase origin main
+git push origin main
+```
+
+See the repository [`README.md`](../../README.md), section “Gitea repository and
+push authentication”, for the full SSH config and caveats.
+
+## Layout
+
+- `profile.toml` — the launch contract (single source of truth).