release: v0.36.0 [skip ci]

DEVX-119: feat: add GiteaClient repo variable methods and parallelize pytest-cov
DEVX-116: chore: update grm package name references
2026-07-07 11:58:00 +00:00 · 2026-07-07 11:57:04 +00:00 · 2026-07-06 15:51:10 +02:00 · 2026-07-06 13:22:27 +00:00 · 2026-07-06 15:21:22 +02:00 · 2026-07-06 13:00:59 +00:00
212 changed files with 26298 additions and 3372 deletions
@@ -0,0 +1,194 @@
+---
+name: ci-investigator
+description: Investigates CI failures in the devx repo by fetching job logs via Gitea MCP, identifying root cause across quality/release/publish/wiki-sync/image-build jobs, and validating fixes locally.
+model: glm-5.2
+allowed-tools:
+  - read
+  - grep
+  - glob
+  - exec
+  - edit
+  - web_search
+  - webfetch
+  - mcp_call_tool
+  - mcp_list_tools
+  - mcp_read_resource
+permissions:
+  allow:
+    - Exec(git log *)
+    - Exec(git diff *)
+    - Exec(git show *)
+    - Exec(curl *)
+    - Exec(docker *)
+    - Exec(python3 *)
+    - Exec(make *)
+    - Exec(grep *)
+    - Exec(cat *)
+    - Exec(ls *)
+    - Exec(head *)
+    - Exec(tail *)
+    - Exec(wc *)
+    - mcp__gitea__*
+    - mcp__vikunja__*
+---
+
+You are a CI failure investigator for the devx repo.
+
+## Working Directory & Virtual Environment
+
+The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## CI Job Dependency Graph
+
+devx has 3 workflows:
+
+**ci.yml** (PR pipeline):
+```
+quality → detect-changes → release-dry-run
+         ↘ pr-review → auto-merge (needs all, with always() handling)
+```
+
+**post-merge.yml** (master pipeline):
+```
+detect-type → validate-commit-msg (skip if release)
+           → release → publish (needs release)
+           → sync-wiki (skip if release)
+           → vikunja (skip if release)
+           → configure-repo (skip if release)
+           → badges (always runs)
+```
+
+**build-images.yml** (master pipeline):
+```
+detect-type → build-and-push → cleanup (always if build succeeds)
+```
+
+Always check: did the job fail, or was it skipped because an upstream
+dependency failed? Skipped jobs are not the root cause.
+
+## Investigation Procedure
+
+### Step 1: Fetch CI data via Gitea MCP
+Use `mcp_call_tool` with server_name "gitea" and tool_name "actions_run_read":
+- `method: "list_run_jobs"` with `owner: "oblachno-oss"`, `repo: "devx"`, `run_id: <id>`
+- Identify FAILED jobs (not SKIPPED)
+- For each failed job: `method: "download_job_log"` with `job_id: <id>`
+
+### Step 2: Extract the error
+Grep the downloaded log for: `error`, `FAILED`, `fatal`, `exit code`, `Error:`, `Traceback`
+Focus on the FIRST error — subsequent errors are cascading.
+
+### Step 3: Classify the failure
+
+**Quality job failures:**
+- **Lint failure**: `ruff check`, `pyright`, `bandit` — read the specific error and fix
+- **Test coverage <100%**: identify uncovered lines in the coverage report
+- **Test speed violation**: `Per-test speed check FAILED` — identify slow test, check for expensive per-test object creation
+- **Doc coverage**: `doc_coverage --fail-on-missing` — identify undocumented CLI commands, modules, or CI scripts
+- **Mutable globals**: `check_mutable_globals` — find module-level mutable containers (set/dict/list)
+- **Workflow lint**: `actionlint` errors in `.gitea/workflows/*.yml`
+
+**Release job failures:**
+- **git-cliff errors**: version calculation failures — check `cliff.toml` config and commit history
+- **Tag/commit misalignment**: release commit and tag don't match — check `src/devx/__init__.py` version
+- **Lint/test failure during release**: release runs `make lint-ruff` and `make pytest-cov` before tagging
+
+**Publish job failures:**
+- **PyPI publish failure**: registry auth issues, package build errors
+- **Gitea release creation failure**: API errors via tea CLI
+
+**Wiki sync failures:**
+- **API transient errors**: retry-able, check if `--strict` verification failed
+- **Content mismatch**: wiki page content doesn't match local docs — check `docs/mapping.json`
+- **Stale pages**: wiki has pages not in mapping.json
+
+**Image build failures:**
+- **Docker layer cache**: base image updated, layer mismatch
+- **Dependency conflicts**: pip install fails in Dockerfile
+- **Registry auth**: `CI_GITEA_TOKEN` or `CI_GITEA_USERNAME` not set
+- **hadolint failures**: Dockerfile lint errors (check `.hadolint.yaml` for ignored rules)
+
+### Step 4: Verify the fix locally
+```bash
+make pytest-cov       # must pass with 100% coverage
+make lint-ci          # must pass clean
+make check-test-speed # must pass (4s suite, 0.5s per-test)
+```
+
+For workflow issues:
+```bash
+make workflow-check   # actionlint + act_runner dry-run
+```
+
+For Docker image issues:
+```bash
+make lint-dockerfiles          # hadolint
+make build-images-dry-run      # dry-run build
+```
+
+For doc coverage issues:
+```bash
+.venv/bin/python -m devx.ci.doc_coverage --fail-on-missing
+.venv/bin/python -m devx.ci.lint_docs --root .
+```
+
+### Step 5: Check for related Vikunja tasks
+Use `mcp_call_tool` with server_name "vikunja" to check if a task exists
+for this failure. CI auto-creates Gitea issues via `notify_failure`.
+
+### Step 6: Report
+1. **Root cause**: The specific error and why it occurred
+2. **Evidence**: Log excerpts, local verification results
+3. **Affected files**: File paths and line numbers
+4. **Suggested fix**: Specific code change with rationale
+5. **Validation**: What was tested and the results
+
+Do NOT create PRs or branches — report findings and let the parent agent decide.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/devx` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "devx"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "devx"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,145 @@
+---
+name: dep-upgrader
+description: Researches and applies Python dependency upgrades in pyproject.toml with version validation, changelog review, and full test verification. Knows the dep documentation comment requirement.
+model: glm-5.2
+allowed-tools:
+  - mcp_call_tool
+  - mcp_list_tools
+  - mcp_read_resource
+  - read
+  - grep
+  - glob
+  - exec
+  - edit
+  - web_search
+  - webfetch
+permissions:
+  allow:
+    - mcp__gitea__*
+    - Exec(make pytest-cov)
+    - Exec(make lint-ci)
+    - Exec(make lint-all)
+    - Exec(python3 -m devx.tools.check_test_speed *)
+    - Exec(python3 -m devx.tools.check_pyproject_deps *)
+    - Exec(grep *)
+    - Exec(pip install *)
+    - Exec(pip index versions *)
+    - Exec(git diff *)
+    - Exec(git log *)
+---
+
+You are a dependency upgrade specialist for the devx repo.
+
+## Working Directory & Virtual Environment
+
+The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## Dependency Reference Locations
+
+- **Primary**: `pyproject.toml` — `[project] dependencies` and `[project.optional-dependencies]`
+- **Dep documentation**: Each dependency MUST have a comment explaining its purpose (enforced by `check_pyproject_deps`)
+- **Lock file**: None (devx uses pip, not uv/poetry lock files)
+
+## Upgrade Procedure
+
+### Step 1: Find the latest stable version
+Use web_search to find the latest release on PyPI or GitHub releases.
+
+Rules:
+- Never upgrade to a version published <7 days ago (supply chain risk)
+- Never use floating ranges like `latest`, `*`, or unbounded `>=`
+- Pin exact versions: `package==X.Y.Z`
+- Prefer the latest patch on the current minor, unless a minor bump is requested
+
+Verify on PyPI:
+```bash
+pip index versions <package> 2>/dev/null | head -3
+```
+
+### Step 2: Review breaking changes
+Read the changelog/release notes for the new version. Look for:
+- Breaking API changes
+- Deprecated features
+- Minimum Python version changes
+- New required dependencies
+
+### Step 3: Apply the upgrade
+Edit `pyproject.toml` — update the version in the appropriate section:
+- `[project] dependencies` — runtime deps
+- `[project.optional-dependencies] dev` — dev tools (ruff, pyright, bandit, etc.)
+- `[project.optional-dependencies] ci` — CI tools
+- `[project.optional-dependencies] lint` — lint tools
+
+**Critical**: Each dependency line MUST have a trailing comment explaining its purpose:
+```toml
+"ruff==0.12.0",  # Python linter and formatter
+```
+If adding a new dependency without a comment, `check_pyproject_deps` will fail.
+
+### Step 4: Install and verify
+```bash
+pip install -e .[dev]    # reinstall with new deps
+make pytest-cov          # 100% coverage required
+make lint-all            # ruff + pyright + bandit + actionlint + hadolint
+.venv/bin/python -m devx.tools.check_pyproject_deps  # verify dep docs
+.venv/bin/python -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
+```
+
+All must pass. If `check_pyproject_deps` fails, add the missing comment.
+
+### Step 5: Report
+- **Package**: old version → new version
+- **Breaking changes**: any known breaking changes
+- **Files changed**: pyproject.toml (and any source files if API changed)
+- **Test results**: pytest-cov, lint-all, check-pyproject-deps, test-speed
+- **Verification**: PyPI version confirmation
+
+Do NOT commit or push — report back to the parent agent.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/devx` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "devx"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "devx"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,165 @@
+---
+name: doc-sync-specialist
+description: Handles documentation coverage gaps, doc structure linting, and wiki sync failures. Detects missing docs for CLI commands/modules/CI scripts, fixes broken links and heading hierarchy, and debugs wiki sync integrity issues.
+model: glm-5.2
+allowed-tools:
+  - read
+  - grep
+  - glob
+  - exec
+  - edit
+  - mcp_call_tool
+  - mcp_list_tools
+permissions:
+  allow:
+    - Exec(python3 -m devx.ci.doc_coverage *)
+    - Exec(python3 -m devx.ci.lint_docs *)
+    - Exec(python3 -m devx.ci.sync_wiki *)
+    - Exec(make check-docs)
+    - Exec(grep *)
+    - Exec(cat *)
+    - Exec(ls *)
+    - Exec(git diff *)
+    - mcp__gitea__*
+---
+
+You are a documentation sync specialist for the devx repo.
+
+## Working Directory & Virtual Environment
+
+The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## Documentation Structure
+
+```
+docs/
+├── index.md              # Wiki homepage
+├── mapping.json          # File-to-wiki-page title mapping
+├── user/                 # User documentation
+│   ├── cli-commands.md
+│   ├── getting-started.md
+│   └── ...
+└── tech/                 # Technical documentation
+    ├── architecture.md
+    ├── ci-cd-workflow.md
+    └── ...
+```
+
+## Key Tools
+
+- `devx.ci.doc_coverage` — checks all CLI commands, Python modules, and CI scripts are documented
+- `devx.ci.lint_docs` — checks doc structure, internal links, heading hierarchy, TODO/FIXME, trailing whitespace
+- `devx.ci.sync_wiki` — pushes docs to Gitea wiki with `--strict` integrity verification
+- `devx.tools.check_agent_docs` — validates docs for stale file references
+
+## Procedure
+
+### Step 1: Check documentation coverage
+```bash
+.venv/bin/python -m devx.ci.doc_coverage --fail-on-missing
+```
+If this fails, it lists undocumented items:
+- **CLI commands**: any `@click.command()` or `@click.group()` without a docs entry
+- **Python modules**: any `src/devx/*.py` without architecture documentation
+- **CI scripts**: any `src/devx/ci/*.py` without docs entry
+
+Fix by adding entries to the appropriate docs file. Cross-reference with
+`docs/user/cli-commands.md` for CLI commands and `docs/tech/architecture.md`
+for modules.
+
+### Step 2: Lint documentation structure
+```bash
+.venv/bin/python -m devx.ci.lint_docs --root .
+```
+Common issues:
+- **Broken internal links**: `[text](page.md)` where `page.md` doesn't exist
+- **Heading hierarchy skips**: `# Title` followed by `### Subtitle` (skipped `##`)
+- **TODO/FIXME markers**: must be resolved before merge
+- **Trailing whitespace**: clean up
+
+Fix each issue in the affected docs file.
+
+### Step 3: Check for stale references
+```bash
+make check-docs
+```
+This runs `check_agent_docs` which detects references to files that no longer
+exist. If a script/module was renamed or deleted, update all doc references.
+
+### Step 4: Verify wiki sync (if investigating a sync failure)
+```bash
+.venv/bin/python -m devx.ci.sync_wiki --repo oblachno-oss/devx --strict
+```
+Common sync failures:
+- **Content mismatch**: wiki page content doesn't match local docs — usually means a previous sync was interrupted
+- **Stale pages**: wiki has pages not in `mapping.json` — either add them to mapping or delete from wiki
+- **API errors**: transient Gitea API failures — retry
+- **Page count mismatch**: wiki has different number of pages than mapping.json
+
+Check `docs/mapping.json` — every docs file should have a mapping entry:
+```json
+{
+  "user/cli-commands.md": "CLI-Commands",
+  "tech/architecture.md": "Architecture"
+}
+```
+
+If adding a new docs file, add it to `mapping.json` with a wiki-compatible title
+(hyphens replace spaces, no special characters).
+
+### Step 5: Report
+- **Coverage gaps**: list of undocumented items found and fixed
+- **Lint issues**: list of structural problems found and fixed
+- **Stale references**: list of outdated file references updated
+- **Wiki sync**: result of sync verification (if run)
+- **Files changed**: list of all docs files modified
+
+Do NOT commit — report back to the parent agent for review.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/devx` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "devx"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "devx"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,183 @@
+---
+name: docker-image-builder
+description: Handles Docker image build, push, and cleanup for the 3-tier runner images (ci-base, ci-quality, ci-full). Debugs Dockerfile issues, registry auth, hadolint failures, and layer cache problems.
+model: glm-5.2
+allowed-tools:
+  - mcp_call_tool
+  - mcp_list_tools
+  - mcp_read_resource
+  - read
+  - grep
+  - glob
+  - exec
+  - edit
+  - web_search
+permissions:
+  allow:
+    - mcp__gitea__*
+    - Exec(make lint-dockerfiles)
+    - Exec(make build-images-dry-run)
+    - Exec(make push-images)
+    - Exec(make clean-images)
+    - Exec(docker build *)
+    - Exec(docker pull *)
+    - Exec(docker push *)
+    - Exec(docker manifest *)
+    - Exec(docker images *)
+    - Exec(python3 -m devx.tools.build_image *)
+    - Exec(python3 -m devx.tools.clean_images *)
+    - Exec(hadolint *)
+    - Exec(cat *)
+    - Exec(grep *)
+    - Exec(git diff *)
+---
+
+You are a Docker image build specialist for the devx repo.
+
+## Working Directory & Virtual Environment
+
+The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## Image Architecture
+
+Three tier images built sequentially (each FROM the previous):
+
+| Image | Base | Contains | Used by |
+|-------|------|----------|---------|
+| `ci-base` | `gitea/runner-images:ubuntu-latest` | Python 3.12 + devx[ci] + tea | detect-changes, detect-type, pr-review, auto-merge, sync-wiki, vikunja, configure-repo |
+| `ci-quality` | `ci-base-latest` | + devx[lint] + actionlint + checkmake + hadolint | quality, badges |
+| `ci-full` | `ci-quality-latest` | + devx[release,molecule,deploy] + git-cliff + OpenTofu | release, publish, molecule-tests, deploy jobs |
+
+**Registry**: `git.oblachno.oblachno.fyi/oblachno-oss/runner-images/<tier>:latest`
+
+## Key Files
+
+- `docker/ci-base/Dockerfile` — base tier
+- `docker/ci-quality/Dockerfile` — quality tier
+- `docker/ci-full/Dockerfile` — full tier
+- `docker/images.json` — build manifest (image definitions, tags, push targets)
+- `.hadolint.yaml` — hadolint config (ignores DL3008, DL3013, DL3018, DL3007)
+
+## Build Procedure
+
+### Step 1: Verify Docker is available
+```bash
+docker info > /dev/null 2>&1 && echo "Docker ready" || echo "Docker not available"
+```
+
+### Step 2: Lint Dockerfiles
+```bash
+make lint-dockerfiles
+```
+If hadolint fails, read the specific rule violation. Check `.hadolint.yaml`
+for already-ignored rules before adding new ignores.
+
+### Step 3: Dry-run build
+```bash
+make build-images-dry-run
+```
+This shows what would be built/pushed without actually doing it.
+Verify the image names, tags, and registry paths are correct.
+
+### Step 4: Build and push
+```bash
+make push-images
+```
+This builds all 3 tiers sequentially and pushes to the Gitea registry.
+
+If only one tier needs rebuilding:
+```bash
+.venv/bin/python -m devx.tools.build_image \
+  --dockerfile docker/ci-quality/Dockerfile \
+  --name oblachno-oss/runner-images/ci-quality \
+  --tag latest \
+  --registry git.oblachno.oblachno.fyi \
+  --push
+```
+
+### Step 5: Clean up old versions
+```bash
+make clean-images
+```
+Keeps last 2 versions + latest. Uses Gitea API via `clean_images.py`.
+
+## Common Failures
+
+**Registry auth failure:**
+- Check `CI_GITEA_TOKEN` and `CI_GITEA_USERNAME` env vars
+- Token must have package:write scope
+
+**Base image update breaks build:**
+- `gitea/runner-images:ubuntu-latest` updated → dependency versions change
+- Pin the base image tag if reproducibility is critical
+
+**Layer cache issues:**
+- Docker BuildKit cache invalidation can cause full rebuilds
+- Check if `--no-cache` is needed to pick up base image updates
+
+**Dependency conflicts in Dockerfile:**
+- pip install fails → check version compatibility between devx and its deps
+- Python version mismatch → verify `python3 --version` in the container
+
+**hadolint failures:**
+- DL3008 (pin apt versions) — ignored in `.hadolint.yaml`
+- DL3013 (pin pip versions) — ignored (we use `==` in pyproject.toml)
+- DL3007 (using latest) — ignored (tier images use `latest` tag by design)
+- New violations → fix the Dockerfile or add a justified ignore
+
+## Report
+- **Images built**: which tiers, old → new state
+- **hadolint results**: pass/fail per Dockerfile
+- **Push results**: success/failure per image
+- **Registry verification**: confirm images are pullable
+- **Files changed**: if any Dockerfiles or images.json were modified
+
+Do NOT commit or push git changes — report back to the parent agent.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/devx` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "devx"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "devx"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,167 @@
+---
+name: workflow-validator
+description: Validates Gitea Actions workflow YAML files using actionlint and act_runner dry-run. Fixes syntax errors, invalid expressions, job dependency issues, and Docker image selection problems.
+model: glm-5.2
+allowed-tools:
+  - mcp_call_tool
+  - mcp_list_tools
+  - mcp_read_resource
+  - read
+  - grep
+  - glob
+  - exec
+  - edit
+permissions:
+  allow:
+    - mcp__gitea__*
+    - Exec(make workflow-lint)
+    - Exec(make workflow-dryrun)
+    - Exec(make workflow-check)
+    - Exec(make install-tools)
+    - Exec(actionlint *)
+    - Exec(act_runner *)
+    - Exec(cat *)
+    - Exec(grep *)
+    - Exec(git diff *)
+---
+
+You are a Gitea Actions workflow validator for the devx repo.
+
+## Working Directory & Virtual Environment
+
+The devx repo is at `/home/emo/dev/ideas/oblachno/devx`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## Key Files
+
+- `.gitea/workflows/ci.yml` — PR pipeline (quality, detect-changes, release-dry-run, pr-review, auto-merge)
+- `.gitea/workflows/post-merge.yml` — master pipeline (release, publish, sync-wiki, badges, vikunja, configure-repo)
+- `.gitea/workflows/build-images.yml` — Docker image build pipeline
+- `.gitea/actionlint.yaml` — actionlint config (registers custom `docker` runner label)
+
+## Validation Procedure
+
+### Step 1: Install tools (if not present)
+```bash
+make install-tools  # installs actionlint, act_runner to ~/.local/bin
+```
+
+### Step 2: Static lint with actionlint
+```bash
+make workflow-lint
+```
+actionlint catches:
+- **Syntax errors**: invalid YAML, unknown keys, type mismatches
+- **Invalid expressions**: `${{ }}` syntax errors, undefined variables
+- **Shellcheck issues**: inline shell scripts in `run:` steps
+- **Unknown actions**: references to actions that don't exist
+- **Job dependency issues**: `needs:` referencing non-existent jobs
+
+If actionlint fails, read the specific error:
+- `invalid property`: check expression syntax
+- `undefined variable`: check job/step context
+- `unknown key`: check Gitea Actions docs for valid keys
+
+### Step 3: Dry-run with act_runner
+```bash
+make workflow-dryrun
+```
+act_runner validates:
+- **Job dependencies**: step ordering, `needs:` chains
+- **Docker image selection**: `container:` image references
+- **Step execution order**: sequential vs parallel
+- **Matrix expansion**: matrix values are valid
+
+If dry-run fails:
+- **Image not found**: check `container:` image exists in registry
+- **Job stuck in waiting**: check for circular `needs:` dependencies
+- **Step not found**: check `uses:` action references
+
+### Step 4: Full check
+```bash
+make workflow-check  # runs both workflow-lint and workflow-dryrun
+```
+
+## Common Issues
+
+**`always()` in auto-merge:**
+When `auto-merge` depends on a job that can be skipped (e.g. `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 `result == 'skipped'`.
+
+```yaml
+auto-merge:
+  needs: [quality, detect-changes, pr-review, molecule-tests]
+  if: >-
+    always() &&
+    github.event_name == 'pull_request' &&
+    needs.quality.result == 'success' &&
+    (needs.molecule-tests.result == 'success' || needs.molecule-tests.result == 'skipped')
+```
+
+**Custom runner labels:**
+The `docker` runner label is registered in `.gitea/actionlint.yaml`.
+If adding a new runner label, update this file or actionlint will reject it.
+
+**Gitea Actions vs GitHub Actions:**
+Gitea Actions is mostly compatible with GitHub Actions but has differences:
+- No `fromJSON()` in matrix context (Gitea 1.26.x)
+- `concurrency` blocks can cause jobs to get stuck (Gitea 1.26.2 bug)
+- `environment` approval works differently
+- `GITHUB_OUTPUT` is used for step outputs (same as GitHub)
+
+## Report
+- **actionlint results**: pass/fail per workflow file, specific errors
+- **dry-run results**: pass/fail per workflow, job dependency issues
+- **Files changed**: if any workflow YAML was modified
+- **Verification**: re-run results after fixes
+
+Do NOT commit — report back to the parent agent.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/devx` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "devx"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "devx"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,37 @@
+# devx-workflow
+
+Quick reference for devx tools when working on the devx repo itself.
+
+## PR Workflow (use these, not raw git/tea/MCP)
+
+| Task | Command |
+|------|---------|
+| Create Vikunja task | `make create-task -- --title "..." --description "..."` |
+| Create PR | `make create-pr` |
+| Push + create PR | `make push-with-pr` |
+| Check CI status | `make devx-pr-status` or `make devx-pr-status PR=42 WAIT=1` |
+| Fetch CI failure logs | `make devx-pr-logs` or `make devx-pr-logs PR=42 JOB=quality TAIL=50` |
+| Add ready-to-merge label | `make devx-pr-label` or `make devx-pr-label PR=42` |
+| Post PR review | `make devx-pr-review PR=42 EVENT=APPROVE BODY="..." CHECKLIST=1,2,3,4,5,6,7,8,9,10,11,12,13` |
+| Rebase current branch | `make rebase` |
+| Rebase PR via API | `make pr-rebase` or `make pr-rebase PR=42` |
+
+## Auto-merge Behavior
+
+When the `ready-to-merge` label is added and all CI checks pass:
+1. Auto-merge validates PR title format (`DEVX-N: <vikunja task title>`)
+2. If branch is behind master, auto-merge **rebases via Gitea API** automatically
+3. The rebase triggers a new CI run; the next auto-merge attempt merges
+4. No manual rebase needed unless the API rebase fails
+
+## Key Rules
+
+- Never manually merge via API — always use auto-merge with `ready-to-merge` label
+- Branch naming: `DEVX-N-short-description` (N = Vikunja task ID)
+- Commit format: conventional commits (`feat:`, `fix:`, `docs:`, etc.)
+- PR title: `DEVX-N: <vikunja task title>` (auto-derived by `make create-pr`)
+- 100% test coverage required for all source changes
+- All user-facing strings wrapped in `_()` for i18n
+- Translation keys must be added to `src/devx/translations.json`
+- New CLI commands must be documented in `docs/user/cli-commands.md`
+- New tools must be registered in `src/devx/cli.py` and added to Make targets
@@ -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.
@@ -0,0 +1,20 @@
+.venv/
+.git/
+.gitea/
+tests/
+docs/
+*.egg-info/
+__pycache__/
+htmlcov/
+.coverage
+dist/
+build/
+*.md
+!README.md
+.env
+.env.example
+activate.sh
+activate.fish
+activate.zsh
+hooks/
+.devin/
@@ -1,6 +1,6 @@
 # Gitea API token (required for CI scripts that interact with Gitea)
 # Create at: https://git.oblachno.oblachno.fyi/user/settings/applications
-REPO_TOKEN=
+CI_GITEA_TOKEN=

 # Vikunja API token (required for post-merge task updates)
 # Create at: https://work.oblachno.oblachno.fyi/settings/tokens
@@ -0,0 +1,140 @@
+name: Build Images
+
+# Builds and pushes pre-built Docker runner images to the Gitea registry.
+# These images eliminate the 40-120s setup tax on every CI job by baking
+# devx and all dependencies into the image.
+#
+# Triggers:
+# - After post-merge workflow completes successfully (workflow_run)
+#   This ensures images are only rebuilt AFTER the release is published
+#   to PyPI, so the image always has the latest released version.
+# - Manually via workflow_dispatch
+#
+# The workflow builds 3 tier images in sequence:
+#   ci-base → ci-quality → ci-full
+#
+# Each tier builds FROM the previous one, so they must be built in order.
+# After pushing, a cleanup job removes old versions (keeps last 2 + latest).
+
+on:
+  workflow_run:
+    workflows: ["Post-merge"]
+    types: [completed]
+    branches: [master]
+  workflow_dispatch:
+
+concurrency:
+  group: build-images
+  cancel-in-progress: false
+
+jobs:
+  detect-type:
+    runs-on: docker
+    timeout-minutes: 5
+    outputs:
+      is-release: ${{ steps.check.outputs.is-release }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Set up environment
+        run: make setup-ci
+      - name: Check if this is a release commit
+        id: check
+        env:
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate
+          python3 -m devx.ci.detect_release_commit
+
+  build-and-push:
+    needs: [detect-type]
+    if: >-
+      needs.detect-type.outputs.is-release == 'false' && (
+        github.event_name == 'workflow_dispatch' ||
+        (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
+      )
+    runs-on: docker
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up environment
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+        run: make setup-release
+      - name: Docker registry login
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_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
+      - name: Build and push tier images
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate
+          export PATH="$HOME/.local/bin:$PATH"
+          # Build ci-base first (it's the base for ci-quality and ci-full)
+          python3 -m devx.tools.build_image \
+            --dockerfile docker/ci-base/Dockerfile \
+            --name oblachno-oss/runner-images/ci-base \
+            --tag latest \
+            --registry git.oblachno.oblachno.fyi \
+            --push --pull
+          # Build ci-quality (FROM ci-base-latest)
+          python3 -m devx.tools.build_image \
+            --dockerfile docker/ci-quality/Dockerfile \
+            --name oblachno-oss/runner-images/ci-quality \
+            --tag latest \
+            --registry git.oblachno.oblachno.fyi \
+            --push
+          # Build ci-full (FROM ci-quality-latest)
+          python3 -m devx.tools.build_image \
+            --dockerfile docker/ci-full/Dockerfile \
+            --name oblachno-oss/runner-images/ci-full \
+            --tag latest \
+            --registry git.oblachno.oblachno.fyi \
+            --push
+      - name: Notify on failure
+        if: failure()
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          export PATH="$HOME/.local/bin:$PATH"
+          python3 -m devx.ci.notify_failure \
+            --repo "${{ github.repository }}" \
+            --run-id "${{ github.run_id }}" \
+            --workflow "build-images/build-and-push" \
+            --commit "${{ github.sha }}" \
+            --auto-login
+
+  cleanup:
+    needs: [build-and-push]
+    if: always() && needs.build-and-push.result == 'success'
+    runs-on: docker
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Set up environment
+        run: make setup-ci
+      - name: Clean up old image versions
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate
+          python3 -m devx.tools.clean_images \
+            --owner oblachno-oss \
+            --name oblachno-oss/runner-images/ci-base \
+            --name oblachno-oss/runner-images/ci-quality \
+            --name oblachno-oss/runner-images/ci-full \
+            --keep 2
@@ -8,48 +8,70 @@ on:
 jobs:
  quality:
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest
    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
    steps:
      - uses: actions/checkout@v4
      - name: Set up environment
-        run: make setup-quality
+        run: make setup-image
      - name: Lint all
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
          make lint-all
      - name: Unit tests with 100% coverage
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          make pytest-cov
      - name: Check unit test speed
        env:
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
-          python3 -m devx.tools.check_test_speed --max-seconds 60 --max-single-seconds 2.0
+          . .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
        env:
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .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 .
+      - name: Documentation version reference check
+        env:
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.tools.check_doc_versions --root .
+      - name: Vale prose lint check
+        env:
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          make devx-vale
      - name: Translation completeness check
        env:
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.check_translations
      - name: Dependency security scan
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          # Install pip in venv if missing (needed by pip-audit)
          .venv/bin/python -m ensurepip 2>/dev/null || true
          PIPAPI_PYTHON_LOCATION=$PWD/.venv/bin/python \
            pip-audit --desc --skip-editable 2>&1 || true
      - name: Workflow dry-run validation
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
          # Best-effort: only runs if act_runner is installed
          if command -v act_runner >/dev/null 2>&1; then
@@ -60,7 +82,11 @@ jobs:

  detect-changes:
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
    outputs:
      user-facing-changed: ${{ steps.detect.outputs.user-facing-changed }}
    steps:
@@ -68,13 +94,13 @@ jobs:
        with:
          fetch-depth: 0
      - name: Set up environment
-        run: make setup-ci
+        run: make setup-image
      - name: Detect changed paths
        id: detect
        env:
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.classify_changes \
            --base "origin/master" \
            --head "${{ github.event.pull_request.head.sha || github.sha }}" \
@@ -84,60 +110,92 @@ jobs:
    needs: [quality, detect-changes]
    if: needs.detect-changes.outputs.user-facing-changed == 'true'
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Set up environment
-        run: make setup-release
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+        run: make setup-image
      - name: Release dry-run validation
        env:
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.release --dry-run || true
+          python3 -m devx.ci.release --dry-run

  pr-review:
    if: github.event_name == 'pull_request'
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
    steps:
      - uses: actions/checkout@v4
      - name: Set up environment
-        run: make setup-ci
+        run: make setup-image
      - name: Run automated PR review
        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
        run: |
          set -euo pipefail
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.pr_review \
            "${{ github.event.number }}" \
            "${{ github.repository }}"

  auto-merge:
    # Auto-merge runs after all CI checks pass. It reads the task ID
-    # from .taskid file, validates the PR title, and squash-merges.
-    # No manual label or review needed — CI is the quality gate.
-    needs: [quality, detect-changes, pr-review]
-    if: github.event_name == 'pull_request'
+    # from the branch name, validates the PR title, and squash-merges.
+    # Uses always() so it runs even when detect-changes skips (no user-facing changes).
+    needs: [quality, detect-changes, pr-review, release-dry-run]
+    if: >-
+      always() &&
+      github.event_name == 'pull_request' &&
+      needs.quality.result == 'success' &&
+      needs.pr-review.result == 'success' &&
+      (needs.release-dry-run.result == 'success' || needs.release-dry-run.result == 'skipped')
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
-          token: ${{ secrets.REPO_TOKEN }}
-      - name: Install dependencies
+          token: ${{ secrets.CI_GITEA_TOKEN }}
+      - name: Set up environment
+        run: make setup-image
+      - name: Post approval review
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          PR_NUMBER: ${{ github.event.number }}
+          REPOSITORY: ${{ github.repository }}
+          PYTHONPATH: src
        run: |
-          python3 -m pip install --break-system-packages requests python-dotenv click
-          python3 -m pip install --break-system-packages -e .
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.ci.pr_review \
+            "$PR_NUMBER" \
+            "$REPOSITORY" \
+            --event APPROVE \
+            --checklist-confirmed \
+            --checklist-categories 1,2,3,4,5,6,7,8,9,10,11,12,13 \
+            --body "Auto-approved: all CI checks passed (quality, pr-review, release-dry-run)."
      - name: Squash merge with task ID
        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
          DEVX_VIKUNJA_PROJECT_ID: "8"
          PYTHONPATH: src
@@ -146,6 +204,7 @@ jobs:
          REPOSITORY: ${{ github.repository }}
          PR_NUMBER: ${{ github.event.number }}
        run: |
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.auto_merge \
            "$HEAD_REF" \
            "$PR_TITLE" \
@@ -1,30 +1,32 @@
 name: Post-merge

 # Runs on every push to master. A single workflow with conditional jobs
-# replaces separate workflows for release, wiki sync, badges, and
-# Vikunja task updates.
+# for release, publish, wiki sync, badges, and Vikunja task updates.
 #
 # Job dependency graph:
 #
-#   detect-type ──┬── release (skip if release commit)
-#                 ├── badges (ALWAYS runs — even on release commits)
+#   detect-type ──┬── validate-commit-msg (skip if release commit)
+#                 ├── release (skip if release commit)
+#                 │   └── publish (needs release — builds & publishes to PyPI)
+#                 ├── badges (needs release — ALWAYS runs, waits for release
+#                 │           so version badge picks up new __version__)
 #                 ├── configure-repo (independent — skip if release commit)
-#                 ├── sync-wiki (needs release — skip if release commit/fails)
-#                 └── vikunja (needs release — skip if release commit/fails)
+#                 ├── sync-wiki (skip if release commit — runs for ALL merges)
+#                 └── vikunja (skip if release commit — runs for ALL merges)
 #
-# sync-wiki and vikunja depend on release succeeding so that the wiki
-# and task tracker are only updated when the code is actually released.
-# If release fails, they are skipped to avoid leaving the wiki or
-# Vikunja in an inconsistent state with the codebase on master.
+# sync-wiki and vikunja run for ALL non-release commits, not just when
+# release succeeds. This ensures the wiki and task tracker are updated
+# even for infrastructure-only changes (docs, CI config, etc.).
 #
-# The badges job depends on release so it picks up the latest version
-# number. It 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, the release
-# commit's post-merge run still updates badges (version badge picks
-# up the new version). Other jobs skip. The tag push triggers publish.yml.
+# When release creates a "release: vX.Y.Z" commit and tag, the publish
+# job (which depends on release) builds and publishes the package to the
+# Gitea PyPI registry. The release commit's post-merge run still updates
+# badges (version badge picks up the new version). Other jobs skip.

 on:
  push:
@@ -33,40 +35,47 @@ on:
 jobs:
  detect-type:
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
    outputs:
      is-release: ${{ steps.check.outputs.is-release }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1
-      - name: Install dependencies
-        run: |
-          python3 -m pip install --break-system-packages requests python-dotenv click
-          python3 -m pip install --break-system-packages -e .
+      - name: Set up environment
+        run: make setup-image
      - name: Check if this is a release commit
        id: check
        env:
          PYTHONPATH: src
-        run: python3 -m devx.ci.detect_release_commit
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.ci.detect_release_commit

  validate-commit-msg:
    needs: [detect-type]
    if: needs.detect-type.outputs.is-release == 'false'
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
    timeout-minutes: 5
+    defaults:
+      run:
+        shell: bash
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1
-      - name: Install dependencies
-        run: |
-          python3 -m pip install --break-system-packages click python-dotenv
-          python3 -m pip install --break-system-packages -e .
+      - name: Set up environment
+        run: make setup-image
      - name: Validate latest commit message
        env:
          PYTHONPATH: src
        run: |
+          . .venv/bin/activate 2>/dev/null || true
          git log -1 --format=%B > commit-msg.txt
          python3 -m devx.ci.validate_commit_msg commit-msg.txt --branch master
          rm -f commit-msg.txt
@@ -75,63 +84,117 @@ jobs:
    needs: [detect-type]
    if: needs.detect-type.outputs.is-release == 'false'
    runs-on: docker
-    timeout-minutes: 10
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        shell: bash
+    outputs:
+      tag: ${{ steps.release-tag.outputs.tag }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
-          token: ${{ secrets.REPO_TOKEN }}
+          token: ${{ secrets.CI_GITEA_TOKEN }}
      - name: Set up environment
-        run: make setup-release
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+        run: make setup-image
      - name: Configure git
        run: |
          git config user.name "devx-ci-bot"
          git config user.email "devx-ci-bot@oblachno.fyi"
      - name: Run release
+        id: release-tag
        env:
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
          python3 -m devx.ci.release
      - name: Notify on failure
        if: failure()
        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
        run: |
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.tools.install_tools --tool tea
-          tea login add --name devx --url "${{ github.server_url }}" --token "$REPO_TOKEN" || true
-          tea login default devx || true
          python3 -m devx.ci.notify_failure \
            --repo "${{ github.repository }}" \
            --run-id "${{ github.run_id }}" \
            --workflow "post-merge/release" \
-            --commit "${{ github.sha }}"
+            --commit "${{ github.sha }}" \
+            --auto-login
+
+  publish:
+    needs: [release]
+    if: needs.release.outputs.tag != ''
+    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.release.outputs.tag }}
+      - name: Set up environment
+        run: make setup-image EXTRAS=release
+      - name: Build and publish release
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          export PATH="$HOME/.local/bin:$PATH"
+          python3 -m devx.ci.publish "${{ needs.release.outputs.tag }}" "${{ github.repository }}" --auto-login
+      - name: Notify on failure
+        if: failure()
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          export PATH="$HOME/.local/bin:$PATH"
+          python3 -m devx.ci.notify_failure \
+            --repo "${{ github.repository }}" \
+            --run-id "${{ github.run_id }}" \
+            --workflow "post-merge/publish" \
+            --commit "${{ github.sha }}" \
+            --auto-login

  sync-wiki:
-    needs: [detect-type, release]
+    needs: [detect-type]
    if: needs.detect-type.outputs.is-release == 'false'
    runs-on: docker
-    timeout-minutes: 10
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
+    timeout-minutes: 15
+    concurrency:
+      group: sync-wiki-${{ github.repository }}
+      cancel-in-progress: false
+    defaults:
+      run:
+        shell: bash
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Set up environment
-        run: make setup-ci
+        run: make setup-image
      - name: Sync documentation to wiki
        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
-          python3 -m devx.ci.sync_wiki --repo "${{ github.repository }}" --strict
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.ci.sync_wiki --repo "${{ github.repository }}" --verify
      - name: Notify on failure
        if: failure()
        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
        run: |
          export PATH="$HOME/.local/bin:$PATH"
@@ -139,35 +202,40 @@ jobs:
            --repo "${{ github.repository }}" \
            --run-id "${{ github.run_id }}" \
            --workflow "post-merge/sync-wiki" \
-            --commit "${{ github.sha }}"
+            --commit "${{ github.sha }}" \
+            --auto-login

  badges:
    needs: [detect-type, release]
    if: always()
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest
    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: master
-          token: ${{ secrets.REPO_TOKEN }}
+          token: ${{ secrets.CI_GITEA_TOKEN }}
      - name: Fetch latest master
        run: |
          git fetch origin master
          git reset --hard origin/master
      - name: Set up environment
-        run: make setup-ci
+        run: make setup-image
      - name: Generate and push badges
        env:
          PRE_COMMIT_ALLOW_NO_CONFIG: "1"
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.push_badges
      - name: Notify on failure
        if: failure()
        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
        run: |
          export PATH="$HOME/.local/bin:$PATH"
@@ -175,71 +243,78 @@ jobs:
            --repo "${{ github.repository }}" \
            --run-id "${{ github.run_id }}" \
            --workflow "post-merge/badges" \
-            --commit "${{ github.sha }}"
+            --commit "${{ github.sha }}" \
+            --auto-login

  vikunja:
-    needs: [detect-type, release]
+    needs: [detect-type]
    if: needs.detect-type.outputs.is-release == 'false'
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
-      - name: Install dependencies
-        run: |
-          python3 -m pip install --break-system-packages requests python-dotenv click
-          python3 -m pip install --break-system-packages -e .
+      - name: Set up environment
+        run: make setup-image
      - name: Update Vikunja task
        env:
          VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
          DEVX_VIKUNJA_PROJECT_ID: "8"
          PYTHONPATH: src
-        run: python3 -m devx.ci.post_merge --git-sha "${{ github.sha }}"
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.ci.post_merge --git-sha "${{ github.sha }}"
      - name: Notify on failure
        if: failure()
        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
        run: |
          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.tools.install_tools --tool tea
-          tea login add --name devx --url "${{ github.server_url }}" --token "$REPO_TOKEN" || true
-          tea login default devx || true
          python3 -m devx.ci.notify_failure \
            --repo "${{ github.repository }}" \
            --run-id "${{ github.run_id }}" \
            --workflow "post-merge/vikunja" \
-            --commit "${{ github.sha }}"
+            --commit "${{ github.sha }}" \
+            --auto-login

  configure-repo:
    needs: [detect-type]
    if: needs.detect-type.outputs.is-release == 'false'
    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
    steps:
      - uses: actions/checkout@v4
-      - name: Install dependencies
-        run: |
-          python3 -m pip install --break-system-packages requests python-dotenv click
-          python3 -m pip install --break-system-packages -e .
+      - name: Set up environment
+        run: make setup-image
      - name: Ensure branch protection and labels
        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
-        run: python3 -m devx.tools.configure_repo --repo devx --owner oblachno-oss
+          DEVX_REPO_NAME: devx
+          DEVX_REPO_OWNER: oblachno-oss
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.tools.configure_repo
      - name: Notify on failure
        if: failure()
        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
        run: |
          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.tools.install_tools --tool tea
-          tea login add --name devx --url "${{ github.server_url }}" --token "$REPO_TOKEN" || true
-          tea login default devx || true
          python3 -m devx.ci.notify_failure \
            --repo "${{ github.repository }}" \
            --run-id "${{ github.run_id }}" \
            --workflow "post-merge/configure-repo" \
-            --commit "${{ github.sha }}"
+            --commit "${{ github.sha }}" \
+            --auto-login
@@ -1,49 +0,0 @@
-name: Publish Release
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  publish:
-    runs-on: docker
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Install dependencies
-        run: |
-          python3 -m pip install --break-system-packages build twine requests python-dotenv click
-          python3 -m pip install --break-system-packages -e .
-      - name: Install CI tools
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.tools.install_tools --tool git-cliff --tool tea
-      - name: Configure tea login
-        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          tea login add --name devx --url "${{ github.server_url }}" --token "$REPO_TOKEN" || true
-          tea login default devx || true
-      - name: Build and publish release
-        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.publish "${{ github.ref_name }}" "${{ github.repository }}"
-      - name: Notify on failure
-        if: failure()
-        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.notify_failure \
-            --repo "${{ github.repository }}" \
-            --run-id "${{ github.run_id }}" \
-            --workflow "publish" \
-            --commit "${{ github.sha }}"
@@ -35,3 +35,6 @@ Thumbs.db

 # Badges
 .badges/
+
+# Deprecated CI task tracking (branch name is the sole source of truth)
+.taskid
@@ -0,0 +1,14 @@
+# Hadolint configuration for devx Dockerfiles
+# https://github.com/hadolint/hadolint#configure
+
+ignored:
+  - DL3008  # Don't require pinning apt package versions
+  - DL3013  # Don't require pinning pip package versions
+  - DL3018  # Don't require pinning apk package versions
+  - DL3007  # Using latest is intentional for tier images (rebuilt on every merge)
+  - SC2102  # False positive: pip extras [release,molecule,deploy] look like shell ranges
+
+trustedRegistries:
+  - git.oblachno.oblachno.fyi
+  - docker.io
+  - gitea/runner-images
@@ -49,6 +49,44 @@ repos:
        pass_filenames: false
        stages: [pre-commit]

+      - id: checkmake
+        name: checkmake Makefile linter
+        entry: make checkmake
+        language: system
+        files: (Makefile|\.mak)$
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: check-test-speed
+        name: unit test speed check
+        entry: .venv/bin/python -m devx.tools.check_test_speed --max-seconds 6 --max-single-seconds 0.5
+        language: system
+        types: [python]
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: check-translations
+        name: translation completeness check
+        entry: env PYTHONPATH=src .venv/bin/python -m devx.ci.check_translations
+        language: system
+        files: ^src/devx/translations\.json$
+        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 .
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
      - id: pytest-cov
        name: pytest with 100% coverage
        entry: make pytest-cov
@@ -1 +0,0 @@
-DEVX-15
@@ -0,0 +1,46 @@
+# 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
+
+# Vale defaults — spelling catches too many technical terms
+Vale.Terms = NO
+Vale.Repetition = NO
+Vale.Spelling = NO
+
+# Readability — warnings only, technical docs are naturally complex
+Readability.FleschReadingEase = suggestion
+Readability.ColemanLiau = suggestion
+Readability.LIX = suggestion
+Readability.GunningFog = suggestion
+Readability.SMOG = suggestion
@@ -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]\.'
@@ -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
@@ -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]'
@@ -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
@@ -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}'
@@ -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:
+  - '\.\.\.'
@@ -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'
+
@@ -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|$)'
@@ -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
@@ -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
@@ -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)
@@ -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*$'
@@ -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
@@ -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
@@ -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'
@@ -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\)'
@@ -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)
@@ -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)'
@@ -0,0 +1,7 @@
+extends: existence
+message: "Use parentheses judiciously."
+link: 'https://developers.google.com/style/parentheses'
+nonword: true
+level: suggestion
+tokens:
+  - '\(.+\)'
@@ -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
@@ -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,}'
@@ -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:
+  - '"[^"]+"[.,?]'
@@ -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+'
@@ -0,0 +1,8 @@
+extends: existence
+message: "Use semicolons judiciously."
+link: 'https://developers.google.com/style/semicolons'
+nonword: true
+scope: sentence
+level: suggestion
+tokens:
+  - ';'
@@ -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
@@ -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]'
@@ -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'
@@ -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)
@@ -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
@@ -0,0 +1,7 @@
+extends: existence
+message: "Avoid using '%s'."
+link: 'https://developers.google.com/style/tense'
+ignorecase: true
+level: warning
+tokens:
+  - will
@@ -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
@@ -0,0 +1,4 @@
+{
+  "feed": "https://github.com/errata-ai/Google/releases.atom",
+  "vale_version": ">=1.0.0"
+}
@@ -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"
@@ -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"
@@ -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"
@@ -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"
@@ -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"
@@ -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"
@@ -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"
@@ -0,0 +1,4 @@
+{
+  "feed": "https://github.com/errata-ai/Readability/releases.atom",
+  "vale_version": ">=2.13.0"
+}
@@ -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
@@ -0,0 +1,6 @@
+extends: existence
+message: "Unlabeled code block — add a language tag (```bash, ```yaml, etc.)"
+level: warning
+scope: raw
+raw:
+  - '(?s)```\n(?!.*```)'
@@ -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'
@@ -0,0 +1,3 @@
+# Custom Vale style for devx documentation
+
+Project-specific terminology and style rules
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,11 @@
+extends: repetition
+message: "'%s' is repeated!"
+level: warning
+alpha: true
+action:
+  name: edit
+  params:
+    - truncate
+    - " "
+tokens:
+  - '[^\s]+'
@@ -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
@@ -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.
+
+```text
+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.
+```
@@ -0,0 +1,5 @@
+extends: existence
+message: "Don't start a sentence with '%s'."
+level: error
+raw:
+  - '(?:[;-]\s)so[\s,]|\bSo[\s,]'
@@ -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'
@@ -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
@@ -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
@@ -0,0 +1,4 @@
+{
+  "feed": "https://github.com/errata-ai/write-good/releases.atom",
+  "vale_version": ">=1.0.0"
+}
@@ -1,23 +1,39 @@
 # AGENTS.md — Project Conventions for devx

