diff --git a/.forgejo/workflows/ci.yml b/.forgejo/workflows/ci.yml
index fc4fc43..ed55fde 100644
--- a/.forgejo/workflows/ci.yml
+++ b/.forgejo/workflows/ci.yml
@@ -1,3 +1,8 @@
+# Forgejo Actions CI for kaizen-agentic.
+# Runner substrate: ubuntu-latest maps to docker://node:20-bookworm (no pip).
+# Install python3 + pip via apt; use archive checkout (no actions/checkout).
+# Pattern from reuse-surface/.forgejo/workflows/ci.yml and
+# railiance-enablement/docs/forgejo-actions-workflow-templates.md.
 name: ci
 
 on:
@@ -17,15 +22,23 @@ jobs:
         run: |
           set -eu
           mkdir -p repo
+          # Prefer short SHA; full SHA archive URLs can hang on this substrate.
+          SHORT="${REF:0:7}"
           wget -qO /tmp/repo.tar.gz \
-            "https://forgejo.coulomb.social/${GITHUB_REPOSITORY}/archive/${REF}.tar.gz"
+            "https://forgejo.coulomb.social/${GITHUB_REPOSITORY}/archive/${SHORT}.tar.gz"
           tar xzf /tmp/repo.tar.gz -C repo --strip-components=1
 
+      - name: Install Python tooling
+        run: |
+          set -eu
+          apt-get update -qq
+          apt-get install -y -qq python3 python3-pip python3-venv >/dev/null
+          python3 -m pip install --break-system-packages --upgrade pip
+
       - name: Install package and dev tools
         working-directory: repo
         run: |
-          python3 -m pip install --upgrade pip
-          python3 -m pip install -e ".[dev]"
+          python3 -m pip install --break-system-packages -e ".[dev]"
 
       - name: Format check (black)
         working-directory: repo
diff --git a/.forgejo/workflows/publish-python-package.yml b/.forgejo/workflows/publish-python-package.yml
index e6225e6..79e87a9 100644
--- a/.forgejo/workflows/publish-python-package.yml
+++ b/.forgejo/workflows/publish-python-package.yml
@@ -1,3 +1,6 @@
+# Publish kaizen-agentic to Forgejo org PyPI on version tags.
+# Runner substrate: ubuntu-latest → node:20-bookworm — install pip via apt.
+# Org secrets required: FORGEJO_PYPI_USER, FORGEJO_PYPI_TOKEN.
 name: Publish Python package
 
 on:
@@ -16,13 +19,17 @@ jobs:
         run: |
           set -eu
           mkdir -p buildctx
+          SHORT="${REF:0:7}"
           wget -qO /tmp/repo.tar.gz \
-            "https://forgejo.coulomb.social/${GITHUB_REPOSITORY}/archive/${REF}.tar.gz"
+            "https://forgejo.coulomb.social/${GITHUB_REPOSITORY}/archive/${SHORT}.tar.gz"
           tar xzf /tmp/repo.tar.gz -C buildctx --strip-components=1
 
-      - name: Set up Python
+      - name: Install Python tooling
         run: |
-          python3 -m pip install --upgrade pip build twine
+          set -eu
+          apt-get update -qq
+          apt-get install -y -qq python3 python3-pip python3-venv >/dev/null
+          python3 -m pip install --break-system-packages --upgrade pip build twine
 
       - name: Build and validate distributions
         working-directory: buildctx