release: v0.18.1 [skip ci]

The rewritten sync_wiki.py (devx 0.35.1) removed the --strict flag.
The new git-based approach is strict by default; --verify adds
post-sync page verification.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

.devin/skills/testing-and-debugging/SKILL.md

@@ -76,7 +76,7 @@ If `.venv` doesn't exist, run `make setup` first.
 
 **Always run `make pytest-cov` before pushing** — CI enforces 100%
 coverage and will fail the PR if any lines are uncovered. This is the
-most common cause of CI quality job failures after code changes. The
+most common cause of CI validate job failures after code changes. The
 pre-push git hook only validates Vikunja task existence, not tests.
 
 ### API Response Type Checking

.env.example

@@ -15,7 +15,8 @@ GITEA_REGISTRATION_TOKEN=your-registration-token
 # If set, API checks are performed as a bonus but do NOT affect pass/fail.
 # Required scopes: read:user, read:repository, read:admin (or just "admin")
 # Generate token at: Settings → Applications → Generate New Token
-# CI_GITEA_TOKEN=your-admin-api-token
+# CI_GITEA_API_TOKEN=your-admin-api-token
+# Legacy CI_GITEA_TOKEN is also accepted.
 
 # Integration test API retries (optional, default: 3).
 # Number of times to retry API checks waiting for runner to appear.
@@ -50,6 +51,16 @@ GITEA_REGISTRATION_TOKEN=your-registration-token
 # Used by PIP_INSTALL to configure PIP_EXTRA_INDEX_URL
 CI_GITEA_USERNAME=your-gitea-username
 
+# Role-based Gitea API tokens (devx 0.40.0+)
+# DEVELOPER_GITEA_API_TOKEN is used by local `grm trigger-workflow` and `make create-pr`.
+# CI_GITEA_API_TOKEN is used by CI workflows (and accepted as a fallback for local tools).
+# REVIEWER_GITEA_API_TOKEN is used by CI to post APPROVE reviews; it must belong to a
+# different user than the PR author.
+# Legacy CI_GITEA_TOKEN and REVIEW_GITEA_TOKEN are accepted as fallbacks.
+# DEVELOPER_GITEA_API_TOKEN=your-developer-token
+# CI_GITEA_API_TOKEN=your-ci-token
+# REVIEWER_GITEA_API_TOKEN=your-reviewer-token
+
 # Vikunja API token (required for `make create-task` dev workflow)
 # Generate at: Vikunja → Settings → API Tokens
 # VIKUNJA_TOKEN=your-vikunja-api-token

.gitea/workflows/ci.yml

@@ -6,21 +6,38 @@ on:
   workflow_dispatch:
 
 env:
-  CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+  PIP_BREAK_SYSTEM_PACKAGES: "1"
+  PYTHONPATH: src
+  CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
   CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
 
 jobs:
-  quality:
+  # Single validation job that merges: quality, detect-changes,
+  # release-dry-run, pre-merge-check, pr-review, and discover-runners.
+  # Uses ci-full image (has git-cliff for release-dry-run).
+  # Saves ~5x checkout+setup overhead vs 6 separate jobs.
+  validate:
     runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest
-    timeout-minutes: 10
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        shell: bash
+    outputs:
+      ansible-changed: ${{ steps.detect.outputs.ansible-changed }}
+      user-facing-changed: ${{ steps.detect.outputs.user-facing-changed }}
+      runner-count: ${{ steps.discover-runners.outputs.runner-count }}
+      runner-indices: ${{ steps.discover-runners.outputs.runner-indices }}
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Set up environment
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
         run: make setup-image EXTRAS=ci,lint
+      # --- quality steps ---
       - name: Lint all
         run: |
           . .venv/bin/activate 2>/dev/null || true
@@ -30,19 +47,20 @@ jobs:
         run: |
           . .venv/bin/activate 2>/dev/null || true
           make pytest-cov
-      - name: Documentation lint check
+      - name: Documentation gate (coverage + stale refs + lint + version refs + prose)
         env:
-          PYTHONPATH: src
+          DEVX_DOC_COVERAGE_STRICT: "1"
+          DEVX_DOC_VERSIONS_PKG: grm
+          DEVX_VALE_LEVEL: warning
         run: |
           . .venv/bin/activate 2>/dev/null || true
-          python3 -m devx.ci.lint_docs --root .
+          export PATH="$HOME/.local/bin:$PATH"
+          make devx-docs-check
       - name: Translation completeness check
         run: |
           . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.ci.check_translations --translations src/grm/translations.json
       - name: Check unit test speed
-        env:
-          PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
@@ -63,52 +81,10 @@ jobs:
           else
             echo "act_runner not found — skipping workflow dry-run (static lint still passed)"
           fi
-
-  release-dry-run:
-    needs: [quality, detect-changes]
-    if: needs.detect-changes.outputs.user-facing-changed == 'true'
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Set up environment
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=ci,lint
-      - name: Release dry-run validation
-        env:
-          PYTHONPATH: src
-          DEVX_VERSION_FILE: src/grm/__init__.py
-          DEVX_TASK_PREFIX: GRM
-        run: |
-          . .venv/bin/activate 2>/dev/null || true
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.release --dry-run
-
-  detect-changes:
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
-    timeout-minutes: 10
-    outputs:
-      ansible-changed: ${{ steps.detect.outputs.ansible-changed }}
-      user-facing-changed: ${{ steps.detect.outputs.user-facing-changed }}
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Set up environment
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=ci
+      # --- detect-changes step ---
       - name: Detect changed paths
         id: detect
         env:
-          PYTHONPATH: src
           DEVX_TASK_PREFIX: GRM
         run: |
           . .venv/bin/activate 2>/dev/null || true
@@ -116,22 +92,10 @@ jobs:
             --base "origin/master" \
             --head "${{ github.event.pull_request.head.sha || github.sha }}" \
             --github-output
-
-  pre-merge-check:
-    needs: [quality, detect-changes]
-    if: github.event_name == 'pull_request'
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
-    timeout-minutes: 5
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Set up environment
-        run: make setup-image EXTRAS=ci
+      # --- validate-pr + pr-review steps (PR only) ---
       - name: Validate auto-merge preconditions
+        if: github.event_name == 'pull_request'
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
           DEVX_TASK_PREFIX: GRM
           DEVX_VIKUNJA_PROJECT_ID: 6
@@ -139,7 +103,6 @@ jobs:
           PR_TITLE: ${{ github.event.pull_request.title }}
           REPOSITORY: ${{ github.repository }}
           PR_NUMBER: ${{ github.event.number }}
-          PYTHONPATH: ${{ env.PYTHONPATH }}
         run: |
           . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.ci.check_auto_merge_ready \
@@ -147,52 +110,65 @@ jobs:
             --pr-title "$PR_TITLE" \
             --repo "$REPOSITORY" \
             --pr-number "$PR_NUMBER"
-
-  discover-runners:
-    needs: [detect-changes]
-    if: needs.detect-changes.outputs.ansible-changed == 'true'
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
-    timeout-minutes: 10
-    outputs:
-      runner-count: ${{ steps.discover.outputs.runner-count }}
-      runner-indices: ${{ steps.discover.outputs.runner-indices }}
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up environment
+      - name: Run automated PR review
+        if: github.event_name == 'pull_request'
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          set -euo pipefail
+          python3 -m devx.ci.pr_review \
+            "${{ github.event.number }}" \
+            "${{ github.repository }}"
+      # --- release-dry-run step (conditional) ---
+      - name: Release dry-run validation
+        if: steps.detect.outputs.user-facing-changed == 'true'
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=ci
-      - name: Discover available runners
-        id: discover
+          DEVX_VERSION_FILE: src/grm/__init__.py
+          DEVX_TASK_PREFIX: GRM
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          export PATH="$HOME/.local/bin:$PATH"
+          python3 -m devx.ci.release --dry-run
+      # --- discover-runners step (conditional on ansible-changed) ---
+      - name: Discover available molecule runners
+        id: discover-runners
+        if: steps.detect.outputs.ansible-changed == 'true'
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           MOLECULE_RUNNERS: ${{ vars.MOLECULE_RUNNERS }}
-          PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.molecule.discover_runners \
             --owner "${{ github.repository_owner }}" \
             --repo "${{ github.event.repository.name }}" \
             --github-output
+      - name: Notify on failure
+        if: failure()
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          export PATH="$HOME/.local/bin:$PATH"
+          python3 -m devx.ci.notify_failure --auto-login \
+            --repo "${{ github.repository }}" \
+            --run-id "${{ github.run_id }}" \
+            --workflow "ci/validate" \
+            --commit "${{ github.sha }}"
 
   molecule-tests:
-    needs: [quality, detect-changes, discover-runners]
-    if: needs.detect-changes.outputs.ansible-changed == 'true'
+    needs: [validate]
+    if: needs.validate.outputs.ansible-changed == 'true'
     runs-on: docker
     container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
-    timeout-minutes: 10
+    timeout-minutes: 15
     strategy:
       fail-fast: true
-      max-parallel: 3
+      max-parallel: 6
       matrix:
         runner-index: [1, 2, 3, 4, 5, 6]
     steps:
       - uses: actions/checkout@v4
       - name: Set up environment
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
         run: make setup-image EXTRAS=ci,molecule
       - name: Install Ansible collections
@@ -202,16 +178,25 @@ jobs:
       - name: Discover assigned test pairs
         env:
           RUNNER_INDEX: ${{ matrix.runner-index }}
-          MAX_RUNNERS: ${{ needs.discover-runners.outputs.runner-count }}
-          PYTHONPATH: src
+          MAX_RUNNERS: 6
         run: |
           . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.molecule.distribute_molecule \
             --runner-index "$RUNNER_INDEX" \
             --max-runners "$MAX_RUNNERS" \
-            --github-env --skip-if-excess
+            --github-env
       - name: Run molecule tests
         if: env.SKIP != 'true'