+## Virtual Environment
+
+All Python tools, tests, and scripts run inside a standard `.venv` directory.
+Activate it before running any non-`make` command:
+
+```bash
+source activate.sh       # bash/zsh
+source activate.fish     # fish
+source activate.zsh      # zsh
+```
+
+If `.venv` doesn't exist, run `make setup` first. The `make` targets handle
+venv activation automatically — always prefer `make <target>` over raw commands.
+
 ## Build & Test Commands

 ```bash
 make setup           # Create venv, install deps, set up hooks, install CI tools
-make install-tools   # Install actionlint, git-cliff, act_runner to ~/.local/bin
-make lint-all        # ruff + pyright + bandit + actionlint
+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** 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` `REPO_TOKEN`)
+- **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)

@@ -43,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)
@@ -52,37 +68,57 @@ src/devx/
 ├── gitea_cli.py         # TeaCLI — wrapper around tea CLI with JSON parsing
 ├── i18n.py              # Translation system (gettext-based, translations.json)
 ├── exceptions.py        # Custom exception types
-├── translations.json    # Translation strings (en, bg)
+├── translations.json    # Translation strings (en, bg, de, pl, ru, zh)
 ├── ci/                  # CI/CD automation modules (run by workflows)
 │   ├── release.py       # Automated versioning, tagging, changelog
 │   ├── publish.py       # Build and publish to Gitea PyPI registry (--skip-build for non-Python repos)
 │   ├── auto_merge.py    # Squash-merge PRs with task ID validation
+│   ├── check_auto_merge_ready.py  # Pre-merge validation gate (branch, PR title, Vikunja, behind-master)
 │   ├── _shared.py      # Shared utilities (get_latest_tag)
-│   ├── classify_changes.py  # User-facing vs workflow-only change detection
+│   ├── classify_changes.py  # User-facing vs infrastructure change detection
 │   ├── detect_release_commit.py  # Detect release commits on master
 │   ├── validate_commit_msg.py    # Conventional commit validation
-│   ├── pr_review.py     # Automated PR review
+│   ├── pr_review.py     # Automated PR review + manual reviews (--event, --body, --checklist-confirmed)
 │   ├── post_merge.py    # Vikunja task updates after merge
 │   ├── sync_wiki.py     # Sync documentation to Gitea wiki
 │   ├── push_badges.py   # Generate and push quality badges (--retries for retry on git push failures)
 │   ├── notify_failure.py    # Create Gitea issues on CI failures (--auto-login)
-│   ├── merge_junit.py   # Merge JUnit XML reports from parallel runners
-│   ├── distribute_files.py  # Distribute files across parallel runners
-│   ├── integration_guard.py # Run pytest with cross-runner fail-fast + JUnit output
+│   ├── distribute_files.py  # Distribute files across parallel runners (LPT scheduling)
+│   ├── distribute_items.py  # Distribute generic items (VMs, hosts) across parallel runners (LPT)
+│   ├── integration_guard.py # Run pytest with cross-runner fail-fast
 │   ├── check_translations.py  # Translation completeness check
-│   └── doc_coverage.py  # Documentation coverage check
+│   ├── doc_coverage.py  # Documentation coverage check
+│   └── lint_docs.py  # Documentation linter (structure, links, headings, code blocks, orphans)
 ├── 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
+│   ├── 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
+│   ├── check_mutable_globals.py  # Detect module-level mutable globals (test isolation bugs)
+│   ├── check_pyproject_deps.py   # Validate pyproject.toml deps have documentation comments
+│   ├── check_test_coverage.py    # Ensure changed files have corresponding tests (configurable rules)
+│   ├── check_agent_docs.py       # Validate docs for stale file references (configurable patterns)
+│   ├── check_config.py       # Validate pyproject.toml [tool.devx] config
 │   ├── configure_repo.py    # Branch protection and label setup
-│   └── generate_badges.py   # Badge SVG generation
+│   ├── generate_badges.py   # Badge SVG generation
+│   ├── generate_cliff_config.py  # Generate git-cliff config (cliff.toml)
+│   ├── create_task.py       # Create Vikunja tasks
+│   ├── create_pr.py         # Create PRs with auto-derived title from Vikunja
+│   ├── pr_status.py         # Check CI status for a PR/commit (--wait polls)
+│   ├── pr_logs.py           # Fetch logs for failed CI jobs
+│   ├── pr_label.py          # Add labels to PRs (idempotent)
+│   ├── 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)
 └── molecule/            # Optional molecule testing helpers (for Ansible projects)
    ├── discover_runners.py    # Dynamic Gitea runner discovery
-    ├── distribute_molecule.py # Distribute molecule scenarios across runners (--roles-root for multi-role)
-    ├── molecule_ci_guard.py   # Run molecule with cross-runner fail-fast + JUnit output (--roles-root, --junit-output)
+    ├── distribute_molecule.py # Distribute molecule scenarios across runners (LPT scheduling, --roles-root for multi-role)
+    ├── molecule_ci_guard.py   # Run molecule with cross-runner fail-fast (--roles-root)
    ├── molecule_all.py        # Run all molecule scenarios locally
