docs: add learning about agent push access to gitea

docs/solutions/workflow-issues/agent-push-access-unavailable.md

@@ -0,0 +1,82 @@
+---
+title: Agent push access to git.sgeboers.nl unavailable
+date: 2026-04-05
+category: workflow-issues
+module: development-workflow
+problem_type: workflow_issue
+component: development_workflow
+severity: low
+applies_when:
+  - Agent attempts to push branches to git.sgeboers.nl
+  - Agent runs git push or gh pr create commands targeting the Gitea instance
+tags:
+  - git
+  - gitea
+  - push-access
+  - ssh
+  - authentication
+---
+
+# Agent push access to git.sgeboers.nl unavailable
+
+## Context
+
+The agent does not have working SSH or HTTPS authentication configured for `git.sgeboers.nl`. All available SSH keys (`id_ed25519`, `id_rsa`, `sb`, `gitlab_cicdtest`, `sgeboers_deploy_key`) are rejected by the Gitea instance. HTTPS credential helpers are not configured.
+
+When the agent attempts `git push`, the operation fails with:
+```
+git@git.sgeboers.nl: Permission denied (publickey).
+```
+
+## Guidance
+
+When the agent completes work on a feature branch and attempts to push or create a PR:
+
+1. **Inform the user** that push/PR creation is blocked due to missing authentication
+2. **Present clear options**:
+   - Add an SSH key to the Gitea account at `https://git.sgeboers.nl/user/settings/keys`
+   - Configure a personal access token for HTTPS push
+3. **Do not attempt workarounds** — the agent cannot configure SSH agents or credential helpers without a TTY
+4. **Document the limitation** in compound learnings so future sessions know immediately
+
+## Why This Matters
+
+The agent can complete all development work (implement features, write tests, run verification) but cannot self-publish. The user must push and create PRs manually. This is acceptable — the agent's value is in the engineering work, not the final git operations.
+
+## When to Apply
+
+- Any time the agent has completed work on a feature branch
+- Before attempting `git push`, `git push --force`, or `gh pr create`
+- After creating commits that the user wants pushed to the remote
+
+## Examples
+
+**Agent workflow when push is needed:**
+
+```
+1. Agent completes feature work, all tests pass
+2. Agent runs: git push -u origin feat/branch-name
+3. Push fails: Permission denied (publickey)
+4. Agent informs user: "I don't have push access to git.sgeboers.nl.
+   Please push manually or configure SSH/HTTPS auth."
+5. User pushes manually
+```
+
+**User configuration to enable agent push:**
+
+Option 1 — Add SSH key:
+```bash
+# Show the public key to add to Gitea
+cat ~/.ssh/id_ed25519.pub
+# User copies to https://git.sgeboers.nl/user/settings/keys
+```
+
+Option 2 — Use HTTPS with token:
+```bash
+git remote set-url origin https://git.sgeboers.nl/user/repo.git
+# Configure credential helper or use GitHub CLI equivalent
+```
+
+## Related
+
+- `AGENTS.md` — project conventions and agent constraints