diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index a73854c..2316535 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -82,6 +82,25 @@ curl -s  http://127.0.0.1:8080/nonexistent  -o /dev/null -w "%{http_code}\n"   #
 - Verify `/`, `/about/`, `/projects/`, `/resume/`, `/posts/` over HTTPS.
 - Confirm the spiral actually renders in a real browser — the one thing `curl` cannot check.
 
+## Troubleshooting
+
+### Deploy status stuck/red on Gitea after a migration or restart
+
+If the Actions/deploy status shows broken or stops updating (commits push but no
+run is registered), the per-repo git hooks may be stale or missing. Fix by
+resynchronizing hooks from the Gitea admin CLI (this regenerates
+`pre-receive`, `update`, `post-receive` and their `.d/gitea` delegates):
+
+```bash
+docker exec -u git gitea gitea admin regenerate hooks
+```
+
+For the full documented recovery, the Gitea FAQ steps are:
+"Sync missed branches from git data to databases", "Sync tags from git data to
+database", and "Resynchronize pre-receive, update and post-receive hooks of all
+repositories" (the last one is what the command above does). After regenerating,
+push a commit to refresh the status.
+
 ## Rollback
 
 The previous site is preserved in the git tag `pre-hugo` and the `archive/` folder. To roll back: `git checkout pre-hugo` and redeploy with the old single-stage Dockerfile (also recoverable from git history).