+    ├── start_docker.py        # Ensure Docker daemon is running for molecule tests
    └── platforms.py           # Supported molecule platforms
 ```

@@ -125,7 +161,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
@@ -163,7 +199,7 @@ the PR. Then add the `ready-to-merge` label. The auto-merge workflow will:
 1. **Validate** PR title format (`DEVX-N: <vikunja task title>`) and match against Vikunja task title
 2. **Check** that at least one substantive APPROVE review exists
 3. Wait for all CI checks to pass (including the `pr-review` job)
-4. Squash-merge with title: `DEVX-N <conventional commit message>` (space-separated, no colon after DEVX-N)
+4. Squash-merge with title: `DEVX-N: <conventional commit message>`
 5. The post-merge workflow marks the Vikunja task as done
 6. The release workflow automatically versions, tags, and publishes

@@ -177,7 +213,7 @@ After a PR is merged to master, the **post-merge workflow**

 1. **detect-type** — Checks if the commit is a regular merge or a
   release commit (`release: vX.Y.Z`). All subsequent jobs skip for
-   release commits.
+   release commits (except badges).

 2. **release** — Runs `python -m devx.ci.release` which:
   - Checks for user-facing changes via `python -m devx.ci.classify_changes`
@@ -189,14 +225,20 @@ After a PR is merged to master, the **post-merge workflow**
   - Creates an annotated tag `vX.Y.Z` on the release commit
   - Pushes both the commit and tag to master

-3. **sync-wiki** — Syncs documentation to the Gitea wiki.
+3. **sync-wiki** — Syncs documentation to the Gitea wiki. Runs for ALL
+   non-release commits (not just when release succeeds), so docs-only
+   changes still update the wiki.

 4. **badges** — Generates and pushes quality badge SVGs to the `badges` branch.
+   Uses `if: always()` so it runs on every push, including release commits.

-5. **vikunja** — Marks the corresponding Vikunja task as done.
+5. **vikunja** — Marks the corresponding Vikunja task as done. Runs for ALL
+   non-release commits (not just when release succeeds), so infrastructure-only
+   changes still update the task tracker.

-The tag push triggers the **publish workflow** (`.gitea/workflows/publish.yml`)
-which builds and publishes the package to the Gitea PyPI registry.
+6. **publish** — Runs after release succeeds (needs: release). Builds and
+   publishes the package to the Gitea PyPI registry. Gets the tag from the
+   release job's `tag` output (written via `GITHUB_OUTPUT`).

 ### Smart CI: User-Facing vs Workflow-Only Changes

@@ -250,7 +292,7 @@ so `.:src` is not needed. The `src` directory is the sole import root.

 The `tea` Gitea CLI tool is used for Gitea API interactions. It is installed
 by `python -m devx.tools.install_tools` and configured by
-`python -m devx.tools.setup` (login profile from `.env` `REPO_TOKEN`).
+`python -m devx.tools.setup` (login profile from `.env` `CI_GITEA_TOKEN`).

 **`devx.gitea_cli.TeaCLI`** — Python wrapper around `tea` CLI with JSON output parsing:
 - `create_issue()` — Create issues with labels
@@ -260,7 +302,7 @@ by `python -m devx.tools.install_tools` and configured by

 ### git-cliff Commit Preprocessing

-Merge commits on master have the format `DEVX-N <conventional commit>`. The
+Merge commits on master have the format `DEVX-N: <conventional commit>`. The
 `cliff.toml` includes a `commit_preprocessors` entry that strips the `DEVX-N `
 prefix before parsing. This ensures all merged work appears in the changelog.

@@ -283,7 +325,52 @@ setuptools via `dynamic = ["version"]` in `pyproject.toml`.
 | Branch name | `DEVX-N-short-description` | `DEVX-12-add-release-script` |
 | Branch commits | `<conventional commit>` | `feat: add release script` |
 | PR title | `DEVX-N: <vikunja task title>` | `DEVX-12: Add release automation` |
-| Merge commit | `DEVX-N <conventional commit>` | `DEVX-12 feat: add release script` |
+| Merge commit | `DEVX-N: <conventional commit>` | `DEVX-12: feat: add release script` |
+
+### Task ID Resolution
+
+`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 (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
+`result == 'skipped'`.
+
+```yaml
+auto-merge:
+  needs: [quality, detect-changes, pr-review, molecule-tests]
+  if: >-
+    always() &&
+    github.event_name == 'pull_request' &&
+    needs.quality.result == 'success' &&
+    needs.pr-review.result == 'success' &&
+    (needs.molecule-tests.result == 'success' || needs.molecule-tests.result == 'skipped')
+```
+
+### LPT Test Distribution Algorithm
+
+`distribute_molecule` and `distribute_files` use **LPT (Longest Processing
+Time first)** scheduling instead of naive round-robin. This produces a more
+balanced distribution when test items have varying costs:
+
+1. **Weight estimation**: Each item is assigned a weight:
+   - Molecule scenarios: heuristic by name (`nextcloud`=10, `gitea`=8,
+     `binary`=2, default=3). See `_SCENARIO_WEIGHTS` in
+     `distribute_molecule.py`.
+   - Integration test files: weight by file size in bytes (as a proxy
+     for test runtime).
+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 (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.

 ## Config System

@@ -295,8 +382,12 @@ devx uses environment variables with `.env` file fallback for configuration.
 |----------|---------|-------------|
 | `DEVX_GITEA_API_URL` | `https://git.oblachno.oblachno.fyi/api/v1` | Gitea API base URL |
 | `DEVX_VIKUNJA_API_URL` | `https://work.oblachno.oblachno.fyi/api/v1` | Vikunja API base URL |
-| `DEVX_LANG` | `en` | Language for i18n (en, bg) |
-| `REPO_TOKEN` | (from .env) | Gitea API token |
+| `DEVX_REPO_OWNER` | **(none — must be set)** | Repository owner for API calls |
+| `DEVX_REPO_NAME` | **(none — must be set)** | Repository name (or `owner/repo`) |
+| `DEVX_TASK_PREFIX` | `DEVX` | Task ID prefix (GRM, OBL-INFRA, etc.) |
+| `DEVX_VIKUNJA_PROJECT_ID` | `6` | Vikunja project ID |
+| `DEVX_LANG` | `en` | Language for i18n (en, bg, de, pl, ru, zh) |
+| `CI_GITEA_TOKEN` | (from .env) | Gitea API token |
 | `VIKUNJA_TOKEN` | (from .env) | Vikunja API token |

 ### Per-Project Overrides
@@ -305,6 +396,139 @@ Projects using devx can override the default API URLs and language by setting
 `DEVX_*` environment variables or entries in their `.env` file. The config
 system loads `.env` automatically via `python-dotenv`.

+### pyproject.toml [tool.devx] Configuration
+
+In addition to `DEVX_` env vars, several 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 (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
+
+**Tool-specific config**:
+- `[tool.devx.check_mutable_globals]` — `scan_dirs`, `skip_dirs`, `known_safe`
+- `[tool.devx.check_test_coverage]` — `rules` (source_pattern → test_paths mapping), `skip_patterns`
+- `[tool.devx.check_agent_docs]` — `scan_dirs`, `deleted_files`, `deprecated_patterns`, `legitimate_indicators`
+
+## devx.mak — Shared Makefile Fragment
+
+`devx.mak` provides common Makefile targets that projects can include
+via `-include $(DEVX_MAK)`. This eliminates Makefile duplication across
+projects.
+
+**Available targets** (all prefixed with `devx-`):
+
+| Target | Purpose |
+|--------|---------|
+| `devx-create-task` | Create a Vikunja task |
+| `devx-create-pr` | Create a PR with auto-derived title |
+| `devx-push` | Push current branch to origin |
+| `devx-push-with-pr` | Push and create PR in one step |
+| `devx-pr-status` | Check CI status for a PR (`PR=`, `WAIT=`, `TIMEOUT=`) |
+| `devx-pr-logs` | Fetch logs for failed CI jobs (`PR=`, `JOB=`, `TAIL=`) |
+| `devx-pr-label` | Add a label to a PR (`PR=`, `LABEL=ready-to-merge`) |
+| `devx-pr-review` | Post a review on a PR (`PR=`, `EVENT=`, `BODY=`, `CHECKLIST=`) |
+| `devx-check-config` | Validate devx configuration |
+| `devx-configure-gitea-pypi` | Configure Gitea private PyPI registry |
+| `devx-env` | Create .env from .env.example |
+| `devx-venv` | Create Python venv with version check |
+| `devx-activate-scripts` | Create shell/fish/zsh activate scripts |
+| `devx-install-hooks` | Set git hooks path to hooks/ |
+| `devx-install-tools` | Install actionlint, git-cliff, act_runner, tea, hadolint |
+| `devx-install-checkmake` | Install checkmake (Makefile linter) |
+| `devx-checkmake` | Lint Makefiles with checkmake |
+| `devx-workflow-lint` | Static lint of Gitea Actions YAML (actionlint) |
+| `devx-workflow-dryrun` | Dry-run all workflows (act_runner) |
+| `devx-workflow-dryrun-safe` | Best-effort dry-run (skips if act_runner missing) |
+| `devx-workflow-check` | Static lint + dry-run |
+| `devx-notify-failure` | Create Gitea issue on CI failure |
+| `devx-lint-ruff` | Run ruff check |
+| `devx-lint-format` | Run ruff format --check |
+| `devx-typecheck` | Run pyright |
+| `devx-lint-bandit` | Run bandit security scan |
+| `devx-lint-deps` | Check dependencies for vulnerabilities (pip-audit) |
+| `devx-lint` | Run all lint targets |
+| `devx-test-unit` | Run unit tests without coverage |
+| `devx-pytest-cov` | Run pytest with coverage enforcement |
+| `devx-check-mutable-globals` | Scan for mutable path globals |
+| `devx-check-dep-docs` | Validate pyproject.toml deps are documented |
+| `devx-check-test-coverage` | Check changed files have corresponding tests |
+| `devx-check-docs` | Validate docs for stale references |
+| `devx-check-test-speed` | Verify test suite timing |
+| `devx-pre-push` | Run lint + tests before push |
+| `devx-clean` | Remove caches, build artifacts, coverage data |
+| `devx-setup-image` | Link /opt/venv + install project (for pre-built image CI jobs) |
+| `devx-lint-dockerfiles` | Lint Dockerfiles with hadolint (fail-fast, parameterized by `DEVX_DOCKERFILE_PATHS`) |
+| `devx-build-images` | Build Docker images from manifest (no push) |
+| `devx-push-images` | Build and push Docker images to Gitea registry |
+| `devx-build-images-dry-run` | Show what would be built/pushed |
+| `devx-clean-images` | Delete old image versions (keep last 2 + latest) |
+
+**Variables** (set BEFORE including devx.mak):
+- `DEVX_PYTHON` — Python executable (default: `python3`)
+- `DEVX_VENV` — venv directory (default: `.venv`)
+- `DEVX_BIN` — venv bin directory (default: `$(DEVX_VENV)/bin`)
+- `DEVX_LINT_PATHS` — paths for ruff/bandit (default: `src/ tests/`)
+- `DEVX_COV_PKG` — coverage package (default: `src/devx`)
+- `DEVX_TEST_PATHS` — pytest paths (default: `tests/`)
+- `DEVX_PR_BASE` — PR base branch (default: `master`)
+- `DEVX_DOCKERFILE_PATHS` — directory to search for Dockerfiles (default: `docker`)
+- `DEVX_GITEA_REGISTRY` — registry URL (default: `git.oblachno.oblachno.fyi`)
+- `DEVX_IMAGE_MANIFEST` — path to JSON manifest (default: `docker/images.json`)
+- `DEVX_IMAGE_OWNER` — package owner for cleanup (default: `oblachno-oss`)
+
+## Pre-built Docker Runner Images
+
+devx builds and publishes three tier images to the Gitea container registry
+to eliminate the 40-120s setup tax on every CI job:
+
+| Image | Contains | Used by jobs |
+|-------|----------|-------------|
+| `ci-base-latest` | Python 3.12 + devx[ci] + tea | detect-changes, detect-type, validate-commit-msg, pr-review, auto-merge, sync-wiki, vikunja, configure-repo |
+| `ci-quality-latest` | ci-base + devx[lint] + actionlint + checkmake + hadolint | quality, badges |
+| `ci-full-latest` | ci-quality + devx[release,molecule,deploy] + git-cliff + OpenTofu | release, publish, release-dry-run, molecule-tests, deploy jobs |
+
+**Build process** (in `build-images.yml` workflow):
+1. `ci-base` builds FROM `gitea/runner-images:ubuntu-latest`
+2. `ci-quality` builds FROM `ci-base-latest`
+3. `ci-full` builds FROM `ci-quality-latest`
+
+Each image is tagged `latest` and pushed to
+`git.oblachno.oblachno.fyi/oblachno-oss/runner-images:<tier>-latest`.
+
+**Using images in workflows**:
+```yaml
+jobs:
+  quality:
+    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        run: make setup-image  # links /opt/venv, installs project (no-deps)
+```
+
+**Image build/push tools** (tested Python modules):
+- `devx.tools.build_image` — Build and push Docker images from Dockerfile or manifest
+- `devx.tools.clean_images` — Delete old image versions via Gitea API (keep last N + latest)
+
+**Usage in project Makefile**:
+```makefile
+DEVX_PYTHON := $(BIN)/python
+DEVX_MAK := $(shell $(BIN)/python -c \
+    "from pathlib import Path; import devx; print(Path(devx.__file__).parent / 'make' / 'devx.mak')" \
+    2>/dev/null)
+-include $(DEVX_MAK)
+
+# Aliases for project-specific names
+lint-ruff: devx-lint-ruff
+workflow-lint: devx-workflow-lint
+create-task: devx-create-task
+```
+
 ## Key Conventions

 - Python 3.12+ required (ruff/pyright target `py312`)
@@ -314,3 +538,113 @@ system loads `.env` automatically via `python-dotenv`.
 - Line length: 120 chars
 - Secrets are passed via environment variables, never on the command line
 - All user-facing strings wrapped in `_()` for i18n
+
+### Container-Level Fix Verification (Mandatory)
+
+**Rule:** Before pushing any fix that modifies container state (CA certs,
+config files, installed packages, daemon restarts), reproduce the exact
+sequence locally with the actual Docker image. Do not push to CI as the
+first test.
+
+This is a hard rule, not a suggestion. CI cycles take 20+ minutes and
+ephemeral staging VMs are destroyed after each run, making interactive
+debugging impossible. A local reproduction takes 30 seconds and catches
+silent failures immediately.
+
+**Procedure:**
+1. `docker pull <actual_image>`
+2. `docker run -d --name <test> ...` and wait for it to start
+3. Run the exact commands from the Ansible task or script
+4. Verify the state change took effect
+5. Clean up: `docker rm -f <test>`
+
+### Verified State Modification (Mandatory)
+
+Ansible tasks that modify container state with `changed_when: false`
+MUST include a post-task verification step that confirms the state
+change took effect. `changed_when: false` suppresses both change
+detection AND failure visibility — a task can silently do nothing and
+report `ok`.
+
+## Subagent Delegation Policy
+
+Custom subagent profiles are defined in `.devin/agents/` (project-specific)
+and `~/.config/devin/agents/` (global, shared across repos). The agent MUST
+automatically delegate to the appropriate subagent based on the task —
+the user should not need to specify which profile to use.
+
+### Available Profiles
+
+**Global** (shared across all projects):
+
+| Profile | Location | Purpose |
+|---------|----------|---------|
+| `pr-reviewer` | `~/.config/devin/agents/` | 13-category PR checklist + quality gates |
+| `release-check` | `~/.config/devin/agents/` | Pre-merge readiness validation |
+
+**devx-specific** (in `.devin/agents/`):
+
+| Profile | Purpose |
+|---------|---------|
+| `ci-investigator` | Investigate CI failures (quality, release, publish, wiki sync, image build) |
+| `dep-upgrader` | Python dependency upgrades in pyproject.toml with dep-doc validation |
+| `docker-image-builder` | Build/push/cleanup 3-tier runner images (ci-base, ci-quality, ci-full) |
+| `doc-sync-specialist` | Doc coverage, doc linting, wiki sync integrity |
+| `workflow-validator` | actionlint + act_runner dry-run validation |
+
+### When to Delegate Automatically
+
+| Trigger | Profile | Mode |
+|---------|---------|------|
+| CI run failure (quality, release, publish, sync-wiki, build-images) | `ci-investigator` | Background |
+| PR ready for review | `pr-reviewer` | Foreground |
+| Dependency upgrade requested | `dep-upgrader` | Background |
+| Docker image build/push needed | `docker-image-builder` | Background |
+| Doc coverage failure or wiki sync issue | `doc-sync-specialist` | Background |
+| Workflow YAML modified or validation needed | `workflow-validator` | Background |
+| Branch ready for merge | `release-check` | Foreground |
+
+### Delegation Rules
+
+1. **Auto-select the profile.** Do not ask the user 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).
+6. **Compact after subagent returns.**
+7. **Never skip delegation to save time** — it keeps main context small.
+
+
+## Feedback Issue Handling
+
+Subagents create Gitea issues in the current repo when they encounter
+tool, workflow, or process issues that warrant follow-up. These issues
+use the `feedback` label plus a category label (`tooling`,
+`ci-improvement`, `doc-improvement`, `workflow-improvement`).
+
+Standard labels are created automatically by `configure_repo` (runs in
+post-merge on every master push). If a label does not exist yet, the
+subagent's issue creation will still succeed — labels can be added
+afterwards.
+
+### When a Subagent Reports a Feedback Issue URL
+
+1. **Acknowledge it** in your response to the user — mention the issue URL
+2. **Do NOT close or modify** the issue — it is for follow-up work
+3. **Do NOT create a PR** to address it unless the user explicitly asks
+4. If the user asks to address feedback, spawn a subagent to investigate
+   the issue and implement a fix
+
+### Creating Feedback Issues Manually
+
+As the parent agent, you can also create feedback issues directly using
+the Gitea MCP (`issue_write` with `create_issue` method). Follow the
+same format as subagents:
+
+- Title: `[feedback] <category>: <short description>`
+- Labels: `feedback` + category label
+- Body: include context, tool/workflow, issue, reproduction, affected
+  files, suggested investigation, and "Reported by: parent agent"
+
+Always deduplicate first via `list_issues` with `labels: "feedback"`.
+
@@ -2,6 +2,560 @@

 All notable changes to this project will be documented in this file.

+## [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
+
+- Abort sync_wiki when list_wiki_pages fails
+
+## [0.33.1] - 2026-07-05
+
+### Bug Fixes
+
+- Build images after post-merge publish, not on push
+
+## [0.33.0] - 2026-07-05
+
+### Features
+
+- Add check_api_identity_checks, setup_ssh_key, and api utils
+
+## [0.32.1] - 2026-07-01
+
+### Bug Fixes
+
+- Add missing i18n translations for new tools
+
+## [0.32.0] - 2026-07-01
+
+### Features
+
+- Extract docker-login, tofu-ops, check-deps, install-tofu to Python tools
+
+## [0.31.0] - 2026-07-01
+
+### Features
+
+- Centralize venv management in devx.mak
+
+## [0.30.0] - 2026-07-01
+
+### Features
+
+- Add standard label creation to configure_repo
+
+## [0.29.1] - 2026-07-01
+
+### Bug Fixes
+
+- Strip task ID prefix from commit messages in extract_conventional_msg
+
+## [0.29.0] - 2026-07-01
+
+### Features
+
+- Detect badge commits as automated CI commits
+
+## [0.28.0] - 2026-07-01
+
+### Features
+
+- Auto-rebase in auto-merge, new rebase tools, CLI registration
+
+## [0.27.3] - 2026-06-30
+
+### Bug Fixes
+
+- Retry wiki integrity check on transient API timeout
+
+## [0.27.2] - 2026-06-29
+
+### Bug Fixes
+
+- Retry release push on non-fast-forward with rebase loop
+
+## [0.27.1] - 2026-06-28
+
+### Bug Fixes
+
+- Exclude .devin/.terraform dirs from lint_docs, add duplicate heading excludes
+
+## [0.27.0] - 2026-06-28
+
+### Features
+
+- Add lint_docs tool, fix doc_coverage/check_translations for any repo
+
+## [0.26.4] - 2026-06-28
+
+### Bug Fixes
+
+- Wrap all user-facing strings with _() for i18n completeness
+
+## [0.26.3] - 2026-06-28
+
+### Bug Fixes
+
+- Pin all dependencies to exact versions for reproducibility
+
+## [0.26.2] - 2026-06-28
+
+### Bug Fixes
+
+- Block admin merge override and auto-approve with review token
+
+## [0.26.1] - 2026-06-28
+
+### Bug Fixes
+
+- Force pip upgrade in setup-image to install new dependencies
+
+## [0.26.0] - 2026-06-28
+
+### Features
+
+- Add distribute_items CI tool for parallel VM deployment
+
+## [0.25.0] - 2026-06-28
+
+### Features
+
+- Add manual review support to pr_review (--event, --body, --checklist-confirmed)
+
+## [0.24.1] - 2026-06-28
+
+### Refactor
+
+- Add find_task_by_identifier, config fallbacks for tools
+
+## [0.24.0] - 2026-06-27
+
+### Features
+
+- Add pr_status, pr_logs, pr_label tools
+
+## [0.23.4] - 2026-06-27
+
+### Bug Fixes
+
+- Add --auto-login to all notify_failure calls in workflows
+- Classify .gitea/** as user-facing for devx, support glob in user_facing_overrides
+
+## [0.23.3] - 2026-06-27
+
+### Bug Fixes
+
+- Correct clean_images delete URL and add retry with error handling
+
+## [0.23.2] - 2026-06-27
+
+### Bug Fixes
+
+- Add skip-ci flag to release commits and concurrency to build-images
+
+## [0.23.1] - 2026-06-27
+
+### Bug Fixes
+
+- Add rsync to ci-full image for molecule_docker
+
+## [0.23.0] - 2026-06-27
+
+### Features
+
+- Add devx-lint-dockerfiles to devx.mak, alias setup-image
+
+### Refactor
+
+- Remove hadolint on-the-fly install from setup-image
+
+## [0.22.1] - 2026-06-27
+
+### Bug Fixes
+
+- Checkout release tag in publish job
+- Fail lint-dockerfiles when hadolint is missing
+
+## [0.22.0] - 2026-06-27
+
+### Features
+
+- Document CI_GITEA_TOKEN scopes and add CI_GITEA_USERNAME to env var table
+
+## [0.21.2] - 2026-06-27
+
+### Bug Fixes
+
+- Gate auto-merge on release-dry-run and unmask failures
+
+## [0.21.1] - 2026-06-27
+
+### Bug Fixes
+
+- Devx-setup-image configures Gitea PyPI registry and shows pip errors
+
+## [0.21.0] - 2026-06-27
+
+### Features
+
+- Add --auto-login to publish, extract configure_tea_login to gitea_cli
+
+### Bug Fixes
+
+- Publish job uses setup-release for build + tea login
+- Remove tag fallback step from release workflow
+
+## [0.20.3] - 2026-06-27
+
+### Bug Fixes
+
+- Release publish failures and duplicate release commits
+
+## [0.20.2] - 2026-06-27
+
+## [0.20.2] - 2026-06-27
+
+### Bug Fixes
+
+- Correct sed substitution in ci-full Dockerfile
+
+## [0.20.1] - 2026-06-27
+
+### Bug Fixes
+
+- Correct image references in tier Dockerfiles
+
+## [0.20.0] - 2026-06-27
+
+### Features
+
+- Add pre-built Docker runner images and tested image build/push tools
+
+## [0.19.3] - 2026-06-26
+
+### Refactor
+
+- Make molecule weights configurable via pyproject.toml
+
+## [0.19.2] - 2026-06-26
+
+### Bug Fixes
+
+- Calibrate molecule weights from actual CI execution times
+
+## [0.19.1] - 2026-06-26
+
+### Refactor
+
+- Consolidate publish.yml into post-merge.yml
+
+## [0.19.0] - 2026-06-26
+
+### Features
+
+- Add skip_ref_prefixes config to check_agent_docs
+
+## [0.18.0] - 2026-06-26
+
+### Features
+
+- Extract generic tools into devx, expand devx.mak, remove personal references
+
+## [0.17.0] - 2026-06-26
+
+### Features
+
+- Weighted LPT distribution, workflow fixes, decouple vikunja/sync-wiki from release
+
+## [0.16.0] - 2026-06-26
+
+### Features
+
+- Single-source-of-truth config via [tool.devx] in pyproject.toml
+
+## [0.15.0] - 2026-06-26
+
+### Features
+
+- Add create-task, create-pr, pre-push-check tools and devx.mak fragment
+
+## [0.14.2] - 2026-06-26
+
+### Bug Fixes
+
+- Make repo arg optional in publish CLI, auto-detect from GITHUB_REPOSITORY
+
+## [0.14.1] - 2026-06-25
+
+### Bug Fixes
+
+- Handle 'already a release' error idempotently in publish
+
+## [0.14.0] - 2026-06-25
+
+### Features
+
+- Add FORCE_DEPLOY env var, --git flag, --from-tag flag
+
+## [0.13.0] - 2026-06-25
+
+### Features
+
+- Add --force flag to classify_changes, fix api_clients coverage
+
+### Bug Fixes
+
+- Squash-merge format uses space not colon after task ID
+- Revert squash-merge format to use colon after task ID
+
+## [0.1.0] - 2026-06-25
+
+## [0.12.5] - 2026-06-25
+
+### Bug Fixes
+
+- Make PyPI publish failures non-fatal
+
+## [0.12.4] - 2026-06-25
+
+### Bug Fixes
+
+- Pass REPO_TOKEN to setup-release so tea login is configured
+- Guarantee Gitea release for every tag
+
+## [0.12.3] - 2026-06-25
+
+### Refactor
+
+- Remove JUnit reporting from devx
+
+## [0.12.2] - 2026-06-25
+
+### Bug Fixes
+
+- Remove auto-rebase from auto-merge to prevent CI feedback loop
+
+## [0.12.1] - 2026-06-25
+
+### Bug Fixes
+
+- Use heredoc syntax for multi-line $GITHUB_ENV values
+
+## [0.12.0] - 2026-06-24
+
+### Features
+
+- Add Polish as officially supported language
+
+## [0.11.1] - 2026-06-24
+
+### Bug Fixes
+
+- Add build/twine to ci deps, activate venv in notify_failure
+
+## [0.11.0] - 2026-06-24
+
+### Features
+
+- Add publish step to post-merge release job, make publish idempotent
+
+## [0.10.2] - 2026-06-24
+
+### Bug Fixes
+
+- Badge generation respects pyproject.toml testpaths, shows stdout in warnings
+
+## [0.10.1] - 2026-06-24
+
+### Bug Fixes
+
+- Badge generation REPO_ROOT, auto-detect package, error feedback
+
+## [0.10.0] - 2026-06-24
+
+### Features
+
+- Remove .taskid file fallback, use branch name only
+
+### Bug Fixes
+
+- Use raw/branch/badges/ URLs for badges in README and docs
+
+## [0.9.12] - 2026-06-24
+
+### Bug Fixes
+
+- Clean dist/ before build and add workflow_dispatch to publish
+
+## [0.9.11] - 2026-06-24
+
+### Bug Fixes
+
+- Use raw/branch/badges/ URLs for badges in README and docs
+- Resolve repo_root from GITHUB_WORKSPACE or cwd
+
+## [0.9.10] - 2026-06-24
+
+### Bug Fixes
+
+- Retrospective fixes for CI/CD friction
+
+## [0.9.9] - 2026-06-24
+
+### Bug Fixes
+
+- Use DOCKER_HOST env var in is_docker_ready + scan all rootless sockets
+- Prefer branch name for task ID extraction + strip heads/ prefix in release
+- Filter non-version tags in release verification
+- Use explicit refspecs for git push to avoid tag/branch ambiguity
+
+## [0.9.8] - 2026-06-24
+
+### Bug Fixes
+
+- Use DOCKER_HOST env var in is_docker_ready + scan all rootless sockets
+
+## [0.9.7] - 2026-06-24
+
+### Bug Fixes
+
+- Add rootless socket fallback and GITHUB_ENV export
+
+## [0.9.6] - 2026-06-24
+
+### Bug Fixes
+
+- Add Docker socket diagnostics to start_docker
+- Add Docker socket diagnostics to start_docker
+
+## [0.9.5] - 2026-06-24
+
+### Bug Fixes
+
+- Use host Docker socket with DOCKER_HOST fallback to local dockerd
+- Use host Docker socket with DOCKER_HOST fallback to local dockerd
+
+## [0.9.4] - 2026-06-24
+
+### Bug Fixes
+
+- Use separate Docker socket for DinD in CI
+
+## [0.9.3] - 2026-06-24
+
+### Bug Fixes
+
+- Use tempfile for dockerd log to fix CI permission error
+
+## [0.9.2] - 2026-06-24
+
+### Bug Fixes
+
+- Use vfs storage driver for Docker-in-Docker in CI
+
+## [0.9.1] - 2026-06-23
+
+### Bug Fixes
+
+- Always start dockerd in CI runner for molecule tests
+
+## [0.9.0] - 2026-06-23
+
+### Features
+
+- Extract Docker daemon start to tested Python module
+
+## [0.8.5] - 2026-06-23
+
+### Bug Fixes
+
+- Retry pip install with --ignore-installed only on failure
+
+## [0.8.4] - 2026-06-23
+
+### Bug Fixes
+
+- Add --ignore-installed to pip in CI to bypass debian packages
+
+## [0.8.3] - 2026-06-23
+
+### Bug Fixes
+
+- Lower check_test_speed threshold to 4 seconds
+- Pass --break-system-packages to pip in CI environments
+
 ## [0.8.2] - 2026-06-23

 ### Bug Fixes
@@ -208,8 +208,8 @@ If you develop a new program, and you want it to be of the greatest possible use

 To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

-     grm
-     Copyright (C) 2026  emil
+     devx
+     Copyright (C) 2026  oblachno-oss

     This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

@@ -221,7 +221,7 @@ Also add information on how to contact you by electronic and paper mail.

 If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:

-     grm  Copyright (C) 2026  emil
+     devx  Copyright (C) 2026  oblachno-oss
     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.

@@ -1,4 +1,4 @@
-.PHONY: all setup setup-ci setup-quality setup-release install update lint lint-ruff lint-format typecheck lint-bandit lint-deps lint-all test test-unit pytest-cov clean workflow-lint workflow-dryrun workflow-check install-tools install-hooks activate-scripts
+.PHONY: all setup setup-ci setup-quality setup-release setup-image install update lint lint-all lint-dockerfiles test test-unit pytest-cov clean install-tools install-hooks activate-scripts checkmake check-mutable-globals check-dep-docs check-test-speed build-images push-images build-images-dry-run clean-images

 PYTHON := python3
 VENV := .venv
@@ -6,6 +6,36 @@ BIN := $(VENV)/bin

 all: setup

+# --- devx.mak integration ----------------------------------------------------
+# Include shared targets from the devx package itself (venv management,
+# workflow-lint, notify-failure, checkmake, lint targets, quality checks, etc.)
+# Since devx IS the package, we can include its own devx.mak.
+DEVX_PYTHON := $(BIN)/python
+DEVX_VENV := $(VENV)
+DEVX_BIN := $(BIN)
+DEVX_LINT_PATHS := src/ tests/
+DEVX_COV_PKG := src/devx
+DEVX_TEST_PATHS := tests/
+
+DEVX_MAK := $(shell $(BIN)/python -c \
+	"from pathlib import Path; import devx; print(Path(devx.__file__).parent / 'make' / 'devx.mak')" \
+	2>/dev/null)
+# Fallback: when the venv doesn't exist yet (chicken-and-egg), use the
+# source tree copy directly. devx IS the package, so src/devx/make/devx.mak
+# is always available in this repo.
+ifeq ($(strip $(DEVX_MAK)),)
+DEVX_MAK := $(CURDIR)/src/devx/make/devx.mak
+endif
+-include $(DEVX_MAK)
+
+# venv, .env, and activate-scripts are provided by devx.mak
+# (devx-venv, devx-env, devx-activate-scripts, $(DEVX_VENV)/bin/activate rule)
+# Aliases for convenience and backward compatibility:
+.PHONY: venv activate-scripts
+venv: devx-venv
+.env: devx-env
+activate-scripts: devx-activate-scripts
+
 # Full setup for local development
 setup: $(VENV)/bin/activate .env activate-scripts install-tools
 	@$(BIN)/pip install -e '.[dev]' 2>/dev/null; \
@@ -25,23 +55,18 @@ setup-quality: $(VENV)/bin/activate .env install-tools

 # Setup for release jobs (needs git-cliff, tea, lint tools)
 setup-release: $(VENV)/bin/activate .env
-	@$(BIN)/pip install -e '.[ci,lint]' 2>/dev/null; \
+	@$(BIN)/pip install -e '.[ci,lint,release]' 2>/dev/null; \
 	$(BIN)/python -m devx.tools.install_tools --tool git-cliff --tool tea; \
 	export PATH="$(HOME)/.local/bin:$$PATH"; \
-	$(BIN)/python -m devx.tools.setup --bin "$(BIN)" --extras "ci,lint" --no-pre-commit
+	$(BIN)/python -m devx.tools.setup --bin "$(BIN)" --extras "ci,lint,release" --no-pre-commit

-.env:
-	@if [ ! -f .env ]; then cp .env.example .env; echo "Created .env from .env.example — please edit it."; fi
-
-$(VENV)/bin/activate:
-	@python3 -c "import sys; v=sys.version_info; assert v >= (3, 12), f'Python 3.12+ required, found {v.major}.{v.minor}'; print(f'Python {v.major}.{v.minor}.{v.micro} OK')"
-	$(PYTHON) -m venv $(VENV)
-	$(BIN)/pip install --upgrade pip setuptools wheel
-
-activate-scripts: $(VENV)/bin/activate
-	@test -f activate.sh || (echo '#!/usr/bin/env bash' > activate.sh && echo 'source "$$(cd "$$(dirname "$${BASH_SOURCE[0]}")" && pwd)/.venv/bin/activate"' >> activate.sh && chmod +x activate.sh)
-	@test -f activate.fish || (echo '#!/usr/bin/env fish' > activate.fish && echo 'set -l script_dir (dirname (status --current-filename))' >> activate.fish && echo 'source "$$script_dir/.venv/bin/activate.fish"' >> activate.fish && chmod +x activate.fish)
-	@test -f activate.zsh || (echo '#!/usr/bin/env zsh' > activate.zsh && echo '0="$${ZERO:-$${0:#$$ZSH_ARGZERO}}"' >> activate.zsh && echo '0="$${$${(M)0:#/*}:-$$PWD/$$0}"' >> activate.zsh && echo 'source "$${0:A:h}/.venv/bin/activate"' >> activate.zsh && chmod +x activate.zsh)
+# Setup for pre-built image jobs (deps already in image, just link venv + install project)
+# Note: Not aliased to devx-setup-image because devx's own CI images may have
+# an older devx.mak that doesn't yet define devx-setup-image. Consumer repos
+# (grm, infra) can safely alias to devx-setup-image since they install devx from PyPI.
+setup-image:
+	@if [ -d /opt/venv ]; then ln -sf /opt/venv $(VENV); . $(VENV)/bin/activate && pip install --no-cache-dir -e . 2>/dev/null; \
+	else echo "[setup-image] /opt/venv not found — falling back to setup-ci"; $(MAKE) setup-ci; fi

 install-hooks:
 	@cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
@@ -52,48 +77,70 @@ install-tools: $(VENV)/bin/activate
 	@$(BIN)/pip install -e '.' 2>/dev/null; \
 	$(BIN)/python -m devx.tools.install_tools

-lint-ruff:
-	$(BIN)/ruff check src/ tests/
+# Aliases — project-specific names map to devx.mak targets
+.PHONY: lint-ruff lint-format typecheck lint-bandit lint-deps lint
+.PHONY: workflow-lint workflow-dryrun workflow-dryrun-safe workflow-check
+.PHONY: notify-failure checkmake check-mutable-globals check-dep-docs
+.PHONY: check-test-speed check-test-coverage check-docs
+.PHONY: create-task create-pr push-with-pr git-push rebase pr-rebase
+.PHONY: lint-all lint-dockerfiles
+lint-ruff: devx-lint-ruff
+lint-format: devx-lint-format
+typecheck: devx-typecheck
+lint-bandit: devx-lint-bandit
+lint-deps: devx-lint-deps
+lint: devx-lint
+workflow-lint: devx-workflow-lint
+workflow-dryrun: devx-workflow-dryrun
+workflow-dryrun-safe: devx-workflow-dryrun-safe
+workflow-check: devx-workflow-check
+notify-failure: devx-notify-failure
+checkmake: devx-checkmake
+check-mutable-globals: devx-check-mutable-globals
+check-dep-docs: devx-check-dep-docs
+check-test-speed: devx-check-test-speed
+check-test-coverage: devx-check-test-coverage
+check-docs: devx-check-docs
+create-task: devx-create-task
+create-pr: devx-create-pr
+push-with-pr: devx-push-with-pr
+git-push: devx-push
+rebase: devx-rebase
+pr-rebase: devx-pr-rebase

-lint-format:
-	$(BIN)/ruff format --check src/ tests/
+lint-all: lint workflow-lint lint-dockerfiles
+	@echo "[lint-all] All linting checks passed."

-typecheck:
-	$(BIN)/pyright
+# Note: Not aliased to devx-lint-dockerfiles for the same reason as setup-image —
+# devx's own CI images may have an older devx.mak. Consumer repos can safely alias.
+lint-dockerfiles:
+	@echo "[lint-dockerfiles] Linting Dockerfiles with hadolint..."
+	@command -v hadolint >/dev/null 2>&1 || { echo "hadolint not found" >&2; exit 1; }
+	@find docker -name 'Dockerfile*' -exec hadolint {} +
+	@echo "[lint-dockerfiles] All Dockerfiles passed."

-lint-bandit:
-	$(BIN)/bandit -r src/
+test-unit: devx-test-unit

-lint: lint-ruff lint-format typecheck lint-bandit
-
-lint-deps:
-	@echo "Checking dependencies for known vulnerabilities..."
-	@.venv/bin/python -m ensurepip 2>/dev/null || true
-	@PIPAPI_PYTHON_LOCATION=$$(pwd)/.venv/bin/python .venv/bin/pip-audit --desc --skip-editable 2>&1 || true
-
-lint-all: lint workflow-lint
-
-workflow-lint:
-	@command -v actionlint >/dev/null 2>&1 || { echo "actionlint not found."; exit 1; }
-	actionlint -config-file .gitea/actionlint.yaml .gitea/workflows/*.yml
-
-workflow-dryrun:
-	@command -v act_runner >/dev/null 2>&1 || { echo "act_runner not found."; exit 1; }
-	@echo "Dry-running all workflows..."
-	act_runner exec --dryrun -W .gitea/workflows/ 2>&1 | grep -E 'DRYRUN|ERROR|FAIL|Job'
-
-workflow-check: workflow-lint workflow-dryrun
-	@echo "Workflow checks passed."
-
-test-unit:
-	$(BIN)/pytest tests/unit/ -v --no-cov
-
-pytest-cov:
-	$(BIN)/pytest tests/ -v --cov=src/devx --cov-report=term-missing --cov-fail-under=100
+pytest-cov: devx-pytest-cov

 test: pytest-cov

-clean:
-	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
-	find . -type f -name "*.pyc" -delete 2>/dev/null || true
-	rm -rf .coverage htmlcov/ dist/ build/ *.egg-info/
+pre-push: lint-all pytest-cov
+	@echo "[pre-push] All checks passed. Proceeding with push."
+
+clean: devx-clean
+	@echo "[clean] Done."
+
+# ── Docker image management ──────────────────────────────────────────────────
+
+build-images: devx-build-images
+	@echo "[build-images] Done."
+
+push-images: devx-push-images
+	@echo "[push-images] Done."
+
+build-images-dry-run: devx-build-images-dry-run
+	@echo "[build-images-dry-run] Done."
+
+clean-images: devx-clean-images
+	@echo "[clean-images] Done."
@@ -1,46 +1,141 @@
 # devx — Reusable Development & CI/CD Tools

-A Python package providing reusable development and CI/CD automation tools for oblachno-oss projects. devx consolidates release management, PR automation, wiki sync, badge generation, translation checks, and more into a single installable package.
+A Python package providing reusable development and CI/CD automation tools for
+oblachno-oss projects. devx consolidates release management, PR automation,
+wiki sync, badge generation, translation checks, documentation coverage,
+parallel test distribution, and more into a single installable package.
+
+It was extracted from the [GRM](https://git.oblachno.oblachno.fyi/oblachno-oss/grm)
+project to be reusable across all oblachno-oss repositories. Any project hosted
+on a Gitea instance with Gitea Actions can install devx and inherit a complete,
+opinionated CI/CD pipeline: conventional commits, automated versioning via
+git-cliff, squash-merge automation, Vikunja task tracking, wiki sync, and
+quality badges.

 > An open-source project from **Oblachno** (облачно means *cloudy* in Bulgarian).

 [![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/badges/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/badges/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/badges/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/badges/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/badges/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/python.svg)](https://www.python.org/downloads/)
+
+## Why devx?
+
+Every oblachno-oss project shares the same CI/CD needs: automated releases,
+PR review, task tracking, documentation sync, and quality badges. Without a
+shared package, each repository duplicates this logic in shell scripts and
+workflow YAML, leading to drift, bugs, and maintenance burden.
+
+devx solves this by providing a single, tested Python package that any
+oblachno-oss project can install. The project declares its configuration via
+environment variables and `pyproject.toml`, and devx handles the rest. Updates
+to the CI/CD pipeline ship as new devx releases — consumer projects pick them
+up by bumping their devx dependency.
+
+### Key features
+
+- **Automated releases** — git-cliff-driven semver versioning, changelog
+  generation, tagging, and publishing to a Gitea PyPI registry.
+- **PR automation** — squash-merge with task ID validation, automated PR
+  review with inline comments, and conventional commit enforcement.
+- **Smart change classification** — user-facing vs workflow-only change
+  detection so infrastructure-only changes skip releases.
+- **Documentation sync** — push `docs/` markdown to the Gitea wiki with
+  integrity verification.
+- **Quality badges** — generate self-contained SVG badges for coverage,
+  tests, docs, quality, version, and Python version.
+- **Translation checks** — validate i18n keys against source code, detect
+  dead keys and missing languages.
+- **Parallel test distribution** — split test files or molecule scenarios
+  across CI runners with cross-runner fail-fast.
+- **Developer tools** — environment setup, CI tool installation, test speed
+  enforcement, repository configuration.
+- **i18n** — built-in translations for English, Bulgarian, German, Russian,
+  Chinese, and Polish; projects can extend with their own keys.

 ## Installation

-Install from the Gitea PyPI registry:
+devx is published to the Gitea PyPI registry at
+`https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple`.
+The registry is publicly readable — no authentication required to install.
+
+### Quick install (one-off)

 ```bash
 pip install devx --index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
 ```

-Or add the registry to your `pip.conf` / `pyproject.toml` and install normally:
+### Persistent configuration (recommended)

-```bash
-pip install devx
+Add the registry to `~/.pip/pip.conf` so `pip install devx` works without
+specifying `--index-url` every time:
+
+```ini
+[global]
+extra-index-url = https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
 ```

-## Usage
+### As a dependency in another project

-### CI/CD Automation
+To use devx as a dependency in your `pyproject.toml`, add the registry as an
+extra index and list devx in your dependencies:

-devx provides CI/CD modules invoked via `python -m devx.ci.*`:
+```toml
+[project]
+dependencies = [
+    "devx>=0.36.0",
+]
+
+[tool.pip]
+extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
+```
+
+Then install normally:
+
+```bash
+pip install -e .
+```
+
+> **Note:** If your project requires a specific devx version, pin it in
+> `dependencies` (for example, `"devx==0.36.0"`) or use a version constraint
+> (for example, `"devx>=0.36.0,<0.37"`).
+
+### Optional extras
+
+devx ships optional dependency groups for different use cases:
+
+```bash
+pip install "devx[ci,lint]"      # CI runners and linting (pytest, ruff, pyright, bandit, build, twine)
+pip install "devx[molecule]"     # Molecule testing for Ansible projects
+pip install "devx[dev]"          # Full local development (ci + lint + build + twine)
+```
+
+## Quick start
+
+After installing devx, set the required environment variables (see
+[Configuration](#configuration)) and invoke modules via `python -m devx.*` or
+the `devx` CLI.
+
+### CI/CD automation
+
+CI/CD modules are invoked via `python -m devx.ci.*`. Each module is also
+available as a `devx ci <command>` subcommand.

 ```bash
 # Release automation (versioning, changelog, tagging)
 python -m devx.ci.release
-python -m devx.ci.release --dry-run
+python -m devx.ci.release --dry-run          # preview without changes
+python -m devx.ci.release --verify           # check tag/version/changelog alignment

 # Publish a release to the Gitea PyPI registry
 python -m devx.ci.publish v1.0.0 oblachno-oss/devx
+python -m devx.ci.publish v1.0.0 oblachno-oss/devx --skip-build  # Gitea release only

-# Automated PR review
+# Automated PR review (posts inline comments and structured review)
 python -m devx.ci.pr_review 42 oblachno-oss/devx

 # Auto-merge a PR (validates title, squash-merges)
@@ -54,66 +149,240 @@ python -m devx.ci.sync_wiki --repo oblachno-oss/devx --strict

 # Generate and push quality badges
 python -m devx.ci.push_badges
+python -m devx.ci.push_badges --retries 3     # retry on git push failures

 # Check translation completeness
 python -m devx.ci.check_translations
+python -m devx.ci.check_translations --translations path/to/translations.json

 # Documentation coverage check
 python -m devx.ci.doc_coverage --fail-on-missing

+# Documentation lint (structure, links, headings, TODOs)
+python -m devx.ci.lint_docs --root .
+
 # Validate a commit message
 python -m devx.ci.validate_commit_msg commit-msg.txt --branch master

+# Detect whether the latest commit is a release commit
+python -m devx.ci.detect_release_commit
+
 # Notify on CI failure (creates a Gitea issue)
-python -m devx.ci.notify_failure --repo oblachno-oss/devx --run-id 123 --workflow ci --commit abc123
+python -m devx.ci.notify_failure --repo oblachno-oss/devx --run-id 123 \
+  --workflow ci --commit abc123 --auto-login
+
+# Discover available Gitea Actions runners
+python -m devx.ci.discover_runners --owner oblachno-oss --repo devx --indices
+
+# Distribute files across parallel runners (round-robin)
+python -m devx.ci.distribute_files --pattern "tests/integration/test_*.py" \
+  --runner-index 1 --max-runners 3 --github-env
+
+# Run pytest with cross-runner fail-fast
+python -m devx.ci.integration_guard -- test_a.py test_b.py
 ```

-### Developer Tools
+### Developer tools

-devx provides developer tooling invoked via `python -m devx.tools.*`:
+Developer tooling modules are invoked via `python -m devx.tools.*` or the
+`devx tools <command>` subcommand.

 ```bash
-# Set up a development environment (venv, deps, hooks)
+# Set up a development environment (venv, deps, hooks, tea login)
 python -m devx.tools.setup --bin .venv/bin
+python -m devx.tools.setup --bin .venv/bin --extras "ci,lint" --no-pre-commit

 # Install CI tools (actionlint, git-cliff, act_runner, tea)
 python -m devx.tools.install_tools
 python -m devx.tools.install_tools --tool git-cliff --tool tea
+python -m devx.tools.install_tools --list
+
+# Install checkmake (Makefile linter)
+python -m devx.tools.install_checkmake

 # Check unit test speed
 python -m devx.tools.check_test_speed --max-seconds 10
+python -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5

 # Configure repository (branch protection, labels)
-python -m devx.tools.configure_repo
+python -m devx.tools.configure_repo --repo devx --owner oblachno-oss
+
+# Generate badge SVG files locally
+python -m devx.tools.generate_badges --output-dir .badges/
+
+# Generate a cliff.toml with the correct task ID prefix
+python -m devx.tools.generate_cliff_config --prefix GRM
+python -m devx.tools.generate_cliff_config --prefix GRM --force  # overwrite existing
 ```

-### CLI
+### Molecule testing (optional)

-devx also provides a `devx` CLI command:
+For projects with Ansible roles, devx provides molecule testing helpers via
+`python -m devx.molecule.*` or `devx molecule <command>`.
+
+```bash
+# Distribute molecule scenarios across parallel runners
+python -m devx.molecule.distribute_molecule --runner-index 1 --max-runners 3
+python -m devx.molecule.distribute_molecule --list              # list all scenarios
+python -m devx.molecule.distribute_molecule --list-platforms    # list platforms
+
+# Run molecule tests with cross-runner fail-fast
+python -m devx.molecule.molecule_ci_guard pair1 pair2
+python -m devx.molecule.molecule_ci_guard --roles-root ansible/roles pair1 pair2
+
+# Run all molecule scenarios locally (sequential)
+python -m devx.molecule.molecule_all
+python -m devx.molecule.molecule_all --bin .venv/bin
+
+# Discover available Gitea Actions runners for molecule tests
+python -m devx.molecule.discover_runners --indices
+
+# Ensure Docker is available for molecule tests in CI
+python -m devx.molecule.start_docker
+```
+
+### OpenTofu helpers
+
+devx provides reusable functions for extracting values from `tofu output`:
+
+```python
+from devx.opentofu import get_tofu_output, get_tofu_vm_ip, get_tofu_vm_field
+
+vms = get_tofu_output("customer_vms", cwd="tofu/environments/staging",
+                      env={"HCLOUD_TOKEN": token})
+ip = get_tofu_vm_ip("customer_vms", "oblachno", cwd="tofu/environments/staging",
+                    env={"HCLOUD_TOKEN": token})
+```
+
+## CLI commands overview
+
+devx provides a `devx` CLI command with three command groups:

 ```bash
 devx --help
 devx --version
 ```

-### Configuration
+### `devx ci` — CI/CD automation

-devx reads configuration from environment variables with `.env` file fallback:
+| Command | Description |
+|---------|-------------|
+| `devx ci auto-merge` | Squash-merge a PR with task ID validation |
+| `devx ci check-translations` | Check translation files for gaps and dead keys |
+| `devx ci classify-changes` | Classify git changes as user-facing or workflow-only |
+| `devx ci detect-release-commit` | Detect whether the latest commit is a release commit |
+| `devx ci discover-runners` | Discover available Gitea Actions runners |
+| `devx ci distribute-files` | Distribute files across parallel runners (round-robin) |
+| `devx ci doc-coverage` | Check documentation coverage for CLI commands and modules |
+| `devx ci integration-guard` | Run pytest with cross-runner fail-fast |
+| `devx ci notify-failure` | Create a Gitea issue when a CI workflow fails |
+| `devx ci post-merge` | Update Vikunja task after a merge to master |
+| `devx ci pr-review` | Run automated PR review |
+| `devx ci publish` | Build package, publish to registry, create Gitea release |
+| `devx ci push-badges` | Generate badge SVG files and push to the badges branch |
+| `devx ci release` | Automated release: version, changelog, tag, push |
+| `devx ci sync-wiki` | Sync documentation from docs/ to the Gitea wiki |
+| `devx ci validate-commit-msg` | Validate commit messages for conventional format |
+
+### `devx tools` — Developer tools
+
+| Command | Description |
+|---------|-------------|
+| `devx tools check-test-speed` | Run unit tests and enforce execution-time budgets |
+| `devx tools configure-repo` | Configure branch protection and labels via Gitea API |
+| `devx tools generate-badges` | Generate self-contained SVG badge files |
+| `devx tools generate-cliff-config` | Generate a cliff.toml with the correct task ID prefix |
+| `devx tools install-checkmake` | Install checkmake (Makefile linter) |
+| `devx tools install-tools` | Install actionlint, git-cliff, act_runner, tea |
+| `devx tools setup` | Project setup: install deps, hooks, tea login |
+
+### `devx molecule` — Molecule testing (optional)
+
+| Command | Description |
+|---------|-------------|
+| `devx molecule all` | Run all molecule scenarios on all supported platforms |
+| `devx molecule discover-runners` | Discover available Gitea Actions runners |
+| `devx molecule distribute` | Distribute molecule test pairs across parallel runners |
+| `devx molecule guard` | Run molecule tests with CI failure polling |
+
+See [CLI Commands](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki/CLI-Commands)
+in the wiki for full command documentation with examples.
+
+## Configuration
+
+devx reads configuration from environment variables with `.env` file fallback.
+The config system loads `.env` automatically via `python-dotenv`.
+
+### DEVX_ environment variables

 | Variable | Default | Description |
 |----------|---------|-------------|
 | `DEVX_GITEA_API_URL` | `https://git.oblachno.oblachno.fyi/api/v1` | Gitea API base URL |
 | `DEVX_VIKUNJA_API_URL` | `https://work.oblachno.oblachno.fyi/api/v1` | Vikunja API base URL |
-| `DEVX_LANG` | `en` | Language (en, bg) |
-| `REPO_TOKEN` | — | Gitea API token |
+| `DEVX_REPO_OWNER` | **(none — must be set)** | Repository owner for API calls |
+| `DEVX_REPO_NAME` | **(none — must be set)** | Repository name (or `owner/repo`) |
+| `DEVX_TASK_PREFIX` | `DEVX` | Task ID prefix (GRM, OBL-INFRA, etc.) |
+| `DEVX_VIKUNJA_PROJECT_ID` | `6` | Vikunja project ID |
+| `DEVX_LANG` | `en` | Language for i18n (en, bg, de, ru, zh, pl) |
+| `DEVX_TRANSLATIONS_PATH` | — | Path to a custom JSON translations file |
+| `DEVX_VERSION_FILE` | `src/devx/__init__.py` | Version source file (used by release) |
+| `DEVX_DOCS_DIR` | `docs` | Documentation directory (used by sync_wiki) |
+| `DEVX_STATUS_CHECKS` | `CI / quality (pull_request)` | Comma-separated status check contexts |
+| `DEVX_PYPI_REGISTRY_URL` | — | Gitea PyPI registry URL (used by publish) |
+| `CI_GITEA_TOKEN` | — | Gitea API token (see scopes below) |
+| `CI_GITEA_USERNAME` | — | Gitea username for registry authentication |
 | `VIKUNJA_TOKEN` | — | Vikunja API token |
+| `PYPI_TOKEN` | — | Standard PyPI token (takes precedence over Gitea registry) |

-Copy `.env.example` to `.env` and fill in your tokens:
+#### CI_GITEA_TOKEN scopes
+
+The `CI_GITEA_TOKEN` is a single Gitea Personal Access Token used across all
+workflows. It requires these scopes:
+
+| Scope | Purpose |
+|-------|---------|
+| `read:repository` | Read repos, PRs, issues, branches |
+| `write:repository` | Push commits, merge PRs, create tags/releases, create issues, set branch protection, push wiki |
+| `read:package` | Pull packages from Gitea PyPI registry, pull Docker images |
+| `write:package` | Publish packages to Gitea PyPI registry, push Docker images |
+| `read:organization` | Query org-level runners for molecule test distribution |
+
+### Per-project overrides
+
+Projects using devx can override the default API URLs and language by setting
+`DEVX_*` environment variables or entries in their `.env` file. Copy
+`.env.example` to `.env` and fill in your tokens:

 ```bash
 cp .env.example .env
 ```

+### Change classification
+
+Projects configure which file paths are infrastructure (no release needed) vs
+user-facing (release needed) in `pyproject.toml`:
+
+```toml
+[tool.devx.classify]
+# Merge with DEFAULT_INFRASTRUCTURE (CI workflows, tests, docs, config)
+# use_defaults = true   # (default)
+
+# Project-specific infrastructure paths (merged with defaults)
+infrastructure = []
+
+# Files that would default to user-facing but are actually infrastructure
+infrastructure_overrides = [
+    "src/myproject/__init__.py",  # only contains __version__
+]
+
+# Safety override for broad infrastructure patterns
+user_facing_overrides = []
+
+# Tag patterns for CI conditional execution (orthogonal to release impact)
+[tool.devx.classify.tags]
+# ansible = ["ansible/**"]
+```
+
 ## Development

 ```bash
@@ -122,10 +391,86 @@ cd devx
 make setup         # Create venv, install deps, hooks, CI tools
 make lint-all      # ruff + pyright + bandit + actionlint
 make pytest-cov    # Unit tests with 100% coverage
+make test-unit     # Unit tests without coverage
+make workflow-check  # Static + dry-run validation of workflow YAML
+make clean         # Remove caches, build artifacts, coverage data
 ```

-See [AGENTS.md](AGENTS.md) for full project conventions, PR workflow, and architecture details.
+`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** via `python -m devx.tools.install_tools`
+- **tea CLI login** via `python -m devx.tools.setup` (configures `tea login` from `.env`)
+
+### Make targets
+
+| Target | Description |
+|--------|-------------|
+| `make setup` | Full local development setup (venv, deps, hooks, CI tools) |
+| `make setup-ci` | Lean setup for CI jobs (pytest + lint + runtime deps) |
+| `make setup-quality` | Setup for quality job (lint + test deps, actionlint) |
+| `make setup-release` | Setup for release jobs (git-cliff, tea, lint tools) |
+| `make install-tools` | Install actionlint, git-cliff, act_runner, tea |
+| `make install-hooks` | Install git hooks (pre-commit, pre-push) |
+| `make lint` | ruff check + ruff format check + pyright + bandit |
+| `make lint-ruff` | ruff check only |
+| `make lint-format` | ruff format check only |
+| `make typecheck` | pyright only |
+| `make lint-bandit` | bandit security scan only |
+| `make lint-all` | lint + workflow-lint (actionlint) |
+| `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-dryrun` | act_runner exec --dryrun on all workflows |
+| `make workflow-check` | workflow-lint + workflow-dryrun |
+| `make clean` | Remove caches, build artifacts, coverage data |
+
+See [AGENTS.md](AGENTS.md) for full project conventions, PR workflow, and
+architecture details.
+
+## Architecture overview
+
+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)
+├── config.py            # Configuration system (DEVX_ env vars, .env loading)
+├── api_clients.py       # GiteaClient, VikunjaClient — HTTP API wrappers
+├── gitea_cli.py         # TeaCLI — wrapper around tea CLI with JSON parsing
+├── i18n.py              # Translation system (gettext-based, translations.json)
+├── exceptions.py        # Custom exception types (DevxError, APIError)
+├── opentofu.py          # OpenTofu output helpers
+├── translations.json    # Translation strings (en, bg, de, ru, zh, pl)
+├── ci/                  # CI/CD automation modules (run by workflows)
+├── tools/               # Developer tooling modules (run locally or by CI)
+└── molecule/            # Optional molecule testing helpers (for Ansible projects)
+```
+
+### Design principles
+
+- **Self-contained package** — `src/devx/` never imports from scripts outside the package
+- **Module-based invocation** — All tools invoked via `python -m devx.ci.*` or `python -m devx.tools.*`
+- **PYTHONPATH: src** — Workflows set `PYTHONPATH: src` (not `.:src` since there are no scripts at repo root)
+- **Config via env vars** — `DEVX_*` environment variables with `.env` file fallback
+- **100% test coverage** — enforced by `--cov-fail-under=100`
+- **i18n by default** — all user-facing strings wrapped in `_()` for translation
+
+See [Architecture](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki/Architecture)
+and [CI/CD Workflow](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki/CI-CD-Workflow)
+in the wiki for detailed documentation.
+
+## Links
+
+- **Wiki**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+- **Releases**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+- **Actions**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+- **Source**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx](https://git.oblachno.oblachno.fyi/oblachno-oss/devx)
+- **GRM (origin project)**: [https://git.oblachno.oblachno.fyi/oblachno-oss/grm](https://git.oblachno.oblachno.fyi/oblachno-oss/grm)

 ## License

-GPL-3.0
+GPL-3.0 — see [LICENSE](LICENSE).
@@ -0,0 +1,26 @@
+# ci-base — lightweight image for CI jobs that only need devx core + tea.
+#
+# Used by: detect-type, detect-changes, validate-commit-msg, pr-review,
+#          auto-merge, sync-wiki, vikunja, configure-repo, discover-runners,
+#          molecule-report, discover-integration-runners
+#
+# Jobs using this image: setup is instant (ln -s /opt/venv .venv)
+# No pip install needed — devx and all deps are pre-installed.
+
+FROM gitea/runner-images:ubuntu-latest
+
+# Create a virtual environment with all deps pre-installed
+RUN python3 -m venv /opt/venv
+ENV PATH="/opt/venv/bin:/root/.local/bin:$PATH"
+
+# Install devx from local source (build context = devx repo root)
+COPY . /tmp/devx
+RUN pip install --no-cache-dir --upgrade pip setuptools wheel \
+    && pip install --no-cache-dir /tmp/devx[ci] \
+    && rm -rf /tmp/devx
+
+# Install tea CLI (for Gitea API operations in CI)
+RUN python3 -m devx.tools.install_tools --tool tea
+
+# Workspace directory (actions/checkout mounts repo here)
+WORKDIR /workspace
@@ -0,0 +1,30 @@
+# ci-full — heaviest image, includes everything for release, molecule, deploy.
+#
+# Used by: release, publish, release-dry-run, molecule-tests,
+#          provision-infra, deploy-observability, provision-zitadel,
+#          deploy-customer, integration-tests
+#
+# Layers on top of ci-quality: adds release tools, molecule, deploy deps,
+# git-cliff, and OpenTofu.
+
+FROM git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest
+
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+
+# Install rsync (required by molecule_docker for file sync between host and test containers)
+RUN apt-get update && apt-get install -y --no-install-recommends rsync \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install devx[release,molecule,deploy] from local source
+COPY . /tmp/devx
+RUN pip install --no-cache-dir /tmp/devx[release,molecule,deploy] \
+    && rm -rf /tmp/devx
+
+# Install git-cliff (changelog generator for release job)
+RUN python3 -m devx.tools.install_tools --tool git-cliff
+
+# Install OpenTofu (for infra deploy jobs)
+RUN ARCH=$(uname -m | sed 's/x86_64/amd64/') \
+    && VERSION=1.12.3 \
+    && curl -fsSL "https://github.com/opentofu/opentofu/releases/download/v${VERSION}/tofu_${VERSION}_$(uname -s | tr '[:upper:]' '[:lower:]')_${ARCH}.tar.gz" \
+    | tar -xz -C /usr/local/bin tofu
@@ -0,0 +1,22 @@
+# ci-quality — image for lint, type-checking, badge generation.
+#
+# Used by: quality (lint-all + pytest-cov + checks), badges (generate_badges
+#          runs ruff/pyright/bandit to produce quality badge)
+#
+# Layers on top of ci-base: adds lint tools + actionlint + checkmake.
+
+FROM git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
+
+# Install devx[lint] from local source (adds ruff, pyright, bandit, etc.)
+COPY . /tmp/devx
+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 --tool vale \
+    && python3 -m devx.tools.install_checkmake
+
+# Install hadolint (Dockerfile linter)
+RUN curl -fsSL "https://github.com/hadolint/hadolint/releases/download/v2.12.0/hadolint-Linux-x86_64" \
+    -o /usr/local/bin/hadolint \
+    && chmod +x /usr/local/bin/hadolint
@@ -0,0 +1,20 @@
+[
+  {
+    "name": "oblachno-oss/runner-images/ci-base",
+    "dockerfile": "docker/ci-base/Dockerfile",
+    "context": ".",
+    "tags": ["latest"]
+  },
+  {
+    "name": "oblachno-oss/runner-images/ci-quality",
+    "dockerfile": "docker/ci-quality/Dockerfile",
+    "context": ".",
+    "tags": ["latest"]
+  },
+  {
+    "name": "oblachno-oss/runner-images/ci-full",
+    "dockerfile": "docker/ci-full/Dockerfile",
+    "context": ".",
+    "tags": ["latest"]
+  }
+]
@@ -1,24 +1,175 @@
 # devx — Reusable Development & CI/CD Tools

-A Python package providing reusable development and CI/CD automation tools for oblachno-oss projects.
+A Python package providing reusable development and CI/CD automation tools for
+oblachno-oss projects. devx consolidates release management, PR automation,
+wiki sync, badge generation, translation checks, documentation coverage,
+parallel test distribution, and more into a single installable package.
+
+It was extracted from the [GRM](https://git.oblachno.oblachno.fyi/oblachno-oss/grm)
+project to be reusable across all oblachno-oss repositories.
+
+> An open-source project from **Oblachno** (облачно means *cloudy* in Bulgarian).
+
+[![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/40fbd801952eefafe3876bef53a09d217267f810/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/40fbd801952eefafe3876bef53a09d217267f810/python.svg)](https://www.python.org/downloads/)

 ## Overview

-devx consolidates release management, PR automation, wiki sync, badge generation, translation checks, and more into a single installable package. It was extracted from the [GRM](https://git.oblachno.oblachno.fyi/oblachno-oss/grm) project to be reusable across all oblachno-oss projects.
+devx provides a complete, opinionated CI/CD pipeline for any project hosted on
+a Gitea instance with Gitea Actions. Install the package, declare configuration
+via environment variables and `pyproject.toml`, and inherit:
+
+- **Automated releases** — git-cliff-driven semver versioning, changelog
+  generation, tagging, and publishing to a Gitea PyPI registry.
+- **PR automation** — squash-merge with task ID validation, automated PR
+  review with inline comments, and conventional commit enforcement.
+- **Smart change classification** — user-facing vs workflow-only change
+  detection so infrastructure-only changes skip releases.
+- **Documentation sync** — push `docs/` markdown to the Gitea wiki with
+  integrity verification.
+- **Quality badges** — self-contained SVG badges for coverage, tests, docs,
+  quality, version, and Python version.
+- **Translation checks** — validate i18n keys against source code, detect
+  dead keys and missing languages.
+- **Parallel test distribution** — split test files or molecule scenarios
+  across CI runners with cross-runner fail-fast.
+- **Developer tools** — environment setup, CI tool installation, test speed
+  enforcement, repository configuration.
+- **i18n** — built-in translations for English, Bulgarian, German, Russian,
+  Chinese, and Polish; projects can extend with their own keys.

 ## Installation

-Install from the Gitea PyPI registry:
+devx is published to the Gitea PyPI registry at
+`https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple`.
+The registry is publicly readable — no authentication required to install.
+
+### Quick install (one-off)

 ```bash
 pip install devx --index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
 ```

+### Persistent configuration (recommended)
+
+Add the registry to `~/.pip/pip.conf`:
+
+```ini
+[global]
+extra-index-url = https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
+```
+
+Then `pip install devx` works without specifying `--index-url`.
+
+### As a dependency in another project
+
+Add devx to your `pyproject.toml` dependencies and configure the registry:
+
+```toml
+[project]
+dependencies = [
+    "devx>=0.36.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.36.0"` or `"devx>=0.36.0,<0.37"`.
+
+### Optional extras
+
+```bash
+pip install "devx[ci,lint]"      # CI runners and linting (pytest, ruff, pyright, bandit, build, twine)
+pip install "devx[molecule]"     # Molecule testing for Ansible projects
+pip install "devx[dev]"          # Full local development (ci + lint + build + twine)
+```
+
 ## Architecture

- **Core modules** — config, exceptions, i18n, api_clients, gitea_cli
- **CI automation** (`devx.ci`) — release, publish, auto_merge, pr_review, classify_changes, etc.
- **Dev tools** (`devx.tools`) — setup, install_tools, check_test_speed, configure_repo, generate_badges
- **Molecule tools** (`devx.molecule`) — Optional, for projects with Ansible roles
+devx is a self-contained Python package under `src/devx/`:

-See [AGENTS.md](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/AGENTS.md) for full project conventions.
+- **Core modules** — `config.py`, `exceptions.py`, `i18n.py`, `api_clients.py`,
+  `gitea_cli.py`, `cli.py`, `opentofu.py`
+- **CI automation** (`devx.ci`) — release, publish, auto_merge, pr_review,
+  classify_changes, sync_wiki, push_badges, check_translations, doc_coverage,
+  validate_commit_msg, detect_release_commit, notify_failure, post_merge,
+  discover_runners, distribute_files, integration_guard
+- **Dev tools** (`devx.tools`) — setup, install_tools, check_test_speed,
+  configure_repo, generate_badges, generate_cliff_config, install_checkmake
+- **Molecule tools** (`devx.molecule`) — Optional, for projects with Ansible
+  roles: distribute_molecule, molecule_ci_guard, molecule_all, discover_runners,
+  start_docker, platforms
+
+See [Architecture](Architecture) for the full package structure, module
+descriptions, design principles, and data flow diagrams.
+
+## CI/CD pipeline
+
+devx uses Gitea Actions with three workflows:
+
+- **CI** (`ci.yml`) — runs on pull requests: quality checks, change detection,
+  release dry-run, automated PR review, and auto-merge.
+- **Post-merge** (`post-merge.yml`) — runs on every push to master: release
+  versioning, wiki sync, badge generation, Vikunja task updates, and repo
+  configuration.
+- **Publish** (`publish.yml`) — runs on tag pushes: builds the package,
+  publishes to the Gitea PyPI registry, and creates a Gitea release.
+
+See [CI/CD Workflow](CI-CD-Workflow) for the full pipeline documentation,
+including the post-merge job graph, release process, badge generation, and
+wiki sync details.
+
+## CLI commands
+
+devx provides a `devx` CLI with three command groups:
+
+- `devx ci <command>` — CI/CD automation (17 commands)
+- `devx tools <command>` — Developer tools (9 commands)
+- `devx molecule <command>` — Molecule testing (4 commands, optional)
+
+See [CLI Commands](CLI-Commands) for full command documentation with examples.
+
+## Configuration
+
+devx reads configuration from `DEVX_*` environment variables with `.env` file
+fallback. Key variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEVX_GITEA_API_URL` | `https://git.oblachno.oblachno.fyi/api/v1` | Gitea API base URL |
+| `DEVX_VIKUNJA_API_URL` | `https://work.oblachno.oblachno.fyi/api/v1` | Vikunja API base URL |
+| `DEVX_REPO_OWNER` | **(must be set)** | Repository owner |
+| `DEVX_REPO_NAME` | **(must be set)** | Repository name |
+| `DEVX_TASK_PREFIX` | `DEVX` | Task ID prefix (GRM, OBL-INFRA, etc.) |
+| `DEVX_LANG` | `en` | Language for i18n (en, bg, de, ru, zh, pl) |
+| `CI_GITEA_TOKEN` | — | Gitea API token |
+| `VIKUNJA_TOKEN` | — | Vikunja API token |
+
+See [AGENTS.md](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/AGENTS.md)
+for the full configuration reference, PR workflow, and project conventions.
+
+## Wiki pages
+
+- [Home](Home) — This page
+- [Getting Started](Getting-Started) — Installation, configuration, and quick start guide
+- [CLI Commands](CLI-Commands) — Full CLI command documentation with examples
+- [Architecture](Architecture) — Package structure, module descriptions, design principles
+- [CI/CD Workflow](CI-CD-Workflow) — Pipeline documentation, workflows, and CI scripts
+
+## Links
+
+- **Source**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx](https://git.oblachno.oblachno.fyi/oblachno-oss/devx)
+- **Releases**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+- **Actions**: [https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+- **GRM (origin project)**: [https://git.oblachno.oblachno.fyi/oblachno-oss/grm](https://git.oblachno.oblachno.fyi/oblachno-oss/grm)
+
+## License
+
+GPL-3.0
@@ -1,5 +1,6 @@
 {
  "index.md": "Home",
+  "user/getting-started.md": "Getting-Started",
  "user/cli-commands.md": "CLI-Commands",
  "tech/architecture.md": "Architecture",
  "tech/ci-cd-workflow.md": "CI-CD-Workflow"
@@ -1,50 +1,585 @@
 # Architecture

-devx is a reusable Python package providing development and CI/CD tools for oblachno-oss projects.
+devx is a reusable Python package providing development and CI/CD tools for
+oblachno-oss projects. It is self-contained under `src/devx/` and never imports
+from scripts outside the package.

-## Package Structure
+## Package structure

-```
+```text
 src/devx/
-├── __init__.py          # Version (single source of truth)
-├── cli.py               # Click-based CLI entry point (devx command)
-├── config.py            # Configuration system (DEVX_ env vars)
-├── api_clients.py       # GiteaClient, VikunjaClient — HTTP API wrappers
-├── gitea_cli.py         # TeaCLI — wrapper around tea CLI with JSON parsing
-├── i18n.py              # Translation system (gettext-based, translations.json)
-├── exceptions.py        # Custom exception types (DevxError, APIError)
-├── translations.json    # Translation strings (en, bg, de, ru, zh)
-├── ci/                  # CI/CD automation modules
-├── tools/               # Developer tooling modules
-└── molecule/            # Optional molecule testing helpers
+├── __init__.py              # Version (single source of truth, read by setuptools)
+├── cli.py                   # Click-based CLI entry point (devx command)
+├── config.py                # Configuration system (DEVX_ env vars, .env loading)
+├── api_clients.py           # GiteaClient, VikunjaClient — HTTP API wrappers
+├── gitea_cli.py             # TeaCLI — wrapper around tea CLI with JSON parsing
+├── i18n.py                  # Translation system (JSON-based, translations.json)
+├── exceptions.py            # Custom exception types (DevxError, APIError)
+├── opentofu.py              # OpenTofu output helpers
+├── translations.json        # Translation strings (en, bg, de, ru, zh, pl)
+├── ci/                      # CI/CD automation modules (run by workflows)
+│   ├── __init__.py
+│   ├── _shared.py           # Shared utilities (get_latest_tag)
+│   ├── release.py           # Automated versioning, tagging, changelog
+│   ├── publish.py           # Build and publish to Gitea PyPI registry
+│   ├── auto_merge.py        # Squash-merge PRs with task ID validation
+│   ├── classify_changes.py  # User-facing vs workflow-only change detection
+│   ├── detect_release_commit.py  # Detect release commits on master
+│   ├── validate_commit_msg.py    # Conventional commit validation
+│   ├── pr_review.py         # Automated PR review
+│   ├── post_merge.py        # Vikunja task updates after merge
+│   ├── sync_wiki.py         # Sync documentation to Gitea wiki
+│   ├── push_badges.py       # Generate and push quality badges
+│   ├── notify_failure.py    # Create Gitea issues on CI failures
+│   ├── distribute_files.py  # Distribute files across parallel runners
+│   ├── integration_guard.py # Run pytest with cross-runner fail-fast
+│   ├── discover_runners.py  # Dynamic Gitea runner discovery
+│   ├── check_translations.py  # Translation completeness check
+│   └── doc_coverage.py      # Documentation coverage check
+├── tools/                   # Developer tooling modules (run locally or by CI)
+│   ├── __init__.py
+│   ├── setup.py             # Environment setup (venv, deps, hooks, tea login)
+│   ├── install_tools.py     # Install actionlint, git-cliff, act_runner, tea
+│   ├── check_test_speed.py  # Measure unit test execution time
+│   ├── configure_repo.py    # Branch protection and label setup
+│   ├── generate_badges.py   # Badge SVG generation
+│   ├── generate_cliff_config.py  # Generate cliff.toml with correct prefix
+│   └── install_checkmake.py # Install checkmake (Makefile linter)
+└── molecule/                # Optional molecule testing helpers (Ansible projects)
+    ├── __init__.py
+    ├── discover_runners.py      # Dynamic Gitea runner discovery
+    ├── distribute_molecule.py   # Distribute scenarios across runners
+    ├── molecule_ci_guard.py     # Run molecule with cross-runner fail-fast
+    ├── molecule_all.py          # Run all molecule scenarios locally
+    ├── start_docker.py          # Ensure Docker is available for molecule
+    └── platforms.py             # Supported molecule platforms
 ```

-## Core Modules
+## Core modules

-### cli.py
+### `__init__.py`

-Click-based CLI entry point. Provides three command groups: `devx ci`, `devx tools`, `devx molecule`. Each subcommand delegates to the corresponding module via `_run_module()`.
+Contains only `__version__`, the single source of truth for the package
+version. Read by setuptools via `dynamic = ["version"]` in `pyproject.toml`.
+Updated automatically by `devx.ci.release` during the release process. Treated
+as infrastructure (not user-facing) by the change classifier since it is a
+release artifact, not user code.

-### i18n.py
+### `cli.py`

-Simple i18n system using a JSON translations file. Supports en, bg, de, ru, zh. Projects can extend translations by setting `DEVX_TRANSLATIONS_PATH` to a custom JSON file.
+Click-based CLI entry point. Provides three command groups: `devx ci`,
+`devx tools`, and `devx molecule`. Each subcommand delegates to the
+corresponding module via `_run_module()`, which imports the module, sets
+`sys.argv`, and calls its `main()` function. This design keeps all logic in
+the modules themselves — `cli.py` is purely a router.

-### exceptions.py
+The CLI is registered as a console script via `pyproject.toml`:
+```toml
+[project.scripts]
+devx = "devx.cli:cli"
+```

-Custom exception hierarchy: `DevxError` (base), `APIError` (HTTP errors with status code and message).
+### `config.py`

-### api_clients.py
+Shared configuration constants for all devx modules. All defaults can be
+overridden via environment variables with the `DEVX_` prefix. Provides:

-HTTP API clients with connection pooling and retry logic:
- `GiteaClient` — Gitea REST API (branch protection, labels, issues, PRs, releases, reviews)
- `VikunjaClient` — Vikunja REST API (tasks, projects, comments)
+- `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 (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
+- `CONVENTIONAL_RE` — conventional commit format regex

-Both clients retry on transient errors (429, 5xx, connection errors) with exponential backoff.
+### `exceptions.py`

-### config.py
+Custom exception hierarchy:

-Configuration constants with env-var overrides (`DEVX_` prefix). Includes API URLs, timeouts, retry settings, task prefix regex, and conventional commit regex.
+- `DevxError` — base exception for all devx errors
+- `APIError(DevxError)` — raised when a REST API call returns an HTTP error.
+  Carries `status` (HTTP status code) and `message` (error message).

-### gitea_cli.py
+### `i18n.py`

-Python wrapper around the `tea` Gitea CLI tool. Parses JSON output for structured data. Used by CI scripts for Gitea API operations (issues, labels, PRs, releases, reviews).
+Simple i18n system using a JSON translations file (`translations.json`).
+Supports six languages: `en`, `bg`, `de`, `pl`, `ru`, `zh`. The `_()` function
+wraps user-facing strings for translation.
+
+Projects can extend translations by setting `DEVX_TRANSLATIONS_PATH` to a
+custom JSON file. Keys from the project's file are merged on top of devx's
+built-in translations, allowing projects to override or add keys without
+modifying the package.
+
+### `api_clients.py`
+
+Reusable HTTP API clients with connection pooling and retry logic. Both
+clients retry on transient errors (429, 5xx, connection errors) with
+exponential backoff (2s, 4s, 8s).
+
+**`GiteaClient`** — Gitea REST API wrapper:
+- Branch protection (get, create, update)
+- Labels (list, create, add to issues)
+- Issues (create, list)
+- Pull requests (get commits, merge, create review)
+- 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:
+- Tasks (list project tasks, get, update, mark done)
+- Comments (create)
+
+### `gitea_cli.py`
+
+Thin Python wrapper around the `tea` Gitea CLI tool. Parses JSON output for
+structured data. Used by CI scripts for Gitea API operations that tea handles
+well, avoiding hand-rolled HTTP requests.
+
+**`TeaCLI`** operations:
+- `create_issue()` — Create issues with labels
+- `list_labels()` / `create_label()` / `add_label()` — Label management
+- `create_pr()` / `merge_pr()` / `review_pr()` — Pull request operations
+- `create_release()` / `list_releases()` — Release management
+- `list_branches()` — Branch listing
+
+Operations NOT supported via tea (still use `GiteaClient`):
+- Wiki page management
+- Commit status checks
+- Runner discovery
+- PR file/commit listing (tea has limited support)
+- Branch protection with detailed config
+
+### `opentofu.py`
+
+OpenTofu output helpers for CI/CD deployment scripts. Provides reusable
+functions for extracting values from `tofu output` in a structured way,
+eliminating duplicated `subprocess.run` boilerplate:
+
+- `get_tofu_output(output_name, cwd, env)` — Run `tofu output -json` and return parsed JSON
+- `get_tofu_vm_ip(output_name, vm_name, cwd, env)` — Extract a VM's IP address
+- `get_tofu_vm_field(output_name, vm_name, field, cwd, env)` — Extract a VM field
+
+## CI/CD modules (`devx.ci`)
+
+Modules in this package are run by Gitea Actions workflows. They may import
+from `devx.api_clients`, `devx.config`, `devx.gitea_cli`, and `devx.i18n`.
+
+### `release.py`
+
+Automated release using git-cliff. Calculates the next semver version from
+conventional commits since the last tag, updates `__version__` in
+`__init__.py` and `CHANGELOG.md`, runs lint and tests to verify the release
+is healthy, commits with `release: vX.Y.Z [skip ci]`, creates an annotated
+tag, and pushes both to master.
+
+Idempotent: if there are no new conventional commits since the last tag, it
+exits without doing anything. If the tag already exists, it skips tag creation
+and only pushes. Includes a `--verify` mode that checks tag/version/changelog
+alignment without making changes.
+
+### `publish.py`
+
+Builds the Python package with `python -m build`, publishes to a Gitea PyPI
+registry (or standard PyPI if `PYPI_TOKEN` is set), and creates a Gitea
+release with git-cliff-generated notes. Supports `--skip-build` for non-Python
+repos that only need a Gitea release.
+
+### `auto_merge.py`
+
+Auto-merges a PR when all CI checks pass. Reads the task ID from the branch
+name, validates the PR title format against
+the Vikunja task title, extracts the conventional commit message from PR
+commits, and squash-merges with title `{PREFIX}-N <conventional commit>`.
+
+If the head branch is behind master (HTTP 405), it automatically pulls master,
+rebases, force-pushes, and retries the merge.
+
+### `classify_changes.py`
+
+Classifies git changes between two refs as user-facing or workflow-only. Uses
+a layered rule system configured in `pyproject.toml` under
+`[tool.devx.classify]`:
+
+1. **User-facing overrides** (highest priority — safety override)
+2. **Infrastructure overrides** (explicit per-file)
+3. **Infrastructure patterns** (DEFAULT_INFRASTRUCTURE + project-specific)
+4. **Default**: user-facing (safe default — any unknown file triggers release)
+
+Also supports custom tags (orthogonal to release impact) for CI conditional
+execution (for example, `ansible` tag to trigger molecule tests).
+
+### `pr_review.py`
+
+Automated PR review. Fetches the PR diff via the Gitea API and runs a series
+of checks, posting a structured review with `COMMENT` (no issues) or
+`REQUEST_CHANGES` (issues found):
+
+- Architecture compliance (no subprocess in CLI, no hardcoded URLs)
+- Best practices (no `print()`, no bare `except`, no `TODO`/`FIXME`, no
+  functions > 50 lines)
+- Security (no hardcoded secrets, no `shell=True`, no `eval`/`exec`)
+- i18n (no raw strings in `click.echo()` without `_()` wrapper)
+- Resource management (no `open()` without `with`, no `Popen()` without cleanup)
+- Documentation (source changes must include doc updates)
+- Test coverage (source changes must include test updates)
+- Commit conventions (conventional commit format on PR commits)
+
+### `sync_wiki.py`
+
+Syncs documentation from `docs/` to the Gitea wiki via the API. Reads
+`docs/mapping.json` to map file paths to wiki page titles, then creates or
+updates pages. Supports `--dry-run`, `--verify` (check content), and
+`--strict` (full integrity check: page count, missing pages, stale pages,
+content match).
+
+### `push_badges.py`
+
+Generates SVG badge files using `devx.tools.generate_badges`, pushes them to
+an orphan `badges` branch, and updates `README.md` and `docs/index.md` on
+master with cache-busting `raw/commit/<sha>/badge.svg` URLs (Gitea caches
+`raw/branch/` URLs for 6 hours). Fetches latest master before generating
+badges so the version badge reflects the current state. Supports `--retries`
+for retrying on git push failures.
+
+### `notify_failure.py`
+
+Creates a Gitea issue when a CI workflow fails. Uses the `tea` CLI for issue
+creation with failure labels. Supports `--auto-login` to configure the tea
+CLI login profile from `CI_GITEA_TOKEN` and `DEVX_GITEA_API_URL` before creating
+the issue.
+
+### `post_merge.py`
+
+Updates the Vikunja task after a merge to master. Extracts the task ID from
+the commit message, marks the task as done, and posts a comment with the
+merge SHA.
+
+### `validate_commit_msg.py`
+
+Validates commit messages. On feature branches: conventional commits only
+(no `{PREFIX}-N` prefix). On master: must have `{PREFIX}-N` prefix from
+auto-merge, followed by a conventional commit message.
+
+### `detect_release_commit.py`
+
+Detects whether the latest git commit is a release commit
+(`release: vX.Y.Z [skip ci]`). Writes `is-release=true` or `is-release=false`
+to `$GITHUB_OUTPUT` for use in CI workflow conditionals.
+
+### `check_translations.py`
+
+Validates translation files against the Python source code. Checks for
+missing keys (used in code but not in translations), dead keys (defined but
+not used), and missing languages (a key exists but is missing one of the five
+supported languages). Supports checking additional translation sets via
+`--translations`.
+
+### `doc_coverage.py`
+
+Checks documentation coverage for CLI commands and major modules. Parses
+Click commands from `cli.py` and verifies each has documentation in
+`docs/user/cli-commands.md`. Checks that core modules are documented in
+`architecture.md` and CI scripts in `ci-cd-workflow.md`. Supports
+`--fail-on-missing` to enforce 100% coverage.
+
+### `discover_runners.py`
+
+Discovers available Gitea Actions runners at three levels: repository,
+organization, and instance (admin). Falls back to the `MOLECULE_RUNNERS` repo
+variable or `DEFAULT_MAX_RUNNERS` (3). Outputs runner count or a JSON index
+array for use as a dynamic matrix in Gitea Actions.
+
+### `distribute_files.py`
+
+Distributes files matching a glob pattern across N parallel runners
+(round-robin). Writes the assigned file list for the current runner to
+`$GITHUB_ENV`. Used for splitting test suites across CI runners.
+
+### `integration_guard.py`
+
+Runs pytest with the same cross-runner failure detection mechanism used by
+`molecule_ci_guard`. If any other integration-tests matrix runner reports
+failure, the current pytest subprocess is killed and this runner exits early.
+
+## Developer tools (`devx.tools`)
+
+Modules in this package are run locally or by CI setup jobs. They may import
+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
+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
+configuration.
+
+### `install_tools.py`
+
+Installs CI/CD development tools that are not Python packages: actionlint,
+git-cliff, act_runner, and tea. Each tool is installed to `~/.local/bin` if
+not already on PATH. Idempotent: skips tools that are already available.
+Supports `--tool` to install specific tools and `--list` to show status.
+
+### `check_test_speed.py`
+
+Runs unit tests and enforces execution-time budgets. Two quality gates:
+total suite time must not exceed `--max-seconds` (default: 10s), and no
+individual test may exceed `--max-single-seconds` (default: 0.5s, 0 to
+disable). Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0`.
+
+### `configure_repo.py`
+
+Configures repository branch protection and labels via the Gitea REST API.
+Sets up master branch protection (required status checks, block on rejected
+reviews, block on outdated branch) and creates standard labels. Status check
+contexts are read from `DEVX_STATUS_CHECKS` or default to
+`CI / quality (pull_request)`.
+
+### `generate_badges.py`
+
+Generates self-contained SVG badge files from project metrics. Runs
+pytest-cov, doc-coverage, lint checks, and version extraction, then writes
+SVG files that can be served as static files from the Gitea raw file API.
+Badges generated: coverage, tests, docs, quality, version, python.
+
+### `generate_cliff_config.py`
+
+Generates a `cliff.toml` configuration file with the correct task ID prefix
+preprocessor. Eliminates the need to manually duplicate and maintain
+`cliff.toml` across repos that use devx. Supports `--prefix` to set the task
+ID prefix and `--force` to overwrite an existing file.
+
+### `install_checkmake.py`
+
+Installs checkmake (Makefile linter) if not already present. Tries
+`go install` first if Go is available, otherwise downloads the latest
+pre-built Linux binary from the official GitHub releases.
+
+## Molecule modules (`devx.molecule`)
+
+Optional modules for projects with Ansible roles. Requires the `molecule`
+extra (`pip install devx[molecule]`).
+
+### `distribute_molecule.py`
+
+Distributes molecule (scenario, platform) pairs across N parallel runners.
+Discovers scenarios under `ansible/roles/*/molecule/` and crosses them with
+the supported OS platform matrix. Supports `--roles-root` for multi-role
+repositories, `--list` to list scenarios, and `--list-platforms` to list
+platforms.
+
+### `molecule_ci_guard.py`
+
+Runs molecule tests sequentially while polling the Gitea API for other runner
+failures. If any other molecule matrix runner reports failure, the current
+molecule subprocess is killed and this runner exits early. Supports both
+single-role (4-part) and multi-role (5-part) pair encoding.
+
+### `molecule_all.py`
+
+Runs all molecule scenarios on all supported OS platforms sequentially.
+Intended for local development; CI uses the parallel matrix instead.
+
+### `molecule/discover_runners.py`
+
+Discovers available Gitea Actions runners for molecule tests. Same logic as
+`devx.ci.discover_runners` but intended for molecule-specific workflows.
+
+### `start_docker.py`
+
+Ensures Docker is available for molecule tests in CI. Verifies Docker is
+accessible and sets `DOCKER_HOST` explicitly. If the host socket is not
+available, tries the rootless socket, then starts a local `dockerd` with the
+vfs storage driver (requires privileged container).
+
+### `platforms.py`
+
+Single source of truth for the supported OS platform matrix. Each entry maps
+a short name to (image, command). Uses the project's pre-built
+molecule-test-base image with `sleep infinity` (not systemd) to avoid cgroup
+v2 failures. Supports loading custom platforms from a JSON file.
+
+## Design principles
+
+- **Self-contained package** — `src/devx/` never imports from scripts outside
+  the package. This allows devx to be installed and used as a dependency
+  without requiring a specific repo layout in the consumer.
+- **Module-based invocation** — All tools invoked via `python -m devx.ci.*`,
+  `python -m devx.tools.*`, or `python -m devx.molecule.*`. The `devx` CLI is
+  a thin router that delegates to module `main()` functions.
+- **PYTHONPATH: src** — Workflows set `PYTHONPATH: src` (not `.:src` since
+  there are no scripts at repo root). The `src` directory is the sole import
+  root.
+- **Config via env vars** — `DEVX_*` environment variables with `.env` file
+  fallback. Projects override defaults via environment or `.env`, never by
+  editing package code.
+- **100% test coverage** — enforced by `--cov-fail-under=100` in pytest.
+- **i18n by default** — all user-facing strings wrapped in `_()` for
+  translation. Five languages supported out of the box.
+- **Safe-by-default classification** — any file that doesn't match an
+  infrastructure pattern defaults to user-facing, triggering a release. This
+  prevents new file types from accidentally skipping releases.
+- **Secrets via environment** — secrets are passed via environment variables,
+  never on the command line.
+
+## Import rules
+
+1. **`src/devx/` is self-contained** — the package never imports from outside `src/`
+2. **CI modules** (`devx.ci.*`) may import from `devx.api_clients`,
+   `devx.config`, `devx.gitea_cli`, `devx.i18n`
+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 (for example, `release.py` imports from
+   `classify_changes.py`)
+
+## Data flow
+
+### PR lifecycle
+
+```text
+Developer creates Vikunja task (DEVX-N)
+    │
+    ▼
+Developer creates branch (DEVX-N-short-description)
+    │
+    ▼
+Developer commits (conventional commits, no DEVX-N prefix)
+    │
+    ▼
+Developer pushes and creates PR (title: "DEVX-N: <vikunja task title>")
+    │
+    ▼
+CI workflow (ci.yml) triggers:
+    │
+    ├── quality (lint, tests, coverage, test speed, doc coverage,
+    │            translation check, dependency scan, workflow dry-run)
+    │
+    ├── detect-changes (classify_changes.py → user-facing or workflow-only)
+    │       └── if user-facing → release-dry-run (release.py --dry-run)
+    │
+    ├── pr-review (pr_review.py → posts COMMENT or REQUEST_CHANGES)
+    │
+    └── auto-merge (auto_merge.py)
+            ├── validate PR title format
+            ├── validate PR title matches Vikunja task title
+            ├── extract conventional commit message from PR commits
+            ├── squash-merge with "DEVX-N <conventional commit>" title
+            └── push to master
+                    │
+                    ▼
+            Post-merge workflow triggers (see below)
+```
+
+### Post-merge flow
+
+```text
+Push to master (squash-merge commit: "DEVX-N <conventional commit>")
+    │
+    ▼
+Post-merge workflow (post-merge.yml) triggers:
+    │
+    ├── detect-type (detect_release_commit.py)
+    │       └── is-release? → skip all jobs except badges
+    │
+    ├── validate-commit-msg (validate_commit_msg.py --branch master)
+    │
+    ├── release (release.py)
+    │       ├── classify_changes.py → skip if workflow-only
+    │       ├── git-cliff → calculate next version
+    │       ├── update __version__ in __init__.py
+    │       ├── update CHANGELOG.md
+    │       ├── run make lint-ruff && make pytest-cov
+    │       ├── commit "release: vX.Y.Z [skip ci]"
+    │       ├── create annotated tag vX.Y.Z
+    │       └── push commit + tag to master
+    │               │
+    │               ▼
+    │       Tag push triggers publish workflow (see below)
+    │
+    ├── sync-wiki (sync_wiki.py --strict)
+    │       └── sync docs/ to Gitea wiki with integrity check
+    │
+    ├── badges (push_badges.py) [ALWAYS runs, even on release commits]
+    │       ├── fetch latest master
+    │       ├── generate_badges.py → SVG files
+    │       ├── push to orphan badges branch
+    │       └── update README.md + docs/index.md with cache-busting URLs
+    │
+    ├── vikunja (post_merge.py)
+    │       ├── extract task ID from commit message
+    │       ├── mark Vikunja task as done
+    │       └── post comment with merge SHA
+    │
+    └── configure-repo (configure_repo.py)
+            └── ensure branch protection and labels
+```
+
+### Publish flow
+
+```text
+Tag push (vX.Y.Z) triggers publish workflow (publish.yml):
+    │
+    ▼
+    ├── install build, twine, git-cliff, tea
+    ├── configure tea login
+    │
+    └── publish (publish.py)
+            ├── build package (python -m build)
+            ├── publish to Gitea PyPI registry (twine upload)
+            │   OR publish to standard PyPI (if PYPI_TOKEN set)
+            │   OR skip publish (if --skip-build)
+            └── create Gitea release with git-cliff notes
+```
+
+### Badge generation flow
+
+```text
+push_badges.py:
+    │
+    ├── fetch_latest_master() → git fetch + reset --hard origin/master
+    │
+    ├── generate_badges() → devx.tools.generate_badges
+    │       ├── run pytest-cov → parse coverage %
+    │       ├── run pytest → parse test count
+    │       ├── run doc_coverage → parse doc coverage %
+    │       ├── run lint → quality status
+    │       ├── read __version__ from __init__.py
+    │       └── write SVG files to .badges/
+    │
+    ├── push_to_badges_branch()
+    │       ├── git checkout --orphan badges
+    │       ├── git rm -rf .
+    │       ├── copy SVG files to root
+    │       ├── git commit "Update badges [skip ci]"
+    │       ├── git push origin badges --force
+    │       └── return commit SHA
+    │
+    └── update_readme_with_badge_sha()
+            ├── git checkout master
+            ├── replace raw/branch/badges/ URLs with raw/commit/<sha>/ URLs
+            ├── git commit "chore: update badge URLs [skip ci]"
+            └── git push origin master
+```
+
+## tea CLI integration
+
+The `tea` Gitea CLI tool is used for Gitea API interactions where tea provides
+reliable, official support. It is installed by
+`python -m devx.tools.install_tools` and configured by
+`python -m devx.tools.setup` (login profile from `.env` `CI_GITEA_TOKEN`).
+
+`devx.gitea_cli.TeaCLI` wraps tea with JSON output parsing. Operations that
+tea does not support (wiki management, commit status, runner discovery,
+detailed branch protection) fall back to `GiteaClient` (direct HTTP).
+
+## Version source
+
+The version source is `__version__` in `src/devx/__init__.py`, read by
+setuptools via `dynamic = ["version"]` in `pyproject.toml`. The release
+script updates this file, commits it, and tags the commit. This ensures the
+package version, git tag, and changelog always stay aligned.
@@ -1,85 +1,543 @@
 # CI/CD Workflow

-devx uses Gitea Actions for CI/CD automation. The workflow replicates GRM's automated pipeline but without molecule tests.
+devx uses Gitea Actions for CI/CD automation. Three workflows implement a
+complete pipeline: pull request validation, post-merge release automation, and
+tag-triggered publishing.

-## Workflows
+## Workflow overview

-### CI (`ci.yml`)
+```text
+PR opened/synchronized ──► CI (ci.yml)
+    │                         ├── quality
+    │                         ├── detect-changes
+    │                         ├── release-dry-run (if user-facing)
+    │                         ├── pr-review
+    │                         └── auto-merge ──► squash-merge to master
+    │                                              │
+    ▼                                              ▼
+Push to master ──► Post-merge (post-merge.yml)
+                     ├── detect-type
+                     ├── validate-commit-msg
+                     ├── release ──► tag vX.Y.Z
+                     ├── sync-wiki        │
+                     ├── badges           │
+                     ├── vikunja          │
+                     └── configure-repo   │
+                                          │
+                                          ▼
+Tag push (v*) ──► Publish (publish.yml)
+                     └── publish ──► Gitea PyPI registry + Gitea release
+```

-Runs on pull requests. Jobs:
+## CI workflow (`ci.yml`)

-1. **quality** — lint (ruff, pyright, bandit, actionlint), unit tests with 100% coverage, test speed check, doc coverage, translation check, dependency scan
-2. **detect-changes** — classify changes as user-facing or workflow-only
-3. **release-dry-run** — dry-run the release script (only if user-facing changes)
-4. **pr-review** — automated PR review
-5. **auto-merge** — squash-merge PR when all checks pass
+Runs on pull requests (opened and synchronize) and manual dispatch.

-### Post-merge (`post-merge.yml`)
+### Jobs

-Runs on every push to master. Jobs:
+#### `quality`

-1. **detect-type** — check if commit is a release commit
-2. **validate-commit-msg** — validate conventional commit format
-3. **release** — calculate next version, update changelog, tag, push
-4. **sync-wiki** — sync docs to Gitea wiki
-5. **badges** — generate and push quality badges
-6. **vikunja** — mark Vikunja task as done
-7. **configure-repo** — ensure branch protection and labels
+The main quality gate. Runs on every PR:

-### Publish (`publish.yml`)
+1. **Lint all** — ruff check, ruff format check, pyright, bandit, actionlint
+   (via `make lint-all`)
+2. **Unit tests with 100% coverage** — `make pytest-cov`
+3. **Check unit test speed** — `python -m devx.tools.check_test_speed
+   --max-seconds 4 --max-single-seconds 0.5`
+4. **Documentation coverage check** — `python -m devx.ci.doc_coverage
+   --fail-on-missing`
+5. **Translation completeness check** — `python -m devx.ci.check_translations`
+6. **Dependency security scan** — `pip-audit --desc --skip-editable`
+   (best-effort, non-blocking)
+7. **Workflow dry-run validation** — `make workflow-dryrun` via act_runner
+   (best-effort, skipped if act_runner is not installed)

-Runs on tag pushes (`v*`). Builds the package, publishes to Gitea PyPI registry, and creates a Gitea release.
+#### `detect-changes`

-## CI Scripts
+Classifies changes between `origin/master` and the PR head as user-facing or
+workflow-only using `python -m devx.ci.classify_changes --github-output`.
+Writes `user-facing-changed=true|false` to the job output for use by
+downstream jobs.

-### auto_merge.py
+#### `release-dry-run`

-Auto-merge PR when all CI checks pass. Reads task ID from `.taskid`, validates PR title format, checks Vikunja task exists, squash-merges with `DEVX-N <conventional commit>` title.
+Depends on `quality` and `detect-changes`. Only runs if user-facing changes
+are detected. Runs `python -m devx.ci.release --dry-run` to validate that
+the release script can calculate the next version and generate the changelog
+without making changes. Non-blocking (uses `|| true`).

-### release.py
+#### `pr-review`

-Automated release using git-cliff. Calculates next semver version from conventional commits, updates `__version__` in `__init__.py`, updates `CHANGELOG.md`, runs lint and tests, commits with `release: vX.Y.Z [skip ci]`, creates annotated tag, pushes.
+Runs on every pull request. Executes `python -m devx.ci.pr_review` with the
+PR number and repository. Fetches the PR diff via the Gitea API and runs
+automated checks, posting a structured review:

-### publish.py
+- `COMMENT` — no issues found
+- `REQUEST_CHANGES` — issues found that must be addressed

-Builds package with `python -m build`, publishes to Gitea PyPI registry via twine, creates Gitea release with git-cliff-generated notes.
+Checks performed:
+1. Architecture compliance — no subprocess in CLI, no hardcoded URLs
+2. Best practices — no `print()`, no bare `except`, no `TODO`/`FIXME`,
+   no functions > 50 lines
+3. Security — no hardcoded secrets, no `shell=True`, no `eval`/`exec`
+4. i18n — no raw strings in `click.echo()` without `_()` wrapper
+5. Resource management — no `open()` without `with`, no `Popen()` without
+   cleanup
+6. Documentation — source changes must include doc updates
+7. Test coverage — source changes must include test updates
+8. Commit conventions — conventional commit format on PR commits

-### pr_review.py
+#### `auto-merge`

-Automated PR review. Checks architecture compliance, best practices, security, i18n, resource management, documentation, test coverage, and commit conventions. Posts inline comments and structured review.
+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:

-### notify_failure.py
+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
+4. **Extract conventional commit message** from PR commits (newest matching
+   conventional format)
+5. **Squash-merge** with title `{PREFIX}-N <conventional commit message>`
+6. If the head branch is behind master (HTTP 405), automatically pulls master,
+   rebases, force-pushes, and retries the merge

-Creates a Gitea issue when a CI workflow fails. Uses tea CLI for issue creation with failure labels.
+The merge commit push to master triggers the post-merge workflow.

-### post_merge.py
+### Smart CI: user-facing vs workflow-only changes

-Updates Vikunja task after a merge to master. Extracts task ID from commit message, marks task as done, posts a comment with the merge SHA.
+Not all changes require a new release. The `detect-changes` job classifies
+changes using `python -m devx.ci.classify_changes`:

-### classify_changes.py
+**Workflow-only paths** (infrastructure — no release needed):
+- `.gitea/**` — Gitea Actions workflows
+- `tests/**` — Test files
+- `AGENTS.md`, `README.md`, `CHANGELOG.md` — Project docs
+- `Makefile`, `cliff.toml`, `.pre-commit-config.yaml` — Config
+- `.env.example`, `.gitignore` — Config
+- `hooks/**` — Git hooks
+- `src/devx/__init__.py` — Only contains `__version__` (release artifact)

-Classifies git changes as user-facing or workflow-only. Used to skip releases for infrastructure-only changes. Patterns are configurable.
+**User-facing paths** (tool changes — release needed) — everything else:
+- `src/devx/**` — Python package source (except `__init__.py`)
+- `pyproject.toml` — Package metadata
+- Any new file type not in the allowlist

-### discover_runners.py
+Classification is configured in `pyproject.toml` under
+`[tool.devx.classify]`. The framework provides `DEFAULT_INFRASTRUCTURE` — a
+curated list of paths that are infrastructure for any Python project. Projects
+inherit these automatically and only specify what is different.

-Discovers available Gitea Actions runners at repo, org, and instance levels. Generates a dynamic matrix for parallel job distribution.
+Rule priority (first match wins):
+1. `user_facing_overrides` — safety override (highest priority)
+2. `infrastructure_overrides` — explicit per-file
+3. `infrastructure` — DEFAULT_INFRASTRUCTURE + project-specific patterns
+4. Default: user-facing (safe — any unknown file triggers release)

-### detect_release_commit.py
+## Post-merge workflow (`post-merge.yml`)

-Detects whether the latest git commit is a release commit. Writes `is-release=true` or `is-release=false` to GitHub output.
+Runs on every push to master. A single workflow with conditional jobs
+replaces separate workflows for release, wiki sync, badges, and Vikunja task
+updates.

-### push_badges.py
+### Job dependency graph

-Generates SVG badge files from project metrics (tests, coverage, quality, version). Pushes to `badges` branch and updates README with cache-busting commit SHA URLs.
+```text
+detect-type ──┬── validate-commit-msg (skip if release commit)
+              ├── release (skip if release commit)
+              │       │
+              │       ├── sync-wiki (needs release)
+              │       ├── badges (needs release, ALWAYS runs)
+              │       └── vikunja (needs release)
+              └── configure-repo (independent, skip if release commit)
+```

-### distribute_molecule.py
+`sync-wiki` and `vikunja` depend on `release` succeeding so that the wiki and
+task tracker are only updated when the code is actually released. If release
+fails, they are skipped to avoid leaving the wiki or Vikunja in an
+inconsistent state.

-Distributes molecule (scenario, platform) pairs across N parallel runners. Discovers scenarios under `ansible/roles/*/molecule/`.
+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.

-### molecule_ci_guard.py
+When `release` creates a `release: vX.Y.Z` commit, the release commit's
+post-merge run still updates badges (the version badge picks up the new
+version). Other jobs skip. The tag push triggers `publish.yml`.

-Runs molecule tests sequentially while polling Gitea for other runner failures. Aborts if another runner fails the same job.
+### Post-merge jobs

-### validate_commit_msg.py
+#### `detect-type`

-Validates commit messages. On feature branches: conventional commits only (no `DEVX-N` prefix). On master: must have `DEVX-N` prefix from auto-merge.
+Checks if the latest commit is a release commit (`release: vX.Y.Z [skip ci]`)
+using `python -m devx.ci.detect_release_commit`. Writes `is-release=true` or
+`is-release=false` to the job output. All subsequent jobs use this to
+conditionally skip for release commits.
+
+#### `validate-commit-msg`
+
+Depends on `detect-type`. Skips for release commits. Validates the latest
+commit message using `python -m devx.ci.validate_commit_msg --branch master`.
+On master, commits must follow `{PREFIX}-N: <conventional commit>` format
+(added by auto-merge).
+
+#### `release`
+
+Depends on `detect-type`. Skips for release commits. The core release
+automation job. Runs `python -m devx.ci.release`:
+
+1. **Classify changes** — calls `classify_changes.py` to check for user-facing
+   changes. If only infrastructure files changed, exits without releasing.
+2. **Calculate next version** — uses git-cliff to determine the next semver
+   version from conventional commits since the last tag
+3. **Update version file** — updates `__version__` in `src/devx/__init__.py`
+4. **Update changelog** — prepends the new version section to `CHANGELOG.md`
+   using git-cliff output
+5. **Run tests** — executes `make lint-ruff` and `make pytest-cov` to verify
+   the release is healthy. If either fails, the release is aborted — no
+   commit, no tag. Use `--skip-tests` only for emergency releases.
+6. **Commit** — stages the version file and changelog, commits with
+   `release: vX.Y.Z [skip ci]` (uses `--no-verify` to bypass the commit-msg
+   hook since release commits are a special case)
+7. **Create tag** — creates an annotated tag `vX.Y.Z` with the changelog as
+   the tag message
+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 (for example,
+from a partial previous run), it skips tag creation and only pushes.
+
+**Tag consistency**: Before releasing, the script fetches remote tags and
+verifies all existing tags point to commits whose message matches the tag
+version. This prevents duplicate release commits and ensures
+tag/version/commit alignment.
+
+**Version bumping rules** (git-cliff):
+
+| Commit type | Version bump |
+|-------------|-------------|
+| `feat:` | minor (0.X.0) |
+| `fix:` | patch (0.0.X) |
+| `feat!:` or `BREAKING CHANGE` | minor (pre-1.0) |
+| `chore:`, `ci:`, `docs:` | no bump (excluded by cliff.toml) |
+
+On failure, the `notify_failure` step creates a Gitea issue via
+`python -m devx.ci.notify_failure`.
+
+#### `sync-wiki`
+
+Depends on `detect-type` and `release`. Skips for release commits. Syncs
+documentation from `docs/` to the Gitea wiki using
+`python -m devx.ci.sync_wiki --repo <owner/repo> --strict`:
+
+1. Reads `docs/mapping.json` to map file paths to wiki page titles
+2. Lists existing wiki pages via the Gitea API
+3. For each mapped file, reads content and creates or updates the wiki page
+4. `--strict` runs a full integrity check: verifies page count, missing
+   pages, stale pages, and content match. Fails if any page is empty or
+   content doesn't match.
+
+Pages that exist in the wiki but not in the mapping are left untouched (not
+deleted).
+
+On failure, the `notify_failure` step creates a Gitea issue.
+
+#### `badges`
+
+Depends on `detect-type` and `release`. Uses `if: always()` so it runs on
+every push to master, including release commits. Generates and pushes quality
+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)
+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`,
+   `version.svg`, `python.svg`
+3. **Push to badges branch** — creates an orphan `badges` branch, copies SVG
+   files, commits, and force-pushes
+4. **Update README/docs** — switches back to master, replaces
+   `raw/branch/badges/<name>.svg` URLs with `raw/commit/<sha>/<name>.svg`
+   URLs (cache-busting — Gitea caches `raw/branch/` URLs for 6 hours),
+   commits, and pushes
+
+Supports `--retries` for retrying on git push failures (fetches latest master
+and waits 10s between attempts).
+
+On failure, the `notify_failure` step creates a Gitea issue.
+
+#### `vikunja`
+
+Depends on `detect-type` and `release`. Skips for release commits. Updates
+the Vikunja task after a merge using `python -m devx.ci.post_merge --git-sha
+<sha>`:
+
+1. Extracts the task ID from the first line of the commit message
+2. Marks the corresponding Vikunja task as done
+3. Posts a comment with the merge SHA
+
+On failure, the `notify_failure` step creates a Gitea issue.
+
+#### `configure-repo`
+
+Depends on `detect-type`. Skips for release commits. Ensures branch
+protection and labels are configured using
+`python -m devx.tools.configure_repo --repo <name> --owner <owner>`:
+
+- Sets up master branch protection (required status checks, block on rejected
+  reviews, block on outdated branch)
+- Creates standard labels
+- Status check contexts read from `DEVX_STATUS_CHECKS` or default to
+  `CI / quality (pull_request)`
+
+On failure, the `notify_failure` step creates a Gitea issue.
+
+## Publish workflow (`publish.yml`)
+
+Runs on tag pushes matching `v*`. Triggered by the `release` job in the
+post-merge workflow when it creates and pushes a new version tag.
+
+### Job: `publish`
+
+1. **Install dependencies** — build, twine, requests, python-dotenv, click,
+   and the project itself
+2. **Install CI tools** — git-cliff and tea via
+   `python -m devx.tools.install_tools`
+3. **Configure tea login** — `tea login add` using `CI_GITEA_TOKEN`
+4. **Build and publish** — `python -m devx.ci.publish <tag> <owner/repo>`:
+   - Build the package with `python -m build`
+   - Publish to the Gitea PyPI registry (default) using `twine upload
+     --repository-url <url> -u <token> -p <token>`
+   - OR publish to standard PyPI if `PYPI_TOKEN` is set
+   - OR skip publishing if `--skip-build` is passed (non-Python repos)
+   - Create a Gitea release with git-cliff-generated release notes via
+     `tea create release`
+
+Publishing destination resolution (checked in order):
+1. **Gitea PyPI registry** — if `--registry-url` is given, or
+   `DEVX_PYPI_REGISTRY_URL` env var is set, or derived from `GITEA_API_URL`
+2. **Standard PyPI** — if `PYPI_TOKEN` is set (takes precedence over Gitea
+   registry)
+3. **Skip** — if neither is configured, only the Gitea release is created
+
+On failure, the `notify_failure` step creates a Gitea issue.
+
+## CI scripts
+
+### `auto_merge.py`
+
+Auto-merge PR when all CI checks pass. Reads task ID from the branch name
+(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.
+
+```bash
+python -m devx.ci.auto_merge <branch> <pr_title> <owner/repo> <pr_number>
+```
+
+### `release.py`
+
+Automated release using git-cliff. Calculates next semver version from
+conventional commits, updates `__version__` and `CHANGELOG.md`, runs lint and
+tests, commits with `release: vX.Y.Z [skip ci]`, creates annotated tag, and
+pushes. Idempotent — exits if no unreleased changes.
+
+```bash
+python -m devx.ci.release [--dry-run] [--skip-tests] [--verify]
+```
+
+- `--dry-run` — preview without making changes
+- `--skip-tests` — skip lint and test verification (emergency only)
+- `--verify` — check tag/version/changelog alignment and exit
+
+### `publish.py`
+
+Builds package, publishes to Gitea PyPI registry or standard PyPI, and
+creates a Gitea release with git-cliff-generated notes.
+
+```bash
+python -m devx.ci.publish <tag> <owner/repo> [--registry-url <url>] [--skip-build]
+```
+
+### `pr_review.py`
+
+Automated PR review. Fetches the PR diff via the Gitea API, runs automated
+checks (architecture, best practices, security, i18n, resource management,
+documentation, test coverage, commit conventions), and posts a structured
+review with inline comments.
+
+```bash
+python -m devx.ci.pr_review <pr_number> <owner/repo>
+```
+
+### `notify_failure.py`
+
+Creates a Gitea issue when a CI workflow fails. Uses the tea CLI for issue
+creation with failure labels. Supports `--auto-login` to configure the tea
+CLI login profile from `CI_GITEA_TOKEN`.
+
+```bash
+python -m devx.ci.notify_failure --repo <owner/repo> --run-id <id> \
+  --workflow <name> --commit <sha> [--auto-login]
+```
+
+### `post_merge.py`
+
+Updates Vikunja task after a merge to master. Extracts task ID from the
+commit message, marks the task as done, and posts a comment with the merge SHA.
+
+```bash
+python -m devx.ci.post_merge <commit_msg> [--commit-sha <sha>] [--git-sha <sha>]
+```
+
+### `classify_changes.py`
+
+Classifies git changes as user-facing or workflow-only. Uses a layered rule
+system configured in `pyproject.toml`. Safe-by-default: any unknown file
+defaults to user-facing.
+
+```bash
+python -m devx.ci.classify_changes [--base <ref>] [--head <ref>] \
+  [--quiet] [--check <category>] [--github-output]
+```
+
+### `discover_runners.py`
+
+Discovers available Gitea Actions runners at repository, organization, and
+instance levels. Falls back to `MOLECULE_RUNNERS` repo variable or
+`DEFAULT_MAX_RUNNERS` (3).
+
+```bash
+python -m devx.ci.discover_runners --owner <owner> --repo <repo> [--count] [--indices]
+```
+
+### `detect_release_commit.py`
+
+Detects whether the latest git commit is a release commit. Writes
+`is-release=true|false` to `$GITHUB_OUTPUT`.
+
+```bash
+python -m devx.ci.detect_release_commit
+```
+
+### `push_badges.py`
+
+Generates SVG badge files, pushes them to the `badges` branch, and updates
+README.md and docs/index.md with cache-busting `raw/commit/<sha>/` URLs.
+
+```bash
+python -m devx.ci.push_badges [--output-dir <dir>] [--branch <branch>] \
+  [--no-readme-update] [--retries <n>]
+```
+
+### `distribute_molecule.py`
+
+Distributes molecule (scenario, platform) pairs across N parallel runners.
+Discovers scenarios under `ansible/roles/*/molecule/`.
+
+```bash
+python -m devx.molecule.distribute_molecule --runner-index <i> --max-runners <n>
+python -m devx.molecule.distribute_molecule --list
+python -m devx.molecule.distribute_molecule --list-platforms
+```
+
+### `molecule_ci_guard.py`
+
+Runs molecule tests sequentially while polling the Gitea API for other runner
+failures. Aborts early if another runner fails the same job.
+
+```bash
+python -m devx.molecule.molecule_ci_guard [--roles-root <dir>] pair1 pair2 ...
+```
+
+### `validate_commit_msg.py`
+
+Validates commit messages. On feature branches: conventional commits only
+(no `{PREFIX}-N` prefix). On master: must have `{PREFIX}-N` prefix from
+auto-merge, followed by a conventional commit message.
+
+```bash
+python -m devx.ci.validate_commit_msg <commit_msg_file> [--branch <branch>]
+```
+
+### `sync_wiki.py`
+
+Syncs documentation from `docs/` to the Gitea wiki via the API. Reads
+`docs/mapping.json` for file-to-page mapping. Supports `--dry-run`,
+`--verify`, and `--strict` (full integrity check).
+
+```bash
+python -m devx.ci.sync_wiki [--dry-run] [--repo <owner/repo>] [--verify] [--strict]
+```
+
+### `check_translations.py`
+
+Validates translation files against the Python source code. Checks for
+missing keys, dead keys, and missing languages.
+
+```bash
+python -m devx.ci.check_translations [--translations <file>]...
+```
+
+### `doc_coverage.py`
+
+Checks documentation coverage for CLI commands and major modules. Parses
+Click commands from `cli.py` and verifies documentation exists.
+
+```bash
+python -m devx.ci.doc_coverage [--docs-dir <dir>] [--fail-on-missing]
+```
+
+### `distribute_files.py`
+
+Distributes files matching a glob pattern across N parallel runners
+(round-robin). Writes the assigned file list to `$GITHUB_ENV`.
+
+```bash
+python -m devx.ci.distribute_files --pattern <glob> --runner-index <i> \
+  --max-runners <n> [--github-env] [--skip-if-excess]
+```
+
+### `integration_guard.py`
+
+Runs pytest with cross-runner failure detection. If any other
+integration-tests matrix runner reports failure, the current pytest
+subprocess is killed and this runner exits early.
+
+```bash
+python -m devx.ci.integration_guard -- <pytest args>
+```
+
+## Release process summary
+
+The complete release process from PR to published package:
+
+1. **PR merged** — `auto-merge` squash-merges the PR to master with
+   `{PREFIX}-N <conventional commit>` title
+2. **Post-merge triggers** — the merge push triggers `post-merge.yml`
+3. **detect-type** — confirms the commit is not a release commit
+4. **release** — `release.py` calculates the next version, updates files,
+   runs tests, commits `release: vX.Y.Z [skip ci]`, creates tag `vX.Y.Z`,
+   and pushes to master
+5. **Tag push triggers publish** — the tag push triggers `publish.yml`
+6. **publish** — `publish.py` builds the package, publishes to the Gitea PyPI
+   registry, and creates a Gitea release with git-cliff notes
+7. **sync-wiki** — documentation is synced to the Gitea wiki
+8. **badges** — quality badges are regenerated and pushed to the `badges`
+   branch; README and docs/index.md are updated with cache-busting URLs
+9. **vikunja** — the corresponding Vikunja task is marked as done
+10. **configure-repo** — branch protection and labels are ensured
+
+The release commit's post-merge run skips all jobs except `badges` (which
+picks up the new version number). This prevents infinite loops.
+
+## Failure handling
+
+Every job in the post-merge and publish workflows has a `notify_failure` step
+that runs `if: failure()`. This creates a Gitea issue with the workflow name,
+run ID, and commit SHA, ensuring failures that would otherwise go unnoticed
+in the Actions tab are surfaced as issues. The issue is created via the tea
+CLI with a `bug` label if available.
@@ -1,134 +1,521 @@
 # CLI Commands

 devx provides a CLI with three command groups: `ci`, `tools`, and `molecule`.
+Each subcommand delegates to the corresponding Python module via
+`python -m devx.*`, so `devx ci release` is equivalent to
+`python -m devx.ci.release`.
+
+```bash
+devx --help        # show all command groups
+devx --version     # show package version
+devx ci --help     # show CI commands
+devx tools --help  # show tools commands
+devx molecule --help  # show molecule commands
+```

 ## CI Commands

 ### `devx ci auto-merge`

-Auto-merge a PR when all CI checks pass. Validates PR title, checks Vikunja task, squash-merges.
+Auto-merge a PR when all CI checks pass. Reads the task ID from the branch
+name, validates the PR title format against
+the Vikunja task title, extracts the conventional commit message from PR
+commits, and squash-merges with `{PREFIX}-N <conventional commit>` title.
+
+If the head branch is behind master (HTTP 405), automatically pulls master,
+rebases, force-pushes, and retries the merge.
+
+```bash
+devx ci auto-merge <branch> <pr_title> <owner/repo> <pr_number>
+# Example:
+devx ci auto-merge DEVX-12-add-feature "DEVX-12: Add feature" oblachno-oss/devx 42
+```

 ### `devx ci check-translations`

-Check translation files for gaps, dead keys, and missing languages.
+Check translation files for gaps, dead keys, and missing languages. Validates
+translation files against the Python source code that uses them. By default,
+checks `src/devx/translations.json` against `src/devx/**/*.py`.
+
+Checks performed:
+- **Missing keys** — a `_()` call in code has no entry in the translations file
+- **Dead keys** — a key in the translations file is not used in any code
+- **Missing languages** — a key exists but is missing one of the six
+  supported languages (en, bg, de, ru, zh, pl)
+
+```bash
+devx ci check-translations
+devx ci check-translations --translations path/to/translations.json
+```

 ### `devx ci classify-changes`

-Classify git changes as user-facing or workflow-only. Used to skip releases for infrastructure-only changes.
+Classify git changes as user-facing or workflow-only. Used to skip releases
+for infrastructure-only changes. Classification rules are configured in
+`pyproject.toml` under `[tool.devx.classify]`.
+
+```bash
+devx ci classify-changes --base origin/master --head HEAD
+devx ci classify-changes --base origin/master --head HEAD --github-output
+devx ci classify-changes --quiet --check user-facing
+devx ci classify-changes --check ansible  # custom tag from pyproject.toml
+```
+
+Options:
+- `--base <ref>` — base ref (default: latest tag)
+- `--head <ref>` — head ref (default: HEAD)
+- `--quiet` — only output true/false
+- `--check <category>` — check specific category: `all` (default),
+  `user-facing`, or any tag name defined in `[tool.devx.classify.tags]`
+- `--github-output` — write results to `$GITHUB_OUTPUT` for CI workflow steps
+
+Exit code 2 indicates workflow-only changes (no release needed).

 ### `devx ci detect-release-commit`

-Detect whether the latest git commit is a release commit (`release: vX.Y.Z [skip ci]`).
+Detect whether the latest git commit is a release commit
+(`release: vX.Y.Z [skip ci]`). Writes `is-release=true` or `is-release=false`
+to `$GITHUB_OUTPUT` for use in CI workflow conditionals.
+
+```bash
+devx ci detect-release-commit
+```

 ### `devx ci discover-runners`

 Discover available Gitea Actions runners for dynamic job distribution.
+Queries the Gitea API for registered runners at repository, organization, and
+instance (admin) levels. Falls back to `MOLECULE_RUNNERS` repo variable or
+`DEFAULT_MAX_RUNNERS` (3).
+
+```bash
+devx ci discover-runners --owner oblachno-oss --repo devx
+devx ci discover-runners --owner oblachno-oss --repo devx --count
+devx ci discover-runners --owner oblachno-oss --repo devx --indices
+```
+
+Options:
+- `--count` — print the number of available runners
+- `--indices` — print a JSON array `[0, 1, ..., N-1]` for use as a dynamic
+  matrix in Gitea Actions

 ### `devx ci distribute-files`

-Distribute files across parallel runners (round-robin). Used for splitting test suites or workloads across CI runners.
+Distribute files across parallel runners (round-robin). Discovers files
+matching a glob pattern, sorts them for deterministic ordering, then assigns
+them round-robin to `max_runners` groups. The assigned group for
+`runner_index` is written to `$GITHUB_ENV`.
+
+```bash
+devx ci distribute-files --pattern "tests/integration/test_*.py" \
+  --runner-index 1 --max-runners 3 --github-env
+```
+
+Options:
+- `--pattern <glob>` — glob pattern for files to distribute
+- `--runner-index <i>` — current runner index (0-based)
+- `--max-runners <n>` — total number of runners (default: 3)
+- `--github-env` — write file list to `$GITHUB_ENV`
+- `--skip-if-excess` — skip if fewer files than runners

 ### `devx ci doc-coverage`

-Check documentation coverage for CLI commands and major modules.
+Check documentation coverage for CLI commands and major modules. Parses
+Click commands from `cli.py` and checks if each has documentation in
+`docs/user/cli-commands.md`. Verifies core modules are documented in
+`architecture.md` and CI scripts in `ci-cd-workflow.md`.
+
+```bash
+devx ci doc-coverage
+devx ci doc-coverage --docs-dir docs/ --source-dir src/ --fail-on-missing
+```
+
+Options:
+- `--docs-dir <dir>` — path to the docs directory (default: `docs/`)
+- `--source-dir <dir>` — path to the source directory (default: auto-detect)
+- `--fail-on-missing` — exit with non-zero status if any documentation is
+  missing
+
+### `devx ci lint-docs`
+
+Lint documentation files for structure, broken links, heading hierarchy,
+duplicate headings, TODO/FIXME markers, and trailing whitespace.
+
+```bash
+devx ci lint-docs
+devx ci lint-docs --root . --fix
+devx ci lint-docs --no-check-links --no-check-stale
+```
+
+Options:
+- `--root <dir>` — repository root directory (default: `.`)
+- `--docs-dir <dir>` — docs directory (default: `<root>/docs`)
+- `--check-links/--no-check-links` — check internal links (default: yes)
+- `--check-headings/--no-check-headings` — check heading hierarchy (default: yes)
+- `--check-todo/--no-check-todo` — check for TODO/FIXME markers (default: yes)
+- `--check-stale/--no-check-stale` — check for stale docs (default: no)
+- `--check-trailing/--no-check-trailing` — check trailing whitespace (default: yes)
+- `--check-duplicates/--no-check-duplicates` — check duplicate headings (default: yes)
+- `--fix` — auto-fix trailing whitespace

 ### `devx ci integration-guard`

-Run pytest with cross-runner failure detection and JUnit XML output. Monitors other runners for failures and aborts early if a critical failure is detected.
+Run pytest with cross-runner failure detection. If any
+other integration-tests matrix runner reports failure, the current pytest
+subprocess is killed and this runner exits early with code 1.

-### `devx ci merge-junit`
+```bash
+devx ci integration-guard -- test_a.py test_b.py
+devx ci integration-guard -- -x -v --tb=short test_a.py
+```

-Merge multiple JUnit XML reports from parallel runners into a single consolidated report.
+Environment variables:
+- `GITEA_URL` — base URL of the Gitea instance
+- `CI_GITEA_TOKEN` — API token with repo access
+- `RUN_ID` — workflow run ID (`GITHUB_RUN_ID`)
+- `JOB_NAME` — base job name (`GITHUB_JOB`)
+- `MATRIX_INDEX` — current matrix index (runner-index)
+- `GITEA_REPOSITORY` — repository in `owner/repo` format

 ### `devx ci notify-failure`

-Create a Gitea issue when a CI workflow fails.
+Create a Gitea issue when a CI workflow fails. Uses the tea CLI for issue
+creation with a `bug` label if available.
+
+```bash
+devx ci notify-failure --repo oblachno-oss/devx --run-id 123 \
+  --workflow ci --commit abc123def456
+devx ci notify-failure --repo oblachno-oss/devx --run-id 123 \
+  --workflow post-merge/release --commit abc123def456 --auto-login
+```
+
+Options:
+- `--repo <owner/repo>` — repository (required)
+- `--run-id <id>` — CI run ID (required)
+- `--workflow <name>` — workflow name (required)
+- `--commit <sha>` — commit SHA (required)
+- `--auto-login` — configure tea CLI login from `CI_GITEA_TOKEN` before creating
+  the issue

 ### `devx ci post-merge`

-Update Vikunja task after a merge to master.
+Update Vikunja task after a merge to master. Extracts the task ID from the
+commit message, marks the task as done, and posts a comment with the merge SHA.
+
+```bash
+devx ci post-merge "DEVX-12 feat: add feature" --git-sha abc123def456
+```

 ### `devx ci pr-review`

-Run automated PR review: check architecture compliance, best practices, and quality.
+Run automated PR review. Fetches the PR diff via the Gitea API and runs a
+series of checks, posting a structured review (`COMMENT` or
+`REQUEST_CHANGES`).
+
+Checks: architecture compliance, best practices, security, i18n, resource
+management, documentation, test coverage, and commit conventions.
+
+```bash
+devx ci pr-review 42 oblachno-oss/devx
+```

 ### `devx ci publish`

-Build package, publish to Gitea PyPI registry, and create Gitea release.
+Build package, publish to Gitea PyPI registry (or standard PyPI), and create
+a Gitea release with git-cliff-generated notes.
+
+```bash
+devx ci publish v1.0.0 oblachno-oss/devx
+devx ci publish v1.0.0 oblachno-oss/devx --registry-url https://git.example.com/api/packages/owner/pypi
+devx ci publish v1.0.0 oblachno-oss/devx --skip-build  # Gitea release only
+```
+
+Options:
+- `--registry-url <url>` — Gitea PyPI registry URL. Defaults to
+  `DEVX_PYPI_REGISTRY_URL` env var or a URL derived from `GITEA_API_URL`.
+  When set, publishes to Gitea PyPI instead of standard PyPI (unless
+  `PYPI_TOKEN` is also set).
+- `--skip-build` — skip package build and PyPI publish (for non-Python repos
+  that only need a Gitea release)

 ### `devx ci push-badges`

-Generate badge SVG files and push them to the `badges` branch.
+Generate badge SVG files and push them to the `badges` branch. Also updates
+`README.md` and `docs/index.md` on master with cache-busting
+`raw/commit/<sha>/` URLs.
+
+```bash
+devx ci push-badges
+devx ci push-badges --output-dir .badges/ --branch master
+devx ci push-badges --no-readme-update  # skip README update (local testing)
+devx ci push-badges --retries 3  # retry on git push failures
+```
+
+Options:
+- `--output-dir <dir>` — temporary directory for badge files (default:
+  `.badges/`)
+- `--branch <branch>` — branch to sync before generating badges (default:
+  `master`)
+- `--no-readme-update` — skip updating README with cache-busting URLs
+- `--retries <n>` — number of attempts on git push failures (default: 1).
+  Between attempts, fetches latest master and waits 10s.

 ### `devx ci release`

-Automated release: calculate next version, update files, tag, and push.
+Automated release: calculate next version, update files, tag, and push. Uses
+git-cliff to determine the next semver version from conventional commits.
+
+```bash
+devx ci release
+devx ci release --dry-run          # preview without making changes
+devx ci release --skip-tests       # skip lint and tests (emergency only)
+devx ci release --verify           # check tag/version/changelog alignment
+```
+
+Options:
+- `--dry-run` — show what would happen without making changes
+- `--skip-tests` — skip lint and test verification (NOT recommended — only
+  for emergency releases)
+- `--verify` — verify tag/version/changelog alignment and exit (no changes
+  made)

 ### `devx ci sync-wiki`

-Sync documentation from `docs/` to the Gitea wiki.
+Sync documentation from `docs/` to the Gitea wiki. Reads `docs/mapping.json`
+for file-to-page mapping. Pages that exist in the wiki but not in the mapping
+are left untouched.
+
+```bash
+devx ci sync-wiki --repo oblachno-oss/devx
+devx ci sync-wiki --repo oblachno-oss/devx --dry-run
+devx ci sync-wiki --repo oblachno-oss/devx --verify
+devx ci sync-wiki --repo oblachno-oss/devx --strict
+```
+
+Options:
+- `--dry-run` — show what would happen without making changes
+- `--repo <owner/repo>` — repository (auto-detected if omitted)
+- `--verify` — after syncing, verify each page has non-empty content. Exit 1
+  if any page is empty or mismatched.
+- `--strict` — full integrity check: verify page count, missing pages, stale
+  pages, and content. Implies `--verify`.

 ### `devx ci validate-commit-msg`

-Validate commit messages for conventional commit format.
+Validate commit messages for conventional commit format. On feature branches:
+conventional commits only (no `{PREFIX}-N` prefix). On master: must have
+`{PREFIX}-N` prefix from auto-merge, followed by a conventional commit
+message.
+
+```bash
+devx ci validate-commit-msg commit-msg.txt
+devx ci validate-commit-msg commit-msg.txt --branch master
+```
+
+Options:
+- `--branch <branch>` — override branch detection (for CI use)

 ## Tools Commands

 ### `devx tools check-test-speed`

-Run unit tests and enforce execution-time budgets:
- **Total suite time** must not exceed `--max-seconds` (default: 10s).
- **Per-test time** — no individual test may exceed `--max-single-seconds` (default: 0.5s, 0 to disable).
+Run unit tests and enforce execution-time budgets. Two quality gates:
+
+- **Total suite time** must not exceed `--max-seconds` (default: 10s)
+- **Per-test time** — no individual test may exceed `--max-single-seconds`
+  (default: 0.5s, 0 to disable)
+
+Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0` so pytest emits
+per-test timing lines.

 ```bash
-python3 -m devx.tools.check_test_speed --max-seconds 10 --max-single-seconds 0.5
+devx tools check-test-speed
+devx tools check-test-speed --max-seconds 10
+devx tools check-test-speed --max-seconds 4 --max-single-seconds 0.5
 ```

 ### `devx tools configure-repo`

-Configure repository: branch protection + labels via Gitea API.
+Configure repository: branch protection and labels via the Gitea REST API.
+Sets up master branch protection (required status checks, block on rejected
+reviews, block on outdated branch) and creates standard labels.
+
+```bash
+devx tools configure-repo --repo devx --owner oblachno-oss
+```
+
+Status check contexts are read from `DEVX_STATUS_CHECKS` (comma-separated) or
+default to `CI / quality (pull_request)`.

 ### `devx tools generate-badges`

-Generate self-contained SVG badge files from project metrics.
+Generate self-contained SVG badge files from project metrics. Runs
+pytest-cov, doc-coverage, lint checks, and version extraction, then writes
+SVG files that can be served as static files from the Gitea raw file API.
+
+Badges generated: `coverage.svg`, `tests.svg`, `docs.svg`, `quality.svg`,
+`version.svg`, `python.svg`.
+
+```bash
+devx tools generate-badges
+devx tools generate-badges --output-dir .badges/
+```

 ### `devx tools generate-cliff-config`

-Generate a `cliff.toml` configuration file with the correct task ID prefix.
-Eliminates the need to manually duplicate and maintain cliff.toml across
-repos that use devx.
+Generate a `cliff.toml` configuration file with the correct task ID prefix
+preprocessor. Eliminates the need to manually duplicate and maintain
+`cliff.toml` across repos that use devx.

 ```bash
-python -m devx.tools.generate_cliff_config --prefix GRM
-python -m devx.tools.generate_cliff_config --prefix GRM --force  # overwrite existing
+devx tools generate-cliff-config --prefix GRM
+devx tools generate-cliff-config --prefix GRM --output cliff.toml
+devx tools generate-cliff-config --prefix GRM --force  # overwrite existing
 ```

+Options:
+- `--prefix <prefix>` — task ID prefix (default: `DEVX_TASK_PREFIX` env var
+  or `DEVX`)
+- `--output <file>` — output file path (default: `cliff.toml`)
+- `--force` — overwrite existing file
+
 ### `devx tools install-checkmake`

-Install checkmake (Makefile linter) if not already present.
+Install checkmake (Makefile linter) if not already present. Tries
+`go install` first if Go is available, otherwise downloads the latest
+pre-built Linux binary from the official GitHub releases.
+
+```bash
+devx tools install-checkmake
+```

 ### `devx tools install-tools`

-Install CI/CD development tools: actionlint, git-cliff, act_runner, tea.
+Install CI/CD development tools that are not Python packages: actionlint,
+git-cliff, act_runner, and tea. Each tool is installed to `~/.local/bin` if
+not already on PATH. Idempotent: skips tools that are already available.
+
+```bash
+devx tools install-tools                    # install all
+devx tools install-tools --tool actionlint  # install one
+devx tools install-tools --tool git-cliff --tool tea  # install specific
+devx tools install-tools --list             # list status
+```

 ### `devx tools setup`

-Project setup: install Python deps and pre-commit hooks.
+Project setup: install Python dependencies (editable mode with extras),
+Ansible Galaxy collections (if `ansible/requirements.yml` exists), pre-commit
+hooks (pre-commit, commit-msg, pre-push), and configure the tea CLI login
+profile from `.env`.
+
+```bash
+devx tools setup --bin .venv/bin
+devx tools setup --bin .venv/bin --extras "ci,lint"
+devx tools setup --bin .venv/bin --no-pre-commit --no-tea-login
+```
+
+Options:
+- `--bin <dir>` — virtualenv bin directory (required)
+- `--extras <groups>` — pip extras to install (default: `dev`)
+- `--no-pre-commit` — skip pre-commit hook installation
+- `--no-tea-login` — skip tea CLI login configuration
+
+### `devx tools rebase`
+
+Rebase the current branch onto `origin/master` and force-push with
+`--force-with-lease`. Checks if the branch is behind master first —
+if up-to-date, exits without doing anything.
+
+```bash
+devx tools rebase                          # rebase + force-push
+devx tools rebase -- --no-push             # rebase locally only
+```
+
+Options (pass after `--`):
+- `--no-push` — rebase locally without pushing
+
+### `devx tools pr-rebase`
+
+Rebase a pull request's head branch onto master via the Gitea API
+(server-side). This triggers a new `pull_request synchronize` event,
+which starts a new CI run. Useful when you don't have the branch
+checked out locally.
+
+```bash
+devx tools pr-rebase -- --pr 42            # rebase PR #42
+devx tools pr-rebase                       # auto-detect PR from current branch
+```
+
+Options (pass after `--`):
+- `--pr <N>` — PR number (auto-detected from current branch if omitted)

 ## Molecule Commands

-### `devx molecule distribute`
-
-Distribute molecule test pairs across parallel runners.
-
-### `devx molecule discover-runners`
-
-Discover available Gitea Actions runners for molecule tests.
-
-### `devx molecule guard`
-
-Run molecule tests sequentially with CI failure polling.
+Molecule commands require the `molecule` extra (`pip install devx[molecule]`).

 ### `devx molecule all`

-Run all molecule scenarios on all supported OS platforms.
+Run all molecule scenarios on all supported OS platforms. Sequential
+execution — CI uses the parallel matrix instead.
+
+```bash
+devx molecule all
+devx molecule all --bin .venv/bin
+```
+
+### `devx molecule discover-runners`
+
+Discover available Gitea Actions runners for molecule tests. Same logic as
+`devx ci discover-runners` but intended for molecule-specific workflows.
+
+```bash
+devx molecule discover-runners --owner oblachno-oss --repo devx --indices
+```
+
+### `devx molecule distribute`
+
+Distribute molecule (scenario, platform) pairs across N parallel runners.
+Discovers scenarios under `ansible/roles/*/molecule/` and crosses them with
+the supported OS platform matrix.
+
+```bash
+devx molecule distribute --runner-index 1 --max-runners 3
+devx molecule distribute --list              # list all scenarios
+devx molecule distribute --list-platforms    # list platforms
+devx molecule distribute --roles-root ansible/roles  # multi-role repos
+```
+
+Options:
+- `--runner-index <i>` — current runner index (0-based)
+- `--max-runners <n>` — total number of runners (default: 3)
+- `--list` — list all scenarios, one per line
+- `--list-platforms` — list all platforms, one per line
+- `--roles-root <dir>` — roles root directory for multi-role repos (default:
+  `ansible/roles`)
+
+### `devx molecule guard`
+
+Run molecule tests sequentially with CI failure polling. A background thread
+polls the Gitea API. If any other molecule matrix runner reports failure, the
+current molecule subprocess is killed and this runner exits early with code 1.
+
+```bash
+devx molecule guard pair1 pair2 pair3
+devx molecule guard --roles-root ansible/roles pair1 pair2
+```
+
+Each pair is encoded as:
+- **Single-role (4-part):** `scenario|platform_name|platform_image|platform_command`
+- **Multi-role (5-part):** `role|scenario|platform_name|platform_image|platform_command`
+
+Options:
+- `--roles-root <dir>` — roles root directory for multi-role repos
+
+Environment variables:
+- `GITEA_URL` — base URL of the Gitea instance
+- `CI_GITEA_TOKEN` — API token with repo access
+- `RUN_ID` — workflow run ID (`GITHUB_RUN_ID`)
+- `JOB_NAME` — base job name (`GITHUB_JOB`)
+- `MATRIX_INDEX` — current matrix index (runner-index)
+- `GITEA_REPOSITORY` — repository in `owner/repo` format
@@ -0,0 +1,161 @@
+# Getting Started with devx
+
+This guide walks you through installing devx, configuring it for your project,
+and setting up a complete CI/CD pipeline.
+
+## Prerequisites
+
+- **Python 3.12+**
+- **A Gitea instance** with Actions enabled
+- **A Gitea API token** with repo, workflow, and organization scopes
+- **(Optional) Vikunja API token** for task tracking integration
+
+## Installation
+
+devx is published to the Gitea PyPI registry. Configure pip to use it:
+
+```bash
+# Configure Gitea PyPI registry
+pip config set global.extra-index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
+
+# Install devx
+pip install devx
+```
+
+Or install from source:
+
+```bash
+git clone https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git
+cd devx
+make setup
+```
+
+## Quick Start
+
+### 1. Configure environment variables
+
+Create a `.env` file in your project root:
+
+```bash
+CI_GITEA_TOKEN=your_gitea_api_token
+VIKUNJA_TOKEN=your_vikunja_api_token  # optional
+```
+
+### 2. Add devx to your project
+
+Add devx to your `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    "devx>=0.36.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "devx>=0.36.0",
+]
+```
+
+### 3. Set up the Makefile
+
+devx provides a shared Makefile fragment. Add this to your `Makefile`:
+
+```makefile
+include devx.mak
+```
+
+Run `devx tools setup` to install all development tools (actionlint, git-cliff,
+tea CLI, etc.) and configure pre-commit hooks.
+
+### 4. Create the docs structure
+
+devx expects a `docs/` directory with at minimum:
+
+```text
+docs/
+├── index.md          # Documentation home page
+├── mapping.json      # Wiki page title mappings
+├── user/             # User-facing documentation
+│   └── cli-commands.md
+└── tech/             # Technical documentation
+    ├── architecture.md
+    └── ci-cd-workflow.md
+```
+
+Example `docs/mapping.json`:
+
+```json
+{
+  "index.md": "Home",
+  "user/cli-commands.md": "CLI-Commands",
+  "tech/architecture.md": "Architecture",
+  "tech/ci-cd-workflow.md": "CI-CD-Workflow"
+}
+```
+
+### 5. Set up CI workflows
+
+Create `.gitea/workflows/ci.yml` and `.gitea/workflows/post-merge.yml` in your
+project. See the [CI/CD Workflow guide](../tech/ci-cd-workflow.md) for details.
+
+### 6. Configure release settings
+
+Add a `cliff.toml` for git-cliff-based versioning:
+
+```bash
+devx tools generate-cliff-config
+```
+
+Add `[tool.devx]` section to `pyproject.toml` for project-specific config:
+
+```toml
+[tool.devx]
+# Vikunja project ID for task tracking
+vikunja_project_id = 6
+
+[tool.devx.classify]
+# File patterns that are infrastructure (no release needed)
+infrastructure = [
+    ".gitea/**",
+    "docs/**",
+    "tests/**",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+]
+```
+
+## Available Tools
+
+### CI/CD Automation (`devx.ci.*`)
+
+- `devx.ci.release` — Automated semver versioning and tagging
+- `devx.ci.publish` — Package publishing to Gitea PyPI registry
+- `devx.ci.auto_merge` — Squash-merge automation with task ID validation
+- `devx.ci.pr_review` — Automated PR review with inline comments
+- `devx.ci.classify_changes` — User-facing vs workflow-only change detection
+- `devx.ci.sync_wiki` — Push docs/ to Gitea wiki
+- `devx.ci.doc_coverage` — Documentation coverage checker
+- `devx.ci.lint_docs` — Documentation linter (structure, links, headings)
+- `devx.ci.check_translations` — i18n translation completeness checker
+- `devx.ci.notify_failure` — Create Gitea issues on CI failures
+- `devx.ci.distribute_files` — Parallel test file distribution
+- `devx.ci.distribute_items` — Parallel item distribution across runners
+- `devx.ci.discover_runners` — Dynamic runner discovery via Gitea API
+
+### Development Tools (`devx.tools.*`)
+
+- `devx.tools.setup` — Environment setup (venv, deps, hooks, tools)
+- `devx.tools.install_tools` — Install CI/CD tools (actionlint, git-cliff, tea)
+- `devx.tools.create_task` — Create Vikunja tasks
+- `devx.tools.create_pr` — Create Gitea PRs with task ID in title
+- `devx.tools.configure_repo` — Configure branch protection and labels
+- `devx.tools.generate_badges` — Generate quality badge SVGs
+- `devx.tools.check_test_speed` — Enforce test execution speed limits
+
+## Next Steps
+
+- Read the [CLI Commands reference](cli-commands.md) for all available commands
+- Read the [Architecture guide](../tech/architecture.md) to understand internals
+- Read the [CI/CD Workflow guide](../tech/ci-cd-workflow.md) for pipeline details
@@ -4,4 +4,4 @@
 # Aligned with CI (ci.yml uses same thresholds).
 set -e
 export PYTHONPATH=src
-python3 -m devx.tools.check_test_speed --max-seconds 10 --max-single-seconds 0.5
+python3 -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
@@ -13,10 +13,13 @@ classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
 ]
+# All dependencies are pinned to exact versions for full reproducibility.
+# Update pinned versions in a dedicated PR with verification.
 dependencies = [
-    "requests>=2.34.2",
-    "python-dotenv>=1.2.2",
-    "click>=8.4.1",
+    "requests==2.34.2",
+    "python-dotenv==1.2.2",
+    "click==8.4.2",
+    "tenacity==9.1.4",  # retry logic for GiteaClient/VikunjaClient
 ]

 [project.scripts]
@@ -26,38 +29,53 @@ devx = "devx.cli:cli"
 version = {attr = "devx.__version__"}

 [project.optional-dependencies]
-# Minimal deps for CI scripts that only need click/dotenv/requests
+# Test runners (pytest + coverage + parallel execution)
 ci = [
-    "pytest>=9.1.0",
-    "pytest-cov>=7.1.0",
+    "pytest==9.1.1",
+    "pytest-cov==7.1.0",
+    "pytest-xdist==3.8.0",
 ]
-# Lint and type-checking tools (quality job)
+# Lint and type-checking tools (quality job, badge generation)
 lint = [
-    "ruff>=0.15.17",
-    "pyright>=1.1.410",
-    "bandit>=1.8.2",
-    "pip-audit>=2.10",
-    "pre-commit>=4.6.0",
+    "ruff==0.15.20",
+    "pyright==1.1.411",
+    "bandit==1.9.4",
+    "pip-audit==2.10.1",
+    "pre-commit==4.6.0",
 ]
-# Molecule testing (optional — for projects with Ansible roles)
+# Release tools (build + publish to PyPI/Gitea registry)
+release = [
+    "build==1.5.0",
+    "twine==6.2.0",
+]
+# Molecule testing (for projects with Ansible roles)
 molecule = [
-    "molecule>=26.4.0",
-    "molecule-docker>=2.1.0",
-    "ansible-lint>=26.4.0",
-    "ansible>=14.0.0",
+    "molecule==26.4.0",
+    "molecule-docker==2.1.0",
+    "ansible-lint==26.4.0",
+    "ansible-core==2.21.1",
+]
+# Deploy tools (for infra staging/production deployments)
+deploy = [
+    "ansible-core==2.21.1",
+    "boto3==1.43.36",
+    "docker==7.1.0",
+    "jinja2==3.1.6",
+    "pyyaml==6.0.3",
+    "cryptography==49.0.0",
 ]
 # Full dev environment (local development)
 dev = [
-    "devx[ci,lint]",
-    "build>=1.3.0",
-    "twine>=6.2.0",
+    "devx[ci,lint,release,molecule]",
+    "build==1.5.0",
+    "twine==6.2.0",
 ]

 [tool.setuptools.packages.find]
 where = ["src"]

 [tool.setuptools.package-data]
-devx = ["translations.json"]
+devx = ["translations.json", "make/*.mak"]

 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -82,6 +100,8 @@ indent-style = "space"
 [tool.pyright]
 include = ["src"]
 pythonVersion = "3.12"
+venvPath = "."
+venv = ".venv"
 strict = ["src/devx/config.py", "src/devx/exceptions.py", "src/devx/i18n.py", "src/devx/api_clients.py", "src/devx/gitea_cli.py"]

 # ---------------------------------------------------------------------------
@@ -94,6 +114,13 @@ strict = ["src/devx/config.py", "src/devx/exceptions.py", "src/devx/i18n.py", "s
 # Rule priority (first match wins):
 #   1. user_facing_overrides (safety — highest priority)
 #   2. infrastructure_overrides (explicit per-file)
+# Project-specific devx configuration (read by devx.config)
+[tool.devx]
+task_prefix = "DEVX"
+vikunja_project_id = 8
+repo_owner = "oblachno-oss"
+repo_name = "devx"
+
 #   3. infrastructure (DEFAULT_INFRASTRUCTURE + project-specific patterns)
 #   4. Default: user-facing (safe)
 [tool.devx.classify]
@@ -117,8 +144,12 @@ infrastructure_overrides = [
 ]

 # User-facing overrides — safety override for broad infrastructure patterns
-# (empty — add when an infrastructure pattern is too broad)
-user_facing_overrides = []
+# devx workflow files (.gitea/**) are reference implementations that
+# downstream repos (grm, infra) copy from. Changes to them affect how
+# consumer projects run their CI, so they must trigger a release.
+user_facing_overrides = [
+    ".gitea/**",
+]

 # Tag patterns — additional categories for CI conditional execution
 # Orthogonal to release impact (user-facing vs infrastructure)
@@ -1,3 +1,3 @@
 """devx — reusable development and CI/CD tools for oblachno-oss projects."""

-__version__ = "0.8.2"
+__version__ = "0.36.0"
@@ -4,10 +4,16 @@ from __future__ import annotations

 import json
 import logging
-import time
 from typing import Any

 import requests
+from tenacity import (
+    before_sleep_log,
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)

 from devx.config import DEFAULT_TIMEOUT, MAX_RETRIES, RETRY_BACKOFF_BASE, RETRY_STATUS_CODES
 from devx.exceptions import APIError
@@ -27,14 +33,69 @@ def _parse_error(e: requests.HTTPError) -> tuple[int, str]:
    return status, message


-def _is_retryable(e: Exception) -> bool:
-    """Check if an exception is a transient error worth retrying."""
-    if isinstance(e, requests.ConnectionError):
-        return True
-    if isinstance(e, requests.HTTPError):
-        status, _ = _parse_error(e)
-        return status in RETRY_STATUS_CODES
-    return isinstance(e, requests.Timeout)
+class _TransientHTTPError(requests.HTTPError):
+    """HTTP error with a retryable status code (wrapped for tenacity)."""
+
+
+class _RetryableRequestError(Exception):
+    """Connection/timeout error wrapped for tenacity retry."""
+
+
+def _execute_request(
+    session: requests.Session,
+    method: str,
+    url: str,
+    **kwargs: Any,
+) -> requests.Response:
+    """Execute a single HTTP request, wrapping transient errors for tenacity.
+
+    Non-retryable HTTP errors (4xx except 429) raise :class:`APIError` directly.
+    Retryable errors (429, 5xx, connection, timeout) raise exceptions that
+    tenacity will retry.
+    """
+    try:
+        response = session.request(method, url, timeout=DEFAULT_TIMEOUT, **kwargs)
+        response.raise_for_status()
+        return response
+    except requests.HTTPError as e:
+        status, message = _parse_error(e)
+        if status in RETRY_STATUS_CODES:
+            # Wrap in _TransientHTTPError so tenacity retries it
+            raise _TransientHTTPError(message, response=e.response) from e
+        raise APIError(status, message) from e
+    except (requests.ConnectionError, requests.Timeout) as e:
+        raise _RetryableRequestError(str(e)) from e
+
+
+# Tenacity retry decorator shared by both clients.
+# Retries on transient HTTP errors (429, 5xx) and connection/timeout errors.
+_retry_decorator = retry(
+    stop=stop_after_attempt(MAX_RETRIES),
+    wait=wait_exponential(multiplier=RETRY_BACKOFF_BASE, min=RETRY_BACKOFF_BASE, max=RETRY_BACKOFF_BASE**MAX_RETRIES),
+    retry=retry_if_exception_type((_TransientHTTPError, _RetryableRequestError)),
+    before_sleep=before_sleep_log(logger, logging.WARNING),
+    reraise=True,
+)
+
+
+def _request_with_retry(
+    session: requests.Session,
+    url: str,
+    method: str,
+    **kwargs: Any,
+) -> requests.Response:
+    """Execute an HTTP request with tenacity-managed retry logic.
+
+    On exhaustion, the last exception is translated to :class:`APIError`.
+    """
+    try:
+        return _retry_decorator(_execute_request)(session, method, url, **kwargs)
+    except _TransientHTTPError as e:
+        response = getattr(e, "response", None)
+        status = response.status_code if response is not None else 0
+        raise APIError(status, str(e)) from e
+    except _RetryableRequestError as e:
+        raise APIError(0, str(e)) from e


 class GiteaClient:
@@ -56,49 +117,7 @@ class GiteaClient:
        return f"{self._base_url}/repos/{self._owner}/{self._repo}{path}"

    def _request(self, method: str, path: str, **kwargs: Any) -> requests.Response:
-        url = self._url(path)
-        last_exc: Exception | None = None
-        for attempt in range(MAX_RETRIES):
-            try:
-                response = self._session.request(method, url, timeout=DEFAULT_TIMEOUT, **kwargs)
-                response.raise_for_status()
-                return response
-            except requests.HTTPError as e:
-                status, message = _parse_error(e)
-                if _is_retryable(e) and attempt < MAX_RETRIES - 1:
-                    wait = RETRY_BACKOFF_BASE ** (attempt + 1)
-                    logger.warning(
-                        "Transient HTTP %d on %s %s, retrying in %ds (attempt %d/%d)",
-                        status,
-                        method,
-                        path,
-                        wait,
-                        attempt + 1,
-                        MAX_RETRIES,
-                    )
-                    time.sleep(wait)
-                    last_exc = e
-                    continue
-                raise APIError(status, message) from e
-            except (requests.ConnectionError, requests.Timeout) as e:
-                if attempt < MAX_RETRIES - 1:
-                    wait = RETRY_BACKOFF_BASE ** (attempt + 1)
-                    logger.warning(
-                        "Connection error on %s %s, retrying in %ds (attempt %d/%d)",
-                        method,
-                        path,
-                        wait,
-                        attempt + 1,
-                        MAX_RETRIES,
-                    )
-                    time.sleep(wait)
-                    last_exc = e
-                    continue
-                raise APIError(0, str(e)) from e
-        # Should not reach here, but just in case
-        if last_exc:  # pragma: no cover
-            raise APIError(0, str(last_exc)) from last_exc
-        raise APIError(0, "Max retries exceeded")  # pragma: no cover
+        return _request_with_retry(self._session, self._url(path), method, **kwargs)

    # -- repo settings --

@@ -175,6 +194,19 @@ class GiteaClient:
        payload = {"Do": "squash", "MergeTitleField": merge_title}
        self._request("POST", f"/pulls/{pr_number}/merge", json=payload)

+    def update_pr_branch(self, pr_number: str | int, style: str = "rebase") -> None:
+        """Update PR head branch by merging/rebasing the base branch into it.
+
+        Uses the Gitea API ``POST /pulls/{index}/update?style=rebase`` endpoint.
+        This rebases the PR's head branch onto the latest base branch server-side,
+        triggering a ``pull_request synchronize`` event that starts a new CI run.
+
+        Args:
+            pr_number: PR number.
+            style: Update method — ``"rebase"`` (default) or ``"merge"``.
+        """
+        self._request("POST", f"/pulls/{pr_number}/update", params={"style": style})
+
    def get_commit_status(self, sha: str) -> list[dict[str, Any]]:
        """Fetch all status check contexts reported for a commit.

@@ -192,11 +224,51 @@ class GiteaClient:
        r = self._request("GET", f"/pulls/{pr_number}")
        return r.json()

+    def create_pr(self, title: str, head: str, base: str = "master", body: str = "") -> dict[str, Any]:
+        """Create a pull request and return the PR dict.
+
+        Args:
+            title: PR title.
+            head: Head branch name.
+            base: Base branch name (default: master).
+            body: PR description (markdown).
+        """
+        payload: dict[str, Any] = {"title": title, "head": head, "base": base}
+        if body:
+            payload["body"] = body
+        r = self._request("POST", "/pulls", json=payload)
+        return r.json()
+
+    def list_prs(self, state: str = "all", **params: Any) -> list[dict[str, Any]]:
+        """List pull requests, optionally filtered by state.
+
+        Args:
+            state: ``open``, ``closed``, ``all`` (default).
+            **params: Additional query params (e.g. ``q="keyword"`` for title search).
+        """
+        params.setdefault("state", state)
+        r = self._request("GET", "/pulls", params=params)
+        return r.json()
+
    def get_pr_files(self, pr_number: str | int) -> list[dict[str, Any]]:
        """Fetch the list of files changed in a pull request."""
        r = self._request("GET", f"/pulls/{pr_number}/files")
        return r.json()

+    def add_pr_label(self, pr_number: str | int, label_names: list[str]) -> None:
+        """Attach labels to a PR/issue by name.
+
+        Args:
+            pr_number: PR or issue number.
+            label_names: List of label names to attach.
+        """
+        self._request("POST", f"/issues/{pr_number}/labels", json={"labels": label_names})
+
+    def get_pr_label_names(self, pr_number: str | int) -> list[str]:
+        """Return label names currently attached to a PR/issue."""
+        r = self._request("GET", f"/issues/{pr_number}/labels")
+        return [label.get("name", "") for label in r.json()]
+
    def get_pr_commits(self, pr_number: str | int) -> list[dict[str, Any]]:
        """Fetch the commits included in a pull request."""
        r = self._request("GET", f"/pulls/{pr_number}/commits")
@@ -275,6 +347,60 @@ class GiteaClient:
            return existing
        return self.create_release(tag=tag, name=name, body=body, draft=draft, prerelease=prerelease)

+    # -- actions (CI/CD) --
+
+    def list_action_runs(self, **params: Any) -> dict[str, Any]:
+        """List workflow runs for the repository.
+
+        Returns the raw API response dict (includes ``workflow_runs`` and
+        ``total_count`` keys per Gitea API).
+        """
+        r = self._request("GET", "/actions/runs", params=params)
+        return r.json()
+
+    def get_action_run_jobs(self, run_id: str | int) -> list[dict[str, Any]]:
+        """List jobs for a specific workflow run."""
+        r = self._request("GET", f"/actions/runs/{run_id}/jobs")
+        data = r.json()
+        return data.get("jobs", [])
+
+    def get_action_job_logs(self, job_id: str | int) -> str:
+        """Fetch logs for a specific CI job.
+
+        Returns the raw log text. Raises APIError if logs are unavailable.
+        """
+        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 PATCH first; if the variable doesn't exist (404), creates it
+        via POST.
+        """
+        try:
+            self._request("PATCH", f"/actions/variables/{name}", json={"value": value})
+        except APIError as e:
+            if e.status != 404:
+                raise
+            self._request("POST", "/actions/variables", json={"name": name, "value": value})
+

 class VikunjaClient:
    """Low-level Vikunja REST API client with connection pooling."""
@@ -286,47 +412,7 @@ class VikunjaClient:

    def _request(self, method: str, path: str, **kwargs: Any) -> requests.Response:
        url = f"{self._base_url}{path}"
-        last_exc: Exception | None = None
-        for attempt in range(MAX_RETRIES):
-            try:
-                response = self._session.request(method, url, timeout=DEFAULT_TIMEOUT, **kwargs)
-                response.raise_for_status()
-                return response
-            except requests.HTTPError as e:
-                status, message = _parse_error(e)
-                if _is_retryable(e) and attempt < MAX_RETRIES - 1:
-                    wait = RETRY_BACKOFF_BASE ** (attempt + 1)
-                    logger.warning(
-                        "Transient HTTP %d on %s %s, retrying in %ds (attempt %d/%d)",
-                        status,
-                        method,
-                        path,
-                        wait,
-                        attempt + 1,
-                        MAX_RETRIES,
-                    )
-                    time.sleep(wait)
-                    last_exc = e
-                    continue
-                raise APIError(status, message) from e
-            except (requests.ConnectionError, requests.Timeout) as e:
-                if attempt < MAX_RETRIES - 1:
-                    wait = RETRY_BACKOFF_BASE ** (attempt + 1)
-                    logger.warning(
-                        "Connection error on %s %s, retrying in %ds (attempt %d/%d)",
-                        method,
-                        path,
-                        wait,
-                        attempt + 1,
-                        MAX_RETRIES,
-                    )
-                    time.sleep(wait)
-                    last_exc = e
-                    continue
-                raise APIError(0, str(e)) from e
-        if last_exc:  # pragma: no cover
-            raise APIError(0, str(last_exc)) from last_exc
-        raise APIError(0, "Max retries exceeded")  # pragma: no cover
+        return _request_with_retry(self._session, url, method, **kwargs)

    def list_tasks(self, **params: Any) -> list[dict[str, Any]]:
        r = self._request("GET", "/tasks", params=params)
@@ -342,8 +428,65 @@ class VikunjaClient:
        r = self._request("GET", f"/projects/{project_id}/tasks", params=params)
        return r.json()

+    def find_task_by_identifier(self, project_id: int, identifier: str, per_page: int = 50) -> dict[str, Any] | None:
+        """Find a task by its identifier (e.g. ``DEVX-42``) in a project.
+
+        Paginates through all tasks in the project. Returns the task dict
+        or None if not found.
+        """
+        page = 1
+        while True:
+            tasks = self.list_project_tasks(project_id, page=page, per_page=per_page)
+            if not tasks:
+                break
+            for t in tasks:
+                if t.get("identifier") == identifier:
+                    return t
+            if len(tasks) < per_page:
+                break
+            page += 1
+        return None
+
+    def create_task(self, project_id: int, title: str, description: str = "") -> dict[str, Any]:
+        """Create a task in a project and return the created task dict.
+
+        Args:
+            project_id: Target Vikunja project ID.
+            title: Task title (required, non-empty).
+            description: Task description (HTML supported, optional).
+        """
+        r = self._request(
+            "PUT",
+            f"/projects/{project_id}/tasks",
+            json={"title": title, "description": description},
+        )
+        return r.json()
+
    def post_comment(self, task_id: int, comment: str) -> None:
        self._request("PUT", f"/tasks/{task_id}/comments", json={"comment": comment})

+    def list_comments(self, task_id: int) -> list[dict[str, Any]]:
+        """List all comments on a task."""
+        r = self._request("GET", f"/tasks/{task_id}/comments")
+        return r.json()
+
    def update_task(self, task_id: int, **fields: Any) -> None:
+        """Update task fields via POST (full replacement semantics).
+
+        Warning: Vikunja's POST /tasks/{id} replaces the entire task body.
+        Unspecified fields are reset to their type defaults. Use
+        ``update_task_safe`` to preserve existing fields.
+        """
        self._request("POST", f"/tasks/{task_id}", json=fields)
+
+    def update_task_safe(self, task_id: int, **fields: Any) -> dict[str, Any]:
+        """Safely update task fields using read-merge-write pattern.
+
+        Fetches the full task body, merges the provided fields on top,
+        and POSTs the complete body back. This prevents accidental
+        resets of done status, title, etc.
+        """
+        task = self.get_task(task_id)
+        task.update(fields)
+        r = self._request("POST", f"/tasks/{task_id}", json=task)
+        return r.json()
@@ -2,8 +2,14 @@

 from __future__ import annotations

+import os
 import subprocess  # nosec B404

+import click
+
+from devx.config import TASK_ID_RE
+from devx.i18n import _
+

 def get_latest_tag() -> str:
    """Get the latest git tag, or empty string if none exists."""
@@ -16,3 +22,97 @@ def get_latest_tag() -> str:
    if result.returncode != 0:
        return ""
    return result.stdout.strip()
+
+
+def run_cmd(
+    args: list[str],
+    check: bool = True,
+    capture: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    """Run a command and return the completed process.
+
+    Args:
+        args: Command and arguments as a list.
+        check: If True, raise :class:`click.ClickException` on non-zero exit.
+        capture: If True, capture stdout/stderr. If False, inherit parent's.
+    """
+    result = subprocess.run(  # nosec B603
+        args,
+        capture_output=capture,
+        text=True,
+        check=False,
+    )
+    if check and result.returncode != 0:
+        raise click.ClickException(
+            _(
+                "Command failed ({cmd}): {stderr}",
+                cmd=" ".join(args),
+                stderr=result.stderr.strip() if result.stderr else result.stdout.strip(),
+            )
+        )
+    return result
+
+
+def extract_task_id(text: str) -> str:
+    """Extract the ``{PREFIX}-N`` task identifier from *text*.
+
+    Returns the matched string (e.g. ``DEVX-42``) or an empty string if
+    no task ID is found.
+    """
+    match = TASK_ID_RE.search(text)
+    return match.group(0) if match else ""
+
+
+def write_github_env(key: str, value: str) -> None:
+    """Append a key=value line to the ``$GITHUB_ENV`` file.
+
+    Multi-line values use the heredoc syntax required by Gitea Actions.
+    Raises :class:`click.ClickException` if ``GITHUB_ENV`` is not set.
+    """
+    gh_env = os.environ.get("GITHUB_ENV")
+    if not gh_env:
+        raise click.ClickException("GITHUB_ENV environment variable is not set")
+    with open(gh_env, "a", encoding="utf-8") as f:  # noqa: PTH123
+        if "\n" in value:
+            delimiter = "EOF"
+            f.write(f"{key}<<{delimiter}\n{value}\n{delimiter}\n")
+        else:
+            f.write(f"{key}={value}\n")
+
+
+def write_github_output(key: str, value: str) -> None:
+    """Append a key=value line to the ``$GITHUB_OUTPUT`` file.
+
+    Raises :class:`click.ClickException` if ``GITHUB_OUTPUT`` is not set.
+    """
+    gh_output = os.environ.get("GITHUB_OUTPUT")
+    if not gh_output:
+        raise click.ClickException("GITHUB_OUTPUT environment variable is not set")
+    with open(gh_output, "a", encoding="utf-8") as f:  # noqa: PTH123
+        f.write(f"{key}={value}\n")
+
+
+def lpt_distribute[T](items: list[T], weights: list[int], max_runners: int) -> list[list[T]]:
+    """Distribute *items* across *max_runners* using LPT scheduling.
+
+    Sorts items by weight (descending), then assigns each to the runner
+    with the least total weight. This produces a more balanced distribution
+    than naive round-robin when items have varying costs.
+
+    Args:
+        items: Items to distribute.
+        weights: Parallel list of integer weights (higher = heavier).
+        max_runners: Number of runner groups to create.
+
+    Returns:
+        A list of ``max_runners`` lists, each containing the items assigned
+        to that runner.
+    """
+    groups: list[list[T]] = [[] for _ in range(max_runners)]
+    loads = [0] * max_runners
+    indexed = sorted(enumerate(items), key=lambda x: (-weights[x[0]], x[0]))
+    for orig_idx, item in indexed:
+        min_runner = min(range(max_runners), key=lambda r: loads[r])
+        groups[min_runner].append(item)
+        loads[min_runner] += weights[orig_idx]
+    return groups
@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
 """Auto-merge PR when all CI checks pass.

-Runs as the final job in ci.yml. Reads the task ID from ``.taskid`` file
-(falling back to branch name extraction for backwards compatibility),
-validates the PR title, and squash-merges with a conventional commit
-message prefixed by the task ID.
+Runs as the final job in ci.yml. Reads the task ID from the branch name
+(e.g., ``DEVX-31-fix-foo`` → ``DEVX-31``), validates the PR title against
+the Vikunja task, and squash-merges with a conventional commit message
+prefixed by the task ID.

 PR title format:    ``{PREFIX}-N: <vikunja task title>``
 Merge commit format: ``{PREFIX}-N <conventional commit message>``
@@ -17,12 +17,11 @@ This allows the PR title to be a human-friendly Vikunja task title
 while the squashed commit follows conventional commits.

 Usage:
-  REPO_TOKEN=<token> python3 -m devx.ci.auto_merge <branch> <pr_title> <repo> <pr_number>
+  CI_GITEA_TOKEN=<token> python3 -m devx.ci.auto_merge <branch> <pr_title> <repo> <pr_number>
 """

 import os
 import re
-import subprocess  # nosec B404
 from pathlib import Path
 from typing import Any

@@ -30,11 +29,11 @@ import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]

 from devx.api_clients import GiteaClient, VikunjaClient
+from devx.ci._shared import extract_task_id as _extract_task_id
 from devx.config import (
    CONVENTIONAL_RE,
    DEFAULT_PER_PAGE,
    GITEA_API_URL,
-    TASK_ID_RE,
    TASK_PREFIX,
    VIKUNJA_API_URL,
    VIKUNJA_PROJECT_ID,
@@ -42,47 +41,47 @@ from devx.config import (
 from devx.exceptions import APIError
 from devx.i18n import _

-TASKID_FILE = ".taskid"
+# 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*")
+
+TASKID_FILE = ".taskid"  # Deprecated, kept for backward-compat warnings
 PR_TITLE_RE = re.compile(rf"^{TASK_PREFIX}-\d+:\s+.+")

 load_dotenv()


-def run_cmd(args: list[str], check: bool = True) -> subprocess.CompletedProcess[str]:
-    """Run a command and return the completed process."""
-    result = subprocess.run(args, capture_output=True, text=True, check=False)  # nosec B603
-    if check and result.returncode != 0:
-        raise click.ClickException(
-            _(
-                "Command failed ({cmd}): {stderr}",
-                cmd=" ".join(args),
-                stderr=result.stderr.strip() or result.stdout.strip(),
-            )
-        )
-    return result
-
-
 def read_taskid(branch: str) -> str:
-    """Read task ID from .taskid file, falling back to branch name extraction.
+    """Read task ID from branch name.

-    The .taskid file is a simple text file containing just the task ID
-    (e.g., ``DEVX-60``).  If the file doesn't exist, extract from the
-    branch name as a backwards-compatibility fallback.
+    The branch name is the sole source of truth for the task ID
+    (e.g., ``DEVX-31-fix-foo`` → ``DEVX-31``).  Branches must include
+    the task ID prefix — there is no ``.taskid`` file fallback.
+
+    If a stale ``.taskid`` file exists and disagrees with the branch
+    name, a deprecation warning is printed advising its removal.
    """
-    path = Path(TASKID_FILE)
-    if path.exists():
-        task_id = path.read_text(encoding="utf-8").strip()
-        if task_id:
-            return task_id
-    # Fallback: extract from branch name
-    match = TASK_ID_RE.search(branch)
-    return match.group(0) if match else ""
+    branch_task_id = extract_task_id(branch)
+    if branch_task_id:
+        # Warn about stale .taskid file if it exists and disagrees
+        path = Path(TASKID_FILE)
+        if path.exists():
+            file_task_id = path.read_text(encoding="utf-8").strip()
+            if file_task_id and file_task_id != branch_task_id:
+                click.echo(
+                    _(
+                        "WARNING: .taskid file ({file_id}) is deprecated and disagrees with branch name ({branch_id}). "
+                        "Delete .taskid from the repo — branch name is the sole source of truth.",
+                        file_id=file_task_id,
+                        branch_id=branch_task_id,
+                    )
+                )
+        return branch_task_id
+    return ""


 def extract_task_id(branch: str) -> str:
-    """Extract DEVX-N task identifier from branch name (legacy fallback)."""
-    match = TASK_ID_RE.search(branch)
-    return match.group(0) if match else ""
+    """Extract task identifier from branch name (delegates to shared utility)."""
+    return _extract_task_id(branch)


 def validate_pr_title(pr_title: str, task_id: str) -> None:
@@ -162,19 +161,33 @@ def validate_pr_title_matches_vikunja(pr_title: str, task_id: str) -> None:
 def extract_conventional_msg(commits: list[dict[str, Any]]) -> str:
    """Extract the conventional commit message from PR commits.

-    Iterates commits in reverse order (newest first) to find the first
-    message matching the conventional commit format.  Falls back to the
-    newest commit message if none match.
+    Picks the highest-priority conventional commit message from the PR.
+    Priority: feat > fix > refactor > docs > chore > other.
+    Falls back to the newest commit message if none match.
    """
+    priority = {"feat": 5, "fix": 4, "refactor": 3, "docs": 2, "chore": 1, "ci": 1, "style": 1, "test": 1}
+    best_msg = ""
+    best_score = 0
    for commit in reversed(commits):
        commit_info = commit.get("commit", {})
        message = str(commit_info.get("message", "") if isinstance(commit_info, dict) else "").split("\n")[0]
-        if CONVENTIONAL_RE.match(message):
-            return message
-    # Fallback: use the newest commit's first line
+        # Strip any leading task ID prefix (e.g. "OBL-INFRA-364: fix: ...") so
+        # conventional commit matching works on the remainder.
+        stripped = _TASK_ID_PREFIX_RE.sub("", message)
+        m = CONVENTIONAL_RE.match(stripped)
+        if m:
+            prefix = m.group(1).split("(")[0].strip()  # e.g. "feat" from "feat(scope)"
+            score = priority.get(prefix, 0)
+            if score > best_score:
+                best_score = score
+                best_msg = stripped
+    if best_msg:
+        return best_msg
+    # Fallback: use the newest commit's first line (strip task ID prefix if present)
    if commits:
        commit_info = commits[-1].get("commit", {})
-        return str(commit_info.get("message", "") if isinstance(commit_info, dict) else "").split("\n")[0]
+        raw = str(commit_info.get("message", "") if isinstance(commit_info, dict) else "").split("\n")[0]
+        return _TASK_ID_PREFIX_RE.sub("", raw)
    return ""


@@ -184,9 +197,9 @@ 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("REPO_TOKEN", "")
+    token = os.environ.get("CI_GITEA_TOKEN", "")
    if not token:
-        raise click.ClickException(_("ERROR: REPO_TOKEN is not set."))
+        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set."))

    # Validate PR number is an integer
    try:
@@ -204,7 +217,8 @@ def main(branch: str, pr_title: str, repo: str, pr_number: str) -> None:
    if not task_id:
        raise click.ClickException(
            _(
-                "Oops! No task ID found in .taskid file or branch name '{branch}'.",
+                "Oops! No task ID found in branch name '{branch}'. "
+                "Branch names must include the task ID prefix (e.g., DEVX-31-fix-bug).",
                branch=branch,
            )
        )
@@ -224,23 +238,35 @@ def main(branch: str, pr_title: str, repo: str, pr_number: str) -> None:
        client.merge_pr(pr_num, merge_title)
    except APIError as e:
        if e.status == 405 and "behind" in e.message.lower():
-            # Head branch is behind master — pull master and rebase, then retry
-            click.echo(_("Head branch is behind master. Pulling and rebasing..."))
+            # Head branch is behind master. Auto-rebase via Gitea API.
+            # This triggers a new pull_request synchronize event → new CI run.
+            # The next auto-merge attempt will find the branch up-to-date and
+            # merge successfully. This is NOT an infinite loop: the rebase
+            # resolves the "behind" condition, so the next run merges.
+            # If another PR merges in between, the branch may fall behind
+            # again, but the process converges as PRs stop merging.
+            click.echo(
+                _(
+                    "Branch is behind master. Auto-rebasing via Gitea API...\n"
+                    "A new CI run will start automatically after the rebase.\n"
+                    "The next auto-merge attempt will merge this PR.",
+                )
+            )
            try:
-                run_cmd(["git", "config", "user.name", "devx-ci-bot"])
-                run_cmd(["git", "config", "user.email", "devx-ci-bot@oblachno.fyi"])
-                run_cmd(["git", "fetch", "origin", "master"])
-                run_cmd(["git", "rebase", "origin/master"])
-                run_cmd(["git", "push", "--force-with-lease", "origin", f"HEAD:{branch}"])
-                click.echo(_("Rebased and pushed. Retrying merge..."))
-                client.merge_pr(pr_num, merge_title)
-            except (APIError, Exception) as retry_err:
+                client.update_pr_branch(pr_num, style="rebase")
+            except APIError as rebase_err:
                raise click.ClickException(
                    _(
-                        "Merge failed after rebase retry: {error}\nPlease rebase the PR manually.",
-                        error=str(retry_err),
+                        "Auto-rebase failed with HTTP {status}: {message}\n"
+                        "Rebase manually:\n"
+                        "  git fetch origin master && git rebase origin/master && git push --force-with-lease\n"
+                        "Then re-add the ready-to-merge label.",
+                        status=rebase_err.status,
+                        message=rebase_err.message,
                    )
                ) from None
+            # Exit cleanly — the rebase triggers a new CI run that will retry.
+            return
        else:
            raise click.ClickException(
                _(
@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""Pre-merge validation gate for auto-merge preconditions.
+
+Validates that a PR satisfies auto-merge requirements BEFORE expensive
+jobs (molecule tests, staging deploy) run.  This catches issues early:
+
+1. Branch name contains a task ID (e.g., ``DEVX-256-fix-foo``).
+2. PR title follows ``{PREFIX}-N: <title>`` format.
+3. PR title task ID matches the branch task ID.
+4. PR title matches the Vikunja task title (requires ``VIKUNJA_TOKEN``).
+5. Branch is not behind master (would trigger a rebase retry cycle).
+
+Exit code 0 = ready for auto-merge (preconditions satisfied).
+Exit code 1 = NOT ready — fix issues before pushing.
+
+Usage::
+
+  # CI (with VIKUNJA_TOKEN and CI_GITEA_TOKEN):
+  python3 -m devx.ci.check_auto_merge_ready \\
+      --branch "$HEAD_REF" \\
+      --pr-title "$PR_TITLE" \\
+      --repo "$REPOSITORY" \\
+      --pr-number "$PR_NUMBER"
+
+  # Local (pre-push hook, no PR yet — validates branch + title format only):
+  python3 -m devx.ci.check_auto_merge_ready --branch "$(git rev-parse --abbrev-ref HEAD)"
+
+  # Local (with PR number, fetches title from Gitea):
+  python3 -m devx.ci.check_auto_merge_ready --branch "$(git rev-parse --abbrev-ref HEAD)" \\
+      --repo owner/repo --pr-number 123
+
+If ``VIKUNJA_TOKEN`` is not set, the Vikunja title match check is
+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
+branch-name and PR-title-format checks run (local mode).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess  # nosec B404
+
+import click
+from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
+
+from devx.api_clients import GiteaClient, VikunjaClient
+from devx.ci.auto_merge import extract_task_id
+from devx.config import (
+    GITEA_API_URL,
+    VIKUNJA_API_URL,
+    VIKUNJA_PROJECT_ID,
+)
+from devx.exceptions import APIError
+from devx.i18n import _
+
+load_dotenv()
+
+
+def is_branch_behind_master(branch: str) -> bool:
+    """Check if the local branch is behind origin/master.
+
+    Fetches origin first (best-effort) then compares commit counts.
+    Returns ``True`` if master has commits not in branch.
+    """
+    try:
+        subprocess.run(  # nosec B603, B607
+            ["git", "fetch", "origin", "master", "--quiet"],
+            check=False,
+            capture_output=True,
+            timeout=30,
+        )
+        result = subprocess.run(  # nosec B603, B607
+            ["git", "rev-list", "--count", f"origin/master..{branch}"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            return False  # Can't determine — don't block
+        result = subprocess.run(  # nosec B603, B607
+            ["git", "rev-list", "--count", f"{branch}..origin/master"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            return False
+        behind = int(result.stdout.strip() or "0")
+    except (subprocess.TimeoutExpired, FileNotFoundError, ValueError):
+        return False  # Don't block on git errors
+    return behind > 0
+
+
+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.
+    """
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    if not token or "/" not in repo:
+        return None
+    owner, repo_name = repo.split("/", 1)
+    client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
+    try:
+        pr = client.get_pr(pr_number)
+        return str(pr.get("title", ""))
+    except APIError:
+        return None
+
+
+def get_vikunja_title_optional(task_id: str) -> str | None:
+    """Fetch the Vikunja task title, returning None if token is not set.
+
+    Unlike :func:`devx.ci.auto_merge.get_vikunja_task_title`, this does NOT
+    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:
+        return None
+    client = VikunjaClient(VIKUNJA_API_URL, token)
+    from devx.config import DEFAULT_PER_PAGE
+
+    page = 1
+    while True:
+        tasks = client.list_project_tasks(VIKUNJA_PROJECT_ID, page=page, per_page=DEFAULT_PER_PAGE)
+        if not tasks:
+            break
+        matches = [t for t in tasks if t.get("identifier") == task_id]
+        if matches:
+            return str(matches[0].get("title", ""))
+        if len(tasks) < DEFAULT_PER_PAGE:
+            break
+        page += 1
+    return None
+
+
+@click.command()
+@click.option("--branch", required=True, help=_("Branch name (e.g., DEVX-256-fix-foo)"))
+@click.option("--pr-title", default=None, help=_("PR title (auto-fetched if --pr-number given)"))
+@click.option("--repo", default=None, help=_("Repository in owner/name format"))
+@click.option("--pr-number", type=int, default=None, help=_("PR number (to fetch title from Gitea)"))
+@click.option("--skip-vikunja", is_flag=True, help=_("Skip Vikunja title match check"))
+@click.option("--skip-behind-check", is_flag=True, help=_("Skip branch-behind-master check"))
+def cli(
+    branch: str,
+    pr_title: str | None,
+    repo: str | None,
+    pr_number: int | None,
+    skip_vikunja: bool,
+    skip_behind_check: bool,
+) -> None:
+    """Validate auto-merge preconditions before expensive CI jobs."""
+    import re
+
+    from devx.config import TASK_PREFIX
+
+    pr_title_re = re.compile(rf"^{TASK_PREFIX}-\d+:\s+.+")  # noqa: PLW1503
+
+    errors: list[str] = []
+
+    # 1. Branch task ID
+    task_id = extract_task_id(branch)
+    if not task_id:
+        errors.append(
+            _(
+                "No task ID found in branch name '{branch}'. Expected format: {prefix}-N-description.",
+                branch=branch,
+                prefix=TASK_PREFIX,
+            ),
+        )
+        # Can't continue — no task ID to validate against
+        for e in errors:
+            click.echo(f"ERROR: {e}", err=True)
+        raise click.ClickException(_("Branch name must contain a task ID."))
+
+    click.echo(f"[pre-merge-check] Task ID: {task_id}")
+
+    # 2. Resolve PR title
+    if pr_title is None and pr_number is not None and repo is not None:
+        pr_title = get_pr_title_from_gitea(repo, pr_number)
+        if pr_title:
+            click.echo(f"[pre-merge-check] PR title (from Gitea): {pr_title}")
+
+    if pr_title is None:
+        # Local mode without PR — only validate branch name
+        if pr_number is not None:
+            raise click.ClickException(
+                _("Could not fetch PR title from Gitea (CI_GITEA_TOKEN not set or PR not found).")
+            )
+        click.echo("[pre-merge-check] No PR title provided — running branch-name-only check (local mode).")
+        click.echo("[pre-merge-check] Branch name OK. Push to create PR, then CI will validate the title.")
+        return
+
+    # 3. PR title format
+    if not pr_title_re.match(pr_title):
+        errors.append(
+            _(
+                "PR title must follow format '{prefix}-N: <task title>'.\n  Got: {title}",
+                prefix=TASK_PREFIX,
+                title=pr_title,
+            ),
+        )
+
+    # 4. PR title task ID matches branch task ID
+    if not pr_title.startswith(f"{task_id}:"):
+        errors.append(
+            _(
+                "PR title task ID mismatch.\n  Branch task ID: {task_id}\n  PR title:       {title}",
+                task_id=task_id,
+                title=pr_title,
+            ),
+        )
+
+    # 5. Vikunja task title match (skip if no token or --skip-vikunja)
+    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", ""))
+            if token_set:
+                errors.append(
+                    _(
+                        "Could not find Vikunja task {task_id} in project {project_id}.",
+                        task_id=task_id,
+                        project_id=VIKUNJA_PROJECT_ID,
+                    ),
+                )
+            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:
+                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:
+        if is_branch_behind_master(branch):
+            errors.append(
+                _("Branch is behind origin/master. Rebase first: git fetch origin master && git rebase origin/master")
+            )
+        else:
+            click.echo("[pre-merge-check] Branch is up-to-date with origin/master.")
+
+    if errors:
+        click.echo("", err=True)
+        click.echo("=" * 60, err=True)
+        click.echo("Pre-merge validation FAILED — fix these before pushing:", err=True)
+        click.echo("=" * 60, err=True)
+        for e in errors:
+            click.echo(f"  - {e}", err=True)
+        raise click.ClickException(_("Pre-merge validation failed."))
+
+    click.echo("[pre-merge-check] All auto-merge preconditions satisfied.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover
@@ -11,8 +11,8 @@ Checks performed (all fail with exit code 1 on error):
 - **Missing keys**: a ``_()`` call in code has no entry in the corresponding
  translations file.
 - **Dead keys**: a key in a translations file is not used in any code.
- **Missing languages**: a key exists but is missing one of the 5 supported
-  languages (en, bg, de, ru, zh). This is an error — all supported languages
+- **Missing languages**: a key exists but is missing one of the 6 supported
+  languages (en, bg, de, ru, zh, pl). This is an error — all supported languages
  must have translations for every key.

 Usage::
@@ -31,11 +31,11 @@ from pathlib import Path

 import click

-REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+REPO_ROOT = Path.cwd()

-SUPPORTED_LANGS = ("en", "bg", "de", "ru", "zh")
+SUPPORTED_LANGS = ("en", "bg", "de", "ru", "zh", "pl")

-# Default translation set: devx package itself
+# Default translation set: look for translations.json in the current repo
 DEFAULT_TRANS_FILE = REPO_ROOT / "src" / "devx" / "translations.json"
 DEFAULT_SRC_DIR = REPO_ROOT / "src" / "devx"

@@ -101,9 +101,9 @@ def collect_keys(src_dir: Path) -> set[str]:
        if pyfile.name == "i18n.py":
            continue
        keys |= extract_keys(pyfile)
-    # Add dynamic keys for the default source directory
-    if src_dir == DEFAULT_SRC_DIR:
-        keys |= DYNAMIC_KEYS
+    # Dynamic keys are common status strings used via _(variable) that
+    # can't be detected by AST scanning. Include them for all projects.
+    keys |= DYNAMIC_KEYS
    return keys


@@ -169,20 +169,44 @@ def print_result(result: TranslationCheckResult) -> None:
    "translations",
    multiple=True,
    type=click.Path(exists=False, path_type=Path),
-    help="Path to a translations JSON file to check (can be repeated). Defaults to src/devx/translations.json.",
+    help="Path to a translations JSON file to check (can be repeated). Auto-detects by default.",
 )
-def main(translations: tuple[Path, ...]) -> None:
+@click.option(
+    "--source-dir",
+    default=None,
+    help="Source directory to scan for _() calls (default: auto-detect).",
+)
+def main(translations: tuple[Path, ...], source_dir: str | None) -> None:
    """Check translation files for gaps, dead keys, and missing languages."""
+    results: list[TranslationCheckResult] = []
    if not translations:
-        # Default: check the devx package's own translations
-        results = [
-            check_translation_set("devx", DEFAULT_SRC_DIR, DEFAULT_TRANS_FILE),
+        # Auto-detect translations file in the current repo
+        root = Path.cwd()
+        # Try common locations
+        candidates = [
+            root / "src" / "devx" / "translations.json",
+            root / "src" / "grm" / "translations.json",
        ]
+        # Also search for any translations.json in src/
+        for match in root.glob("src/*/translations.json"):
+            candidates.append(match)
+
+        found = False
+        for candidate in candidates:
+            if candidate.exists():
+                src_dir = Path(source_dir) if source_dir else candidate.parent
+                results.append(check_translation_set(candidate.parent.name, src_dir, candidate))
+                found = True
+                break
+
+        if not found:
+            # No translations file found — this repo doesn't use i18n
+            click.echo("PASS: No translations file found — skipping (repo does not use i18n).")
+            return
    else:
-        results = []
        for trans_file in translations:
            # Infer source directory as the parent of the translations file
-            src_dir = trans_file.parent
+            src_dir = Path(source_dir) if source_dir else trans_file.parent
            name = trans_file.parent.name
            results.append(check_translation_set(name, src_dir, trans_file))

@@ -138,7 +138,7 @@ from typing import Any

 import click

-from devx.ci._shared import get_latest_tag
+from devx.ci._shared import get_latest_tag, write_github_output
 from devx.i18n import _

 # ---------------------------------------------------------------------------
@@ -298,8 +298,6 @@ DEFAULT_INFRASTRUCTURE: list[str] = [
    "activate.sh",
    "activate.fish",
    "activate.zsh",
-    # CI task tracking file (written by CI, not by developers)
-    ".taskid",
 ]


@@ -395,14 +393,15 @@ class ChangeClassifier:
        tags = self._compute_tags(file_path)

        # 1. User-facing overrides (highest priority — safety)
-        if file_path in self._user_overrides:
-            return FileClassification(
-                path=file_path,
-                is_user_facing=True,
-                reason="User-facing override (safety override)",
-                matched_rule="user_facing_overrides",
-                tags=tags,
-            )
+        for pattern in self._user_overrides:
+            if _matches_glob(file_path, pattern):
+                return FileClassification(
+                    path=file_path,
+                    is_user_facing=True,
+                    reason=f"User-facing override (matches '{pattern}')",
+                    matched_rule="user_facing_overrides",
+                    tags=tags,
+                )

        # 2. Infrastructure overrides
        if file_path in self._infra_overrides:
@@ -585,15 +584,8 @@ def has_user_facing_changes(
 # ---------------------------------------------------------------------------


-def _write_github_output(key: str, value: str) -> None:
-    """Append a key=value line to the $GITHUB_OUTPUT file."""
-    gh_output = os.environ.get("GITHUB_OUTPUT")
-    if not gh_output:
-        raise click.ClickException("GITHUB_OUTPUT environment variable is not set")
-    with open(gh_output, "a") as f:  # noqa: PTH123
-        f.write(f"{key}={value}\n")
-
-
+# ---------------------------------------------------------------------------
+# Classification logic
 # ---------------------------------------------------------------------------
 # CLI
 # ---------------------------------------------------------------------------
@@ -617,18 +609,36 @@ def _write_github_output(key: str, value: str) -> None:
    help="Write results to $GITHUB_OUTPUT file (for CI workflow steps). "
    "Outputs 'user-facing-changed' and '<tag>-changed' for each configured tag.",
 )
-def main(base: str | None, head: str, quiet: bool, check: str, github_output: bool) -> None:
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Force user-facing-changed=true regardless of actual changes. "
+    "Used by workflow_dispatch with force-deploy input.",
+)
+def main(base: str | None, head: str, quiet: bool, check: str, github_output: bool, force: bool) -> None:
    """Classify git changes and output results."""
    classifier = _get_classifier()
    available_tags = list(classifier.config.tags.keys())

+    # --force can also be activated via FORCE_DEPLOY env var (for workflow_dispatch)
+    if os.environ.get("FORCE_DEPLOY", "").lower() == "true":
+        force = True
+
+    if force and github_output:
+        write_github_output("user-facing-changed", "true")
+        for tag in available_tags:
+            write_github_output(f"{tag}-changed", "true")
+        click.echo("Forced user-facing-changed=true via --force flag.")
+        return
+
    if base is None:
        base = get_latest_tag()
        if not base:
            if github_output:
-                _write_github_output("user-facing-changed", "true")
+                write_github_output("user-facing-changed", "true")
                for tag in available_tags:
-                    _write_github_output(f"{tag}-changed", "true")
+                    write_github_output(f"{tag}-changed", "true")
                click.echo("No tags found — treating all changes as user-facing.")
                return
            if quiet:
@@ -640,9 +650,9 @@ def main(base: str | None, head: str, quiet: bool, check: str, github_output: bo
    files = get_changed_files(base, head)
    if not files:
        if github_output:
-            _write_github_output("user-facing-changed", "false")
+            write_github_output("user-facing-changed", "false")
            for tag in available_tags:
-                _write_github_output(f"{tag}-changed", "false")
+                write_github_output(f"{tag}-changed", "false")
            click.echo(f"No changes between {base} and {head}.")
            return
        if quiet:
@@ -654,9 +664,9 @@ def main(base: str | None, head: str, quiet: bool, check: str, github_output: bo
    result = classifier.classify(files)

    if github_output:
-        _write_github_output("user-facing-changed", "true" if result.has_user_facing else "false")
+        write_github_output("user-facing-changed", "true" if result.has_user_facing else "false")
        for tag in available_tags:
-            _write_github_output(f"{tag}-changed", "true" if result.has_tag(tag) else "false")
+            write_github_output(f"{tag}-changed", "true" if result.has_tag(tag) else "false")
        click.echo(f"User-facing files changed: {result.has_user_facing}")
        for tag in available_tags:
            click.echo(f"{tag.capitalize()} files changed: {result.has_tag(tag)}")
@@ -1,7 +1,10 @@
 #!/usr/bin/env python3
-"""Detect whether the latest git commit is a release commit.
+"""Detect whether the latest git commit is an automated CI commit.
+
+Release commits have the format ``release: vX.Y.Z``.
+Badge commits have the format ``chore: update badge URLs ... [skip ci]``.
+Both are generated by CI and should skip post-merge jobs.

-Release commits have the format ``release: vX.Y.Z [skip ci]``.
 This script writes ``is-release=true`` or ``is-release=false`` to
 ``$GITHUB_OUTPUT`` for use in CI workflow conditionals.

@@ -12,13 +15,16 @@ Usage::

 from __future__ import annotations

-import os
 import re
 import subprocess  # nosec B404

 import click

+from devx.ci._shared import write_github_output
+from devx.i18n import _
+
 RELEASE_RE = re.compile(r"^release: v\d+\.\d+\.\d+")
+BADGE_RE = re.compile(r"^chore: update badge URLs.*\[skip ci\]")


 def get_commit_message() -> str:
@@ -39,26 +45,31 @@ def is_release_commit(message: str) -> bool:
    return bool(RELEASE_RE.match(message))


-def write_github_output(key: str, value: str) -> None:
-    """Append a key=value line to the $GITHUB_OUTPUT file."""
-    gh_output = os.environ.get("GITHUB_OUTPUT")
-    if not gh_output:
-        raise click.ClickException("GITHUB_OUTPUT environment variable is not set")
-    with open(gh_output, "a") as f:  # noqa: PTH123
-        f.write(f"{key}={value}\n")
+def is_badge_commit(message: str) -> bool:
+    """Check if a commit message matches the badge commit format."""
+    return bool(BADGE_RE.match(message))
+
+
+def is_automated_commit(message: str) -> bool:
+    """Check if a commit is an automated CI commit (release or badge)."""
+    return is_release_commit(message) or is_badge_commit(message)


@click.command()
 def main() -> None:
-    """Detect if the latest commit is a release commit and set GITHUB_OUTPUT."""
+    """Detect if the latest commit is an automated CI commit and set GITHUB_OUTPUT."""
    msg = get_commit_message()
-    click.echo(f"Commit message: {msg}")
+    click.echo(_("Commit message: {msg}", msg=msg))
    is_release = is_release_commit(msg)
+    is_automated = is_automated_commit(msg)
    write_github_output("is-release", "true" if is_release else "false")
+    write_github_output("is-automated", "true" if is_automated else "false")
    if is_release:
-        click.echo("Release commit — skipping all post-merge jobs.")
+        click.echo(_("Release commit — skipping all post-merge jobs."))
+    elif is_automated:
+        click.echo(_("Automated CI commit (badge) — skipping post-merge jobs."))
    else:
-        click.echo("Regular merge commit — running all post-merge jobs.")
+        click.echo(_("Regular merge commit — running all post-merge jobs."))


 if __name__ == "__main__":  # pragma: no cover
@@ -29,7 +29,8 @@ import os
 import click
 import requests

-from devx.config import GITEA_API_URL
+from devx.config import GITEA_API_URL, REPO_NAME, REPO_OWNER
+from devx.i18n import _

 DEFAULT_MAX_RUNNERS = 3

@@ -55,9 +56,9 @@ def query_runners(api_url: str, token: str, owner: str, repo: str) -> int:
            data = r.json()
            total += data.get("total_count", 0)
        else:
-            click.echo(f"Warning: repo-level runners query returned HTTP {r.status_code}", err=True)
+            click.echo(_("Warning: repo-level runners query returned HTTP {status}", status=r.status_code), err=True)
    except (requests.RequestException, ValueError) as e:
-        click.echo(f"Warning: repo-level runners query failed: {e}", err=True)
+        click.echo(_("Warning: repo-level runners query failed: {error}", error=e), err=True)

    # 2. Organization-level runners
    try:
@@ -70,9 +71,9 @@ def query_runners(api_url: str, token: str, owner: str, repo: str) -> int:
            data = r.json()
            total += data.get("total_count", 0)
        else:
-            click.echo(f"Warning: org-level runners query returned HTTP {r.status_code}", err=True)
+            click.echo(_("Warning: org-level runners query returned HTTP {status}", status=r.status_code), err=True)
    except (requests.RequestException, ValueError) as e:
-        click.echo(f"Warning: org-level runners query failed: {e}", err=True)
+        click.echo(_("Warning: org-level runners query failed: {error}", error=e), err=True)

    # 3. Instance-level runners (requires admin scope)
    try:
@@ -85,9 +86,12 @@ def query_runners(api_url: str, token: str, owner: str, repo: str) -> int:
            data = r.json()
            total += data.get("total_count", 0)
        elif r.status_code != 403:  # 403 is expected without admin scope
-            click.echo(f"Warning: instance-level runners query returned HTTP {r.status_code}", err=True)
+            click.echo(
+                _("Warning: instance-level runners query returned HTTP {status}", status=r.status_code),
+                err=True,
+            )
    except (requests.RequestException, ValueError) as e:
-        click.echo(f"Warning: instance-level runners query failed: {e}", err=True)
+        click.echo(_("Warning: instance-level runners query failed: {error}", error=e), err=True)

    return total

@@ -148,12 +152,12 @@ def main(
    output_indices: bool,
    github_output: bool,
 ) -> None:
-    token = os.environ.get("REPO_TOKEN", "")
+    token = os.environ.get("CI_GITEA_TOKEN", "")

    if owner is None:
-        owner = os.environ.get("DEVX_REPO_OWNER", "oblachno-oss")
+        owner = os.environ.get("DEVX_REPO_OWNER", "") or REPO_OWNER
    if repo is None:
-        repo = os.environ.get("DEVX_REPO_NAME", "devx")
+        repo = os.environ.get("DEVX_REPO_NAME", "") or REPO_NAME

    count = get_runner_count(GITEA_API_URL, token, owner, repo)
    indices = generate_indices(count)
@@ -162,11 +166,11 @@ def main(
        gh_output = os.environ.get("GITHUB_OUTPUT")
        if not gh_output:
            raise click.ClickException("GITHUB_OUTPUT environment variable is not set")
-        with open(gh_output, "a") as f:  # noqa: PTH123
+        with open(gh_output, "a", encoding="utf-8") as f:  # noqa: PTH123
            f.write(f"runner-count={count}\n")
            f.write(f"runner-indices={json.dumps(indices)}\n")
-        click.echo(f"Runner count: {count}")
-        click.echo(f"Runner indices: {indices}")
+        click.echo(_("Runner count: {count}", count=count))
+        click.echo(_("Runner indices: {indices}", indices=indices))
        return

    if output_count:
@@ -178,8 +182,8 @@ def main(
        return

    # Default: output both as key=value pairs for CI consumption
-    click.echo(f"count={count}")
-    click.echo(f"indices={json.dumps(indices)}")
+    click.echo(_("count={count}", count=count))
+    click.echo(_("indices={indices}", indices=json.dumps(indices)))


 if __name__ == "__main__":  # pragma: no cover
--- a/Show More
+++ b/Show More