diff --git a/GITEA_PUSH_HOWTO.md b/GITEA_PUSH_HOWTO.md
new file mode 100644
index 0000000..b88c773
--- /dev/null
+++ b/GITEA_PUSH_HOWTO.md
@@ -0,0 +1,75 @@
+# Gitea push how-to (for Codex / automation)
+
+Repo remote:
+- `origin = gitea-elm:admin/elmprodvpn.git`
+
+Problem this file solves:
+- Sometimes `ssh -T gitea-elm` works in your terminal, but `git push` from Codex fails with:
+  - `Permission denied (publickey)`
+  - `ssh_askpass: ... No such file or directory`
+
+Root cause:
+- Codex may run commands with a different `SSH_AUTH_SOCK` (different ssh-agent).
+- The key exists on disk, but is NOT loaded into the agent used by the current process.
+
+## 1) Sanity check: can we authenticate to Gitea?
+
+Preferred:
+```bash
+ssh -T gitea-elm
+```
+
+Expected:
+- `Hi there, admin! ... Gitea does not provide shell access.`
+
+## 2) If `git push` fails with publickey: find the right ssh-agent
+
+Check current agent:
+```bash
+echo "$SSH_AUTH_SOCK"
+ssh-add -l
+```
+
+If you see `The agent has no identities`, search for other agents (common on desktop sessions):
+```bash
+ls -la /tmp/ssh-*/agent.* 2>/dev/null
+for s in /tmp/ssh-*/agent.*; do
+  echo "== $s"
+  SSH_AUTH_SOCK="$s" ssh-add -l 2>&1 || true
+done
+```
+
+Pick the agent that contains the Gitea key and verify it works:
+```bash
+SSH_AUTH_SOCK=/tmp/ssh-XXXX/agent.YYY ssh -o BatchMode=yes -T gitea-elm
+```
+
+Then run git commands with the same `SSH_AUTH_SOCK`:
+```bash
+SSH_AUTH_SOCK=/tmp/ssh-XXXX/agent.YYY git fetch origin
+SSH_AUTH_SOCK=/tmp/ssh-XXXX/agent.YYY git push
+```
+
+Tip:
+- If you want to avoid repeating it, export once:
+  `export SSH_AUTH_SOCK=/tmp/ssh-XXXX/agent.YYY`
+
+## 3) If push is rejected with “fetch first”
+
+Remote `main` already has commits. Use rebase:
+```bash
+SSH_AUTH_SOCK=/tmp/ssh-XXXX/agent.YYY git fetch origin
+git rebase origin/main
+SSH_AUTH_SOCK=/tmp/ssh-XXXX/agent.YYY git push
+```
+
+## 4) If rebase complains about permissions / cannot unlink files
+
+Usually means some files in the repo are owned by root or another user.
+Fix ownership for the problematic paths:
+```bash
+sudo chown -R dev:dev <path>
+```
+
+Then retry the rebase.
+