diff --git a/.forgejo/workflows/build.yml b/.forgejo/workflows/build.yml
new file mode 100644
index 0000000..750a79e
--- /dev/null
+++ b/.forgejo/workflows/build.yml
@@ -0,0 +1,70 @@
+name: Build images
+
+on:
+  push:
+    branches: [dev, main]
+
+# Requires repo secret RELEASE_TOKEN — a Forgejo PAT with scopes:
+#   - write:package, read:package  (for docker push to git.fabledsword.com)
+#   - write:release                (for future release-cutting workflows)
+#   - write:issue                  (for future issue-management automation)
+# The injected GITHUB_TOKEN cannot be used — it lacks write:package.
+
+jobs:
+  build-web:
+    runs-on: fabledcurator-ci
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Determine tag
+        id: tag
+        run: |
+          if [ "${GITHUB_REF##*/}" = "main" ]; then
+            echo "tags=git.fabledsword.com/bvandeusen/fabledcurator:main,git.fabledsword.com/bvandeusen/fabledcurator:latest" >> "$GITHUB_OUTPUT"
+          else
+            echo "tags=git.fabledsword.com/bvandeusen/fabledcurator:dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Login to Forgejo registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.fabledsword.com
+          username: ${{ github.actor }}
+          password: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Build and push web image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: Dockerfile
+          push: true
+          tags: ${{ steps.tag.outputs.tags }}
+
+  build-ml:
+    runs-on: fabledcurator-ci
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Determine tag
+        id: tag
+        run: |
+          if [ "${GITHUB_REF##*/}" = "main" ]; then
+            echo "tags=git.fabledsword.com/bvandeusen/fabledcurator-ml:main,git.fabledsword.com/bvandeusen/fabledcurator-ml:latest" >> "$GITHUB_OUTPUT"
+          else
+            echo "tags=git.fabledsword.com/bvandeusen/fabledcurator-ml:dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Login to Forgejo registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.fabledsword.com
+          username: ${{ github.actor }}
+          password: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Build and push ml image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: Dockerfile.ml
+          push: true
+          tags: ${{ steps.tag.outputs.tags }}
diff --git a/README.md b/README.md
index 990356f..0ee52da 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,18 @@ docker compose up -d
 
 FabledCurator is designed to run inside a self-hosted homelab environment over plain HTTP. If you want TLS, terminate it at your reverse proxy. The app does not generate certificates, redirect to HTTPS, or set HSTS.
 
+## CI / Forgejo setup
+
+The repo's workflows expect:
+
+- **Runner label `fabledcurator-ci`** — a Forgejo runner with Python 3.14, ruff, and Node 22 pre-installed. Both `ci.yml` and `build.yml` use this label.
+- **Repo secret `RELEASE_TOKEN`** — a Forgejo PAT with the following scopes:
+  - `write:package` + `read:package` — for `docker push` to `git.fabledsword.com`
+  - `write:release` — for future release-cutting workflows
+  - `write:issue` — for future issue-management automation
+
+  Generate at https://git.fabledsword.com/user/settings/applications. The injected `GITHUB_TOKEN` cannot be used because it lacks `write:package`.
+
 ## License
 
 Personal project; use at your own discretion.