diff --git a/docs/git-workflow.md b/docs/git-workflow.md
new file mode 100644
index 0000000..929cbc6
--- /dev/null
+++ b/docs/git-workflow.md
@@ -0,0 +1,86 @@
+Git Workflow and Branch Protection
+==================================
+
+Goal
+- Keep `master` protected; changes land via pull requests with review and passing checks.
+
+Remotes
+- Forgejo repo: `ssh://git@git.halla-aho.net:2223/thalla/lomavuokraus.git`
+- Add remote if missing: `git remote add origin ssh://git@git.halla-aho.net:2223/thalla/lomavuokraus.git`
+- Verify: `git remote -v`
+
+Daily flow
+1) Sync `master`:
+   ```
+   git checkout master
+   git pull --rebase   # or `git pull` if you prefer merges; see config below
+   ```
+2) Create a feature branch:
+   ```
+   git checkout -b feature/<short-name>
+   ```
+3) Commit locally:
+   ```
+   git status
+   git add <files>
+   git commit -m "Your change"
+   ```
+4) Push branch to Forgejo:
+   ```
+   git push -u origin feature/<short-name>
+   ```
+5) Open a PR targeting `master` in Forgejo.
+6) Get review + approvals; ensure CI passes.
+7) Merge via the PR; master stays protected.
+8) After merge, sync local master:
+   ```
+   git checkout master
+   git pull --rebase
+   git branch -d feature/<short-name>   # cleanup
+   ```
+
+Branch protection (set in Forgejo UI)
+- Settings → Branches → Protect `master`.
+- Enable:
+  - Prevent direct pushes (except admins if desired).
+  - Require pull requests.
+  - Require at least 1 approval.
+  - Restrict who can push (admins/maintainers).
+  - Optionally dismiss stale approvals and require status checks (CI).
+
+Recommended local config
+- Default pull strategy (pick one):
+  - Rebase pulls: `git config pull.rebase true`
+  - Merge pulls: `git config pull.rebase false`
+  - Fast-forward only: `git config pull.ff only`
+- Set your user:
+  ```
+  git config user.name "Your Name"
+  git config user.email "you@example.com"
+  ```
+
+Common troubleshooting
+- Divergent branches on pull: set pull strategy (see above) and rerun `git pull --rebase` or `git pull`.
+- “Remote not found”: add `origin` remote (see Remotes).
+- Push rejected (protected branch): push to a feature branch and open a PR.
+- Conflicts during pull/rebase:
+  ```
+  git status          # see conflicted files
+  # edit files to resolve
+  git add <files>
+  git rebase --continue   # if rebasing
+  git commit             # if merging
+  ```
+- Wrong branch for work: create a new branch and move commits:
+  ```
+  git checkout -b feature/fix
+  git push -u origin feature/fix
+  ```
+- Clean up merged branches locally: `git branch --merged master` then `git branch -d <branch>`.
+
+CI
+- Workflows live under `.forgejo/workflows/`. Ensure CI passes before merging.
+
+Secrets and kubeconfig
+- `creds/` is git-ignored; place kubeconfig at `creds/kubeconfig.yaml` or set `KUBECONFIG`.
+- Age/SOPS key: store at `~/.config/age/keys.txt` or set `SOPS_AGE_KEY_FILE`.
diff --git a/generate_images.py b/scripts/generate_sample_images.py
similarity index 100%
rename from generate_images.py
rename to scripts/generate_sample_images.py