From a81fd5f299a14c72e5fa398d445da4dfa5752c7b Mon Sep 17 00:00:00 2001
From: Dan <dleink@gmail.com>
Date: Thu, 22 Jan 2026 15:03:34 -0800
Subject: [PATCH] docs: Forgejo collaboration guide for dev users

Research for ops-jrz1-mh2: how dev users collaborate on git.clarun.xyz

Covers:
- Account setup and SSH access
- Shared repo vs fork+PR models
- Trunk-based workflow
- Troubleshooting common issues
---
 .beads/.local_version         |   2 +-
 .beads/last-touched           |   2 +-
 docs/forgejo-collaboration.md | 178 ++++++++++++++++++++++++++++++++++
 3 files changed, 180 insertions(+), 2 deletions(-)
 create mode 100644 docs/forgejo-collaboration.md

diff --git a/.beads/.local_version b/.beads/.local_version
index 650298f..5c4503b 100644
--- a/.beads/.local_version
+++ b/.beads/.local_version
@@ -1 +1 @@
-0.47.1
+0.49.0
diff --git a/.beads/last-touched b/.beads/last-touched
index dcd4101..904e843 100644
--- a/.beads/last-touched
+++ b/.beads/last-touched
@@ -1 +1 @@
-ops-jrz1-6hu4
+ops-jrz1-mh2
diff --git a/docs/forgejo-collaboration.md b/docs/forgejo-collaboration.md
new file mode 100644
index 0000000..0089735
--- /dev/null
+++ b/docs/forgejo-collaboration.md
@@ -0,0 +1,178 @@
+# Forgejo Collaboration Guide
+
+How dev users collaborate on shared projects via git.clarun.xyz.
+
+## Overview
+
+Forgejo is our self-hosted git server at https://git.clarun.xyz. Dev users get automatic accounts when provisioned via `dev-add.sh`.
+
+## Getting Started
+
+### Your Account
+
+When your account is created, you automatically get:
+- **Forgejo username** matching your Unix username
+- **SSH access** from both your laptop and the dev server
+- **Initial password** in `~/.forgejo-credentials` (change on first login)
+
+### Clone a Repository
+
+```bash
+# From the dev server (or laptop with SSH key registered)
+git clone forgejo@git.clarun.xyz:owner/repo.git
+```
+
+> **Note:** The SSH user is `forgejo`, not `git`.
+
+### Web Interface
+
+Browse repos, manage settings, view history: https://git.clarun.xyz
+
+## Collaboration Models
+
+### Shared Repository (Small Teams)
+
+All collaborators have write access to the same repo.
+
+**Setup:**
+1. Repo owner adds collaborators via web UI (Settings → Collaborators)
+2. Everyone clones the same repo
+3. Use branches for features, merge to main
+
+**Best for:** Trusted teams, internal projects, rapid iteration
+
+### Fork + Pull Request (Open Contribution)
+
+Contributors work on personal forks and submit PRs.
+
+**Setup:**
+1. Fork the repo via web UI
+2. Clone your fork
+3. Push changes to your fork
+4. Create Pull Request to upstream
+
+**Best for:** External contributors, code review gates, open source style
+
+## Recommended Workflow
+
+We use **trunk-based development**:
+
+```
+main (always deployable)
+  │
+  ├── feature-branch (short-lived)
+  │     └── merge back quickly
+  │
+  └── another-feature
+```
+
+### Daily Workflow
+
+```bash
+# Start fresh
+git checkout main
+git pull
+
+# Create feature branch
+git checkout -b add-new-feature
+
+# Make changes, commit often
+git add .
+git commit -m "Add new feature"
+
+# Push and create PR (or merge directly for small teams)
+git push -u origin add-new-feature
+```
+
+### Commit Messages
+
+Keep them clear and concise:
+- ~70 characters for the summary line
+- Reference issue IDs if applicable
+- No emojis or marketing language
+
+## Repository Settings
+
+### Creating a New Repo
+
+**Via Web UI:**
+1. Click "+" → "New Repository"
+2. Choose owner (you or an organization)
+3. Set visibility (public/private)
+
+**Via API (admins):**
+```bash
+TOKEN=$(cat /run/secrets/forgejo-api-token)
+curl -X POST "http://localhost:3000/api/v1/user/repos" \
+  -H "Authorization: token $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-project", "private": false}'
+```
+
+### Adding Collaborators
+
+1. Go to repo → Settings → Collaborators
+2. Search by username
+3. Choose permission level (Read, Write, Admin)
+
+## SSH Configuration
+
+### From Your Laptop
+
+Add to `~/.ssh/config`:
+```
+Host git.clarun.xyz
+    HostName git.clarun.xyz
+    User forgejo
+    IdentityFile ~/.ssh/id_ed25519
+```
+
+Then clone with:
+```bash
+git clone git.clarun.xyz:owner/repo.git
+```
+
+### From the Dev Server
+
+SSH keys are pre-configured. Just clone:
+```bash
+git clone forgejo@git.clarun.xyz:owner/repo.git
+```
+
+## Troubleshooting
+
+### "Permission denied (publickey)"
+
+Your SSH key isn't registered in Forgejo.
+
+**Fix:** 
+1. Go to https://git.clarun.xyz/user/settings/keys
+2. Add your public key (`cat ~/.ssh/id_ed25519.pub`)
+
+### "Repository not found"
+
+Either the repo doesn't exist or you don't have access.
+
+**Fix:**
+- Check the URL spelling
+- Ask the repo owner to add you as a collaborator
+- For private repos, ensure you're authenticated
+
+### Clone works but push fails
+
+You have read access but not write access.
+
+**Fix:** Ask repo owner to grant Write permission in Collaborators settings.
+
+## Best Practices
+
+1. **Pull before starting work** - Avoid merge conflicts
+2. **Small, focused commits** - Easier to review and revert
+3. **Use branches** - Keep main deployable
+4. **Write good commit messages** - Future you will thank you
+5. **Don't commit secrets** - Use environment variables or secret management
+
+## Related Docs
+
+- [Dev Onboarding](dev-onboarding.md) - Full setup guide
+- [Forgejo Admin](forgejo-admin.md) - API tokens and admin operations