diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml
index 1618625..b572735 100644
--- a/.gitea/workflows/ci.yaml
+++ b/.gitea/workflows/ci.yaml
@@ -54,13 +54,21 @@ jobs:
           SHORT_SHA=$(git rev-parse --short HEAD)
           echo "short_sha=${SHORT_SHA}" >> $GITHUB_OUTPUT
 
+      - name: Validate registry credentials
+        run: |
+          if [ -z "${{ secrets.FORGEJO_REGISTRY_USER }}" ] || [ -z "${{ secrets.FORGEJO_REGISTRY_TOKEN }}" ]; then
+            echo "❌ ERROR: Registry secrets not configured"
+            echo "Set FORGEJO_REGISTRY_USER and FORGEJO_REGISTRY_TOKEN in repo settings"
+            exit 1
+          fi
+          echo "✓ Registry credentials configured"
+
       - name: Registry login
         run: |
-          echo "${REGISTRY_TOKEN}" | docker login "${REGISTRY}" \
-            --username "${REGISTRY_USER}" --password-stdin
+          echo "${{ secrets.FORGEJO_REGISTRY_TOKEN }}" | docker login "${{ env.REGISTRY }}" \
+            --username "${{ secrets.FORGEJO_REGISTRY_USER }}" --password-stdin
         env:
-          REGISTRY_USER: ${{ secrets.FORGEJO_REGISTRY_USER }}
-          REGISTRY_TOKEN: ${{ secrets.FORGEJO_REGISTRY_TOKEN }}
+          DOCKER_CONFIG: /tmp/docker-config
 
       - name: Build Docker image
         run: |
diff --git a/REGISTRY_SETUP.md b/REGISTRY_SETUP.md
new file mode 100644
index 0000000..88b0811
--- /dev/null
+++ b/REGISTRY_SETUP.md
@@ -0,0 +1,78 @@
+# Forgejo Registry Secrets Configuration
+
+## One-Time Setup (Org Level)
+
+All repos in the `rock` org share the same Forgejo registry credentials.
+
+### Configure at Organization Level
+
+1. Navigate to: https://forgejo.riotpiao.com/rock
+2. Click Settings (gear icon)
+3. Go to: Actions → Secrets
+4. Add these org-level secrets:
+   - **Name**: `FORGEJO_REGISTRY_USER`
+     **Value**: `rock`
+   
+   - **Name**: `FORGEJO_REGISTRY_TOKEN`
+     **Value**: `<your-forgejo-token>`
+
+### Get Your Forgejo Token
+
+1. Go to: https://forgejo.riotpiao.com/user/settings/applications
+2. Click "Generate New Token"
+3. Set scopes: `api`, `read:registry`, `write:registry`
+4. Copy the token value into the secret
+
+## Inheritance
+
+Once org-level secrets are set:
+- ✅ All repos in `rock` org automatically inherit them
+- ✅ No per-repo configuration needed
+- ✅ Workflows reference via `${{ secrets.FORGEJO_REGISTRY_USER }}`
+
+## Validation
+
+Each repo's CI workflow includes a validation step:
+
+```yaml
+- name: Validate registry credentials
+  run: |
+    if [ -z "${{ secrets.FORGEJO_REGISTRY_USER }}" ] || [ -z "${{ secrets.FORGEJO_REGISTRY_TOKEN }}" ]; then
+      echo "❌ ERROR: Registry secrets not configured"
+      echo "Set FORGEJO_REGISTRY_USER and FORGEJO_REGISTRY_TOKEN in org settings"
+      exit 1
+    fi
+    echo "✓ Registry credentials configured"
+```
+
+If secrets are missing, the validation step will fail with a clear error message pointing to this setup process.
+
+## Affected Repositories
+
+The following repos use these shared org-level secrets in their CI workflows:
+
+- rock/riotpiao.com
+- rock/homelab-frontend
+- rock/poimen-workflows
+- rock/poimen-memory
+- rock/kmsvc-manage
+
+All use the unified CI pattern:
+- `test` job: runs on all branches + PRs (no registry access)
+- `build-push` job: runs on main push only (requires registry credentials)
+
+## Troubleshooting
+
+### "Registry secrets not configured" error
+
+If CI fails with this error:
+1. Check org settings: https://forgejo.riotpiao.com/rock/settings/actions/secrets
+2. Verify both secrets exist and are not empty
+3. Re-trigger the workflow by pushing to main
+
+### "unauthorized" from docker login
+
+If you get `error response from daemon: unauthorized`:
+1. Check the token value is correct (copy-paste carefully)
+2. Verify token has `read:registry` and `write:registry` scopes
+3. Generate a new token if the old one expired