+        env:
+          GITEA_URL: ${{ github.server_url }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+          RUN_ID: ${{ github.run_id }}
+          ANSIBLE_INJECT_INVOCATION: "1"
+          JOB_NAME: ${{ github.job }}
+          MATRIX_INDEX: ${{ matrix.runner-index }}
+          GITEA_REPOSITORY: ${{ github.repository }}
+          DOCKER_HOST: unix:///var/run/docker.sock
         run: |
           . .venv/bin/activate 2>/dev/null || true
           if [ -z "$TEST_PAIRS" ]; then exit 0; fi
@@ -219,61 +204,22 @@ jobs:
             echo "Docker not available in CI container — skipping molecule tests"
             exit 0
           fi
-          echo "$CI_GITEA_TOKEN" | docker login git.oblachno.oblachno.fyi -u "$CI_GITEA_USERNAME" --password-stdin
+          _TOKEN="$CI_GITEA_API_TOKEN"; [ -z "$_TOKEN" ] && _TOKEN="$CI_GITEA_TOKEN"
+          [ -z "$_TOKEN" ] && { echo "Gitea API token not set — skipping Docker login"; exit 0; }
+          echo "$_TOKEN" | docker login git.oblachno.oblachno.fyi -u "$CI_GITEA_USERNAME" --password-stdin
           # shellcheck disable=SC2086 # intentional word splitting for argument expansion
           python3 -m devx.molecule.molecule_ci_guard $TEST_PAIRS
-        env:
-          GITEA_URL: ${{ github.server_url }}
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-          RUN_ID: ${{ github.run_id }}
-          ANSIBLE_INJECT_INVOCATION: "1"
-          JOB_NAME: ${{ github.job }}
-          MATRIX_INDEX: ${{ matrix.runner-index }}
-          GITEA_REPOSITORY: ${{ github.repository }}
-          PYTHONPATH: src
-          DOCKER_HOST: unix:///var/run/docker.sock
-
-  pr-review:
-    if: github.event_name == 'pull_request'
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
-    timeout-minutes: 10
-    defaults:
-      run:
-        shell: bash
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up environment
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=ci
-      - name: Run automated PR review
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          set -euo pipefail
-          . .venv/bin/activate 2>/dev/null || true
-          python3 -m devx.ci.pr_review \
-            "${{ github.event.number }}" \
-            "${{ github.repository }}"
 
   auto-merge:
-    # Auto-merge runs after all CI checks pass. It reads the task ID
-    # from the branch name, validates the PR title, and squash-merges.
+    # Auto-merge runs after validate + molecule-tests pass (or molecule is skipped).
     # Uses always() so it evaluates even when molecule-tests is skipped
     # (Gitea Actions skips dependent jobs of skipped jobs by default).
-    needs: [quality, detect-changes, pre-merge-check, pr-review, molecule-tests, release-dry-run]
+    needs: [validate, molecule-tests]
     if: >-
       always() &&
       github.event_name == 'pull_request' &&
-      needs.quality.result == 'success' &&
-      needs.pre-merge-check.result == 'success' &&
-      needs.pr-review.result == 'success' &&
-      (needs.molecule-tests.result == 'success' || needs.molecule-tests.result == 'skipped') &&
-      (needs.release-dry-run.result == 'success' || needs.release-dry-run.result == 'skipped')
+      needs.validate.result == 'success' &&
+      (needs.molecule-tests.result == 'success' || needs.molecule-tests.result == 'skipped')
     runs-on: docker
     container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
@@ -284,18 +230,17 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: ${{ secrets.CI_GITEA_TOKEN }}
+          token: ${{ secrets.CI_GITEA_API_TOKEN }}
       - name: Set up environment
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
         run: make setup-image EXTRAS=ci
       - name: Post approval review
         env:
-          CI_GITEA_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          REVIEWER_GITEA_API_TOKEN: ${{ secrets.REVIEWER_GITEA_API_TOKEN }}
           PR_NUMBER: ${{ github.event.number }}
           REPOSITORY: ${{ github.repository }}
-          PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.ci.pr_review \
@@ -304,12 +249,11 @@ jobs:
             --event APPROVE \
             --checklist-confirmed \
             --checklist-categories 1,2,3,4,5,6,7,8,9,10,11,12,13 \
-            --body "Auto-approved: all CI checks passed (quality, molecule, pr-review, pre-merge-check)."
+            --body "Auto-approved: all CI checks passed (validate, molecule-tests)."
       - name: Squash merge with task ID
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
-          PYTHONPATH: src
           DEVX_TASK_PREFIX: GRM
           DEVX_VIKUNJA_PROJECT_ID: 6
           HEAD_REF: ${{ github.head_ref }}

.gitea/workflows/post-merge.yml

@@ -1,115 +1,136 @@
 name: Post-merge
 
-# Runs on every push to master. A single workflow with conditional jobs
-# for release, publish, wiki sync, badges, and Vikunja task updates.
+# Runs on every push to master (after CI workflow merges a PR).
+# Consolidated into 2 jobs (from 7) to reduce runner overhead:
+#   detect-and-configure ──→ release-and-maintain
 #
-# Job dependency graph:
+# Job 1: detect release commit, validate commit msg, configure repo
+#        (branch protection, labels).
+# Job 2: release + publish + sync-wiki + vikunja + badges.
+#        Individual steps are conditional on job 1 outputs.
 #
-#   detect-type ──┬── validate-commit-msg (skip if release commit)
-#                 ├── release (skip if release commit)
-#                 │   └── publish (needs release — builds & publishes to PyPI)
-#                 ├── badges (ALWAYS runs — even on release commits)
-#                 ├── configure-repo (independent — skip if release commit)
-#                 ├── sync-wiki (skip if release commit — runs for ALL merges)
-#                 └── vikunja (skip if release commit — runs for ALL merges)
-#
-# sync-wiki and vikunja run for ALL non-release commits, not just when
-# release succeeds. This ensures the wiki and task tracker are updated
-# even for infrastructure-only changes (docs, CI config, etc.).
-#
-# The badges job uses `if: always()` with no is-release condition so it
-# runs on every push to master, including release commits. This ensures
-# badges (tests, coverage, version, etc.) are always current.
+# The badges step always runs (even on release commits) so version
+# badge picks up the new __version__. It runs last so it sees the
+# new version if release created one.
 #
 # When release creates a "release: vX.Y.Z" commit and tag, the publish
-# job (which depends on release) builds and publishes the package to the
-# Gitea PyPI registry. The release commit's post-merge run still updates
-# badges (version badge picks up the new version). Other jobs skip.
+# step builds and publishes the package to the Gitea PyPI registry.
+# The release commit's post-merge run still updates badges. Other
+# steps (sync-wiki, vikunja) skip on release commits.
 
 on:
   push:
     branches: [master]
   workflow_dispatch:
 
+concurrency:
+  group: post-merge-${{ github.ref }}
+  cancel-in-progress: true
+
 env:
-  CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+  PIP_BREAK_SYSTEM_PACKAGES: "1"
+  PYTHONPATH: src
+  CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
   CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
 
 jobs:
-  detect-type:
+  detect-and-configure:
     runs-on: docker
     container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
     outputs:
       is-release: ${{ steps.check.outputs.is-release }}
+      is-automated: ${{ steps.check.outputs.is-automated }}
+      user-facing-changed: ${{ steps.detect.outputs.user-facing-changed }}
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 1
+          fetch-depth: 0
       - name: Set up environment
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
         run: make setup-image EXTRAS=ci
+      - name: Ensure branch protection and labels
+        env:
+          DEVX_REPO_NAME: grm
+          DEVX_REPO_OWNER: oblachno-oss
+          DEVX_STATUS_CHECKS: "CI / validate (pull_request),CI / molecule-tests (1) (pull_request),CI / molecule-tests (2) (pull_request),CI / molecule-tests (3) (pull_request)"
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.tools.configure_repo
       - name: Check if this is a release commit
         id: check
-        env:
-          PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.ci.detect_release_commit
-
-  validate-commit-msg:
-    needs: [detect-type]
-    if: needs.detect-type.outputs.is-release == 'false'
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
-    timeout-minutes: 5
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-      - name: Set up environment
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=ci
       - name: Validate latest commit message
+        if: steps.check.outputs.is-automated == 'false'
         env:
-          PYTHONPATH: src
           DEVX_TASK_PREFIX: GRM
         run: |
           . .venv/bin/activate 2>/dev/null || true
           git log -1 --format=%B > commit-msg.txt
           python3 -m devx.ci.validate_commit_msg commit-msg.txt --branch master
           rm -f commit-msg.txt
+      - name: Detect changed paths
+        id: detect
+        if: steps.check.outputs.is-release == 'false'
+        env:
+          DEVX_TASK_PREFIX: GRM
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.ci.classify_changes \
+            --base "HEAD~1" \
+            --head "HEAD" \
+            --github-output
+      - name: Notify on failure
+        if: failure()
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          export PATH="$HOME/.local/bin:$PATH"
+          python3 -m devx.ci.notify_failure --auto-login \
+            --repo "${{ github.repository }}" \
+            --run-id "${{ github.run_id }}" \
+            --workflow "post-merge/detect-and-configure" \
+            --commit "${{ github.sha }}"
 
-  release:
-    needs: [detect-type]
-    if: needs.detect-type.outputs.is-release == 'false'
+  release-and-maintain:
+    needs: [detect-and-configure]
+    if: always() && needs.detect-and-configure.result == 'success'
     runs-on: docker
     container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
     timeout-minutes: 15
     outputs:
       tag: ${{ steps.release-tag.outputs.tag }}
+    defaults:
+      run:
+        shell: bash
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: ${{ secrets.CI_GITEA_TOKEN }}
+          ref: master
+          token: ${{ secrets.CI_GITEA_API_TOKEN }}
       - name: Set up environment
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
         run: make setup-image EXTRAS=ci,lint
       - name: Configure git
         run: |
           git config user.name "grm-ci-bot"
           git config user.email "grm-ci-bot@oblachno.fyi"
+      # --- release + publish (only if not a release commit) ---
       - name: Run release
         id: release-tag
+        if: needs.detect-and-configure.outputs.is-release == 'false' && needs.detect-and-configure.outputs.user-facing-changed == 'true'
         env:
-          PYTHONPATH: src
           DEVX_VERSION_FILE: src/grm/__init__.py
           DEVX_TASK_PREFIX: GRM
           DEVX_VIKUNJA_PROJECT_ID: 6
@@ -117,207 +138,54 @@ jobs:
           . .venv/bin/activate 2>/dev/null || true
           export PATH="$HOME/.local/bin:$PATH"
           python3 -m devx.ci.release
-      - name: Notify on failure
-        if: failure()
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          . .venv/bin/activate 2>/dev/null || true
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.notify_failure --auto-login \
-            --repo "${{ github.repository }}" \
-            --run-id "${{ github.run_id }}" \
-            --workflow "post-merge/release" \
-            --commit "${{ github.sha }}"
-
-  publish:
-    needs: [release]
-    if: needs.release.outputs.tag != ''
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          ref: ${{ needs.release.outputs.tag }}
-      - name: Set up environment
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=ci,lint
       - name: Build and publish release
+        if: steps.release-tag.outputs.tag != ''
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: |
           . .venv/bin/activate 2>/dev/null || true
           export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.publish \
-            "${{ needs.release.outputs.tag }}" \
-            "${{ github.repository }}" --auto-login
-      - name: Notify on failure
-        if: failure()
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          . .venv/bin/activate 2>/dev/null || true
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.notify_failure --auto-login \
-            --repo "${{ github.repository }}" \
-            --run-id "${{ github.run_id }}" \
-            --workflow "post-merge/publish" \
-            --commit "${{ github.sha }}"
-
-  sync-wiki:
-    needs: [detect-type]
-    if: needs.detect-type.outputs.is-release == 'false'
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
-    timeout-minutes: 15
-    concurrency:
-      group: sync-wiki-${{ github.repository }}
-      cancel-in-progress: false
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Set up environment
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=ci
+          git fetch --tags
+          git checkout "${{ steps.release-tag.outputs.tag }}"
+          python3 -m devx.ci.publish "${{ steps.release-tag.outputs.tag }}" "${{ github.repository }}" --auto-login
+      # --- sync-wiki + vikunja (skip on automated/release commits) ---
       - name: Sync documentation to wiki
+        if: needs.detect-and-configure.outputs.is-automated == 'false'
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: |
           . .venv/bin/activate 2>/dev/null || true
-          python3 -m devx.ci.sync_wiki --repo "${{ github.repository }}" --strict
-      - name: Notify on failure
-        if: failure()
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.notify_failure --auto-login \
-            --repo "${{ github.repository }}" \
-            --run-id "${{ github.run_id }}" \
-            --workflow "post-merge/sync-wiki" \
-            --commit "${{ github.sha }}"
-
-  badges:
-    needs: [detect-type]
-    if: always()
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          ref: master
-          token: ${{ secrets.CI_GITEA_TOKEN }}
-      - name: Fetch latest master
-        run: |
-          git fetch origin master
-          git reset --hard origin/master
-      - name: Set up environment
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=lint
-      - name: Generate and push badges
-        env:
-          PRE_COMMIT_ALLOW_NO_CONFIG: "1"
-        run: |
-          . .venv/bin/activate 2>/dev/null || true
-          python3 -m devx.ci.push_badges
-      - name: Notify on failure
-        if: failure()
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.notify_failure --auto-login \
-            --repo "${{ github.repository }}" \
-            --run-id "${{ github.run_id }}" \
-            --workflow "post-merge/badges" \
-            --commit "${{ github.sha }}"
-
-  vikunja:
-    needs: [detect-type]
-    if: needs.detect-type.outputs.is-release == 'false'
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Set up environment
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=ci
+          python3 -m devx.ci.sync_wiki --repo "${{ github.repository }}" --verify
       - name: Update Vikunja task
+        if: needs.detect-and-configure.outputs.is-automated == 'false'
         env:
           VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
-          PYTHONPATH: src
           DEVX_TASK_PREFIX: GRM
           DEVX_VIKUNJA_PROJECT_ID: 6
         run: |
           . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.ci.post_merge --git-sha "${{ github.sha }}"
-      - name: Notify on failure
-        if: failure()
+      # --- badges (always run — even on release commits) ---
+      - name: Generate and push badges
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.notify_failure --auto-login \
-            --repo "${{ github.repository }}" \
-            --run-id "${{ github.run_id }}" \
-            --workflow "post-merge/vikunja" \
-            --commit "${{ github.sha }}"
-
-  configure-repo:
-    needs: [detect-type]
-    if: needs.detect-type.outputs.is-release == 'false'
-    runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up environment
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=ci
-      - name: Ensure branch protection and labels
-        env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
-          DEVX_REPO_NAME: grm
-          DEVX_REPO_OWNER: oblachno-oss
-          DEVX_STATUS_CHECKS: "CI / quality (pull_request),CI / molecule-tests (1) (pull_request),CI / molecule-tests (2) (pull_request),CI / molecule-tests (3) (pull_request)"
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
+          PRE_COMMIT_ALLOW_NO_CONFIG: "1"
         run: |
           . .venv/bin/activate 2>/dev/null || true
-          python3 -m devx.tools.configure_repo
+          export PATH="$HOME/.local/bin:$PATH"
+          # Fetch latest master to pick up any release commit that was pushed
+          git fetch origin master
+          git reset --hard origin/master
+          python3 -m devx.ci.push_badges
       - name: Notify on failure
         if: failure()
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          PYTHONPATH: src
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: |
+          . .venv/bin/activate 2>/dev/null || true
           export PATH="$HOME/.local/bin:$PATH"
           python3 -m devx.ci.notify_failure --auto-login \
             --repo "${{ github.repository }}" \
             --run-id "${{ github.run_id }}" \
-            --workflow "post-merge/configure-repo" \
+            --workflow "post-merge/release-and-maintain" \
             --commit "${{ github.sha }}"

.pre-commit-config.yaml

@@ -81,11 +81,12 @@ repos:
         pass_filenames: false
         stages: [pre-commit]
 
-      - id: lint-docs
-        name: documentation lint check
-        entry: env PYTHONPATH=src .venv/bin/python -m devx.ci.lint_docs --root .
+      - id: docs-check
+        name: documentation gate (coverage + stale refs + lint + version refs + prose)
+        entry: bash -c 'PYTHONPATH=src DEVX_DOC_COVERAGE_STRICT=1 DEVX_DOC_VERSIONS_PKG=grm DEVX_VALE_LEVEL=warning make devx-docs-check'
         language: system
         pass_filenames: false
+        always_run: true
         stages: [pre-commit]
 
       - id: pytest-cov

.vale.ini

@@ -0,0 +1,51 @@
+# Vale configuration for grm documentation
+# https://vale.sh/docs/
+
+StylesPath = .vale/styles
+
+# Packages are downloaded via `vale sync`
+Packages = write-good, Google, Readability
+
+# Minimum alert level to display (suggestion, warning, error)
+MinAlertLevel = warning
+
+# Project vocabulary — terms not flagged as spelling errors
+Vocab = grm
+
+[*.{md}]
+# Enable style guides
+BasedOnStyles = Vale, write-good, Google, Readability, devx
+
+# Google style — relax rules too strict for technical docs
+Google.Contractions = NO
+Google.WordList = NO
+Google.Acronyms = NO
+Google.We = NO
+Google.Will = NO
+Google.Colons = NO
+Google.Headings = NO
+Google.EmDash = NO
+Google.Units = NO
+Google.Latin = NO
+Google.OptionalPlurals = NO
+
+# write-good — relax rules too strict for technical writing
+write-good.E-Prime = NO
+write-good.So = NO
+write-good.ThereIs = NO
+write-good.TooWordy = NO
+write-good.Passive = NO
+
+# Vale defaults — spelling catches too many technical terms
+Vale.Terms = NO
+Vale.Repetition = NO
+Vale.Spelling = NO
+
+# Readability — technical docs are naturally complex, downgrade to suggestions
+Readability.FleschReadingEase = suggestion
+Readability.FleschKincaid = suggestion
+Readability.AutomatedReadability = suggestion
+Readability.ColemanLiau = suggestion
+Readability.LIX = suggestion
+Readability.GunningFog = suggestion
+Readability.SMOG = suggestion

.vale/styles/Google/AMPM.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'AM' or 'PM' (preceded by a space)."
+link: "https://developers.google.com/style/word-list"
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}[AP]M\b'
+  - '\d{1,2} ?[ap]m\b'
+  - '\d{1,2} ?[aApP]\.[mM]\.'

.vale/styles/Google/Acronyms.yml

@@ -0,0 +1,64 @@
+extends: conditional
+message: "Spell out '%s', if it's unfamiliar to the audience."
+link: 'https://developers.google.com/style/abbreviations'
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP

.vale/styles/Google/Colons.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "'%s' should be in lowercase."
+link: 'https://developers.google.com/style/colons'
+nonword: true
+level: warning
+scope: sentence
+tokens:
+  - '(?<!:[^ ]+?):\s[A-Z]'

.vale/styles/Google/Contractions.yml

@@ -0,0 +1,30 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://developers.google.com/style/contractions'
+level: suggestion
+ignorecase: true
+action:
+  name: replace
+swap:
+  are not: aren't
+  cannot: can't
+  could not: couldn't
+  did not: didn't
+  do not: don't
+  does not: doesn't
+  has not: hasn't
+  have not: haven't
+  how is: how's
+  is not: isn't
+  it is: it's
+  should not: shouldn't
+  that is: that's
+  they are: they're
+  was not: wasn't
+  we are: we're
+  we have: we've
+  were not: weren't
+  what is: what's
+  when is: when's
+  where is: where's
+  will not: won't

.vale/styles/Google/DateFormat.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'July 31, 2016' format, not '%s'."
+link: 'https://developers.google.com/style/dates-times'
+ignorecase: true
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
+  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}'

.vale/styles/Google/Ellipses.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "In general, don't use an ellipsis."
+link: 'https://developers.google.com/style/ellipses'
+nonword: true
+level: warning
+action:
+  name: remove
+tokens:
+  - '\.\.\.'

.vale/styles/Google/EmDash.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a space before or after a dash."
+link: "https://developers.google.com/style/dashes"
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim
+    - " "
+tokens:
+  - '\s[—–]\s'
+

.vale/styles/Google/Exclamation.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't use exclamation points in text."
+link: "https://developers.google.com/style/exclamation-points"
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim_right
+    - "!"
+tokens:
+  - '\w+!(?:\s|$)'

.vale/styles/Google/FirstPerson.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid first-person pronouns such as '%s'."
+link: 'https://developers.google.com/style/pronouns#personal-pronouns'
+ignorecase: true
+level: warning
+nonword: true
+tokens:
+  - (?:^|\s)I\s
+  - (?:^|\s)I,\s
+  - \bI'm\b
+  - \bme\b
+  - \bmy\b
+  - \bmine\b

.vale/styles/Google/Gender.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Don't use '%s' as a gender-neutral pronoun."
+link: 'https://developers.google.com/style/pronouns#gender-neutral-pronouns'
+level: error
+ignorecase: true
+tokens:
+  - he/she
+  - s/he
+  - \(s\)he

.vale/styles/Google/GenderBias.yml

@@ -0,0 +1,43 @@
+extends: substitution
+message: "Consider using '%s' instead of '%s'."
+ignorecase: true
+link: "https://developers.google.com/style/inclusive-documentation"
+level: error
+action:
+  name: replace
+swap:
+  (?:alumna|alumnus): graduate
+  (?:alumnae|alumni): graduates
+  air(?:m[ae]n|wom[ae]n): pilot(s)
+  anchor(?:m[ae]n|wom[ae]n): anchor(s)
+  authoress: author
+  camera(?:m[ae]n|wom[ae]n): camera operator(s)
+  door(?:m[ae]|wom[ae]n): concierge(s)
+  draft(?:m[ae]n|wom[ae]n): drafter(s)
+  fire(?:m[ae]n|wom[ae]n): firefighter(s)
+  fisher(?:m[ae]n|wom[ae]n): fisher(s)
+  fresh(?:m[ae]n|wom[ae]n): first-year student(s)
+  garbage(?:m[ae]n|wom[ae]n): waste collector(s)
+  lady lawyer: lawyer
+  ladylike: courteous
+  mail(?:m[ae]n|wom[ae]n): mail carriers
+  man and wife: husband and wife
+  man enough: strong enough
+  mankind: human kind|humanity
+  manmade: manufactured
+  manpower: personnel
+  middle(?:m[ae]n|wom[ae]n): intermediary
+  news(?:m[ae]n|wom[ae]n): journalist(s)
+  ombuds(?:man|woman): ombuds
+  oneupmanship: upstaging
+  poetess: poet
+  police(?:m[ae]n|wom[ae]n): police officer(s)
+  repair(?:m[ae]n|wom[ae]n): technician(s)
+  sales(?:m[ae]n|wom[ae]n): salesperson or sales people
+  service(?:m[ae]n|wom[ae]n): soldier(s)
+  steward(?:ess)?: flight attendant
+  tribes(?:m[ae]n|wom[ae]n): tribe member(s)
+  waitress: waiter
+  woman doctor: doctor
+  woman scientist[s]?: scientist(s)
+  work(?:m[ae]n|wom[ae]n): worker(s)

.vale/styles/Google/HeadingPunctuation.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a period at the end of a heading."
+link: "https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings"
+nonword: true
+level: warning
+scope: heading
+action:
+  name: edit
+  params:
+    - trim_right
+    - "."
+tokens:
+  - '[a-z0-9][.]\s*$'

.vale/styles/Google/Headings.yml

@@ -0,0 +1,29 @@
+extends: capitalization
+message: "'%s' should use sentence-style capitalization."
+link: "https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings"
+level: warning
+scope: heading
+match: $sentence
+indicators:
+  - ":"
+exceptions:
+  - Azure
+  - CLI
+  - Cosmos
+  - Docker
+  - Emmet
+  - gRPC
+  - I
+  - Kubernetes
+  - Linux
+  - macOS
+  - Marketplace
+  - MongoDB
+  - REPL
+  - Studio
+  - TypeScript
+  - URLs
+  - Visual
+  - VS
+  - Windows
+  - JSON

.vale/styles/Google/Latin.yml

@@ -0,0 +1,11 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://developers.google.com/style/abbreviations'
+ignorecase: true
+level: error
+nonword: true
+action:
+  name: replace
+swap:
+  '\b(?:eg|e\.g\.)(?=[\s,;])': for example
+  '\b(?:ie|i\.e\.)(?=[\s,;])': that is

.vale/styles/Google/LyHyphens.yml

@@ -0,0 +1,14 @@
+extends: existence
+message: "'%s' doesn't need a hyphen."
+link: "https://developers.google.com/style/hyphens"
+level: error
+ignorecase: false
+nonword: true
+action:
+  name: edit
+  params:
+    - regex
+    - "-"
+    - " "
+tokens:
+  - '\b[^\s-]+ly-\w+\b'

.vale/styles/Google/OptionalPlurals.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't use plurals in parentheses such as in '%s'."
+link: "https://developers.google.com/style/plurals-parentheses"
+level: error
+nonword: true
+action:
+  name: edit
+  params:
+    - trim_right
+    - "(s)"
+tokens:
+  - '\b\w+\(s\)'

