release: v0.40.0 [skip ci]

Update hardcoded path and docstring examples from
`gitea_runner_manager` to `grm` after the package rename in grm PR #203.

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

@@ -0,0 +1,98 @@
+# testing-and-debugging
+
+Make targets for testing, debugging, and CI investigation. **Use these
+instead of raw `pytest`, `ruff`, or `actionlint` commands.**
+
+## Why Make Targets
+
+Make targets encapsulate the correct venv activation, PYTHONPATH, env
+vars, and flags. Running raw commands bypasses venv activation and
+produces false failures (missing dependencies, wrong Python version).
+
+## Unit Tests
+
+| Task | Command | Notes |
+|------|---------|-------|
+| Run all unit tests | `make test-unit` | Fast, no coverage |
+| Run with coverage | `make pytest-cov` | **Required before push** — enforces 100% |
+| Run single test | `make pytest-cov TEST=tests/test_foo.py::test_bar` | |
+| Check test speed | `make check-test-speed` | Fails if tests > 10s total or > 0.5s each |
+| Check test coverage | `make check-test-coverage` | Fails if source changed but tests didn't |
+
+## Linting
+
+| Task | Command | Notes |
+|------|---------|-------|
+| Full lint | `make lint-all` | ruff + workflow-lint + lint-dockerfiles |
+| Ruff only | `make lint-ruff` | |
+| Format check | `make lint-format` | |
+| Type check | `make typecheck` | pyright |
+| Bandit | `make lint-bandit` | Security linter |
+| Workflow lint | `make workflow-check` | actionlint + act_runner dry-run |
+| Dockerfile lint | `make lint-dockerfiles` | hadolint on all Dockerfiles |
+| Check mutable globals | `make check-mutable-globals` | Detects module-level mutable state |
+| Check dep docs | `make check-dep-docs` | Verifies pyproject.toml deps have comments |
+
+## Pre-Push Verification
+
+**Before pushing any branch:**
+
+```bash
+make pre-push
+```
+
+This runs `lint-all` + `pytest-cov`. The pre-push git hook only
+validates the Vikunja task exists — it does NOT run tests. You must
+run `make pre-push` manually.
+
+## CI Failure Investigation
+
+When investigating a CI failure:
+
+1. **Fetch logs via MCP** — use `mcp_call_tool` with gitea server,
+   `actions_run_read` method, `download_job_log` tool
+2. **Reproduce locally** — use `make pytest-cov` or `make lint-all`
+   depending on which CI job failed
+3. **Never run raw pytest** — always use the make target
+
+## Virtual Environment
+
+All commands run inside `.venv`. `make` targets handle activation
+automatically. For raw commands (rare), activate first:
+
+```bash
+source activate.sh       # bash/zsh
+source activate.fish     # fish
+source activate.zsh      # zsh
+```
+
+If `.venv` doesn't exist, run `make setup` first.
+
+## Common Pitfalls
+
+### Coverage Verification Before Push
+
+**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
+pre-push git hook only validates Vikunja task existence, not tests.
+
+### API Response Type Checking
+
+Never use `is True`/`is False` identity checks on API response values.
+Many APIs return boolean values as strings (`"true"`/`"false"`). Use
+the `is_truthy()`/`is_falsy()` helpers from `devx.utils.api` or compare
+against string values.
+
+### Time Mocking in Tests
+
+Always mock `time.sleep` and `time.monotonic` in unit tests using
+`@patch` decorators. Real sleep calls make tests slow and exceed test
+speed limits (10s total, 0.5s per test).
+
+### Mutable Global State
+
+The `check-mutable-globals` tool detects module-level mutable state
+(lists, dicts, sets) that can cause test pollution. Avoid module-level
+mutable defaults — use factory functions or `None` with initialization
+inside functions.

.env.example

@@ -1,6 +1,19 @@
-# Gitea API token (required for CI scripts that interact with Gitea)
+# Role-based Gitea API tokens.
+# Each token serves a specific role. For small teams the developer and CI
+# tokens may belong to the same user, but the reviewer token MUST belong to a
+# different Gitea user than the PR author so Gitea accepts approval reviews.
 # Create at: https://git.oblachno.oblachno.fyi/user/settings/applications
-CI_GITEA_TOKEN=
+
+# Developer token — used by local tooling: create-task, create-pr, setup, etc.
+DEVELOPER_GITEA_API_TOKEN=
+
+# CI token — used by CI workflows and scripts that do not post approvals.
+# Legacy CI_GITEA_TOKEN is also accepted.
+CI_GITEA_API_TOKEN=
+
+# Reviewer token — used by the auto-merge workflow to post APPROVE reviews.
+# This must be a different Gitea user from the developer/CI user.
+REVIEWER_GITEA_API_TOKEN=
 
 # Vikunja API token (required for post-merge task updates)
 # Create at: https://work.oblachno.oblachno.fyi/settings/tokens

.gitea/workflows/build-images.yml

@@ -38,6 +38,8 @@ jobs:
         with:
           fetch-depth: 1
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-ci
       - name: Check if this is a release commit
         id: check
@@ -62,18 +64,22 @@ jobs:
           fetch-depth: 0
       - name: Set up environment
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-release
       - name: Docker registry login
         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: |
           . .venv/bin/activate
-          echo "$CI_GITEA_TOKEN" | docker login git.oblachno.oblachno.fyi -u "$CI_GITEA_USERNAME" --password-stdin
+          _TOKEN="$CI_GITEA_API_TOKEN"
+          [ -z "$_TOKEN" ] && _TOKEN="$DEVELOPER_GITEA_API_TOKEN"
+          [ -z "$_TOKEN" ] && _TOKEN="$CI_GITEA_TOKEN"
+          if [ -z "$_TOKEN" ]; then echo "Gitea API token not set — skipping Docker login"; exit 1; fi
+          echo "$_TOKEN" | docker login git.oblachno.oblachno.fyi -u "$CI_GITEA_USERNAME" --password-stdin
       - name: Build and push tier images
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
           PYTHONPATH: src
         run: |
@@ -103,7 +109,7 @@ jobs:
       - name: Notify on failure
         if: failure()
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
@@ -125,10 +131,12 @@ jobs:
         with:
           fetch-depth: 1
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-ci
       - name: Clean up old image versions
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate

.gitea/workflows/ci.yml

@@ -16,6 +16,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Lint all
         run: |
@@ -32,18 +34,15 @@ jobs:
         run: |
           . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.tools.check_test_speed --max-seconds 6 --max-single-seconds 0.5
-      - name: Documentation coverage check
+      - name: Documentation gate (coverage + stale refs + lint + version refs + prose)
         env:
           PYTHONPATH: src
+          DEVX_DOC_COVERAGE_STRICT: "1"
+          DEVX_VALE_LEVEL: warning
         run: |
           . .venv/bin/activate 2>/dev/null || true
-          python3 -m devx.ci.doc_coverage --fail-on-missing
-      - name: Documentation lint check
-        env:
-          PYTHONPATH: src
-        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
         env:
           PYTHONPATH: src
@@ -82,6 +81,8 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Detect changed paths
         id: detect
@@ -109,10 +110,11 @@ jobs:
           fetch-depth: 0
       - name: Set up environment
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Release dry-run validation
         env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
@@ -130,10 +132,12 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Run automated PR review
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           set -euo pipefail
@@ -163,12 +167,14 @@ 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_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - 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
@@ -183,7 +189,7 @@ jobs:
             --body "Auto-approved: all CI checks passed (quality, pr-review, release-dry-run)."
       - 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 }}
           DEVX_VIKUNJA_PROJECT_ID: "8"
           PYTHONPATH: src

.gitea/workflows/post-merge.yml

@@ -8,7 +8,8 @@ name: Post-merge
 #   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)
+#                 ├── badges (needs release — ALWAYS runs, waits for release
+#                 │           so version badge picks up new __version__)
 #                 ├── 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)
@@ -17,9 +18,10 @@ name: Post-merge
 # 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 job uses `if: always()` and needs `release` so it waits for
+# the release job to complete (whether it ran or was skipped). This ensures
+# the version badge always reflects the latest __version__ on master.
+# Badges run on every push to master, including release commits.
 #
 # 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
@@ -45,6 +47,8 @@ jobs:
         with:
           fetch-depth: 1
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Check if this is a release commit
         id: check
@@ -68,6 +72,8 @@ jobs:
         with:
           fetch-depth: 1
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Validate latest commit message
         env:
@@ -93,10 +99,10 @@ 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 }}
         run: make setup-image
       - name: Configure git
         run: |
@@ -105,6 +111,7 @@ jobs:
       - name: Run release
         id: release-tag
         env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
@@ -113,7 +120,7 @@ jobs:
       - name: Notify on failure
         if: failure()
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
@@ -140,10 +147,12 @@ jobs:
           fetch-depth: 0
           ref: ${{ needs.release.outputs.tag }}
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image EXTRAS=release
       - name: Build and publish release
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
@@ -152,7 +161,7 @@ jobs:
       - name: Notify on failure
         if: failure()
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
@@ -169,7 +178,10 @@ jobs:
     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
+    timeout-minutes: 15
+    concurrency:
+      group: sync-wiki-${{ github.repository }}
+      cancel-in-progress: false
     defaults:
       run:
         shell: bash
@@ -178,18 +190,20 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Sync documentation to wiki
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
-          python3 -m devx.ci.sync_wiki --repo "${{ github.repository }}" --strict
+          python3 -m devx.ci.sync_wiki --repo "${{ github.repository }}" --verify
       - name: Notify on failure
         if: failure()
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           export PATH="$HOME/.local/bin:$PATH"
@@ -201,7 +215,7 @@ jobs:
             --auto-login
 
   badges:
-    needs: [detect-type]
+    needs: [detect-type, release]
     if: always()
     runs-on: docker
     container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest
@@ -214,15 +228,18 @@ jobs:
         with:
           fetch-depth: 0
           ref: master
-          token: ${{ secrets.CI_GITEA_TOKEN }}
+          token: ${{ secrets.CI_GITEA_API_TOKEN }}
       - name: Fetch latest master
         run: |
           git fetch origin master
           git reset --hard origin/master
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Generate and push badges
         env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PRE_COMMIT_ALLOW_NO_CONFIG: "1"
         run: |
           . .venv/bin/activate 2>/dev/null || true
@@ -230,7 +247,7 @@ jobs:
       - name: Notify on failure
         if: failure()
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           export PATH="$HOME/.local/bin:$PATH"
@@ -255,6 +272,8 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Update Vikunja task
         env:
@@ -267,7 +286,7 @@ jobs:
       - name: Notify on failure
         if: failure()
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           export PATH="$HOME/.local/bin:$PATH"
@@ -290,10 +309,12 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up environment
+        env:
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
         run: make setup-image
       - name: Ensure branch protection and labels
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
           DEVX_REPO_NAME: devx
           DEVX_REPO_OWNER: oblachno-oss
@@ -303,7 +324,7 @@ jobs:
       - name: Notify on failure
         if: failure()
         env:
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PYTHONPATH: src
         run: |
           export PATH="$HOME/.local/bin:$PATH"

.pre-commit-config.yaml

@@ -73,18 +73,12 @@ repos:
         pass_filenames: false
         stages: [pre-commit]
 
