diff --git a/.gitea/workflows/README.md b/.gitea/workflows/README.md
index f8cde45..471c464 100644
--- a/.gitea/workflows/README.md
+++ b/.gitea/workflows/README.md
@@ -47,6 +47,55 @@ Suppress specific rules per-line with `# gdlint: disable=<rule>` or
 project-wide with a `gdlintrc` file at the repo root (see
 [gdtoolkit docs](https://github.com/Scony/godot-gdscript-toolkit/wiki)).
 
+## Known issues from first runs
+
+Captured from the first triggered runs on `feature/godot-migration`
+(2026-05-17). Both must be resolved before the workflow can pass.
+
+### 1. Container jobs fail at `actions/checkout@v4` with `node: not found`
+
+```
+OCI runtime exec failed: ... exec: "node": executable file not found in $PATH
+```
+
+`actions/checkout@v4` is a JavaScript action and needs Node.js inside
+the container. The `barichello/godot-ci:4.6` image does not ship Node,
+so every job using `container:` (validate, export-desktop, export-android)
+breaks immediately.
+
+Fix path (recommended): drop the `container:` block entirely and install
+Godot in a step (the default `catthehacker/ubuntu:act-latest` image used
+for `runs-on: ubuntu-latest` already has Node, Python, git, JDK). The
+`lint` job is already structured this way.
+
+Alternative: switch to a Godot CI image that bundles Node (some community
+images do); pin a specific tag.
+
+### 2. `actions/checkout` clones the wrong URL (resolved 2026-05-17)
+
+The first runs failed at clone time because the runner asked for
+`https://dev.stilobique.com/darknight/puzzle-quest/info/refs` while
+Gitea was mounted under `/gitea/` behind YunoHost — the request was
+intercepted by the YunoHost SSO at the root and redirected before
+reaching Gitea.
+
+Resolved by relocating Gitea to the root: it now serves at
+`https://dev.stilobique.com/` directly (API at `/api/v1/...`,
+`clone_url` at `/<owner>/<repo>.git`). The runner-injected
+`GITHUB_SERVER_URL` and the actual Gitea base URL now agree.
+
+If Gitea is ever moved back under a sub-path, the fix is `ROOT_URL` in
+`app.ini` (`[server] ROOT_URL = https://<host>/<prefix>/`) or
+re-registering `act_runner` with the full instance URL.
+
+### 3. Default-branch mismatch
+
+The Gitea API reports `default_branch: main` for the repo, but
+`CLAUDE.md` describes `dev` as the default. The workflow listens to both,
+so jobs trigger correctly either way, but the "Workflows" sidebar in the
+Gitea UI reads from whatever the actual default branch is. If you intend
+`dev` to be the default, update it under repo Settings → Branches.
+
 ## Differences from the old `.drone.yml`
 
 - No more Drone, no more Butler — build only, artifacts downloadable from