.vale/styles/Google/Ordinal.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Spell out all ordinal numbers ('%s') in text."
+link: 'https://developers.google.com/style/numbers'
+level: error
+nonword: true
+tokens:
+  - \d+(?:st|nd|rd|th)

.vale/styles/Google/OxfordComma.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Use the Oxford comma in '%s'."
+link: 'https://developers.google.com/style/commas'
+scope: sentence
+level: warning
+tokens:
+  - '(?:[^,]+,){1,}\s\w+\s(?:and|or)'

.vale/styles/Google/Parens.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Use parentheses judiciously."
+link: 'https://developers.google.com/style/parentheses'
+nonword: true
+level: suggestion
+tokens:
+  - '\(.+\)'

.vale/styles/Google/Passive.yml

@@ -0,0 +1,184 @@
+extends: existence
+link: 'https://developers.google.com/style/voice'
+message: "In general, use active voice instead of passive voice ('%s')."
+ignorecase: true
+level: suggestion
+raw:
+  - \b(am|are|were|being|is|been|was|be)\b\s*
+tokens:
+  - '[\w]+ed'
+  - awoken
+  - beat
+  - become
+  - been
+  - begun
+  - bent
+  - beset
+  - bet
+  - bid
+  - bidden
+  - bitten
+  - bled
+  - blown
+  - born
+  - bought
+  - bound
+  - bred
+  - broadcast
+  - broken
+  - brought
+  - built
+  - burnt
+  - burst
+  - cast
+  - caught
+  - chosen
+  - clung
+  - come
+  - cost
+  - crept
+  - cut
+  - dealt
+  - dived
+  - done
+  - drawn
+  - dreamt
+  - driven
+  - drunk
+  - dug
+  - eaten
+  - fallen
+  - fed
+  - felt
+  - fit
+  - fled
+  - flown
+  - flung
+  - forbidden
+  - foregone
+  - forgiven
+  - forgotten
+  - forsaken
+  - fought
+  - found
+  - frozen
+  - given
+  - gone
+  - gotten
+  - ground
+  - grown
+  - heard
+  - held
+  - hidden
+  - hit
+  - hung
+  - hurt
+  - kept
+  - knelt
+  - knit
+  - known
+  - laid
+  - lain
+  - leapt
+  - learnt
+  - led
+  - left
+  - lent
+  - let
+  - lighted
+  - lost
+  - made
+  - meant
+  - met
+  - misspelt
+  - mistaken
+  - mown
+  - overcome
+  - overdone
+  - overtaken
+  - overthrown
+  - paid
+  - pled
+  - proven
+  - put
+  - quit
+  - read
+  - rid
+  - ridden
+  - risen
+  - run
+  - rung
+  - said
+  - sat
+  - sawn
+  - seen
+  - sent
+  - set
+  - sewn
+  - shaken
+  - shaven
+  - shed
+  - shod
+  - shone
+  - shorn
+  - shot
+  - shown
+  - shrunk
+  - shut
+  - slain
+  - slept
+  - slid
+  - slit
+  - slung
+  - smitten
+  - sold
+  - sought
+  - sown
+  - sped
+  - spent
+  - spilt
+  - spit
+  - split
+  - spoken
+  - spread
+  - sprung
+  - spun
+  - stolen
+  - stood
+  - stridden
+  - striven
+  - struck
+  - strung
+  - stuck
+  - stung
+  - stunk
+  - sung
+  - sunk
+  - swept
+  - swollen
+  - sworn
+  - swum
+  - swung
+  - taken
+  - taught
+  - thought
+  - thrived
+  - thrown
+  - thrust
+  - told
+  - torn
+  - trodden
+  - understood
+  - upheld
+  - upset
+  - wed
+  - wept
+  - withheld
+  - withstood
+  - woken
+  - won
+  - worn
+  - wound
+  - woven
+  - written
+  - wrung

.vale/styles/Google/Periods.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Don't use periods with acronyms or initialisms such as '%s'."
+link: 'https://developers.google.com/style/abbreviations'
+level: error
+nonword: true
+tokens:
+  - '\b(?:[A-Z]\.){3,}'

.vale/styles/Google/Quotes.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Commas and periods go inside quotation marks."
+link: 'https://developers.google.com/style/quotation-marks'
+level: error
+nonword: true
+tokens:
+  - '"[^"]+"[.,?]'

.vale/styles/Google/Ranges.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Don't add words such as 'from' or 'between' to describe a range of numbers."
+link: 'https://developers.google.com/style/hyphens'
+nonword: true
+level: warning
+tokens:
+  - '(?:from|between)\s\d+\s?-\s?\d+'

.vale/styles/Google/Semicolons.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Use semicolons judiciously."
+link: 'https://developers.google.com/style/semicolons'
+nonword: true
+scope: sentence
+level: suggestion
+tokens:
+  - ';'

.vale/styles/Google/Slang.yml

@@ -0,0 +1,11 @@
+extends: existence
+message: "Don't use internet slang abbreviations such as '%s'."
+link: 'https://developers.google.com/style/abbreviations'
+ignorecase: true
+level: error
+tokens:
+  - 'tl;dr'
+  - ymmv
+  - rtfm
+  - imo
+  - fwiw

.vale/styles/Google/Spacing.yml

@@ -0,0 +1,10 @@
+extends: existence
+message: "'%s' should have one space."
+link: 'https://developers.google.com/style/sentence-spacing'
+level: error
+nonword: true
+action:
+  name: remove
+tokens:
+  - '[a-z][.?!] {2,}[A-Z]'
+  - '[a-z][.?!][A-Z]'

.vale/styles/Google/Spelling.yml

@@ -0,0 +1,10 @@
+extends: existence
+message: "In general, use American spelling instead of '%s'."
+link: 'https://developers.google.com/style/spelling'
+ignorecase: true
+level: warning
+tokens:
+  - '(?:\w+)nised?'
+  - 'colour'
+  - 'labour'
+  - 'centre'

.vale/styles/Google/Units.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Put a nonbreaking space between the number and the unit in '%s'."
+link: "https://developers.google.com/style/units-of-measure"
+nonword: true
+level: error
+tokens:
+  - \b\d+(?:B|kB|MB|GB|TB)
+  - \b\d+(?:ns|ms|s|min|h|d)

.vale/styles/Google/We.yml

@@ -0,0 +1,11 @@
+extends: existence
+message: "Try to avoid using first-person plural like '%s'."
+link: 'https://developers.google.com/style/pronouns#personal-pronouns'
+level: warning
+ignorecase: true
+tokens:
+  - we
+  - we'(?:ve|re)
+  - ours?
+  - us
+  - let's

.vale/styles/Google/Will.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Avoid using '%s'."
+link: 'https://developers.google.com/style/tense'
+ignorecase: true
+level: warning
+tokens:
+  - will

.vale/styles/Google/WordList.yml

@@ -0,0 +1,80 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: "https://developers.google.com/style/word-list"
+level: warning
+ignorecase: false
+action:
+  name: replace
+swap:
+  "(?:API Console|dev|developer) key": API key
+  "(?:cell ?phone|smart ?phone)": phone|mobile phone
+  "(?:dev|developer|APIs) console": API console
+  "(?:e-mail|Email|E-mail)": email
+  "(?:file ?path|path ?name)": path
+  "(?:kill|terminate|abort)": stop|exit|cancel|end
+  "(?:OAuth ?2|Oauth)": OAuth 2.0
+  "(?:ok|Okay)": OK|okay
+  "(?:WiFi|wifi)": Wi-Fi
+  '[\.]+apk': APK
+  '3\-D': 3D
+  'Google (?:I\-O|IO)': Google I/O
+  "tap (?:&|and) hold": touch & hold
+  "un(?:check|select)": clear
+  above: preceding
+  account name: username
+  action bar: app bar
+  admin: administrator
+  Ajax: AJAX
+  a\.k\.a|aka: or|also known as
+  Android device: Android-powered device
+  android: Android
+  API explorer: APIs Explorer
+  application: app
+  approx\.: approximately
+  authN: authentication
+  authZ: authorization
+  autoupdate: automatically update
+  cellular data: mobile data
+  cellular network: mobile network
+  chapter: documents|pages|sections
+  check box: checkbox
+  CLI: command-line tool
+  click on: click|click in
+  Cloud: Google Cloud Platform|GCP
+  Container Engine: Kubernetes Engine
+  content type: media type
+  curated roles: predefined roles
+  data are: data is
+  Developers Console: Google API Console|API Console
+  disabled?: turn off|off
+  ephemeral IP address: ephemeral external IP address
+  fewer data: less data
+  file name: filename
+  firewalls: firewall rules
+  functionality: capability|feature
+  Google account: Google Account
+  Google accounts: Google Accounts
+  Googling: search with Google
+  grayed-out: unavailable
+  HTTPs: HTTPS
+  in order to: to
+  ingest: import|load
+  k8s: Kubernetes
+  long press: touch & hold
+  network IP address: internal IP address
+  omnibox: address bar
+  open-source: open source
+  overview screen: recents screen
+  regex: regular expression
+  SHA1: SHA-1|HAS-SHA1
+  sign into: sign in to
+  sign-?on: single sign-on
+  static IP address: static external IP address
+  stylesheet: style sheet
+  synch: sync
+  tablename: table name
+  tablet: device
+  touch: tap
+  url: URL
+  vs\.: versus
+  World Wide Web: web

.vale/styles/Google/meta.json

@@ -0,0 +1,4 @@
+{
+  "feed": "https://github.com/errata-ai/Google/releases.atom",
+  "vale_version": ">=1.0.0"
+}

.vale/styles/Readability/AutomatedReadability.yml

@@ -0,0 +1,8 @@
+extends: metric
+message: "Try to keep the Automated Readability Index (%s) below 8."
+link: https://en.wikipedia.org/wiki/Automated_readability_index
+
+formula: |
+  (4.71 * (characters / words)) + (0.5 * (words / sentences)) - 21.43
+
+condition: "> 8"

.vale/styles/Readability/ColemanLiau.yml

@@ -0,0 +1,8 @@
+extends: metric
+message: "Try to keep the Coleman–Liau Index grade (%s) below 9."
+link: https://en.wikipedia.org/wiki/Coleman%E2%80%93Liau_index
+
+formula: |
+  (0.0588 * (characters / words) * 100) - (0.296 * (sentences / words) * 100) - 15.8
+
+condition: "> 9"

.vale/styles/Readability/FleschKincaid.yml

@@ -0,0 +1,8 @@
+extends: metric
+message: "Try to keep the Flesch–Kincaid grade level (%s) below 8."
+link: https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests
+
+formula: |
+  (0.39 * (words / sentences)) + (11.8 * (syllables / words)) - 15.59
+
+condition: "> 8"

.vale/styles/Readability/FleschReadingEase.yml

@@ -0,0 +1,8 @@
+extends: metric
+message: "Try to keep the Flesch reading ease score (%s) above 70."
+link: https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests
+
+formula: |
+  206.835 - (1.015 * (words / sentences)) - (84.6 * (syllables / words))
+
+condition: "< 70"

.vale/styles/Readability/GunningFog.yml

@@ -0,0 +1,8 @@
+extends: metric
+message: "Try to keep the Gunning-Fog index (%s) below 10."
+link: https://en.wikipedia.org/wiki/Gunning_fog_index
+
+formula: |
+  0.4 * ((words / sentences) + 100 * (complex_words / words))
+
+condition: "> 10"

.vale/styles/Readability/LIX.yml

@@ -0,0 +1,17 @@
+extends: metric
+message: "Try to keep the LIX score (%s) below 35."
+
+link: https://en.wikipedia.org/wiki/Lix_(readability_test)
+# Very Easy: 20 - 25
+#
+# Easy: 30 - 35
+#
+# Medium: 40 - 45
+#
+# Difficult: 50 - 55
+#
+# Very Difficult: 60+
+formula: |
+  (words / sentences) + ((long_words * 100) / words)
+
+condition: "> 35"

.vale/styles/Readability/SMOG.yml

@@ -0,0 +1,8 @@
+extends: metric
+message: "Try to keep the SMOG grade (%s) below 10."
+link: https://en.wikipedia.org/wiki/SMOG
+
+formula: |
+  1.0430 * math.sqrt((polysyllabic_words * 30.0) / sentences) + 3.1291
+
+condition: "> 10"

.vale/styles/Readability/meta.json

@@ -0,0 +1,4 @@
+{
+  "feed": "https://github.com/errata-ai/Readability/releases.atom",
+  "vale_version": ">=2.13.0"
+}

.vale/styles/config/vocabularies/grm/accept.txt

@@ -0,0 +1,42 @@
+devx
+grm
+GRM
+Gitea
+ZITADEL
+OpenTofu
+Ansible
+Vaultwarden
+Nextcloud
+Vikunja
+Mattermost
+Prometheus
+Grafana
+Loki
+Alertmanager
+Promtail
+pyproject
+tofu
+act_runner
+actionlint
+hadolint
+git-cliff
+pre-commit
+semver
+changelog
+idempotent
+rootless
+OIDC
+SSO
+SAML
+LDAP
+pytest
+molecule
+ruff
+pyright
+bandit
+Vale
+oblachno
+Oblachno
+Bulgarian
+gitea-runner
+runner

.vale/styles/devx/CodeBlockLanguage.yml

@@ -0,0 +1,6 @@
+extends: existence
+message: "Unlabeled code block — add a language tag (```bash, ```yaml, etc.)"
+level: warning
+scope: raw
+raw:
+  - '(?ms)^\n```\n.*?^```\s*$'

.vale/styles/devx/Condescending.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid '%s' — it's condescending in technical documentation"
+level: warning
+ignorecase: true
+tokens:
+  - '\bsimply\b'
+  - '\bjust\b'
+  - '\bobviously\b'
+  - '\bof course\b'
+  - '\bas you (can )?see\b'
+  - '\beasily\b'
+  - '\btrivial\b'
+  - '\bstraightforward\b'

.vale/styles/devx/README.md

@@ -0,0 +1,3 @@
+# Custom Vale style for devx documentation
+
+Project-specific terminology and style rules

.vale/styles/devx/Terminology.yml

@@ -0,0 +1,11 @@
+extends: substitution
+message: "Use '%s' instead of '%s' (terminology consistency)"
+level: error
+ignorecase: false
+swap:
+  '\b(?i)gitea\b': Gitea
+  '\b(?i)zitadel\b': ZITADEL
+  '\b(?i)opentofu\b': OpenTofu
+  '\b(?i)vaultwarden\b': Vaultwarden
+  '\b(?i)nextcloud\b': Nextcloud
+  '\b(?i)mattermost\b': Mattermost

.vale/styles/write-good/Cliches.yml