-      - id: doc-coverage
-        name: documentation coverage check
-        entry: env PYTHONPATH=src .venv/bin/python -m devx.ci.doc_coverage --fail-on-missing
-        language: system
-        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_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,49 @@
+# Vale configuration for devx 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 = devx
+
+[*.{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
+
+# 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/devx/accept.txt

@@ -0,0 +1,38 @@
+devx
+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
+Vikunja
+oblachno
+Oblachno
+Bulgarian

.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

@@ -18,19 +18,21 @@ venv activation automatically — always prefer `make <target>` over raw command
 
 ```bash
 make setup           # Create venv, install deps, set up hooks, install CI tools
-make install-tools   # Install actionlint, git-cliff, act_runner, tea, hadolint to ~/.local/bin
+make install-tools   # Install actionlint, git-cliff, act_runner, tea, hadolint, vale to ~/.local/bin
 make lint-all        # ruff + pyright + bandit + actionlint + lint-dockerfiles
 make pytest-cov      # Unit tests with 100% coverage enforcement
 make test-unit       # Unit tests without coverage
 make workflow-lint   # Static lint of .gitea/workflows/*.yml (actionlint)
 make workflow-dryrun # Dry-run all workflows in Docker (act_runner exec --dryrun)
 make workflow-check  # workflow-lint + workflow-dryrun
+make devx-check-doc-versions  # Verify docs version refs match __version__
+make devx-vale       # Run Vale prose linter on docs and README
 make clean           # Remove caches, build artifacts, coverage data
 ```
 
 `make setup` automatically installs all development tools:
 - **Python deps** via `python -m devx.tools.setup` (pip install -e .[dev], pre-commit hooks)
-- **actionlint, git-cliff, act_runner, tea, hadolint** via `python -m devx.tools.install_tools` (CI/CD tools to ~/.local/bin)
+- **actionlint, git-cliff, act_runner, tea, hadolint, vale** via `python -m devx.tools.install_tools` (CI/CD tools to ~/.local/bin)
 - **tea CLI login** via `python -m devx.tools.setup` (configures `tea login` from `.env` `CI_GITEA_TOKEN`)
 
 ## Workflow Verification (Before Push)
@@ -57,7 +59,7 @@ devx is a reusable Python package providing development and CI/CD tools for obla
 
 ### Package Structure
 
-```
+```text
 src/devx/
 ├── __init__.py          # Version (single source of truth, read by setuptools)
 ├── cli.py               # Click-based CLI entry point (devx command)
@@ -86,11 +88,14 @@ src/devx/
 │   ├── integration_guard.py # Run pytest with cross-runner fail-fast
 │   ├── check_translations.py  # Translation completeness check
 │   ├── doc_coverage.py  # Documentation coverage check
-│   └── lint_docs.py  # Documentation linter (structure, links, headings)
+│   ├── lint_docs.py  # Documentation linter (structure, links, headings, code blocks, orphans)
+│   ├── validate_deploy_ref.py  # Validate git tag for deployments (--github-output)
+│   └── record_deployed_tag.py  # Record deployed tag to Gitea repo variable
 ├── tools/               # Developer tooling modules (run locally or by CI)
 │   ├── setup.py         # Environment setup (venv, deps, hooks)
-│   ├── install_tools.py # Install actionlint, git-cliff, act_runner, tea, hadolint
+│   ├── install_tools.py # Install actionlint, git-cliff, act_runner, tea, hadolint, vale
 │   ├── install_checkmake.py  # Install checkmake (Makefile linter)
+│   ├── check_doc_versions.py  # Verify docs version refs match __version__
 │   ├── build_image.py   # Build and push Docker images to Gitea registry
 │   ├── clean_images.py  # Clean up old Docker image versions from Gitea registry
 │   ├── check_test_speed.py  # Measure unit test execution time
@@ -110,6 +115,16 @@ src/devx/
 │   ├── pre_push_check.py    # Validate Vikunja task existence before push
 │   └── _shared.py           # Shared tool utilities
 ├── opentofu.py          # OpenTofu output helpers (get_tofu_output, get_tofu_vm_ip, get_tofu_vm_field)
+├── utils/               # Shared utilities (reusable across projects)
+│   ├── api.py            # API response helpers (is_truthy, is_falsy)
+│   ├── ssh.py            # SSH exec + wait_for_ssh (pure-Python socket check)
+│   ├── crypto.py         # Secret generation (shell-safe passwords)
+│   ├── vault.py          # Ansible vault encrypt/decrypt helpers
+│   ├── network.py        # HTTP connectivity check + wait_for_ssh
+│   ├── confirm.py        # Typed confirmation validation for destructive ops
+│   ├── json_registry.py  # File-locked JSON registry for local state
+│   ├── step_tracker.py   # Multi-step operation tracking with reports
+│   └── logging.py        # XDG-compliant logging configuration
 └── molecule/            # Optional molecule testing helpers (for Ansible projects)
     ├── discover_runners.py    # Dynamic Gitea runner discovery
     ├── distribute_molecule.py # Distribute molecule scenarios across runners (LPT scheduling, --roles-root for multi-role)
@@ -145,6 +160,12 @@ The following rules are enforced for `master`:
 ### 1. Create Vikunja Task
 Create a task in Vikunja to get a `DEVX-N` identifier.
 
+**IMPORTANT:** The task title must NOT include the `DEVX-N:` prefix.
+The `make create-pr` and `check_auto_merge_ready` commands automatically
+prepend `DEVX-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
@@ -158,7 +179,7 @@ git checkout -b DEVX-N-short-description
 
 ### 4. Commit (Conventional Commits)
 Branch commits use conventional commit format (no `DEVX-N:` prefix):
-```
+```text
 feat: add new feature
 fix: resolve bug
 docs: update README
@@ -223,14 +244,14 @@ After a PR is merged to master, the **post-merge workflow**
    - Pushes both the commit and tag to master
 
 3. **sync-wiki** — Syncs documentation to the Gitea wiki. Runs for ALL
-   non-release commits (not just when release succeeds), so docs-only
+   non-release commits (not only 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.
 
 5. **vikunja** — Marks the corresponding Vikunja task as done. Runs for ALL
-   non-release commits (not just when release succeeds), so infrastructure-only
+   non-release commits (not only when release succeeds), so infrastructure-only
    changes still update the task tracker.
 
 6. **publish** — Runs after release succeeds (needs: release). Builds and
@@ -326,14 +347,14 @@ setuptools via `dynamic = ["version"]` in `pyproject.toml`.
 
 ### Task ID Resolution
 
-`auto_merge` resolves the task ID solely from the branch name (e.g.
+`auto_merge` resolves the task ID solely from the branch name (for example
 `DEVX-12-fix-foo` → `DEVX-12`). Branch names must include the task ID
 prefix — there is no `.taskid` file fallback. If a stale `.taskid` file
 exists in the repo, a deprecation warning is printed advising its removal.
 
 ### Workflow `auto-merge` Job and `always()`
 
-When `auto-merge` depends on a job that can be skipped (e.g.
+When `auto-merge` depends on a job that can be skipped (for example
 `molecule-tests`), the `if:` condition MUST include `always() &&`
 at the start. Without it, Gitea Actions skips `auto-merge` when any
 dependency is skipped, even if the condition explicitly allows
@@ -365,7 +386,7 @@ balanced distribution when test items have varying costs:
 2. **LPT assignment**: Items are sorted by weight (descending), then
    each is assigned to the runner with the least total weight.
 
-This ensures heavy scenarios (e.g. `nextcloud`) are spread across
+This ensures heavy scenarios (for example `nextcloud`) are spread across
 different runners rather than clustered on one, reducing the
 longest-runner time from ~16 min to ~11 min with 6 runners.
 
@@ -395,12 +416,12 @@ system loads `.env` automatically via `python-dotenv`.
 
 ### pyproject.toml [tool.devx] Configuration
 
-In addition to `DEVX_` env vars, several devx tools read configuration from
+In addition to `DEVX_` env vars, many devx tools read configuration from
 the `[tool.devx]` section in `pyproject.toml`. This allows per-project
 customization without environment variables.
 
 **Base config** (`[tool.devx]`):
-- `task_prefix` — Task ID prefix (e.g. `"DEVX"`, `"GRM"`, `"OBL-INFRA"`)
+- `task_prefix` — Task ID prefix (for example `"DEVX"`, `"GRM"`, `"OBL-INFRA"`)
 - `vikunja_project_id` — Vikunja project ID
 - `repo_owner` / `repo_name` — Gitea repository coordinates
 - `gitea_api_url` / `vikunja_api_url` — API endpoints
@@ -572,7 +593,7 @@ the user should not need to specify which profile to use.
 
 ### Available Profiles
 
-**Global** (shared with infra and grm):
+**Global** (shared across all projects):
 
 | Profile | Location | Purpose |
 |---------|----------|---------|
@@ -607,7 +628,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.
 

CHANGELOG.md

@@ -2,6 +2,114 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.40.0] - 2026-07-11
+
+### Features
+
+- Detect double-prefix in Vikunja task title during pre-merge validation
+
+## [0.39.0] - 2026-07-09
+
+### Features
+
+- Extract shared utilities from infra and grm into devx
+
+## [0.38.0] - 2026-07-08
+
+### Features
+
+- Introduce role-based Gitea API token environment variables
+
+## [0.37.0] - 2026-07-07
+
+### Features
+
+- Consolidate docs checks into devx-docs-check target
+
+## [0.36.2] - 2026-07-07
+
+### Bug Fixes
+
+- GiteaClient.set_repo_variable uses PUT instead of PATCH
+
+## [0.36.1] - 2026-07-07
+
+### Bug Fixes
+
+- Preserve .badges/ dir during git clean in push_badges
+
+## [0.36.0] - 2026-07-07
+
+### Features
+
+- Add GiteaClient repo variable methods and parallelize pytest-cov
+
+## [0.35.7] - 2026-07-06
+
+### Bug Fixes
+
+- Use Gitea wiki dash-marker filename convention
+
+## [0.35.6] - 2026-07-06
+
+### Bug Fixes
+
+- Add delay before wiki verification to avoid race condition
+
+## [0.35.5] - 2026-07-06
+
+### Bug Fixes
+
+- Embed token in wiki clone URL for push auth
+
+## [0.35.4] - 2026-07-06
+
+### Bug Fixes
+
+- Configure git identity before commit in sync_wiki
+
+## [0.35.3] - 2026-07-06
+
+### Bug Fixes
+
+- Replace --strict with --verify for sync_wiki
+
+## [0.35.2] - 2026-07-06
+
+### Bug Fixes
+
+- Exclude .vale directory from lint_docs scanning
+
+## [0.35.1] - 2026-07-06
+
+### Refactor
+
+- Rewrite sync_wiki.py to use git-based approach
+
+## [0.35.0] - 2026-07-06
+
+### Features
+
+- Enrich lint_docs.py with single H1, max depth, line length, code block lang, orphan checks
+
+## [0.34.0] - 2026-07-06
+
+### Features
+
+- Enhance documentation-as-code with badges, version refs, Vale
+
+## [0.33.4] - 2026-07-06
+
+### Refactor
+
+- Remove project-specific references from devx
+
+## [0.33.3] - 2026-07-06
+
+### Bug Fixes
+
+- Make wiki sync resilient to API timeouts and stale page lists
+
 ## [0.33.2] - 2026-07-05
 
 ### Bug Fixes

README.md

@@ -16,12 +16,12 @@ quality badges.
 
 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/python.svg)](https://www.python.org/downloads/)
 
 ## Why devx?
 
@@ -87,7 +87,7 @@ extra index and list devx in your dependencies:
 ```toml
 [project]
 dependencies = [
-    "devx>=0.27.0",
+    "devx>=0.40.0",
 ]
 
 [tool.pip]
@@ -101,8 +101,8 @@ pip install -e .
 ```
 
 > **Note:** If your project requires a specific devx version, pin it in
-> `dependencies` (e.g., `"devx==0.27.0"`) or use a version constraint
-> (e.g., `"devx>=0.27.0,<0.28"`).
+> `dependencies` (for example, `"devx==0.40.0"`) or use a version constraint
+> (for example, `"devx>=0.40.0,<0.41"`).
 
 ### Optional extras
 
@@ -372,7 +372,7 @@ infrastructure = []
 
 # Files that would default to user-facing but are actually infrastructure
 infrastructure_overrides = [
-    "src/myproject/__init__.py",  # only contains __version__
+    "src/myproject/__init__.py",  # example only — only contains __version__
 ]
 
 # Safety override for broad infrastructure patterns
@@ -420,7 +420,7 @@ make clean         # Remove caches, build artifacts, coverage data
 | `make lint-deps` | pip-audit dependency vulnerability scan |
 | `make test-unit` | Unit tests without coverage |
 | `make pytest-cov` | Unit tests with 100% coverage enforcement |
-| `make workflow-lint` | actionlint on .gitea/workflows/*.yml |
+| `make workflow-lint` | actionlint on `.gitea/workflows/*.yml` |
 | `make workflow-dryrun` | act_runner exec --dryrun on all workflows |
 | `make workflow-check` | workflow-lint + workflow-dryrun |
 | `make clean` | Remove caches, build artifacts, coverage data |
@@ -434,7 +434,7 @@ devx is a self-contained Python package under `src/devx/`. It never imports
 from scripts outside the package. All tools are invoked via
 `python -m devx.ci.*`, `python -m devx.tools.*`, or `python -m devx.molecule.*`.
 
-```
+```text
 src/devx/
 ├── __init__.py          # Version (single source of truth, read by setuptools)
 ├── cli.py               # Click-based CLI entry point (devx command)

docker/ci-quality/Dockerfile

@@ -13,7 +13,7 @@ RUN pip install --no-cache-dir /tmp/devx[lint] \
     && rm -rf /tmp/devx
 
 # Install CI/CD binary tools
-RUN python3 -m devx.tools.install_tools --tool actionlint \
+RUN python3 -m devx.tools.install_tools --tool actionlint --tool vale \
     && python3 -m devx.tools.install_checkmake
 
 # Install hadolint (Dockerfile linter)

docs/index.md

@@ -12,12 +12,12 @@ project to be reusable across all oblachno-oss repositories.
 
 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/66fec9ab17b49e54a8ea382b6e3b338eb2c973ea/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/c9f25c1348d9703783e473e54f9d624879667bbc/python.svg)](https://www.python.org/downloads/)
 
 ## Overview
 
@@ -74,14 +74,14 @@ Add devx to your `pyproject.toml` dependencies and configure the registry:
 ```toml
 [project]
 dependencies = [
-    "devx>=0.27.0",
+    "devx>=0.40.0",
 ]
 
 [tool.pip]
 extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
 ```
 
-Pin a specific version if needed: `"devx==0.27.0"` or `"devx>=0.27.0,<0.28"`.
+Pin a specific version if needed: `"devx==0.40.0"` or `"devx>=0.40.0,<0.41"`.
 
 ### Optional extras
 

docs/tech/architecture.md

@@ -6,7 +6,7 @@ from scripts outside the package.
 
 ## Package structure
 
-```
+```text
 src/devx/
 ├── __init__.py              # Version (single source of truth, read by setuptools)
 ├── cli.py                   # Click-based CLI entry point (devx command)
@@ -86,7 +86,7 @@ overridden via environment variables with the `DEVX_` prefix. Provides:
 
 - `GITEA_API_URL` / `VIKUNJA_API_URL` — API endpoints
 - `REPO_OWNER` — repository owner (must be set per-project)
-- `TASK_PREFIX` / `TASK_ID_RE` — task ID prefix and regex (e.g., `DEVX-N`)
+- `TASK_PREFIX` / `TASK_ID_RE` — task ID prefix and regex (for example, `DEVX-N`)
 - `VIKUNJA_PROJECT_ID` — Vikunja project for task tracking
 - `DEFAULT_TIMEOUT`, `DEFAULT_PER_PAGE` — HTTP client defaults
 - `MAX_RETRIES`, `RETRY_BACKOFF_BASE`, `RETRY_STATUS_CODES` — retry config
@@ -122,7 +122,9 @@ exponential backoff (2s, 4s, 8s).
 - Labels (list, create, add to issues)
 - Issues (create, list)
 - Pull requests (get commits, merge, create review)
-- Releases (list)
+- Releases (list, create idempotent)
+- Actions (list runs, list jobs, get job logs)
+- Actions variables (get, set idempotent)
 - Wiki pages (list, fetch, create, update, delete)
 
 **`VikunjaClient`** — Vikunja REST API wrapper:
@@ -206,7 +208,7 @@ a layered rule system configured in `pyproject.toml` under
 4. **Default**: user-facing (safe default — any unknown file triggers release)
 
 Also supports custom tags (orthogonal to release impact) for CI conditional
-execution (e.g., `ansible` tag to trigger molecule tests).
+execution (for example, `ansible` tag to trigger molecule tests).
 
 ### `pr_review.py`
 
@@ -309,7 +311,7 @@ from `devx.api_clients`, `devx.config`, and `devx.gitea_cli`.
 ### `setup.py`
 
 Project setup: installs Python dependencies (editable mode with extras),
-Ansible Galaxy collections (if `ansible/requirements.yml` exists), pre-commit
+Ansible Galaxy collections (if `ansible/requirements.yml` exists in the target repo), pre-commit
 hooks (pre-commit, commit-msg, pre-push), and configures the `tea` CLI login
 profile from `.env`. Supports `--extras` to specify dependency groups,
 `--no-pre-commit` to skip hook installation, and `--no-tea-login` to skip tea
@@ -432,14 +434,14 @@ v2 failures. Supports loading custom platforms from a JSON file.
 3. **Tool modules** (`devx.tools.*`) may import from `devx.api_clients`,
    `devx.config`, `devx.gitea_cli`
 4. **Cross-module imports** within `devx.ci.*` or `devx.tools.*` are allowed
-   but must be documented (e.g., `release.py` imports from
+   but must be documented (for example, `release.py` imports from
    `classify_changes.py`)
 
 ## Data flow
 
 ### PR lifecycle
 
-```
+```text
 Developer creates Vikunja task (DEVX-N)
     │
     ▼
@@ -475,7 +477,7 @@ CI workflow (ci.yml) triggers:
 
 ### Post-merge flow
 
-```
+```text
 Push to master (squash-merge commit: "DEVX-N <conventional commit>")
     │
     ▼
@@ -519,7 +521,7 @@ Post-merge workflow (post-merge.yml) triggers:
 
 ### Publish flow
 
-```
+```text
 Tag push (vX.Y.Z) triggers publish workflow (publish.yml):
     │
     ▼
@@ -536,7 +538,7 @@ Tag push (vX.Y.Z) triggers publish workflow (publish.yml):
 
 ### Badge generation flow
 
-```
+```text
 push_badges.py:
     │
     ├── fetch_latest_master() → git fetch + reset --hard origin/master

docs/tech/ci-cd-workflow.md

@@ -6,7 +6,7 @@ tag-triggered publishing.
 
 ## Workflow overview
 
-```
+```text
 PR opened/synchronized ──► CI (ci.yml)
     │                         ├── quality
     │                         ├── detect-changes
@@ -93,7 +93,7 @@ Depends on `quality`, `detect-changes`, and `pr-review`. The final job in the
 CI workflow. Runs `python -m devx.ci.auto_merge` with the branch name, PR
 title, repository, and PR number:
 
-1. **Read task ID** from branch name (e.g., `DEVX-12-fix-foo` → `DEVX-12`)
+1. **Read task ID** from branch name (for example, `DEVX-12-fix-foo` → `DEVX-12`)
 2. **Validate PR title format** — must be `{PREFIX}-N: <vikunja task title>`
 3. **Validate PR title matches Vikunja task** — fetches the Vikunja task and
    compares the title
@@ -143,7 +143,7 @@ updates.
 
 ### Job dependency graph
 
-```
+```text
 detect-type ──┬── validate-commit-msg (skip if release commit)
               ├── release (skip if release commit)
               │       │
@@ -205,7 +205,7 @@ automation job. Runs `python -m devx.ci.release`:
 8. **Push** — pushes both the commit and tag to master
 
 The script is idempotent: if there are no new conventional commits since the
-last tag, it exits without doing anything. If the tag already exists (e.g.,
+last tag, it exits without doing anything. If the tag already exists (for example,
 from a partial previous run), it skips tag creation and only pushes.
 
 **Tag consistency**: Before releasing, the script fetches remote tags and
@@ -251,7 +251,7 @@ badges using `python -m devx.ci.push_badges`:
 
 1. **Fetch latest master** — `git fetch origin master && git reset --hard
    origin/master` (ensures the version badge reflects the current state,
-   even if the release job just pushed a new version)
+   even if the release job recently pushed a new version)
 2. **Generate badges** — calls `devx.tools.generate_badges` which runs
    pytest-cov, doc-coverage, lint checks, and version extraction, then writes
    SVG files: `coverage.svg`, `tests.svg`, `docs.svg`, `quality.svg`,
@@ -329,7 +329,7 @@ On failure, the `notify_failure` step creates a Gitea issue.
 ### `auto_merge.py`
 
 Auto-merge PR when all CI checks pass. Reads task ID from the branch name
-(e.g., `DEVX-12-fix-foo` → `DEVX-12`). Validates PR title format, checks the
+(for example, `DEVX-12-fix-foo` → `DEVX-12`). Validates PR title format, checks the
 Vikunja task exists and the title matches, extracts the conventional commit
 message from PR commits, and squash-merges with
 `{PREFIX}-N <conventional commit>` title.

docs/user/cli-commands.md

@@ -405,7 +405,7 @@ devx tools install-tools --list             # list status
 ### `devx tools setup`
 
 Project setup: install Python dependencies (editable mode with extras),
-Ansible Galaxy collections (if `ansible/requirements.yml` exists), pre-commit
+Ansible Galaxy collections (if `ansible/requirements.yml` exists in the target repo), pre-commit
 hooks (pre-commit, commit-msg, pre-push), and configure the tea CLI login
 profile from `.env`.
 

docs/user/getting-started.md

@@ -48,12 +48,12 @@ Add devx to your `pyproject.toml`:
 ```toml
 [project]
 dependencies = [
-    "devx>=0.27.0",
+    "devx>=0.40.0",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "devx[dev]>=0.27.0",
+    "devx>=0.40.0",
 ]
 ```
 
@@ -72,7 +72,7 @@ tea CLI, etc.) and configure pre-commit hooks.
 
 devx expects a `docs/` directory with at minimum:
 
-```
+```text
 docs/
 ├── index.md          # Documentation home page
 ├── mapping.json      # Wiki page title mappings

pyproject.toml

@@ -121,6 +121,12 @@ vikunja_project_id = 8
 repo_owner = "oblachno-oss"
 repo_name = "devx"
 
+[tool.devx.check_agent_docs]
+skip_ref_prefixes = [
+    "src/myproject/",
+    "ansible/requirements.yml",
+]
+
 #   3. infrastructure (DEFAULT_INFRASTRUCTURE + project-specific patterns)
 #   4. Default: user-facing (safe)
 [tool.devx.classify]

src/devx/__init__.py

@@ -1,3 +1,3 @@
 """devx — reusable development and CI/CD tools for oblachno-oss projects."""
 
-__version__ = "0.33.2"
+__version__ = "0.40.0"

src/devx/api_clients.py

@@ -372,6 +372,36 @@ class GiteaClient:
         r = self._request("GET", f"/actions/jobs/{job_id}/logs")
         return r.text
 
+    # -- actions variables (repo-level) --
+
+    def get_repo_variable(self, name: str) -> str | None:
+        """Read a Gitea Actions repository variable.
+
+        Returns the variable value, or ``None`` if the variable is not set.
+        Raises :class:`APIError` on other HTTP errors.
+        """
+        try:
+            r = self._request("GET", f"/actions/variables/{name}")
+            return r.json().get("value")
+        except APIError as e:
+            if e.status == 404:
+                return None
+            raise
+
+    def set_repo_variable(self, name: str, value: str) -> None:
+        """Create or update a Gitea Actions repository variable (idempotent).
+
+        Tries PUT first (update); if the variable doesn't exist (404),
+        creates it via POST. Gitea 1.26.x does not support PATCH for
+        action variables.
+        """
+        try:
+            self._request("PUT", f"/actions/variables/{name}", json={"value": value})
+        except APIError as e:
+            if e.status != 404:
+                raise
+            self._request("POST", f"/actions/variables/{name}", json={"value": value})
+
 
 class VikunjaClient:
     """Low-level Vikunja REST API client with connection pooling."""

src/devx/ci/auto_merge.py

@@ -17,10 +17,9 @@ This allows the PR title to be a human-friendly Vikunja task title
 while the squashed commit follows conventional commits.
 
 Usage:
-  CI_GITEA_TOKEN=<token> python3 -m devx.ci.auto_merge <branch> <pr_title> <repo> <pr_number>
+  CI_GITEA_API_TOKEN=<token> VIKUNJA_TOKEN=<token> python3 -m devx.ci.auto_merge <branch> <pr_title> <repo> <pr_number>
 """
 
-import os
 import re
 from pathlib import Path
 from typing import Any
@@ -40,6 +39,7 @@ from devx.config import (
 )
 from devx.exceptions import APIError
 from devx.i18n import _
+from devx.tokens import get_ci_token, get_vikunja_token
 
 # Strip leading task ID prefix (e.g. "DEVX-12: " or "OBL-INFRA-364: ") from commit subjects.
 _TASK_ID_PREFIX_RE = re.compile(rf"^{TASK_PREFIX}-\d+:\s*")
@@ -115,9 +115,12 @@ def get_vikunja_task_title(task_id: str) -> str:
 
     Raises ClickException if VIKUNJA_TOKEN is not set or the task is not found.
     """
-    token = os.environ.get("VIKUNJA_TOKEN", "")
-    if not token:
-        raise click.ClickException(_("VIKUNJA_TOKEN is not set. This is required in CI to validate PR titles."))
+    try:
+        token = get_vikunja_token()
+    except click.ClickException:
+        raise click.ClickException(
+            _("VIKUNJA_TOKEN is not set. This is required in CI to validate PR titles.")
+        ) from None
     client = VikunjaClient(VIKUNJA_API_URL, token)
     page = 1
     while True:
@@ -197,9 +200,10 @@ def extract_conventional_msg(commits: list[dict[str, Any]]) -> str:
 @click.argument("repo")
 @click.argument("pr_number")
 def main(branch: str, pr_title: str, repo: str, pr_number: str) -> None:
-    token = os.environ.get("CI_GITEA_TOKEN", "")
-    if not token:
-        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set."))
+    try:
+        token = get_ci_token()
+    except click.ClickException:
+        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set.")) from None
 
     # Validate PR number is an integer
     try:

src/devx/ci/check_auto_merge_ready.py

@@ -15,7 +15,7 @@ Exit code 1 = NOT ready — fix issues before pushing.
 
 Usage::
 
-  # CI (with VIKUNJA_TOKEN and CI_GITEA_TOKEN):
+  # CI (with VIKUNJA_TOKEN and CI_GITEA_API_TOKEN):
   python3 -m devx.ci.check_auto_merge_ready \\
       --branch "$HEAD_REF" \\
       --pr-title "$PR_TITLE" \\
@@ -34,13 +34,12 @@ skipped (with a warning) — this allows local pre-push hooks to run
 without CI secrets.  In CI, the token is always set and the check is
 mandatory.
 
-If ``CI_GITEA_TOKEN`` is not set and ``--pr-number`` is not provided, only
+If ``CI_GITEA_API_TOKEN`` is not set and ``--pr-number`` is not provided, only
 branch-name and PR-title-format checks run (local mode).
 """
 
 from __future__ import annotations
 
-import os
 import subprocess  # nosec B404
 
 import click
@@ -55,6 +54,7 @@ from devx.config import (
 )
 from devx.exceptions import APIError
 from devx.i18n import _
+from devx.tokens import get_ci_token, get_vikunja_token
 
 load_dotenv()
 
@@ -99,10 +99,13 @@ def is_branch_behind_master(branch: str) -> bool:
 def get_pr_title_from_gitea(repo: str, pr_number: int) -> str | None:
     """Fetch the PR title from the Gitea API.
 
-    Returns ``None`` if ``CI_GITEA_TOKEN`` is not set or the PR cannot be fetched.
+    Returns ``None`` if no token is set or the PR cannot be fetched.
     """
-    token = os.environ.get("CI_GITEA_TOKEN", "")
-    if not token or "/" not in repo:
+    try:
+        token = get_ci_token()
+    except click.ClickException:
+        return None
+    if "/" not in repo:
         return None
     owner, repo_name = repo.split("/", 1)
     client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
@@ -120,8 +123,9 @@ def get_vikunja_title_optional(task_id: str) -> str | None:
     raise when ``VIKUNJA_TOKEN`` is missing — it returns ``None`` so the
     caller can skip the check in local mode.
     """
-    token = os.environ.get("VIKUNJA_TOKEN", "")
-    if not token:
+    try:
+        token = get_vikunja_token()
+    except click.ClickException:
         return None
     client = VikunjaClient(VIKUNJA_API_URL, token)
     from devx.config import DEFAULT_PER_PAGE
@@ -221,7 +225,11 @@ def cli(
     if not skip_vikunja:
         vikunja_title = get_vikunja_title_optional(task_id)
         if vikunja_title is None:
-            token_set = bool(os.environ.get("VIKUNJA_TOKEN", ""))
+            try:
+                get_vikunja_token()
+                token_set = True
+            except click.ClickException:
+                token_set = False
             if token_set:
                 errors.append(
                     _(
@@ -233,17 +241,33 @@ def cli(
             else:
                 click.echo("[pre-merge-check] WARNING: VIKUNJA_TOKEN not set — skipping Vikunja title match check.")
         else:
-            expected = f"{task_id}: {vikunja_title}"
-            if pr_title != expected:
+            # Defensive check: warn if the Vikunja task title already includes
+            # the task ID prefix. The expected PR title is
+            # f"{task_id}: {vikunja_title}" — if vikunja_title already starts
+            # with "{task_id}:", the PR title will have a double prefix.
+            if vikunja_title.startswith(f"{task_id}:"):
                 errors.append(
                     _(
-                        "PR title does not match Vikunja task title.\n  Expected: {expected}\n  Got:      {title}",
-                        expected=expected,
-                        title=pr_title,
+                        "Vikunja task title '{title}' starts with '{prefix}:'. "
+                        "The task title should NOT include the '{prefix}' prefix — "
+                        "it is automatically added to the PR title. "
+                        "Update the Vikunja task title to remove the prefix.",
+                        title=vikunja_title,
+                        prefix=task_id,
                     ),
                 )
             else:
-                click.echo(f"[pre-merge-check] Vikunja title match OK: {expected}")
+                expected = f"{task_id}: {vikunja_title}"
+                if pr_title != expected:
+                    errors.append(
+                        _(
+                            "PR title does not match Vikunja task title.\n  Expected: {expected}\n  Got:      {title}",
+                            expected=expected,
+                            title=pr_title,
+                        ),
+                    )
+                else:
+                    click.echo(f"[pre-merge-check] Vikunja title match OK: {expected}")
 
     # 6. Branch behind master (skip if --skip-behind-check)
     if not skip_behind_check:

src/devx/ci/check_translations.py

@@ -185,7 +185,7 @@ def main(translations: tuple[Path, ...], source_dir: str | None) -> None:
         # Try common locations
         candidates = [
             root / "src" / "devx" / "translations.json",
-            root / "src" / "gitea_runner_manager" / "translations.json",
+            root / "src" / "grm" / "translations.json",
         ]
         # Also search for any translations.json in src/
         for match in root.glob("src/*/translations.json"):

src/devx/ci/discover_runners.py

@@ -31,6 +31,7 @@ import requests
 
 from devx.config import GITEA_API_URL, REPO_NAME, REPO_OWNER
 from devx.i18n import _
+from devx.tokens import get_ci_token
 
 DEFAULT_MAX_RUNNERS = 3
 
@@ -96,7 +97,7 @@ def query_runners(api_url: str, token: str, owner: str, repo: str) -> int:
     return total
 
 
-def get_runner_count(api_url: str, token: str, owner: str, repo: str) -> int:
+def get_runner_count(api_url: str, token: str | None, owner: str, repo: str) -> int:
     """Determine the number of available runners.
 
     Tries the Gitea API first, then falls back to env vars, then default.
@@ -152,7 +153,10 @@ def main(
     output_indices: bool,
     github_output: bool,
 ) -> None:
-    token = os.environ.get("CI_GITEA_TOKEN", "")
+    try:
+        token = get_ci_token()
+    except click.ClickException:
+        token = None
 
     if owner is None:
         owner = os.environ.get("DEVX_REPO_OWNER", "") or REPO_OWNER

src/devx/ci/distribute_items.py

@@ -7,7 +7,7 @@ ordering, then assigned to *max_runners* groups using LPT (Longest
 Processing Time first) scheduling.
 
 Each item is a string (e.g. an Ansible ``--limit`` pattern like
-``observability`` or ``infra-314-vm``). Optionally, items can be objects
+``observability`` or ``customer-1-vm``). Optionally, items can be objects
 with ``{"id": "...", "weight": N}`` to provide explicit weights.
 
 The assigned group for *runner_index* is written to ``$GITHUB_ENV`` as
@@ -15,7 +15,7 @@ The assigned group for *runner_index* is written to ``$GITHUB_ENV`` as
 
 Usage::
 
-    echo '["observability", "infra-314-vm"]' | \\
+    echo '["observability", "customer-1-vm"]' | \\
         python3 -m devx.ci.distribute_items \\
         --runner-index 1 --max-runners 3 \\
         --github-env --skip-if-excess

src/devx/ci/doc_coverage.py

@@ -21,6 +21,7 @@ from pathlib import Path
 
 import click
 
+from devx.config import _load_pyproject_devx
 from devx.i18n import _
 
 # Default to the current working directory (consuming repo's root)
@@ -71,12 +72,30 @@ def extract_cli_commands(source_dir: Path) -> list[str]:
     # Matches @cli.command, @ci.command, @tools.command, @molecule.command
     for match in re.finditer(r"@\w+\.command\b", content):
         # Check for explicit name="..." in the decorator arguments
-        decorator_end = content.find(")", match.start())
+        # Use a balanced paren search to find the end of the decorator
+        # (handles nested parens like @cli.command(help=_("...")))
+        depth = 0
+        decorator_end = match.start()
+        for i in range(match.start(), len(content)):
+            if content[i] == "(":
+                depth += 1
+            elif content[i] == ")":
+                depth -= 1
+                if depth == 0:
+                    decorator_end = i
+                    break
         decorator_text = content[match.start() : decorator_end + 1]
-        name_match = re.search(r'["\']([^"\']+)["\']', decorator_text)
+        # Look for explicit name="..." parameter (not help=, not other kwargs)
+        name_match = re.search(r'\bname\s*=\s*["\']([^"\']+)["\']', decorator_text)
         if name_match:
             commands.append(name_match.group(1))
             continue
+        # Look for a positional string argument (e.g. @cli.command("my-cmd"))
+        # but skip if the only strings are in help= or other keyword args
+        positional_match = re.search(r'@\w+\.command\s*\(\s*["\']([^"\']+)["\']', decorator_text)
+        if positional_match:
+            commands.append(positional_match.group(1))
+            continue
         # Find the next def statement after this decorator
         after = content[decorator_end:]
         def_match = re.search(r"def\s+(\w+)\s*\(", after)
@@ -106,16 +125,38 @@ def check_module_documented(module: str, docs_content: str) -> bool:
 @click.command()
 @click.option("--docs-dir", default=None, help="Path to the docs directory (default: ./docs).")
 @click.option("--source-dir", default=None, help="Path to the source directory (default: auto-detect from src/).")
+@click.option(
+    "--ci-scripts-dir",
+    default=None,
+    help=(
+        "Path to CI scripts directory (default: auto-detect from src/ci/). "
+        "Set to empty string to skip CI script checks."
+    ),
+)
 @click.option(
     "--fail-on-missing",
     is_flag=True,
     default=False,
     help="Exit with non-zero status if any documentation is missing.",
 )
-def main(docs_dir: str | None, source_dir: str | None, fail_on_missing: bool) -> None:
+def main(docs_dir: str | None, source_dir: str | None, ci_scripts_dir: str | None, fail_on_missing: bool) -> None:
     root = Path.cwd()
     docs_path = Path(docs_dir) if docs_dir else root / "docs"
 
+    # Read [tool.devx.doc_coverage] config from pyproject.toml
+    devx_cfg = _load_pyproject_devx()
+    doc_cov_cfg_raw: object = devx_cfg.get("doc_coverage", {}) if isinstance(devx_cfg, dict) else {}
+    doc_cov_cfg: dict[str, object] = doc_cov_cfg_raw if isinstance(doc_cov_cfg_raw, dict) else {}
+
+    # CLI args override config; config overrides defaults
+    if ci_scripts_dir is None and "ci_scripts_dir" in doc_cov_cfg:
+        ci_scripts_dir = str(doc_cov_cfg["ci_scripts_dir"])
+    if docs_dir is None and "docs_dir" in doc_cov_cfg:
+        docs_dir = str(doc_cov_cfg["docs_dir"])
+        docs_path = Path(docs_dir)
+    if source_dir is None and "source_dir" in doc_cov_cfg:
+        source_dir = str(doc_cov_cfg["source_dir"])
+
     # Auto-detect source directory
     if source_dir:
         src_path = Path(source_dir)
@@ -166,13 +207,27 @@ def main(docs_dir: str | None, source_dir: str | None, fail_on_missing: bool) ->
             missing.append(f"Module: {module}")
 
     # Check CI scripts in ci-cd-workflow.md
-    # Auto-detect CI scripts from ci/ subdirectory
+    # Auto-detect CI scripts from ci/ subdirectory, or use explicit config
     click.echo(_("\nChecking CI script documentation in ci-cd-workflow.md..."))
-    ci_dir = src_path / "ci" if src_path.name != "ci" else src_path
-    if ci_dir.exists():
-        detected_scripts = sorted(f.name for f in ci_dir.glob("*.py") if f.name != "__init__.py")
+    if ci_scripts_dir is not None:
+        # Explicit config — empty string means skip CI script checks
+        if ci_scripts_dir == "":
+            detected_scripts = []
+        else:
+            ci_dir = Path(ci_scripts_dir)
+            if ci_dir.exists():
+                detected_scripts = sorted(f.name for f in ci_dir.glob("*.py") if f.name != "__init__.py")
+            else:
+                detected_scripts = []
     else:
-        detected_scripts = REQUIRED_SCRIPTS
+        # Auto-detect from src_path/ci/
+        ci_dir = src_path / "ci" if src_path.name != "ci" else src_path
+        if ci_dir.exists():
+            detected_scripts = sorted(f.name for f in ci_dir.glob("*.py") if f.name != "__init__.py")
+        else:
+            # No ci/ directory found — skip CI script checks rather than falling back
+            # to REQUIRED_SCRIPTS (which is devx-specific)
+            detected_scripts = []
     total += len(detected_scripts)
     ci_docs = ci_cd_file.read_text() if ci_cd_file.exists() else ""
     for script in detected_scripts:

src/devx/ci/integration_guard.py

@@ -17,7 +17,7 @@ Usage::
 
 Environment variables:
     GITEA_URL           Base URL of the Gitea instance.
-    CI_GITEA_TOKEN      API token with repo access.
+    CI_GITEA_API_TOKEN  API token with repo access (CI_GITEA_TOKEN accepted for legacy).
     RUN_ID              Workflow run ID (GITHUB_RUN_ID).
     JOB_NAME            Base job name (GITHUB_JOB), e.g. "integration-tests".
     MATRIX_INDEX        Current matrix index (runner-index).
@@ -41,6 +41,7 @@ from devx.i18n import _
 from devx.molecule.molecule_ci_guard import (
     poll_for_other_failures,
 )
+from devx.tokens import get_ci_token
 
 POLL_INTERVAL = 10
 
@@ -50,7 +51,10 @@ POLL_INTERVAL = 10
 def cli(pytest_args: tuple[str, ...]) -> None:
     """Run pytest with cross-runner failure detection."""
     gitea_url = os.environ.get("GITEA_URL", "")
-    token = os.environ.get("CI_GITEA_TOKEN", "")
+    try:
+        token = get_ci_token()
+    except click.ClickException:
+        token = None
     run_id = int(os.environ.get("RUN_ID", "0"))
     job_name = os.environ.get("JOB_NAME", "integration-tests")
     current_index = int(os.environ.get("MATRIX_INDEX", "0"))

src/devx/ci/lint_docs.py

@@ -7,6 +7,12 @@ Checks performed (all configurable via pyproject.toml ``[tool.devx.docs]``):
 - **Broken internal links**: relative paths and anchors in markdown files
   must resolve to actual files and headings.
 - **Heading hierarchy**: no skipping heading levels (e.g., ``#`` → ``###``).
+- **Single H1**: each markdown file should have at most one H1 heading.
+- **Max heading depth**: headings should not exceed H4 (configurable).
+- **Max line length**: lines should not exceed 120 characters (configurable).
+- **Code block language**: fenced code blocks should specify a language.
+- **Orphan docs**: docs not linked from index.md or mapping.json (warning).
+- **Mapping completeness**: all docs/*.md should be in mapping.json (warning).
 - **TODO/FIXME**: flags leftover TODO/FIXME markers in documentation.
 - **Stale docs**: files not modified in >180 days (warning only).
 - **Trailing whitespace**: lines should not end with whitespace.
@@ -49,6 +55,15 @@ REQUIRED_DOC_FILES = ["index.md"]
 # Maximum age for docs before they're considered stale (days)
 STALE_THRESHOLD_DAYS = 180
 
+# Maximum heading depth (H4 by default)
+MAX_HEADING_DEPTH = 4
+
+# Maximum line length
+MAX_LINE_LENGTH = 120
+
+# Code block without language: ``` followed by optional whitespace only
+_CODE_BLOCK_NO_LANG_RE = re.compile(r"^```[ \t]*$", re.MULTILINE)
+
 # Files excluded from duplicate heading checks (auto-generated or structured
 # with repeated subsections under different parent sections)
 DUPLICATE_HEADING_EXCLUDES = {
@@ -70,6 +85,7 @@ _EXCLUDE_DIRS = {
     ".pytest_cache",
     ".devin",
     ".terraform",
+    ".vale",
     "site-packages",
     "dist-info",
 }
@@ -318,6 +334,120 @@ def check_duplicate_headings(root: Path) -> list[str]:
     return issues
 
 
+def check_single_h1(root: Path) -> list[str]:
+    """Check that each markdown file has at most one H1 heading."""
+    issues: list[str] = []
+    md_files = [f for f in root.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        if md_file.name in DUPLICATE_HEADING_EXCLUDES:
+            continue
+        content = strip_code_blocks(md_file.read_text(encoding="utf-8"))
+        h1_count = len(re.findall(r"^#\s+", content, re.MULTILINE))
+        if h1_count > 1:
+            issues.append(f"{rel_path}: {h1_count} H1 headings — should have at most 1")
+
+    return issues
+
+
+def check_max_heading_depth(root: Path) -> list[str]:
+    """Check that headings don't exceed MAX_HEADING_DEPTH."""
+    issues: list[str] = []
+    md_files = [f for f in root.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        content = strip_code_blocks(md_file.read_text(encoding="utf-8"))
+        for match in re.finditer(r"^(#{1,6})\s+", content, re.MULTILINE):
+            level = len(match.group(1))
+            if level > MAX_HEADING_DEPTH:
+                line_num = content[: match.start()].count("\n") + 1
+                issues.append(f"{rel_path}:{line_num}: heading depth H{level} exceeds max H{MAX_HEADING_DEPTH}")
+
+    return issues
+
+
+def check_line_length(root: Path) -> list[str]:
+    """Check that no lines exceed MAX_LINE_LENGTH characters."""
+    issues: list[str] = []
+    md_files = [f for f in root.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        content = md_file.read_text(encoding="utf-8")
+        for i, line in enumerate(content.splitlines(), 1):
+            if len(line) > MAX_LINE_LENGTH:
+                issues.append(f"{rel_path}:{i}: line too long ({len(line)} > {MAX_LINE_LENGTH} chars)")
+
+    return issues
+
+
+def check_code_block_languages(root: Path) -> list[str]:
+    """Check that fenced code blocks specify a language."""
+    issues: list[str] = []
+    md_files = [f for f in root.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        content = md_file.read_text(encoding="utf-8")
+        in_code_block = False
+        for i, line in enumerate(content.splitlines(), 1):
+            stripped = line.strip()
+            if stripped.startswith("```"):
+                if not in_code_block:
+                    # Opening fence — check for language
+                    if _CODE_BLOCK_NO_LANG_RE.match(line):
+                        issues.append(f"{rel_path}:{i}: code block without language specifier")
+                    in_code_block = True
+                else:
+                    # Closing fence
+                    in_code_block = False
+
+    return issues
+
+
+def check_orphan_docs(root: Path, docs_dir: Path) -> list[str]:
+    """Check for docs not linked from index.md or mapping.json (warnings)."""
+    issues: list[str] = []
+    if not docs_dir.is_dir():
+        return issues
+
+    # Collect all referenced files from index.md and mapping.json
+    referenced: set[str] = set()
+    index_file = docs_dir / "index.md"
+    if index_file.exists():
+        content = index_file.read_text(encoding="utf-8")
+        for match in _LINK_RE.finditer(content):
+            url = match.group(2).strip()
+            if not url.startswith(("http://", "https://", "mailto:")):
+                referenced.add(url.split("#")[0])
+
+    mapping_file = docs_dir / "mapping.json"
+    if mapping_file.exists():
+        try:
+            mapping = json.loads(mapping_file.read_text(encoding="utf-8"))
+            if isinstance(mapping, dict):
+                # Add both keys (filenames) and values (wiki page names)
+                for k, v in mapping.items():
+                    if isinstance(k, str):
+                        referenced.add(k)
+                    if isinstance(v, str):
+                        referenced.add(v)
+        except (json.JSONDecodeError, AttributeError):
+            pass
+
+    # Check each doc file
+    for md_file in sorted(docs_dir.rglob("*.md")):
+        if md_file.name == "index.md":
+            continue
+        rel_path = md_file.relative_to(docs_dir).as_posix()
+        if rel_path not in referenced and md_file.name not in referenced:
+            issues.append(f"docs/{rel_path}: orphan doc — not linked from index.md or mapping.json")
+
+    return issues
+
+
 @click.command()
 @click.option("--root", default=".", help="Repository root directory.")
 @click.option("--docs-dir", default=None, help="Docs directory (default: <root>/docs).")
@@ -327,6 +457,11 @@ def check_duplicate_headings(root: Path) -> list[str]:
 @click.option("--check-stale/--no-check-stale", default=False, help="Check for stale docs.")
 @click.option("--check-trailing/--no-check-trailing", default=True, help="Check trailing whitespace.")
 @click.option("--check-duplicates/--no-check-duplicates", default=True, help="Check duplicate headings.")
+@click.option("--check-single-h1/--no-check-single-h1", "single_h1", default=True, help="Check single H1 per file.")
+@click.option("--check-depth/--no-check-depth", "depth", default=True, help="Check max heading depth.")
+@click.option("--check-line-length/--no-check-line-length", "line_length", default=True, help="Check line length.")
+@click.option("--check-code-lang/--no-check-code-lang", "code_lang", default=True, help="Check code block languages.")
+@click.option("--check-orphans/--no-check-orphans", "orphans", default=False, help="Check for orphan docs (warnings).")
 @click.option("--fix", is_flag=True, default=False, help="Auto-fix trailing whitespace.")
 def main(
     root: str,
@@ -337,6 +472,11 @@ def main(
     check_stale: bool,
     check_trailing: bool,
     check_duplicates: bool,
+    single_h1: bool,
+    depth: bool,
+    line_length: bool,
+    code_lang: bool,
+    orphans: bool,
     fix: bool,
 ) -> None:
     """Lint documentation files for structure, links, and quality."""
@@ -369,6 +509,31 @@ def main(
         click.echo(_("Checking duplicate headings..."))
         all_issues.extend(check_duplicate_headings(root_path))
 
+    # Single H1
+    if single_h1:
+        click.echo(_("Checking single H1 per file..."))
+        all_issues.extend(check_single_h1(root_path))
+
+    # Max heading depth
+    if depth:
+        click.echo(_("Checking max heading depth..."))
+        all_issues.extend(check_max_heading_depth(root_path))
+
+    # Line length (warnings — badge URLs and tables can exceed 120)
+    if line_length:
+        click.echo(_("Checking line length..."))
+        ll_issues = check_line_length(root_path)
+        for issue in ll_issues[:10]:  # Show first 10 only
+            click.echo(f"  WARN: {issue}")
+        if len(ll_issues) > 10:
+            click.echo(_("  ... and {n} more", n=len(ll_issues) - 10))
+        click.echo(_("  {n} long lines found (warnings only)", n=len(ll_issues)))
+
+    # Code block languages
+    if code_lang:
+        click.echo(_("Checking code block languages..."))
+        all_issues.extend(check_code_block_languages(root_path))
+
     # TODO/FIXME
     if check_todo:
         click.echo(_("Checking for TODO/FIXME markers..."))
@@ -391,15 +556,22 @@ def main(
         else:
             all_issues.extend(ws_issues)
 
-    # Stale docs
+    # Stale docs (warnings)
     if check_stale:
         click.echo(_("Checking for stale docs..."))
         stale = check_stale_docs(root_path)
         for issue in stale:
             click.echo(f"  WARN: {issue}")
-        # Stale docs are warnings, not errors
         click.echo(_("  {n} stale docs found (warnings only)", n=len(stale)))
 
+    # Orphan docs (warnings)
+    if orphans:
+        click.echo(_("Checking for orphan docs..."))
+        orphan_issues = check_orphan_docs(root_path, docs_path)
+        for issue in orphan_issues:
+            click.echo(f"  WARN: {issue}")
+        click.echo(_("  {n} orphan docs found (warnings only)", n=len(orphan_issues)))
+
     # Report
     click.echo(f"\n{'=' * 60}")
     if all_issues:

src/devx/ci/notify_failure.py

@@ -6,7 +6,7 @@ otherwise go unnoticed in the Actions tab. Uses the ``tea`` Gitea CLI
 for issue creation — tea must be installed and configured.
 
 Usage:
-  CI_GITEA_TOKEN=<token> python3 -m devx.ci.notify_failure \
+  CI_GITEA_API_TOKEN=<token> python3 -m devx.ci.notify_failure \
     --repo <owner/repo> \
     --run-id <run_id> \
     --workflow <workflow_name> \
@@ -14,14 +14,13 @@ Usage:
     --auto-login
 
 With ``--auto-login``, the script configures the tea CLI login profile
-from ``CI_GITEA_TOKEN`` and ``DEVX_GITEA_API_URL`` before creating the issue,
+from the CI API token and ``DEVX_GITEA_API_URL`` before creating the issue,
 eliminating the need for a separate ``tea login add`` step in the workflow.
 """
 
 from __future__ import annotations
 
 import logging
-import os
 
 import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
@@ -29,6 +28,7 @@ from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnk
 from devx.config import GITEA_API_URL
 from devx.gitea_cli import TeaCLI, TeaCLIError, configure_tea_login
 from devx.i18n import _
+from devx.tokens import get_ci_token
 
 load_dotenv()
 
@@ -74,9 +74,10 @@ def _create_issue_via_tea(repo: str, title: str, body: str) -> int:
     help="Configure tea CLI login from CI_GITEA_TOKEN before creating the issue.",
 )
 def main(repo: str, run_id: str, workflow: str, commit: str, auto_login: bool) -> None:
-    token = os.environ.get("CI_GITEA_TOKEN", "")
-    if not token:
-        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set."))
+    try:
+        get_ci_token()
+    except click.ClickException:
+        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set.")) from None
 
     if auto_login:
         configure_tea_login()

src/devx/ci/post_merge.py

@@ -5,7 +5,6 @@ Usage:
   VIKUNJA_TOKEN=<token> python3 -m devx.ci.post_merge <commit_msg> [--commit-sha <sha>]
 """
 
-import os
 import re
 import subprocess  # nosec B404
 
@@ -17,6 +16,7 @@ from devx.ci._shared import extract_task_id as _extract_task_id
 from devx.config import DEFAULT_PER_PAGE, TASK_PREFIX, VIKUNJA_API_URL, VIKUNJA_PROJECT_ID
 from devx.exceptions import APIError
 from devx.i18n import _
+from devx.tokens import get_vikunja_token
 
 load_dotenv()
 
@@ -127,9 +127,10 @@ def main(commit_msg: str | None, commit_sha: str, from_git: bool, git_sha: str)
             commit_sha = _get_git_commit_sha()
     if not commit_msg:
         raise click.ClickException("commit_msg argument is required (or use --from-git or --git-sha)")
-    token = os.environ.get("VIKUNJA_TOKEN", "")
-    if not token:
-        raise click.ClickException(_("ERROR: VIKUNJA_TOKEN is not set."))
+    try:
+        token = get_vikunja_token()
+    except click.ClickException:
+        raise click.ClickException(_("ERROR: VIKUNJA_TOKEN is not set.")) from None
 
     task_id = extract_task_id(commit_msg)
     if not task_id:

src/devx/ci/pr_review.py

@@ -17,12 +17,11 @@ Checks performed:
   8. Commit conventions — conventional commit format on branch commits
 
 Usage:
-  CI_GITEA_TOKEN=<token> python3 -m devx.ci.pr_review <pr_number> <owner/repo>
+  CI_GITEA_API_TOKEN=<token> [REVIEWER_GITEA_API_TOKEN=<token>] python3 -m devx.ci.pr_review <pr_number> <owner/repo>
 """
 
 from __future__ import annotations
 
-import os
 import re
 from dataclasses import dataclass, field
 from typing import Any
@@ -34,6 +33,7 @@ from devx.api_clients import GiteaClient
 from devx.config import GITEA_API_URL
 from devx.exceptions import APIError
 from devx.i18n import _
+from devx.tokens import get_ci_token, get_reviewer_token
 
 load_dotenv()
 
@@ -636,9 +636,10 @@ def main(
     Without --event: runs automated checks and posts COMMENT/REQUEST_CHANGES.
     With --event: posts a manual review (skips automated checks).
     """
-    token = os.environ.get("CI_GITEA_TOKEN", "")
-    if not token:
-        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set."))
+    try:
+        token = get_reviewer_token() if (event and event.upper() == "APPROVE") else get_ci_token()
+    except click.ClickException:
+        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set.")) from None
 
     owner, repo_name = repo.split("/")
     client = GiteaClient(GITEA_API_URL, token, owner, repo_name)

src/devx/ci/publish.py

@@ -9,14 +9,14 @@ Publishing destinations (checked in order):
      ``DEVX_PYPI_REGISTRY_URL`` env var is set, or ``GITEA_API_URL``
      is converted to a packages URL). Uses ``twine upload
      --repository-url <url> -u <token> -p <token>`` with the
-     ``CI_GITEA_TOKEN`` as both username and password.
+     CI API token as both username and password.
   2. **Standard PyPI** — if ``PYPI_TOKEN`` is set. Uses the standard
      ``twine upload -u __token__ -p <token>`` flow.
   3. **Skip** — if neither is configured, only the Gitea release is created.
 
 Usage:
-  CI_GITEA_TOKEN=<token> [PYPI_TOKEN=<token>] python3 -m devx.ci.publish <tag> <repo>
-  CI_GITEA_TOKEN=<token> python3 -m devx.ci.publish <tag> <repo> --registry-url https://git.example.com/api/packages/owner/pypi
+  CI_GITEA_API_TOKEN=<token> [PYPI_TOKEN=<token>] python3 -m devx.ci.publish <tag> <repo>
+  CI_GITEA_API_TOKEN=<token> python3 -m devx.ci.publish <tag> <repo> --registry-url https://git.example.com/api/packages/owner/pypi
 """
 
 import os
@@ -31,6 +31,7 @@ from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnk
 from devx.config import GITEA_API_URL, REPO_OWNER
 from devx.gitea_cli import TeaCLI, TeaCLIError, configure_tea_login
 from devx.i18n import _
+from devx.tokens import get_ci_token
 
 load_dotenv()
 
@@ -253,9 +254,10 @@ def main(
 
     if not tag:
         raise click.ClickException(_("Tag is required (or use --from-tag)."))
-    gitea_token = os.environ.get("CI_GITEA_TOKEN", "")
-    if not gitea_token:
-        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set."))
+    try:
+        gitea_token = get_ci_token()
+    except click.ClickException:
+        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set.")) from None
 
     pypi_token = os.environ.get("PYPI_TOKEN", "")
 

src/devx/ci/push_badges.py

@@ -87,19 +87,26 @@ def push_to_badges_branch(badges_dir: str) -> str:
 
     Returns the commit SHA of the pushed badges branch.
     """
+    import shutil
+
     _run(["git", "config", "user.name", "gitea-actions-bot"])  # nosec B607
     _run(["git", "config", "user.email", "actions@oblachno.fyi"])  # nosec B607
     _run(["git", "checkout", "--orphan", "badges"])  # nosec B607
     _run(["git", "rm", "-rf", "."])  # nosec B607
+    # Remove untracked files/dirs left behind, but preserve .badges/ for copy below
+    _run(["git", "clean", "-fdx", "-e", ".git", "-e", badges_dir])  # nosec B607
 
     # Copy badge files to root
-    import shutil
-
     for svg in Path(badges_dir).glob("*.svg"):
         shutil.copy2(svg, Path.cwd() / svg.name)
 
     _run(["git", "add", "./*.svg"])  # nosec B607
-    _run(["git", "commit", "--no-verify", "-m", "Update badges [skip ci]"])  # nosec B607
+    # Commit even if no changes (ensures badges branch always exists)
+    result = _run_capture(["git", "diff", "--cached", "--name-only"])  # nosec B607
+    if result.stdout.strip():
+        _run(["git", "commit", "--no-verify", "-m", "Update badges [skip ci]"])  # nosec B607
+    else:
+        click.echo(_("No badge changes — skipping commit"))
     _run(["git", "push", "origin", "badges", "--force"])  # nosec B607
     click.echo(_("Badges pushed to badges branch"))
 
@@ -135,6 +142,22 @@ def update_readme_with_badge_sha(badges_sha: str, repo_root: Path | None = None)
     _run(["git", "fetch", "origin", "master"])  # nosec B607
     _run(["git", "reset", "--hard", "origin/master"])  # nosec B607
 
+    # Verify version badge matches current __version__
+    from devx.tools.generate_badges import detect_package_name, read_version
+
+    pkg = detect_package_name(root)
+    current_version = read_version(root) if pkg else "unknown"
+    version_svg = Path(".badges") / "version.svg"
+    if version_svg.exists():
+        svg_content = version_svg.read_text()
+        if current_version != "unknown" and f"v{current_version}" not in svg_content:
+            click.echo(
+                _(
+                    "WARNING: Version badge shows stale version (expected v{version}) — regenerating",
+                    version=current_version,
+                )
+            )
+
     updated_any = False
     for filename in FILES_WITH_BADGE_URLS:
         filepath = root / filename

src/devx/ci/record_deployed_tag.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Record the deployed git tag for a given environment.
+
+Writes the tag to a Gitea repository variable so it can be queried
+later via the Gitea API or ``devx.ci.get_deployed_tag``.
+
+Usage::
+
+    python -m devx.ci.record_deployed_tag --env production --tag v0.28.1
+    python -m devx.ci.record_deployed_tag --env staging --tag master-abc1234
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from devx.api_clients import GiteaClient
+from devx.config import GITEA_API_URL, REPO_NAME, REPO_OWNER
+from devx.i18n import _
+from devx.tokens import get_ci_token
+
+
+@click.command()
+@click.option(
+    "--env",
+    "env_name",
+    type=click.Choice(["staging", "production"]),
+    required=True,
+)
+@click.option("--tag", required=True, help=_("Git tag or ref that was deployed"))
+def main(env_name: str, tag: str) -> None:
+    """Record the deployed tag for the given environment."""
+    try:
+        token = get_ci_token()
+    except click.ClickException as exc:
+        click.echo(f"Error: {exc.message}", err=True)
+        sys.exit(1)
+
+    var_name = f"{env_name.upper()}_DEPLOY_TAG"
+    client = GiteaClient(GITEA_API_URL, token, REPO_OWNER, REPO_NAME)
+    client.set_repo_variable(var_name, tag)
+    click.echo(f"Recorded {var_name} = {tag}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/ci/release.py

@@ -29,7 +29,7 @@ version.  This prevents duplicate release commits (a common issue when CI
 checkouts don't fetch tags) and ensures tag/version/commit alignment.
 
 Usage:
-  CI_GITEA_TOKEN=<token> python3 -m devx.ci.release [--dry-run] [--skip-tests]
+  CI_GITEA_API_TOKEN=<token> python3 -m devx.ci.release [--dry-run] [--skip-tests]
   python3 -m devx.ci.release --verify   # Check tag/version/release alignment
 """
 
@@ -246,6 +246,32 @@ def update_changelog(changelog: str) -> None:
         f.write(updated)
 
 
+def update_doc_versions(new_version: str) -> None:
+    """Update documentation version references to match the new release.
+
+    Runs ``check_doc_versions --fix`` so that README.md and docs/*.md
+    always reference the latest released version.
+    """
+    import subprocess  # nosec B404
+
+    result = subprocess.run(  # nosec B603
+        [sys.executable, "-m", "devx.tools.check_doc_versions", "--fix"],
+        check=False,
+        text=True,
+        capture_output=True,
+    )
+    if result.returncode == 0:
+        click.echo(_("Updated documentation version references to v{version}", version=new_version))
+    else:
+        click.echo(
+            _(
+                "WARNING: check_doc_versions --fix failed (rc={rc}): {err}",
+                rc=result.returncode,
+                err=result.stderr.strip()[:200],
+            )
+        )
+
+
 def commit_release_changes(new_version: str) -> bool:
     """Stage version file and changelog, then create a release commit.
 
@@ -255,7 +281,7 @@ def commit_release_changes(new_version: str) -> bool:
     commits are a special case generated by the release script.
     Returns True if a commit was created, False if there were no staged changes.
     """
-    run_cmd(["git", "add", INIT_FILE, CHANGELOG_FILE])
+    run_cmd(["git", "add", INIT_FILE, CHANGELOG_FILE, "README.md", "docs/"])
     status = run_cmd(["git", "diff", "--cached", "--quiet"], check=False)
     if status.returncode == 0:
         click.echo(_("No staged changes — version and changelog already up to date."))
@@ -684,6 +710,7 @@ def main(dry_run: bool, skip_tests: bool, verify: bool) -> None:
         click.echo(_("\n[dry-run] Changelog:\n{changelog}", changelog=changelog))
         click.echo(_("[dry-run] Would update {init}", init=INIT_FILE))
         click.echo(_("[dry-run] Would update {changelog_file}", changelog_file=CHANGELOG_FILE))
+        click.echo(_("[dry-run] Would update doc version references via check_doc_versions --fix"))
         click.echo(_("[dry-run] Would commit: release: v{version} [skip ci]", version=new_version))
         click.echo(_("[dry-run] Would push commit to master"))
         click.echo(_("[dry-run] Would create tag: v{version}", version=new_version))
@@ -697,6 +724,9 @@ def main(dry_run: bool, skip_tests: bool, verify: bool) -> None:
     update_changelog(changelog)
     click.echo(_("Updated {changelog_file}", changelog_file=CHANGELOG_FILE))
 
+    # Update documentation version references (README, docs/*.md)
+    update_doc_versions(new_version)
+
     # Verify tests pass BEFORE committing or tagging.
     # This ensures we never release a version that fails tests.
     if skip_tests:

src/devx/ci/sync_wiki.py

@@ -1,62 +1,75 @@
 #!/usr/bin/env python3
-"""Sync documentation from /docs/ to the Gitea wiki via API.
+"""Sync documentation from /docs/ to the Gitea wiki via Git.
 
-Reads markdown files from the ``docs/`` directory, uses ``mapping.json`` to
-map file paths to wiki page titles, and creates/updates wiki pages via the
-Gitea API.  Pages that exist in the wiki but not in the mapping are left
-untouched (not deleted).
+Instead of using the Gitea wiki API (which is slow, unreliable, and
+prone to timeouts), this module clones the wiki Git repository,
+copies the documentation files into it, transforms internal links
+to wiki-friendly format, commits, and pushes.
 
-Gitea 1.26 wiki API endpoints (all use content_base64, NOT content):
-  - Create: POST /repos/{owner}/{repo}/wiki/new  {title, content_base64, message}
-  - Update: PATCH /repos/{owner}/{repo}/wiki/page/{sub_url}  {title, content_base64, message}
-  - List:   GET /repos/{owner}/{repo}/wiki/pages  → [{title, sub_url, ...}]
-  - Fetch:  GET /repos/{owner}/{repo}/wiki/page/{sub_url}  → {title, content_base64, ...}
-  - Delete: DELETE /repos/{owner}/{repo}/wiki/page/{sub_url}
+This approach is:
+- **Faster** — a single git push vs N API calls
+- **More reliable** — no API timeouts or rate limits
+- **Atomic** — all pages sync in one commit
+- **Auto-pruning** — stale wiki pages are removed automatically
+
+The wiki Git URL is ``{clone_url}.wiki.git`` (Gitea convention).
+
+Link transformations:
+- ``[text](file.md)`` → ``[text](file)`` (wiki pages don't use .md)
+- ``[text](docs/file.md)`` → ``[text](file)``
+- External links (http/https/mailto) are preserved
+- Anchor-only links (``#section``) are preserved
 
 Usage:
-  CI_GITEA_TOKEN=<token> python3 -m devx.ci.sync_wiki [--dry-run] [--repo owner/repo]
+  CI_GITEA_API_TOKEN=<token> python3 -m devx.ci.sync_wiki [--dry-run] [--repo owner/repo]
 """
 
 from __future__ import annotations
 
-import base64
 import json
-import logging
 import os
+import re
+import subprocess  # nosec B404
+import tempfile
+import time
 from pathlib import Path
+from urllib.parse import quote, urlparse
 
 import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
-from tenacity import (
-    before_sleep_log,
-    retry,
-    retry_if_exception_type,
-    stop_after_attempt,
-    wait_exponential,
-)
 
-from devx.api_clients import GiteaClient
 from devx.config import GITEA_API_URL, REPO_NAME, REPO_OWNER
-from devx.exceptions import APIError
 from devx.i18n import _
+from devx.tokens import get_ci_token
 
 load_dotenv()
 
-# DOCS_DIR is the repo's docs/ directory. When devx is installed as a
-# package (e.g., in .venv/lib/python3.12/site-packages/devx/), the
-# __file__-relative path would point inside the venv, not the repo.
-# Use DEVX_DOCS_DIR env var if set, otherwise fall back to ./docs
-# (relative to the current working directory, which is the repo root
-# in CI and local development).
 DOCS_DIR = Path(os.environ.get("DEVX_DOCS_DIR", "docs"))
 MAPPING_FILE = DOCS_DIR / "mapping.json"
 
+# Markdown link pattern: [text](url)
+_LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
+
+
+def wiki_filename(page_title: str) -> str:
+    """Convert a wiki page title to its Gitea wiki filename.
+
+    Gitea uses a "dash marker" (``.-``) suffix to distinguish literal dashes
+    from space-to-dash conversions.  See Gitea's ``services/wiki/wiki_path.go``.
+
+    - "Architecture" (no dashes) → ``Architecture.md``
+    - "Getting-Started" (has dashes) → ``Getting-Started.-.md``
+    - "Home" (no dashes) → ``Home.md``
+    """
+    name = page_title.replace(" ", "-")
+    if "-" in name:
+        name += ".-"
+    name += ".md"
+    return quote(name, safe="")
+
 
 def load_mapping() -> dict[str, str]:
-    """Load the file-to-wiki-page mapping from mapping.json.
-
-    Validates that the mapping is a dict of string-to-string pairs.
-    """
+    """Load the file-to-wiki-page mapping from mapping.json."""
     with open(MAPPING_FILE, encoding="utf-8") as f:
         data = json.load(f)
     if not isinstance(data, dict):
@@ -69,191 +82,186 @@ def load_mapping() -> dict[str, str]:
     return data
 
 
-def read_doc_content(file_path: str) -> str:
-    """Read markdown content from a docs file."""
-    full_path = DOCS_DIR / file_path
-    with open(full_path, encoding="utf-8") as f:
-        return f.read()
+def transform_links(content: str) -> str:
+    """Transform markdown links from file-based to wiki-friendly format.
 
-
-def encode_content(content: str) -> str:
-    """Encode content as base64 for the Gitea wiki API.
-
-    The Gitea wiki API requires content_base64, not plain content.
-    Sending plain content silently fails (pages are created/updated
-    but with empty content).
+    - ``[text](file.md)`` → ``[text](file)``
+    - ``[text](docs/file.md)`` → ``[text](file)``
+    - ``[text](../file.md)`` → ``[text](file)``
+    - External links (http/https/mailto) preserved
+    - Anchor-only links (``#section``) preserved
     """
-    return base64.b64encode(content.encode("utf-8")).decode("ascii")
+
+    def replace_link(match: re.Match[str]) -> str:
+        text = match.group(1)
+        url = match.group(2).strip()
+        # Skip external links and mailto
+        if url.startswith(("http://", "https://", "mailto:")):
+            return match.group(0)
+        # Skip anchor-only links
+        if url.startswith("#"):
+            return match.group(0)
+        # Split path and anchor
+        if "#" in url:
+            path_part, anchor = url.split("#", 1)
+            anchor = f"#{anchor}"
+        else:
+            path_part, anchor = url, ""
+        # Remove .md extension and directory prefixes
+        if path_part.endswith(".md"):
+            path_part = path_part[:-3]
+        # Remove directory prefix (docs/, ../, etc.)
+        path_part = path_part.split("/")[-1]
+        return f"[{text}]({path_part}{anchor})"
+
+    return _LINK_RE.sub(replace_link, content)
 
 
-def decode_content(content_b64: str) -> str:
-    """Decode base64 content from the Gitea wiki API."""
-    if not content_b64:
-        return ""
-    return base64.b64decode(content_b64).decode("utf-8")
+def get_wiki_clone_url(owner: str, repo: str, token: str) -> str:
+    """Build the wiki Git clone URL with token auth."""
+    # Gitea wiki repos are at {clone_url}.wiki.git
+    # Extract base URL from API URL
+    base = GITEA_API_URL.rsplit("/api/v1", 1)[0]
+    # Embed token in URL for both clone and push auth
+    # Format: https://token@host/owner/repo.wiki.git
+    parsed = urlparse(base)
+    return f"{parsed.scheme}://{token}@{parsed.hostname}/{owner}/{repo}.wiki.git"
 
 
-def list_wiki_pages(client: GiteaClient) -> dict[str, str]:
-    """List existing wiki pages, returning {title: sub_url}.
+def clone_wiki(wiki_url: str, dest: Path) -> bool:
+    """Clone the wiki repo into dest. Returns True if clone succeeded.
 
-    Raises :class:`APIError` if the wiki API is unavailable — the caller
-    is responsible for retrying or handling the failure.
+    If the wiki repo doesn't exist yet (no pages created), returns False.
     """
-    pages = client._request("GET", "/wiki/pages").json()
-    return {page.get("title", ""): page.get("sub_url", page.get("title", "")) for page in pages}
-
-
-def fetch_page_content(client: GiteaClient, sub_url: str) -> str:
-    """Fetch a wiki page's content by sub_url, decoded from base64."""
-    try:
-        page = client._request("GET", f"/wiki/page/{sub_url}").json()
-        return decode_content(page.get("content_base64", ""))
-    except APIError:
-        return ""
-
-
-def sync_page(
-    client: GiteaClient,
-    page_title: str,
-    content: str,
-    existing_pages: dict[str, str],
-    dry_run: bool,
-) -> str:
-    """Create or update a single wiki page.
-
-    Returns "created", "updated", or "skipped" (if dry-run).
-    """
-    if dry_run:
-        click.echo(_("[dry-run] Would sync page: {title} ({chars} chars)", title=page_title, chars=len(content)))
-        return "skipped"
-
-    content_b64 = encode_content(content)
-
-    if page_title in existing_pages:
-        # Update existing page via PATCH
-        sub_url = existing_pages[page_title]
-        client._request(
-            "PATCH",
-            f"/wiki/page/{sub_url}",
-            json={
-                "title": page_title,
-                "content_base64": content_b64,
-                "message": f"Sync from docs/ — update {page_title}",
-            },
-        )
-        return "updated"
-
-    # Create new page via POST /wiki/new
-    client._request(
-        "POST",
-        "/wiki/new",
-        json={
-            "title": page_title,
-            "content_base64": content_b64,
-            "message": f"Sync from docs/ — create {page_title}",
-        },
+    result = subprocess.run(  # nosec
+        ["git", "clone", "--depth", "1", wiki_url, str(dest)],
+        capture_output=True,
+        text=True,
+        timeout=60,
     )
-    return "created"
+    return result.returncode == 0
 
 
-def verify_wiki_page(
-    client: GiteaClient, page_title: str, expected_content: str, existing_pages: dict[str, str]
-) -> bool:
-    """Verify that a wiki page has non-empty content matching the docs.
-
-    Returns True if the page content matches, False otherwise.
-    """
-    if page_title not in existing_pages:
-        return False
-    sub_url = existing_pages[page_title]
-    actual = fetch_page_content(client, sub_url)
-    return actual.strip() == expected_content.strip()
-
-
-def _list_wiki_pages_with_retry(client: GiteaClient) -> dict[str, str]:
-    """List wiki pages with tenacity retry on APIError.
-
-    The Gitea API can be briefly unavailable right after a batch of wiki
-    page updates.  Uses the same tenacity pattern as ``api_clients`` for
-    exponential backoff.
-    """
-    _logger = logging.getLogger("sync_wiki")
-
-    @retry(
-        stop=stop_after_attempt(3),
-        wait=wait_exponential(multiplier=2, min=2, max=8),
-        retry=retry_if_exception_type(APIError),
-        before_sleep=before_sleep_log(_logger, logging.WARNING),
-        reraise=True,
+def init_wiki(dest: Path) -> None:
+    """Initialize a fresh wiki repo (when clone fails)."""
+    dest.mkdir(parents=True, exist_ok=True)
+    subprocess.run(["git", "init"], cwd=dest, capture_output=True, check=True)  # nosec
+    subprocess.run(  # nosec
+        ["git", "config", "user.email", "ci@oblachno.fyi"],
+        cwd=dest,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(  # nosec
+        ["git", "config", "user.name", "CI Wiki Sync"],
+        cwd=dest,
+        capture_output=True,
+        check=True,
     )
-    def _do_list() -> dict[str, str]:
-        return list_wiki_pages(client)
-
-    return _do_list()
 
 
-def verify_wiki_integrity(
-    client: GiteaClient,
+def sync_files(
+    docs_dir: Path,
+    wiki_dir: Path,
     mapping: dict[str, str],
-    synced: dict[str, str],
-) -> list[str]:
-    """Comprehensive wiki verification.
+    dry_run: bool,
+) -> tuple[int, int]:
+    """Copy docs files to wiki dir with link transformation.
 
-    Checks:
-    1. Every mapped page exists in the wiki
-    2. Every mapped page has non-empty content
-    3. Every mapped page's content matches the docs
-    4. No stale pages exist in the wiki (pages not in mapping)
-    5. Page count matches
-
-    Returns a list of failure messages (empty if all checks pass).
-    If the wiki API is temporarily unavailable (all retry attempts
-    fail), returns an empty list with a warning — the sync itself
-    already succeeded, so a transient API outage should not fail the job.
+    Returns (synced, pruned) counts.
     """
-    failures: list[str] = []
+    synced = 0
 
-    try:
-        existing_pages = _list_wiki_pages_with_retry(client)
-    except APIError:
-        click.echo(
-            _(
-                "WARNING: Could not fetch wiki page list after retries. "
-                "The sync itself succeeded ({count} pages updated), but the "
-                "integrity check could not verify them due to a transient API issue.",
-                count=len(synced),
-            )
-        )
-        return []
+    # Build set of expected wiki filenames
+    expected_files: set[str] = set()
 
-    expected_titles = set(mapping.values())
+    for file_path, page_title in sorted(mapping.items()):
+        src = docs_dir / file_path
+        if not src.exists():
+            click.echo(_("  WARN: Mapped file {file} not found, skipping", file=file_path))
+            continue
 
-    # Check 1: Page count
-    if len(existing_pages) != len(expected_titles):
-        failures.append(f"Page count mismatch: wiki has {len(existing_pages)}, mapping has {len(expected_titles)}")
+        content = src.read_text(encoding="utf-8")
+        if not content.strip():
+            click.echo(_("  WARN: Mapped file {file} is empty, skipping", file=file_path))
+            continue
 
-    # Check 2: Missing pages (in mapping but not in wiki)
-    missing = expected_titles - set(existing_pages.keys())
-    for title in sorted(missing):
-        failures.append(f"Missing page: {title}")
+        # Transform links
+        transformed = transform_links(content)
 
-    # Check 3: Stale pages (in wiki but not in mapping)
-    stale = set(existing_pages.keys()) - expected_titles
-    for title in sorted(stale):
-        failures.append(f"Stale page (not in mapping): {title}")
+        # Wiki filename: Gitea uses a dash-marker convention for titles with dashes
+        fname = wiki_filename(page_title)
+        expected_files.add(fname)
 
-    # Check 4: Content verification
-    for page_title, expected_content in sorted(synced.items()):
-        ok = verify_wiki_page(client, page_title, expected_content, existing_pages)
-        if not ok:
-            sub_url = existing_pages.get(page_title, "?")
-            actual = fetch_page_content(client, sub_url)
-            if not actual.strip():
-                failures.append(f"Empty content: {page_title}")
-            else:
-                failures.append(f"Content mismatch: {page_title}")
+        if not dry_run:
+            dest = wiki_dir / fname
+            dest.write_text(transformed, encoding="utf-8")
+        synced += 1
+        click.echo(_("  Synced: {title} → {file}", title=page_title, file=fname))
 
-    return failures
+    # Prune stale pages (in wiki but not in mapping)
+    pruned = 0
+    if not dry_run:
+        for existing in wiki_dir.glob("*.md"):
+            if existing.name not in expected_files:
+                existing.unlink()
+                pruned += 1
+                click.echo(_("  Pruned: {file} (not in mapping)", file=existing.name))
+
+    return synced, pruned
+
+
+def commit_and_push(wiki_dir: Path, wiki_url: str, dry_run: bool) -> bool:
+    """Commit changes and push to the wiki repo. Returns True if pushed."""
+    if dry_run:
+        click.echo(_("[dry-run] Would commit and push wiki changes"))
+        return False
+
+    # Stage all changes
+    subprocess.run(["git", "add", "-A"], cwd=wiki_dir, capture_output=True, check=True)  # nosec
+
+    # Check if there are changes to commit
+    result = subprocess.run(  # nosec
+        ["git", "diff", "--cached", "--quiet"],
+        cwd=wiki_dir,
+        capture_output=True,
+    )
+    if result.returncode == 0:
+        click.echo(_("No changes to sync — wiki is up to date."))
+        return False
+
+    # Commit — ensure git identity is configured (CI environments may lack it)
+    subprocess.run(  # nosec
+        ["git", "config", "user.email", "devin-ai-integration[bot]@users.noreply.github.com"],
+        cwd=wiki_dir,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(  # nosec
+        ["git", "config", "user.name", "Devin CI"],
+        cwd=wiki_dir,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(  # nosec
+        ["git", "commit", "-m", "Sync wiki from docs/ [skip ci]"],
+        cwd=wiki_dir,
+        capture_output=True,
+        check=True,
+    )
+
+    # Push
+    result = subprocess.run(  # nosec
+        ["git", "push", "--force", wiki_url, "HEAD:master"],
+        cwd=wiki_dir,
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    if result.returncode != 0:
+        click.echo(_("Push failed: {error}", error=result.stderr))
+        return False
+    return True
 
 
 @click.command()
@@ -263,18 +271,14 @@ def verify_wiki_integrity(
     "--verify",
     is_flag=True,
     default=False,
-    help="After syncing, verify each page has non-empty content. Exit 1 if any page is empty or mismatched.",
+    help="After syncing, verify each page exists in the wiki. Exit 1 if any page is missing.",
 )
-@click.option(
-    "--strict",
-    is_flag=True,
-    default=False,
-    help="Full integrity check: verify page count, missing pages, stale pages, and content. Implies --verify.",
-)
-def main(dry_run: bool, repo: str | None, verify: bool, strict: bool) -> None:
-    token = os.environ.get("CI_GITEA_TOKEN", "")
-    if not token:
-        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set."))
+def main(dry_run: bool, repo: str | None, verify: bool) -> None:
+    """Sync documentation to the Gitea wiki via Git."""
+    try:
+        token = get_ci_token()
+    except click.ClickException:
+        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set.")) from None
 
     if repo is None:
         owner = os.environ.get("DEVX_REPO_OWNER", "") or REPO_OWNER
@@ -286,103 +290,66 @@ def main(dry_run: bool, repo: str | None, verify: bool, strict: bool) -> None:
         raise click.ClickException(_("ERROR: mapping.json not found at {path}", path=MAPPING_FILE))
 
     mapping = load_mapping()
-    client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
+    wiki_url = get_wiki_clone_url(owner, repo_name, token)
 
-    click.echo(_("Syncing {count} documentation pages to wiki...", count=len(mapping)))
+    click.echo(_("Syncing {count} documentation pages to wiki via Git...", count=len(mapping)))
 
-    try:
-        existing_pages = list_wiki_pages(client)
-    except APIError as e:
-        raise click.ClickException(
-            _("Failed to list existing wiki pages: {error}. Aborting to avoid creating duplicate pages.", error=e)
-        ) from e
-    if existing_pages:
-        click.echo(_("Found {count} existing wiki pages.", count=len(existing_pages)))
+    with tempfile.TemporaryDirectory() as tmpdir:
+        wiki_dir = Path(tmpdir) / "wiki"
 
-    created = 0
-    updated = 0
-    skipped = 0
-    synced: dict[str, str] = {}  # title -> content, for verification
-
-    for file_path, page_title in sorted(mapping.items()):
-        try:
-            content = read_doc_content(file_path)
-        except FileNotFoundError:
-            raise click.ClickException(
-                _("Mapped file {file} not found. Update mapping.json or create the file.", file=file_path)
-            ) from None
-
-        if not content.strip():
-            raise click.ClickException(
-                _("Mapped file {file} is empty. Update the content or remove from mapping.json.", file=file_path)
-            ) from None
-
-        result = sync_page(client, page_title, content, existing_pages, dry_run)
-        if result == "created":
-            created += 1
-            click.echo(_("  Created: {title}", title=page_title))
-        elif result == "updated":
-            updated += 1
-            click.echo(_("  Updated: {title}", title=page_title))
+        click.echo(_("Cloning wiki repo..."))
+        if clone_wiki(wiki_url, wiki_dir):
+            click.echo(_("Cloned existing wiki."))
         else:
-            skipped += 1
+            click.echo(_("Wiki repo not found or empty — initializing fresh."))
+            init_wiki(wiki_dir)
 
-        synced[page_title] = content
+        click.echo(_("Syncing files..."))
+        synced, pruned = sync_files(DOCS_DIR, wiki_dir, mapping, dry_run)
 
-    click.echo(
-        _(
-            "\nDone! Created: {created}, Updated: {updated}, Skipped: {skipped}",
-            created=created,
-            updated=updated,
-            skipped=skipped,
+        click.echo(
+            _(
+                "\nDone! Synced: {synced}, Pruned: {pruned}",
+                synced=synced,
+                pruned=pruned,
+            )
         )
-    )
 
-    # --strict implies --verify
-    do_verify = verify or strict
+        if dry_run:
+            click.echo(_("[dry-run] No changes pushed."))
+            return
 
-    if do_verify and not dry_run:
-        if strict:
-            click.echo(_("\nRunning full wiki integrity check..."))
-            failures = verify_wiki_integrity(client, mapping, synced)
-            if failures:
-                click.echo(_("\nIntegrity check FAILED ({count} issues):", count=len(failures)))
-                for f in failures:
-                    click.echo(f"  - {f}")
-                raise click.ClickException(_("Wiki integrity check failed — {count} issue(s)", count=len(failures)))
-            click.echo(_("\nIntegrity check passed — all {count} pages verified.", count=len(synced)))
-        else:
-            click.echo(_("\nVerifying wiki pages have content..."))
-            # Re-fetch the page list to get updated sub_urls
-            try:
-                existing_pages = _list_wiki_pages_with_retry(client)
-            except APIError:
-                click.echo(
-                    _(
-                        "WARNING: Could not re-fetch wiki page list for verification. "
-                        "Skipping content verification due to transient API issue."
-                    )
-                )
-                return
+        click.echo(_("Committing and pushing..."))
+        pushed = commit_and_push(wiki_dir, wiki_url, dry_run)
+        if pushed:
+            click.echo(_("Wiki synced successfully."))
+        elif not dry_run:
+            click.echo(_("No push needed (no changes or push failed)."))
+
+        # Verification
+        if verify and not dry_run:
+            if pushed:
+                click.echo(_("Waiting 5s for Gitea to process pushed commits..."))
+                time.sleep(5)
+            click.echo(_("\nVerifying wiki pages..."))
+            # Re-clone to verify
+            verify_dir = Path(tmpdir) / "verify"
+            if not clone_wiki(wiki_url, verify_dir):
+                click.echo(_("FAIL: Could not clone wiki for verification."))
+                raise click.ClickException(_("Wiki verification failed — could not clone wiki"))
             failures = 0
-            for page_title, expected_content in sorted(synced.items()):
-                ok = verify_wiki_page(client, page_title, expected_content, existing_pages)
-                if ok:
-                    click.echo(_("  OK: {title} ({chars} chars)", title=page_title, chars=len(expected_content)))
+            for _file_path, page_title in sorted(mapping.items()):
+                fname = wiki_filename(page_title)
+                if (verify_dir / fname).exists():
+                    click.echo(_("  OK: {title}", title=page_title))
                 else:
-                    click.echo(_("  FAIL: {title} — content mismatch or empty!", title=page_title))
+                    click.echo(_("  FAIL: {title} — page not found in wiki!", title=page_title))
                     failures += 1
             if failures > 0:
-                click.echo(
-                    _(
-                        "\nVerification FAILED: {failures} page(s) have empty or mismatched content!",
-                        failures=failures,
-                    )
-                )
                 raise click.ClickException(
-                    _("Wiki verification failed — {failures} page(s) empty or mismatched", failures=failures)
+                    _("Wiki verification failed — {failures} page(s) missing", failures=failures)
                 )
-            click.echo(_("\nVerification passed — all wiki pages have correct content."))
+            click.echo(_("\nVerification passed — all wiki pages exist."))
 
 
 if __name__ == "__main__":  # pragma: no cover

src/devx/ci/validate_deploy_ref.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Resolve and validate the git tag to deploy.
+
+Shared between staging and production deployments.  Ensures a concrete
+git tag is used — never a moving branch ref — so deployments are
+reproducible and rollback-friendly.
+
+Usage in workflows::
+
+    # Production (tag required)
+    python -m devx.ci.validate_deploy_ref --tag "$TAG" --github-output
+
+    # Staging force-deploy (tag required)
+    python -m devx.ci.validate_deploy_ref --tag "$TAG" --github-output
+
+    # Staging PR-triggered (PR SHA is already concrete, no tag needed)
+    python -m devx.ci.validate_deploy_ref --allow-empty --github-output
+
+Writes ``deploy-ref=<tag>`` to ``$GITHUB_OUTPUT`` when ``--github-output``
+is passed, otherwise prints the ref to stdout.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess  # nosec B404
+import sys
+
+import click
+
+from devx.i18n import _
+
+
+@click.command()
+@click.option("--tag", default="", help=_("Git tag to deploy (e.g. v0.28.1)."))
+@click.option(
+    "--allow-empty",
+    is_flag=True,
+    help=_("Allow empty tag (PR mode where SHA is concrete)."),
+)
+@click.option(
+    "--github-output",
+    is_flag=True,
+    help=_("Write deploy-ref to $GITHUB_OUTPUT file."),
+)
+def main(tag: str, allow_empty: bool, github_output: bool) -> None:
+    """Resolve and validate the deploy ref, exiting non-zero on failure."""
+    if not tag:
+        if not allow_empty:
+            click.echo(
+                "::error::No tag specified. Deployments require a concrete git tag "
+                "(e.g. v0.28.1). Use --allow-empty only for PR-triggered staging deploys "
+                "where the checkout SHA is already concrete.",
+                err=True,
+            )
+            sys.exit(1)
+        ref = ""
+        click.echo("No tag specified — using checkout ref (PR mode).")
+    else:
+        result = subprocess.run(  # nosec B603, B607
+            ["git", "rev-parse", "-q", "--verify", f"refs/tags/{tag}"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            click.echo(f"::error::Tag '{tag}' does not exist in the repository.", err=True)
+            sys.exit(1)
+        ref = tag
+        commit = result.stdout.strip()[:8]
+        click.echo(f"Deploying tag: {tag} (commit {commit})")
+
+    if github_output:
+        github_output_path = os.environ.get("GITHUB_OUTPUT")
+        if not github_output_path:
+            click.echo("::error::GITHUB_OUTPUT environment variable not set.", err=True)
+            sys.exit(1)
+        with open(github_output_path, "a") as f:
+            f.write(f"deploy-ref={ref}\n")
+    else:
+        click.echo(ref)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/gitea_cli.py

@@ -40,7 +40,6 @@ Usage::
 from __future__ import annotations
 
 import json
-import os
 import shutil
 import subprocess  # nosec B404
 from typing import Any
@@ -49,6 +48,7 @@ import click
 
 from devx.config import GITEA_API_URL
 from devx.i18n import _
+from devx.tokens import get_ci_token
 
 
 class TeaCLIError(Exception):
@@ -56,10 +56,10 @@ class TeaCLIError(Exception):
 
 
 def configure_tea_login(login_name: str = "devx") -> None:
-    """Configure tea CLI login from CI_GITEA_TOKEN and DEVX_GITEA_API_URL.
+    """Configure tea CLI login from CI_GITEA_API_TOKEN and DEVX_GITEA_API_URL.
 
     Idempotent: if a login with the same name already exists, it is not re-added.
-    Skips silently if tea is not installed or CI_GITEA_TOKEN is not set.
+    Skips silently if tea is not installed or no token is set.
 
     Used by CI scripts (publish, notify_failure) that need tea login but
     run in containerized environments where ``make setup`` was not called.
@@ -69,8 +69,9 @@ def configure_tea_login(login_name: str = "devx") -> None:
         click.echo(_("tea not installed — skipping login configuration."))
         return
 
-    token = os.environ.get("CI_GITEA_TOKEN", "")
-    if not token:
+    try:
+        token = get_ci_token()
+    except click.ClickException:
         click.echo(_("CI_GITEA_TOKEN not set — skipping login configuration."))
         return
 

src/devx/make/devx.mak

@@ -39,6 +39,9 @@
 #   DEVX_GITEA_PYPI_ORG  — Gitea PyPI org (default: oblachno-oss)
 #   DEVX_ACTIONLINT_CFG  — actionlint config file (default: .gitea/actionlint.yaml)
 #   DEVX_WORKFLOW_DIR    — workflow directory (default: .gitea/workflows)
+#   DEVX_DOC_COVERAGE_STRICT — fail on missing docs (default: 0)
+#   DEVX_DOC_VERSIONS_PKG    — package name for version ref checks (default: auto)
+#   DEVX_VALE_LEVEL          — vale alert threshold (default: warning)
 
 DEVX_PYTHON ?= python3
 DEVX_PR_BASE ?= master
@@ -52,21 +55,24 @@ DEVX_GITEA_PYPI_ORG ?= oblachno-oss
 DEVX_ACTIONLINT_CFG ?= .gitea/actionlint.yaml
 DEVX_WORKFLOW_DIR ?= .gitea/workflows
 DEVX_DOCKERFILE_PATHS ?= docker
+DEVX_VALE_LEVEL ?= warning
 
 # PIP_INSTALL — helper to run pip with Gitea private PyPI registry configured.
 # Usage: $(DEVX_PIP_INSTALL) install -e '.[ci,lint]'
 # CI_GITEA_USERNAME can be set in .env, as an env var, or as a Make variable.
 # Projects can alias: PIP_INSTALL = $(DEVX_PIP_INSTALL)
-DEVX_PIP_INSTALL := if [ -z "$$CI_GITEA_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
-	CI_GITEA_TOKEN="$$CI_GITEA_TOKEN"; \
+DEVX_PIP_INSTALL := if [ -z "$$CI_GITEA_API_TOKEN" ] && [ -z "$$DEVELOPER_GITEA_API_TOKEN" ] && [ -z "$$CI_GITEA_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
+	_TOKEN="$$CI_GITEA_API_TOKEN"; \
+	[ -z "$$_TOKEN" ] && _TOKEN="$$DEVELOPER_GITEA_API_TOKEN"; \
+	[ -z "$$_TOKEN" ] && _TOKEN="$$CI_GITEA_TOKEN"; \
 	_PYPI_USER="$${CI_GITEA_USERNAME:-emil}"; \
-	if [ -n "$$CI_GITEA_TOKEN" ] && [ -n "$$_PYPI_USER" ]; then export PIP_EXTRA_INDEX_URL="https://$$_PYPI_USER:$$CI_GITEA_TOKEN@$(DEVX_GITEA_PYPI_HOST)/api/packages/$(DEVX_GITEA_PYPI_ORG)/pypi/simple/"; fi; \
+	if [ -n "$$_TOKEN" ] && [ -n "$$_PYPI_USER" ]; then export PIP_EXTRA_INDEX_URL="https://$$_PYPI_USER:$$_TOKEN@$(DEVX_GITEA_PYPI_HOST)/api/packages/$(DEVX_GITEA_PYPI_ORG)/pypi/simple/"; fi; \
 	$(DEVX_BIN)/pip
 
 # ── Virtual environment management ────────────────────────────────────────────
 #
 # These targets provide a single, consistent venv setup across all
-# devx-integrated projects (infra, grm, devx). Each project includes
+# devx-integrated projects. Each project includes
 # devx.mak and aliases its local targets to these.
 #
 # The venv is a standard .venv directory (no pyenv virtualenv dependency).
@@ -109,7 +115,7 @@ devx-ensure-venv:
 .PHONY: devx-notify-failure devx-install-hooks devx-activate-scripts devx-venv devx-ensure-venv
 .PHONY: devx-lint-ruff devx-lint-format devx-typecheck devx-lint-bandit devx-lint-deps devx-lint
 .PHONY: devx-clean devx-pre-push
-.PHONY: devx-check-mutable-globals devx-check-dep-docs devx-check-test-coverage devx-check-docs devx-check-test-speed
+.PHONY: devx-check-mutable-globals devx-check-dep-docs devx-check-test-coverage devx-check-docs devx-check-test-speed devx-check-doc-versions devx-vale
 .PHONY: devx-check-api-identity-checks devx-setup-ssh-key
 .PHONY: devx-test-unit devx-pytest-cov
 .PHONY: devx-setup-image devx-lint-dockerfiles
@@ -192,12 +198,14 @@ devx-pr-rebase:
 # ── Environment setup ─────────────────────────────────────────────────────────
 
 # Configure Gitea private PyPI registry so pip can find devx and other
-# private packages. In CI, CI_GITEA_TOKEN is set as a secret. Locally, it's in .env.
+# private packages. In CI, CI_GITEA_API_TOKEN is set as a secret. Locally, DEVELOPER_GITEA_API_TOKEN or CI_GITEA_TOKEN can be used.
 devx-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)."
+	@if [ -z "$$CI_GITEA_API_TOKEN" ] && [ -z "$$DEVELOPER_GITEA_API_TOKEN" ] && [ -z "$$CI_GITEA_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
+	_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)."
 
 # Create .env from .env.example if it doesn't exist
 devx-env:
@@ -264,7 +272,7 @@ devx-workflow-check: devx-workflow-lint devx-workflow-dryrun
 
 # Notify on CI failure — creates a Gitea issue via devx.ci.notify_failure.
 # Usage: make devx-notify-failure WORKFLOW=post-merge/release
-# Requires: CI_GITEA_TOKEN, GITHUB_REPOSITORY, GITHUB_RUN_ID, GITHUB_SHA
+# Requires: CI_GITEA_API_TOKEN, GITHUB_REPOSITORY, GITHUB_RUN_ID, GITHUB_SHA
 devx-notify-failure:
 	@. $(DEVX_VENV)/bin/activate 2>/dev/null || true; \
 	export PATH="$(HOME)/.local/bin:$$PATH"; \
@@ -304,7 +312,7 @@ devx-test-unit:
 	@$(DEVX_BIN)/pytest $(DEVX_TEST_PATHS) -q --no-cov
 
 devx-pytest-cov:
-	@$(DEVX_BIN)/pytest $(DEVX_TEST_PATHS) -v --cov=$(DEVX_COV_PKG) --cov-report=term-missing --cov-fail-under=100
+	@$(DEVX_BIN)/pytest $(DEVX_TEST_PATHS) -n auto --cov=$(DEVX_COV_PKG) --cov-report=term-missing --cov-fail-under=100
 
 # ── Quality checks ────────────────────────────────────────────────────────────
 
@@ -324,6 +332,51 @@ devx-check-test-coverage:
 devx-check-docs:
 	@$(DEVX_PYTHON) -m devx.tools.check_agent_docs
 
+# Check documentation version references match current package version
+devx-check-doc-versions:
+	@$(DEVX_PYTHON) -m devx.tools.check_doc_versions --root .
+
+# Documentation coverage — checks that all modules/scripts/CLI commands
+# are documented. Fails if any are missing when DEVX_DOC_COVERAGE_STRICT=1.
+devx-doc-coverage:
+	@$(DEVX_PYTHON) -m devx.ci.doc_coverage $(if $(filter 1,$(DEVX_DOC_COVERAGE_STRICT)),--fail-on-missing)
+
+# All-in-one documentation gate: coverage + stale refs + structural lint +
+# version refs + prose lint. Use in CI and pre-commit as a single step
+# instead of 5+ separate steps.
+#
+# Configuration via environment variables (set in Makefile before include
+# or in CI env):
+#   DEVX_DOC_COVERAGE_STRICT=1  — fail on missing docs (recommended)
+#   DEVX_DOC_VERSIONS_PKG=<pkg> — enable version ref checks for a named package
+#   DEVX_VALE_LEVEL=<level>     — vale alert threshold (error, warning, suggestion)
+#                                  default: warning (catches weasel words, unlabeled
+#                                  code blocks, etc. — not just spelling errors)
+devx-docs-check: devx-doc-coverage devx-check-docs
+	@$(DEVX_PYTHON) -m devx.ci.lint_docs --root .
+	@if [ -n "$(DEVX_DOC_VERSIONS_PKG)" ]; then \
+		$(DEVX_PYTHON) -m devx.tools.check_doc_versions --root . --package $(DEVX_DOC_VERSIONS_PKG); \
+	elif $(DEVX_PYTHON) -c "import importlib.util,sys; sys.exit(0 if any(importlib.util.find_spec(p) for p in ['devx','grm','oblachno_infra']) else 1)" 2>/dev/null; then \
+		$(DEVX_PYTHON) -m devx.tools.check_doc_versions --root . 2>/dev/null || true; \
+	fi
+	@export PATH="$$HOME/.local/bin:$$PATH" && \
+		if ! command -v vale >/dev/null 2>&1; then \
+			echo "[devx-docs-check] vale not installed — skipping prose lint (install with 'make install-tools')"; \
+		else \
+			vale sync >/dev/null 2>&1 || true; \
+			vale --minAlertLevel=$(DEVX_VALE_LEVEL) docs/ AGENTS.md README.md; \
+		fi
+
+# Run Vale prose linter on docs and README (skips if vale not installed)
+# Legacy target — use devx-docs-check for the full documentation gate.
+devx-vale:
+	@export PATH="$$HOME/.local/bin:$$PATH" && \
+		if ! command -v vale >/dev/null 2>&1; then \
+			echo "[devx-vale] vale not installed — skipping (install with 'make install-tools')"; \
+		else \
+			vale --minAlertLevel=error docs/ AGENTS.md README.md; \
+		fi
+
 # Verify test suite timing
 devx-check-test-speed:
 	@$(DEVX_PYTHON) -m devx.tools.check_test_speed

src/devx/molecule/discover_runners.py

@@ -16,7 +16,7 @@ Outputs:
   - (default): prints both as ``count=N`` and ``indices=[0,1,...]``
 
 Usage:
-  python3 -m devx.molecule.discover_runners --owner oblachno-oss --repo grm
+  python3 -m devx.molecule.discover_runners --owner my-org --repo my-repo
   python3 -m devx.molecule.discover_runners --indices
   python3 -m devx.molecule.discover_runners --count
 """
@@ -30,6 +30,7 @@ import click
 import requests
 
 from devx.config import GITEA_API_URL, REPO_NAME, REPO_OWNER
+from devx.tokens import get_ci_token
 
 DEFAULT_MAX_RUNNERS = 3
 
@@ -86,7 +87,7 @@ def query_runners(api_url: str, token: str, owner: str, repo: str) -> int:
     return total
 
 
-def get_runner_count(api_url: str, token: str, owner: str, repo: str) -> int:
+def get_runner_count(api_url: str, token: str | None, owner: str, repo: str) -> int:
     """Determine the number of available runners.
 
     Tries the Gitea API first, then falls back to env vars, then default.
@@ -142,7 +143,10 @@ def main(
     output_indices: bool,
     github_output: bool,
 ) -> None:
-    token = os.environ.get("CI_GITEA_TOKEN", "")
+    try:
+        token = get_ci_token()
+    except click.ClickException:
+        token = None
 
     if owner is None:
         owner = os.environ.get("DEVX_REPO_OWNER", "") or REPO_OWNER

src/devx/molecule/distribute_molecule.py

@@ -137,7 +137,7 @@ def build_multi_role_pairs(
 # --- Molecule weight configuration ---
 #
 # Weights are loaded from ``[tool.devx.molecule.weights]`` in
-# ``pyproject.toml``.  Each project (infra, grm, …) contributes its own
+# ``pyproject.toml``.  Each project contributes its own
 # weights calibrated from actual CI execution times.
 #
 # Two key formats are supported:

src/devx/molecule/molecule_ci_guard.py

@@ -15,14 +15,14 @@ exits early with code 1.
 
 Usage::
 
-    # Single-role (grm-style)
+    # Single-role
     python3 -m devx.molecule.molecule_ci_guard pair1 pair2 ...
-    # Multi-role (infra-style)
+    # Multi-role
     python3 -m devx.molecule.molecule_ci_guard --roles-root ansible/roles pair1 pair2 ...
 
 Environment variables:
     GITEA_URL           Base URL of the Gitea instance.
-    CI_GITEA_TOKEN      API token with repo access.
+    CI_GITEA_API_TOKEN  API token with repo access (CI_GITEA_TOKEN accepted for legacy).
     RUN_ID              Workflow run ID (GITHUB_RUN_ID).
     JOB_NAME            Base job name (GITHUB_JOB), e.g. "molecule-tests".
     MATRIX_INDEX        Current matrix index (runner-index).
@@ -45,6 +45,7 @@ import requests
 
 from devx.config import REPO_NAME, REPO_OWNER
 from devx.i18n import _
+from devx.tokens import get_ci_token
 
 POLL_INTERVAL = 10
 
@@ -164,7 +165,10 @@ def resolve_role_dir(role: str, roles_root: Path | None, repo_root: Path) -> Pat
 def cli(pairs: tuple[str, ...], roles_root: Path | None) -> None:
     """Run molecule pairs sequentially, stop if another CI runner fails."""
     gitea_url = os.environ.get("GITEA_URL", "")
-    token = os.environ.get("CI_GITEA_TOKEN", "")
+    try:
+        token = get_ci_token()
+    except click.ClickException:
+        token = None
     run_id = int(os.environ.get("RUN_ID", "0"))
     job_name = os.environ.get("JOB_NAME", "molecule-tests")
     current_index = int(os.environ.get("MATRIX_INDEX", "0"))

src/devx/tokens.py

@@ -0,0 +1,76 @@
+"""Token resolution helpers for devx tools.
+
+Centralizes Gitea/Vikunja token discovery with role-based environment
+variable names and backwards compatibility with the legacy
+``CI_GITEA_TOKEN`` / ``REVIEW_GITEA_TOKEN`` naming convention.
+
+Roles:
+- ``CI_GITEA_API_TOKEN``: CI workflows (read actions, post status, merge, etc.)
+- ``REVIEWER_GITEA_API_TOKEN``: PR approval reviews (must be a different user
+  from the PR author for Gitea to accept the review as an approval)
+- ``DEVELOPER_GITEA_API_TOKEN``: local development tools (create-task,
+  create-pr, setup, etc.)
+
+Fallbacks:
+- New role names are checked first.
+- Legacy names (``CI_GITEA_TOKEN``, ``REVIEW_GITEA_TOKEN``) are accepted for
+  backwards compatibility.
+- If no role-specific token is set, the generic CI tokens are tried last.
+"""
+
+from __future__ import annotations
+
+import os
+
+import click
+
+from devx.i18n import _
+
+# Token environment variable names, in lookup priority order.
+CI_TOKEN_NAMES = ["CI_GITEA_API_TOKEN", "CI_GITEA_TOKEN"]
+REVIEWER_TOKEN_NAMES = [
+    "REVIEWER_GITEA_API_TOKEN",
+    # Legacy name used before role-based tokens.
+    "REVIEW_GITEA_TOKEN",
+    *CI_TOKEN_NAMES,
+]
+DEVELOPER_TOKEN_NAMES = ["DEVELOPER_GITEA_API_TOKEN", *CI_TOKEN_NAMES]
+
+VIKUNJA_TOKEN_NAMES = ["VIKUNJA_TOKEN"]
+
+
+def get_token(*names: str) -> str:
+    """Return the first non-empty value from the listed environment variables.
+
+    Raises a ``click.ClickException`` if none of the listed variables are set.
+    """
+    for name in names:
+        token = os.environ.get(name, "").strip()
+        if token:
+            return token
+    raise click.ClickException(
+        _(
+            "Gitea API token not set. Set one of: {names}",
+            names=", ".join(names),
+        )
+    )
+
+
+def get_ci_token() -> str:
+    """Resolve the CI Gitea API token."""
+    return get_token(*CI_TOKEN_NAMES)
+
+
+def get_reviewer_token() -> str:
+    """Resolve the reviewer Gitea API token used for PR approvals."""
+    return get_token(*REVIEWER_TOKEN_NAMES)
+
+
+def get_developer_token() -> str:
+    """Resolve the developer Gitea API token used for local tooling."""
+    return get_token(*DEVELOPER_TOKEN_NAMES)
+
+
+def get_vikunja_token() -> str:
+    """Resolve the Vikunja API token."""
+    return get_token(*VIKUNJA_TOKEN_NAMES)

src/devx/tools/_shared.py

@@ -8,6 +8,8 @@ import subprocess  # nosec B404
 
 import click
 
+from devx.tokens import get_developer_token
+
 
 def arch_string() -> str:
     """Return the architecture string used by release assets.
@@ -45,8 +47,9 @@ def detect_pr_number() -> int | None:
     if branch == "HEAD":
         return None
 
-    token = os.environ.get("CI_GITEA_TOKEN", "")
-    if not token:
+    try:
+        token = get_developer_token()
+    except click.ClickException:
         return None
 
     owner = os.environ.get("DEVX_REPO_OWNER", "")

src/devx/tools/build_image.py

@@ -34,8 +34,8 @@ The manifest file is a JSON list of dicts, each with:
     - ``context``: build context directory (optional, defaults to repo root)
     - ``tags``: list of tags (optional, defaults to ``["latest"]``)
 
-Registry authentication uses ``CI_GITEA_TOKEN`` and ``CI_GITEA_USERNAME``
-environment variables, matching the existing CI workflow patterns.
+Registry authentication uses ``CI_GITEA_API_TOKEN`` (or legacy ``CI_GITEA_TOKEN``)
+and ``CI_GITEA_USERNAME`` environment variables, matching the existing CI workflow patterns.
 """
 
 from __future__ import annotations
@@ -49,6 +49,7 @@ from pathlib import Path
 import click
 
 from devx.i18n import _
+from devx.tokens import get_developer_token
 
 
 @dataclass
@@ -221,9 +222,12 @@ def push_image(
 
 def _get_registry_creds() -> tuple[str, str]:
     """Get registry credentials from environment variables."""
-    token = os.environ.get("CI_GITEA_TOKEN", "")
+    try:
+        token = get_developer_token()
+    except click.ClickException:
+        token = None
     username = os.environ.get("CI_GITEA_USERNAME", "")
-    return username, token
+    return username, token or ""
 
 
 @click.command()