@@ -0,0 +1,702 @@
+extends: existence
+message: "Try to avoid using clichés like '%s'."
+ignorecase: true
+level: warning
+tokens:
+  - a chip off the old block
+  - a clean slate
+  - a dark and stormy night
+  - a far cry
+  - a fine kettle of fish
+  - a loose cannon
+  - a penny saved is a penny earned
+  - a tough row to hoe
+  - a word to the wise
+  - ace in the hole
+  - acid test
+  - add insult to injury
+  - against all odds
+  - air your dirty laundry
+  - all fun and games
+  - all in a day's work
+  - all talk, no action
+  - all thumbs
+  - all your eggs in one basket
+  - all's fair in love and war
+  - all's well that ends well
+  - almighty dollar
+  - American as apple pie
+  - an axe to grind
+  - another day, another dollar
+  - armed to the teeth
+  - as luck would have it
+  - as old as time
+  - as the crow flies
+  - at loose ends
+  - at my wits end
+  - avoid like the plague
+  - babe in the woods
+  - back against the wall
+  - back in the saddle
+  - back to square one
+  - back to the drawing board
+  - bad to the bone
+  - badge of honor
+  - bald faced liar
+  - ballpark figure
+  - banging your head against a brick wall
+  - baptism by fire
+  - barking up the wrong tree
+  - bat out of hell
+  - be all and end all
+  - beat a dead horse
+  - beat around the bush
+  - been there, done that
+  - beggars can't be choosers
+  - behind the eight ball
+  - bend over backwards
+  - benefit of the doubt
+  - bent out of shape
+  - best thing since sliced bread
+  - bet your bottom dollar
+  - better half
+  - better late than never
+  - better mousetrap
+  - better safe than sorry
+  - between a rock and a hard place
+  - beyond the pale
+  - bide your time
+  - big as life
+  - big cheese
+  - big fish in a small pond
+  - big man on campus
+  - bigger they are the harder they fall
+  - bird in the hand
+  - bird's eye view
+  - birds and the bees
+  - birds of a feather flock together
+  - bit the hand that feeds you
+  - bite the bullet
+  - bite the dust
+  - bitten off more than he can chew
+  - black as coal
+  - black as pitch
+  - black as the ace of spades
+  - blast from the past
+  - bleeding heart
+  - blessing in disguise
+  - blind ambition
+  - blind as a bat
+  - blind leading the blind
+  - blood is thicker than water
+  - blood sweat and tears
+  - blow off steam
+  - blow your own horn
+  - blushing bride
+  - boils down to
+  - bolt from the blue
+  - bone to pick
+  - bored stiff
+  - bored to tears
+  - bottomless pit
+  - boys will be boys
+  - bright and early
+  - brings home the bacon
+  - broad across the beam
+  - broken record
+  - brought back to reality
+  - bull by the horns
+  - bull in a china shop
+  - burn the midnight oil
+  - burning question
+  - burning the candle at both ends
+  - burst your bubble
+  - bury the hatchet
+  - busy as a bee
+  - by hook or by crook
+  - call a spade a spade
+  - called onto the carpet
+  - calm before the storm
+  - can of worms
+  - can't cut the mustard
+  - can't hold a candle to
+  - case of mistaken identity
+  - cat got your tongue
+  - cat's meow
+  - caught in the crossfire
+  - caught red-handed
+  - checkered past
+  - chomping at the bit
+  - cleanliness is next to godliness
+  - clear as a bell
+  - clear as mud
+  - close to the vest
+  - cock and bull story
+  - cold shoulder
+  - come hell or high water
+  - cool as a cucumber
+  - cool, calm, and collected
+  - cost a king's ransom
+  - count your blessings
+  - crack of dawn
+  - crash course
+  - creature comforts
+  - cross that bridge when you come to it
+  - crushing blow
+  - cry like a baby
+  - cry me a river
+  - cry over spilt milk
+  - crystal clear
+  - curiosity killed the cat
+  - cut and dried
+  - cut through the red tape
+  - cut to the chase
+  - cute as a bugs ear
+  - cute as a button
+  - cute as a puppy
+  - cuts to the quick
+  - dark before the dawn
+  - day in, day out
+  - dead as a doornail
+  - devil is in the details
+  - dime a dozen
+  - divide and conquer
+  - dog and pony show
+  - dog days
+  - dog eat dog
+  - dog tired
+  - don't burn your bridges
+  - don't count your chickens
+  - don't look a gift horse in the mouth
+  - don't rock the boat
+  - don't step on anyone's toes
+  - don't take any wooden nickels
+  - down and out
+  - down at the heels
+  - down in the dumps
+  - down the hatch
+  - down to earth
+  - draw the line
+  - dressed to kill
+  - dressed to the nines
+  - drives me up the wall
+  - dull as dishwater
+  - dyed in the wool
+  - eagle eye
+  - ear to the ground
+  - early bird catches the worm
+  - easier said than done
+  - easy as pie
+  - eat your heart out
+  - eat your words
+  - eleventh hour
+  - even the playing field
+  - every dog has its day
+  - every fiber of my being
+  - everything but the kitchen sink
+  - eye for an eye
+  - face the music
+  - facts of life
+  - fair weather friend
+  - fall by the wayside
+  - fan the flames
+  - feast or famine
+  - feather your nest
+  - feathered friends
+  - few and far between
+  - fifteen minutes of fame
+  - filthy vermin
+  - fine kettle of fish
+  - fish out of water
+  - fishing for a compliment
+  - fit as a fiddle
+  - fit the bill
+  - fit to be tied
+  - flash in the pan
+  - flat as a pancake
+  - flip your lid
+  - flog a dead horse
+  - fly by night
+  - fly the coop
+  - follow your heart
+  - for all intents and purposes
+  - for the birds
+  - for what it's worth
+  - force of nature
+  - force to be reckoned with
+  - forgive and forget
+  - fox in the henhouse
+  - free and easy
+  - free as a bird
+  - fresh as a daisy
+  - full steam ahead
+  - fun in the sun
+  - garbage in, garbage out
+  - gentle as a lamb
+  - get a kick out of
+  - get a leg up
+  - get down and dirty
+  - get the lead out
+  - get to the bottom of
+  - get your feet wet
+  - gets my goat
+  - gilding the lily
+  - give and take
+  - go against the grain
+  - go at it tooth and nail
+  - go for broke
+  - go him one better
+  - go the extra mile
+  - go with the flow
+  - goes without saying
+  - good as gold
+  - good deed for the day
+  - good things come to those who wait
+  - good time was had by all
+  - good times were had by all
+  - greased lightning
+  - greek to me
+  - green thumb
+  - green-eyed monster
+  - grist for the mill
+  - growing like a weed
+  - hair of the dog
+  - hand to mouth
+  - happy as a clam
+  - happy as a lark
+  - hasn't a clue
+  - have a nice day
+  - have high hopes
+  - have the last laugh
+  - haven't got a row to hoe
+  - head honcho
+  - head over heels
+  - hear a pin drop
+  - heard it through the grapevine
+  - heart's content
+  - heavy as lead
+  - hem and haw
+  - high and dry
+  - high and mighty
+  - high as a kite
+  - hit paydirt
+  - hold your head up high
+  - hold your horses
+  - hold your own
+  - hold your tongue
+  - honest as the day is long
+  - horns of a dilemma
+  - horse of a different color
+  - hot under the collar
+  - hour of need
+  - I beg to differ
+  - icing on the cake
+  - if the shoe fits
+  - if the shoe were on the other foot
+  - in a jam
+  - in a jiffy
+  - in a nutshell
+  - in a pig's eye
+  - in a pinch
+  - in a word
+  - in hot water
+  - in the gutter
+  - in the nick of time
+  - in the thick of it
+  - in your dreams
+  - it ain't over till the fat lady sings
+  - it goes without saying
+  - it takes all kinds
+  - it takes one to know one
+  - it's a small world
+  - it's only a matter of time
+  - ivory tower
+  - Jack of all trades
+  - jockey for position
+  - jog your memory
+  - joined at the hip
+  - judge a book by its cover
+  - jump down your throat
+  - jump in with both feet
+  - jump on the bandwagon
+  - jump the gun
+  - jump to conclusions
+  - just a hop, skip, and a jump
+  - just the ticket
+  - justice is blind
+  - keep a stiff upper lip
+  - keep an eye on
+  - keep it simple, stupid
+  - keep the home fires burning
+  - keep up with the Joneses
+  - keep your chin up
+  - keep your fingers crossed
+  - kick the bucket
+  - kick up your heels
+  - kick your feet up
+  - kid in a candy store
+  - kill two birds with one stone
+  - kiss of death
+  - knock it out of the park
+  - knock on wood
+  - knock your socks off
+  - know him from Adam
+  - know the ropes
+  - know the score
+  - knuckle down
+  - knuckle sandwich
+  - knuckle under
+  - labor of love
+  - ladder of success
+  - land on your feet
+  - lap of luxury
+  - last but not least
+  - last hurrah
+  - last-ditch effort
+  - law of the jungle
+  - law of the land
+  - lay down the law
+  - leaps and bounds
+  - let sleeping dogs lie
+  - let the cat out of the bag
+  - let the good times roll
+  - let your hair down
+  - let's talk turkey
+  - letter perfect
+  - lick your wounds
+  - lies like a rug
+  - life's a bitch
+  - life's a grind
+  - light at the end of the tunnel
+  - lighter than a feather
+  - lighter than air
+  - like clockwork
+  - like father like son
+  - like taking candy from a baby
+  - like there's no tomorrow
+  - lion's share
+  - live and learn
+  - live and let live
+  - long and short of it
+  - long lost love
+  - look before you leap
+  - look down your nose
+  - look what the cat dragged in
+  - looking a gift horse in the mouth
+  - looks like death warmed over
+  - loose cannon
+  - lose your head
+  - lose your temper
+  - loud as a horn
+  - lounge lizard
+  - loved and lost
+  - low man on the totem pole
+  - luck of the draw
+  - luck of the Irish
+  - make hay while the sun shines
+  - make money hand over fist
+  - make my day
+  - make the best of a bad situation
+  - make the best of it
+  - make your blood boil
+  - man of few words
+  - man's best friend
+  - mark my words
+  - meaningful dialogue
+  - missed the boat on that one
+  - moment in the sun
+  - moment of glory
+  - moment of truth
+  - money to burn
+  - more power to you
+  - more than one way to skin a cat
+  - movers and shakers
+  - moving experience
+  - naked as a jaybird
+  - naked truth
+  - neat as a pin
+  - needle in a haystack
+  - needless to say
+  - neither here nor there
+  - never look back
+  - never say never
+  - nip and tuck
+  - nip it in the bud
+  - no guts, no glory
+  - no love lost
+  - no pain, no gain
+  - no skin off my back
+  - no stone unturned
+  - no time like the present
+  - no use crying over spilled milk
+  - nose to the grindstone
+  - not a hope in hell
+  - not a minute's peace
+  - not in my backyard
+  - not playing with a full deck
+  - not the end of the world
+  - not written in stone
+  - nothing to sneeze at
+  - nothing ventured nothing gained
+  - now we're cooking
+  - off the top of my head
+  - off the wagon
+  - off the wall
+  - old hat
+  - older and wiser
+  - older than dirt
+  - older than Methuselah
+  - on a roll
+  - on cloud nine
+  - on pins and needles
+  - on the bandwagon
+  - on the money
+  - on the nose
+  - on the rocks
+  - on the spot
+  - on the tip of my tongue
+  - on the wagon
+  - on thin ice
+  - once bitten, twice shy
+  - one bad apple doesn't spoil the bushel
+  - one born every minute
+  - one brick short
+  - one foot in the grave
+  - one in a million
+  - one red cent
+  - only game in town
+  - open a can of worms
+  - open and shut case
+  - open the flood gates
+  - opportunity doesn't knock twice
+  - out of pocket
+  - out of sight, out of mind
+  - out of the frying pan into the fire
+  - out of the woods
+  - out on a limb
+  - over a barrel
+  - over the hump
+  - pain and suffering
+  - pain in the
+  - panic button
+  - par for the course
+  - part and parcel
+  - party pooper
+  - pass the buck
+  - patience is a virtue
+  - pay through the nose
+  - penny pincher
+  - perfect storm
+  - pig in a poke
+  - pile it on
+  - pillar of the community
+  - pin your hopes on
+  - pitter patter of little feet
+  - plain as day
+  - plain as the nose on your face
+  - play by the rules
+  - play your cards right
+  - playing the field
+  - playing with fire
+  - pleased as punch
+  - plenty of fish in the sea
+  - point with pride
+  - poor as a church mouse
+  - pot calling the kettle black
+  - pretty as a picture
+  - pull a fast one
+  - pull your punches
+  - pulling your leg
+  - pure as the driven snow
+  - put it in a nutshell
+  - put one over on you
+  - put the cart before the horse
+  - put the pedal to the metal
+  - put your best foot forward
+  - put your foot down
+  - quick as a bunny
+  - quick as a lick
+  - quick as a wink
+  - quick as lightning
+  - quiet as a dormouse
+  - rags to riches
+  - raining buckets
+  - raining cats and dogs
+  - rank and file
+  - rat race
+  - reap what you sow
+  - red as a beet
+  - red herring
+  - reinvent the wheel
+  - rich and famous
+  - rings a bell
+  - ripe old age
+  - ripped me off
+  - rise and shine
+  - road to hell is paved with good intentions
+  - rob Peter to pay Paul
+  - roll over in the grave
+  - rub the wrong way
+  - ruled the roost
+  - running in circles
+  - sad but true
+  - sadder but wiser
+  - salt of the earth
+  - scared stiff
+  - scared to death
+  - sealed with a kiss
+  - second to none
+  - see eye to eye
+  - seen the light
+  - seize the day
+  - set the record straight
+  - set the world on fire
+  - set your teeth on edge
+  - sharp as a tack
+  - shoot for the moon
+  - shoot the breeze
+  - shot in the dark
+  - shoulder to the wheel
+  - sick as a dog
+  - sigh of relief
+  - signed, sealed, and delivered
+  - sink or swim
+  - six of one, half a dozen of another
+  - skating on thin ice
+  - slept like a log
+  - slinging mud
+  - slippery as an eel
+  - slow as molasses
+  - smart as a whip
+  - smooth as a baby's bottom
+  - sneaking suspicion
+  - snug as a bug in a rug
+  - sow wild oats
+  - spare the rod, spoil the child
+  - speak of the devil
+  - spilled the beans
+  - spinning your wheels
+  - spitting image of
+  - spoke with relish
+  - spread like wildfire
+  - spring to life
+  - squeaky wheel gets the grease
+  - stands out like a sore thumb
+  - start from scratch
+  - stick in the mud
+  - still waters run deep
+  - stitch in time
+  - stop and smell the roses
+  - straight as an arrow
+  - straw that broke the camel's back
+  - strong as an ox
+  - stubborn as a mule
+  - stuff that dreams are made of
+  - stuffed shirt
+  - sweating blood
+  - sweating bullets
+  - take a load off
+  - take one for the team
+  - take the bait
+  - take the bull by the horns
+  - take the plunge
+  - takes one to know one
+  - takes two to tango
+  - the more the merrier
+  - the real deal
+  - the real McCoy
+  - the red carpet treatment
+  - the same old story
+  - there is no accounting for taste
+  - thick as a brick
+  - thick as thieves
+  - thin as a rail
+  - think outside of the box
+  - third time's the charm
+  - this day and age
+  - this hurts me worse than it hurts you
+  - this point in time
+  - three sheets to the wind
+  - through thick and thin
+  - throw in the towel
+  - tie one on
+  - tighter than a drum
+  - time and time again
+  - time is of the essence
+  - tip of the iceberg
+  - tired but happy
+  - to coin a phrase
+  - to each his own
+  - to make a long story short
+  - to the best of my knowledge
+  - toe the line
+  - tongue in cheek
+  - too good to be true
+  - too hot to handle
+  - too numerous to mention
+  - touch with a ten foot pole
+  - tough as nails
+  - trial and error
+  - trials and tribulations
+  - tried and true
+  - trip down memory lane
+  - twist of fate
+  - two cents worth
+  - two peas in a pod
+  - ugly as sin
+  - under the counter
+  - under the gun
+  - under the same roof
+  - under the weather
+  - until the cows come home
+  - unvarnished truth
+  - up the creek
+  - uphill battle
+  - upper crust
+  - upset the applecart
+  - vain attempt
+  - vain effort
+  - vanquish the enemy
+  - vested interest
+  - waiting for the other shoe to drop
+  - wakeup call
+  - warm welcome
+  - watch your p's and q's
+  - watch your tongue
+  - watching the clock
+  - water under the bridge
+  - weather the storm
+  - weed them out
+  - week of Sundays
+  - went belly up
+  - wet behind the ears
+  - what goes around comes around
+  - what you see is what you get
+  - when it rains, it pours
+  - when push comes to shove
+  - when the cat's away
+  - when the going gets tough, the tough get going
+  - white as a sheet
+  - whole ball of wax
+  - whole hog
+  - whole nine yards
+  - wild goose chase
+  - will wonders never cease?
+  - wisdom of the ages
+  - wise as an owl
+  - wolf at the door
+  - words fail me
+  - work like a dog
+  - world weary
+  - worst nightmare
+  - worth its weight in gold
+  - wrong side of the bed
+  - yanking your chain
+  - yappy as a dog
+  - years young
+  - you are what you eat
+  - you can run but you can't hide
+  - you only live once
+  - you're the boss
+  - young and foolish
+  - young and vibrant

.vale/styles/write-good/E-Prime.yml

@@ -0,0 +1,32 @@
+extends: existence
+message: "Try to avoid using '%s'."
+ignorecase: true
+level: suggestion
+tokens:
+  - am
+  - are
+  - aren't
+  - be
+  - been
+  - being
+  - he's
+  - here's
+  - here's
+  - how's
+  - i'm
+  - is
+  - isn't
+  - it's
+  - she's
+  - that's
+  - there's
+  - they're
+  - was
+  - wasn't
+  - we're
+  - were
+  - weren't
+  - what's
+  - where's
+  - who's
+  - you're

.vale/styles/write-good/Illusions.yml

@@ -0,0 +1,11 @@
+extends: repetition
+message: "'%s' is repeated!"
+level: warning
+alpha: true
+action:
+  name: edit
+  params:
+    - truncate
+    - " "
+tokens:
+  - '[^\s]+'

.vale/styles/write-good/Passive.yml

@@ -0,0 +1,183 @@
+extends: existence
+message: "'%s' may be passive voice. Use active voice if you can."
+ignorecase: true
+level: warning
+raw:
+  - \b(am|are|were|being|is|been|was|be)\b\s*
+tokens:
+  - '[\w]+ed'
+  - awoken
+  - beat
+  - become
+  - been
+  - begun
+  - bent
+  - beset
+  - bet
+  - bid
+  - bidden
+  - bitten
+  - bled
+  - blown
+  - born
+  - bought
+  - bound
+  - bred
+  - broadcast
+  - broken
+  - brought
+  - built
+  - burnt
+  - burst
+  - cast
+  - caught
+  - chosen
+  - clung
+  - come
+  - cost
+  - crept
+  - cut
+  - dealt
+  - dived
+  - done
+  - drawn
+  - dreamt
+  - driven
+  - drunk
+  - dug
+  - eaten
+  - fallen
+  - fed
+  - felt
+  - fit
+  - fled
+  - flown
+  - flung
+  - forbidden
+  - foregone
+  - forgiven
+  - forgotten
+  - forsaken
+  - fought
+  - found
+  - frozen
+  - given
+  - gone
+  - gotten
+  - ground
+  - grown
+  - heard
+  - held
+  - hidden
+  - hit
+  - hung
+  - hurt
+  - kept
+  - knelt
+  - knit
+  - known
+  - laid
+  - lain
+  - leapt
+  - learnt
+  - led
+  - left
+  - lent
+  - let
+  - lighted
+  - lost
+  - made
+  - meant
+  - met
+  - misspelt
+  - mistaken
+  - mown
+  - overcome
+  - overdone
+  - overtaken
+  - overthrown
+  - paid
+  - pled
+  - proven
+  - put
+  - quit
+  - read
+  - rid
+  - ridden
+  - risen
+  - run
+  - rung
+  - said
+  - sat
+  - sawn
+  - seen
+  - sent
+  - set
+  - sewn
+  - shaken
+  - shaven
+  - shed
+  - shod
+  - shone
+  - shorn
+  - shot
+  - shown
+  - shrunk
+  - shut
+  - slain
+  - slept
+  - slid
+  - slit
+  - slung
+  - smitten
+  - sold
+  - sought
+  - sown
+  - sped
+  - spent
+  - spilt
+  - spit
+  - split
+  - spoken
+  - spread
+  - sprung
+  - spun
+  - stolen
+  - stood
+  - stridden
+  - striven
+  - struck
+  - strung
+  - stuck
+  - stung
+  - stunk
+  - sung
+  - sunk
+  - swept
+  - swollen
+  - sworn
+  - swum
+  - swung
+  - taken
+  - taught
+  - thought
+  - thrived
+  - thrown
+  - thrust
+  - told
+  - torn
+  - trodden
+  - understood
+  - upheld
+  - upset
+  - wed
+  - wept
+  - withheld
+  - withstood
+  - woken
+  - won
+  - worn
+  - wound
+  - woven
+  - written
+  - wrung

.vale/styles/write-good/README.md

@@ -0,0 +1,27 @@
+Based on [write-good](https://github.com/btford/write-good).
+
+> Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too.
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2014 Brian Ford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

.vale/styles/write-good/So.yml

@@ -0,0 +1,5 @@
+extends: existence
+message: "Don't start a sentence with '%s'."
+level: error
+raw:
+  - '(?:[;-]\s)so[\s,]|\bSo[\s,]'

.vale/styles/write-good/ThereIs.yml

@@ -0,0 +1,6 @@
+extends: existence
+message: "Don't start a sentence with '%s'."
+ignorecase: false
+level: error
+raw:
+  - '(?:[;-]\s)There\s(is|are)|\bThere\s(is|are)\b'

.vale/styles/write-good/TooWordy.yml

@@ -0,0 +1,221 @@
+extends: existence
+message: "'%s' is too wordy."
+ignorecase: true
+level: warning
+tokens:
+  - a number of
+  - abundance
+  - accede to
+  - accelerate
+  - accentuate
+  - accompany
+  - accomplish
+  - accorded
+  - accrue
+  - acquiesce
+  - acquire
+  - additional
+  - adjacent to
+  - adjustment
+  - admissible
+  - advantageous
+  - adversely impact
+  - advise
+  - aforementioned
+  - aggregate
+  - aircraft
+  - all of
+  - all things considered
+  - alleviate
+  - allocate
+  - along the lines of
+  - already existing
+  - alternatively
+  - amazing
+  - ameliorate
+  - anticipate
+  - apparent
+  - appreciable
+  - as a matter of fact
+  - as a means of
+  - as far as I'm concerned
+  - as of yet
+  - as to
+  - as yet
+  - ascertain
+  - assistance
+  - at the present time
+  - at this time
+  - attain
+  - attributable to
+  - authorize
+  - because of the fact that
+  - belated
+  - benefit from
+  - bestow
+  - by means of
+  - by virtue of
+  - by virtue of the fact that
+  - cease
+  - close proximity
+  - commence
+  - comply with
+  - concerning
+  - consequently
+  - consolidate
+  - constitutes
+  - demonstrate
+  - depart
+  - designate
+  - discontinue
+  - due to the fact that
+  - each and every
+  - economical
+  - eliminate
+  - elucidate
+  - employ
+  - endeavor
+  - enumerate
+  - equitable
+  - equivalent
+  - evaluate
+  - evidenced
+  - exclusively
+  - expedite
+  - expend
+  - expiration
+  - facilitate
+  - factual evidence
+  - feasible
+  - finalize
+  - first and foremost
+  - for all intents and purposes
+  - for the most part
+  - for the purpose of
+  - forfeit
+  - formulate
+  - have a tendency to
+  - honest truth
+  - however
+  - if and when
+  - impacted
+  - implement
+  - in a manner of speaking
+  - in a timely manner
+  - in a very real sense
+  - in accordance with
+  - in addition
+  - in all likelihood
+  - in an effort to
+  - in between
+  - in excess of
+  - in lieu of
+  - in light of the fact that
+  - in many cases
+  - in my opinion
+  - in order to
+  - in regard to
+  - in some instances
+  - in terms of
+  - in the case of
+  - in the event that
+  - in the final analysis
+  - in the nature of
+  - in the near future
+  - in the process of
+  - inception
+  - incumbent upon
+  - indicate
+  - indication
+  - initiate
+  - irregardless
+  - is applicable to
+  - is authorized to
+  - is responsible for
+  - it is
+  - it is essential
+  - it seems that
+  - it was
+  - magnitude
+  - maximum
+  - methodology
+  - minimize
+  - minimum
+  - modify
+  - monitor
+  - multiple
+  - necessitate
+  - nevertheless
+  - not certain
+  - not many
+  - not often
+  - not unless
+  - not unlike
+  - notwithstanding
+  - null and void
+  - numerous
+  - objective
+  - obligate
+  - obtain
+  - on the contrary
+  - on the other hand
+  - one particular
+  - optimum
+  - overall
+  - owing to the fact that
+  - participate
+  - particulars
+  - pass away
+  - pertaining to
+  - point in time
+  - portion
+  - possess
+  - preclude
+  - previously
+  - prior to
+  - prioritize
+  - procure
+  - proficiency
+  - provided that
+  - purchase
+  - put simply
+  - readily apparent
+  - refer back
+  - regarding
+  - relocate
+  - remainder
+  - remuneration
+  - requirement
+  - reside
+  - residence
+  - retain
+  - satisfy
+  - shall
+  - should you wish
+  - similar to
+  - solicit
+  - span across
+  - strategize
+  - subsequent
+  - substantial
+  - successfully complete
+  - sufficient
+  - terminate
+  - the month of
+  - the point I am trying to make
+  - therefore
+  - time period
+  - took advantage of
+  - transmit
+  - transpire
+  - type of
+  - until such time as
+  - utilization
+  - utilize
+  - validate
+  - various different
+  - what I mean to say is
+  - whether or not
+  - with respect to
+  - with the exception of
+  - witnessed

.vale/styles/write-good/Weasel.yml

@@ -0,0 +1,29 @@
+extends: existence
+message: "'%s' is a weasel word!"
+ignorecase: true
+level: warning
+tokens:
+  - clearly
+  - completely
+  - exceedingly
+  - excellent
+  - extremely
+  - fairly
+  - huge
+  - interestingly
+  - is a number
+  - largely
+  - mostly
+  - obviously
+  - quite
+  - relatively
+  - remarkably
+  - several
+  - significantly
+  - substantially
+  - surprisingly
+  - tiny
+  - usually
+  - various
+  - vast
+  - very

.vale/styles/write-good/meta.json

@@ -0,0 +1,4 @@
+{
+  "feed": "https://github.com/errata-ai/write-good/releases.atom",
+  "vale_version": ">=1.0.0"
+}

AGENTS.md

@@ -51,13 +51,13 @@ Workflow YAML files (`.gitea/workflows/*.yml`) are verified with two tools:
 
 Both run via `make workflow-check` and are part of `make lint-all`.
 The pre-commit hook runs actionlint automatically when workflow files change.
-The CI `quality` job runs `make setup` (which installs all tools) then `make lint-all`.
+The CI `validate` job runs `make setup-image` (which installs all tools) then `make lint-all`.
 CI also runs a best-effort `make workflow-dryrun` step (skipped if act_runner is not installed in the CI Docker image).
 
 ## Architecture
 
 - **Python CLI** (`src/grm/`) — Click-based CLI that delegates to Ansible
-- **Ansible Role** (`ansible/roles/gitea-runner/`) — Idempotent role for rootless Docker runner setup
+- **Ansible Role** (`ansible/roles/gitea_runner/`) — Idempotent role for rootless Docker runner setup with pasta networking (IPv6 support)
 - **devx package** (installed from git) — Reusable CI/CD tools: auto-merge, post-merge, release, publishing, molecule distribution, PR reviews, failure notifications
 - **Versioning** (`cliff.toml`) — git-cliff configuration for automated semver versioning from conventional commits
 
@@ -69,13 +69,13 @@ Every change to master goes through this workflow. No exceptions.
 
 Branch protection and labels are automatically configured by
 `devx.tools.configure_repo` (run as `python -m devx.tools.configure_repo`),
-which runs as a `configure-repo` job in
+which runs as a step in the `detect-and-configure` job in
 the post-merge workflow on every push to master.
 
 The following rules are enforced for `master`:
 - **Require pull request**: No direct pushes to master
 - **Require approval review**: At least 1 `APPROVE` review before merge
-- **Require status checks**: CI quality + molecule tests must pass
+- **Require status checks**: CI validate + molecule tests must pass
 - **Block force pushes**: No history rewriting on master
 
 The auto-merge workflow enforces the APPROVE review check programmatically
@@ -84,6 +84,12 @@ as a defense-in-depth measure, but branch protection is the primary gate.
 ### 1. Create Vikunja Task
 Create a task in Vikunja project 6 via `make create-task -- --title "Task title" --description "<h2>...</h2>"` (requires `VIKUNJA_TOKEN` in `.env`). This prints the `GRM-N` identifier and next-step instructions.
 
+**IMPORTANT:** The task title must NOT include the `GRM-N:` prefix.
+The `make create-pr` and `check_auto_merge_ready` commands automatically
+prepend `GRM-N: ` to the Vikunja task title when forming the PR title.
+If the Vikunja task title already includes the prefix, the PR title will
+have a double prefix and auto-merge validation will fail.
+
 ### 2. Create Branch
 ```bash
 git checkout master && git pull
@@ -97,7 +103,7 @@ git checkout -b GRM-N-short-description
 
 ### 4. Commit (Conventional Commits)
 Branch commits use conventional commit format (no `GRM-N:` prefix):
-```
+```text
 feat: add new feature
 fix: resolve bug
 docs: update README
@@ -117,8 +123,9 @@ architecture, code quality, security, i18n, testing, performance,
 UX, documentation, workflow compliance, maintainability, resource
 management, backwards compatibility, and logging.
 
-**Automated review (CI `pr-review` job):** Every PR triggers an automated
-review via `devx.ci.pr_review` (run as `python -m devx.ci.pr_review`). This job posts a review with
+**Automated review (CI `validate` job):** Every PR triggers an automated
+review via `python -m devx.ci.pr_review` as a step in the `validate` job.
+This posts a review with
 `COMMENT` (no issues) or `REQUEST_CHANGES` (issues found) based on
 the **[auto]** items in the checklist:
 
@@ -166,16 +173,16 @@ it attests that the reviewer has gone through every checklist category.
 The `--checklist-categories` flag is also **required** — it must list at
 least 8 of the 13 category numbers, ensuring the reviewer actually
 checked each category rather than rubber-stamping. The review body must
-be substantive (> 50 characters) — trivial approvals like "LGTM" are
+be substantive (> 50 characters) — perfunctory approvals like "LGTM" are
 rejected.
 
 Then add the `ready-to-merge` label. The auto-merge workflow will:
 1. **Validate** PR title format (`GRM-N: <vikunja task title>`) and match against Vikunja task title
 2. **Check** that at least one substantive APPROVE review exists (body > 20 chars or has inline comments)
-3. Wait for all CI checks to pass (including the `pr-review` job)
+3. Wait for all CI checks to pass (including the `validate` job)
 4. Squash-merge with title: `GRM-N: <conventional commit message>`
 5. The post-merge workflow marks the Vikunja task as done
-6. The release workflow automatically versions, tags, and publishes (see below)
+6. The release-and-maintain job automatically versions, tags, and publishes (see below)
 
 **If the branch is behind master** (another PR merged first), auto-merge
 automatically rebases the PR's head branch via the Gitea API. This triggers
@@ -191,21 +198,22 @@ No manual rebase needed. To rebase manually: `make rebase` (local) or
 
 ### CI Path Filtering
 
-The CI workflow includes a `pre-merge-check` job (runs after quality +
-detect-changes) that validates branch format, PR title, and Vikunja task
-match. This fails fast before expensive molecule tests run.
+The CI workflow's `validate` job includes a pre-merge validation step
+that validates branch format, PR title, and Vikunja task match. This
+fails fast before expensive molecule tests run.
 
-The CI workflow includes a `detect-changes` job that checks whether any files
-under `ansible/` or `.ansible-lint` have changed. If no Ansible files are
-changed, molecule tests are skipped — this prevents non-Ansible changes
-(e.g., Python scripts, workflow YAML, docs) from being blocked by molecule
-test infrastructure flakiness.
+The `validate` job also includes a `detect-changes` step that checks
+whether any files under `ansible/` or `.ansible-lint` have changed. If
+no Ansible files are changed, molecule tests are skipped — this prevents
+non-Ansible changes (e.g., Python scripts, workflow YAML, docs) from
+being blocked by molecule test infrastructure flakiness.
 
 ### Dynamic Runner Discovery
 
 Molecule tests are distributed across available Gitea Actions runners
-dynamically via `devx.molecule.discover_runners`. The `discover-runners`
-job queries the Gitea API for runners at all levels (repo, org, instance)
+dynamically via `devx.molecule.discover_runners`. The `validate` job
+includes a `discover-runners` step (conditional on ansible-changed) that
+queries the Gitea API for runners at all levels (repo, org, instance)
 and generates a dynamic matrix. If the API can't see instance-level runners
 (no admin scope), it falls back to the `MOLECULE_RUNNERS` repo variable,
 then to a default of 3.
@@ -218,47 +226,27 @@ then to a default of 3.
 ### Automated Release Pipeline
 
 After a PR is merged to master, the **post-merge workflow**
-(`.gitea/workflows/post-merge.yml`) runs automatically. This single
-workflow consolidates release, wiki sync, badge generation, and
-Vikunja task updates:
+(`.gitea/workflows/post-merge.yml`) runs automatically. Consolidated
+into 2 jobs (from 7) to reduce runner overhead:
 
-1. **detect-type** — Checks if the commit is a regular merge or a
-   release commit (`release: vX.Y.Z`). All subsequent jobs skip for
-   release commits (the `[skip ci]` tag also prevents re-triggering).
+1. **detect-and-configure** — Configures repo (branch protection, labels),
+   detects release commit, validates commit message. Outputs `is-release`
+   and `is-automated` for the next job.
 
-2. **release** — Runs `devx.ci.release` which:
-   - **Checks for user-facing changes** via `devx.ci.classify_changes` — if only
-     workflow/infrastructure files changed (`.gitea/`, `docs/`, `tests/`,
-     `AGENTS.md`, `Makefile`, etc.), the release is **skipped entirely** — no version
-     bump, no tag, no publish. This prevents unnecessary releases for CI/docs-only changes.
-   - Uses **git-cliff** to calculate the next semver version from conventional commits
-   - Updates `__version__` in `src/grm/__init__.py` (single source of truth)
-   - Updates `CHANGELOG.md` with the new version section
-   - **Runs `make lint-ruff` and `make pytest-cov`** to verify the release is healthy
-   - If lint or tests fail, **aborts immediately** — no commit, no tag
-   - Commits with `release: vX.Y.Z [skip ci]` prefix (the `[skip ci]` prevents
-     re-triggering post-merge on the release commit)
-   - Creates an annotated tag `vX.Y.Z` on the release commit
-   - Pushes both the commit and tag to master
-   - `--skip-tests` flag bypasses test verification (emergency use only, not recommended)
-   - Loops are prevented by `has_unreleased_changes` — after a release commit is tagged, the next run finds no unreleased changes and exits
-
-3. **sync-wiki** — Syncs documentation to the Gitea wiki. Runs for ALL
-   non-release commits (not just when release succeeds), so docs-only
-   changes still update the wiki.
-
-4. **badges** — Generates and pushes quality badge SVGs to the `badges` branch.
-   Uses `if: always()` so it runs on every push, including release commits.
-   The script fetches the latest master before generating badges to pick up
-   any release commits.
-
-5. **vikunja** — Marks the corresponding Vikunja task as done. Runs for ALL
-   non-release commits (not just when release succeeds), so infrastructure-only
-   changes still update the task tracker.
-
-6. **publish** — Runs after release succeeds (needs: release). Builds and
-   publishes the package to the Gitea PyPI registry. Gets the tag from the
-   release job's `tag` output.
+2. **release-and-maintain** — Runs all post-merge maintenance as
+   conditional steps:
+   - **release** (if not a release commit) — Runs `devx.ci.release` which
+     checks for user-facing changes via `classify_changes` (skips if only
+     workflow/infrastructure files changed), uses git-cliff for semver,
+     updates `__version__`, updates `CHANGELOG.md`, runs lint+tests, commits
+     with `release: vX.Y.Z [skip ci]`, creates annotated tag, pushes to master.
+   - **publish** (if release created a tag) — Builds and publishes the
+     package to the Gitea PyPI registry. Checks out the release tag
+     within the same job.
+   - **sync-wiki** (if not automated) — Syncs documentation to the Gitea wiki.
+   - **vikunja** (if not automated) — Marks the corresponding Vikunja task as done.
+   - **badges** (always) — Generates and pushes quality badge SVGs to the
+     `badges` branch. Fetches latest master first to pick up release commits.
 
 ### Smart CI: User-Facing vs Workflow-Only Changes
 
@@ -379,9 +367,9 @@ platform matrix. Both `devx.molecule.distribute_molecule` (CI) and
 `devx.molecule.molecule_all` (dev tool) import `PLATFORMS` from it — this
 avoids dev tools importing directly from CI modules.
 
-2. **Publish job** (in `post-merge.yml`, needs: release):
-   - Runs after the release job creates a tag
-   - Gets the tag from `needs.release.outputs.tag`
+2. **Publish step** (in the `release-and-maintain` job, runs after the release step creates a tag):
+   - Runs after the release step creates a tag
+   - Gets the tag from the release step's output
    - Builds the Python package
    - Publishes to the Gitea PyPI registry
    - Creates a Gitea release with git-cliff-generated release notes
@@ -479,14 +467,20 @@ report `ok`.
 
 ## Ansible Role Structure
 
-```
+```text
 main.yml → systemd_check → user_setup → rootless_docker → install_runner → prune → integration_test
 ```
 
 - `install_runner.yml` handles: download, config, validate, register, service
 - `main.yml` handles: prune, integration_test (NOT install_runner — avoids duplicates)
 - `systemctl --user` tasks must be guarded by `docker_rootless_setup`
-- Template creation tasks are NOT guarded by `docker_rootless_setup` (they just create files)
+- Template creation tasks are NOT guarded by `docker_rootless_setup` (they only create files)
+- On Arch Linux, `rootless_docker.yml` fetches the rootless setup scripts
+  (`dockerd-rootless-setuptool.sh`, `dockerd-rootless.sh`) from `moby/moby` `contrib/`
+  at a pinned ref (`gitea_runner_rootless_scripts_ref`) into `/usr/bin` and installs
+  `rootlesskit` — Arch's `docker` package ships neither. These fetch tasks run
+  regardless of `docker_rootless_setup` so CI exercises them on the archlinux platform.
+  See ADR-011 in the decision log.
 
 ## Molecule Scenarios
 
@@ -507,7 +501,7 @@ All documentation lives in `/docs/` and is synced to the Gitea wiki automaticall
 
 ### Structure
 
-```
+```text
 docs/
 ├── index.md              # Wiki homepage
 ├── mapping.json          # File-to-wiki-page title mapping
@@ -536,7 +530,7 @@ docs/
 ### Documentation Coverage
 
 - `devx.ci.doc_coverage` checks that all CLI commands, Python modules, and CI scripts are documented
-- Runs as a CI step in the quality job with `--fail-on-missing` (blocks CI if docs are missing)
+- Runs as a CI step in the validate job with `--fail-on-missing` (blocks CI if docs are missing)
 - Enforced: 100% coverage for public CLI commands and major architectural components
 
 ### Updating Documentation
@@ -566,7 +560,7 @@ the user should not need to specify which profile to use.
 
 | Profile | Purpose |
 |---------|---------|
-| `ci-investigator` | Investigate CI failures (quality, molecule, release, publish, wiki sync) |
+| `ci-investigator` | Investigate CI failures (validate, molecule-tests, release-and-maintain) |
 | `molecule-runner` | Run 7 molecule scenarios across 4 platforms, report pass/fail |
 | `dep-upgrader` | Python + Ansible dependency upgrades with molecule verification |
 | `doc-sync-specialist` | Doc coverage, doc linting, wiki sync for grm docs |
@@ -576,7 +570,7 @@ the user should not need to specify which profile to use.
 
 | Trigger | Profile | Mode |
 |---------|---------|------|
-| CI run failure (quality, molecule-tests, release, publish, sync-wiki) | `ci-investigator` | Background |
+| CI run failure (validate, molecule-tests, release-and-maintain) | `ci-investigator` | Background |
 | PR ready for review | `pr-reviewer` | Foreground |
 | Molecule tests need to run | `molecule-runner` | Background |
 | Dependency upgrade requested | `dep-upgrader` | Background |
@@ -590,7 +584,7 @@ the user should not need to specify which profile to use.
 2. **Background by default, foreground when blocking.**
 3. **Provide full context in the prompt** — subagents don't inherit conversation history.
 4. **One subagent per concern.** Chain: investigate → fix in main session → review.
-5. **Don't delegate trivial work** (<30s, <50 lines of context).
+5. **Don't delegate minor work** (<30s, <50 lines of context).
 6. **Compact after subagent returns.**
 7. **Never skip delegation to save time** — it keeps main context small.
 
@@ -602,8 +596,9 @@ tool, workflow, or process issues that warrant follow-up. These issues
 use the `feedback` label plus a category label (`tooling`,
 `ci-improvement`, `doc-improvement`, `workflow-improvement`).
 
-Standard labels are created automatically by `configure_repo` (runs in
-post-merge on every master push). If a label does not exist yet, the
+Standard labels are created automatically by `configure_repo` (runs as
+a step in `detect-and-configure` in post-merge on every master push).
+If a label does not exist yet, the
 subagent's issue creation will still succeed — labels can be added
 afterwards.
 

CHANGELOG.md

@@ -2,6 +2,52 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.18.1] - 2026-07-16
+
+### Bug Fixes
+
+- Fetch rootless Docker scripts on Arch Linux
+
+## [0.18.0] - 2026-07-12
+
+### Features
+
+- *(runner)* Enable IPv6 in rootless Docker via pasta network driver
+
+## [0.17.2] - 2026-07-11
+
+### Refactor
+
+- Adopt devx v0.40.0
+
+## [0.17.1] - 2026-07-09
+
+### Bug Fixes
+
+- Disable IPv6 in rootless Docker daemon on runners
+
+## [0.17.0] - 2026-07-08
+
+### Features
+
+- Bump devx to 0.38.0 and migrate to role-based Gitea tokens
+
+## [0.16.0] - 2026-07-07
+
+### Features
+
+- Consolidate docs checks into devx-docs-check target
+
+### Bug Fixes
+
+- Replace --strict with --verify for sync_wiki
+
+## [0.15.0] - 2026-07-06
+
+### Features
+
+- Adopt documentation-as-code enhancements from devx
+
 ## [0.14.4] - 2026-07-06
 
 ### Refactor

CONTRIBUTING.md

@@ -19,7 +19,7 @@ The `GRM-N` prefix is mandatory — CI extracts it for merge messages and Vikunj
 ### Feature branches
 Use **conventional commits** on feature branches:
 
-```
+```text
 feat: add new command
 fix: resolve timeout issue
 chore: update dependencies
@@ -33,7 +33,7 @@ Allowed types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `tes
 ### Master branch (squash merges)
 Squash commits on `master` must follow:
 
-```
+```text
 GRM-N: <conventional commit message>
 ```
 

Makefile

@@ -1,6 +1,7 @@
 .PHONY: all setup setup-ci setup-quality setup-molecule setup-release setup-image install update lint ansible-lint makefile-lint lint-all lint-ruff lint-format lint-bandit lint-deps typecheck checkmake install-hooks test test-unit pytest-cov molecule molecule-all test-all clean workflow-lint workflow-dryrun workflow-check install-tools check-api-identity-checks
 .PHONY: configure-gitea-pypi
 .PHONY: create-task create-pr push-with-pr git-push
+.PHONY: check-docs docs-check
 
 PYTHON := python3
 VENV := .venv
@@ -49,13 +50,14 @@ setup: $(VENV)/bin/activate .env activate-scripts configure-gitea-pypi
 	$(BIN)/python -m devx.tools.setup --bin "$(BIN)" --skip-install
 
 # Lean setup for CI jobs that need pytest + lint tools + runtime deps
-# (detect-changes, discover-runners, pr-review, sync-wiki, badges)
-# badges job runs generate_badges.py which needs ruff, pyright, bandit
+# (validate job steps: detect-changes, discover-runners, pr-review;
+#  release-and-maintain job steps: sync-wiki, badges)
+# badges step runs generate_badges.py which needs ruff, pyright, bandit
 setup-ci: $(VENV)/bin/activate .env configure-gitea-pypi
 	@$(PIP_INSTALL) install -e '.[ci,lint]'
 	@$(BIN)/python -m devx.tools.setup --bin "$(BIN)" --skip-install --no-ansible-collections --no-pre-commit --no-tea-login
 
-# Setup for the quality job (lint + test deps, actionlint tool)
+# Setup for the validate CI job (lint + test deps, actionlint tool)
 setup-quality: $(VENV)/bin/activate .env configure-gitea-pypi
 	@$(PIP_INSTALL) install -e '.[ci,lint]'
 	@$(BIN)/python -m devx.tools.install_tools
@@ -85,7 +87,8 @@ setup-release: $(VENV)/bin/activate .env configure-gitea-pypi
 # the venv symlink first, then installs the project.
 setup-image:
 	@if [ -d /opt/venv ]; then ln -sf /opt/venv .venv; . .venv/bin/activate; \
-		if [ -n "$$CI_GITEA_TOKEN" ]; then export PIP_EXTRA_INDEX_URL="https://$$CI_GITEA_USERNAME:$$CI_GITEA_TOKEN@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"; fi; \
+		_TOKEN="$$CI_GITEA_API_TOKEN"; [ -z "$$_TOKEN" ] && _TOKEN="$$DEVELOPER_GITEA_API_TOKEN"; [ -z "$$_TOKEN" ] && _TOKEN="$$CI_GITEA_TOKEN"; \
+		if [ -n "$$_TOKEN" ]; then export PIP_EXTRA_INDEX_URL="https://$$CI_GITEA_USERNAME:$${_TOKEN}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"; fi; \
 		pip install -e .$(if $(EXTRAS),[$(EXTRAS)],); \
 	else echo "[setup-image] /opt/venv not found — falling back to setup-ci"; $(MAKE) setup-ci; fi
 
@@ -158,10 +161,9 @@ workflow-dryrun: devx-workflow-dryrun
 workflow-check: devx-workflow-check
 
 configure-gitea-pypi:
-	@if [ -z "$$CI_GITEA_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
-	CI_GITEA_TOKEN="$$CI_GITEA_TOKEN"; \
-	if [ -z "$$CI_GITEA_TOKEN" ]; then echo "[configure-gitea-pypi] CI_GITEA_TOKEN not set — skipping (devx must be on public PyPI)"; exit 0; fi; \
-	echo "[configure-gitea-pypi] Gitea PyPI registry configured (CI_GITEA_TOKEN present)."
+	_TOKEN="$$CI_GITEA_API_TOKEN"; [ -z "$$_TOKEN" ] && _TOKEN="$$DEVELOPER_GITEA_API_TOKEN"; [ -z "$$_TOKEN" ] && _TOKEN="$$CI_GITEA_TOKEN"; \
+	if [ -z "$$_TOKEN" ]; then echo "[configure-gitea-pypi] Gitea API token not set — skipping (devx must be on public PyPI)"; exit 0; fi; \
+	echo "[configure-gitea-pypi] Gitea PyPI registry configured (token present)."
 
 ansible-lint:
 	PATH="$(PWD)/$(BIN):$$PATH" $(BIN)/ansible-lint ansible/
@@ -182,7 +184,7 @@ test-integration:
 	$(BIN)/pytest tests/integration/ -v --no-cov
 
 MOLECULE := $(realpath $(BIN))/molecule
-MOLECULE_BASE := cd $(CURDIR)/ansible/roles/gitea-runner && ANSIBLE_ALLOW_BROKEN_CONDITIONALS=true ANSIBLE_INJECT_INVOCATION=1 $(MOLECULE)
+MOLECULE_BASE := cd $(CURDIR)/ansible/roles/gitea_runner && ANSIBLE_ALLOW_BROKEN_CONDITIONALS=true ANSIBLE_INJECT_INVOCATION=1 $(MOLECULE)
 
 # Quick local test: Ubuntu 22.04 only, all scenarios
 molecule:
@@ -202,3 +204,7 @@ create-task: devx-create-task
 create-pr: devx-create-pr
 push-with-pr: devx-push-with-pr
 git-push: devx-push
+
+# --- Documentation checks (via devx.mak fragment) -----------------------------
+check-docs: devx-check-docs
+docs-check: devx-docs-check

README.md

@@ -8,12 +8,12 @@ Each runner runs in an isolated **rootless Docker** environment under a dedicate
 
 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/32ca75618dd3c64ce1709fd13c4459f5d17305c7/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/32ca75618dd3c64ce1709fd13c4459f5d17305c7/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/32ca75618dd3c64ce1709fd13c4459f5d17305c7/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/32ca75618dd3c64ce1709fd13c4459f5d17305c7/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/32ca75618dd3c64ce1709fd13c4459f5d17305c7/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/32ca75618dd3c64ce1709fd13c4459f5d17305c7/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/1249a783c6188af168d50bec3b12e0c5d7710b8a/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/1249a783c6188af168d50bec3b12e0c5d7710b8a/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/1249a783c6188af168d50bec3b12e0c5d7710b8a/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/1249a783c6188af168d50bec3b12e0c5d7710b8a/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/1249a783c6188af168d50bec3b12e0c5d7710b8a/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/1249a783c6188af168d50bec3b12e0c5d7710b8a/python.svg)](https://www.python.org/downloads/)
 
 ## Why GRM?
 
@@ -147,7 +147,7 @@ GRM provides a single `grm` command with subcommands for the full runner lifecyc
 | `grm enable <name>` | Enable a runner to start on boot |
 | `grm disable <name>` | Disable and deregister a runner |
 | `grm status <name>` | Check the status of a registered runner |
-| `grm remove <name>` | Remove a runner completely (with remote cleanup) |
+| `grm remove <name>` | Remove a runner entirely (with remote cleanup) |
 | `grm remove <name> --force` | Remove only the local registry entry (skip remote cleanup) |
 | `grm list` | List all registered runners with live status |
 | `grm list --no-status` | List registered runners without SSH status checks |
@@ -187,7 +187,7 @@ GRM reads configuration from a `.env` file in the current directory (loaded auto
 
 ### Sudo Password Handling
 
-GRM delegates remote operations to Ansible, which uses `sudo` (become) on the target host. There are several ways to provide the sudo password, in priority order:
+GRM delegates remote operations to Ansible, which uses `sudo` (become) on the target host. There are multiple ways to provide the sudo password, in priority order:
 
 1. **`--become-password-file <path>`** (CLI flag, global) — Read sudo password from a file. Works for all commands including `grm list`.
 2. **`GRM_BECOME_PASSWORD_FILE`** (env var) — Same as above, set in `.env` or environment.
@@ -266,8 +266,8 @@ One of GRM's core features is the ability to run multiple isolated runners on th
 
 - **Dedicated system user**: `grm-<name>` with its own home directory at `/home/grm-<name>/`
 - **Rootless Docker daemon**: Isolated Docker socket at `/run/user/<UID>/docker.sock`
-- **Data directory**: `/var/lib/gitea-runner/<name>/`
-- **Config directory**: `/etc/gitea-runner/<name>/`
+- **Data directory**: `/var/lib/gitea_runner/<name>/`
+- **Config directory**: `/etc/gitea_runner/<name>/`
 - **Systemd user service**: `gitea-runner.service` (independent start/stop/enable)
 - **Docker prune timer**: Per-instance daily cleanup
 
@@ -341,13 +341,13 @@ GRM consists of two layers:
 
 1. **Python CLI** (`src/grm/`) — Built with Click, handles argument parsing, environment loading, i18n translations, and delegates to Ansible via the `ansible-playbook` subprocess. Secrets are passed via temporary JSON files to avoid exposure in the process list.
 
-2. **Ansible Role** (`ansible/roles/gitea-runner/`) — Idempotent role that creates a dedicated system user, sets up rootless Docker, installs the runner binary, creates a systemd user service, registers the runner with Gitea, and sets up a Docker prune timer.
+2. **Ansible Role** (`ansible/roles/gitea_runner/`) — Idempotent role that creates a dedicated system user, sets up rootless Docker, installs the runner binary, creates a systemd user service, registers the runner with Gitea, and sets up a Docker prune timer.
 
-```
+```text
 grm install <host>
   └── RunnerManager.install()
       └── ansible-playbook ansible/install-runner.yml
-          └── role: gitea-runner
+          └── role: gitea_runner
               ├── user_setup.yml       (create per-runner system user + lingering)
               ├── rootless_docker.yml  (rootless Docker setup under runner user)
               ├── install_runner.yml   (download binary, config, register, service)

ansible/disable-runner.yml

@@ -6,13 +6,13 @@
   tasks:
     - name: Include systemd availability check
       ansible.builtin.include_role:
-        name: gitea-runner
+        name: gitea_runner
         tasks_from: systemd_check.yml
 
     - name: Stop gitea-runner user service
       ansible.builtin.command: systemctl --user stop gitea-runner
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
       when: systemd_available.stat.exists
@@ -21,7 +21,7 @@
     - name: Stop and disable healthcheck timer
       ansible.builtin.command: systemctl --user stop --disable runner-healthcheck.timer
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
       when: systemd_available.stat.exists
@@ -30,14 +30,14 @@
 
     - name: Include deregistration
       ansible.builtin.include_role:
-        name: gitea-runner
+        name: gitea_runner
         tasks_from: deregister.yml
-      when: not skip_runner_registration | default(false)
+      when: not gitea_runner_skip_registration | default(false)
 
     - name: Disable gitea-runner user service
       ansible.builtin.command: systemctl --user disable gitea-runner
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
       when: systemd_available.stat.exists

ansible/enable-runner.yml

@@ -6,13 +6,13 @@
   tasks:
     - name: Include systemd availability check
       ansible.builtin.include_role:
-        name: gitea-runner
+        name: gitea_runner
         tasks_from: systemd_check.yml
 
     - name: Enable gitea-runner user service
       ansible.builtin.command: systemctl --user enable gitea-runner
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
       when: systemd_available.stat.exists
@@ -21,7 +21,7 @@
     - name: Start gitea-runner user service
       ansible.builtin.command: systemctl --user start gitea-runner
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
       when: systemd_available.stat.exists

ansible/install-runner.yml

@@ -3,4 +3,4 @@
   hosts: all
   become: true
   roles:
-    - role: gitea-runner
+    - role: gitea_runner

ansible/remove-runner.yml

@@ -6,11 +6,11 @@
   tasks:
     - name: Include systemd availability check
       ansible.builtin.include_role:
-        name: gitea-runner
+        name: gitea_runner
         tasks_from: systemd_check.yml
 
     - name: Get runner user UID
-      ansible.builtin.command: id -u "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      ansible.builtin.command: id -u "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       register: runner_uid_result
       changed_when: false
       failed_when: false
@@ -23,20 +23,20 @@
     - name: Stop gitea-runner user service
       ansible.builtin.command: systemctl --user stop gitea-runner
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
-      when: systemd_available.stat.exists
+      when: gitea_runner_systemd_available.stat.exists
       changed_when: true
       failed_when: false
 
     - name: Disable gitea-runner user service
       ansible.builtin.command: systemctl --user disable gitea-runner
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
-      when: systemd_available.stat.exists
+      when: gitea_runner_systemd_available.stat.exists
       changed_when: true
       failed_when: false
 
@@ -47,7 +47,7 @@
       args:
         executable: /bin/bash
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
         DOCKER_HOST: "unix:///run/user/{{ gitea_runner_uid | default('') }}/docker.sock"
@@ -57,7 +57,7 @@
     - name: Prune all Docker images, volumes, and build cache (rootless)
       ansible.builtin.command: docker system prune -af --volumes
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
         DOCKER_HOST: "unix:///run/user/{{ gitea_runner_uid | default('') }}/docker.sock"
@@ -67,7 +67,7 @@
     - name: Stop rootless Docker daemon
       ansible.builtin.command: systemctl --user stop docker
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
       changed_when: true
@@ -75,120 +75,120 @@
 
     - name: Include deregistration
       ansible.builtin.include_role:
-        name: gitea-runner
+        name: gitea_runner
         tasks_from: deregister.yml
-      when: not skip_runner_registration | default(false)
+      when: not gitea_runner_skip_registration | default(false)
 
     - name: Stop and disable healthcheck timer
       ansible.builtin.command: systemctl --user stop --disable runner-healthcheck.timer
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       environment:
         XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
-      when: systemd_available.stat.exists
+      when: gitea_runner_systemd_available.stat.exists
       changed_when: true
       failed_when: false
 
     - name: Remove docker-prune user service file
       ansible.builtin.file:
-        path: "{{ gitea_runner_home | default('/home/grm-' ~ runner_name) }}/.config/systemd/user/docker-prune.service"
+        path: "{{ gitea_runner_home | default('/home/grm-' ~ gitea_runner_name) }}/.config/systemd/user/docker-prune.service"
         state: absent
       failed_when: false
 
     - name: Remove docker-prune user timer file
       ansible.builtin.file:
-        path: "{{ gitea_runner_home | default('/home/grm-' ~ runner_name) }}/.config/systemd/user/docker-prune.timer"
+        path: "{{ gitea_runner_home | default('/home/grm-' ~ gitea_runner_name) }}/.config/systemd/user/docker-prune.timer"
         state: absent
       failed_when: false
 
     - name: Remove healthcheck user service file
       ansible.builtin.file:
-        path: "{{ gitea_runner_home | default('/home/grm-' ~ runner_name) }}/.config/systemd/user/runner-healthcheck.service"
+        path: "{{ gitea_runner_home | default('/home/grm-' ~ gitea_runner_name) }}/.config/systemd/user/runner-healthcheck.service"
         state: absent
       failed_when: false
 
     - name: Remove healthcheck user timer file
       ansible.builtin.file:
-        path: "{{ gitea_runner_home | default('/home/grm-' ~ runner_name) }}/.config/systemd/user/runner-healthcheck.timer"
+        path: "{{ gitea_runner_home | default('/home/grm-' ~ gitea_runner_name) }}/.config/systemd/user/runner-healthcheck.timer"
         state: absent
       failed_when: false
 
     - name: Remove healthcheck script
       ansible.builtin.file:
-        path: "{{ gitea_runner_config_dir | default('/etc/gitea-runner/' ~ runner_name) }}/healthcheck.sh"
+        path: "{{ gitea_runner_config_dir | default('/etc/gitea-runner/' ~ gitea_runner_name) }}/healthcheck.sh"
         state: absent
       failed_when: false
 
     - name: Remove systemd user unit file
       ansible.builtin.file:
-        path: "{{ gitea_runner_home | default('/home/grm-' ~ runner_name) }}/.config/systemd/user/gitea-runner.service"
+        path: "{{ gitea_runner_home | default('/home/grm-' ~ gitea_runner_name) }}/.config/systemd/user/gitea-runner.service"
         state: absent
       when: remove_systemd_template | default(true)
 
     - name: Kill remaining processes of runner user
-      ansible.builtin.command: loginctl terminate-user "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      ansible.builtin.command: loginctl terminate-user "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       failed_when: false
       changed_when: true
 
     - name: Wait for processes to terminate
-      ansible.builtin.command: "pkill -u {{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      ansible.builtin.command: "pkill -u {{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       failed_when: false
       changed_when: false
 
     - name: Disable lingering for runner user
-      ansible.builtin.command: loginctl disable-linger "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      ansible.builtin.command: loginctl disable-linger "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
       failed_when: false
       changed_when: true
 
     - name: Remove runner user and home directory
       ansible.builtin.user:
-        name: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+        name: "{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}"
         state: absent
         remove: true
-      when: remove_runner_user | default(true)
+      when: gitea_runner_remove_user | default(true)
       failed_when: false
 
     - name: Remove Docker data root when user is kept
       ansible.builtin.file:
-        path: "{{ gitea_runner_home | default('/home/grm-' ~ runner_name) }}/.local/share/docker"
+        path: "{{ gitea_runner_home | default('/home/grm-' ~ gitea_runner_name) }}/.local/share/docker"
         state: absent
-      when: not (remove_runner_user | default(true))
+      when: not (gitea_runner_remove_user | default(true))
       failed_when: false
 
     - name: Remove act cache when user is kept
       ansible.builtin.file:
-        path: "{{ gitea_runner_home | default('/home/grm-' ~ runner_name) }}/.cache/act"
+        path: "{{ gitea_runner_home | default('/home/grm-' ~ gitea_runner_name) }}/.cache/act"
         state: absent
-      when: not (remove_runner_user | default(true))
+      when: not (gitea_runner_remove_user | default(true))
       failed_when: false
 
     - name: Remove systemd user config dir when user is kept
       ansible.builtin.file:
-        path: "{{ gitea_runner_home | default('/home/grm-' ~ runner_name) }}/.config/systemd/user"
+        path: "{{ gitea_runner_home | default('/home/grm-' ~ gitea_runner_name) }}/.config/systemd/user"
         state: absent
-      when: not (remove_runner_user | default(true))
+      when: not (gitea_runner_remove_user | default(true))
       failed_when: false
 
     - name: Remove subuid entry for runner user
       ansible.builtin.lineinfile:
         path: /etc/subuid
-        regexp: "^{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}:"
+        regexp: "^{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}:"
         state: absent
       failed_when: false
 
     - name: Remove subgid entry for runner user
       ansible.builtin.lineinfile:
         path: /etc/subgid
-        regexp: "^{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}:"
+        regexp: "^{{ gitea_runner_service_user | default('grm-' ~ gitea_runner_name) }}:"
         state: absent
       failed_when: false
 
     - name: Remove runner data directory
       ansible.builtin.file:
-        path: "{{ gitea_runner_data_dir | default('/var/lib/gitea-runner/' ~ runner_name) }}"
+        path: "{{ gitea_runner_data_dir | default('/var/lib/gitea-runner/' ~ gitea_runner_name) }}"
         state: absent
 
     - name: Remove runner config directory
       ansible.builtin.file:
-        path: "{{ gitea_runner_config_dir | default('/etc/gitea-runner/' ~ runner_name) }}"
+        path: "{{ gitea_runner_config_dir | default('/etc/gitea-runner/' ~ gitea_runner_name) }}"
         state: absent

ansible/requirements.yml

@@ -2,6 +2,6 @@ collections:
   - name: community.general
     version: "==13.1.0"
   - name: ansible.posix
-    version: "==2.2.0"
+    version: "==2.2.1"
   - name: community.docker
     version: "==5.2.1"

ansible/restart-runner.yml

@@ -7,12 +7,12 @@
   tasks:
     - name: Include systemd availability check
       ansible.builtin.include_role:
-        name: gitea-runner
+        name: gitea_runner
         tasks_from: systemd_check.yml
 
     - name: Resolve runner UID
       ansible.builtin.include_role:
-        name: gitea-runner
+        name: gitea_runner
         tasks_from: resolve_uid.yml
 
     - name: Stop gitea-runner user service

ansible/roles/gitea-runner/defaults/main.yml

@@ -1,55 +0,0 @@
----
-gitea_runner_version: "1.0.8"
-runner_labels: "docker,ubuntu-latest:docker://runner-images:ubuntu-26.04"
-skip_runner_registration: false
-
-# Per-runner user (rootless isolation)
-gitea_runner_user_prefix: "grm-"
-gitea_runner_base_home: "/home"
-gitea_runner_service_user: "{{ gitea_runner_user_prefix }}{{ runner_name }}"
-gitea_runner_home: "{{ gitea_runner_base_home }}/{{ gitea_runner_service_user }}"
-
-# Base paths (instance-scoped via runner_name)
-gitea_runner_base_data_dir: "/var/lib/gitea-runner"
-gitea_runner_base_config_dir: "/etc/gitea-runner"
-gitea_runner_data_dir: "{{ gitea_runner_base_data_dir }}/{{ runner_name }}"
-gitea_runner_config_dir: "{{ gitea_runner_base_config_dir }}/{{ runner_name }}"
-gitea_runner_binary_path: "/usr/local/bin/gitea_runner"
-
-# Prune configuration
-gitea_runner_prune_until: "24h"
-gitea_runner_prune_schedule: "daily"
-gitea_runner_prune_label: "gitea-runner=true"
-
-# Service configuration
-gitea_runner_service_restart_sec: "5"
-
-# Health check configuration
-gitea_runner_healthcheck_interval: "5min"
-gitea_runner_healthcheck_boot_delay: "2min"
-gitea_runner_healthcheck_disk_threshold: 85
-gitea_runner_healthcheck_script_path: "{{ gitea_runner_config_dir }}/healthcheck.sh"
-
-# Admin token for runner deregistration via Gitea API.
-# If not set, falls back to registration_token (which likely lacks admin scope).
-# Set this to a token with admin scope to enable automatic runner cleanup on removal.
-gitea_admin_token: ""
-
-# Removal defaults
-remove_systemd_template: true
-remove_runner_user: true
-
-# Runner configuration
-gitea_runner_log_level: "info"
-gitea_runner_container_label: "gitea-runner=true"
-gitea_runner_file: ".runner"
-
-# Docker installation (for rootless dependencies)
-docker_gpg_key_path: "/etc/apt/keyrings/docker.gpg"
-docker_apt_arch: "{{ 'amd64' if ansible_facts['architecture'] == 'x86_64' else ansible_facts['architecture'] }}"
-docker_apt_source_line: >-
-  deb [arch={{ docker_apt_arch }} signed-by={{ docker_gpg_key_path }}]
-  https://download.docker.com/linux/{{ ansible_facts['distribution'] | lower }}
-  {{ ansible_facts['distribution_release'] }} stable
-# Set to false in CI/molecule to skip rootless daemon startup (needs kernel userns)
-docker_rootless_setup: true

ansible/roles/gitea-runner/molecule/default/converge.yml

@@ -1,12 +0,0 @@
----
-- name: Converge
-  hosts: all
-  become: true
-  vars:
-    gitea_url: "http://localhost:3000"
-    registration_token: "fake-token-for-testing"
-    runner_name: "molecule-test-runner"
-    skip_runner_registration: true
-    docker_rootless_setup: false
-  roles:
-    - role: gitea-runner

ansible/roles/gitea-runner/molecule/deregister/converge.yml

@@ -1,12 +0,0 @@
----
-- name: Converge
-  hosts: all
-  become: true
-  vars:
-    gitea_url: "http://localhost:3000"
-    registration_token: "fake-token-for-testing"
-    runner_name: "deregister-test-runner"
-    skip_runner_registration: true
-    docker_rootless_setup: false
-  roles:
-    - role: gitea-runner

ansible/roles/gitea-runner/molecule/lifecycle/converge.yml

@@ -1,12 +0,0 @@
----
-- name: Converge
-  hosts: all
-  become: true
-  vars:
-    gitea_url: "http://localhost:3000"
-    registration_token: "fake-token-for-testing"
-    runner_name: "lifecycle-test-runner"
-    skip_runner_registration: true
-    docker_rootless_setup: false
-  roles:
-    - role: gitea-runner

ansible/roles/gitea-runner/molecule/remove/converge.yml

@@ -1,12 +0,0 @@
----
-- name: Converge
-  hosts: all
-  become: true
-  vars:
-    gitea_url: "http://localhost:3000"
-    registration_token: "fake-token-for-testing"
-    runner_name: "remove-test-runner"
-    skip_runner_registration: true
-    docker_rootless_setup: false
-  roles:
-    - role: gitea-runner

ansible/roles/gitea-runner/molecule/template-content/converge.yml

@@ -1,12 +0,0 @@
----
-- name: Converge
-  hosts: all
-  become: true
-  vars:
-    gitea_url: "http://localhost:3000"
-    registration_token: "fake-token-for-testing"
-    runner_name: "template-test-runner"
-    skip_runner_registration: true
-    docker_rootless_setup: false
-  roles:
-    - role: gitea-runner

ansible/roles/gitea-runner/molecule/update/converge.yml

@@ -1,12 +0,0 @@
----
-- name: Converge
-  hosts: all
-  become: true
-  vars:
-    gitea_url: "http://localhost:3000"
-    registration_token: "fake-token-for-testing"
-    runner_name: "update-test-runner"
-    skip_runner_registration: true
-    docker_rootless_setup: false
-  roles:
-    - role: gitea-runner

ansible/roles/gitea-runner/tasks/deregister.yml

@@ -1,58 +0,0 @@
----
-- name: Check if runner registration file exists
-  ansible.builtin.stat:
-    path: "{{ gitea_runner_data_dir }}/.runner"
-  register: runner_file_stat
-
-- name: Read runner registration file
-  ansible.builtin.slurp:
-    src: "{{ gitea_runner_data_dir }}/.runner"
-  register: runner_file_content
-  when: runner_file_stat.stat.exists | default(false) | bool
-
-- name: Parse runner registration data
-  ansible.builtin.set_fact:
-    runner_reg: >
-      {{ (runner_file_content.content | b64decode | from_json)
-      if (runner_file_content is defined and runner_file_content.content is defined)
-      else {} }}
-  when: runner_file_stat.stat.exists | default(false) | bool
-
-- name: Deregister runner from Gitea via API
-  ansible.builtin.command: >
-    curl -sf --connect-timeout 5 --max-time 10 -X DELETE
-    -H "Authorization: token {{ gitea_admin_token | default(registration_token) }}"
-    "{{ gitea_url }}/api/v1/admin/actions/runners/{{ runner_reg.id }}"
-  args:
-    chdir: "{{ gitea_runner_data_dir }}"
-  become: true
-  become_user: "{{ gitea_runner_service_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default(0) }}"
-    DOCKER_HOST: "unix:///run/user/{{ gitea_runner_uid | default(0) }}/docker.sock"
-  when:
-    - runner_file_stat.stat.exists | default(false) | bool
-    - not skip_runner_registration
-    - runner_reg.id is defined
-  register: deregister_output
-  changed_when: deregister_output.rc == 0
-  failed_when: false
-
-- name: Warn if deregistration failed
-  ansible.builtin.debug:
-    msg: >-
-      WARNING: Runner deregistration from Gitea failed (rc={{ deregister_output.rc | default('N/A') }}).
-      The runner entry may remain in Gitea's admin UI as offline.
-      Use an admin token (gitea_admin_token var) to enable automatic cleanup,
-      or remove it manually from {{ gitea_url }}/-/admin/actions/runners
-  when:
-    - runner_file_stat.stat.exists | default(false) | bool
-    - not skip_runner_registration
-    - deregister_output is defined
-    - deregister_output.rc | default(1) != 0
-
-- name: Remove runner registration file
-  ansible.builtin.file:
-    path: "{{ gitea_runner_data_dir }}/.runner"
-    state: absent
-  when: runner_file_stat.stat.exists | default(false) | bool

ansible/roles/gitea-runner/tasks/integration_test.yml

@@ -1,102 +0,0 @@
----
-- name: Check runner registration file exists
-  ansible.builtin.stat:
-    path: "{{ gitea_runner_data_dir }}/.runner"
-  register: runner_file_stat
-
-- name: Read runner registration file
-  ansible.builtin.slurp:
-    src: "{{ gitea_runner_data_dir }}/.runner"
-  register: runner_file_content
-  when: runner_file_stat.stat.exists | default(false) | bool
-
-- name: Parse runner registration data
-  ansible.builtin.set_fact:
-    runner_reg: >
-      {{ (runner_file_content.content | b64decode | from_json)
-      if (runner_file_content is defined and runner_file_content.content is defined)
-      else {} }}
-  when: runner_file_stat.stat.exists | default(false) | bool
-
-- name: Verify runner user service active
-  ansible.builtin.command: systemctl --user is-active gitea-runner
-  become: true
-  become_user: "{{ gitea_runner_service_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
-  register: service_check
-  changed_when: false
-  when:
-    - systemd_available.stat.exists
-    - docker_rootless_setup
-
-- name: Validate runner installation
-  ansible.builtin.fail:
-    msg: >
-      Runner '{{ runner_name }}' is not properly installed:
-      {% if not (runner_file_stat.stat.exists | default(false)) %}
-      - Registration file (.runner) is missing. Registration may have failed.
-      {% endif %}
-      {% if docker_rootless_setup and not (service_check.stdout | default('') | trim) == 'active' %}
-      - Systemd user service is not active.
-      {% endif %}
-  when: >
-    not (runner_file_stat.stat.exists | default(false))
-    or (docker_rootless_setup and not (service_check.stdout | default('') | trim) == 'active')
-
-- name: Report runner status
-  ansible.builtin.debug:
-    msg: >
-      Runner '{{ runner_name }}' is installed and running.
-      Registered: {{ runner_file_stat.stat.exists | default(false) }}
-      {% if runner_reg.id is defined %}Runner ID: {{ runner_reg.id }}{% endif %}
-      {% if runner_reg.uuid is defined %}UUID: {{ runner_reg.uuid }}{% endif %}
-      {% if runner_reg.address is defined %}Gitea: {{ runner_reg.address }}{% endif %}
-      Service: {{ service_check.stdout | default('unknown') | trim }}
-
-- name: Optional Gitea API verification
-  when:
-    - gitea_url is defined
-    - gitea_admin_token is defined
-    - gitea_admin_token | length > 0
-  block:
-    - name: Check admin runners API
-      ansible.builtin.uri:
-        url: "{{ gitea_url }}/api/v1/admin/runners"
-        headers:
-          Authorization: "token {{ gitea_admin_token }}"
-        method: GET
-        status_code: [200, 401, 403, 404]
-        return_content: true
-        body_format: json
-      register: admin_api_response
-      ignore_errors: true
-
-    - name: Check repo runners API
-      ansible.builtin.uri:
-        url: "{{ gitea_url }}/api/v1/repos/{{ gitea_runner_test_repo | default('oblachno-oss/grm') }}/actions/runners"
-        headers:
-          Authorization: "token {{ gitea_admin_token }}"
-        method: GET
-        status_code: [200, 401, 403, 404]
-        return_content: true
-        body_format: json
-      register: repo_api_response
-      ignore_errors: true
-
-    - name: Report API status (informational only)
-      ansible.builtin.debug:
-        msg: >
-          API checks (informational only — not used for pass/fail):
-          Admin API: {{ admin_api_response.status | default('no response') }}.
-          Repo API: {{ repo_api_response.status | default('no response') }}.
-          {% if admin_api_response.json.runners | default([]) | selectattr('name', 'equalto', runner_name) | list | length > 0 %}
-          Runner found in admin API.
-          {% endif %}
-          {% if repo_api_response.json.runners | default([]) | selectattr('name', 'equalto', runner_name) | list | length > 0 %}
-          Runner found in repo API.
-          {% endif %}
-  rescue:
-    - name: API check failed
-      ansible.builtin.debug:
-        msg: "API verification skipped due to connection or permission error."

ansible/roles/gitea-runner/tasks/rootless_docker.yml

@@ -1,112 +0,0 @@
----
-- name: Ensure keyrings directory exists (Debian/Ubuntu)
-  ansible.builtin.file:
-    path: "/etc/apt/keyrings"
-    state: directory
-    mode: "0755"
-  when: ansible_facts['os_family'] == 'Debian'
-
-- name: Download and dearmor Docker GPG key (Debian/Ubuntu)
-  ansible.builtin.shell: |
-    set -o pipefail
-    curl -fsSL "https://download.docker.com/linux/{{ ansible_facts['distribution'] | lower }}/gpg" | gpg --dearmor --yes -o {{ docker_gpg_key_path }}
-  args:
-    creates: "{{ docker_gpg_key_path }}"
-    executable: /bin/bash
-  when: ansible_facts['os_family'] == 'Debian'
-
-- name: Add Docker APT repository (Debian/Ubuntu)
-  ansible.builtin.copy:
-    dest: /etc/apt/sources.list.d/docker.list
-    content: "{{ docker_apt_source_line }}\n"
-    mode: "0644"
-  register: docker_apt_repo
-  when: ansible_facts['os_family'] == 'Debian'
-
-- name: Update apt cache after adding Docker repo (Debian/Ubuntu)
-  ansible.builtin.apt:
-    update_cache: true
-  when:
-    - ansible_facts['os_family'] == 'Debian'
-    - docker_apt_repo is changed
-
-- name: Install rootless Docker dependencies (Debian/Ubuntu)
-  ansible.builtin.apt:
-    name:
-      - uidmap
-      - slirp4netns
-      - fuse-overlayfs
-      - docker-ce
-      - docker-ce-cli
-      - docker-ce-rootless-extras
-      - containerd.io
-      - docker-compose-plugin
-      - rsync
-    state: present
-  when: ansible_facts['os_family'] == 'Debian'
-
-- name: Update pacman cache (Arch Linux)
-  community.general.pacman:
-    update_cache: true
-  when: ansible_facts['os_family'] == 'Archlinux'
-  changed_when: false
-
-- name: Install rootless Docker dependencies (Arch Linux)
-  community.general.pacman:
-    name:
-      - docker
-      - docker-compose
-      - slirp4netns
-      - fuse-overlayfs
-      - rsync
-    state: present
-  when: ansible_facts['os_family'] == 'Archlinux'
-
-- name: Check if rootless Docker is already set up
-  ansible.builtin.stat:
-    path: "{{ gitea_runner_home }}/.config/systemd/user/docker.service"
-  register: rootless_docker_check
-
-- name: Set up rootless Docker for runner user
-  ansible.builtin.command: dockerd-rootless-setuptool.sh install
-  args:
-    creates: "{{ gitea_runner_home }}/.config/systemd/user/docker.service"
-  become: true
-  become_user: "{{ gitea_runner_service_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
-  when:
-    - docker_rootless_setup
-    - not rootless_docker_check.stat.exists
-
-- name: Start rootless Docker daemon (systemd user service)
-  ansible.builtin.command: systemctl --user start docker
-  become: true
-  become_user: "{{ gitea_runner_service_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
-  changed_when: true
-  when: docker_rootless_setup
-
-- name: Enable rootless Docker daemon (systemd user service)
-  ansible.builtin.command: systemctl --user enable docker
-  become: true
-  become_user: "{{ gitea_runner_service_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
-  changed_when: true
-  when: docker_rootless_setup
-
-- name: Wait for rootless Docker daemon to be ready
-  ansible.builtin.command: docker version
-  become: true
-  become_user: "{{ gitea_runner_service_user }}"
-  environment:
-    DOCKER_HOST: "unix:///run/user/{{ gitea_runner_uid }}/docker.sock"
-    XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
-  register: docker_ready
-  until: docker_ready.rc == 0
-  retries: 10
-  delay: 2
-  changed_when: false
-  when: docker_rootless_setup

ansible/roles/gitea_runner/defaults/main.yml

@@ -0,0 +1,72 @@
+---
+gitea_runner_version: "2.0.1"
+gitea_runner_labels: "docker,ubuntu-latest:docker://runner-images:ubuntu-26.04"
+gitea_runner_skip_registration: false
+
+# Per-runner user (rootless isolation)
+gitea_runner_user_prefix: "grm-"
+gitea_runner_base_home: "/home"
+gitea_runner_service_user: "{{ gitea_runner_user_prefix }}{{ gitea_runner_name }}"
+gitea_runner_home: "{{ gitea_runner_base_home }}/{{ gitea_runner_service_user }}"
+
+# Base paths (instance-scoped via gitea_runner_name)
+gitea_runner_base_data_dir: "/var/lib/gitea-runner"
+gitea_runner_base_config_dir: "/etc/gitea-runner"
+gitea_runner_data_dir: "{{ gitea_runner_base_data_dir }}/{{ gitea_runner_name }}"
+gitea_runner_config_dir: "{{ gitea_runner_base_config_dir }}/{{ gitea_runner_name }}"
+gitea_runner_binary_path: "/usr/local/bin/gitea_runner"
+
+# Prune configuration
+gitea_runner_prune_until: "24h"
+gitea_runner_prune_schedule: "daily"
+gitea_runner_prune_label: "gitea-runner=true"
+
+# Service configuration
+gitea_runner_service_restart_sec: "5"
+
+# Health check configuration
+gitea_runner_healthcheck_interval: "5min"
+gitea_runner_healthcheck_boot_delay: "2min"
+gitea_runner_healthcheck_disk_threshold: 85
+gitea_runner_healthcheck_script_path: "{{ gitea_runner_config_dir }}/healthcheck.sh"
+
+# Admin token for runner deregistration via Gitea API.
+# If not set, falls back to registration_token (which likely lacks admin scope).
+# Set this to a token with admin scope to enable automatic runner cleanup on removal.
+gitea_runner_admin_token: ""
+
+# Removal defaults
+gitea_runner_remove_systemd_template: true
+gitea_runner_remove_user: true
+
+# Runner configuration
+gitea_runner_log_level: "info"
+gitea_runner_container_label: "gitea-runner=true"
+gitea_runner_file: ".runner"
+
+# Docker installation (for rootless dependencies)
+gitea_runner_docker_gpg_key_path: "/etc/apt/keyrings/docker.gpg"
+gitea_runner_docker_apt_arch: "{{ 'amd64' if ansible_facts['architecture'] == 'x86_64' else ansible_facts['architecture'] }}"
+gitea_runner_docker_apt_source_line: >-
+  deb [arch={{ gitea_runner_docker_apt_arch }} signed-by={{ gitea_runner_docker_gpg_key_path }}]
+  https://download.docker.com/linux/{{ ansible_facts['distribution'] | lower }}
+  {{ ansible_facts['distribution_release'] }} stable
+# Set to false in CI/molecule to skip rootless daemon startup (needs kernel userns)
+gitea_runner_docker_rootless_setup: true
+
+# Rootless Docker helper scripts (dockerd-rootless-setuptool.sh / dockerd-rootless.sh).
+# Arch Linux's "docker" package does not ship these (unlike Debian's docker-ce-rootless-extras),
+# and no official Arch package provides them. They are fetched from the upstream moby/moby
+# "contrib/" directory at the git ref below. The scripts are stable bash wrappers that are
+# version-agnostic with respect to the dockerd binary, so a pinned ref is safe.
+gitea_runner_rootless_scripts_ref: "v28.5.1"
+# Install dir MUST match the location of the "docker" / "dockerd" / "rootlesskit" binaries so
+# that dockerd-rootless-setuptool.sh (which derives BIN from its own dirname) finds them co-located.
+gitea_runner_rootless_scripts_install_dir: "/usr/bin"
+
+# Rootless Docker network driver: "pasta" (IPv6 support) or "slirp4netns" (IPv4 only)
+# pasta has proper outgoing IPv6 support; slirp4netns does not (known limitation).
+gitea_runner_docker_rootless_net_driver: "pasta"
+
+# IPv6 subnet for rootless Docker containers (ULA range, not routable on internet)
+gitea_runner_docker_ipv6_cidr: "fd00:dead:beef::/48"

ansible/roles/gitea_runner/handlers/main.yml

@@ -9,4 +9,4 @@
   when:
     - ansible_facts is defined
     - ansible_facts['service_mgr'] | default('') == 'systemd'
-    - docker_rootless_setup
+    - gitea_runner_docker_rootless_setup

ansible/roles/gitea_runner/molecule/default/converge.yml

@@ -0,0 +1,12 @@
+---
+- name: Converge
+  hosts: all
+  become: true
+  vars:
+    gitea_url: "http://localhost:3000"
+    registration_token: "fake-token-for-testing"
+    gitea_runner_name: "molecule-test-runner"
+    gitea_runner_skip_registration: true
+    gitea_runner_docker_rootless_setup: false
+  roles:
+    - role: gitea_runner

ansible/roles/gitea_runner/molecule/default/verify.yml

@@ -3,7 +3,7 @@
   hosts: all
   become: true
   vars:
-    runner_name: "molecule-test-runner"
+    gitea_runner_name: "molecule-test-runner"
   pre_tasks:
     - name: Load role defaults
       ansible.builtin.include_vars:

ansible/roles/gitea_runner/molecule/deregister/converge.yml

@@ -0,0 +1,12 @@
+---
+- name: Converge
+  hosts: all
+  become: true
+  vars:
+    gitea_url: "http://localhost:3000"
+    registration_token: "fake-token-for-testing"
+    gitea_runner_name: "deregister-test-runner"
+    gitea_runner_skip_registration: true
+    gitea_runner_docker_rootless_setup: false
+  roles:
+    - role: gitea_runner

ansible/roles/gitea_runner/molecule/deregister/side_effect.yml

@@ -3,7 +3,7 @@
   hosts: all
   become: true
   vars:
-    runner_name: "deregister-test-runner"
+    gitea_runner_name: "deregister-test-runner"
   pre_tasks:
     - name: Load role defaults
       ansible.builtin.include_vars:
@@ -13,7 +13,7 @@
       ansible.builtin.copy:
         dest: "{{ gitea_runner_data_dir }}/.runner"
         content: |
-          {"id": 1, "uuid": "test-uuid-1234", "name": "{{ runner_name }}", "address": "http://localhost:3000"}
+          {"id": 1, "uuid": "test-uuid-1234", "name": "{{ gitea_runner_name }}", "address": "http://localhost:3000"}
         owner: "{{ gitea_runner_service_user }}"
         group: "{{ gitea_runner_service_user }}"
         mode: "0644"
@@ -22,12 +22,12 @@
   hosts: all
   become: true
   vars:
-    runner_name: "deregister-test-runner"
+    gitea_runner_name: "deregister-test-runner"
     registration_token: "fake-token-for-testing"
     gitea_url: "http://localhost:3000"
-    skip_runner_registration: false
+    gitea_runner_skip_registration: false
   tasks:
     - name: Include deregistration tasks
       ansible.builtin.include_role:
-        name: gitea-runner
+        name: gitea_runner
         tasks_from: deregister.yml

ansible/roles/gitea_runner/molecule/deregister/verify.yml

@@ -3,7 +3,7 @@
   hosts: all
   become: true
   vars:
-    runner_name: "deregister-test-runner"
+    gitea_runner_name: "deregister-test-runner"
   pre_tasks:
     - name: Load role defaults
       ansible.builtin.include_vars:
@@ -12,12 +12,12 @@
     - name: Check registration file was removed
       ansible.builtin.stat:
         path: "{{ gitea_runner_data_dir }}/.runner"
-      register: runner_file_stat
+      register: gitea_runner_file_stat
 
     - name: Assert registration file no longer exists
       ansible.builtin.assert:
         that:
-          - not runner_file_stat.stat.exists
+          - not gitea_runner_file_stat.stat.exists
         fail_msg: "Registration file (.runner) was not removed by deregistration"
 
     - name: Check systemd user service still exists

ansible/roles/gitea_runner/molecule/lifecycle/converge.yml

@@ -0,0 +1,12 @@
+---
+- name: Converge
+  hosts: all
+  become: true
+  vars:
+    gitea_url: "http://localhost:3000"
+    registration_token: "fake-token-for-testing"
+    gitea_runner_name: "lifecycle-test-runner"
+    gitea_runner_skip_registration: true
+    gitea_runner_docker_rootless_setup: false
+  roles:
+    - role: gitea_runner

ansible/roles/gitea_runner/molecule/lifecycle/side_effect.yml

@@ -3,7 +3,7 @@
   hosts: all
   become: true
   vars:
-    runner_name: "lifecycle-test-runner"
+    gitea_runner_name: "lifecycle-test-runner"
   pre_tasks:
     - name: Load role defaults
       ansible.builtin.include_vars:
@@ -23,7 +23,7 @@
   hosts: all
   become: true
   vars:
-    runner_name: "lifecycle-test-runner"
+    gitea_runner_name: "lifecycle-test-runner"
   pre_tasks:
     - name: Load role defaults
       ansible.builtin.include_vars:

ansible/roles/gitea_runner/molecule/lifecycle/verify.yml

@@ -3,7 +3,7 @@
   hosts: all
   become: true
   vars:
-    runner_name: "lifecycle-test-runner"
+    gitea_runner_name: "lifecycle-test-runner"
   pre_tasks:
     - name: Load role defaults
       ansible.builtin.include_vars:

ansible/roles/gitea_runner/molecule/multi-instance/converge.yml

@@ -5,11 +5,11 @@
   vars:
     gitea_url: "http://localhost:3000"
     registration_token: "fake-token-for-testing"
-    runner_name: "molecule-runner-a"
-    skip_runner_registration: true
-    docker_rootless_setup: false
+    gitea_runner_name: "molecule-runner-a"
+    gitea_runner_skip_registration: true
+    gitea_runner_docker_rootless_setup: false
   roles:
-    - role: gitea-runner
+    - role: gitea_runner
 
 - name: Converge second runner instance
   hosts: all
@@ -17,8 +17,8 @@
   vars:
     gitea_url: "http://localhost:3000"
     registration_token: "fake-token-for-testing"
-    runner_name: "molecule-runner-b"
-    skip_runner_registration: true
-    docker_rootless_setup: false
+    gitea_runner_name: "molecule-runner-b"
+    gitea_runner_skip_registration: true
+    gitea_runner_docker_rootless_setup: false
   roles:
-    - role: gitea-runner
+    - role: gitea_runner