release: v0.33.3 [skip ci]

.devin/agents/ci-investigator/AGENT.md

@@ -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

.devin/agents/dep-upgrader/AGENT.md

@@ -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

.devin/agents/doc-sync-specialist/AGENT.md

@@ -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

.devin/agents/docker-image-builder/AGENT.md

@@ -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

.devin/agents/workflow-validator/AGENT.md

@@ -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

.devin/skills/devx-workflow/SKILL.md

@@ -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

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

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

.dockerignore

@@ -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/

.env.example

@@ -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

.gitea/workflows/build-images.yml

@@ -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

.gitea/workflows/ci.yml

@@ -8,48 +8,58 @@ 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 4 --max-single-seconds 0.5
+          . .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: 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 +70,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 +82,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 +98,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 +192,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" \

.gitea/workflows/post-merge.yml

@@ -1,30 +1,30 @@
 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)
+#   detect-type ──┬── validate-commit-msg (skip if release commit)
+#                 ├── release (skip if release commit)
+#                 │   └── publish (needs release — builds & publishes to PyPI)
 #                 ├── badges (ALWAYS runs — even on release commits)
 #                 ├── configure-repo (independent — skip if release commit)
-#                 ├── sync-wiki (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()` 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.
 #
-# 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 +33,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 +82,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
+          . .venv/bin/activate 2>/dev/null || true
           python3 -m devx.ci.sync_wiki --repo "${{ github.repository }}" --strict
       - 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 +200,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]
+    needs: [detect-type]
     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 +241,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

.gitea/workflows/publish.yml

@@ -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 }}"

.gitignore

@@ -35,3 +35,6 @@ Thumbs.db
 
 # Badges
 .badges/
+
+# Deprecated CI task tracking (branch name is the sole source of truth)
+.taskid

.hadolint.yaml

@@ -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

.pre-commit-config.yaml

@@ -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

.taskid

@@ -1 +0,0 @@
-DEVX-18

AGENTS.md

@@ -1,11 +1,25 @@
 # 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 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)
@@ -16,8 +30,8 @@ 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** 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)
 
@@ -52,37 +66,56 @@ 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)
 ├── 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
+│   ├── install_checkmake.py  # Install checkmake (Makefile linter)
+│   ├── 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
 ```
 
@@ -163,7 +196,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 +210,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 +222,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 +289,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 +299,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 +322,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 (e.g.
+`DEVX-12-fix-foo` → `DEVX-12`). Branch names must include the task ID
+prefix — there is no `.taskid` file fallback. If a stale `.taskid` file
+exists in the repo, a deprecation warning is printed advising its removal.
+
+### Workflow `auto-merge` Job and `always()`
+
+When `auto-merge` depends on a job that can be skipped (e.g.
+`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 (e.g. `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 +379,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 +393,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 (e.g. `"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 +535,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 with infra and grm):
+
+| 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"`.
+

CHANGELOG.md

@@ -2,6 +2,481 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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

LICENSE

@@ -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.
 

Makefile

@@ -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."

README.md

@@ -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/b07bea6f88be4058d6a6dff32b004ae44870791c/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/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.27.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` (e.g., `"devx==0.27.0"`) or use a version constraint
+> (e.g., `"devx>=0.27.0,<0.28"`).
+
+### 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.*`.
+
+```
+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).

docker/ci-base/Dockerfile

@@ -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

docker/ci-full/Dockerfile

@@ -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

docker/ci-quality/Dockerfile

@@ -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 \
+    && 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

docker/images.json

@@ -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"]
+  }
+]

docs/index.md

@@ -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/b07bea6f88be4058d6a6dff32b004ae44870791c/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b07bea6f88be4058d6a6dff32b004ae44870791c/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.27.0",
+]
+
+[tool.pip]
+extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
+```
+
+Pin a specific version if needed: `"devx==0.27.0"` or `"devx>=0.27.0,<0.28"`.
+
+### 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

docs/mapping.json

@@ -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"

docs/tech/architecture.md

@@ -1,50 +1,583 @@
 # 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
 
 ```
 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 (e.g., `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)
+- 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 (e.g., `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 (e.g., `release.py` imports from
+   `classify_changes.py`)
+
+## Data flow
+
+### PR lifecycle
+
+```
+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
+
+```
+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
+
+```
+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
+
+```
+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.

docs/tech/ci-cd-workflow.md

@@ -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`)
+```
+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 (e.g., `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.
+```
+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 (e.g.,
+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
+(e.g., `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.

docs/user/cli-commands.md

@@ -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

docs/user/getting-started.md

@@ -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.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "devx[dev]>=0.27.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:
+
+```
+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

pyproject.toml

@@ -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)

src/devx/__init__.py

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

src/devx/api_clients.py

@@ -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,31 @@ 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
+
 
 class VikunjaClient:
     """Low-level Vikunja REST API client with connection pooling."""
@@ -286,47 +383,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 +399,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()

src/devx/ci/_shared.py

@@ -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

src/devx/ci/auto_merge.py

@@ -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(
                 _(

src/devx/ci/check_auto_merge_ready.py

@@ -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

src/devx/ci/check_translations.py

@@ -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" / "gitea_runner_manager" / "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))
 

src/devx/ci/classify_changes.py

@@ -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)}")

src/devx/ci/detect_release_commit.py

@@ -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

src/devx/ci/discover_runners.py

@@ -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

src/devx/ci/distribute_files.py

@@ -1,10 +1,14 @@
 #!/usr/bin/env python3
-"""Distribute a list of files across N parallel runners (round-robin).
+"""Distribute a list of files across N parallel runners using LPT scheduling.
 
 Generic file-based test distribution for CI matrix jobs. 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`` for use by subsequent steps.
+assigns them to *max_runners* groups using LPT (Longest Processing Time
+first) scheduling — files are weighted by size (as a proxy for test
+runtime) and assigned to the runner with the least total weight.
+
+The assigned group for *runner_index* is written to ``$GITHUB_ENV`` for
+use by subsequent steps.
 
 Usage::
 
@@ -22,6 +26,7 @@ import os
 
 import click
 
+from devx.ci._shared import lpt_distribute, write_github_env
 from devx.i18n import _
 
 DEFAULT_MAX_RUNNERS = 3
@@ -32,12 +37,25 @@ def discover_files(pattern: str) -> list[str]:
     return sorted(glob.glob(pattern))
 
 
+def _file_weight(path: str) -> int:
+    """Estimate a weight for a file based on its size in bytes.
+
+    Falls back to 1 if the file cannot be stat'd (e.g. in tests).
+    """
+    try:
+        return max(1, os.path.getsize(path))
+    except OSError:
+        return 1
+
+
 def distribute(files: list[str], max_runners: int) -> list[list[str]]:
-    """Split *files* into *max_runners* balanced groups (round-robin)."""
-    groups: list[list[str]] = [[] for _ in range(max_runners)]
-    for i, f in enumerate(files):
-        groups[i % max_runners].append(f)
-    return groups
+    """Split *files* into *max_runners* balanced groups using LPT scheduling.
+
+    Files are weighted by size (as a proxy for runtime) and assigned to
+    the runner with the least total weight.
+    """
+    weights = [_file_weight(f) for f in files]
+    return lpt_distribute(files, weights, max_runners)
 
 
 def files_for_runner(files: list[str], runner_index: int, max_runners: int) -> list[str]:
@@ -50,14 +68,6 @@ def files_for_runner(files: list[str], runner_index: int, max_runners: int) -> l
     return groups[runner_index]
 
 
-def _write_github_env(key: str, value: str) -> None:
-    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") as f:  # noqa: PTH123
-        f.write(f"{key}={value}\n")
-
-
 @click.command()
 @click.option("--pattern", required=True, help="Glob pattern for files to distribute.")
 @click.option(
@@ -92,26 +102,34 @@ def main(pattern: str, runner_index: int | None, max_runners: int, github_env: b
         groups = distribute(files, max_runners)
         for i, group in enumerate(groups):
             labels = " ".join(group) if group else "(none)"
-            click.echo(f"Runner {i}: {labels}")
+            click.echo(_("Runner {i}: {labels}", i=i, labels=labels))
         return
 
     if skip_if_excess and github_env and runner_index > max_runners:
-        click.echo(f"Skipping — runner index {runner_index} > max runners {max_runners}")
-        _write_github_env("ASSIGNED_FILES", "")
-        _write_github_env("SKIP", "true")
+        click.echo(
+            _(
+                "Skipping — runner index {runner_index} > max runners {max_runners}",
+                runner_index=runner_index,
+                max_runners=max_runners,
+            )
+        )
+        write_github_env("ASSIGNED_FILES", "")
+        write_github_env("SKIP", "true")
         return
 
     if runner_index < 1:
-        raise click.ClickException(f"Runner index {runner_index} is out of range (must be >= 1)")
+        raise click.ClickException(
+            _("Runner index {runner_index} is out of range (must be >= 1)", runner_index=runner_index)
+        )
 
     zero_based = runner_index - 1
     assigned = files_for_runner(files, zero_based, max_runners)
     encoded = "\n".join(assigned)
 
     if github_env:
-        _write_github_env("ASSIGNED_FILES", encoded)
-        _write_github_env("SKIP", "false")
-        click.echo(f"Assigned {len(assigned)} files to runner {runner_index}")
+        write_github_env("ASSIGNED_FILES", encoded)
+        write_github_env("SKIP", "false")
+        click.echo(_("Assigned {count} files to runner {runner_index}", count=len(assigned), runner_index=runner_index))
         return
 
     click.echo(encoded)

src/devx/ci/distribute_items.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Distribute a list of items across N parallel runners using LPT scheduling.
+
+Generic item distribution for CI matrix jobs. Items are read from a JSON
+array on stdin (or from a file via --items-file), sorted for deterministic
+ordering, then assigned to *max_runners* groups using LPT (Longest
+Processing Time first) scheduling.
+
+Each item is a string (e.g. an Ansible ``--limit`` pattern like
+``observability`` or ``infra-314-vm``). Optionally, items can be objects
+with ``{"id": "...", "weight": N}`` to provide explicit weights.
+
+The assigned group for *runner_index* is written to ``$GITHUB_ENV`` as
+``ASSIGNED_ITEMS`` (space-delimited) for use by subsequent steps.
+
+Usage::
+
+    echo '["observability", "infra-314-vm"]' | \\
+        python3 -m devx.ci.distribute_items \\
+        --runner-index 1 --max-runners 3 \\
+        --github-env --skip-if-excess
+
+    # With weights:
+    echo '[{"id": "observability", "weight": 5}, {"id": "customer-1", "weight": 3}]' | \\
+        python3 -m devx.ci.distribute_items \\
+        --runner-index 1 --max-runners 3 --github-env
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+from devx.ci._shared import lpt_distribute, write_github_env
+from devx.i18n import _
+
+DEFAULT_MAX_RUNNERS = 3
+DEFAULT_WEIGHT = 1
+
+
+def parse_items(raw: str) -> list[str]:
+    """Parse a JSON array into a list of item identifier strings.
+
+    Accepts both plain string arrays (``["a", "b"]``) and object arrays
+    (``[{"id": "a", "weight": 2}]``). Returns just the identifier strings.
+    """
+    data = json.loads(raw)
+    if not isinstance(data, list):
+        raise click.ClickException(_("Items input must be a JSON array, got {type}", type=type(data).__name__))
+    items: list[str] = []
+    for entry in data:
+        if isinstance(entry, str):
+            items.append(entry)
+        elif isinstance(entry, dict) and "id" in entry:
+            items.append(str(entry["id"]))
+        else:
+            raise click.ClickException(
+                _("Each item must be a string or an object with 'id', got {type}", type=type(entry).__name__)
+            )
+    return items
+
+
+def parse_weighted_items(raw: str) -> tuple[list[str], list[int]]:
+    """Parse a JSON array into (items, weights) lists.
+
+    For plain string arrays, all items get ``DEFAULT_WEIGHT``.
+    For object arrays, the ``weight`` field is used (default: ``DEFAULT_WEIGHT``).
+    """
+    data = json.loads(raw)
+    if not isinstance(data, list):
+        raise click.ClickException(_("Items input must be a JSON array, got {type}", type=type(data).__name__))
+    items: list[str] = []
+    weights: list[int] = []
+    for entry in data:
+        if isinstance(entry, str):
+            items.append(entry)
+            weights.append(DEFAULT_WEIGHT)
+        elif isinstance(entry, dict) and "id" in entry:
+            items.append(str(entry["id"]))
+            weights.append(int(entry.get("weight", DEFAULT_WEIGHT)))
+        else:
+            raise click.ClickException(
+                _("Each item must be a string or an object with 'id', got {type}", type=type(entry).__name__)
+            )
+    return items, weights
+
+
+def distribute(items: list[str], weights: list[int], max_runners: int) -> list[list[str]]:
+    """Split *items* into *max_runners* balanced groups using LPT scheduling.
+
+    Items are sorted by weight (descending), then assigned to the runner
+    with the least total weight.
+    """
+    return lpt_distribute(items, weights, max_runners)
+
+
+def items_for_runner(items: list[str], weights: list[int], runner_index: int, max_runners: int) -> list[str]:
+    """Return the subset of items assigned to *runner_index* (0-based)."""
+    groups = distribute(items, weights, max_runners)
+    if runner_index < 0 or runner_index >= len(groups):
+        raise click.ClickException(
+            _("Runner index {index} out of range (0..{max})", index=runner_index, max=max_runners - 1)
+        )
+    return groups[runner_index]
+
+
+@click.command()
+@click.option(
+    "--items-file",
+    type=click.Path(exists=True, file_okay=True, path_type=None),
+    default=None,
+    help="Read items from a JSON file instead of stdin.",
+)
+@click.option(
+    "--runner-index",
+    type=int,
+    default=None,
+    help="One-based runner index. If omitted, prints all groups.",
+)
+@click.option(
+    "--max-runners",
+    type=int,
+    default=DEFAULT_MAX_RUNNERS,
+    show_default=True,
+    help="Total number of parallel runners.",
+)
+@click.option(
+    "--github-env",
+    is_flag=True,
+    default=False,
+    help="Write ASSIGNED_ITEMS and SKIP to $GITHUB_ENV.",
+)
+@click.option(
+    "--skip-if-excess",
+    is_flag=True,
+    default=False,
+    help="With --github-env: write SKIP=true when runner-index exceeds max-runners.",
+)
+def main(
+    items_file: str | None,
+    runner_index: int | None,
+    max_runners: int,
+    github_env: bool,
+    skip_if_excess: bool,
+) -> None:
+    # Read items from file or stdin
+    if items_file is not None:
+        with open(items_file, encoding="utf-8") as f:  # noqa: PTH123
+            raw = f.read()
+    else:
+        raw = sys.stdin.read()
+
+    raw = raw.strip()
+    if not raw:
+        raw = "[]"
+
+    items, weights = parse_weighted_items(raw)
+
+    if runner_index is None:
+        groups = distribute(items, weights, max_runners)
+        for i, group in enumerate(groups):
+            labels = " ".join(group) if group else "(none)"
+            click.echo(_("Runner {i}: {labels}", i=i, labels=labels))
+        return
+
+    if skip_if_excess and github_env and runner_index > max_runners:
+        click.echo(
+            _(
+                "Skipping — runner index {runner_index} > max runners {max_runners}",
+                runner_index=runner_index,
+                max_runners=max_runners,
+            )
+        )
+        write_github_env("ASSIGNED_ITEMS", "")
+        write_github_env("SKIP", "true")
+        return
+
+    if runner_index < 1:
+        raise click.ClickException(
+            _("Runner index {runner_index} is out of range (must be >= 1)", runner_index=runner_index)
+        )
+
+    zero_based = runner_index - 1
+    assigned = items_for_runner(items, weights, zero_based, max_runners)
+    encoded = " ".join(assigned)
+
+    if github_env:
+        write_github_env("ASSIGNED_ITEMS", encoded)
+        write_github_env("SKIP", "false")
+        click.echo(
+            _(
+                "Assigned {count} items to runner {runner_index}: {encoded}",
+                count=len(assigned),
+                runner_index=runner_index,
+                encoded=encoded,
+            )
+        )
+        return
+
+    click.echo(encoded)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/ci/doc_coverage.py

@@ -5,8 +5,12 @@ Parses Click commands from the CLI source code and checks if each command
 has corresponding documentation in the wiki/docs.  Reports missing
 documentation as warnings and exits with non-zero if coverage is below 100%.
 
+By default, checks the current repository's own source and docs directories.
+When run from the devx package itself (development mode), it checks devx's
+own files. When installed as a package, it checks the consuming repo's files.
+
 Usage:
-  python3 -m devx.ci.doc_coverage [--docs-dir docs/] [--fail-on-missing]
+  python3 -m devx.ci.doc_coverage [--docs-dir docs/] [--source-dir src/] [--fail-on-missing]
 """
 
 from __future__ import annotations
@@ -19,11 +23,12 @@ import click
 
 from devx.i18n import _
 
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+# Default to the current working directory (consuming repo's root)
+REPO_ROOT = Path.cwd()
 DOCS_DIR = REPO_ROOT / "docs"
-CLI_FILE = REPO_ROOT / "src" / "devx" / "cli.py"
 
 # Major modules that should be documented in tech/architecture.md
+# These are devx-specific; when checking other repos, use --source-dir
 REQUIRED_MODULES = [
     "cli.py",
     "i18n.py",
@@ -51,11 +56,16 @@ REQUIRED_SCRIPTS = [
 ]
 
 
-def extract_cli_commands() -> list[str]:
+def extract_cli_commands(source_dir: Path) -> list[str]:
     """Extract command names from the CLI source file."""
-    if not CLI_FILE.exists():
+    # Try to find the CLI file in the source directory
+    cli_file = None
+    for candidate in source_dir.rglob("cli.py"):
+        cli_file = candidate
+        break
+    if cli_file is None or not cli_file.exists():
         return []
-    content = CLI_FILE.read_text()
+    content = cli_file.read_text()
     commands: list[str] = []
     # Find all @<group>.command("name") occurrences in the CLI source
     # Matches @cli.command, @ci.command, @tools.command, @molecule.command
@@ -94,15 +104,30 @@ def check_module_documented(module: str, docs_content: str) -> bool:
 
 
 @click.command()
-@click.option("--docs-dir", default=str(DOCS_DIR), help="Path to the docs directory.")
+@click.option("--docs-dir", default=None, help="Path to the docs directory (default: ./docs).")
+@click.option("--source-dir", default=None, help="Path to the source directory (default: auto-detect from src/).")
 @click.option(
     "--fail-on-missing",
     is_flag=True,
     default=False,
     help="Exit with non-zero status if any documentation is missing.",
 )
-def main(docs_dir: str, fail_on_missing: bool) -> None:
-    docs_path = Path(docs_dir)
+def main(docs_dir: str | None, source_dir: str | None, fail_on_missing: bool) -> None:
+    root = Path.cwd()
+    docs_path = Path(docs_dir) if docs_dir else root / "docs"
+
+    # Auto-detect source directory
+    if source_dir:
+        src_path = Path(source_dir)
+    else:
+        # Try common source directories
+        for candidate in [root / "src", root / "scripts"]:
+            if candidate.exists():
+                src_path = candidate
+                break
+        else:
+            src_path = root / "src"
+
     cli_commands_file = docs_path / "user" / "cli-commands.md"
     architecture_file = docs_path / "tech" / "architecture.md"
     ci_cd_file = docs_path / "tech" / "ci-cd-workflow.md"
@@ -112,21 +137,28 @@ def main(docs_dir: str, fail_on_missing: bool) -> None:
 
     # Check CLI commands
     click.echo(_("Checking CLI command documentation..."))
-    commands = extract_cli_commands()
+    commands = extract_cli_commands(src_path)
     total += len(commands)
     cli_docs = cli_commands_file.read_text() if cli_commands_file.exists() else ""
     for cmd in commands:
         if check_command_documented(cmd, cli_docs):
-            click.echo(_("  OK: devx {cmd}", cmd=cmd))
+            click.echo(_("  OK: {cmd}", cmd=cmd))
         else:
-            click.echo(_("  MISSING: devx {cmd}", cmd=cmd))
-            missing.append(f"CLI command: devx {cmd}")
+            click.echo(_("  MISSING: {cmd}", cmd=cmd))
+            missing.append(f"CLI command: {cmd}")
 
     # Check modules in architecture.md
+    # Auto-detect modules from source directory (top-level only, exclude subdirs)
     click.echo(_("\nChecking module documentation in architecture.md..."))
-    total += len(REQUIRED_MODULES)
+    if src_path.exists():
+        detected_modules = sorted(
+            f.name for f in src_path.glob("*.py") if f.name != "__init__.py" and f.name != "cli.py"
+        )
+    else:
+        detected_modules = REQUIRED_MODULES
+    total += len(detected_modules)
     arch_docs = architecture_file.read_text() if architecture_file.exists() else ""
-    for module in REQUIRED_MODULES:
+    for module in detected_modules:
         if check_module_documented(module, arch_docs):
             click.echo(_("  OK: {module}", module=module))
         else:
@@ -134,10 +166,16 @@ def main(docs_dir: str, fail_on_missing: bool) -> None:
             missing.append(f"Module: {module}")
 
     # Check CI scripts in ci-cd-workflow.md
+    # Auto-detect CI scripts from ci/ subdirectory
     click.echo(_("\nChecking CI script documentation in ci-cd-workflow.md..."))
-    total += len(REQUIRED_SCRIPTS)
+    ci_dir = src_path / "ci" if src_path.name != "ci" else src_path
+    if ci_dir.exists():
+        detected_scripts = sorted(f.name for f in ci_dir.glob("*.py") if f.name != "__init__.py")
+    else:
+        detected_scripts = REQUIRED_SCRIPTS
+    total += len(detected_scripts)
     ci_docs = ci_cd_file.read_text() if ci_cd_file.exists() else ""
-    for script in REQUIRED_SCRIPTS:
+    for script in detected_scripts:
         if check_module_documented(script, ci_docs):
             click.echo(_("  OK: {script}", script=script))
         else:

src/devx/ci/integration_guard.py

@@ -6,23 +6,18 @@ Wraps ``pytest`` with the same Gitea API polling mechanism used by
 reports failure, the current pytest subprocess is killed and this runner
 exits early with code 1.
 
-JUnit XML is generated via pytest's ``--junitxml`` flag (passed through
-to the pytest invocation).
-
 Usage::
 
     python3 -m devx.ci.integration_guard \\
-        --junit-output junit-results/runner-1.xml \\
         -- test_file1.py test_file2.py
 
     # With pytest options
     python3 -m devx.ci.integration_guard \\
-        --junit-output junit-results/runner-1.xml \\
         -- -x -v --tb=short test_file1.py
 
 Environment variables:
     GITEA_URL           Base URL of the Gitea instance.
-    REPO_TOKEN          API token with repo access.
+    CI_GITEA_TOKEN      API token with repo access.
     RUN_ID              Workflow run ID (GITHUB_RUN_ID).
     JOB_NAME            Base job name (GITHUB_JOB), e.g. "integration-tests".
     MATRIX_INDEX        Current matrix index (runner-index).
@@ -41,6 +36,7 @@ import time
 
 import click
 
+from devx.config import REPO_NAME, REPO_OWNER
 from devx.i18n import _
 from devx.molecule.molecule_ci_guard import (
     poll_for_other_failures,
@@ -51,25 +47,20 @@ POLL_INTERVAL = 10
 
 @click.command(context_settings={"ignore_unknown_options": True})
 @click.argument("pytest_args", nargs=-1, type=click.UNPROCESSED, required=True)
-@click.option(
-    "--junit-output",
-    default=None,
-    help="Path for JUnit XML output (passed to pytest as --junitxml).",
-)
-def cli(pytest_args: tuple[str, ...], junit_output: str | None) -> None:
+def cli(pytest_args: tuple[str, ...]) -> None:
     """Run pytest with cross-runner failure detection."""
     gitea_url = os.environ.get("GITEA_URL", "")
-    token = os.environ.get("REPO_TOKEN", "")
+    token = os.environ.get("CI_GITEA_TOKEN", "")
     run_id = int(os.environ.get("RUN_ID", "0"))
     job_name = os.environ.get("JOB_NAME", "integration-tests")
     current_index = int(os.environ.get("MATRIX_INDEX", "0"))
-    repository = os.environ.get("GITEA_REPOSITORY", "oblachno-oss/devx")
+    repository = os.environ.get("GITEA_REPOSITORY", "")
     owner, _sep, repo = repository.partition("/")
     if not owner or not repo:
-        owner, repo = "oblachno-oss", "devx"
+        owner, repo = REPO_OWNER, REPO_NAME
 
     if not all([gitea_url, token, run_id]):
-        click.echo(_("GITEA_URL/REPO_TOKEN/RUN_ID not set; running without cross-runner cancellation."))
+        click.echo(_("GITEA_URL/CI_GITEA_TOKEN/RUN_ID not set; running without cross-runner cancellation."))
 
     stop_event = threading.Event()
     failed_event = threading.Event()
@@ -93,11 +84,9 @@ def cli(pytest_args: tuple[str, ...], junit_output: str | None) -> None:
         poller.start()
 
     cmd = [sys.executable, "-m", "pytest"]
-    if junit_output:
-        cmd.extend(["--junitxml", junit_output])
     cmd.extend(pytest_args)
 
-    click.echo(f"Running: {' '.join(cmd)}")
+    click.echo(_("Running: {cmd}", cmd=" ".join(cmd)))
 
     process = subprocess.Popen(  # nosec B603
         cmd,

src/devx/ci/lint_docs.py

@@ -0,0 +1,415 @@
+#!/usr/bin/env python3
+"""Lint documentation files for structure, links, and quality.
+
+Checks performed (all configurable via pyproject.toml ``[tool.devx.docs]``):
+- **Required files**: README.md, AGENTS.md, CHANGELOG.md must exist.
+- **Docs structure**: ``docs/index.md`` and ``docs/mapping.json`` must exist.
+- **Broken internal links**: relative paths and anchors in markdown files
+  must resolve to actual files and headings.
+- **Heading hierarchy**: no skipping heading levels (e.g., ``#`` → ``###``).
+- **TODO/FIXME**: flags leftover TODO/FIXME markers in documentation.
+- **Stale docs**: files not modified in >180 days (warning only).
+- **Trailing whitespace**: lines should not end with whitespace.
+- **Blank line before headings**: headings should have a blank line before them.
+
+Usage::
+
+    python3 -m devx.ci.lint_docs
+    python3 -m devx.ci.lint_docs --docs-dir docs/ --root .
+    python3 -m devx.ci.lint_docs --fix  # auto-fix trailing whitespace
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import click
+
+from devx.i18n import _
+
+# Heading slug pattern (GitHub-style)
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.+?)\s*$", re.MULTILINE)
+# Markdown link pattern: [text](url)
+_LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
+# Trailing whitespace
+_TRAILING_WS_RE = re.compile(r"[ \t]+$")
+# Heading without blank line before
+_HEADING_NO_BLANK_RE = re.compile(r"([^\n])\n(#{1,6}\s)")
+
+# Files that must exist in every project
+REQUIRED_FILES = ["README.md", "AGENTS.md", "CHANGELOG.md"]
+
+# Files that must exist in docs/
+REQUIRED_DOC_FILES = ["index.md"]
+
+# Maximum age for docs before they're considered stale (days)
+STALE_THRESHOLD_DAYS = 180
+
+# Files excluded from duplicate heading checks (auto-generated or structured
+# with repeated subsections under different parent sections)
+DUPLICATE_HEADING_EXCLUDES = {
+    "CHANGELOG.md",
+    "incident-response-sso.md",
+    "role-sync-design.md",
+}
+
+# TODO/FIXME pattern — matches "TODO:" or "FIXME:" at start of line/after whitespace
+# Does NOT match references to the word "TODO" in rules/documentation
+_TODO_RE = re.compile(r"(?m)^\s*(?:>>>?\s*)?(TODO|FIXME|HACK|XXX)\s*:", re.IGNORECASE)
+
+# Directories excluded from markdown file scanning
+_EXCLUDE_DIRS = {
+    ".venv",
+    ".git",
+    "node_modules",
+    "__pycache__",
+    ".pytest_cache",
+    ".devin",
+    ".terraform",
+    "site-packages",
+    "dist-info",
+}
+
+
+def slugify(text: str) -> str:
+    """Convert heading text to a GitHub-style slug."""
+    slug = text.lower().strip()
+    slug = re.sub(r"[^\w\s-]", "", slug)
+    slug = re.sub(r"[\s]+", "-", slug)
+    return slug
+
+
+def strip_code_blocks(content: str) -> str:
+    """Remove fenced code blocks from markdown content.
+
+    Replaces ```...``` blocks with empty lines so heading detection
+    doesn't pick up # comments inside code blocks.
+    """
+    result: list[str] = []
+    in_code_block = False
+    for line in content.splitlines():
+        if line.strip().startswith("```"):
+            in_code_block = not in_code_block
+            result.append("")
+            continue
+        if in_code_block:
+            result.append("")
+            continue
+        result.append(line)
+    return "\n".join(result)
+
+
+def extract_headings(filepath: Path) -> dict[str, int]:
+    """Extract all headings from a markdown file.
+
+    Returns a dict mapping slug → heading level.
+    """
+    content = strip_code_blocks(filepath.read_text(encoding="utf-8"))
+    headings: dict[str, int] = {}
+    for match in _HEADING_RE.finditer(content):
+        level = len(match.group(1))
+        text = match.group(2)
+        slug = slugify(text)
+        headings[slug] = level
+    return headings
+
+
+def extract_links(filepath: Path) -> list[tuple[int, str, str]]:
+    """Extract all markdown links from a file.
+
+    Returns a list of (line_number, link_text, url) tuples.
+    Includes anchor-only links (#section) for validation.
+    Skips external links (http/https) and mailto.
+    """
+    content = filepath.read_text(encoding="utf-8")
+    links: list[tuple[int, str, str]] = []
+    for match in _LINK_RE.finditer(content):
+        url = match.group(2).strip()
+        # Skip external links and mailto
+        if url.startswith(("http://", "https://", "mailto:")):
+            continue
+        line_num = content[: match.start()].count("\n") + 1
+        links.append((line_num, match.group(1), url))
+    return links
+
+
+def check_required_files(root: Path) -> list[str]:
+    """Check that required files exist."""
+    issues: list[str] = []
+    for filename in REQUIRED_FILES:
+        if not (root / filename).exists():
+            issues.append(f"Missing required file: {filename}")
+    return issues
+
+
+def check_docs_structure(root: Path, docs_dir: Path) -> list[str]:
+    """Check that docs directory has required structure."""
+    issues: list[str] = []
+    if not docs_dir.exists():
+        issues.append(f"Docs directory not found: {docs_dir}")
+        return issues
+    for filename in REQUIRED_DOC_FILES:
+        if not (docs_dir / filename).exists():
+            issues.append(f"Missing required doc file: docs/{filename}")
+    mapping_file = docs_dir / "mapping.json"
+    if mapping_file.exists():
+        try:
+            mapping = json.loads(mapping_file.read_text(encoding="utf-8"))
+            if not isinstance(mapping, dict):
+                issues.append("docs/mapping.json must be a JSON object")
+            elif not mapping:
+                issues.append("docs/mapping.json is empty")
+        except json.JSONDecodeError as e:
+            issues.append(f"docs/mapping.json is invalid JSON: {e}")
+    return issues
+
+
+def check_internal_links(root: Path, docs_dir: Path) -> list[str]:
+    """Check that all internal links in markdown files resolve."""
+    issues: list[str] = []
+    md_files = list(root.rglob("*.md"))
+    # Exclude .venv, .git, node_modules
+    md_files = [f for f in md_files if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    # Load wiki page names from mapping.json — these are valid link targets
+    wiki_pages: set[str] = set()
+    mapping_file = docs_dir / "mapping.json"
+    if mapping_file.exists():
+        try:
+            mapping = json.loads(mapping_file.read_text(encoding="utf-8"))
+            wiki_pages = set(mapping.values())
+        except (json.JSONDecodeError, AttributeError):
+            pass
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        links = extract_links(md_file)
+        headings = extract_headings(md_file)
+
+        for line_num, _link_text, url in links:
+            # Split into path and anchor
+            if "#" in url:
+                path_part, anchor = url.split("#", 1)
+            else:
+                path_part, anchor = url, ""
+
+            # Skip wiki page references (no file extension, no /, matches mapping.json values)
+            if path_part and "." not in path_part and "/" not in path_part:
+                if path_part in wiki_pages:
+                    continue
+                # Also skip if it looks like a wiki page name (CamelCase or hyphenated)
+                # without a file extension — can't verify these locally
+                if not any(c in path_part for c in "/\\"):
+                    continue
+
+            # Resolve relative path
+            if path_part:
+                target = (md_file.parent / path_part).resolve()
+                if not target.exists():
+                    issues.append(f"{rel_path}:{line_num}: broken link '{url}' — file not found: {path_part}")
+                    continue
+                # Check anchor in target file
+                if anchor:
+                    target_headings = extract_headings(target)
+                    target_slug = slugify(anchor)
+                    if target_slug not in target_headings:
+                        issues.append(f"{rel_path}:{line_num}: broken anchor '#{anchor}' in {path_part}")
+            elif anchor:
+                # Anchor-only link — check in current file
+                anchor_slug = slugify(anchor)
+                if anchor_slug not in headings:
+                    issues.append(f"{rel_path}:{line_num}: broken anchor '#{anchor}'")
+
+    return issues
+
+
+def check_heading_hierarchy(root: Path) -> list[str]:
+    """Check that headings don't skip levels."""
+    issues: list[str] = []
+    md_files = [f for f in root.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        content = strip_code_blocks(md_file.read_text(encoding="utf-8"))
+        prev_level = 0
+        for match in _HEADING_RE.finditer(content):
+            level = len(match.group(1))
+            if prev_level > 0 and level > prev_level + 1:
+                issues.append(f"{rel_path}: heading hierarchy skip — H{prev_level} → H{level}: '{match.group(2)}'")
+            prev_level = level
+
+    return issues
+
+
+def check_todo_fixme(root: Path) -> list[str]:
+    """Check for TODO/FIXME/HACK/XXX markers in documentation.
+
+    Only flags actual TODO/FIXME markers (e.g., "TODO: fix this"), not
+    references to the word "TODO" in rules or documentation about TODOs.
+    """
+    issues: list[str] = []
+    md_files = [f for f in root.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        content = md_file.read_text(encoding="utf-8")
+        for match in _TODO_RE.finditer(content):
+            line_num = content[: match.start()].count("\n") + 1
+            line = content.splitlines()[line_num - 1] if line_num <= len(content.splitlines()) else ""
+            issues.append(f"{rel_path}:{line_num}: TODO/FIXME found: {line.strip()}")
+
+    return issues
+
+
+def check_trailing_whitespace(root: Path) -> list[str]:
+    """Check for trailing whitespace in markdown files."""
+    issues: list[str] = []
+    md_files = [f for f in root.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        content = md_file.read_text(encoding="utf-8")
+        for i, line in enumerate(content.splitlines(), 1):
+            if _TRAILING_WS_RE.search(line):
+                issues.append(f"{rel_path}:{i}: trailing whitespace")
+
+    return issues
+
+
+def check_stale_docs(root: Path) -> list[str]:
+    """Check for stale documentation (not modified in >180 days)."""
+    issues: list[str] = []
+    threshold = datetime.now() - timedelta(days=STALE_THRESHOLD_DAYS)
+    md_files = [f for f in root.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        mtime = datetime.fromtimestamp(md_file.stat().st_mtime)
+        if mtime < threshold:
+            days_old = (datetime.now() - mtime).days
+            issues.append(f"{rel_path}: stale doc — not modified in {days_old} days")
+
+    return issues
+
+
+def check_duplicate_headings(root: Path) -> list[str]:
+    """Check for duplicate headings within the same file."""
+    issues: list[str] = []
+    md_files = [f for f in root.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+
+    for md_file in md_files:
+        rel_path = md_file.relative_to(root)
+        # Skip auto-generated files like CHANGELOG.md
+        if md_file.name in DUPLICATE_HEADING_EXCLUDES:
+            continue
+        content = strip_code_blocks(md_file.read_text(encoding="utf-8"))
+        seen: dict[str, int] = {}
+        for match in _HEADING_RE.finditer(content):
+            text = match.group(2)
+            slug = slugify(text)
+            if slug in seen:
+                issues.append(f"{rel_path}: duplicate heading '{text}'")
+            seen[slug] = 1
+
+    return issues
+
+
+@click.command()
+@click.option("--root", default=".", help="Repository root directory.")
+@click.option("--docs-dir", default=None, help="Docs directory (default: <root>/docs).")
+@click.option("--check-links/--no-check-links", default=True, help="Check internal links.")
+@click.option("--check-headings/--no-check-headings", default=True, help="Check heading hierarchy.")
+@click.option("--check-todo/--no-check-todo", default=True, help="Check for TODO/FIXME.")
+@click.option("--check-stale/--no-check-stale", default=False, help="Check for stale docs.")
+@click.option("--check-trailing/--no-check-trailing", default=True, help="Check trailing whitespace.")
+@click.option("--check-duplicates/--no-check-duplicates", default=True, help="Check duplicate headings.")
+@click.option("--fix", is_flag=True, default=False, help="Auto-fix trailing whitespace.")
+def main(
+    root: str,
+    docs_dir: str | None,
+    check_links: bool,
+    check_headings: bool,
+    check_todo: bool,
+    check_stale: bool,
+    check_trailing: bool,
+    check_duplicates: bool,
+    fix: bool,
+) -> None:
+    """Lint documentation files for structure, links, and quality."""
+    root_path = Path(root).resolve()
+    docs_path = Path(docs_dir) if docs_dir else root_path / "docs"
+
+    click.echo(_("Linting documentation in {root}...", root=str(root_path)))
+
+    all_issues: list[str] = []
+
+    # Structure checks
+    click.echo(_("Checking required files..."))
+    all_issues.extend(check_required_files(root_path))
+
+    click.echo(_("Checking docs structure..."))
+    all_issues.extend(check_docs_structure(root_path, docs_path))
+
+    # Link checks
+    if check_links:
+        click.echo(_("Checking internal links..."))
+        all_issues.extend(check_internal_links(root_path, docs_path))
+
+    # Heading hierarchy
+    if check_headings:
+        click.echo(_("Checking heading hierarchy..."))
+        all_issues.extend(check_heading_hierarchy(root_path))
+
+    # Duplicate headings
+    if check_duplicates:
+        click.echo(_("Checking duplicate headings..."))
+        all_issues.extend(check_duplicate_headings(root_path))
+
+    # TODO/FIXME
+    if check_todo:
+        click.echo(_("Checking for TODO/FIXME markers..."))
+        all_issues.extend(check_todo_fixme(root_path))
+
+    # Trailing whitespace
+    if check_trailing:
+        click.echo(_("Checking trailing whitespace..."))
+        ws_issues = check_trailing_whitespace(root_path)
+        if fix and ws_issues:
+            fixed = 0
+            md_files = [f for f in root_path.rglob("*.md") if not any(part in _EXCLUDE_DIRS for part in f.parts)]
+            for md_file in md_files:
+                content = md_file.read_text(encoding="utf-8")
+                fixed_content = _TRAILING_WS_RE.sub("", content)
+                if content != fixed_content:
+                    md_file.write_text(fixed_content, encoding="utf-8")
+                    fixed += 1
+            click.echo(_("  Auto-fixed trailing whitespace in {n} files", n=fixed))
+        else:
+            all_issues.extend(ws_issues)
+
+    # Stale docs
+    if check_stale:
+        click.echo(_("Checking for stale docs..."))
+        stale = check_stale_docs(root_path)
+        for issue in stale:
+            click.echo(f"  WARN: {issue}")
+        # Stale docs are warnings, not errors
+        click.echo(_("  {n} stale docs found (warnings only)", n=len(stale)))
+
+    # Report
+    click.echo(f"\n{'=' * 60}")
+    if all_issues:
+        click.echo(_("FAIL: {n} documentation issues found:", n=len(all_issues)))
+        for issue in all_issues:
+            click.echo(f"  - {issue}")
+        sys.exit(1)
+    else:
+        click.echo(_("PASS: All documentation checks passed!"))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/ci/merge_junit.py

@@ -1,97 +0,0 @@
-#!/usr/bin/env python3
-"""Merge multiple JUnit XML reports into a single report.
-
-Used by CI workflows to consolidate JUnit XML files produced by
-parallel matrix runners into a single merged report for archival
-and dashboard consumption.
-
-Usage::
-
-    python3 -m devx.ci.merge_junit \\
-        --pattern "junit-results/runner-*.xml" \\
-        --output junit-merged.xml
-
-Exit code is non-zero if any merged test suite reports failures,
-making this suitable as a CI gating step after matrix jobs.
-"""
-
-from __future__ import annotations
-
-import glob
-import sys
-import xml.etree.ElementTree as ET  # nosec B405
-
-import click
-
-from devx.i18n import _
-
-
-def merge_files(pattern: str) -> tuple[ET.Element, int, int]:
-    """Merge JUnit XML files matching *pattern* into a single ``<testsuites>`` element.
-
-    Returns ``(merged_element, total_tests, total_failures)``.
-    If no files match, returns an empty ``<testsuites>`` with zero counts.
-    """
-    files = sorted(glob.glob(pattern))
-    merged = ET.Element("testsuites")
-    total_tests = 0
-    total_failures = 0
-
-    for f in files:
-        tree = ET.parse(f)  # nosec B314
-        suite = tree.getroot()
-        # Handle both <testsuites> (wrapper) and <testsuite> (single) roots
-        if suite.tag == "testsuites":
-            for child in suite:
-                merged.append(child)
-                total_tests += int(child.get("tests", 0))
-                total_failures += int(child.get("failures", 0))
-        else:
-            merged.append(suite)
-            total_tests += int(suite.get("tests", 0))
-            total_failures += int(suite.get("failures", 0))
-
-    merged.set("tests", str(total_tests))
-    merged.set("failures", str(total_failures))
-    return merged, total_tests, total_failures
-
-
-@click.command()
-@click.option(
-    "--pattern",
-    default="junit-results/runner-*.xml",
-    show_default=True,
-    help="Glob pattern for input JUnit XML files.",
-)
-@click.option(
-    "--output",
-    default="junit-merged.xml",
-    show_default=True,
-    help="Output path for the merged JUnit XML file.",
-)
-def main(pattern: str, output: str) -> None:
-    merged, total_tests, total_failures = merge_files(pattern)
-
-    if total_tests == 0:
-        click.echo(_("No JUnit reports found matching {pattern} — skipping merge.", pattern=pattern))
-        return
-
-    ET.indent(merged)
-    tree = ET.ElementTree(merged)
-    tree.write(output, encoding="UTF-8", xml_declaration=True)
-    click.echo(
-        _(
-            "Merged {count} reports: {tests} tests, {failures} failures → {output}",
-            count=len(glob.glob(pattern)),
-            tests=total_tests,
-            failures=total_failures,
-            output=output,
-        )
-    )
-
-    if total_failures > 0:
-        sys.exit(1)
-
-
-if __name__ == "__main__":  # pragma: no cover
-    main()

src/devx/ci/notify_failure.py

@@ -6,7 +6,7 @@ otherwise go unnoticed in the Actions tab. Uses the ``tea`` Gitea CLI
 for issue creation — tea must be installed and configured.
 
 Usage:
-  REPO_TOKEN=<token> python3 -m devx.ci.notify_failure \
+  CI_GITEA_TOKEN=<token> python3 -m devx.ci.notify_failure \
     --repo <owner/repo> \
     --run-id <run_id> \
     --workflow <workflow_name> \
@@ -14,7 +14,7 @@ Usage:
     --auto-login
 
 With ``--auto-login``, the script configures the tea CLI login profile
-from ``REPO_TOKEN`` and ``DEVX_GITEA_API_URL`` before creating the issue,
+from ``CI_GITEA_TOKEN`` and ``DEVX_GITEA_API_URL`` before creating the issue,
 eliminating the need for a separate ``tea login add`` step in the workflow.
 """
 
@@ -22,14 +22,12 @@ from __future__ import annotations
 
 import logging
 import os
-import shutil
-import subprocess  # nosec B404
 
 import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
 
 from devx.config import GITEA_API_URL
-from devx.gitea_cli import TeaCLI, TeaCLIError
+from devx.gitea_cli import TeaCLI, TeaCLIError, configure_tea_login
 from devx.i18n import _
 
 load_dotenv()
@@ -37,49 +35,6 @@ load_dotenv()
 logger = logging.getLogger("devx")
 
 
-def _configure_tea_login(login_name: str = "devx") -> None:
-    """Configure tea CLI login from REPO_TOKEN and DEVX_GITEA_API_URL.
-
-    Idempotent: if a login with the same name already exists, it is not re-added.
-    Skips silently if tea is not installed or REPO_TOKEN is not set.
-    """
-    tea_bin = shutil.which("tea")
-    if tea_bin is None:
-        click.echo("notify_failure: tea not installed — skipping login configuration.")
-        return
-
-    token = os.environ.get("REPO_TOKEN", "")
-    if not token:
-        click.echo("notify_failure: REPO_TOKEN not set — skipping login configuration.")
-        return
-
-    gitea_url = GITEA_API_URL.replace("/api/v1", "")
-
-    result = subprocess.run(  # nosec B603
-        [tea_bin, "login", "list", "--output", "simple"],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    if result.returncode == 0 and login_name in result.stdout:
-        click.echo(f"notify_failure: tea login '{login_name}' already configured.")
-        return
-
-    click.echo(f"notify_failure: configuring tea login '{login_name}' for {gitea_url}...")
-    subprocess.run(  # nosec B603
-        [tea_bin, "login", "add", "--name", login_name, "--url", gitea_url, "--token", token],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    subprocess.run(  # nosec B603
-        [tea_bin, "login", "default", login_name],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-
-
 def _create_issue_via_tea(repo: str, title: str, body: str) -> int:
     """Create issue via tea CLI. Returns issue index.
 
@@ -116,15 +71,15 @@ def _create_issue_via_tea(repo: str, title: str, body: str) -> int:
     "--auto-login",
     is_flag=True,
     default=False,
-    help="Configure tea CLI login from REPO_TOKEN before creating the issue.",
+    help="Configure tea CLI login from CI_GITEA_TOKEN before creating the issue.",
 )
 def main(repo: str, run_id: str, workflow: str, commit: str, auto_login: bool) -> None:
-    token = os.environ.get("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."))
 
     if auto_login:
-        _configure_tea_login()
+        configure_tea_login()
 
     title = f"[CI] {workflow} workflow failed (run #{run_id})"
     body = (

src/devx/ci/post_merge.py

@@ -13,7 +13,8 @@ import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
 
 from devx.api_clients import VikunjaClient
-from devx.config import DEFAULT_PER_PAGE, TASK_ID_RE, TASK_PREFIX, VIKUNJA_API_URL, VIKUNJA_PROJECT_ID
+from devx.ci._shared import extract_task_id as _extract_task_id
+from devx.config import DEFAULT_PER_PAGE, TASK_PREFIX, VIKUNJA_API_URL, VIKUNJA_PROJECT_ID
 from devx.exceptions import APIError
 from devx.i18n import _
 
@@ -47,10 +48,9 @@ def _get_git_commit_sha() -> str:
 
 
 def extract_task_id(commit_msg: str) -> str:
-    """Extract DEVX-N task identifier from the first line of commit message."""
+    """Extract task identifier from the first line of commit message (delegates to shared utility)."""
     first_line = commit_msg.split("\n")[0]
-    match = TASK_ID_RE.search(first_line)
-    return match.group(0) if match else ""
+    return _extract_task_id(first_line)
 
 
 def extract_conventional_msg(commit_msg: str) -> str:
@@ -61,7 +61,7 @@ def extract_conventional_msg(commit_msg: str) -> str:
     - ``DEVX-N <message>`` (current, space-separated)
     """
     first_line = commit_msg.split("\n")[0]
-    return re.sub(r"^DEVX-\d+[:\s]\s*", "", first_line)
+    return re.sub(rf"^{TASK_PREFIX}-\d+[:\s]\s*", "", first_line)
 
 
 def resolve_task_id(client: VikunjaClient, task_id: str) -> int:

src/devx/ci/pr_review.py

@@ -17,7 +17,7 @@ Checks performed:
   8. Commit conventions — conventional commit format on branch commits
 
 Usage:
-  REPO_TOKEN=<token> python3 -m devx.ci.pr_review <pr_number> <owner/repo>
+  CI_GITEA_TOKEN=<token> python3 -m devx.ci.pr_review <pr_number> <owner/repo>
 """
 
 from __future__ import annotations
@@ -387,14 +387,34 @@ def check_documentation(files: list[dict[str, Any]], result: ReviewResult) -> No
         for f in files
     )
     has_ansible_changes = any(f.get("filename", "").startswith("ansible/") for f in files)
+    has_tofu_changes = any(f.get("filename", "").startswith("tofu/") for f in files)
+    has_workflow_changes = any(f.get("filename", "").startswith(".gitea/") for f in files)
+
+    # Check for TODO/FIXME in changed docs
+    todo_issues: list[str] = []
+    for f in files:
+        filename = f.get("filename", "")
+        if filename.endswith(".md") and filename.startswith(("docs/", "README", "AGENTS")):
+            # Can't check file content from PR API easily, but flag if patch adds TODO
+            patch = f.get("patch", "")
+            if patch and re.search(r"^\+.*\b(TODO|FIXME|HACK|XXX)\b", patch, re.IGNORECASE):
+                todo_issues.append(f"{filename}: new TODO/FIXME added in documentation")
 
     if has_src_changes and not has_doc_changes:
         result.add_summary("- Documentation: WARNING — source files changed but no docs updated")
     elif has_ansible_changes and not has_doc_changes:
         result.add_summary("- Documentation: WARNING — Ansible role changed but no docs updated")
+    elif has_tofu_changes and not has_doc_changes:
+        result.add_summary("- Documentation: WARNING — OpenTofu changes but no docs updated")
+    elif has_workflow_changes and not has_doc_changes:
+        result.add_summary("- Documentation: INFO — workflow changes (consider updating CI docs if behavior changed)")
     else:
         result.add_summary("- Documentation: OK")
 
+    if todo_issues:
+        for issue in todo_issues:
+            result.add_summary(f"- Documentation: WARNING — {issue}")
+
 
 def check_test_coverage(files: list[dict[str, Any]], result: ReviewResult) -> None:
     """Check that tests are updated for source changes."""
@@ -520,19 +540,113 @@ def post_review(client: GiteaClient, pr_number: str, result: ReviewResult) -> di
     return client.create_review(pr_number, event=event, body=body, comments=comments)
 
 
+def _post_manual_review(
+    client: GiteaClient,
+    pr_number: str,
+    event: str,
+    body: str | None,
+    checklist_confirmed: bool,
+    checklist_categories: str | None,
+    dry_run: bool,
+) -> None:
+    """Post a manual review with validation for APPROVE events."""
+    if not body or len(body) < 50:
+        raise click.ClickException(_("Review body must be at least 50 characters."))
+
+    if event == "APPROVE":
+        if not checklist_confirmed:
+            raise click.ClickException(
+                _("--checklist-confirmed is required for APPROVE events."),
+            )
+        cats = [c.strip() for c in (checklist_categories or "").split(",") if c.strip()]
+        cat_nums: list[int] = []
+        for c in cats:
+            try:
+                cat_nums.append(int(c))
+            except ValueError:
+                raise click.ClickException(
+                    _("Invalid checklist category: {cat}. Must be numbers.", cat=c),
+                ) from None
+        if len(cat_nums) < 8:
+            raise click.ClickException(
+                _("--checklist-categories must list at least 8 of 13 categories. Got {count}.", count=len(cat_nums)),
+            )
+
+    click.echo(f"Manual review event: {event}")
+    click.echo(f"Body: {body[:80]}...")
+    if checklist_confirmed:
+        click.echo(f"Checklist confirmed: {checklist_categories}")
+
+    if dry_run:
+        click.echo("\n[dry-run] Review not posted.")
+        return
+
+    try:
+        review = client.create_review(pr_number, event=event, body=body)
+    except APIError as e:
+        if "approve" in e.message.lower() or "422" in str(e.status):
+            click.echo(_("Note: Self-approval not allowed. Posting COMMENT instead."))
+            review = client.create_review(pr_number, event="COMMENT", body=body)
+        else:
+            raise
+    review_id = review.get("id", "?")
+    click.echo(
+        _(
+            "\nReview #{review_id} posted on PR #{pr_number} with event '{event}'.",
+            review_id=review_id,
+            pr_number=pr_number,
+            event=event,
+        )
+    )
+
+
 @click.command()
 @click.argument("pr_number")
 @click.argument("repo")
 @click.option("--dry-run", is_flag=True, default=False, help="Print review without posting.")
-def main(pr_number: str, repo: str, dry_run: bool) -> None:
-    """Run automated PR review and post results to Gitea."""
-    token = os.environ.get("REPO_TOKEN", "")
+@click.option(
+    "--event",
+    type=click.Choice(["APPROVE", "REQUEST_CHANGES", "COMMENT"], case_sensitive=False),
+    default=None,
+    help="Post a manual review with the given event (skips automated checks).",
+)
+@click.option("--body", default=None, help="Review body text (required with --event).")
+@click.option(
+    "--checklist-confirmed",
+    is_flag=True,
+    default=False,
+    help="Attest that REVIEW_CHECKLIST.md categories were checked (required for APPROVE).",
+)
+@click.option(
+    "--checklist-categories",
+    default=None,
+    help="Comma-separated checklist category numbers (required for APPROVE, min 8 of 13).",
+)
+def main(
+    pr_number: str,
+    repo: str,
+    dry_run: bool,
+    event: str | None,
+    body: str | None,
+    checklist_confirmed: bool,
+    checklist_categories: str | None,
+) -> None:
+    """Run automated PR review and post results to Gitea.
+
+    Without --event: runs automated checks and posts COMMENT/REQUEST_CHANGES.
+    With --event: posts a manual review (skips automated checks).
+    """
+    token = os.environ.get("CI_GITEA_TOKEN", "")
     if not token:
-        raise click.ClickException(_("ERROR: REPO_TOKEN is not set."))
+        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set."))
 
     owner, repo_name = repo.split("/")
     client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
 
+    if event is not None:
+        _post_manual_review(client, pr_number, event.upper(), body, checklist_confirmed, checklist_categories, dry_run)
+        return
+
     result = run_review(client, pr_number)
 
     body = build_review_body(result)

src/devx/ci/publish.py

@@ -9,26 +9,27 @@ Publishing destinations (checked in order):
      ``DEVX_PYPI_REGISTRY_URL`` env var is set, or ``GITEA_API_URL``
      is converted to a packages URL). Uses ``twine upload
      --repository-url <url> -u <token> -p <token>`` with the
-     ``REPO_TOKEN`` as both username and password.
+     ``CI_GITEA_TOKEN`` as both username and password.
   2. **Standard PyPI** — if ``PYPI_TOKEN`` is set. Uses the standard
      ``twine upload -u __token__ -p <token>`` flow.
   3. **Skip** — if neither is configured, only the Gitea release is created.
 
 Usage:
-  REPO_TOKEN=<token> [PYPI_TOKEN=<token>] python3 -m devx.ci.publish <tag> <repo>
-  REPO_TOKEN=<token> python3 -m devx.ci.publish <tag> <repo> --registry-url https://git.example.com/api/packages/owner/pypi
+  CI_GITEA_TOKEN=<token> [PYPI_TOKEN=<token>] python3 -m devx.ci.publish <tag> <repo>
+  CI_GITEA_TOKEN=<token> python3 -m devx.ci.publish <tag> <repo> --registry-url https://git.example.com/api/packages/owner/pypi
 """
 
 import os
 import shutil
 import subprocess  # nosec B404
 import sys
+from pathlib import Path
 
 import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
 
-from devx.config import GITEA_API_URL
-from devx.gitea_cli import TeaCLI, TeaCLIError
+from devx.config import GITEA_API_URL, REPO_OWNER
+from devx.gitea_cli import TeaCLI, TeaCLIError, configure_tea_login
 from devx.i18n import _
 
 load_dotenv()
@@ -60,6 +61,12 @@ def generate_release_notes(tag: str) -> str:
 
 def build_package() -> None:
     """Build the Python package using python -m build."""
+    # Clean dist/ to avoid uploading stale packages from previous builds
+    # (Gitea PyPI returns 409 Conflict for already-published versions).
+    dist_dir = Path("dist")
+    if dist_dir.exists():
+        shutil.rmtree(dist_dir)
+
     result = subprocess.run(  # nosec B603
         [sys.executable, "-m", "build"],
         capture_output=True,
@@ -128,13 +135,21 @@ def publish_to_gitea_registry(registry_url: str, token: str) -> None:
         check=False,
     )
     if result.returncode != 0:
-        raise click.ClickException(
-            _(
-                "Oops! Gitea PyPI registry publish failed:\n{stderr}",
-                stderr=result.stderr.strip(),
+        # Twine writes errors to stdout (not stderr), so check both.
+        combined = f"{result.stdout}\n{result.stderr}".strip()
+        # 409 Conflict means the package version is already published —
+        # this is not an error, just a sign we're re-running publish.
+        if "409" in combined or "Conflict" in combined:
+            click.echo(_("Gitea PyPI registry: {tag} already published — continuing.", tag=""))
+        else:
+            raise click.ClickException(
+                _(
+                    "Oops! Gitea PyPI registry publish failed:\n{stderr}",
+                    stderr=combined,
+                )
             )
-        )
-    click.echo(_("Published to Gitea PyPI registry."))
+    else:
+        click.echo(_("Published to Gitea PyPI registry."))
 
 
 def _default_gitea_registry_url() -> str:
@@ -150,13 +165,41 @@ def _default_gitea_registry_url() -> str:
         base = base[: -len("/api/v1")]
     elif base.endswith("/api"):
         base = base[: -len("/api")]
-    owner = os.environ.get("DEVX_REPO_OWNER", "oblachno-oss")
+    owner = os.environ.get("DEVX_REPO_OWNER", "") or REPO_OWNER
     return f"{base}/api/packages/{owner}/pypi"
 
 
+def get_latest_tag() -> str | None:
+    """Get the latest git tag, or None if no tags exist."""
+    try:
+        result = subprocess.run(  # nosec
+            ["git", "describe", "--tags", "--abbrev=0"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError:
+        return None
+
+
+def is_release_commit(tag: str) -> bool:
+    """Check if HEAD commit message starts with 'release: <tag>'."""
+    try:
+        result = subprocess.run(  # nosec
+            ["git", "log", "-1", "--format=%s"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip().startswith(f"release: {tag}")
+    except subprocess.CalledProcessError:
+        return False
+
+
 @click.command()
-@click.argument("tag")
-@click.argument("repo")
+@click.argument("tag", required=False)
+@click.argument("repo", required=False)
 @click.option(
     "--registry-url",
     default=None,
@@ -171,10 +214,48 @@ def _default_gitea_registry_url() -> str:
     help="Skip package build and PyPI publish (for non-Python repos that only "
     "need a Gitea release with git-cliff notes).",
 )
-def main(tag: str, repo: str, registry_url: str | None, skip_build: bool) -> None:
-    gitea_token = os.environ.get("REPO_TOKEN", "")
+@click.option(
+    "--from-tag",
+    is_flag=True,
+    default=False,
+    help="Auto-detect latest tag and check if HEAD is a release commit. "
+    "Skips publish if no tag or HEAD is not a release commit for that tag.",
+)
+@click.option(
+    "--auto-login",
+    is_flag=True,
+    default=False,
+    help="Configure tea CLI login from CI_GITEA_TOKEN before creating the Gitea release. "
+    "Eliminates the need for a separate tea login step in containerized CI jobs.",
+)
+def main(
+    tag: str | None,
+    repo: str | None,
+    registry_url: str | None,
+    skip_build: bool,
+    from_tag: bool,
+    auto_login: bool,
+) -> None:
+    if repo is None:
+        repo = os.environ.get("GITHUB_REPOSITORY", "")
+    if not repo:
+        raise click.ClickException(_("REPO argument is required (or set GITHUB_REPOSITORY env var)."))
+    if from_tag:
+        detected_tag = get_latest_tag()
+        if not detected_tag:
+            click.echo(_("No tag found — skipping publish."))
+            return
+        if not is_release_commit(detected_tag):
+            click.echo(_("HEAD is not a release commit for {tag} — skipping publish.", tag=detected_tag))
+            return
+        tag = detected_tag
+        click.echo(_("Publishing release {tag}...", tag=tag))
+
+    if not tag:
+        raise click.ClickException(_("Tag is required (or use --from-tag)."))
+    gitea_token = os.environ.get("CI_GITEA_TOKEN", "")
     if not gitea_token:
-        raise click.ClickException(_("ERROR: REPO_TOKEN is not set."))
+        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set."))
 
     pypi_token = os.environ.get("PYPI_TOKEN", "")
 
@@ -187,28 +268,54 @@ def main(tag: str, repo: str, registry_url: str | None, skip_build: bool) -> Non
     if not skip_build:
         build_package()
 
-        if pypi_token:
-            # Standard PyPI flow takes precedence when PYPI_TOKEN is set
-            publish_to_pypi(pypi_token)
-        elif registry_url:
-            # Gitea PyPI registry flow
-            publish_to_gitea_registry(registry_url, gitea_token)
-        else:
+        try:
+            if pypi_token:
+                # Standard PyPI flow takes precedence when PYPI_TOKEN is set
+                publish_to_pypi(pypi_token)
+            elif registry_url:
+                # Gitea PyPI registry flow
+                publish_to_gitea_registry(registry_url, gitea_token)
+            else:
+                click.echo(
+                    _(
+                        "PYPI_TOKEN not set and no registry URL configured — "
+                        "skipping PyPI publish. No worries, we'll just create the Gitea release."
+                    )
+                )
+        except click.ClickException as e:
             click.echo(
                 _(
-                    "PYPI_TOKEN not set and no registry URL configured — "
-                    "skipping PyPI publish. No worries, we'll just create the Gitea release."
-                )
+                    "PyPI publish failed (non-fatal — continuing to Gitea release):\n{error}",
+                    error=str(e),
+                ),
+                err=True,
             )
     else:
         click.echo(_("--skip-build: skipping package build and PyPI publish."))
 
     tea = TeaCLI(repo=repo)
+
+    if auto_login:
+        configure_tea_login()
+
+    # Check if release already exists (idempotent — avoids failure when
+    # called multiple times, e.g. by both post-merge and publish workflows)
+    try:
+        releases = tea.list_releases(repo)
+        if any(r.get("tag_name") == tag for r in releases):
+            click.echo(_("Gitea release {tag} already exists — skipping creation.", tag=tag))
+            return
+    except TeaCLIError:
+        pass  # If listing fails, proceed to create
+
     release_body = generate_release_notes(tag)
 
     try:
         tea.create_release(repo, tag=tag, title=tag, body=release_body)
     except TeaCLIError as e:
+        if "already" in str(e).lower() and "release" in str(e).lower():
+            click.echo(_("Gitea release {tag} already exists — skipping creation.", tag=tag))
+            return
         raise click.ClickException(_("Release creation failed: {error}", error=str(e))) from None
 
     click.echo(

src/devx/ci/push_badges.py

@@ -18,6 +18,7 @@ Usage::
 from __future__ import annotations
 
 import contextlib
+import os
 import re
 import subprocess  # nosec B404
 import sys
@@ -27,7 +28,18 @@ from typing import Any
 
 import click
 
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+from devx.i18n import _
+
+
+def _repo_root() -> Path:
+    """Resolve repo root from GITHUB_WORKSPACE or cwd."""
+    workspace = os.environ.get("GITHUB_WORKSPACE")
+    if workspace:
+        path = Path(workspace)
+        if path.is_dir():
+            return path
+    return Path.cwd()
+
 
 # Badge filenames that get pushed to the badges branch
 BADGE_FILES = ["coverage.svg", "tests.svg", "docs.svg", "quality.svg", "version.svg", "python.svg"]
@@ -58,7 +70,7 @@ def fetch_latest_master(branch: str = "master") -> None:
     """
     _run(["git", "fetch", "origin", branch])  # nosec B607
     _run(["git", "reset", "--hard", f"origin/{branch}"])  # nosec B607
-    click.echo(f"Synced to latest origin/{branch}")
+    click.echo(_("Synced to latest origin/{branch}", branch=branch))
 
 
 def generate_badges(output_dir: str) -> None:
@@ -66,8 +78,8 @@ def generate_badges(output_dir: str) -> None:
     _run([sys.executable, "-m", "devx.tools.generate_badges", "--output-dir", output_dir])
     badges = list(Path(output_dir).glob("*.svg"))
     if not badges:
-        raise click.ClickException("No badge SVG files generated")
-    click.echo(f"Generated {len(badges)} badge files")
+        raise click.ClickException(_("No badge SVG files generated"))
+    click.echo(_("Generated {count} badge files", count=len(badges)))
 
 
 def push_to_badges_branch(badges_dir: str) -> str:
@@ -89,12 +101,12 @@ def push_to_badges_branch(badges_dir: str) -> str:
     _run(["git", "add", "./*.svg"])  # nosec B607
     _run(["git", "commit", "--no-verify", "-m", "Update badges [skip ci]"])  # nosec B607
     _run(["git", "push", "origin", "badges", "--force"])  # nosec B607
-    click.echo("Badges pushed to badges branch")
+    click.echo(_("Badges pushed to badges branch"))
 
     # Get the commit SHA of the badges branch
     result = _run_capture(["git", "rev-parse", "HEAD"])  # nosec B607
     sha = result.stdout.strip()
-    click.echo(f"Badges commit SHA: {sha}")
+    click.echo(_("Badges commit SHA: {sha}", sha=sha))
     return sha
 
 
@@ -116,7 +128,7 @@ def update_readme_with_badge_sha(badges_sha: str, repo_root: Path | None = None)
     Switches back to master, replaces ``raw/branch/badges/`` URLs with
     ``raw/commit/<sha>/`` URLs, commits and pushes.
     """
-    root = repo_root or REPO_ROOT
+    root = repo_root or _repo_root()
 
     # Switch back to master
     _run(["git", "checkout", "master"])  # nosec B607
@@ -132,11 +144,11 @@ def update_readme_with_badge_sha(badges_sha: str, repo_root: Path | None = None)
         new_content = update_badge_urls(content, badges_sha)
         if new_content != content:
             filepath.write_text(new_content)
-            click.echo(f"Updated badge URLs in {filename}")
+            click.echo(_("Updated badge URLs in {filename}", filename=filename))
             updated_any = True
 
     if not updated_any:
-        click.echo("No badge URLs found to update — README already up to date")
+        click.echo(_("No badge URLs found to update — README already up to date"))
         return
 
     _run(["git", "add", "README.md", "docs/index.md"])  # nosec B607
@@ -150,7 +162,7 @@ def update_readme_with_badge_sha(badges_sha: str, repo_root: Path | None = None)
         ]
     )  # nosec B607
     _run(["git", "push", "origin", "master"])  # nosec B607
-    click.echo(f"Pushed README update with badge SHA {badges_sha[:8]}")
+    click.echo(_("Pushed README update with badge SHA {sha}", sha=badges_sha[:8]))
 
 
 @click.command()
@@ -183,13 +195,22 @@ def main(output_dir: str, branch: str, no_readme_update: bool, retries: int) ->
         except (subprocess.CalledProcessError, RuntimeError) as exc:
             last_error = exc
             if attempt < retries:
-                click.echo(f"Badge push attempt {attempt}/{retries} failed — retrying: {exc}")
+                click.echo(
+                    _(
+                        "Badge push attempt {attempt}/{retries} failed — retrying: {error}",
+                        attempt=attempt,
+                        retries=retries,
+                        error=exc,
+                    )
+                )
                 time.sleep(10)
                 with contextlib.suppress(subprocess.CalledProcessError):
                     fetch_latest_master(branch)
             else:
-                click.echo(f"Badge push failed after {retries} attempts: {exc}")
-    raise click.ClickException(f"Badge push failed after {retries} attempts: {last_error}")
+                click.echo(_("Badge push failed after {retries} attempts: {error}", retries=retries, error=exc))
+    raise click.ClickException(
+        _("Badge push failed after {retries} attempts: {error}", retries=retries, error=last_error)
+    )
 
 
 if __name__ == "__main__":  # pragma: no cover

src/devx/ci/release.py

@@ -29,7 +29,7 @@ version.  This prevents duplicate release commits (a common issue when CI
 checkouts don't fetch tags) and ensures tag/version/commit alignment.
 
 Usage:
-  REPO_TOKEN=<token> python3 -m devx.ci.release [--dry-run] [--skip-tests]
+  CI_GITEA_TOKEN=<token> python3 -m devx.ci.release [--dry-run] [--skip-tests]
   python3 -m devx.ci.release --verify   # Check tag/version/release alignment
 """
 
@@ -37,13 +37,13 @@ from __future__ import annotations
 
 import os
 import re
-import subprocess  # nosec B404
 import sys
+import time
 
 import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
 
-from devx.ci._shared import get_latest_tag
+from devx.ci._shared import get_latest_tag, run_cmd, write_github_output
 from devx.ci.classify_changes import has_user_facing_changes  # cross-CI import, needs PYTHONPATH=.
 from devx.i18n import _
 
@@ -54,25 +54,6 @@ CHANGELOG_FILE = "CHANGELOG.md"
 CLIFF_CONFIG = "cliff.toml"
 
 
-def run_cmd(args: list[str], check: bool = True, capture: bool = True) -> subprocess.CompletedProcess[str]:
-    """Run a command and return the completed process."""
-    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 tag_exists(tag: str) -> bool:
     """Check if a git tag already exists."""
     result = run_cmd(["git", "tag", "-l", tag], check=False)
@@ -136,10 +117,14 @@ def verify_tag_consistency() -> list[str]:
     """
     errors: list[str] = []
     tags = get_all_tags()
-    # Sort oldest first to identify the first tag
-    sorted_tags = sorted(tags, key=lambda t: [int(x) for x in t.lstrip("v").split(".")])
+    # Filter to version tags (vX.Y.Z) and sort oldest first
+    version_tags = [t for t in tags if re.match(r"^v\d+\.\d+\.\d+$", t)]
+    sorted_tags = sorted(version_tags, key=lambda t: [int(x) for x in t.lstrip("v").split(".")])
     first_tag = sorted_tags[0] if sorted_tags else None
     for tag in tags:
+        # Skip non-version tags (e.g., branch names like "master")
+        if not re.match(r"^v\d+\.\d+\.\d+$", tag):
+            continue
         tag_version = tag.lstrip("v")
         commit_version = get_commit_version(tag)
         if commit_version is None:
@@ -213,7 +198,7 @@ def has_unreleased_changes(bumped_version: str | None = None) -> bool:
 
 def update_init_version(new_version: str) -> None:
     """Update __version__ in __init__.py."""
-    with open(INIT_FILE) as f:
+    with open(INIT_FILE, encoding="utf-8") as f:
         content = f.read()
     if not re.search(r'^__version__\s*=\s*"[^"]*"', content, flags=re.MULTILINE):
         raise click.ClickException(_("Could not find __version__ in {file}", file=INIT_FILE))
@@ -224,7 +209,7 @@ def update_init_version(new_version: str) -> None:
         count=1,
         flags=re.MULTILINE,
     )
-    with open(INIT_FILE, "w") as f:
+    with open(INIT_FILE, "w", encoding="utf-8") as f:
         f.write(updated)
 
 
@@ -241,10 +226,10 @@ def update_changelog(changelog: str) -> None:
         changelog = changelog[section_match.start() :]
 
     try:
-        with open(CHANGELOG_FILE) as f:
+        with open(CHANGELOG_FILE, encoding="utf-8") as f:
             existing = f.read()
     except FileNotFoundError:
-        with open(CHANGELOG_FILE, "w") as f:
+        with open(CHANGELOG_FILE, "w", encoding="utf-8") as f:
             f.write(changelog + "\n")
         return
 
@@ -257,7 +242,7 @@ def update_changelog(changelog: str) -> None:
     else:
         # No version sections found — append
         updated = existing.rstrip() + "\n\n" + changelog + "\n"
-    with open(CHANGELOG_FILE, "w") as f:
+    with open(CHANGELOG_FILE, "w", encoding="utf-8") as f:
         f.write(updated)
 
 
@@ -313,6 +298,19 @@ def run_tests() -> None:
     click.echo(_("Tests passed."))
 
 
+def _write_release_tag(tag: str) -> None:
+    """Write the release tag to GITHUB_OUTPUT for downstream jobs.
+
+    This allows a publish job (needs: release) to read the tag via
+    ``${{ needs.release.outputs.tag }}`` instead of relying on
+    tag-push event triggering a separate workflow.
+    """
+    if not os.environ.get("GITHUB_OUTPUT"):
+        return
+    write_github_output("tag", tag)
+    click.echo(_("Wrote tag {tag} to GITHUB_OUTPUT.", tag=tag))
+
+
 def create_and_push_tag(new_version: str, changelog: str, dry_run: bool) -> bool:
     """Create an annotated tag with the changelog as message and push it.
 
@@ -340,14 +338,16 @@ def create_and_push_tag(new_version: str, changelog: str, dry_run: bool) -> bool
         click.echo(_("Tag {tag} already exists and points to HEAD. Skipping creation.", tag=tag))
         if not dry_run:
             # Ensure the existing tag is pushed
-            run_cmd(["git", "push", "origin", tag], check=False)
+            run_cmd(["git", "push", "origin", f"refs/tags/{tag}"], check=False)
+        _write_release_tag(tag)
         return False
     tag_msg = f"Release v{new_version}\n\n{changelog}"
     if dry_run:
         click.echo(_("[dry-run] Would create tag: {tag}", tag=tag))
         return True
     run_cmd(["git", "tag", "-a", tag, "-m", tag_msg])
-    run_cmd(["git", "push", "origin", tag])
+    run_cmd(["git", "push", "origin", f"refs/tags/{tag}"])
+    _write_release_tag(tag)
     return True
 
 
@@ -359,7 +359,7 @@ def create_and_push_tag(new_version: str, changelog: str, dry_run: bool) -> bool
 def get_init_version() -> str | None:
     """Read __version__ from the version file."""
     try:
-        with open(INIT_FILE) as f:
+        with open(INIT_FILE, encoding="utf-8") as f:
             content = f.read()
         match = re.search(r'^__version__\s*=\s*"([^"]*)"', content, flags=re.MULTILINE)
         return match.group(1) if match else None
@@ -370,7 +370,7 @@ def get_init_version() -> str | None:
 def get_changelog_versions() -> list[str]:
     """Extract version numbers from CHANGELOG.md headers, in order."""
     try:
-        with open(CHANGELOG_FILE) as f:
+        with open(CHANGELOG_FILE, encoding="utf-8") as f:
             content = f.read()
         return re.findall(r"^## \[(\d+\.\d+\.\d+)\]", content, flags=re.MULTILINE)
     except FileNotFoundError:
@@ -478,7 +478,7 @@ def verify_alignment() -> int:
     )
     if result.returncode == 0 and result.stdout.strip():
         all_release_commits = result.stdout.strip().split("\n")
-        all_tags_set = {t.lstrip("v") for t in get_all_tags()}
+        all_tags_set = {t.lstrip("v") for t in get_all_tags() if re.match(r"^v\d+\.\d+\.\d+$", t)}
         truly_untagged: list[str] = []
         duplicates: list[str] = []
         for line in all_release_commits:
@@ -547,6 +547,8 @@ def main(dry_run: bool, skip_tests: bool, verify: bool) -> None:
 
     # Ensure we're on master (skip this check in dry-run mode for PR validation)
     branch = run_cmd(["git", "rev-parse", "--abbrev-ref", "HEAD"]).stdout.strip()
+    # Some git versions return "heads/master" instead of "master"
+    branch = branch.removeprefix("heads/")
     if branch != "master" and not dry_run:
         raise click.ClickException(_("Release must be run on master, currently on '{branch}'.", branch=branch))
     if branch != "master" and dry_run:
@@ -611,6 +613,7 @@ def main(dry_run: bool, skip_tests: bool, verify: bool) -> None:
                     tag=release_tag,
                 )
             )
+            _write_release_tag(release_tag)
             return
         # Tag is missing — recover by creating and pushing it
         click.echo(
@@ -645,6 +648,20 @@ def main(dry_run: bool, skip_tests: bool, verify: bool) -> None:
         return
 
     current_tag = get_latest_tag()
+    # If the bumped version equals the current tag version, there's nothing
+    # new to release. git-cliff didn't bump because the commits since the last
+    # tag don't warrant a version change (e.g., only ci:/chore: commits).
+    # Creating a release commit with the same version would cause a tag
+    # conflict.
+    if current_tag and current_tag.lstrip("v") == new_version:
+        click.echo(
+            _(
+                "Version stays at v{version} — no version bump from git-cliff. "
+                "Commits since last tag don't warrant a new release. Skipping.",
+                version=new_version,
+            )
+        )
+        return
     click.echo(
         _(
             "Bumping version: {current} -> v{new_version}",
@@ -667,7 +684,7 @@ def main(dry_run: bool, skip_tests: bool, verify: bool) -> None:
         click.echo(_("\n[dry-run] Changelog:\n{changelog}", changelog=changelog))
         click.echo(_("[dry-run] Would update {init}", init=INIT_FILE))
         click.echo(_("[dry-run] Would update {changelog_file}", changelog_file=CHANGELOG_FILE))
-        click.echo(_("[dry-run] Would commit: release: v{version}", version=new_version))
+        click.echo(_("[dry-run] Would commit: release: v{version} [skip ci]", version=new_version))
         click.echo(_("[dry-run] Would push commit to master"))
         click.echo(_("[dry-run] Would create tag: v{version}", version=new_version))
         return
@@ -693,8 +710,39 @@ def main(dry_run: bool, skip_tests: bool, verify: bool) -> None:
         click.echo(_("Created release commit."))
         # Pull --rebase before push to handle the case where master
         # advanced between checkout and commit (e.g., another merge).
-        run_cmd(["git", "pull", "--rebase", "origin", "master"], check=False)
-        run_cmd(["git", "push", "origin", "master"])
+        # Retry up to 3 times to handle concurrent pushes.
+        push_succeeded = False
+        for attempt in range(3):
+            rebase = run_cmd(["git", "pull", "--rebase", "origin", "master"], check=False)
+            if rebase.returncode != 0:
+                # Rebase failed (likely conflicts). Abort and retry.
+                click.echo(
+                    _(
+                        "Rebase attempt {n}/3 failed: {err}",
+                        n=attempt + 1,
+                        err=rebase.stderr.strip() if rebase.stderr else rebase.stdout.strip(),
+                    )
+                )
+                run_cmd(["git", "rebase", "--abort"], check=False)
+                # Brief delay before retry to let concurrent pushes settle.
+                time.sleep(5)
+                continue
+            push = run_cmd(["git", "push", "origin", "refs/heads/master:refs/heads/master"], check=False)
+            if push.returncode == 0:
+                push_succeeded = True
+                break
+            click.echo(
+                _(
+                    "Push attempt {n}/3 failed: {err}",
+                    n=attempt + 1,
+                    err=push.stderr.strip() if push.stderr else push.stdout.strip(),
+                )
+            )
+            time.sleep(5)
+        if not push_succeeded:
+            raise click.ClickException(
+                _("Failed to push release commit after 3 attempts. Manual intervention required.")
+            )
         click.echo(_("Pushed release commit to master."))
     else:
         click.echo(_("Skipping commit push — no staged changes."))

src/devx/ci/sync_wiki.py

@@ -14,21 +14,29 @@ Gitea 1.26 wiki API endpoints (all use content_base64, NOT content):
   - Delete: DELETE /repos/{owner}/{repo}/wiki/page/{sub_url}
 
 Usage:
-  REPO_TOKEN=<token> python3 -m devx.ci.sync_wiki [--dry-run] [--repo owner/repo]
+  CI_GITEA_TOKEN=<token> python3 -m devx.ci.sync_wiki [--dry-run] [--repo owner/repo]
 """
 
 from __future__ import annotations
 
 import base64
 import json
+import logging
 import os
 from pathlib import Path
 
 import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
+from tenacity import (
+    before_sleep_log,
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
 
 from devx.api_clients import GiteaClient
-from devx.config import GITEA_API_URL
+from devx.config import GITEA_API_URL, REPO_NAME, REPO_OWNER
 from devx.exceptions import APIError
 from devx.i18n import _
 
@@ -49,7 +57,7 @@ def load_mapping() -> dict[str, str]:
 
     Validates that the mapping is a dict of string-to-string pairs.
     """
-    with open(MAPPING_FILE) as f:
+    with open(MAPPING_FILE, encoding="utf-8") as f:
         data = json.load(f)
     if not isinstance(data, dict):
         raise click.ClickException(
@@ -64,7 +72,7 @@ def load_mapping() -> dict[str, str]:
 def read_doc_content(file_path: str) -> str:
     """Read markdown content from a docs file."""
     full_path = DOCS_DIR / file_path
-    with open(full_path) as f:
+    with open(full_path, encoding="utf-8") as f:
         return f.read()
 
 
@@ -86,11 +94,12 @@ def decode_content(content_b64: str) -> str:
 
 
 def list_wiki_pages(client: GiteaClient) -> dict[str, str]:
-    """List existing wiki pages, returning {title: sub_url}."""
-    try:
-        pages = client._request("GET", "/wiki/pages").json()
-    except APIError:
-        return {}
+    """List existing wiki pages, returning {title: sub_url}.
+
+    Raises :class:`APIError` if the wiki API is unavailable — the caller
+    is responsible for retrying or handling the failure.
+    """
+    pages = client._request("GET", "/wiki/pages").json()
     return {page.get("title", ""): page.get("sub_url", page.get("title", "")) for page in pages}
 
 
@@ -113,6 +122,9 @@ def sync_page(
     """Create or update a single wiki page.
 
     Returns "created", "updated", or "skipped" (if dry-run).
+
+    If a create fails with HTTP 400 "already exists" (the page list was
+    stale), re-lists the wiki and falls back to an update.
     """
     if dry_run:
         click.echo(_("[dry-run] Would sync page: {title} ({chars} chars)", title=page_title, chars=len(content)))
@@ -135,16 +147,36 @@ def sync_page(
         return "updated"
 
     # Create new page via POST /wiki/new
-    client._request(
-        "POST",
-        "/wiki/new",
-        json={
-            "title": page_title,
-            "content_base64": content_b64,
-            "message": f"Sync from docs/ — create {page_title}",
-        },
-    )
-    return "created"
+    try:
+        client._request(
+            "POST",
+            "/wiki/new",
+            json={
+                "title": page_title,
+                "content_base64": content_b64,
+                "message": f"Sync from docs/ — create {page_title}",
+            },
+        )
+        return "created"
+    except APIError as e:
+        if e.status == 400 and "already exists" in e.message.lower():
+            # The page list was stale (e.g. after a timeout-retry returned
+            # incomplete data). Re-list and fall back to update.
+            click.echo(_("  Page '{title}' already exists (stale list). Re-listing and updating...", title=page_title))
+            fresh_pages = _list_wiki_pages_with_retry(client)
+            if page_title in fresh_pages:
+                sub_url = fresh_pages[page_title]
+                client._request(
+                    "PATCH",
+                    f"/wiki/page/{sub_url}",
+                    json={
+                        "title": page_title,
+                        "content_base64": content_b64,
+                        "message": f"Sync from docs/ — update {page_title} (create→update fallback)",
+                    },
+                )
+                return "updated"
+        raise
 
 
 def verify_wiki_page(
@@ -161,6 +193,28 @@ def verify_wiki_page(
     return actual.strip() == expected_content.strip()
 
 
+def _list_wiki_pages_with_retry(client: GiteaClient) -> dict[str, str]:
+    """List wiki pages with tenacity retry on APIError.
+
+    The Gitea wiki API can be slow (it renders pages on each request)
+    and may time out. Uses 5 attempts with exponential backoff to handle
+    transient slowness.
+    """
+    _logger = logging.getLogger("sync_wiki")
+
+    @retry(
+        stop=stop_after_attempt(5),
+        wait=wait_exponential(multiplier=2, min=2, max=16),
+        retry=retry_if_exception_type(APIError),
+        before_sleep=before_sleep_log(_logger, logging.WARNING),
+        reraise=True,
+    )
+    def _do_list() -> dict[str, str]:
+        return list_wiki_pages(client)
+
+    return _do_list()
+
+
 def verify_wiki_integrity(
     client: GiteaClient,
     mapping: dict[str, str],
@@ -176,9 +230,25 @@ def verify_wiki_integrity(
     5. Page count matches
 
     Returns a list of failure messages (empty if all checks pass).
+    If the wiki API is temporarily unavailable (all retry attempts
+    fail), returns an empty list with a warning — the sync itself
+    already succeeded, so a transient API outage should not fail the job.
     """
     failures: list[str] = []
-    existing_pages = list_wiki_pages(client)
+
+    try:
+        existing_pages = _list_wiki_pages_with_retry(client)
+    except APIError:
+        click.echo(
+            _(
+                "WARNING: Could not fetch wiki page list after retries. "
+                "The sync itself succeeded ({count} pages updated), but the "
+                "integrity check could not verify them due to a transient API issue.",
+                count=len(synced),
+            )
+        )
+        return []
+
     expected_titles = set(mapping.values())
 
     # Check 1: Page count
@@ -225,13 +295,13 @@ def verify_wiki_integrity(
     help="Full integrity check: verify page count, missing pages, stale pages, and content. Implies --verify.",
 )
 def main(dry_run: bool, repo: str | None, verify: bool, strict: bool) -> None:
-    token = os.environ.get("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."))
 
     if repo is None:
-        owner = os.environ.get("DEVX_REPO_OWNER", "oblachno-oss")
-        repo_name = os.environ.get("DEVX_REPO_NAME", "devx")
+        owner = os.environ.get("DEVX_REPO_OWNER", "") or REPO_OWNER
+        repo_name = os.environ.get("DEVX_REPO_NAME", "") or REPO_NAME
     else:
         owner, repo_name = repo.split("/")
 
@@ -243,7 +313,16 @@ def main(dry_run: bool, repo: str | None, verify: bool, strict: bool) -> None:
 
     click.echo(_("Syncing {count} documentation pages to wiki...", count=len(mapping)))
 
-    existing_pages = list_wiki_pages(client)
+    try:
+        existing_pages = _list_wiki_pages_with_retry(client)
+    except APIError as e:
+        raise click.ClickException(
+            _(
+                "Failed to list existing wiki pages after retries: {error}. "
+                "Aborting to avoid creating duplicate pages.",
+                error=e,
+            )
+        ) from e
     if existing_pages:
         click.echo(_("Found {count} existing wiki pages.", count=len(existing_pages)))
 
@@ -302,7 +381,16 @@ def main(dry_run: bool, repo: str | None, verify: bool, strict: bool) -> None:
         else:
             click.echo(_("\nVerifying wiki pages have content..."))
             # Re-fetch the page list to get updated sub_urls
-            existing_pages = list_wiki_pages(client)
+            try:
+                existing_pages = _list_wiki_pages_with_retry(client)
+            except APIError:
+                click.echo(
+                    _(
+                        "WARNING: Could not re-fetch wiki page list for verification. "
+                        "Skipping content verification due to transient API issue."
+                    )
+                )
+                return
             failures = 0
             for page_title, expected_content in sorted(synced.items()):
                 ok = verify_wiki_page(client, page_title, expected_content, existing_pages)

src/devx/ci/validate_commit_msg.py

@@ -14,6 +14,7 @@ task ID format for each project.
 
 import re
 import subprocess  # nosec B404
+import sys
 
 import click
 
@@ -23,6 +24,17 @@ from devx.i18n import _
 MASTER_TASK_ID_RE = re.compile(rf"^{TASK_PREFIX}-\d+:")
 
 
+def get_latest_commit_msg() -> str:
+    """Get the latest commit message from git."""
+    result = subprocess.run(  # nosec
+        ["git", "log", "-1", "--format=%B"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.strip()
+
+
 def first_line(text: str) -> str:
     return text.split("\n")[0]
 
@@ -41,11 +53,26 @@ def get_branch() -> str:
 
 
 @click.command()
-@click.argument("commit_msg_file")
+@click.argument("commit_msg_file", required=False)
 @click.option("--branch", default=None, help="Override branch detection (for CI use).")
-def main(commit_msg_file: str, branch: str | None) -> None:
-    with open(commit_msg_file) as f:
-        msg = f.read().strip()
+@click.option(
+    "--git",
+    "from_git",
+    is_flag=True,
+    default=False,
+    help="Read commit message from git log instead of a file.",
+)
+def main(commit_msg_file: str | None, branch: str | None, from_git: bool) -> None:
+    if from_git:
+        msg = get_latest_commit_msg()
+    elif commit_msg_file:
+        if commit_msg_file == "-":
+            msg = sys.stdin.read().strip()
+        else:
+            with open(commit_msg_file, encoding="utf-8") as f:
+                msg = f.read().strip()
+    else:
+        raise click.ClickException(_("Provide a commit message file or use --git."))
 
     if branch is None:
         branch = get_branch()

src/devx/cli.py

@@ -95,6 +95,13 @@ def ci_doc_coverage(args: tuple[str, ...]) -> None:
     _run_module("devx.ci.doc_coverage", list(args))
 
 
+@ci.command("lint-docs")
+@click.argument("args", nargs=-1)
+def ci_lint_docs(args: tuple[str, ...]) -> None:
+    """Lint documentation files for structure, links, and quality."""
+    _run_module("devx.ci.lint_docs", list(args))
+
+
 @ci.command("notify-failure")
 @click.argument("args", nargs=-1)
 def ci_notify_failure(args: tuple[str, ...]) -> None:
@@ -158,17 +165,10 @@ def ci_distribute_files(args: tuple[str, ...]) -> None:
     _run_module("devx.ci.distribute_files", list(args))
 
 
-@ci.command("merge-junit")
-@click.argument("args", nargs=-1)
-def ci_merge_junit(args: tuple[str, ...]) -> None:
-    """Merge multiple JUnit XML reports into a single report."""
-    _run_module("devx.ci.merge_junit", list(args))
-
-
 @ci.command("integration-guard")
 @click.argument("args", nargs=-1)
 def ci_integration_guard(args: tuple[str, ...]) -> None:
-    """Run pytest with cross-runner failure detection and JUnit output."""
+    """Run pytest with cross-runner failure detection."""
     _run_module("devx.ci.integration_guard", list(args))
 
 
@@ -226,6 +226,20 @@ def tools_setup(args: tuple[str, ...]) -> None:
     _run_module("devx.tools.setup", list(args))
 
 
+@tools.command("rebase")
+@click.argument("args", nargs=-1)
+def tools_rebase(args: tuple[str, ...]) -> None:
+    """Rebase current branch onto origin/master and force-push."""
+    _run_module("devx.tools.rebase", list(args))
+
+
+@tools.command("pr-rebase")
+@click.argument("args", nargs=-1)
+def tools_pr_rebase(args: tuple[str, ...]) -> None:
+    """Rebase a PR's head branch onto master via Gitea API (server-side)."""
+    _run_module("devx.tools.pr_rebase", list(args))
+
+
 @cli.group()
 def molecule() -> None:
     """Molecule testing commands (requires devx[molecule])."""

src/devx/config.py

@@ -1,27 +1,87 @@
 """Shared configuration constants for devx scripts and API clients.
 
-All defaults can be overridden via environment variables with the ``DEVX_``
-prefix. Projects consuming devx can set these in their ``.env`` files.
+Configuration is read from two sources, in priority order:
+
+1. **Environment variables** (``DEVX_`` prefix) — highest priority, used for
+   CI secrets and per-run overrides.
+2. **``[tool.devx]`` section in ``pyproject.toml``** — project defaults,
+   read from the current working directory.
+
+If neither source provides a value, built-in defaults are used.
 """
 
 from __future__ import annotations
 
 import os
 import re
+import tomllib
+from pathlib import Path
+
+
+def _load_pyproject_devx() -> dict[str, object]:
+    """Load the ``[tool.devx]`` section from pyproject.toml in the CWD.
+
+    Returns an empty dict if the file or section is missing.
+    """
+    path = Path("pyproject.toml")
+    if not path.exists():
+        return {}
+    try:
+        with open(path, "rb") as f:  # noqa: PTH123
+            data: dict[str, object] = tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError):
+        return {}
+    tool_raw: object = data.get("tool", {})
+    if not isinstance(tool_raw, dict):
+        return {}
+    tool: dict[str, object] = tool_raw  # type: ignore[assignment]
+    devx_raw: object = tool.get("devx", {})
+    if not isinstance(devx_raw, dict):
+        return {}
+    devx: dict[str, object] = devx_raw  # type: ignore[assignment]
+    return devx
+
+
+_PYPROJECT = _load_pyproject_devx()
+
+
+def _get(key: str, env_var: str, default: str) -> str:
+    """Get a config value: env var > pyproject.toml > default."""
+    env_val = os.getenv(env_var)
+    if env_val is not None:
+        return env_val
+    pyproject_val = _PYPROJECT.get(key)
+    if isinstance(pyproject_val, str):
+        return pyproject_val
+    return default
+
+
+def _get_int(key: str, env_var: str, default: int) -> int:
+    """Get an int config value: env var > pyproject.toml > default."""
+    env_val = os.getenv(env_var)
+    if env_val is not None:
+        return int(env_val)
+    pyproject_val = _PYPROJECT.get(key)
+    if isinstance(pyproject_val, int):
+        return pyproject_val
+    return default
+
 
 # API endpoints — override via env vars for different Gitea/Vikunja instances
-GITEA_API_URL = os.getenv("DEVX_GITEA_API_URL", "https://git.oblachno.oblachno.fyi/api/v1")
-VIKUNJA_API_URL = os.getenv("DEVX_VIKUNJA_API_URL", "https://work.oblachno.oblachno.fyi/api/v1")
+GITEA_API_URL = _get("gitea_api_url", "DEVX_GITEA_API_URL", "https://git.oblachno.oblachno.fyi/api/v1")
+VIKUNJA_API_URL = _get("vikunja_api_url", "DEVX_VIKUNJA_API_URL", "https://work.oblachno.oblachno.fyi/api/v1")
 
-# Organization defaults
-REPO_OWNER = os.getenv("DEVX_REPO_OWNER", "oblachno-oss")
+# Organization defaults — each project MUST set DEVX_REPO_OWNER explicitly.
+# No default: prevents silent 404s when the wrong owner is used.
+REPO_OWNER = _get("repo_owner", "DEVX_REPO_OWNER", "")
+REPO_NAME = _get("repo_name", "DEVX_REPO_NAME", "")
 
 # Task prefix for Vikunja task IDs — each project sets its own (GRM, DEVX, INFRA, etc.)
-TASK_PREFIX = os.getenv("DEVX_TASK_PREFIX", "DEVX")
+TASK_PREFIX = _get("task_prefix", "DEVX_TASK_PREFIX", "DEVX")
 TASK_ID_RE = re.compile(rf"{TASK_PREFIX}-\d+")
 
 # Vikunja project ID — each project uses a different Vikunja project
-VIKUNJA_PROJECT_ID = int(os.getenv("DEVX_VIKUNJA_PROJECT_ID", "6"))
+VIKUNJA_PROJECT_ID = _get_int("vikunja_project_id", "DEVX_VIKUNJA_PROJECT_ID", 6)
 
 # HTTP client defaults
 DEFAULT_TIMEOUT = 30

src/devx/gitea_cli.py

@@ -40,15 +40,67 @@ Usage::
 from __future__ import annotations
 
 import json
+import os
 import shutil
 import subprocess  # nosec B404
 from typing import Any
 
+import click
+
+from devx.config import GITEA_API_URL
+from devx.i18n import _
+
 
 class TeaCLIError(Exception):
     """Raised when a tea CLI command fails."""
 
 
+def configure_tea_login(login_name: str = "devx") -> None:
+    """Configure tea CLI login from CI_GITEA_TOKEN and DEVX_GITEA_API_URL.
+
+    Idempotent: if a login with the same name already exists, it is not re-added.
+    Skips silently if tea is not installed or CI_GITEA_TOKEN is not set.
+
+    Used by CI scripts (publish, notify_failure) that need tea login but
+    run in containerized environments where ``make setup`` was not called.
+    """
+    tea_bin = shutil.which("tea")
+    if tea_bin is None:
+        click.echo(_("tea not installed — skipping login configuration."))
+        return
+
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    if not token:
+        click.echo(_("CI_GITEA_TOKEN not set — skipping login configuration."))
+        return
+
+    gitea_url = GITEA_API_URL.replace("/api/v1", "")
+
+    result = subprocess.run(  # nosec B603
+        [tea_bin, "login", "list", "--output", "simple"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode == 0 and login_name in result.stdout:
+        click.echo(_("tea login '{name}' already configured.", name=login_name))
+        return
+
+    click.echo(_("Configuring tea login '{name}' for {url}...", name=login_name, url=gitea_url))
+    subprocess.run(  # nosec B603
+        [tea_bin, "login", "add", "--name", login_name, "--url", gitea_url, "--token", token],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    subprocess.run(  # nosec B603
+        [tea_bin, "login", "default", login_name],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
 class TeaCLI:
     """Wrapper around the ``tea`` Gitea CLI tool.
 
@@ -82,12 +134,15 @@ class TeaCLI:
         cmd = [self._tea, *args]
         if json_output:
             cmd.extend(["--output", "json"])
-        result = subprocess.run(  # nosec B603
-            cmd,
-            capture_output=True,
-            text=True,
-            check=False,
-        )
+        try:
+            result = subprocess.run(  # nosec B603
+                cmd,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except FileNotFoundError as e:
+            raise TeaCLIError(f"tea binary not found ('{self._tea}'). Install tea or add it to PATH.") from e
         if result.returncode != 0:
             raise TeaCLIError(
                 f"tea command failed (rc={result.returncode}): {' '.join(args)}\nstderr: {result.stderr.strip()}"

src/devx/i18n.py

@@ -1,7 +1,7 @@
 """Simple i18n for devx scripts and tools.
 
 Set DEVX_LANG environment variable to override the default English.
-Supported: en, bg, de, ru, zh.
+Supported: en, bg, de, ru, zh, pl.
 
 Projects can extend translations by setting DEVX_TRANSLATIONS_PATH to a
 JSON file with additional keys. Keys from the project's file are merged
@@ -45,7 +45,7 @@ def _(key: str, **kwargs: object) -> str:
     If unset, English is always returned regardless of system locale.
     """
     lang = os.getenv("DEVX_LANG", "en")
-    if lang not in ("en", "bg", "de", "ru", "zh"):
+    if lang not in ("en", "bg", "de", "ru", "zh", "pl"):
         lang = "en"
     template = TRANSLATIONS.get(key, {}).get(lang, key)
     return template.format(**kwargs)

src/devx/make/devx.mak

@@ -0,0 +1,426 @@
+# devx.mak — Shared Makefile fragment for devx-integrated projects.
+#
+# This fragment provides common targets for:
+# - Vikunja task management and PR creation
+# - Workflow validation (actionlint, act_runner)
+# - Linting (ruff, pyright, bandit, pip-audit)
+# - CI failure notification
+# - Environment setup (venv, .env, hooks)
+# - Test execution and quality checks
+#
+# Project config (task prefix, Vikunja project ID, repo owner, repo name)
+# is read from [tool.devx] in pyproject.toml by devx.config — no
+# Makefile variables needed.
+#
+# Usage in your Makefile:
+#
+#   # Set DEVX_PYTHON to your venv's Python
+#   DEVX_PYTHON := $(BIN)/python
+#
+#   # Include the devx fragment (silent if devx not installed yet)
+#   DEVX_MAK := $(shell $(DEVX_PYTHON) -c \
+#     "from pathlib import Path; import devx; print(Path(devx.__file__).parent / 'make' / 'devx.mak')" \
+#     2>/dev/null)
+#   -include $(DEVX_MAK)
+#
+# If devx is not installed, the -include silently skips and the targets
+# are simply unavailable (run 'make setup' first).
+#
+# Variables (set BEFORE including this fragment):
+#   DEVX_PYTHON          — Python executable (default: python3)
+#   DEVX_PR_BASE         — PR base branch (default: master)
+#   DEVX_VENV            — venv directory name (default: .venv)
+#   DEVX_BIN             — venv bin directory (default: $(DEVX_VENV)/bin)
+#   DEVX_LINT_PATHS      — paths for ruff/bandit (default: src/ tests/)
+#   DEVX_TYPECHECK_PATHS — paths for pyright (default: empty — uses pyright config)
+#   DEVX_COV_PKG         — coverage package name (default: src/devx)
+#   DEVX_TEST_PATHS      — pytest paths (default: tests/)
+#   DEVX_GITEA_PYPI_HOST — Gitea PyPI host (default: git.oblachno.oblachno.fyi)
+#   DEVX_GITEA_PYPI_ORG  — Gitea PyPI org (default: oblachno-oss)
+#   DEVX_ACTIONLINT_CFG  — actionlint config file (default: .gitea/actionlint.yaml)
+#   DEVX_WORKFLOW_DIR    — workflow directory (default: .gitea/workflows)
+
+DEVX_PYTHON ?= python3
+DEVX_PR_BASE ?= master
+DEVX_VENV ?= .venv
+DEVX_BIN ?= $(DEVX_VENV)/bin
+DEVX_LINT_PATHS ?= src/ tests/
+DEVX_COV_PKG ?= src/devx
+DEVX_TEST_PATHS ?= tests/
+DEVX_GITEA_PYPI_HOST ?= git.oblachno.oblachno.fyi
+DEVX_GITEA_PYPI_ORG ?= oblachno-oss
+DEVX_ACTIONLINT_CFG ?= .gitea/actionlint.yaml
+DEVX_WORKFLOW_DIR ?= .gitea/workflows
+DEVX_DOCKERFILE_PATHS ?= docker
+
+# PIP_INSTALL — helper to run pip with Gitea private PyPI registry configured.
+# Usage: $(DEVX_PIP_INSTALL) install -e '.[ci,lint]'
+# CI_GITEA_USERNAME can be set in .env, as an env var, or as a Make variable.
+# Projects can alias: PIP_INSTALL = $(DEVX_PIP_INSTALL)
+DEVX_PIP_INSTALL := if [ -z "$$CI_GITEA_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
+	CI_GITEA_TOKEN="$$CI_GITEA_TOKEN"; \
+	_PYPI_USER="$${CI_GITEA_USERNAME:-emil}"; \
+	if [ -n "$$CI_GITEA_TOKEN" ] && [ -n "$$_PYPI_USER" ]; then export PIP_EXTRA_INDEX_URL="https://$$_PYPI_USER:$$CI_GITEA_TOKEN@$(DEVX_GITEA_PYPI_HOST)/api/packages/$(DEVX_GITEA_PYPI_ORG)/pypi/simple/"; fi; \
+	$(DEVX_BIN)/pip
+
+# ── Virtual environment management ────────────────────────────────────────────
+#
+# These targets provide a single, consistent venv setup across all
+# devx-integrated projects (infra, grm, devx). Each project includes
+# devx.mak and aliases its local targets to these.
+#
+# The venv is a standard .venv directory (no pyenv virtualenv dependency).
+# pyenv can still be used to install Python 3.12+ but the venv itself
+# is created with `python3 -m venv .venv`.
+#
+# Projects should set these variables BEFORE including devx.mak:
+#   DEVX_VENV   — venv directory (default: .venv)
+#   DEVX_BIN    — venv bin directory (default: $(DEVX_VENV)/bin)
+#   DEVX_PYTHON — Python executable (default: python3; should be $(DEVX_BIN)/python after setup)
+#
+# Common aliases in project Makefiles:
+#   PIP_INSTALL = $(DEVX_PIP_INSTALL)
+#   venv: devx-venv
+#   activate-scripts: devx-activate-scripts
+#   .env: devx-env
+
+# Create .venv with Python version check (3.12+ required)
+$(DEVX_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')"
+	python3 -m venv $(DEVX_VENV)
+	$(DEVX_BIN)/pip install --upgrade pip setuptools wheel
+
+# Alias: devx-venv creates the venv (delegates to the activate rule)
+devx-venv: $(DEVX_VENV)/bin/activate
+
+# Ensure a venv exists — in CI (no pyenv), creates .venv if missing.
+# Locally, uses the existing .venv (created by `make setup` or `make devx-venv`).
+devx-ensure-venv:
+	@if [ ! -f $(DEVX_BIN)/python ]; then \
+		echo "[ensure-venv] Creating $(DEVX_VENV) (no venv found)..."; \
+		python3 -m venv $(DEVX_VENV); \
+		$(DEVX_BIN)/pip install --upgrade pip setuptools wheel; \
+	fi
+
+.PHONY: devx-create-task devx-create-pr devx-push devx-push-with-pr devx-check-config
+.PHONY: devx-pr-status devx-pr-logs devx-pr-label devx-pr-review devx-rebase devx-pr-rebase
+.PHONY: devx-configure-gitea-pypi devx-install-tools devx-install-checkmake devx-checkmake
+.PHONY: devx-workflow-lint devx-workflow-dryrun devx-workflow-dryrun-safe devx-workflow-check
+.PHONY: devx-notify-failure devx-install-hooks devx-activate-scripts devx-venv devx-ensure-venv
+.PHONY: devx-lint-ruff devx-lint-format devx-typecheck devx-lint-bandit devx-lint-deps devx-lint
+.PHONY: devx-clean devx-pre-push
+.PHONY: devx-check-mutable-globals devx-check-dep-docs devx-check-test-coverage devx-check-docs devx-check-test-speed
+.PHONY: devx-check-api-identity-checks devx-setup-ssh-key
+.PHONY: devx-test-unit devx-pytest-cov
+.PHONY: devx-setup-image devx-lint-dockerfiles
+
+# ── Vikunja task and PR management ────────────────────────────────────────────
+
+# Create a Vikunja task (project ID read from [tool.devx] in pyproject.toml)
+devx-create-task:
+	@$(DEVX_PYTHON) -m devx.tools.create_task
+
+# Create a PR with title auto-derived from the Vikunja task
+# (owner/repo read from [tool.devx] in pyproject.toml)
+devx-create-pr:
+	@$(DEVX_PYTHON) -m devx.tools.create_pr --base $(DEVX_PR_BASE)
+
+# Push current branch to origin
+devx-push:
+	@git push -u origin HEAD
+
+# Validate devx configuration in pyproject.toml
+devx-check-config:
+	@$(DEVX_PYTHON) -m devx.tools.check_config
+
+# Push and create PR in one step
+devx-push-with-pr: devx-push devx-create-pr
+
+# Check CI status for a PR (auto-detects current branch's PR)
+# Usage: make devx-pr-status
+#        make devx-pr-status PR=42
+#        make devx-pr-status PR=42 WAIT=1 TIMEOUT=600
+devx-pr-status:
+	@$(DEVX_PYTHON) -m devx.tools.pr_status \
+		$(if $(PR),--pr $(PR)) \
+		$(if $(WAIT),--wait) \
+		$(if $(TIMEOUT),--timeout $(TIMEOUT))
+
+# Fetch logs for failed CI jobs on a PR
+# Usage: make devx-pr-logs
+#        make devx-pr-logs PR=42
+#        make devx-pr-logs PR=42 JOB=quality TAIL=50
+devx-pr-logs:
+	@$(DEVX_PYTHON) -m devx.tools.pr_logs \
+		$(if $(PR),--pr $(PR)) \
+		$(if $(JOB),--job $(JOB)) \
+		$(if $(TAIL),--tail $(TAIL))
+
+# Add a label to a PR (default: ready-to-merge)
+# Usage: make devx-pr-label
+#        make devx-pr-label PR=42
+#        make devx-pr-label PR=42 LABEL=ready-to-merge
+devx-pr-label:
+	@$(DEVX_PYTHON) -m devx.tools.pr_label \
+		$(if $(PR),--pr $(PR)) \
+		--label $(or $(LABEL),ready-to-merge)
+
+# Usage: make devx-pr-review PR=42 EVENT=APPROVE BODY="..." CHECKLIST=1,2,3,4,5,6,7,8,9,10,11,12,13
+#        make devx-pr-review PR=42 EVENT=REQUEST_CHANGES BODY="..."
+#        make devx-pr-review PR=42  (auto review)
+devx-pr-review:
+	@$(DEVX_PYTHON) -m devx.ci.pr_review \
+		$(PR) $(DEVX_REPO_OWNER)/$(DEVX_REPO_NAME) \
+		$(if $(EVENT),--event $(EVENT)) \
+		$(if $(BODY),--body "$(BODY)") \
+		$(if $(CHECKLIST),--checklist-confirmed --checklist-categories $(CHECKLIST))
+
+# Rebase current branch onto origin/master and force-push
+# Usage: make devx-rebase
+#        make devx-rebase NO_PUSH=1
+devx-rebase:
+	@$(DEVX_PYTHON) -m devx.tools.rebase \
+		$(if $(NO_PUSH),--no-push)
+
+# Rebase a PR's head branch via Gitea API (server-side, no local git needed)
+# Usage: make devx-pr-rebase
+#        make devx-pr-rebase PR=42
+devx-pr-rebase:
+	@$(DEVX_PYTHON) -m devx.tools.pr_rebase \
+		$(if $(PR),--pr $(PR))
+
+# ── Environment setup ─────────────────────────────────────────────────────────
+
+# Configure Gitea private PyPI registry so pip can find devx and other
+# private packages. In CI, CI_GITEA_TOKEN is set as a secret. Locally, it's in .env.
+devx-configure-gitea-pypi:
+	@if [ -z "$$CI_GITEA_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
+	CI_GITEA_TOKEN="$$CI_GITEA_TOKEN"; \
+	if [ -z "$$CI_GITEA_TOKEN" ]; then echo "[configure-gitea-pypi] CI_GITEA_TOKEN not set — skipping (devx must be on public PyPI)"; exit 0; fi; \
+	echo "[configure-gitea-pypi] Gitea PyPI registry configured (CI_GITEA_TOKEN present)."
+
+# Create .env from .env.example if it doesn't exist
+devx-env:
+	@if [ ! -f .env ]; then \
+		cp .env.example .env; \
+		echo "Created .env from .env.example — please edit it with your credentials."; \
+	fi
+
+# Create activate scripts for shell/fish/zsh
+devx-activate-scripts:
+	@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)
+
+# Set git hooks path to hooks/
+devx-install-hooks:
+	@git config core.hooksPath hooks
+	@chmod +x hooks/pre-commit hooks/pre-push 2>/dev/null || true
+	@echo "core.hooksPath set to hooks/ — tracked hooks are now live."
+
+# ── Tool installation ─────────────────────────────────────────────────────────
+
+# Install CI/CD tools (actionlint, git-cliff, act_runner, tea) to ~/.local/bin
+devx-install-tools:
+	@$(DEVX_PYTHON) -m devx.tools.install_tools
+
+# Install checkmake (Makefile linter)
+devx-install-checkmake:
+	@$(DEVX_PYTHON) -m devx.tools.install_checkmake
+
+# Lint Makefiles with checkmake
+devx-checkmake:
+	@CHECKMAKE_EXE="$$(command -v checkmake 2>/dev/null || echo $(HOME)/.local/bin/checkmake)"; \
+	if ! command -v "$$CHECKMAKE_EXE" >/dev/null 2>&1 && ! [ -x "$$CHECKMAKE_EXE" ]; then \
+		echo "[checkmake] checkmake not found. Run: make devx-install-checkmake"; exit 1; \
+	fi; \
+	"$$CHECKMAKE_EXE" $(CURDIR)/Makefile
+
+# ── Workflow validation ───────────────────────────────────────────────────────
+
+# Static lint of Gitea Actions workflow YAML files
+devx-workflow-lint:
+	@command -v actionlint >/dev/null 2>&1 || { \
+		echo "actionlint not found. Install: bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)"; \
+		exit 1; \
+	}
+	actionlint -config-file $(DEVX_ACTIONLINT_CFG) $(DEVX_WORKFLOW_DIR)/*.yml
+
+# Dry-run all workflows (requires act_runner)
+devx-workflow-dryrun:
+	@command -v act_runner >/dev/null 2>&1 || { echo "act_runner not found. Install: https://gitea.com/gitea/act_runner/releases"; exit 1; }
+	@echo "Dry-running all workflows (no Docker containers started)..."
+	act_runner exec --dryrun -W $(DEVX_WORKFLOW_DIR)/ 2>&1 | grep -E 'DRYRUN|ERROR|FAIL|Job'
+
+# Best-effort dry-run (skips if act_runner is not installed)
+devx-workflow-dryrun-safe:
+	@command -v act_runner >/dev/null 2>&1 && { echo "Dry-running workflows..."; act_runner exec --dryrun -W $(DEVX_WORKFLOW_DIR)/ 2>&1 | grep -E 'DRYRUN|ERROR|FAIL|Job'; } || echo "act_runner not found — skipping workflow dry-run (static lint still passed)"
+
+# Static lint + dry-run
+devx-workflow-check: devx-workflow-lint devx-workflow-dryrun
+	@echo "Workflow checks passed (static lint + dry-run)."
+
+# ── CI failure notification ───────────────────────────────────────────────────
+
+# Notify on CI failure — creates a Gitea issue via devx.ci.notify_failure.
+# Usage: make devx-notify-failure WORKFLOW=post-merge/release
+# Requires: CI_GITEA_TOKEN, GITHUB_REPOSITORY, GITHUB_RUN_ID, GITHUB_SHA
+devx-notify-failure:
+	@. $(DEVX_VENV)/bin/activate 2>/dev/null || true; \
+	export PATH="$(HOME)/.local/bin:$$PATH"; \
+	$(DEVX_PYTHON) -m devx.tools.install_tools --tool tea 2>/dev/null || true; \
+	$(DEVX_PYTHON) -m devx.ci.notify_failure --auto-login \
+		--repo "$${GITHUB_REPOSITORY}" \
+		--run-id "$${GITHUB_RUN_ID}" \
+		--workflow "$(WORKFLOW)" \
+		--commit "$${GITHUB_SHA}"
+
+# ── Linting ───────────────────────────────────────────────────────────────────
+
+devx-lint-ruff:
+	@$(DEVX_BIN)/ruff check $(DEVX_LINT_PATHS)
+
+devx-lint-format:
+	@$(DEVX_BIN)/ruff format --check $(DEVX_LINT_PATHS)
+
+devx-typecheck:
+	@$(DEVX_BIN)/pyright
+
+devx-lint-bandit:
+	@$(DEVX_BIN)/bandit -r src/
+
+devx-lint-deps:
+	@echo "Checking dependencies for known vulnerabilities..."
+	@$(DEVX_BIN)/python -m ensurepip 2>/dev/null || true
+	@PIPAPI_PYTHON_LOCATION=$$(pwd)/$(DEVX_VENV)/bin/python \
+		$(DEVX_BIN)/pip-audit --desc --skip-editable 2>&1 || true
+
+devx-lint: devx-lint-ruff devx-lint-format devx-typecheck devx-lint-bandit
+	@echo "[devx-lint] Linting checks passed."
+
+# ── Testing ───────────────────────────────────────────────────────────────────
+
+devx-test-unit:
+	@$(DEVX_BIN)/pytest $(DEVX_TEST_PATHS) -q --no-cov
+
+devx-pytest-cov:
+	@$(DEVX_BIN)/pytest $(DEVX_TEST_PATHS) -v --cov=$(DEVX_COV_PKG) --cov-report=term-missing --cov-fail-under=100
+
+# ── Quality checks ────────────────────────────────────────────────────────────
+
+# Scan for module-level mutable globals that cause test isolation bugs
+devx-check-mutable-globals:
+	@$(DEVX_PYTHON) -m devx.tools.check_mutable_globals
+
+# Validate that every dependency in pyproject.toml has a documented purpose
+devx-check-dep-docs:
+	@$(DEVX_PYTHON) -m devx.tools.check_pyproject_deps
+
+# Check that changed files have corresponding tests
+devx-check-test-coverage:
+	@$(DEVX_PYTHON) -m devx.tools.check_test_coverage
+
+# Validate agent and user docs for stale file references
+devx-check-docs:
+	@$(DEVX_PYTHON) -m devx.tools.check_agent_docs
+
+# Verify test suite timing
+devx-check-test-speed:
+	@$(DEVX_PYTHON) -m devx.tools.check_test_speed
+
+# Scan integration tests for unsafe is True/is False identity checks
+devx-check-api-identity-checks:
+	@$(DEVX_PYTHON) -m devx.tools.check_api_identity_checks
+
+# Set up SSH private key from SSH_PRIVATE_KEY env var
+devx-setup-ssh-key:
+	@$(DEVX_PYTHON) -m devx.tools.setup_ssh_key
+
+# ── Pre-push validation ───────────────────────────────────────────────────────
+
+# Run lint + tests before push (projects can override with project-specific targets)
+devx-pre-push: devx-lint devx-pytest-cov
+	@echo "[devx-pre-push] All checks passed. Proceeding with push."
+
+# ── Cleanup ───────────────────────────────────────────────────────────────────
+
+devx-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/ .molecule/ 2>/dev/null || true
+
+# ── Dockerfile linting ────────────────────────────────────────────────────────
+#
+# Lint Dockerfiles with hadolint. Fails fast if hadolint is not installed
+# (no silent skip). Set DEVX_DOCKERFILE_PATHS to the directory containing
+# your Dockerfiles (default: docker).
+#
+# Usage:
+#   make devx-lint-dockerfiles                          (lints docker/ directory)
+#   make devx-lint-dockerfiles DEVX_DOCKERFILE_PATHS=ansible  (lints ansible/)
+
+devx-lint-dockerfiles:
+	@echo "[devx-lint-dockerfiles] Linting Dockerfiles with hadolint..."
+	@if ! command -v hadolint >/dev/null 2>&1; then \
+		echo "[devx-lint-dockerfiles] ERROR: hadolint not found. Install from https://github.com/hadolint/hadolint/releases" >&2; \
+		exit 1; \
+	fi
+	@find $(DEVX_DOCKERFILE_PATHS) -name 'Dockerfile*' -exec hadolint {} +
+	@echo "[devx-lint-dockerfiles] All Dockerfiles passed."
+
+# ── Pre-built image setup ─────────────────────────────────────────────────────
+#
+# When running inside a pre-built Docker runner image (ci-base, ci-quality,
+# ci-full), all deps are already installed in /opt/venv. This target links
+# the venv and installs the project itself (with optional extras).
+#
+# Usage:
+#   make devx-setup-image              (runtime deps only)
+#   make devx-setup-image EXTRAS=lint  (runtime + lint deps)
+#   make devx-setup-image EXTRAS=ci,lint (runtime + ci + lint deps)
+#
+# Falls back to setup-ci if /opt/venv is not present (local dev).
+# Note: the fallback target name is project-specific (setup-ci, not
+# devx-setup-ci) — each project defines its own setup-ci target.
+
+devx-setup-image:
+	@/opt/venv/bin/python -m devx.tools.setup_image --venv $(DEVX_VENV) --extras "$(EXTRAS)" \
+		--gitea-host $(DEVX_GITEA_PYPI_HOST) --gitea-org $(DEVX_GITEA_PYPI_ORG)
+
+# ── Docker image build / push / cleanup ───────────────────────────────────────
+#
+# Variables:
+#   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)
+
+DEVX_GITEA_REGISTRY ?= git.oblachno.oblachno.fyi
+DEVX_IMAGE_MANIFEST ?= docker/images.json
+DEVX_IMAGE_OWNER ?= oblachno-oss
+
+# Build all images from manifest (no push)
+devx-build-images:
+	@$(DEVX_PYTHON) -m devx.tools.build_image --manifest $(DEVX_IMAGE_MANIFEST) --pull
+
+# Build and push all images to the Gitea registry
+devx-push-images:
+	@$(DEVX_PYTHON) -m devx.tools.build_image \
+		--manifest $(DEVX_IMAGE_MANIFEST) \
+		--registry $(DEVX_GITEA_REGISTRY) \
+		--push --pull
+
+# Dry-run: show what would be built/pushed
+devx-build-images-dry-run:
+	@$(DEVX_PYTHON) -m devx.tools.build_image \
+		--manifest $(DEVX_IMAGE_MANIFEST) \
+		--registry $(DEVX_GITEA_REGISTRY) \
+		--push --dry-run
+
+# Clean up old image versions (keep last 2 + latest)
+devx-clean-images:
+	@$(DEVX_PYTHON) -m devx.tools.clean_images \
+		--owner $(DEVX_IMAGE_OWNER) \
+		--name oblachno-oss/runner-images/ci-base \
+		--name oblachno-oss/runner-images/ci-quality \
+		--name oblachno-oss/runner-images/ci-full \
+		--keep 2

src/devx/molecule/__init__.py

@@ -0,0 +1 @@
+"""Molecule testing helpers for Ansible projects."""

src/devx/molecule/discover_runners.py

@@ -29,7 +29,7 @@ import os
 import click
 import requests
 
-from devx.config import GITEA_API_URL
+from devx.config import GITEA_API_URL, REPO_NAME, REPO_OWNER
 
 DEFAULT_MAX_RUNNERS = 3
 
@@ -142,12 +142,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)
@@ -156,7 +156,7 @@ 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}")

src/devx/molecule/distribute_molecule.py

@@ -19,11 +19,13 @@ Usage:
 
 from __future__ import annotations
 
+import tomllib
 from dataclasses import dataclass
 from pathlib import Path
 
 import click
 
+from devx.ci._shared import lpt_distribute, write_github_env
 from devx.i18n import _
 from devx.molecule.platforms import PLATFORMS, load_platforms
 
@@ -132,12 +134,102 @@ def build_multi_role_pairs(
     return [MultiRoleTestPair(r, s, p) for r, s in role_scenarios for p in platforms]
 
 
+# --- Molecule weight configuration ---
+#
+# Weights are loaded from ``[tool.devx.molecule.weights]`` in
+# ``pyproject.toml``.  Each project (infra, grm, …) contributes its own
+# weights calibrated from actual CI execution times.
+#
+# Two key formats are supported:
+#   - ``"scenario" = weight`` — applies to any role with that scenario name
+#   - ``"role/scenario" = weight`` — role-specific (takes priority)
+#
+# Example pyproject.toml::
+#
+#   [tool.devx.molecule.weights]
+#   "nextcloud" = 15
+#   "app_container/customer-apps" = 11
+#   "restore/default" = 11
+#   "default" = 3
+#
+# If no configuration is found, a generic default weight is used for all
+# scenarios (producing a round-robin distribution).
+
+_DEFAULT_SCENARIO_WEIGHT = 3
+
+
+def _load_molecule_weights(pyproject_path: str = "pyproject.toml") -> tuple[dict[str, int], dict[tuple[str, str], int]]:
+    """Load molecule weights from ``[tool.devx.molecule.weights]`` in pyproject.toml.
+
+    Returns a tuple of ``(scenario_weights, role_scenario_weights)``:
+    - ``scenario_weights``: maps scenario name → weight (applies to any role)
+    - ``role_scenario_weights``: maps (role, scenario) → weight (role-specific)
+    """
+    path = Path(pyproject_path)
+    if not path.exists():
+        return {}, {}
+    try:
+        with open(path, "rb") as f:  # noqa: PTH123
+            data = tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError):
+        return {}, {}
+
+    weights_raw = data.get("tool", {}).get("devx", {}).get("molecule", {}).get("weights", {})
+    if not isinstance(weights_raw, dict):
+        return {}, {}
+
+    scenario_weights: dict[str, int] = {}
+    role_scenario_weights: dict[tuple[str, str], int] = {}
+
+    for key, value in weights_raw.items():
+        if not isinstance(value, int):
+            continue
+        if "/" in key:
+            role, scenario = key.split("/", 1)
+            role_scenario_weights[(role.lower(), scenario.lower())] = value
+        else:
+            scenario_weights[key.lower()] = value
+
+    return scenario_weights, role_scenario_weights
+
+
+# Load weights once at import time (like devx.config and classify_changes)
+_SCENARIO_WEIGHTS, _ROLE_SCENARIO_WEIGHTS = _load_molecule_weights()
+
+
+def _scenario_weight(scenario: str, role: str | None = None) -> int:
+    """Estimate a weight for a scenario based on its name and optionally its role.
+
+    Role-specific weights (``"role/scenario"``) take priority over
+    scenario-name-only weights (``"scenario"``).  Falls back to the
+    default weight if no configuration matches.
+    """
+    s = scenario.lower()
+    if role is not None:
+        r = role.lower()
+        key = (r, s)
+        if key in _ROLE_SCENARIO_WEIGHTS:
+            return _ROLE_SCENARIO_WEIGHTS[key]
+    for key, weight in _SCENARIO_WEIGHTS.items():
+        if key in s:
+            return weight
+    return _DEFAULT_SCENARIO_WEIGHT
+
+
+def _lpt_distribute[T](items: list[T], weights: list[int], max_runners: int) -> list[list[T]]:
+    """Distribute *items* across *max_runners* using LPT (delegates to shared utility)."""
+    return lpt_distribute(items, weights, max_runners)
+
+
 def distribute_multi_role(pairs: list[MultiRoleTestPair], max_runners: int) -> list[list[MultiRoleTestPair]]:
-    """Split *pairs* into *max_runners* balanced groups (round-robin)."""
-    groups: list[list[MultiRoleTestPair]] = [[] for _ in range(max_runners)]
-    for i, pair in enumerate(pairs):
-        groups[i % max_runners].append(pair)
-    return groups
+    """Split *pairs* into *max_runners* balanced groups using LPT scheduling.
+
+    Each pair is weighted by role+scenario heuristics (e.g. ``nextcloud`` is
+    heavier than ``simple-app``). Pairs are sorted by weight descending and
+    assigned to the runner with the least total weight.
+    """
+    weights = [_scenario_weight(p.scenario, p.role) for p in pairs]
+    return _lpt_distribute(pairs, weights, max_runners)
 
 
 def multi_role_pairs_for_runner(
@@ -153,11 +245,14 @@ def multi_role_pairs_for_runner(
 
 
 def distribute(pairs: list[TestPair], max_runners: int) -> list[list[TestPair]]:
-    """Split *pairs* into *max_runners* balanced groups (round-robin)."""
-    groups: list[list[TestPair]] = [[] for _ in range(max_runners)]
-    for i, pair in enumerate(pairs):
-        groups[i % max_runners].append(pair)
-    return groups
+    """Split *pairs* into *max_runners* balanced groups using LPT scheduling.
+
+    Each pair is weighted by scenario name heuristics (e.g. ``nextcloud`` is
+    heavier than ``binary``). Pairs are sorted by weight descending and
+    assigned to the runner with the least total weight.
+    """
+    weights = [_scenario_weight(p.scenario) for p in pairs]
+    return _lpt_distribute(pairs, weights, max_runners)
 
 
 def pairs_for_runner(pairs: list[TestPair], runner_index: int, max_runners: int) -> list[TestPair]:
@@ -175,14 +270,8 @@ def pairs_for_runner(pairs: list[TestPair], runner_index: int, max_runners: int)
 
 
 def _write_github_env(key: str, value: str) -> None:
-    """Append a key=value line to the $GITHUB_ENV file."""
-    import os
-
-    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") as f:  # noqa: PTH123
-        f.write(f"{key}={value}\n")
+    """Append a key=value line to the $GITHUB_ENV file (delegates to shared utility)."""
+    write_github_env(key, value)
 
 
 @click.command()

src/devx/molecule/molecule_ci_guard.py

@@ -13,21 +13,16 @@ 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.
 
-JUnit XML is generated when ``--junit-output`` is provided, recording each
-pair as a testcase with pass/fail status and elapsed time.
-
 Usage::
 
     # Single-role (grm-style)
     python3 -m devx.molecule.molecule_ci_guard pair1 pair2 ...
     # Multi-role (infra-style)
     python3 -m devx.molecule.molecule_ci_guard --roles-root ansible/roles pair1 pair2 ...
-    # With JUnit output
-    python3 -m devx.molecule.molecule_ci_guard --junit-output junit-results/runner-1.xml pair1 pair2 ...
 
 Environment variables:
     GITEA_URL           Base URL of the Gitea instance.
-    REPO_TOKEN          API token with repo access.
+    CI_GITEA_TOKEN      API token with repo access.
     RUN_ID              Workflow run ID (GITHUB_RUN_ID).
     JOB_NAME            Base job name (GITHUB_JOB), e.g. "molecule-tests".
     MATRIX_INDEX        Current matrix index (runner-index).
@@ -43,12 +38,12 @@ import subprocess  # nosec B404
 import sys
 import threading
 import time
-import xml.etree.ElementTree as ET  # nosec B405
 from pathlib import Path
 
 import click
 import requests
 
+from devx.config import REPO_NAME, REPO_OWNER
 from devx.i18n import _
 
 POLL_INTERVAL = 10
@@ -158,68 +153,33 @@ def resolve_role_dir(role: str, roles_root: Path | None, repo_root: Path) -> Pat
     return repo_root / "ansible" / "roles" / "gitea-runner"
 
 
-def write_junit_report(
-    output_path: str,
-    testcases: list[dict],
-    runner_index: int,
-) -> None:
-    """Write a JUnit XML report from collected test case results.
-
-    Each testcase dict has: role, scenario, time (float), passed (bool), error (str|None).
-    """
-    suite = ET.Element(
-        "testsuite",
-        name=f"molecule-runner-{runner_index}",
-        tests=str(len(testcases)),
-        failures=str(sum(1 for tc in testcases if not tc["passed"])),
-    )
-    for tc in testcases:
-        classname = tc["role"] if tc["role"] else "molecule"
-        elem = ET.SubElement(
-            suite,
-            "testcase",
-            classname=classname,
-            name=tc["scenario"],
-            time=f"{tc['time']:.1f}",
-        )
-        if not tc["passed"]:
-            fail = ET.SubElement(elem, "failure")
-            fail.text = tc.get("error") or "molecule test failed"
-    tree = ET.ElementTree(suite)
-    ET.indent(tree)
-    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-    tree.write(output_path, encoding="UTF-8", xml_declaration=True)
-
-
 @click.command()
 @click.argument("pairs", nargs=-1, required=True)
-@click.option(
-    "--junit-output",
-    default=None,
-    help="Path to write JUnit XML report (e.g. junit-results/runner-1.xml).",
-)
 @click.option(
     "--roles-root",
     type=click.Path(exists=True, file_okay=False, path_type=Path),
     default=None,
     help="Root directory for multi-role pairs (e.g. ansible/roles). Required when pairs use 5-part format.",
 )
-def cli(pairs: tuple[str, ...], junit_output: str | None, roles_root: Path | None) -> None:
+def cli(pairs: tuple[str, ...], roles_root: Path | None) -> None:
     """Run molecule pairs sequentially, stop if another CI runner fails."""
     gitea_url = os.environ.get("GITEA_URL", "")
-    token = os.environ.get("REPO_TOKEN", "")
+    token = os.environ.get("CI_GITEA_TOKEN", "")
     run_id = int(os.environ.get("RUN_ID", "0"))
     job_name = os.environ.get("JOB_NAME", "molecule-tests")
     current_index = int(os.environ.get("MATRIX_INDEX", "0"))
-    repository = os.environ.get("GITEA_REPOSITORY", "oblachno-oss/devx")
+    repository = os.environ.get("GITEA_REPOSITORY", "")
     owner, _sep, repo = repository.partition("/")
     if not owner or not repo:
-        owner, repo = "oblachno-oss", "devx"
+        owner, repo = REPO_OWNER, REPO_NAME
 
     if not all([gitea_url, token, run_id]):
-        click.echo(_("GITEA_URL/REPO_TOKEN/RUN_ID not set; running without cross-runner cancellation."))
+        click.echo(_("GITEA_URL/CI_GITEA_TOKEN/RUN_ID not set; running without cross-runner cancellation."))
 
-    repo_root = Path(__file__).resolve().parent.parent.parent.parent
+    # When devx is installed as a pip package, __file__ resolves to the
+    # site-packages directory, not the repo root. Use GITHUB_WORKSPACE
+    # (set by Gitea Actions) or cwd as the repo root.
+    repo_root = Path(os.environ.get("GITHUB_WORKSPACE", os.getcwd())).resolve()
 
     base_env = os.environ.copy()
     base_env.setdefault("DOCKER_HOST", f"unix:///run/user/{os.getuid()}/docker.sock")
@@ -246,8 +206,6 @@ def cli(pairs: tuple[str, ...], junit_output: str | None, roles_root: Path | Non
         )
         poller.start()
 
-    testcases: list[dict] = []
-
     try:
         for pair in pairs:
             if failed_event.is_set():
@@ -260,7 +218,6 @@ def cli(pairs: tuple[str, ...], junit_output: str | None, roles_root: Path | Non
             env = build_env_for_pair(pair, base_env)
             cwd = resolve_role_dir(role, roles_root, repo_root)
 
-            start = time.time()
             process = subprocess.Popen(  # nosec B603
                 cmd,
                 cwd=str(cwd),
@@ -279,18 +236,6 @@ def cli(pairs: tuple[str, ...], junit_output: str | None, roles_root: Path | Non
                             with contextlib.suppress(ProcessLookupError):
                                 os.killpg(os.getpgid(process.pid), signal.SIGKILL)
                             process.wait()
-                        elapsed = time.time() - start
-                        testcases.append(
-                            {
-                                "role": role,
-                                "scenario": scenario,
-                                "time": elapsed,
-                                "passed": False,
-                                "error": "Cancelled — another runner failed",
-                            }
-                        )
-                        if junit_output:
-                            write_junit_report(junit_output, testcases, current_index)
                         sys.exit(1)
                     time.sleep(1)
             except KeyboardInterrupt:
@@ -300,30 +245,25 @@ def cli(pairs: tuple[str, ...], junit_output: str | None, roles_root: Path | Non
                 sys.exit(1)
 
             rc = process.returncode
-            elapsed = time.time() - start
-            passed = rc == 0
-
-            testcases.append(
-                {
-                    "role": role,
-                    "scenario": scenario,
-                    "time": elapsed,
-                    "passed": passed,
-                    "error": f"Exit code: {rc}" if not passed else None,
-                }
-            )
 
             if rc != 0:
                 click.echo(_("FAILED: {pair} exited with code {code}", pair=pair, code=rc))
-                if junit_output:
-                    write_junit_report(junit_output, testcases, current_index)
                 sys.exit(rc)
 
             click.echo(_("PASSED: {pair}", pair=pair))
 
+            # Prune Docker data between scenarios to prevent disk exhaustion
+            # in Docker-in-Docker molecule containers (each scenario pulls
+            # hundreds of MB of images that accumulate across pairs).
+            with contextlib.suppress(subprocess.SubprocessError, OSError):
+                subprocess.run(  # nosec B603, B607
+                    ["docker", "system", "prune", "-af", "--volumes"],
+                    check=False,
+                    capture_output=True,
+                    timeout=60,
+                )
+
         click.echo(_("All molecule tests passed."))
-        if junit_output:
-            write_junit_report(junit_output, testcases, current_index)
     finally:
         stop_event.set()
 

src/devx/molecule/platforms.py

@@ -41,7 +41,7 @@ def load_platforms(platforms_file: str | Path | None = None) -> list[dict[str, s
     path = Path(platforms_file)
     if not path.is_file():
         return PLATFORMS
-    with path.open() as f:
+    with path.open(encoding="utf-8") as f:
         data = json.load(f)
     if not isinstance(data, list) or not data:
         return PLATFORMS

src/devx/molecule/start_docker.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Ensure Docker is available for molecule tests in CI.
+
+CI runners (e.g. ``gitea/runner-images:ubuntu-latest``) may have the host's
+Docker socket mounted. This module verifies Docker is accessible and
+sets ``DOCKER_HOST`` explicitly so molecule's Python docker library
+connects to the same socket as the Docker CLI.
+
+If the host socket is not available, it tries the rootless socket, then
+starts a local ``dockerd`` with the vfs storage driver (requires
+privileged container).
+
+Usage::
+
+    python3 -m devx.molecule.start_docker [--timeout 30]
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import subprocess  # nosec B404
+import sys
+import tempfile
+import time
+
+import click
+
+from devx.i18n import _
+
+DEFAULT_TIMEOUT = 30
+DOCKER_SOCK = "/var/run/docker.sock"
+# Rootless socket fallback (e.g. /run/user/994/docker.sock)
+ROOTLESS_SOCK = f"/run/user/{os.getuid()}/docker.sock"
+
+
+def is_docker_ready() -> bool:
+    """Check if Docker daemon is responding on the configured socket."""
+    docker_host = os.environ.get("DOCKER_HOST", f"unix://{DOCKER_SOCK}")
+    result = subprocess.run(  # nosec B603 B607
+        ["docker", "info"],
+        capture_output=True,
+        check=False,
+        env={**os.environ, "DOCKER_HOST": docker_host},
+    )
+    return result.returncode == 0
+
+
+def _diagnose_socket() -> None:
+    """Print diagnostic info about the Docker socket."""
+    click.echo(f"DOCKER_HOST = {os.environ.get('DOCKER_HOST', '(not set)')}")
+    click.echo(f"Socket path: {DOCKER_SOCK}")
+    click.echo(f"Socket exists: {os.path.exists(DOCKER_SOCK)}")
+    if os.path.exists(DOCKER_SOCK):
+        stat = os.stat(DOCKER_SOCK)
+        click.echo(f"Socket mode: {oct(stat.st_mode)}")
+        click.echo(f"Socket uid: {stat.st_uid}, gid: {stat.st_gid}")
+    # Check if it's a mount point
+    result = subprocess.run(  # nosec B603 B607
+        ["mount"],
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    docker_mounts = [line for line in result.stdout.splitlines() if "docker" in line.lower()]
+    if docker_mounts:
+        click.echo("Docker-related mounts:")
+        for line in docker_mounts:
+            click.echo(f"  {line}")
+    else:
+        click.echo("No Docker-related mounts found")
+    # Check docker context
+    result = subprocess.run(  # nosec B603 B607
+        ["docker", "context", "ls"],
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    click.echo(f"Docker contexts:\n{result.stdout}")
+    # Try docker info without DOCKER_HOST
+    result = subprocess.run(  # nosec B603 B607
+        ["docker", "info"],
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    click.echo(f"docker info (no DOCKER_HOST): rc={result.returncode}")
+    if result.returncode != 0:
+        click.echo(f"  stderr: {result.stderr[:500]}")
+    else:
+        # Print server version and storage driver
+        for line in result.stdout.splitlines():
+            if "Server Version" in line or "Storage Driver" in line or "Docker Root Dir" in line:
+                click.echo(f"  {line.strip()}")
+
+
+def start_docker_daemon(timeout: int = DEFAULT_TIMEOUT) -> bool:
+    """Ensure Docker is ready for molecule tests.
+
+    First tries the host socket. If that works, sets ``DOCKER_HOST`` and
+    returns immediately. If not, tries the rootless socket. If neither
+    works, starts a local ``dockerd`` with vfs storage driver (requires
+    privileged container).
+
+    Returns ``True`` if Docker is ready, ``False`` if it failed to
+    start within the timeout.
+    """
+    # Point Docker CLI and Python library to the socket explicitly
+    os.environ["DOCKER_HOST"] = f"unix://{DOCKER_SOCK}"
+
+    # Diagnose socket state
+    click.echo("--- Docker socket diagnostics ---")
+    _diagnose_socket()
+    click.echo("--- End diagnostics ---")
+
+    # Check if host Docker is already available
+    if is_docker_ready():
+        click.echo(_("Docker daemon already running"))
+        return True
+
+    # Try rootless socket (e.g. /run/user/994/docker.sock)
+    click.echo(f"Trying rootless socket: {ROOTLESS_SOCK}")
+    os.environ["DOCKER_HOST"] = f"unix://{ROOTLESS_SOCK}"
+    if os.path.exists(ROOTLESS_SOCK) and is_docker_ready():
+        click.echo(_("Docker daemon already running"))
+        return True
+
+    # Scan for any rootless sockets at other UIDs
+    for sock in sorted(glob.glob("/run/user/*/docker.sock")):
+        if sock == ROOTLESS_SOCK:
+            continue
+        click.echo(f"Trying alternative rootless socket: {sock}")
+        os.environ["DOCKER_HOST"] = f"unix://{sock}"
+        if is_docker_ready():
+            click.echo(_("Docker daemon already running"))
+            return True
+
+    click.echo(_("Host Docker not available, starting local dockerd..."))
+
+    # Reset DOCKER_HOST to host socket for local dockerd
+    os.environ["DOCKER_HOST"] = f"unix://{DOCKER_SOCK}"
+
+    # Start local dockerd (requires privileged container)
+    log_file = tempfile.NamedTemporaryFile(  # noqa: SIM115
+        mode="w", suffix="dockerd.log", delete=False
+    )
+    click.echo(f"dockerd log: {log_file.name}")
+    subprocess.Popen(  # nosec B603 B607
+        [
+            "dockerd",
+            "--storage-driver",
+            "vfs",
+            "-H",
+            f"unix://{DOCKER_SOCK}",
+        ],
+        stdout=log_file,
+        stderr=subprocess.STDOUT,
+        start_new_session=True,
+    )
+
+    for _i in range(timeout):
+        if is_docker_ready():
+            click.echo(_("Docker daemon started"))
+            return True
+        time.sleep(1)
+
+    # Print dockerd log on failure
+    click.echo(_("Docker daemon failed to start"))
+    click.echo("--- dockerd log ---")
+    try:
+        with open(log_file.name, encoding="utf-8") as f:
+            log_content = f.read()
+        click.echo(log_content[-3000:] if len(log_content) > 3000 else log_content)
+    except OSError as e:
+        click.echo(f"Could not read log: {e}")
+    click.echo("--- End dockerd log ---")
+
+    return False
+
+
+@click.command()
+@click.option(
+    "--timeout",
+    default=DEFAULT_TIMEOUT,
+    type=int,
+    help="Seconds to wait for Docker daemon to start (default: 30).",
+)
+def main(timeout: int) -> None:
+    """Start Docker daemon for CI molecule tests."""
+    if start_docker_daemon(timeout):
+        # Export DOCKER_HOST to GITHUB_ENV for subsequent CI steps
+        github_env = os.environ.get("GITHUB_ENV")
+        if github_env and os.environ.get("DOCKER_HOST"):
+            with open(github_env, "a", encoding="utf-8") as f:
+                f.write(f"DOCKER_HOST={os.environ['DOCKER_HOST']}\n")
+            click.echo(f"Exported DOCKER_HOST={os.environ['DOCKER_HOST']} to GITHUB_ENV")
+        sys.exit(0)
+    sys.exit(1)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/_shared.py

@@ -0,0 +1,75 @@
+"""Shared utilities for tools modules."""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess  # nosec B404
+
+import click
+
+
+def arch_string() -> str:
+    """Return the architecture string used by release assets.
+
+    Maps ``platform.machine()`` to the common release asset naming:
+    ``amd64`` for x86_64, ``arm64`` for aarch64.
+
+    Raises:
+        click.ClickException: If the architecture is not supported.
+    """
+    machine = platform.machine().lower()
+    if machine in {"x86_64", "amd64"}:
+        return "amd64"
+    if machine in {"aarch64", "arm64"}:
+        return "arm64"
+    raise click.ClickException(f"Unsupported architecture: {machine}")
+
+
+def detect_pr_number() -> int | None:
+    """Detect the PR number for the current git branch.
+
+    Returns the PR number if the current branch has an open PR, or None
+    if no PR is found. Does NOT raise — callers decide how to handle None.
+    Best-effort: returns None on any failure (no token, API down, etc.).
+    """
+    result = subprocess.run(  # nosec B603, B607
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+    branch = result.stdout.strip()
+    if branch == "HEAD":
+        return None
+
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    if not token:
+        return None
+
+    owner = os.environ.get("DEVX_REPO_OWNER", "")
+    repo = os.environ.get("DEVX_REPO_NAME", "")
+    if not owner or not repo:
+        github_repo = os.environ.get("GITHUB_REPOSITORY", "")
+        if "/" in github_repo:
+            owner, repo = github_repo.split("/", 1)
+
+    if not owner or not repo:
+        return None
+
+    # Lazy import to avoid circular dependency
+    from devx.api_clients import APIError, GiteaClient  # noqa: PLC0415
+    from devx.config import GITEA_API_URL  # noqa: PLC0415
+
+    client = GiteaClient(GITEA_API_URL, token, owner, repo)
+    try:
+        prs = client.list_prs(state="open")
+    except APIError:
+        # Best-effort: API down or auth failure → no PR detected
+        return None
+    for pr in prs:
+        if pr.get("head", {}).get("ref") == branch:
+            return int(pr["number"])
+    return None

src/devx/tools/build_image.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""Build and push Docker images to a Gitea container registry.
+
+Replaces raw ``docker build`` / ``docker push`` shell commands with a
+tested Python tool.  Supports:
+
+- Building from any Dockerfile with a configurable context directory
+- Tagging with multiple tags (e.g. ``latest`` + version)
+- Optional push to a Gitea registry (with login)
+- Dry-run mode (prints commands without executing)
+
+Usage::
+
+    # Build a single image
+    python3 -m devx.tools.build_image \\
+        --dockerfile docker/ci-base/Dockerfile \\
+        --tag ci-base:latest \\
+        --tag ci-base:0.19.3
+
+    # Build and push to registry
+    python3 -m devx.tools.build_image \\
+        --dockerfile docker/ci-base/Dockerfile \\
+        --tag ci-base:latest \\
+        --tag ci-base:0.19.3 \\
+        --registry git.oblachno.oblachno.fyi \\
+        --push
+
+    # Build multiple images (from a manifest file)
+    python3 -m devx.tools.build_image --manifest docker/images.json --push
+
+The manifest file is a JSON list of dicts, each with:
+    - ``name``: image name (e.g. ``ci-base``)
+    - ``dockerfile``: path to Dockerfile (relative to repo root)
+    - ``context``: build context directory (optional, defaults to repo root)
+    - ``tags``: list of tags (optional, defaults to ``["latest"]``)
+
+Registry authentication uses ``CI_GITEA_TOKEN`` and ``CI_GITEA_USERNAME``
+environment variables, matching the existing CI workflow patterns.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess  # nosec B404
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import click
+
+from devx.i18n import _
+
+
+@dataclass
+class ImageSpec:
+    """Specification for a single Docker image to build."""
+
+    name: str
+    dockerfile: str
+    context: str = "."
+    tags: list[str] = field(default_factory=lambda: ["latest"])
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> ImageSpec:
+        """Create an ImageSpec from a dict (e.g. from a JSON manifest)."""
+        name = str(data.get("name", ""))
+        if not name:
+            raise ValueError(_("Image manifest entry missing 'name'"))
+        dockerfile = str(data.get("dockerfile", ""))
+        if not dockerfile:
+            raise ValueError(_("Image manifest entry missing 'dockerfile'"))
+        context = str(data.get("context", "."))
+        tags_raw = data.get("tags", ["latest"])
+        if not isinstance(tags_raw, list):
+            raise ValueError(_("Image 'tags' must be a list"))
+        tags = [str(t) for t in tags_raw] if tags_raw else ["latest"]
+        return cls(name=name, dockerfile=dockerfile, context=context, tags=tags)
+
+
+def load_manifest(path: str | Path) -> list[ImageSpec]:
+    """Load a JSON manifest file describing images to build.
+
+    The file must contain a JSON list of dicts with at least ``name`` and
+    ``dockerfile`` keys.  ``context`` and ``tags`` are optional.
+
+    Returns a list of :class:`ImageSpec` instances.
+    """
+    p = Path(path)
+    if not p.is_file():
+        raise click.ClickException(_("Manifest file not found: {path}", path=p))
+    with p.open(encoding="utf-8") as f:  # noqa: PTH123
+        data = json.load(f)
+    if not isinstance(data, list):
+        raise click.ClickException(_("Manifest must be a JSON list"))
+    return [ImageSpec.from_dict(entry) for entry in data]
+
+
+def build_full_tag(registry: str | None, name: str, tag: str) -> str:
+    """Build a full image tag, optionally prefixed with a registry.
+
+    >>> build_full_tag(None, "ci-base", "latest")
+    'ci-base:latest'
+    >>> build_full_tag("git.example.com", "ci-base", "0.1.0")
+    'git.example.com/ci-base:0.1.0'
+    """
+    if registry:
+        return f"{registry}/{name}:{tag}"
+    return f"{name}:{tag}"
+
+
+def registry_login(
+    registry: str,
+    username: str,
+    token: str,
+    *,
+    dry_run: bool = False,
+) -> bool:
+    """Log in to a Docker registry.
+
+    Returns True on success, False on failure.
+    In dry-run mode, prints the command without executing.
+    """
+    cmd = ["docker", "login", registry, "-u", username, "--password-stdin"]
+    if dry_run:
+        click.echo(f"[dry-run] {' '.join(cmd)}")
+        return True
+    result = subprocess.run(  # nosec B603
+        cmd,
+        input=token,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        click.echo(
+            _("Registry login failed: {error}", error=result.stderr.strip()),
+            err=True,
+        )
+        return False
+    click.echo(f"Logged in to {registry}")
+    return True
+
+
+def build_image(
+    spec: ImageSpec,
+    registry: str | None = None,
+    *,
+    dry_run: bool = False,
+    pull: bool = False,
+) -> bool:
+    """Build a Docker image from a Dockerfile.
+
+    Tags the image with all specified tags, optionally prefixed with the
+    registry.  Returns True on success, False on failure.
+    """
+    if not Path(spec.dockerfile).is_file():
+        click.echo(
+            _("Dockerfile not found: {path}", path=spec.dockerfile),
+            err=True,
+        )
+        return False
+
+    full_tags = [build_full_tag(registry, spec.name, t) for t in spec.tags]
+    cmd = ["docker", "build"]
+    if pull:
+        cmd.append("--pull")
+    for ft in full_tags:
+        cmd.extend(["-t", ft])
+    cmd.extend(["-f", spec.dockerfile, spec.context])
+
+    if dry_run:
+        click.echo(f"[dry-run] {' '.join(cmd)}")
+        return True
+
+    click.echo(f"Building {spec.name} ({len(full_tags)} tag(s))...")
+    result = subprocess.run(  # nosec B603
+        cmd,
+        check=False,
+    )
+    if result.returncode != 0:
+        click.echo(_("Build failed for {name}", name=spec.name), err=True)
+        return False
+    click.echo(f"Built {spec.name}")
+    return True
+
+
+def push_image(
+    spec: ImageSpec,
+    registry: str,
+    *,
+    dry_run: bool = False,
+) -> bool:
+    """Push all tags of a Docker image to the registry.
+
+    Returns True if all pushes succeed, False if any fail.
+    """
+    full_tags = [build_full_tag(registry, spec.name, t) for t in spec.tags]
+    all_ok = True
+    for ft in full_tags:
+        cmd = ["docker", "push", ft]
+        if dry_run:
+            click.echo(f"[dry-run] {' '.join(cmd)}")
+            continue
+        click.echo(f"Pushing {ft}...")
+        result = subprocess.run(  # nosec B603
+            cmd,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            click.echo(
+                _("Push failed for {tag}: {error}", tag=ft, error=result.stderr.strip()),
+                err=True,
+            )
+            all_ok = False
+        else:
+            click.echo(f"Pushed {ft}")
+    return all_ok
+
+
+def _get_registry_creds() -> tuple[str, str]:
+    """Get registry credentials from environment variables."""
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    username = os.environ.get("CI_GITEA_USERNAME", "")
+    return username, token
+
+
+@click.command()
+@click.option(
+    "--dockerfile",
+    "dockerfile",
+    default=None,
+    help="Path to Dockerfile (for single-image build).",
+)
+@click.option(
+    "--context",
+    "context",
+    default=".",
+    help="Build context directory (for single-image build).",
+)
+@click.option(
+    "--name",
+    "name",
+    default=None,
+    help="Image name (for single-image build).",
+)
+@click.option(
+    "--tag",
+    "tags",
+    multiple=True,
+    help="Tag(s) for the image. Can be repeated. Defaults to 'latest'.",
+)
+@click.option(
+    "--manifest",
+    "manifest",
+    default=None,
+    help="Path to JSON manifest file listing images to build.",
+)
+@click.option(
+    "--registry",
+    "registry",
+    default=None,
+    help="Registry URL (e.g. git.example.com). If set with --push, images are tagged and pushed there.",
+)
+@click.option(
+    "--push",
+    is_flag=True,
+    default=False,
+    help="Push images to the registry after building.",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Print commands without executing.",
+)
+@click.option(
+    "--pull",
+    is_flag=True,
+    default=False,
+    help="Pass --pull to docker build (always fetch latest base image).",
+)
+def main(
+    dockerfile: str | None,
+    context: str,
+    name: str | None,
+    tags: tuple[str, ...],
+    manifest: str | None,
+    registry: str | None,
+    push: bool,
+    dry_run: bool,
+    pull: bool,
+) -> None:
+    """Build and optionally push Docker images to a Gitea registry."""
+    if manifest:
+        specs = load_manifest(manifest)
+    elif dockerfile and name:
+        tag_list = list(tags) if tags else ["latest"]
+        specs = [ImageSpec(name=name, dockerfile=dockerfile, context=context, tags=tag_list)]
+    else:
+        raise click.ClickException(_("Provide --manifest or both --dockerfile and --name"))
+
+    if push:
+        if not registry:
+            raise click.ClickException(_("--push requires --registry"))
+        username, token = _get_registry_creds()
+        if not token or not username:
+            raise click.ClickException(
+                _("Registry credentials required: set CI_GITEA_TOKEN and CI_GITEA_USERNAME env vars")
+            )
+        if not registry_login(registry, username, token, dry_run=dry_run):
+            raise click.ClickException(_("Registry login failed"))
+
+    failed: list[str] = []
+    for spec in specs:
+        if not build_image(spec, registry, dry_run=dry_run, pull=pull):
+            failed.append(spec.name)
+            continue
+        if push and not push_image(spec, registry, dry_run=dry_run):  # type: ignore[arg-type]
+            failed.append(spec.name)
+
+    if failed:
+        raise click.ClickException(_("Failed images: {names}", names=", ".join(failed)))
+    click.echo(f"\nDone. {len(specs)} image(s) processed.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()  # pragma: no cover

src/devx/tools/check_agent_docs.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""Validate agent documentation and user docs for stale file references.
+
+Scans documentation files (``.devin/``, ``docs/``, ``README.md``) for:
+- References to files that no longer exist
+- References to deleted files (configurable blocklist)
+- References to deprecated patterns (configurable regex patterns)
+
+Configuration (``[tool.devx.check_agent_docs]`` in pyproject.toml):
+
+``scan_dirs``          — directories to scan for docs (default: ``[".devin", "docs"]``)
+``scan_files``         — specific files to scan (default: ``["README.md", "README.rst"]``)
+``scan_extensions``    — file extensions to scan (default: ``[".md", ".yml", ".yaml"]``)
+``excluded_paths``     — paths to exclude from scanning (default: ``["docs/retrospectives"]``)
+``deleted_files``      — list of file paths that should never be referenced
+``deprecated_patterns`` — list of regex patterns for deprecated references
+``legitimate_indicators`` — substrings that indicate a legitimate reference to a deprecated pattern
+``repo_path_prefixes`` — path prefixes that indicate a repo-relative reference
+                    (default: ``["ansible/", "scripts/", "tofu/", ".devin/", "src/"]``)
+``min_path_ref_length`` — minimum length for a path reference to be checked (default: 5)
+
+Usage::
+
+    python3 -m devx.tools.check_agent_docs
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+from pathlib import Path
+
+import click
+
+from devx.config import _load_pyproject_devx
+from devx.i18n import _
+
+MIN_PATH_REF_LENGTH_DEFAULT = 5
+
+# Pattern that matches file path references in markdown or code
+FILE_REF_RE = re.compile(
+    r"(?:`|\")?"
+    r"([\w\-./]+(?:\.[a-zA-Z0-9]+))"
+    r"(?:`|\))?"
+)
+
+DEFAULT_SCAN_DIRS = [".devin", "docs"]
+DEFAULT_SCAN_FILES = ["README.md", "README.rst"]
+DEFAULT_SCAN_EXTENSIONS = [".md", ".yml", ".yaml"]
+DEFAULT_EXCLUDED_PATHS = ["docs/retrospectives"]
+DEFAULT_REPO_PATH_PREFIXES = ["ansible/", "scripts/", "tofu/", ".devin/", "src/"]
+
+
+def _load_config() -> dict[str, object]:
+    """Load check_agent_docs configuration from pyproject.toml."""
+    devx_cfg = _load_pyproject_devx()
+    cfg_raw = devx_cfg.get("check_agent_docs", {})
+    if not isinstance(cfg_raw, dict):
+        return {}
+    return cfg_raw  # type: ignore[return-value]
+
+
+def _should_skip(path: Path, excluded_paths: list[str], repo_root: Path) -> bool:
+    """Check if a path should be excluded from scanning."""
+    try:
+        rel = str(path.relative_to(repo_root))
+    except ValueError:
+        return False
+    return any(excluded in rel for excluded in excluded_paths)
+
+
+def _is_legitimate_ref(line: str, legitimate_indicators: list[str]) -> bool:
+    """Check if a line contains a legitimate reference to a deprecated pattern."""
+    line_lower = line.lower()
+    return any(legit.lower() in line_lower for legit in legitimate_indicators)
+
+
+def _collect_doc_files(
+    repo_root: Path,
+    scan_dirs: list[str],
+    scan_files: list[str],
+    scan_extensions: list[str],
+    excluded_paths: list[str],
+) -> list[Path]:
+    """Collect all documentation files to scan."""
+    files: list[Path] = []
+
+    for scan_dir_name in scan_dirs:
+        scan_dir = repo_root / scan_dir_name
+        if not scan_dir.exists():
+            continue
+        for ext in scan_extensions:
+            for path in scan_dir.glob(f"**/*{ext}"):
+                if not _should_skip(path, excluded_paths, repo_root):
+                    files.append(path)
+
+    for readme_name in scan_files:
+        path = repo_root / readme_name
+        if path.exists() and not _should_skip(path, excluded_paths, repo_root):
+            files.append(path)
+
+    # Deduplicate while preserving order
+    seen: set[Path] = set()
+    unique: list[Path] = []
+    for f in files:
+        if f not in seen:
+            seen.add(f)
+            unique.append(f)
+    return unique
+
+
+def _check_file(
+    path: Path,
+    repo_root: Path,
+    deleted_files: set[str],
+    deprecated_patterns: list[re.Pattern[str]],
+    legitimate_indicators: list[str],
+    repo_path_prefixes: list[str],
+    min_path_ref_length: int,
+    skip_ref_prefixes: list[str],
+) -> list[str]:
+    """Check a single file for stale references."""
+    issues: list[str] = []
+    rel_path = path.relative_to(repo_root)
+
+    try:
+        content = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return issues
+
+    for lineno, line in enumerate(content.splitlines(), start=1):
+        # Check for deleted file references
+        for deleted in deleted_files:
+            if deleted in line:
+                issues.append(f"{rel_path}:{lineno}: references deleted file '{deleted}'")
+
+        # Check for deprecated pattern references
+        for pattern in deprecated_patterns:
+            if pattern.search(line) and not _is_legitimate_ref(line, legitimate_indicators):
+                issues.append(f"{rel_path}:{lineno}: matches deprecated pattern '{pattern.pattern}'")
+
+        # Check for references to files that don't exist
+        for match in FILE_REF_RE.finditer(line):
+            ref = match.group(1)
+            # Skip URLs, bare words, and short strings
+            if "/" not in ref or len(ref) < min_path_ref_length:
+                continue
+            # Only check references that look like repo paths
+            if not any(ref.startswith(prefix) for prefix in repo_path_prefixes):
+                continue
+            # Skip references matching configured skip prefixes (e.g. aspirational test files)
+            if any(ref.startswith(prefix) for prefix in skip_ref_prefixes):
+                continue
+            candidate = repo_root / ref
+            if not candidate.exists():
+                issues.append(f"{rel_path}:{lineno}: references non-existent file '{ref}'")
+
+    return issues
+
+
+@click.command()
+def cli() -> None:
+    """Validate agent documentation and user docs for stale file references."""
+    repo_root = Path.cwd()
+    cfg = _load_config()
+
+    scan_dirs_raw = cfg.get("scan_dirs")
+    scan_dirs: list[str] = [str(d) for d in scan_dirs_raw] if isinstance(scan_dirs_raw, list) else DEFAULT_SCAN_DIRS
+    scan_files_raw = cfg.get("scan_files")
+    scan_files: list[str] = [str(d) for d in scan_files_raw] if isinstance(scan_files_raw, list) else DEFAULT_SCAN_FILES
+    scan_ext_raw = cfg.get("scan_extensions")
+    scan_extensions: list[str] = (
+        [str(d) for d in scan_ext_raw] if isinstance(scan_ext_raw, list) else DEFAULT_SCAN_EXTENSIONS
+    )
+    excluded_raw = cfg.get("excluded_paths")
+    excluded_paths: list[str] = (
+        [str(d) for d in excluded_raw] if isinstance(excluded_raw, list) else DEFAULT_EXCLUDED_PATHS
+    )
+    prefixes_raw = cfg.get("repo_path_prefixes")
+    repo_path_prefixes: list[str] = (
+        [str(d) for d in prefixes_raw] if isinstance(prefixes_raw, list) else DEFAULT_REPO_PATH_PREFIXES
+    )
+    min_len_raw = cfg.get("min_path_ref_length")
+    min_path_ref_length: int = int(min_len_raw) if isinstance(min_len_raw, int) else MIN_PATH_REF_LENGTH_DEFAULT
+
+    skip_prefixes_raw = cfg.get("skip_ref_prefixes", [])
+    skip_ref_prefixes: list[str] = [str(d) for d in skip_prefixes_raw] if isinstance(skip_prefixes_raw, list) else []
+
+    deleted_files: set[str] = set()
+    deleted_raw = cfg.get("deleted_files", [])
+    if isinstance(deleted_raw, list):
+        deleted_files = {str(d) for d in deleted_raw}
+
+    deprecated_patterns: list[re.Pattern[str]] = []
+    deprecated_raw = cfg.get("deprecated_patterns", [])
+    if isinstance(deprecated_raw, list):
+        for pattern_str in deprecated_raw:
+            if isinstance(pattern_str, str):
+                with contextlib.suppress(re.error):
+                    deprecated_patterns.append(re.compile(pattern_str))
+
+    legitimate_indicators: list[str] = []
+    legit_raw = cfg.get("legitimate_indicators", [])
+    if isinstance(legit_raw, list):
+        legitimate_indicators = [str(s) for s in legit_raw]
+
+    files = _collect_doc_files(repo_root, scan_dirs, scan_files, scan_extensions, excluded_paths)
+    all_issues: list[str] = []
+
+    for path in sorted(files):
+        issues = _check_file(
+            path,
+            repo_root,
+            deleted_files,
+            deprecated_patterns,
+            legitimate_indicators,
+            repo_path_prefixes,
+            min_path_ref_length,
+            skip_ref_prefixes,
+        )
+        all_issues.extend(issues)
+
+    if all_issues:
+        click.echo(f"[check_agent_docs] Found {len(all_issues)} issue(s):\n", err=True)
+        for issue in all_issues:
+            click.echo(issue, err=True)
+        click.echo(
+            f"\n[check_agent_docs] FAILED: {len(all_issues)} stale reference(s)",
+            err=True,
+        )
+        raise click.ClickException(_("Found {count} stale documentation reference(s)", count=len(all_issues)))
+
+    click.echo(_("[check_agent_docs] Passed: scanned {count} file(s), no stale references", count=len(files)))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/check_api_identity_checks.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Scan integration tests for unsafe ``is True``/``is False`` identity checks.
+
+Many APIs (e.g. Mattermost) return boolean values as strings (``"true"``,
+``"false"``) rather than native JSON booleans.  Using ``is True`` or
+``is not False`` on such responses silently fails because ``"true" is True``
+evaluates to ``False`` in Python.
+
+This tool scans ``tests/integration/test_*.py`` files for identity checks
+on API response values and reports them as errors.
+
+Configuration (``[tool.devx.check_api_identity_checks]`` in pyproject.toml):
+
+``scan_dirs``      — list of directories to scan (default: ``["tests/integration"]``)
+``skip_patterns``  — list of filename patterns to skip (default: ``["test_*_helpers.py"]``)
+``noqa_marker``    — comment to suppress individual lines (default: ``# noqa``)
+
+Usage::
+
+    python3 -m devx.tools.check_api_identity_checks
+    python3 -m devx.tools.check_api_identity_checks --scan-dir tests/integration
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import click
+
+from devx.config import _load_pyproject_devx
+from devx.i18n import _
+
+DEFAULT_SCAN_DIRS = ["tests/integration"]
+DEFAULT_SKIP_PATTERNS = ["test_*_helpers.py"]
+DEFAULT_NOQA_MARKER = "# noqa"
+
+# Matches: x is True, x is False, x is not True, x is not False
+_IDENTITY_CHECK_RE = re.compile(r"\bis\s+(not\s+)?(True|False)\b")
+
+
+def _load_config() -> tuple[list[str], list[str], str]:
+    """Load configuration from pyproject.toml [tool.devx.check_api_identity_checks]."""
+    devx_cfg = _load_pyproject_devx()
+    cfg_raw = devx_cfg.get("check_api_identity_checks", {})
+    if not isinstance(cfg_raw, dict):
+        return DEFAULT_SCAN_DIRS, DEFAULT_SKIP_PATTERNS, DEFAULT_NOQA_MARKER
+    cfg: dict[str, object] = cfg_raw  # type: ignore[assignment]
+
+    scan_dirs_raw = cfg.get("scan_dirs", DEFAULT_SCAN_DIRS)
+    scan_dirs: list[str] = [str(d) for d in scan_dirs_raw] if isinstance(scan_dirs_raw, list) else DEFAULT_SCAN_DIRS
+
+    skip_raw = cfg.get("skip_patterns", DEFAULT_SKIP_PATTERNS)
+    skip_patterns: list[str] = [str(p) for p in skip_raw] if isinstance(skip_raw, list) else DEFAULT_SKIP_PATTERNS
+
+    noqa_marker = str(cfg.get("noqa_marker", DEFAULT_NOQA_MARKER))
+
+    return scan_dirs, skip_patterns, noqa_marker
+
+
+def _matches_skip_pattern(path: Path, skip_patterns: list[str]) -> bool:
+    """Check if a file path matches any skip pattern."""
+    name = path.name
+    return any(Path(name).match(pattern) for pattern in skip_patterns)
+
+
+def find_identity_checks(
+    file_path: Path,
+    repo_root: Path,
+    noqa_marker: str,
+) -> list[str]:
+    """Return a list of issue strings for unsafe identity checks in *file_path*."""
+    issues: list[str] = []
+    try:
+        source = file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return issues
+
+    rel = str(file_path.relative_to(repo_root))
+    for lineno, line in enumerate(source.splitlines(), 1):
+        if noqa_marker in line:
+            continue
+        match = _IDENTITY_CHECK_RE.search(line)
+        if match:
+            issues.append(
+                f"{rel}:{lineno}: unsafe identity check '{match.group()}' "
+                f"— APIs may return string 'true'/'false'. "
+                f"Use string comparison or _is_truthy()/_is_falsy() helpers."
+            )
+
+    return issues
+
+
+@click.command()
+@click.option(
+    "--scan-dir",
+    multiple=True,
+    help=_("Directory to scan (default: tests/integration). Can be repeated."),
+)
+def cli(scan_dir: tuple[str, ...]) -> None:
+    """Scan integration tests for unsafe ``is True``/``is False`` identity checks."""
+    repo_root = Path.cwd()
+    config_scan_dirs, skip_patterns, noqa_marker = _load_config()
+
+    scan_dirs = list(scan_dir) if scan_dir else config_scan_dirs
+
+    all_issues: list[str] = []
+
+    for scan_dir_name in scan_dirs:
+        scan_path = repo_root / scan_dir_name
+        if not scan_path.exists():
+            continue
+        for py_file in scan_path.rglob("test_*.py"):
+            if _matches_skip_pattern(py_file, skip_patterns):
+                continue
+            all_issues.extend(find_identity_checks(py_file, repo_root, noqa_marker))
+
+    if all_issues:
+        click.echo(
+            _("Found {count} unsafe identity check(s) in integration tests.", count=len(all_issues)),
+            err=True,
+        )
+        for issue in all_issues:
+            click.echo(f"  {issue}", err=True)
+        raise click.ClickException(
+            _(
+                "Use string comparison or _is_truthy()/_is_falsy() helpers instead. "
+                "Add '{marker}' to suppress individual lines.",
+                marker=noqa_marker,
+            )
+        )
+
+    click.echo(_("[check-api-identity-checks] Passed: no unsafe identity checks found"))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/check_config.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Validate devx configuration consistency in pyproject.toml.
+
+Checks:
+1. [tool.devx] section exists with required keys (task_prefix, vikunja_project_id, repo_owner, repo_name)
+2. devx version is consistent across all extras that mention it
+
+Usage::
+
+    python3 -m devx.tools.check_config
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from pathlib import Path
+
+import click
+
+from devx.i18n import _
+
+
+@click.command()
+def cli() -> None:
+    """Validate devx configuration in pyproject.toml."""
+    path = Path("pyproject.toml")
+    if not path.exists():
+        raise click.ClickException(_("pyproject.toml not found in current directory."))
+
+    with open(path, "rb") as f:  # noqa: PTH123
+        data = tomllib.load(f)
+
+    errors: list[str] = []
+
+    # Check [tool.devx] section
+    devx_cfg = data.get("tool", {}).get("devx", {})
+    required_keys = {"task_prefix", "vikunja_project_id", "repo_owner", "repo_name"}
+    missing = required_keys - set(devx_cfg.keys())
+    if missing:
+        errors.append(
+            _("[tool.devx] missing required keys: {keys}", keys=", ".join(sorted(missing))),
+        )
+
+    # Check devx version consistency across extras
+    optional_deps = data.get("project", {}).get("optional-dependencies", {})
+    devx_versions: dict[str, str] = {}
+    for extra_name, deps in optional_deps.items():
+        for dep in deps:
+            # Match "devx>=X.Y.Z", "devx==X.Y.Z", "devx>X.Y.Z", etc.
+            m = re.search(r"\bdevx\s*(>=|==|>|<=|<|~=)\s*([\d.]+)", dep)
+            if m:
+                devx_versions[extra_name] = m.group(2)
+
+    if devx_versions:
+        unique_versions = set(devx_versions.values())
+        if len(unique_versions) > 1:
+            detail = ", ".join(f"{extra}={v}" for extra, v in sorted(devx_versions.items()))
+            errors.append(
+                _("devx version mismatch across extras: {detail}", detail=detail),
+            )
+
+    if errors:
+        for err in errors:
+            click.echo(f"ERROR: {err}", err=True)
+        raise click.ClickException(_("Configuration validation failed."))
+
+    click.echo(_("Configuration OK: [tool.devx] present, devx versions consistent."))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/check_deps.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Check that required development tools are present.
+
+Verifies the availability of core tools (tofu, docker, checkmake, Python
+3.12+ in the venv) and prints warnings or errors for missing ones.
+
+Usage::
+
+    python3 -m devx.tools.check_deps
+    python3 -m devx.tools.check_deps --venv .venv
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess  # nosec B404
+from pathlib import Path
+
+import click
+
+from devx.i18n import _
+
+REQUIRED_TOOLS = ["tofu", "docker"]
+OPTIONAL_TOOLS = ["checkmake"]
+PYTHON_MIN_VERSION = (3, 12)
+
+
+def _check_tool(name: str, *, optional: bool = False) -> bool:
+    """Check if a tool is on PATH. Returns True if found."""
+    found = shutil.which(name) is not None
+    if found:
+        return True
+    level = "WARN" if optional else "ERROR"
+    click.echo(
+        _("{level}: {tool} not found.{hint}", level=level, tool=name, hint=""),
+        err=True,
+    )
+    return False
+
+
+def _check_python_version(venv_bin: Path) -> None:
+    """Check that the venv Python is >= 3.12."""
+    python_bin = venv_bin / "python"
+    if not python_bin.exists():
+        click.echo(
+            _("WARN: .venv not found. Run 'make setup-venv' to create it."),
+            err=True,
+        )
+        return
+    result = subprocess.run(  # nosec B603
+        [str(python_bin), "--version"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        click.echo(_("WARN: Could not determine Python version in .venv."), err=True)
+        return
+    version_str = result.stdout.strip().split()[-1] if result.stdout else ""
+    try:
+        major, minor = int(version_str.split(".")[0]), int(version_str.split(".")[1])
+    except (IndexError, ValueError):
+        click.echo(_("WARN: Could not parse Python version '{version}'.", version=version_str), err=True)
+        return
+    if (major, minor) < PYTHON_MIN_VERSION:
+        click.echo(
+            _(
+                "WARN: .venv has Python {version}, but >={req} is required.",
+                version=version_str,
+                req=f"{PYTHON_MIN_VERSION[0]}.{PYTHON_MIN_VERSION[1]}",
+            ),
+            err=True,
+        )
+        return
+    click.echo(_("[check-deps] Virtualenv .venv ready (Python {version}).", version=version_str))
+
+
+@click.command()
+@click.option("--venv", default=".venv", show_default=True, help="Path to the virtual environment.")
+@click.option("--checkmake-bin", default=None, help="Path to checkmake binary (fallback if not on PATH).")
+def cli(venv: str, checkmake_bin: str | None) -> None:
+    """Verify that required development tools are present."""
+    click.echo(_("[check-deps] Verifying tools..."))
+
+    all_required = True
+    for tool in REQUIRED_TOOLS:
+        if not _check_tool(tool):
+            all_required = False
+
+    for tool in OPTIONAL_TOOLS:
+        if not _check_tool(tool, optional=True):
+            if checkmake_bin and Path(checkmake_bin).exists():
+                click.echo(_("  {tool}: found at {path}", tool=tool, path=checkmake_bin))
+            else:
+                click.echo(_("  Run 'make install-checkmake' to install the Makefile linter."))
+
+    _check_python_version(Path(venv) / "bin")
+
+    if not all_required:
+        raise click.ClickException(_("Required tools missing."))
+    click.echo(_("[check-deps] All core tools present."))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/check_mutable_globals.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Detect module-level mutable globals that may cause test isolation bugs.
+
+Scans Python files for patterns like::
+
+    _SEEN: set[Path] = set()
+    _CACHE: dict[Path, Any] = {}
+    PATHS: list[Path] = []
+
+These are hazardous because one test mutates the container and the next
+sees stale state.  The script reports the file/line and suggests a factory
+function or fixture replacement.
+
+Configuration (``[tool.devx.check_mutable_globals]`` in pyproject.toml):
+
+``scan_dirs``      — list of directories to scan (default: ``["scripts", "tests"]``)
+``skip_dirs``      — directory names to skip (default: ``__pycache__``, ``.pytest_cache``, ``venv``, ``.venv``)
+``known_safe``     — list of ``"path:line:var_name"`` entries to ignore
+
+Usage::
+
+    python3 -m devx.tools.check_mutable_globals
+    python3 -m devx.tools.check_mutable_globals --scan-dir src --scan-dir tests
+"""
+
+from __future__ import annotations
+
+import ast
+import contextlib
+from pathlib import Path
+
+import click
+
+from devx.config import _load_pyproject_devx
+from devx.i18n import _
+
+MUTABLE_TYPES = {"set", "dict", "list"}
+PATH_HINTS = ("path", "paths", "seen", "cache", "memo", "registry")
+DEFAULT_SCAN_DIRS = ["scripts", "tests"]
+DEFAULT_SKIP_DIRS = {"__pycache__", ".pytest_cache", "venv", ".venv"}
+
+
+def _load_config() -> tuple[list[str], set[str], set[tuple[str, int, str]]]:
+    """Load configuration from pyproject.toml [tool.devx.check_mutable_globals]."""
+    devx_cfg = _load_pyproject_devx()
+    cfg_raw = devx_cfg.get("check_mutable_globals", {})
+    if not isinstance(cfg_raw, dict):
+        return DEFAULT_SCAN_DIRS, DEFAULT_SKIP_DIRS, set()
+    cfg: dict[str, object] = cfg_raw  # type: ignore[assignment]
+
+    scan_dirs_raw = cfg.get("scan_dirs", DEFAULT_SCAN_DIRS)
+    scan_dirs: list[str] = [str(d) for d in scan_dirs_raw] if isinstance(scan_dirs_raw, list) else DEFAULT_SCAN_DIRS
+
+    skip_dirs_raw = cfg.get("skip_dirs", list(DEFAULT_SKIP_DIRS))
+    skip_dirs: set[str] = {str(d) for d in skip_dirs_raw} if isinstance(skip_dirs_raw, list) else DEFAULT_SKIP_DIRS
+
+    known_safe_raw = cfg.get("known_safe", [])
+    known_safe: set[tuple[str, int, str]] = set()
+    if isinstance(known_safe_raw, list):
+        for entry in known_safe_raw:
+            if isinstance(entry, str) and entry.count(":") >= 2:
+                parts = entry.rsplit(":", 2)
+                with contextlib.suppress(ValueError):
+                    known_safe.add((parts[0], int(parts[1]), parts[2]))
+
+    return scan_dirs, skip_dirs, known_safe
+
+
+def _should_skip(path: Path, skip_dirs: set[str]) -> bool:
+    return any(part in skip_dirs for part in path.parts)
+
+
+def find_mutable_globals(
+    file_path: Path,
+    repo_root: Path,
+    known_safe: set[tuple[str, int, str]],
+) -> list[str]:
+    """Return a list of issue strings for mutable globals in *file_path*."""
+    issues: list[str] = []
+    try:
+        source = file_path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+    except SyntaxError:
+        return issues
+
+    for node in ast.iter_child_nodes(tree):
+        if not isinstance(node, ast.AnnAssign | ast.Assign):
+            continue
+
+        names: list[str] = []
+        if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            names.append(node.target.id)
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    names.append(target.id)
+
+        for name in names:
+            name_lower = name.lower()
+            value = node.value
+            if value is None:
+                continue
+
+            is_mutable_literal = False
+            if isinstance(value, ast.Call):
+                if isinstance(value.func, ast.Name):
+                    if value.func.id in MUTABLE_TYPES:
+                        is_mutable_literal = True
+                elif isinstance(value.func, ast.Attribute):
+                    # e.g. collections.defaultdict
+                    pass
+            elif isinstance(value, (ast.Dict, ast.List, ast.Set)):
+                is_mutable_literal = True
+
+            if not is_mutable_literal:
+                continue
+
+            # Check if the name or type hint suggests Path usage
+            has_path_hint = any(hint in name_lower for hint in PATH_HINTS)
+            has_path_type = False
+            if isinstance(node, ast.AnnAssign) and node.annotation:
+                ann = ast.unparse(node.annotation)
+                has_path_type = "Path" in ann
+
+            if has_path_hint or has_path_type:
+                rel = str(file_path.relative_to(repo_root))
+                if (rel, node.lineno, name) in known_safe:
+                    continue
+                value_str = ast.unparse(value) if value is not None else "..."
+                issues.append(
+                    f"{rel}:{node.lineno}: mutable global {name!r} "
+                    f"({value_str}) — use a factory function or pytest fixture"
+                )
+
+    return issues
+
+
+@click.command()
+@click.option(
+    "--scan-dir",
+    multiple=True,
+    help=_("Additional directory to scan (default: scripts, tests). Can be repeated."),
+)
+def cli(scan_dir: tuple[str, ...]) -> None:
+    """Scan for module-level mutable globals that cause test isolation bugs."""
+    repo_root = Path.cwd()
+    config_scan_dirs, skip_dirs, known_safe = _load_config()
+
+    # CLI --scan-dir overrides config if provided
+    scan_dirs = list(scan_dir) if scan_dir else config_scan_dirs
+
+    all_issues: list[str] = []
+
+    for scan_dir_name in scan_dirs:
+        scan_path = repo_root / scan_dir_name
+        if not scan_path.exists():
+            continue
+        for py_file in scan_path.rglob("*.py"):
+            if _should_skip(py_file, skip_dirs):
+                continue
+            all_issues.extend(find_mutable_globals(py_file, repo_root, known_safe))
+
+    if all_issues:
+        click.echo(f"[check-mutable-globals] FAILED: {len(all_issues)} issue(s)", err=True)
+        for issue in all_issues:
+            click.echo(f"  {issue}", err=True)
+        raise click.ClickException(
+            _("Found {count} mutable global(s) — use factory functions or pytest fixtures.", count=len(all_issues))
+        )
+
+    click.echo(_("[check-mutable-globals] Passed: no mutable path globals found"))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/check_pyproject_deps.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Validate that every dependency in pyproject.toml has a documented purpose.
+
+This script does NOT resolve versions or query PyPI. It only ensures that
+every dependency listed in ``[project.dependencies]`` or
+``[project.optional-dependencies]`` has a corresponding comment nearby
+explaining why it is needed.
+
+Failure means a dependency lacks documentation.
+
+Usage::
+
+    python3 -m devx.tools.check_pyproject_deps
+    python3 -m devx.tools.check_pyproject_deps --file path/to/pyproject.toml
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from devx.i18n import _
+
+
+def check_deps(pyproject_path: Path) -> list[str]:
+    """Return a list of issue strings for undocumented dependencies.
+
+    An empty list means all dependencies are documented.
+    """
+    if not pyproject_path.exists():
+        return [str(pyproject_path) + ": file not found"]
+
+    content = pyproject_path.read_text(encoding="utf-8")
+    lines = content.splitlines()
+
+    issues: list[str] = []
+    in_deps_section = False
+    prev_was_comment = False
+
+    for i, raw_line in enumerate(lines, start=1):
+        stripped = raw_line.strip()
+
+        # Detect section headers
+        if stripped in ("[project.dependencies]", "[project.optional-dependencies]"):
+            in_deps_section = True
+            continue
+        if stripped.startswith("[") and in_deps_section:
+            in_deps_section = False
+            continue
+
+        if not in_deps_section:
+            continue
+
+        if stripped == "":
+            continue
+
+        # We're inside a dependency list
+        if stripped.startswith("#"):
+            prev_was_comment = True
+            continue
+
+        if stripped.startswith("-") or stripped.startswith('"'):
+            if not prev_was_comment:
+                issues.append(f"{pyproject_path.name}:{i}: dependency lacks description comment: {stripped}")
+            prev_was_comment = False
+        else:
+            prev_was_comment = False
+
+    return issues
+
+
+@click.command()
+@click.option(
+    "--file",
+    "pyproject_file",
+    type=click.Path(path_type=Path),
+    default=Path("pyproject.toml"),
+    help=_("Path to pyproject.toml (default: pyproject.toml in CWD)."),
+)
+def cli(pyproject_file: Path) -> None:
+    """Validate that every dependency in pyproject.toml has a documented purpose."""
+    issues = check_deps(pyproject_file)
+
+    if issues:
+        click.echo(
+            _("FAILED: {count} undocumented dependency/ies", count=len(issues)),
+            err=True,
+        )
+        for issue in issues:
+            click.echo(f"  {issue}", err=True)
+        raise click.ClickException(_("Dependencies must have documentation comments."))
+
+    click.echo(_("[check-dep-docs] Passed: all dependencies are documented"))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/check_test_coverage.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Pre-commit / CI check: ensure every changed or new file has corresponding tests.
+
+Configuration (``[tool.devx.check_test_coverage]`` in pyproject.toml):
+
+``rules`` — list of mapping rules, each with:
+
+``source_pattern``  — glob pattern for source files (e.g. ``"scripts/*.py"``)
+``test_paths``      — list of test path templates (e.g. ``["scripts/tests/test_{name}", "tests/unit/test_{name}"]``)
+``description``     — human-readable description for error messages
+
+``skip_patterns``   — list of file patterns to skip (e.g. ``["__init__.py", "config.py"]``)
+``test_file_indicators`` — substrings that identify a file as a test (default: ``["tests/", "/test_", "_test.py"]``)
+``skip_extensions`` — file extensions to skip (default: .md, .yml, .yaml, .json, .tf, .sh, .conf, .service)
+
+Built-in defaults cover common Python project layouts (``scripts/*.py``, ``src/**/*.py``).
+Project-specific rules are merged with defaults (first match wins).
+
+Usage::
+
+    python3 -m devx.tools.check_test_coverage [--staged-only] [--warn-only]
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import subprocess  # nosec B404
+from pathlib import Path
+
+import click
+
+from devx.config import _load_pyproject_devx
+from devx.i18n import _
+
+DEFAULT_TEST_INDICATORS = ["tests/", "/test_", "_test.py"]
+DEFAULT_SKIP_EXTENSIONS = (".md", ".yml", ".yaml", ".json", ".tf", ".sh", ".conf", ".service")
+
+# Built-in rules for common Python project layouts
+BUILTIN_RULES: list[dict[str, object]] = [
+    {
+        "source_pattern": "scripts/*.py",
+        "test_paths": ["scripts/tests/test_{name}", "tests/unit/test_{name}"],
+        "description": "Missing unit test: scripts/tests/test_{name} or tests/unit/test_{name}",
+    },
+    {
+        "source_pattern": "src/**/*.py",
+        "test_paths": ["tests/unit/test_{name}", "tests/unit/test_{module}_{name}"],
+        "description": "Missing unit test: tests/unit/test_{name}",
+    },
+]
+
+
+def _load_rules() -> tuple[list[dict[str, object]], list[str], list[str], tuple[str, ...]]:
+    """Load test coverage rules from pyproject.toml."""
+    devx_cfg = _load_pyproject_devx()
+    cfg_raw = devx_cfg.get("check_test_coverage", {})
+    if not isinstance(cfg_raw, dict):
+        return BUILTIN_RULES, [], DEFAULT_TEST_INDICATORS, DEFAULT_SKIP_EXTENSIONS
+    cfg: dict[str, object] = cfg_raw  # type: ignore[assignment]
+
+    rules_raw = cfg.get("rules", BUILTIN_RULES)
+    rules: list[dict[str, object]] = [dict(r) for r in rules_raw] if isinstance(rules_raw, list) else BUILTIN_RULES
+
+    skip_raw = cfg.get("skip_patterns", [])
+    skip_patterns: list[str] = [str(s) for s in skip_raw] if isinstance(skip_raw, list) else []
+
+    indicators_raw = cfg.get("test_file_indicators", DEFAULT_TEST_INDICATORS)
+    indicators: list[str] = (
+        [str(s) for s in indicators_raw] if isinstance(indicators_raw, list) else DEFAULT_TEST_INDICATORS
+    )
+
+    skip_ext_raw = cfg.get("skip_extensions", list(DEFAULT_SKIP_EXTENSIONS))
+    if isinstance(skip_ext_raw, list):
+        skip_ext: tuple[str, ...] = tuple(str(s) for s in skip_ext_raw)
+    else:
+        skip_ext = DEFAULT_SKIP_EXTENSIONS
+
+    return rules, skip_patterns, indicators, skip_ext
+
+
+def _changed_files(staged_only: bool, repo_root: Path) -> list[str]:
+    """Return list of changed file paths relative to repo root."""
+    if staged_only:
+        cmd = ["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"]
+    else:
+        # Compare against origin/master for CI usage
+        cmd = ["git", "diff", "origin/master...HEAD", "--name-only", "--diff-filter=ACMR"]
+    result = subprocess.run(  # nosec B603, B607
+        cmd, capture_output=True, text=True, check=False, cwd=repo_root
+    )
+    if result.returncode != 0:
+        # fallback: just use staged files
+        result = subprocess.run(  # nosec B603, B607
+            ["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"],
+            capture_output=True,
+            text=True,
+            check=False,
+            cwd=repo_root,
+        )
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
+def _is_test_file(filepath: str, indicators: list[str]) -> bool:
+    """Check if a file is a test file."""
+    return any(indicator in filepath for indicator in indicators)
+
+
+def _should_skip_file(
+    filepath: str,
+    skip_patterns: list[str],
+    skip_extensions: tuple[str, ...],
+) -> bool:
+    """Check if a file should be skipped."""
+    if filepath.startswith("."):
+        return True
+    if filepath.endswith(skip_extensions):
+        return True
+    name = Path(filepath).name
+    return any(fnmatch.fnmatch(name, pattern) or fnmatch.fnmatch(filepath, pattern) for pattern in skip_patterns)
+
+
+def _resolve_test_path(template: str, source_path: str, repo_root: Path) -> Path:
+    """Resolve a test path template to an actual path.
+
+    Templates can use:
+    - ``{name}`` — the source file's name (without extension)
+    - ``{module}`` — the source file's parent directory name
+    - ``{package_prefix}`` — underscore-joined subdirectories (for nested modules)
+    """
+    path = Path(source_path)
+    name = path.stem
+    module = path.parent.name
+
+    # Build package prefix for nested modules (e.g. scripts/utils/secrets.py -> utils)
+    parts = path.parts
+    package_prefix = ""
+    if len(parts) > 2:
+        package_prefix = "_".join(parts[1:-1])
+
+    resolved = template.format(
+        name=name,
+        module=module,
+        package_prefix=package_prefix,
+    )
+    # Normalize hyphens to underscores (Python module naming)
+    resolved = resolved.replace("-", "_")
+    return repo_root / resolved
+
+
+def _find_missing_tests(
+    files: list[str],
+    repo_root: Path,
+    rules: list[dict[str, object]],
+    skip_patterns: list[str],
+    test_indicators: list[str],
+    skip_extensions: tuple[str, ...],
+) -> dict[str, str]:
+    """Map each untested file to the reason it's untested."""
+    missing: dict[str, str] = {}
+
+    for f in files:
+        # Skip test files themselves
+        if _is_test_file(f, test_indicators):
+            continue
+
+        # Skip config, docs, meta files
+        if _should_skip_file(f, skip_patterns, skip_extensions):
+            continue
+
+        for rule in rules:
+            pattern = str(rule.get("source_pattern", ""))
+            if not fnmatch.fnmatch(f, pattern):
+                continue
+
+            test_templates = rule.get("test_paths", [])
+            if not isinstance(test_templates, list):
+                continue
+
+            description_template = str(rule.get("description", "Missing test for {f}"))
+
+            test_paths = [_resolve_test_path(str(t), f, repo_root) for t in test_templates]
+
+            # Check if any test path exists (with .py extension)
+            found = False
+            for tp in test_paths:
+                if tp.with_suffix(".py").exists() or tp.exists():
+                    found = True
+                    break
+
+            if not found:
+                # Format description with file info
+                name = Path(f).stem
+                missing[f] = description_template.format(
+                    name=name,
+                    f=f,
+                    test_name=f"test_{name}".replace("-", "_"),
+                )
+            break
+
+        # If no rule matched, the file is not checked (no test requirement)
+        # This is intentional — only files matching a rule need tests
+
+    return missing
+
+
+@click.command()
+@click.option("--staged-only", is_flag=True, help=_("Only check staged files (for pre-commit)"))
+@click.option("--warn-only", is_flag=True, help=_("Print warnings but always exit 0"))
+def cli(staged_only: bool, warn_only: bool) -> None:
+    """Check that changed files have corresponding tests."""
+    repo_root = Path.cwd()
+    rules, skip_patterns, test_indicators, skip_extensions = _load_rules()
+
+    files = _changed_files(staged_only, repo_root)
+    if not files:
+        click.echo(_("[check_test_coverage] No changed files to check."))
+        return
+
+    missing = _find_missing_tests(files, repo_root, rules, skip_patterns, test_indicators, skip_extensions)
+    if not missing:
+        click.echo(f"[check_test_coverage] All {len(files)} changed file(s) have tests.")
+        return
+
+    click.echo("[check_test_coverage] FAILED: missing tests for changed files:\n", err=True)
+    for f, reason in missing.items():
+        click.echo(f"  {f}", err=True)
+        click.echo(f"    -> {reason}", err=True)
+
+    click.echo(
+        _("\n[check_test_coverage] Fix: add the missing test file(s) before committing."),
+        err=True,
+    )
+
+    if not warn_only:
+        raise click.ClickException(_("Missing tests for changed files."))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/check_test_speed.py

@@ -32,7 +32,10 @@ _TIMING_RE = re.compile(r"(\d+) passed.* in ([0-9.]+)s")
 
 # Matches per-test duration lines from --durations=0:
 #   0.51s call     tests/test_foo.py::test_bar
-_DURATION_LINE_RE = re.compile(r"^(\d+\.?\d*)s\s+(?:setup|call|teardown)\s+(.+)$")
+# Only "call" duration is counted — "setup" includes import/collection
+# overhead (coverage init, module imports) which is environment-dependent
+# and not a test quality signal.
+_DURATION_LINE_RE = re.compile(r"^(\d+\.?\d*)s\s+call\s+(.+)$")
 
 
 def run_tests() -> tuple[str, str]:

src/devx/tools/clean_images.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""Clean up old Docker images from a Gitea container registry.
+
+Queries the Gitea API for all versions of a package (container type) and
+deletes all but the most recent N versions.  The ``latest`` tag is always
+preserved if present.
+
+Usage::
+
+    # Clean up ci-base images, keep last 2 versions
+    python3 -m devx.tools.clean_images \\
+        --owner oblachno-oss \\
+        --name ci-base \\
+        --keep 2
+
+    # Clean up multiple images
+    python3 -m devx.tools.clean_images \\
+        --owner oblachno-oss \\
+        --name ci-base \\
+        --name ci-quality \\
+        --name ci-full \\
+        --keep 2
+
+    # Dry run (list what would be deleted)
+    python3 -m devx.tools.clean_images \\
+        --owner oblachno-oss \\
+        --name ci-base \\
+        --keep 2 \\
+        --dry-run
+
+Authentication uses ``CI_GITEA_TOKEN`` environment variable.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import click
+import requests
+
+from devx.config import GITEA_API_URL, REPO_OWNER
+from devx.i18n import _
+
+
+def list_package_versions(
+    api_url: str,
+    owner: str,
+    name: str,
+    token: str,
+    *,
+    timeout: int = 30,
+) -> list[dict[str, Any]]:
+    """List all versions of a container package from the Gitea API.
+
+    Returns a list of version dicts, each containing at least ``version``
+    and ``created_at`` fields.
+    """
+    url = f"{api_url}/packages/{owner}?type=container&name={name}"
+    headers = {"Authorization": f"token {token}"}
+    all_versions: list[dict[str, Any]] = []
+    page = 1
+    while True:
+        resp = requests.get(
+            f"{url}&page={page}&limit=50",
+            headers=headers,
+            timeout=timeout,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if not data:
+            break
+        all_versions.extend(data)
+        if len(data) < 50:
+            break
+        page += 1
+    return all_versions
+
+
+def delete_package_version(
+    api_url: str,
+    owner: str,
+    name: str,
+    version: str,
+    token: str,
+    *,
+    timeout: int = 30,
+    package_type: str = "container",
+    max_retries: int = 3,
+) -> bool:
+    """Delete a specific version of a container package.
+
+    Uses the Gitea API endpoint ``DELETE /packages/{owner}/{type}/{name}/{version}``.
+    Retries on transient failures (5xx, timeouts) up to ``max_retries`` times.
+
+    Returns True on success, False on failure.
+    """
+    url = f"{api_url}/packages/{owner}/{package_type}/{name}/{version}"
+    headers = {"Authorization": f"token {token}"}
+    for attempt in range(max_retries):
+        try:
+            resp = requests.delete(url, headers=headers, timeout=timeout)
+        except requests.RequestException:
+            if attempt < max_retries - 1:
+                time.sleep(2**attempt)
+                continue
+            return False
+        if resp.status_code in (204, 200):
+            return True
+        # 404 means already deleted — treat as success
+        if resp.status_code == 404:
+            return True
+        # 5xx is transient — retry
+        if 500 <= resp.status_code < 600 and attempt < max_retries - 1:
+            time.sleep(2**attempt)
+            continue
+        return False
+    return False
+
+
+def sort_versions_by_date(
+    versions: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Sort package versions by creation date, newest first.
+
+    Falls back to version string comparison if created_at is missing.
+    """
+
+    def _sort_key(v: dict[str, Any]) -> str:
+        return str(v.get("created_at", v.get("version", "")))
+
+    return sorted(versions, key=_sort_key, reverse=True)
+
+
+def select_for_deletion(
+    versions: list[dict[str, Any]],
+    keep: int,
+) -> list[dict[str, Any]]:
+    """Select versions to delete, keeping the most recent ``keep`` versions.
+
+    Versions named ``latest`` are always preserved.
+    """
+    sorted_versions = sort_versions_by_date(versions)
+    to_delete = sorted_versions[keep:]
+    # Always preserve 'latest' tag
+    to_delete = [v for v in to_delete if v.get("version") != "latest"]
+    return to_delete
+
+
+@click.command()
+@click.option(
+    "--owner",
+    default=None,
+    help="Package owner (user or org, default: from [tool.devx] repo_owner).",
+)
+@click.option(
+    "--name",
+    "names",
+    multiple=True,
+    required=True,
+    help="Package name(s). Can be repeated.",
+)
+@click.option(
+    "--keep",
+    default=2,
+    type=int,
+    show_default=True,
+    help="Number of recent versions to keep (excluding 'latest').",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="List versions that would be deleted without actually deleting.",
+)
+@click.option(
+    "--api-url",
+    default=None,
+    help="Gitea API URL (defaults to DEVX_GITEA_API_URL or built-in default).",
+)
+def main(
+    owner: str | None,
+    names: tuple[str, ...],
+    keep: int,
+    dry_run: bool,
+    api_url: str | None,
+) -> None:
+    """Clean up old Docker image versions from a Gitea registry."""
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    if not token:
+        raise click.ClickException(_("CI_GITEA_TOKEN environment variable required"))
+    if not owner:
+        owner = REPO_OWNER
+    if not owner:
+        raise click.ClickException(_("Package owner not specified. Use --owner or set [tool.devx] repo_owner."))
+    base_url = api_url or GITEA_API_URL
+
+    total_deleted = 0
+    total_kept = 0
+    total_failed = 0
+    for name in names:
+        click.echo(_("\n{separator}", separator="=" * 60))
+        click.echo(_("Package: {owner}/{name}", owner=owner, name=name))
+        click.echo(_("{separator}", separator="=" * 60))
+        try:
+            versions = list_package_versions(base_url, owner, name, token)
+        except requests.RequestException as exc:
+            click.echo(
+                _("Failed to list versions for {name}: {error}", name=name, error=exc),
+                err=True,
+            )
+            total_failed += 1
+            continue
+
+        if not versions:
+            click.echo(_("No versions found."))
+            continue
+
+        click.echo(_("Found {count} version(s):", count=len(versions)))
+        for v in sort_versions_by_date(versions):
+            click.echo(
+                _("  {version} (created: {created})", version=v.get("version", "?"), created=v.get("created_at", "?"))
+            )
+
+        to_delete = select_for_deletion(versions, keep)
+        kept_count = len(versions) - len(to_delete)
+        click.echo(_("\nKeeping {kept}, would delete {count}", kept=kept_count, count=len(to_delete)))
+
+        if dry_run:
+            for v in to_delete:
+                click.echo(_("  [dry-run] Would delete: {version}", version=v.get("version", "?")))
+            total_kept += kept_count
+            continue
+
+        deleted_count = 0
+        failed_count = 0
+        for v in to_delete:
+            version = str(v.get("version", ""))
+            if delete_package_version(base_url, owner, name, version, token):
+                click.echo(_("  Deleted: {version}", version=version))
+                deleted_count += 1
+            else:
+                click.echo(_("  FAILED to delete: {version}", version=version), err=True)
+                failed_count += 1
+
+        total_deleted += deleted_count
+        total_kept += kept_count
+        total_failed += failed_count
+
+    click.echo(
+        _(
+            "\nDone. Deleted {deleted}, kept {kept}, failed {failed}.",
+            deleted=total_deleted,
+            kept=total_kept,
+            failed=total_failed,
+        )
+    )
+    if total_failed > 0:
+        raise click.ClickException(_("Failed to delete {count} image version(s)", count=total_failed))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()  # pragma: no cover

src/devx/tools/configure_repo.py

@@ -1,13 +1,14 @@
 #!/usr/bin/env python3
-"""Configure repository: branch protection + repo settings via Gitea REST API.
+"""Configure repository: branch protection, repo settings, and standard labels.
 
-Uses ``GiteaClient`` for branch protection and repo settings.
-The ``tea`` CLI is used for label creation if available, with a
-fallback to ``GiteaClient`` if tea is not installed.
+Uses ``GiteaClient`` for branch protection, repo settings, and label
+creation. Standard labels (bug, ready-to-merge, feedback, tooling,
+ci-improvement, doc-improvement, workflow-improvement) are created
+idempotently via ``ensure_label``.
 
 Usage:
-  REPO_TOKEN=<token> python3 -m devx.tools.configure_repo --repo my-repo
-  REPO_TOKEN=<token> python3 -m devx.tools.configure_repo --repo my-repo --owner my-org
+  CI_GITEA_TOKEN=<token> python3 -m devx.tools.configure_repo --repo my-repo
+  CI_GITEA_TOKEN=<token> python3 -m devx.tools.configure_repo --repo my-repo --owner my-org
 """
 
 from __future__ import annotations
@@ -19,7 +20,7 @@ from typing import Any, cast
 import click
 
 from devx.api_clients import GiteaClient
-from devx.config import GITEA_API_URL, REPO_OWNER
+from devx.config import GITEA_API_URL, REPO_NAME, REPO_OWNER
 from devx.exceptions import APIError
 from devx.i18n import _
 
@@ -50,11 +51,17 @@ def _default_branch_protection_config() -> dict[str, Any]:
         "push_whitelist_usernames": [],
         "enable_status_check": True,
         "status_check_contexts": _default_status_checks(),
-        "required_approvals": 0,
+        "required_approvals": 1,
         "dismiss_stale_approvals": True,
         "block_on_outdated_branch": True,
         "block_on_rejected_reviews": True,
         "block_on_official_review_requests": True,
+        # Prevent admins from force-merging PRs that don't meet branch
+        # protection requirements (e.g. missing approvals). Without this,
+        # an admin token can bypass the approval gate via force_merge=true,
+        # allowing merges that failed the auto-merge CI job to reach master
+        # and trigger the post-merge release pipeline.
+        "block_admin_merge_override": True,
     }
 
 
@@ -65,6 +72,19 @@ def _default_repo_settings_config() -> dict[str, Any]:
     }
 
 
+# Standard labels created in every oblachno repo.
+# These cover CI failure notifications, subagent feedback, and auto-merge.
+_STANDARD_LABELS: list[dict[str, str]] = [
+    {"name": "bug", "color": "#ee0701", "description": "Something is not working"},
+    {"name": "ready-to-merge", "color": "#a2eeef", "description": "PR has been reviewed and is ready for auto-merge"},
+    {"name": "feedback", "color": "#fbca04", "description": "Issues from subagent or agent feedback"},
+    {"name": "tooling", "color": "#c5def5", "description": "Tool-related feedback or improvements"},
+    {"name": "ci-improvement", "color": "#84b6eb", "description": "CI workflow improvements"},
+    {"name": "doc-improvement", "color": "#d4c5f9", "description": "Documentation improvements"},
+    {"name": "workflow-improvement", "color": "#fef2c0", "description": "Workflow alignment or pattern improvements"},
+]
+
+
 def _handle_http_error(e: APIError) -> None:
     """Raise a user-friendly Click exception for HTTP errors."""
     if e.status == http.HTTPStatus.FORBIDDEN:
@@ -102,7 +122,7 @@ def configure_repo(
         api_url: Gitea API base URL. If None, uses ``GITEA_API_URL`` from config.
     """
     if not token:
-        raise click.ClickException(_("ERROR: REPO_TOKEN is not set."))
+        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set."))
 
     url = api_url or GITEA_API_URL
     client = GiteaClient(url, token, owner, repo)
@@ -123,6 +143,7 @@ def configure_repo(
         click.echo(_("  - Dismiss stale approvals: yes"))
         click.echo(_("  - Block outdated branches: yes"))
         click.echo(_("  - Block rejected reviews: yes"))
+        click.echo(_("  - Block admin merge override: yes"))
         checks = ", ".join(cast(list[str], bp_config["status_check_contexts"]))
         click.echo(_("  - Required status checks: {checks}", checks=checks))
 
@@ -131,6 +152,12 @@ def configure_repo(
         client.update_repo_settings(cast(dict[str, object], rs_config))
         click.echo(_("  - Auto-delete branch after merge: yes"))
 
+        click.echo("")
+        click.echo(_("Ensuring standard labels..."))
+        for label in _STANDARD_LABELS:
+            client.ensure_label(label["name"], label["color"], label["description"])
+        click.echo(_("  - {count} standard labels verified", count=len(_STANDARD_LABELS)))
+
         click.echo("")
         click.echo(_("Repository configuration complete."))
     except APIError as e:
@@ -148,13 +175,26 @@ def configure_repo(
 )
 def main(repo: str | None, owner: str | None, branch: str, api_url: str | None) -> None:
     """Configure branch protection and repository settings via the Gitea API."""
-    token = os.environ.get("REPO_TOKEN", "")
+    token = os.environ.get("CI_GITEA_TOKEN", "")
 
     if repo is None:
-        repo = os.environ.get("DEVX_REPO_NAME", "")
+        repo = os.environ.get("DEVX_REPO_NAME", "") or REPO_NAME
     if not repo:
         raise click.ClickException(_("ERROR: Repository name not specified. Use --repo or set DEVX_REPO_NAME."))
 
+    # If DEVX_REPO_NAME contains a slash (e.g. "oblachno/infra"), split into owner/repo.
+    # This prevents 404s when workflows set DEVX_REPO_NAME to the full path.
+    if "/" in repo and owner is None:
+        parts = repo.split("/", 1)
+        owner, repo = parts[0], parts[1]
+        click.echo(
+            _(
+                "Parsed owner={owner}, repo={repo} from DEVX_REPO_NAME",
+                owner=owner,
+                repo=repo,
+            )
+        )
+
     if owner is None:
         owner = REPO_OWNER
 

src/devx/tools/create_pr.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Create a pull request with the correct title from the Vikunja task.
+
+This tool is run **after** pushing a feature branch.  It:
+
+1. Extracts the task ID from the branch name (e.g. ``DEVX-31-fix-foo`` → ``DEVX-31``).
+2. Fetches the Vikunja task title for that task ID.
+3. Creates a PR with title ``{TASK_PREFIX}-N: <vikunja task title>``.
+
+This eliminates manual PR title entry and ensures the title always
+matches the Vikunja task — which is what the auto-merge workflow
+validates.
+
+If a PR already exists for the branch, the tool prints its URL and
+exits successfully (idempotent).
+
+Usage::
+
+    python -m devx.tools.create_pr --branch DEVX-31-fix-foo
+
+The repository is auto-detected from ``DEVX_REPO_OWNER`` /
+``DEVX_REPO_NAME`` or ``GITHUB_REPOSITORY`` environment variables.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess  # nosec B404
+
+import click
+from dotenv import load_dotenv
+
+from devx.api_clients import GiteaClient, VikunjaClient
+from devx.config import (
+    DEFAULT_PER_PAGE,
+    GITEA_API_URL,
+    REPO_NAME,
+    REPO_OWNER,
+    TASK_ID_RE,
+    TASK_PREFIX,
+    VIKUNJA_API_URL,
+    VIKUNJA_PROJECT_ID,
+)
+from devx.i18n import _
+
+load_dotenv()
+
+
+def get_repo_name() -> str:
+    """Auto-detect repository name from env vars, pyproject.toml, or git remote."""
+    name = os.environ.get("DEVX_REPO_NAME", "")
+    if name:
+        return name
+    github_repo = os.environ.get("GITHUB_REPOSITORY", "")
+    if github_repo and "/" in github_repo:
+        return github_repo.split("/", 1)[1]
+    if REPO_NAME:
+        return REPO_NAME
+    raise click.ClickException(
+        _("Repository name not set. Use DEVX_REPO_NAME, [tool.devx] repo_name, or GITHUB_REPOSITORY env var."),
+    )
+
+
+def extract_task_id(branch: str) -> str:
+    """Extract the task ID (e.g. ``DEVX-31``) from a branch name."""
+    match = TASK_ID_RE.search(branch)
+    return match.group(0) if match else ""
+
+
+def get_vikunja_task_title(task_id: str) -> str:
+    """Fetch the Vikunja task title for the given task identifier.
+
+    Raises ClickException if VIKUNJA_TOKEN is not set or the task is not found.
+    """
+    token = os.environ.get("VIKUNJA_TOKEN", "")
+    if not token:
+        raise click.ClickException(_("VIKUNJA_TOKEN is not set. Required to derive PR title."))
+    client = VikunjaClient(VIKUNJA_API_URL, token)
+    task = client.find_task_by_identifier(VIKUNJA_PROJECT_ID, task_id, per_page=DEFAULT_PER_PAGE)
+    if not task:
+        raise click.ClickException(
+            _(
+                "Could not find Vikunja task {task_id} in project {project_id}.",
+                task_id=task_id,
+                project_id=VIKUNJA_PROJECT_ID,
+            ),
+        )
+    return str(task.get("title", ""))
+
+
+def find_existing_pr(client: GiteaClient, branch: str) -> dict | None:
+    """Return an existing open PR for the branch, or None."""
+    prs = client.list_prs(state="open")
+    for pr in prs:
+        if pr.get("head", {}).get("ref") == branch:
+            return pr
+    return None
+
+
+def create_pr(
+    branch: str,
+    base: str,
+    body: str,
+    repo_owner: str,
+    repo_name: str,
+) -> dict:
+    """Create a PR with the title derived from the Vikunja task.
+
+    Returns the PR dict from the Gitea API.
+    """
+    task_id = extract_task_id(branch)
+    if not task_id:
+        raise click.ClickException(
+            _(
+                "Branch '{branch}' does not contain a task ID.\n  Expected format: {prefix}-N-short-description",
+                branch=branch,
+                prefix=TASK_PREFIX,
+            ),
+        )
+
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    if not token:
+        raise click.ClickException(_("CI_GITEA_TOKEN is not set. Required to create a PR."))
+
+    vikunja_title = get_vikunja_task_title(task_id)
+    pr_title = f"{task_id}: {vikunja_title}"
+
+    client = GiteaClient(GITEA_API_URL, token, repo_owner, repo_name)
+
+    existing = find_existing_pr(client, branch)
+    if existing:
+        click.echo(
+            _(
+                "PR already exists: #{index} — {url}",
+                index=existing.get("number", "?"),
+                url=existing.get("html_url", ""),
+            ),
+        )
+        return existing
+
+    pr = client.create_pr(title=pr_title, head=branch, base=base, body=body)
+    click.echo(
+        _(
+            "Created PR #{index}: {title}\n  {url}",
+            index=pr.get("number", "?"),
+            title=pr_title,
+            url=pr.get("html_url", ""),
+        ),
+    )
+    return pr
+
+
+@click.command()
+@click.option("--branch", default=None, help="Head branch (default: auto-detect from git).")
+@click.option("--base", default="master", show_default=True, help="Base branch.")
+@click.option("--body", default="", help="PR body (markdown). Read from stdin if '-' is passed.")
+@click.option("--owner", default=None, help="Repository owner (default: DEVX_REPO_OWNER).")
+@click.option("--repo", default=None, help="Repository name (default: DEVX_REPO_NAME or GITHUB_REPOSITORY).")
+def cli(branch: str | None, base: str, body: str, owner: str | None, repo: str | None) -> None:
+    """Create a PR with the correct title from the Vikunja task."""
+    if branch is None:
+        result = subprocess.run(  # nosec
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise click.ClickException(
+                _("Could not detect current branch: {error}", error=result.stderr.strip()),
+            )
+        branch = result.stdout.strip()
+
+    if body == "-":
+        body = click.get_text_stream("stdin").read().strip()
+
+    repo_owner = owner or REPO_OWNER
+    if not repo_owner:
+        raise click.ClickException(_("Repository owner not set. Use --owner or DEVX_REPO_OWNER env var."))
+    repo_name = repo or get_repo_name()
+
+    create_pr(branch, base, body, repo_owner, repo_name)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/create_task.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Create a Vikunja task with a detailed HTML description.
+
+This tool is used during the planning phase of the development workflow
+to create a well-described task before any code is written.  The task
+identifier (e.g. ``DEVX-N``, ``GRM-N``, ``OBL-INFRA-N``) is then used
+to name the feature branch and the pull request.
+
+Usage::
+
+    python -m devx.tools.create_task --title "Add release automation" \\
+        --description "<h2>Overview</h2><p>Implement automated...</p>"
+
+The project ID and task prefix are read from ``DEVX_VIKUNJA_PROJECT_ID``
+and ``DEVX_TASK_PREFIX`` environment variables (or ``.env``).
+"""
+
+from __future__ import annotations
+
+import os
+
+import click
+from dotenv import load_dotenv
+
+from devx.api_clients import VikunjaClient
+from devx.config import TASK_PREFIX, VIKUNJA_API_URL, VIKUNJA_PROJECT_ID
+from devx.i18n import _
+
+load_dotenv()
+
+
+@click.command()
+@click.option("--title", required=True, help="Task title (becomes the Vikunja task title).")
+@click.option(
+    "--description",
+    default="",
+    help="Task description (HTML supported). Read from stdin if '-' is passed.",
+)
+@click.option("--project-id", type=int, default=None, help="Vikunja project ID (default: DEVX_VIKUNJA_PROJECT_ID).")
+def cli(title: str, description: str, project_id: int | None) -> None:
+    """Create a Vikunja task and print its identifier."""
+    token = os.environ.get("VIKUNJA_TOKEN", "")
+    if not token:
+        raise click.ClickException(_("VIKUNJA_TOKEN is not set. Set it in .env or environment."))
+
+    pid = project_id if project_id is not None else VIKUNJA_PROJECT_ID
+
+    if description == "-":
+        description = click.get_text_stream("stdin").read().strip()
+
+    client = VikunjaClient(VIKUNJA_API_URL, token)
+    task = client.create_task(pid, title, description)
+
+    identifier = task.get("identifier", "")
+    task_id = task.get("id", "")
+    click.echo(
+        _(
+            "Created Vikunja task: {identifier} (id={task_id})",
+            identifier=identifier,
+            task_id=task_id,
+        )
+    )
+    if identifier:
+        click.echo(
+            _(
+                "Next steps:\n"
+                "  1. git checkout master && git pull\n"
+                "  2. git checkout -b {prefix}-{num}-short-description\n"
+                "  3. Implement changes, commit with conventional commit format\n"
+                "  4. git push -u origin HEAD\n"
+                "  5. make create-pr  (creates PR with title: {identifier}: {title})",
+                prefix=TASK_PREFIX,
+                num=identifier.split("-")[-1] if "-" in identifier else "N",
+                identifier=identifier,
+                title=title,
+            )
+        )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/docker_login.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Docker registry login helper.
+
+Handles login to Docker registries (Gitea, Docker Hub) with credential
+loading from environment variables. Supports required and optional modes.
+
+Usage::
+
+    python3 -m devx.tools.docker_login --registry git.oblachno.oblachno.fyi \\
+        --token-env CI_GITEA_TOKEN --username-env CI_GITEA_USERNAME \\
+        --default-username emil
+
+    python3 -m devx.tools.docker_login --registry docker.io \\
+        --token-env DOCKER_HUB_TOKEN --username-env DOCKER_HUB_USERNAME --optional
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+
+import click
+
+from devx.i18n import _
+
+
+def docker_login(
+    registry: str,
+    username: str,
+    token: str,
+    *,
+    suppress_failure: bool = False,
+) -> bool:
+    """Log in to a Docker registry.
+
+    Returns True on success, False on failure.
+    If ``suppress_failure`` is True, prints a warning instead of raising.
+    """
+    cmd = ["docker", "login", registry, "-u", username, "-p", token]
+    result = subprocess.run(  # nosec B603
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        if suppress_failure:
+            click.echo(
+                _("[docker-login] Login to {registry} failed (continuing).", registry=registry),
+                err=True,
+            )
+            return False
+        raise click.ClickException(
+            _("Login to {registry} failed: {error}", registry=registry, error=result.stderr.strip()),
+        )
+    click.echo(_("[docker-login] Logged in to {registry}.", registry=registry))
+    return True
+
+
+def _resolve_credentials(
+    token_env: str,
+    username_env: str,
+    default_username: str | None,
+) -> tuple[str | None, str | None]:
+    """Resolve credentials from environment variables.
+
+    Returns (username, token) or (None, None) if token is not set.
+    """
+    import os
+
+    token = os.environ.get(token_env, "")
+    if not token:
+        return None, None
+    username = os.environ.get(username_env, "") or (default_username or "")
+    return username, token
+
+
+@click.command()
+@click.option("--registry", required=True, help="Docker registry URL (e.g. docker.io, git.example.com).")
+@click.option("--token-env", required=True, help="Environment variable name for the auth token.")
+@click.option("--username-env", required=True, help="Environment variable name for the username.")
+@click.option(
+    "--default-username",
+    default=None,
+    help="Default username if the env var is not set.",
+)
+@click.option(
+    "--optional",
+    is_flag=True,
+    default=False,
+    help="Skip silently if token is not set instead of raising.",
+)
+@click.option(
+    "--suppress-failure",
+    is_flag=True,
+    default=False,
+    help="Continue on login failure instead of raising (prints warning).",
+)
+def cli(
+    registry: str,
+    token_env: str,
+    username_env: str,
+    default_username: str | None,
+    optional: bool,
+    suppress_failure: bool,
+) -> None:
+    """Log in to a Docker registry using credentials from environment variables."""
+    username, token = _resolve_credentials(token_env, username_env, default_username)
+    if token is None:
+        if optional:
+            click.echo(_("[docker-login] Skipping {registry} (token {env} not set).", registry=registry, env=token_env))
+            return
+        raise click.ClickException(
+            _("{env} is not set. Set it in your .env file or pass it as an environment variable.", env=token_env),
+        )
+    if not username:
+        raise click.ClickException(
+            _("{env} is not set. Set it in your .env file.", env=username_env),
+        )
+    docker_login(registry, username, token, suppress_failure=suppress_failure)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/generate_badges.py

@@ -5,12 +5,21 @@ Runs pytest-cov, doc-coverage, lint checks, and version extraction,
 then writes SVG badge files that can be served as static files from
 the Gitea raw file API.
 
+The repo root is resolved from ``GITHUB_WORKSPACE`` or ``os.getcwd()``,
+so this module works correctly both when run from a source checkout
+and when devx is installed as a pip package in CI.
+
+The package name and coverage target are auto-detected from the
+``src/`` directory structure, making this module reusable across
+all oblachno-oss repos without per-repo configuration.
+
 Usage:
     python3 -m devx.tools.generate_badges --output-dir .badges/
 """
 
 from __future__ import annotations
 
+import os
 import re
 import subprocess  # nosec B404
 import sys
@@ -18,8 +27,9 @@ from pathlib import Path
 
 import click
 
-REPO_ROOT = Path(__file__).resolve().parents[4]
+from devx.i18n import _
 
+# Coverage regex matches "TOTAL ... NN%" or "TOTAL ... NN.NN%"
 _COVERAGE_RE = re.compile(r"TOTAL.*?(\d+(?:\.\d+)?)%")
 _PASSED_RE = re.compile(r"(\d+) passed")
 _DOC_COVERAGE_RE = re.compile(r"Doc coverage:\s+\d+/\d+\s+\((\d+)%")
@@ -37,18 +47,59 @@ COLOR_HEX: dict[str, str] = {
 }
 
 
-def _find_package_init() -> Path | None:
-    """Find the first package __init__.py under src/ that defines __version__."""
-    src_dir = REPO_ROOT / "src"
-    if not src_dir.exists():
+def resolve_repo_root() -> Path:
+    """Resolve the repository root directory.
+
+    Uses ``GITHUB_WORKSPACE`` env var (set by Gitea Actions) or
+    falls back to ``os.getcwd()``.  This ensures the correct repo
+    root is used even when devx is installed as a pip package.
+    """
+    workspace = os.environ.get("GITHUB_WORKSPACE")
+    if workspace:
+        path = Path(workspace)
+        if path.is_dir():
+            return path
+    return Path.cwd()
+
+
+def detect_package_name(repo_root: Path) -> str | None:
+    """Auto-detect the Python package name from ``src/`` directory.
+
+    Looks for the first subdirectory under ``src/`` that contains
+    an ``__init__.py`` file with ``__version__``.
+
+    Returns the package directory name (e.g., ``devx``,
+    ``gitea_runner_manager``) or ``None`` if no package is found.
+    """
+    src_dir = repo_root / "src"
+    if not src_dir.is_dir():
         return None
-    for init_file in src_dir.rglob("__init__.py"):
-        try:
-            content = init_file.read_text()
-        except OSError:
+    for entry in sorted(src_dir.iterdir()):
+        if not entry.is_dir():
             continue
-        if "__version__" in content:
-            return init_file
+        init_file = entry / "__init__.py"
+        if init_file.exists():
+            return entry.name
+    return None
+
+
+def detect_coverage_target(repo_root: Path) -> str | None:
+    """Auto-detect the pytest-cov target from pyproject.toml.
+
+    Parses ``addopts`` in ``[tool.pytest.ini_options]`` for
+    ``--cov=src/<package>``.  Falls back to ``src/<package>`` if
+    the package is detected but no explicit cov target is found.
+    """
+    pyproject = repo_root / "pyproject.toml"
+    if pyproject.exists():
+        content = pyproject.read_text()
+        match = re.search(r"--cov=(\S+)", content)
+        if match:
+            return match.group(1)
+    # Fallback: derive from package name
+    pkg = detect_package_name(repo_root)
+    if pkg:
+        return f"src/{pkg}"
     return None
 
 
@@ -57,14 +108,15 @@ def _xml_escape(text: str) -> str:
     return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")
 
 
-def run_command(cmd: list[str]) -> tuple[int, str, str]:
+def run_command(cmd: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
     """Run a command and return (returncode, stdout, stderr)."""
+    root = str(cwd or resolve_repo_root())
     result = subprocess.run(  # nosec B603
         cmd,
         capture_output=True,
         text=True,
         check=False,
-        cwd=str(REPO_ROOT),
+        cwd=root,
     )
     return result.returncode, result.stdout, result.stderr
 
@@ -139,15 +191,27 @@ def extract_doc_coverage(output: str) -> int | None:
     return None
 
 
-def read_version() -> str:
-    """Read __version__ from the package __init__.py."""
-    init_file = _find_package_init()
-    if init_file is None:
+def read_version(repo_root: Path) -> str:
+    """Read __version__ from the package __init__.py under src/.
+
+    Auto-detects the package directory and reads ``__version__``
+    from its ``__init__.py``.
+    """
+    pkg = detect_package_name(repo_root)
+    if pkg is None:
+        click.echo(_("  WARNING: No Python package found under src/ — version badge will show 'unknown'"))
+        return "unknown"
+    init_file = repo_root / "src" / pkg / "__init__.py"
+    if not init_file.exists():
+        click.echo(_("  WARNING: {init_file} not found — version badge will show 'unknown'", init_file=init_file))
         return "unknown"
     content = init_file.read_text()
     match = re.search(r'__version__\s*=\s*["\']([^"\']+)["\']', content)
     if match:
         return match.group(1)
+    click.echo(
+        _("  WARNING: No __version__ found in {init_file} — version badge will show 'unknown'", init_file=init_file)
+    )
     return "unknown"
 
 
@@ -179,65 +243,170 @@ def doc_coverage_color(pct: int) -> str:
     return "orange"
 
 
-def generate_badges(output_dir: Path) -> dict[str, dict[str, str | int]]:
-    """Generate all badge SVG files and return badge data as a dict."""
-    badges: dict[str, dict[str, str | int]] = {}
+def detect_testpaths(repo_root: Path) -> list[str]:
+    """Detect test paths from pyproject.toml or filesystem.
 
-    # 1. Code coverage + test count (single pytest-cov run)
-    rc, stdout, stderr = run_command(
-        [
-            sys.executable,
-            "-m",
-            "pytest",
-            "tests/",
-            "-v",
-            "--cov=src/devx",
-            "--cov-report=term-missing",
-            "--cov-fail-under=0",
-        ]
-    )
+    Parses ``testpaths`` in ``[tool.pytest.ini_options]`` from
+    pyproject.toml.  Falls back to ``["tests"]`` if the tests/
+    directory exists.  Returns an empty list if no test paths
+    are found (pytest will use its own defaults).
+    """
+    pyproject = repo_root / "pyproject.toml"
+    if pyproject.exists():
+        content = pyproject.read_text()
+        # Match: testpaths = ["dir1", "dir2"]
+        match = re.search(r"testpaths\s*=\s*\[([^\]]+)\]", content)
+        if match:
+            paths = re.findall(r'["\']([^"\']+)["\']', match.group(1))
+            resolved = []
+            for p in paths:
+                p = p.strip()
+                if (repo_root / p).exists():
+                    resolved.append(p)
+            if resolved:
+                return resolved
+
+    # Fallback: tests/ directory
+    tests_dir = repo_root / "tests"
+    if tests_dir.is_dir():
+        return ["tests"]
+    return []
+
+
+def collect_coverage_and_tests(repo_root: Path) -> tuple[dict[str, str | int], dict[str, str | int]]:
+    """Run pytest-cov and collect coverage + test count badges.
+
+    Returns (coverage_badge, tests_badge).  If pytest is not
+    available or no tests are found, returns 'unknown' badges
+    with a clear warning explaining the failure.
+    """
+    cov_target = detect_coverage_target(repo_root)
+    if cov_target is None:
+        click.echo(_("  WARNING: No coverage target detected (no src/ package, no --cov in pyproject.toml)"))
+        return make_badge("coverage", "unknown", "lightgrey"), make_badge("tests", "unknown", "lightgrey")
+
+    testpaths = detect_testpaths(repo_root)
+    click.echo(_("  Test paths: {testpaths}", testpaths=testpaths or "(pytest defaults)"))
+
+    cmd = [
+        sys.executable,
+        "-m",
+        "pytest",
+        *testpaths,
+        "--cov",
+        cov_target,
+        "--cov-report=term-missing",
+        "--cov-fail-under=0",
+        "-q",
+    ]
+    rc, stdout, stderr = run_command(cmd, cwd=repo_root)
     combined = stdout + "\n" + stderr
 
     coverage = extract_coverage(combined)
     if coverage is not None:
-        badges["coverage"] = make_badge("coverage", f"{coverage:.0f}%", coverage_color(coverage))
+        cov_badge = make_badge("coverage", f"{coverage:.0f}%", coverage_color(coverage))
     else:
-        badges["coverage"] = make_badge("coverage", "unknown", "red")
+        click.echo(_("  WARNING: Could not extract coverage from pytest output (rc={rc})", rc=rc))
+        click.echo(_("    pytest stdout (last 300 chars): {stdout}", stdout=stdout.strip()[-300:]))
+        click.echo(_("    pytest stderr (last 300 chars): {stderr}", stderr=stderr.strip()[-300:]))
+        cov_badge = make_badge("coverage", "unknown", "red")
 
     test_count = extract_test_count(combined)
     if test_count is not None:
-        badges["tests"] = make_badge("tests", f"{test_count} passing", "brightgreen" if rc == 0 else "red")
+        tests_badge = make_badge("tests", f"{test_count} passing", "brightgreen" if rc == 0 else "red")
     else:
-        badges["tests"] = make_badge("tests", "unknown", "red")
+        click.echo(_("  WARNING: Could not extract test count from pytest output (rc={rc})", rc=rc))
+        click.echo(_("    pytest stdout (last 300 chars): {stdout}", stdout=stdout.strip()[-300:]))
+        click.echo(_("    pytest stderr (last 300 chars): {stderr}", stderr=stderr.strip()[-300:]))
+        tests_badge = make_badge("tests", "unknown", "red")
 
-    # 2. Documentation coverage
-    rc, stdout, _ = run_command(
-        [
-            sys.executable,
-            "-m",
-            "devx.ci.doc_coverage",
-        ]
+    return cov_badge, tests_badge
+
+
+def collect_doc_coverage(repo_root: Path) -> dict[str, str | int]:
+    """Run doc_coverage and collect the docs badge."""
+    rc, stdout, stderr = run_command(
+        [sys.executable, "-m", "devx.ci.doc_coverage"],
+        cwd=repo_root,
     )
     doc_pct = extract_doc_coverage(stdout)
     if doc_pct is not None:
-        badges["docs"] = make_badge("docs", f"{doc_pct}%", doc_coverage_color(doc_pct))
-    else:
-        badges["docs"] = make_badge("docs", "unknown", "red")
+        return make_badge("docs", f"{doc_pct}%", doc_coverage_color(doc_pct))
+    click.echo(_("  WARNING: Could not extract doc coverage (rc={rc})", rc=rc))
+    click.echo(_("    stderr: {stderr}", stderr=stderr.strip()[:200]))
+    return make_badge("docs", "unknown", "red")
 
-    # 3. Code quality (ruff + pyright + bandit all pass)
-    lint_rc, _, _ = run_command([sys.executable, "-m", "ruff", "check", "src/", "tests/"])
-    format_rc, _, _ = run_command([sys.executable, "-m", "ruff", "format", "--check", "src/", "tests/"])
-    type_rc, _, _ = run_command([sys.executable, "-m", "pyright"])
-    bandit_rc, _, _ = run_command([sys.executable, "-m", "bandit", "-r", "src/"])
 
-    all_pass = all(rc == 0 for rc in [lint_rc, format_rc, type_rc, bandit_rc])
-    badges["quality"] = make_badge("code quality", "A" if all_pass else "F", "brightgreen" if all_pass else "red")
+def collect_quality(repo_root: Path) -> dict[str, str | int]:
+    """Run lint checks and collect the quality badge.
+
+    Runs ruff check, ruff format --check, pyright, and bandit.
+    If any tool is not installed, it is skipped with a warning.
+    """
+    results: list[bool] = []
+    tool_names: list[str] = []
+
+    for cmd, name in [
+        ([sys.executable, "-m", "ruff", "check", "src/", "tests/"], "ruff check"),
+        ([sys.executable, "-m", "ruff", "format", "--check", "src/", "tests/"], "ruff format"),
+        ([sys.executable, "-m", "pyright"], "pyright"),
+        ([sys.executable, "-m", "bandit", "-r", "src/"], "bandit"),
+    ]:
+        rc, _stdout, stderr = run_command(cmd, cwd=repo_root)
+        if rc == 0:
+            results.append(True)
+            tool_names.append(f"{name}: pass")
+        else:
+            results.append(False)
+            # Distinguish "tool not installed" from "tool found issues"
+            if "No module named" in stderr or "not found" in stderr.lower():
+                click.echo(_("  WARNING: {name} not installed — skipping (counted as pass)", name=name))
+                results[-1] = True
+                tool_names.append(f"{name}: not installed (skipped)")
+            else:
+                tool_names.append(f"{name}: FAIL")
+                click.echo(_("  WARNING: {name} failed (rc={rc})", name=name, rc=rc))
+                click.echo(_("    stderr: {stderr}", stderr=stderr.strip()[:200]))
+
+    all_pass = all(results)
+    click.echo(_("  Quality checks: {checks}", checks=", ".join(tool_names)))
+    return make_badge("code quality", "A" if all_pass else "F", "brightgreen" if all_pass else "red")
+
+
+def generate_badges(output_dir: Path, repo_root: Path | None = None) -> dict[str, dict[str, str | int]]:
+    """Generate all badge SVG files and return badge data as a dict.
+
+    Args:
+        output_dir: Directory to write SVG files.
+        repo_root: Repository root (auto-detected if None).
+    """
+    root = repo_root or resolve_repo_root()
+    click.echo(_("  Repo root: {root}", root=root))
+    pkg = detect_package_name(root)
+    click.echo(_("  Package: {pkg}", pkg=pkg or "none"))
+
+    badges: dict[str, dict[str, str | int]] = {}
+
+    # 1. Code coverage + test count (single pytest-cov run)
+    click.echo(_("  Collecting coverage and tests..."))
+    cov_badge, tests_badge = collect_coverage_and_tests(root)
+    badges["coverage"] = cov_badge
+    badges["tests"] = tests_badge
+
+    # 2. Documentation coverage
+    click.echo(_("  Collecting doc coverage..."))
+    badges["docs"] = collect_doc_coverage(root)
+
+    # 3. Code quality (ruff + pyright + bandit)
+    click.echo(_("  Collecting code quality..."))
+    badges["quality"] = collect_quality(root)
 
     # 4. Version
-    version = read_version()
+    click.echo(_("  Collecting version..."))
+    version = read_version(root)
     badges["version"] = make_badge("version", f"v{version}", "blue")
 
-    # 5. Python version (static but nice)
+    # 5. Python version (static)
     badges["python"] = make_badge("python", "3.12", "blue")
 
     # Write SVG files
@@ -246,7 +415,7 @@ def generate_badges(output_dir: Path) -> dict[str, dict[str, str | int]]:
         svg = render_svg(str(badge["label"]), str(badge["message"]), str(badge["color"]))
         path = output_dir / f"{name}.svg"
         path.write_text(svg)
-        click.echo(f"  Generated: {path}")
+        click.echo(_("  Generated: {path}", path=path))
 
     return badges
 
@@ -254,17 +423,31 @@ def generate_badges(output_dir: Path) -> dict[str, dict[str, str | int]]:
 @click.command()
 @click.option(
     "--output-dir",
-    default=str(REPO_ROOT / ".badges"),
+    default=".badges",
     help="Directory to write badge SVG files.",
 )
-def cli(output_dir: str) -> None:
+@click.option(
+    "--repo-root",
+    default=None,
+    help="Repository root (auto-detected if not specified).",
+)
+def cli(output_dir: str, repo_root: str | None) -> None:
     """Generate self-contained SVG badge files from project metrics."""
     out = Path(output_dir)
-    click.echo(f"Generating badges in {out}...")
-    badges = generate_badges(out)
-    click.echo(f"\nGenerated {len(badges)} badges:")
+    root = Path(repo_root) if repo_root else None
+    click.echo(_("Generating badges in {out}...", out=out))
+    badges = generate_badges(out, repo_root=root)
+    click.echo(_("\nGenerated {count} badges:", count=len(badges)))
     for name, badge in badges.items():
-        click.echo(f"  {name}: {badge['label']}={badge['message']} ({badge['color']})")
+        click.echo(
+            _(
+                "  {name}: {label}={message} ({color})",
+                name=name,
+                label=badge["label"],
+                message=badge["message"],
+                color=badge["color"],
+            )
+        )
 
 
 if __name__ == "__main__":  # pragma: no cover

src/devx/tools/generate_cliff_config.py

@@ -109,7 +109,7 @@ def _generate(prefix: str) -> str:
 @click.option(
     "--prefix",
     default=TASK_PREFIX,
-    help="Task ID prefix for commit preprocessor (default: DEVX_TASK_PREFIX env var or 'DEVX').",
+    help="Task ID prefix for commit preprocessor (default: from [tool.devx] task_prefix in pyproject.toml).",
 )
 @click.option(
     "--output",

src/devx/tools/install_checkmake.py

@@ -7,7 +7,6 @@ pre-built Linux binary from the official GitHub releases.
 
 from __future__ import annotations
 
-import platform
 import shutil
 import subprocess  # nosec B404
 import urllib.request
@@ -15,6 +14,8 @@ from pathlib import Path
 
 import click
 
+from devx.tools._shared import arch_string
+
 CHECKMAKE_VERSION = "0.3.2"
 RELEASE_URL_TEMPLATE = (
     "https://github.com/checkmake/checkmake/releases/download/"
@@ -23,18 +24,11 @@ RELEASE_URL_TEMPLATE = (
 TARGET_PATH = Path("/usr/local/bin/checkmake")
 
 
-def _arch() -> str:
-    """Return the architecture string used by checkmake releases."""
-    machine = platform.machine().lower()
-    if machine in {"x86_64", "amd64"}:
-        return "amd64"
-    if machine in {"aarch64", "arm64"}:
-        return "arm64"
-    raise click.ClickException(f"Unsupported architecture: {machine}")
-
-
 def _install_with_go() -> bool:
-    """Install checkmake using go install if Go is available."""
+    """Install checkmake using go install if Go is available.
+
+    Returns True if the installation succeeded, False if Go is not installed.
+    """
     go_bin = shutil.which("go")
     if go_bin is None:
         return False
@@ -51,12 +45,13 @@ def _install_with_go() -> bool:
 
 def _download_binary() -> None:
     """Download the prebuilt checkmake binary for the current architecture."""
-    url = RELEASE_URL_TEMPLATE.format(arch=_arch())
+    url = RELEASE_URL_TEMPLATE.format(arch=arch_string())
     urllib.request.urlretrieve(url, TARGET_PATH)  # nosec B310
     TARGET_PATH.chmod(0o755)
 
 
-def main() -> None:
+@click.command()
+def cli() -> None:
     """Install checkmake if not already present."""
     if shutil.which("checkmake") is not None:
         return
@@ -66,4 +61,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":  # pragma: no cover
-    main()  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/install_tools.py

@@ -6,6 +6,7 @@ Handles installation of:
 - git-cliff (changelog generator)
 - act_runner (Gitea Actions local runner, optional)
 - tea (Gitea CLI — official command-line tool for Gitea API operations)
+- hadolint (Dockerfile linter)
 
 Each tool is installed to ``~/.local/bin`` if not already on PATH.
 Idempotent: skips tools that are already available.
@@ -39,15 +40,16 @@ ACT_RUNNER_VERSION = "0.2.11"
 
 TEA_VERSION = "0.14.1"
 
+HADOLINT_VERSION = "2.12.0"
+
+TOFU_VERSION = "1.12.3"
+
 
 def _arch() -> str:
-    """Return the architecture string used by release assets."""
-    machine = platform.machine().lower()
-    if machine in {"x86_64", "amd64"}:
-        return "amd64"
-    if machine in {"aarch64", "arm64"}:
-        return "arm64"
-    raise click.ClickException(f"Unsupported architecture: {machine}")
+    """Return the architecture string used by release assets (delegates to shared utility)."""
+    from devx.tools._shared import arch_string
+
+    return arch_string()
 
 
 def _ensure_target_dir() -> Path:
@@ -161,7 +163,40 @@ def install_tea() -> bool:
     return True
 
 
-TOOL_NAMES = ["actionlint", "git-cliff", "act_runner", "tea"]
+def install_hadolint() -> bool:
+    """Install hadolint if not already present. Returns True if installed/skipped."""
+    if _is_installed("hadolint"):
+        click.echo("hadolint: already installed")
+        return True
+    machine = platform.machine().lower()
+    arch = "x86_64" if machine in {"x86_64", "amd64"} else "arm64"
+    url = f"https://github.com/hadolint/hadolint/releases/download/v{HADOLINT_VERSION}/hadolint-Linux-{arch}"
+    dest = _download_binary(url, "hadolint")
+    click.echo(f"hadolint: installed to {dest}")
+    return True
+
+
+def install_tofu() -> bool:
+    """Install OpenTofu if not already present. Returns True if installed/skipped.
+
+    Downloads the official release tarball from GitHub and extracts the
+    ``tofu`` binary to ``~/.local/bin``.
+    """
+    if _is_installed("tofu"):
+        click.echo("tofu: already installed")
+        return True
+    arch = _arch()
+    os_name = platform.system().lower()
+    url = (
+        f"https://github.com/opentofu/opentofu/releases/download/"
+        f"v{TOFU_VERSION}/tofu_{TOFU_VERSION}_{os_name}_{arch}.tar.gz"
+    )
+    dest = _download_and_extract_tarball(url, "tofu")
+    click.echo(f"tofu: installed to {dest}")
+    return True
+
+
+TOOL_NAMES = ["actionlint", "git-cliff", "act_runner", "tea", "hadolint", "tofu"]
 
 
 def _install_tool(name: str) -> bool:
@@ -174,6 +209,10 @@ def _install_tool(name: str) -> bool:
         return install_act_runner()
     if name == "tea":
         return install_tea()
+    if name == "hadolint":
+        return install_hadolint()
+    if name == "tofu":
+        return install_tofu()
     raise click.ClickException(f"Unknown tool: {name}")
 
 

src/devx/tools/pr_label.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Add a label to a pull request (idempotent).
+
+Commonly used to add the ``ready-to-merge`` label after CI passes and
+review is complete. The operation is idempotent — if the label is already
+attached, it succeeds without error.
+
+Usage::
+
+    # Add ready-to-merge to PR #42
+    python -m devx.tools.pr_label --pr 42 --label ready-to-merge
+
+    # Add label to current branch's PR
+    python -m devx.tools.pr_label --label ready-to-merge
+
+    # Add multiple labels
+    python -m devx.tools.pr_label --pr 42 --label ready-to-merge --label reviewed
+
+The repository is auto-detected from ``DEVX_REPO_OWNER`` /
+``DEVX_REPO_NAME`` or ``GITHUB_REPOSITORY`` environment variables.
+"""
+
+from __future__ import annotations
+
+import os
+
+import click
+from dotenv import load_dotenv
+
+from devx.api_clients import GiteaClient
+from devx.config import GITEA_API_URL, REPO_OWNER
+from devx.i18n import _
+from devx.tools.create_pr import get_repo_name
+from devx.tools.pr_status import _get_current_branch_pr
+
+load_dotenv()
+
+
+@click.command()
+@click.option("--pr", "pr_number", type=int, default=None, help="PR number (default: auto-detect from current branch).")
+@click.option("--label", "labels", multiple=True, required=True, help="Label name(s) to add (can be repeated).")
+@click.option("--owner", default=None, help="Repository owner (default: DEVX_REPO_OWNER).")
+@click.option("--repo", default=None, help="Repository name (default: DEVX_REPO_NAME or GITHUB_REPOSITORY).")
+def cli(
+    pr_number: int | None,
+    labels: tuple[str, ...],
+    owner: str | None,
+    repo: str | None,
+) -> None:
+    """Add one or more labels to a pull request (idempotent)."""
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    if not token:
+        raise click.ClickException(_("CI_GITEA_TOKEN is not set."))
+
+    repo_owner = owner or REPO_OWNER
+    if not repo_owner:
+        raise click.ClickException(_("Repository owner not set. Use --owner or DEVX_REPO_OWNER env var."))
+    repo_name = repo or get_repo_name()
+
+    client = GiteaClient(GITEA_API_URL, token, repo_owner, repo_name)
+
+    if pr_number is None:
+        pr_number = _get_current_branch_pr(client)
+
+    label_list = list(labels)
+    existing = client.get_pr_label_names(pr_number)
+    to_add = [lbl for lbl in label_list if lbl not in existing]
+    already = [lbl for lbl in label_list if lbl in existing]
+
+    if already:
+        for lbl in already:
+            click.echo(_("Label '{label}' already on PR #{pr}.", label=lbl, pr=pr_number))
+
+    if to_add:
+        client.add_pr_label(pr_number, to_add)
+        for lbl in to_add:
+            click.echo(_("Added label '{label}' to PR #{pr}.", label=lbl, pr=pr_number))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/pr_logs.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""Fetch logs for failed CI jobs on a pull request.
+
+Lists CI jobs for the latest workflow run of a PR's branch, then fetches
+and prints the logs of any failed jobs. Useful for diagnosing CI failures
+without navigating the web UI.
+
+Usage::
+
+    # Show failed job logs for PR #42
+    python -m devx.tools.pr_logs --pr 42
+
+    # Show failed job logs for current branch's PR
+    python -m devx.tools.pr_logs
+
+    # Show logs for a specific job (by name)
+    python -m devx.tools.pr_logs --pr 42 --job quality
+
+    # Show last N lines of each failed job's logs
+    python -m devx.tools.pr_logs --pr 42 --tail 50
+
+The repository is auto-detected from ``DEVX_REPO_OWNER`` /
+``DEVX_REPO_NAME`` or ``GITHUB_REPOSITORY`` environment variables.
+"""
+
+from __future__ import annotations
+
+import os
+
+import click
+from dotenv import load_dotenv
+
+from devx.api_clients import APIError, GiteaClient
+from devx.config import GITEA_API_URL, REPO_OWNER
+from devx.i18n import _
+from devx.tools.create_pr import get_repo_name
+from devx.tools.pr_status import _get_current_branch_pr
+
+load_dotenv()
+
+
+def _get_pr_sha(client: GiteaClient, pr_number: int) -> str:
+    """Fetch the head SHA of a PR."""
+    pr = client.get_pr(pr_number)
+    return pr.get("head", {}).get("sha", "")
+
+
+def _find_latest_run_by_sha(client: GiteaClient, sha: str) -> dict | None:
+    """Find the latest workflow run for a commit SHA.
+
+    Gitea Actions API doesn't set head_branch for pull_request events,
+    so we filter by head_sha instead.
+    """
+    data = client.list_action_runs(limit=50)
+    for run in data.get("workflow_runs", []):
+        if run.get("head_sha", "").startswith(sha):
+            return run
+    return None
+
+
+def _find_failed_jobs(jobs: list[dict]) -> list[dict]:
+    """Return jobs with conclusion 'failure'."""
+    return [j for j in jobs if j.get("conclusion") == "failure"]
+
+
+def _find_job_by_name(jobs: list[dict], name: str) -> dict | None:
+    """Find a job by name (case-insensitive partial match)."""
+    name_lower = name.lower()
+    for j in jobs:
+        if name_lower in j.get("name", "").lower():
+            return j
+    return None
+
+
+def _print_job_summary(jobs: list[dict]) -> None:
+    """Print a summary table of all jobs and their status."""
+    for j in jobs:
+        name = j.get("name", "?")
+        conclusion = j.get("conclusion", "pending")
+        status = j.get("status", "?")
+        symbol = "[FAIL]" if conclusion == "failure" else "[OK]" if conclusion == "success" else f"[{conclusion}]"
+        click.echo(f"  {symbol} {name} (status: {status}, conclusion: {conclusion})")
+
+
+def _print_failed_steps(job: dict) -> list[int]:
+    """Print failed steps for a job. Returns list of failed step numbers."""
+    failed_steps = []
+    for step in job.get("steps", []):
+        if step.get("conclusion") == "failure":
+            name = step.get("name", "?")
+            num = step.get("number", "?")
+            click.echo(f"    FAILED step #{num}: {name}")
+            failed_steps.append(num)
+    return failed_steps
+
+
+def _print_logs(client: GiteaClient, job_id: int, tail: int = 0) -> None:
+    """Fetch and print logs for a job. If tail > 0, print only last N lines."""
+    try:
+        logs = client.get_action_job_logs(job_id)
+    except APIError as e:
+        click.echo(_("    Could not fetch logs: {error}", error=str(e)))
+        return
+
+    if tail > 0:
+        lines = logs.strip().split("\n")
+        if len(lines) > tail:
+            click.echo(f"    ... (showing last {tail} of {len(lines)} lines)")
+            logs = "\n".join(lines[-tail:])
+
+    for line in logs.split("\n"):
+        click.echo(f"    {line}")
+
+
+@click.command()
+@click.option("--pr", "pr_number", type=int, default=None, help="PR number (default: auto-detect from current branch).")
+@click.option("--job", default=None, help="Job name to show logs for (partial match, case-insensitive).")
+@click.option("--tail", type=int, default=80, show_default=True, help="Show last N lines of logs (0 = all).")
+@click.option("--owner", default=None, help="Repository owner (default: DEVX_REPO_OWNER).")
+@click.option("--repo", default=None, help="Repository name (default: DEVX_REPO_NAME or GITHUB_REPOSITORY).")
+def cli(
+    pr_number: int | None,
+    job: str | None,
+    tail: int,
+    owner: str | None,
+    repo: str | None,
+) -> None:
+    """Fetch logs for failed CI jobs on a pull request."""
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    if not token:
+        raise click.ClickException(_("CI_GITEA_TOKEN is not set."))
+
+    repo_owner = owner or REPO_OWNER
+    if not repo_owner:
+        raise click.ClickException(_("Repository owner not set. Use --owner or DEVX_REPO_OWNER env var."))
+    repo_name = repo or get_repo_name()
+
+    client = GiteaClient(GITEA_API_URL, token, repo_owner, repo_name)
+
+    if pr_number is None:
+        pr_number = _get_current_branch_pr(client)
+        click.echo(_("Fetching logs for PR #{pr_number}...", pr_number=pr_number))
+
+    sha = _get_pr_sha(client, pr_number)
+    if not sha:
+        raise click.ClickException(_("Could not determine head SHA for PR #{pr_number}.", pr_number=pr_number))
+
+    run = _find_latest_run_by_sha(client, sha)
+    if not run:
+        raise click.ClickException(_("No workflow runs found for SHA {sha}.", sha=sha[:8]))
+
+    run_id = run.get("id", 0)
+    run_status = run.get("status", "?")
+    click.echo(_("Latest run: #{run_id} (status: {status})", run_id=run_id, status=run_status))
+    click.echo("")
+
+    jobs = client.get_action_run_jobs(run_id)
+    if not jobs:
+        click.echo(_("No jobs found for run #{run_id}.", run_id=run_id))
+        return
+
+    _print_job_summary(jobs)
+    click.echo("")
+
+    if job:
+        target = _find_job_by_name(jobs, job)
+        if not target:
+            raise click.ClickException(_("No job matching '{job}' found.", job=job))
+        click.echo(f"Logs for job '{target.get('name', '?')}' (id={target.get('id')}):")
+        _print_failed_steps(target)
+        click.echo("")
+        _print_logs(client, target["id"], tail)
+    else:
+        failed = _find_failed_jobs(jobs)
+        if not failed:
+            click.echo(_("No failed jobs."))
+            return
+        for fj in failed:
+            click.echo(f"Logs for failed job '{fj.get('name', '?')}' (id={fj.get('id')}):")
+            _print_failed_steps(fj)
+            click.echo("")
+            _print_logs(client, fj["id"], tail)
+            click.echo("")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/pr_rebase.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Rebase a pull request's head branch onto master via Gitea API.
+
+Uses the Gitea ``POST /pulls/{index}/update?style=rebase`` endpoint to
+rebase the PR's head branch server-side. This triggers a new
+``pull_request synchronize`` event, which starts a new CI run.
+
+This is useful when:
+  - You don't have the branch checked out locally
+  - You want to rebase a PR from another machine
+  - You want to trigger the auto-merge retry without local git operations
+
+Usage::
+
+    # Rebase PR #42
+    python -m devx.tools.pr_rebase --pr 42
+
+    # Rebase current branch's PR (auto-detected)
+    python -m devx.tools.pr_rebase
+
+The repository is auto-detected from ``DEVX_REPO_OWNER`` /
+``DEVX_REPO_NAME`` or ``GITHUB_REPOSITORY`` environment variables.
+"""
+
+from __future__ import annotations
+
+import os
+
+import click
+from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
+
+from devx.api_clients import APIError, GiteaClient
+from devx.config import GITEA_API_URL
+from devx.i18n import _
+from devx.tools._shared import detect_pr_number
+
+
+@click.command()
+@click.option("--pr", type=int, help="PR number (auto-detected if omitted).")
+def main(pr: int | None) -> None:
+    """Rebase a pull request's head branch onto master via Gitea API."""
+    load_dotenv()
+
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    if not token:
+        raise click.ClickException(_("CI_GITEA_TOKEN is not set. Add it to .env or export it."))
+
+    pr_num = pr or detect_pr_number()
+    if not pr_num:
+        raise click.ClickException(
+            _(
+                "Could not detect PR number. Use --pr to specify it explicitly,\n"
+                "or run this command from a branch with an open PR.",
+            )
+        )
+
+    owner = os.environ.get("DEVX_REPO_OWNER", "")
+    repo = os.environ.get("DEVX_REPO_NAME", "")
+    if not owner or not repo:
+        github_repo = os.environ.get("GITHUB_REPOSITORY", "")
+        if "/" in github_repo:
+            owner, repo = github_repo.split("/", 1)
+
+    if not owner or not repo:
+        raise click.ClickException(
+            _(
+                "Could not determine repository. Set DEVX_REPO_OWNER and DEVX_REPO_NAME\n"
+                "or GITHUB_REPOSITORY environment variables.",
+            )
+        )
+
+    client = GiteaClient(GITEA_API_URL, token, owner, repo)
+
+    click.echo(_("Rebasing PR #{pr} via Gitea API...", pr=pr_num))
+    try:
+        client.update_pr_branch(pr_num, style="rebase")
+    except APIError as e:
+        raise click.ClickException(
+            _(
+                "Rebase failed with HTTP {status}: {message}",
+                status=e.status,
+                message=e.message,
+            )
+        ) from None
+
+    click.echo(
+        _(
+            "PR #{pr} rebased successfully. A new CI run will start automatically.\n"
+            "If auto-merge is enabled (ready-to-merge label), the next CI run\n"
+            "will attempt to merge this PR.",
+            pr=pr_num,
+        )
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/pr_status.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Check CI status for a pull request or commit.
+
+Displays the status of all CI checks for a PR (or a specific commit SHA).
+Optionally polls until all checks complete (``--wait``).
+
+Usage::
+
+    # Check status of PR #42
+    python -m devx.tools.pr_status --pr 42
+
+    # Check status of current branch's PR
+    python -m devx.tools.pr_status
+
+    # Wait for all checks to complete (timeout 600s)
+    python -m devx.tools.pr_status --pr 42 --wait --timeout 600
+
+    # Check a specific commit SHA
+    python -m devx.tools.pr_status --sha abc1234
+
+The repository is auto-detected from ``DEVX_REPO_OWNER`` /
+``DEVX_REPO_NAME`` or ``GITHUB_REPOSITORY`` environment variables.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess  # nosec B404
+import time
+
+import click
+from dotenv import load_dotenv
+
+from devx.api_clients import GiteaClient
+from devx.config import GITEA_API_URL, REPO_OWNER
+from devx.i18n import _
+from devx.tools.create_pr import get_repo_name
+
+load_dotenv()
+
+# Status symbols for terminal output
+_STATUS_SYMBOLS = {
+    "success": "[OK]",
+    "failure": "[FAIL]",
+    "error": "[FAIL]",
+    "pending": "[..]",
+    "skipped": "[SKIP]",
+    "none": "[--]",
+}
+
+
+def _get_symbol(status: str) -> str:
+    return _STATUS_SYMBOLS.get(status, f"[{status}]")
+
+
+def _get_pr_sha(client: GiteaClient, pr_number: int) -> str:
+    """Fetch the head SHA of a PR."""
+    pr = client.get_pr(pr_number)
+    return pr.get("head", {}).get("sha", "")
+
+
+def _get_current_branch_pr(client: GiteaClient) -> int:
+    """Find the open PR for the current git branch."""
+    result = subprocess.run(  # nosec
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise click.ClickException(_("Could not detect current branch: {error}", error=result.stderr.strip()))
+    branch = result.stdout.strip()
+
+    prs = client.list_prs(state="open")
+    for pr in prs:
+        if pr.get("head", {}).get("ref") == branch:
+            return int(pr["number"])
+    raise click.ClickException(_("No open PR found for branch '{branch}'.", branch=branch))
+
+
+def print_status(client: GiteaClient, sha: str) -> str:
+    """Print CI check statuses for a commit SHA. Returns the overall state."""
+    statuses = client.get_commit_status(sha)
+    if not statuses:
+        click.echo(_("No CI checks found for commit {sha}.", sha=sha[:8]))
+        return "none"
+
+    overall = "success"
+    for s in statuses:
+        context = s.get("context", "?")
+        status = s.get("status", "pending")
+        symbol = _get_symbol(status)
+        click.echo(f"  {symbol} {context}")
+        if status in ("failure", "error"):
+            overall = "failure"
+        elif status == "pending" and overall != "failure":
+            overall = "pending"
+        elif status == "skipped" and overall == "success":
+            overall = "success"
+
+    click.echo(f"\n  Overall: {_get_symbol(overall)} {overall}")
+    return overall
+
+
+def wait_for_completion(
+    client: GiteaClient,
+    sha: str,
+    timeout: int = 600,
+    interval: int = 30,
+) -> str:
+    """Poll CI status until all checks complete or timeout. Returns final state."""
+    click.echo(_("Waiting for CI checks to complete (timeout: {timeout}s)...", timeout=timeout))
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        state = print_status(client, sha)
+        if state in ("success", "failure", "error", "none"):
+            return state
+        click.echo(f"  ...still pending, retrying in {interval}s\n")
+        time.sleep(interval)
+    click.echo(_("Timeout reached after {timeout}s.", timeout=timeout))
+    return "pending"
+
+
+@click.command()
+@click.option("--pr", "pr_number", type=int, default=None, help="PR number (default: auto-detect from current branch).")
+@click.option("--sha", default=None, help="Commit SHA to check (alternative to --pr).")
+@click.option("--wait", "do_wait", is_flag=True, help="Poll until all checks complete.")
+@click.option("--timeout", type=int, default=600, show_default=True, help="Wait timeout in seconds.")
+@click.option("--interval", type=int, default=30, show_default=True, help="Poll interval in seconds.")
+@click.option("--owner", default=None, help="Repository owner (default: DEVX_REPO_OWNER).")
+@click.option("--repo", default=None, help="Repository name (default: DEVX_REPO_NAME or GITHUB_REPOSITORY).")
+def cli(
+    pr_number: int | None,
+    sha: str | None,
+    do_wait: bool,
+    timeout: int,
+    interval: int,
+    owner: str | None,
+    repo: str | None,
+) -> None:
+    """Check CI status for a pull request or commit."""
+    token = os.environ.get("CI_GITEA_TOKEN", "")
+    if not token:
+        raise click.ClickException(_("CI_GITEA_TOKEN is not set."))
+
+    repo_owner = owner or REPO_OWNER
+    if not repo_owner:
+        raise click.ClickException(_("Repository owner not set. Use --owner or DEVX_REPO_OWNER env var."))
+    repo_name = repo or get_repo_name()
+
+    client = GiteaClient(GITEA_API_URL, token, repo_owner, repo_name)
+
+    if sha is None:
+        if pr_number is None:
+            pr_number = _get_current_branch_pr(client)
+            click.echo(_("Checking status for PR #{pr_number}...", pr_number=pr_number))
+        pr = client.get_pr(pr_number)
+        sha = pr.get("head", {}).get("sha", "")
+        if not sha:
+            raise click.ClickException(_("Could not determine head SHA for PR #{pr_number}.", pr_number=pr_number))
+
+    click.echo(_("Commit: {sha}", sha=sha[:12]))
+    click.echo("")
+
+    state = wait_for_completion(client, sha, timeout, interval) if do_wait else print_status(client, sha)
+
+    if state in ("failure", "error"):
+        raise click.ClickException(_("CI checks failed."))
+    if state == "pending" and do_wait:
+        raise click.ClickException(_("CI checks did not complete within timeout."))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/pre_push_check.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Pre-push validation: ensure a Vikunja task exists for the branch.
+
+This tool is designed to run as a git pre-push hook.  It extracts the
+task ID from the branch name (e.g. ``DEVX-31-fix-foo`` → ``DEVX-31``)
+and verifies that a corresponding Vikunja task exists.
+
+If the task does not exist, the hook **fails with guidance** — it does
+not auto-create the task.  This prevents accidental pushes of branches
+without a planning task.
+
+Usage::
+
+    python -m devx.tools.pre_push_check --branch DEVX-31-fix-foo
+
+Exit codes:
+  0 — all checks passed, safe to push
+  1 — validation failed (missing task, missing token, etc.)
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess  # nosec B404
+
+import click
+from dotenv import load_dotenv
+
+from devx.api_clients import VikunjaClient
+from devx.config import DEFAULT_PER_PAGE, TASK_ID_RE, TASK_PREFIX, VIKUNJA_API_URL, VIKUNJA_PROJECT_ID
+from devx.i18n import _
+
+load_dotenv()
+
+
+def get_current_branch() -> str:
+    """Return the current git branch name, or empty string on error."""
+    result = subprocess.run(  # nosec
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.stdout.strip()
+
+
+def extract_task_id(branch: str) -> str:
+    """Extract the task ID (e.g. ``DEVX-31``) from a branch name."""
+    match = TASK_ID_RE.search(branch)
+    return match.group(0) if match else ""
+
+
+def task_exists(task_id: str) -> bool:
+    """Check if a Vikunja task with the given identifier exists.
+
+    Returns ``False`` if VIKUNJA_TOKEN is not set (soft-fail in local mode).
+    """
+    token = os.environ.get("VIKUNJA_TOKEN", "")
+    if not token:
+        return False
+    client = VikunjaClient(VIKUNJA_API_URL, token)
+    return client.find_task_by_identifier(VIKUNJA_PROJECT_ID, task_id, per_page=DEFAULT_PER_PAGE) is not None
+
+
+def validate(branch: str) -> None:
+    """Run all pre-push validations for the given branch.
+
+    Raises ``click.ClickException`` on failure.
+    """
+    if not branch or branch in ("master", "main"):
+        return
+
+    task_id = extract_task_id(branch)
+    if not task_id:
+        raise click.ClickException(
+            _(
+                "Branch '{branch}' does not contain a task ID.\n"
+                "  Expected format: {prefix}-N-short-description\n"
+                "  Example: {prefix}-42-add-feature\n"
+                "  Fix: rename the branch or create a Vikunja task first:\n"
+                '    python -m devx.tools.create_task --title "Task title"',
+                branch=branch,
+                prefix=TASK_PREFIX,
+            )
+        )
+
+    token = os.environ.get("VIKUNJA_TOKEN", "")
+    if not token:
+        click.echo(
+            _(
+                "WARNING: VIKUNJA_TOKEN not set — skipping task existence check. "
+                "Set it in .env to enable full validation.",
+            ),
+            err=True,
+        )
+        return
+
+    if not task_exists(task_id):
+        raise click.ClickException(
+            _(
+                "Vikunja task {task_id} not found in project {project_id}.\n"
+                "  Create it first:\n"
+                '    python -m devx.tools.create_task --title "Task title"\n'
+                "  Or check that the task ID in the branch name is correct.",
+                task_id=task_id,
+                project_id=VIKUNJA_PROJECT_ID,
+            )
+        )
+
+    click.echo(_("Pre-push check passed: task {task_id} exists.", task_id=task_id))
+
+
+@click.command()
+@click.option("--branch", default=None, help="Branch name (default: auto-detect from git).")
+def cli(branch: str | None) -> None:
+    """Validate pre-push preconditions for the current branch."""
+    if branch is None:
+        branch = get_current_branch()
+    validate(branch)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/rebase.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Rebase current branch onto origin/master and force-push.
+
+Fetches origin/master, rebases the current branch, and force-pushes with
+``--force-with-lease``. This is the manual equivalent of what
+``auto_merge.py`` does automatically via the Gitea API.
+
+Usage::
+
+    # Rebase current branch onto master and force-push
+    python -m devx.tools.rebase
+
+    # Rebase without pushing (local only)
+    python -m devx.tools.rebase --no-push
+
+The tool fails if:
+  - The rebase encounters conflicts (exits with rebase in progress)
+  - The force-push is rejected (remote has unexpected commits)
+  - Not on a branch (detached HEAD)
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+
+import click
+
+from devx.i18n import _
+
+
+def _run_git(args: list[str], check: bool = True) -> subprocess.CompletedProcess[str]:
+    """Run a git command and return the result."""
+    return subprocess.run(  # nosec B603, B607
+        ["git", *args],
+        capture_output=True,
+        text=True,
+        check=check,
+    )
+
+
+@click.command()
+@click.option("--no-push", is_flag=True, help="Rebase locally without pushing.")
+def main(no_push: bool) -> None:
+    """Rebase current branch onto origin/master and force-push."""
+    # Ensure we're on a branch (check=False — we handle errors ourselves)
+    branch_result = _run_git(["rev-parse", "--abbrev-ref", "HEAD"], check=False)
+    if branch_result.returncode != 0:
+        raise click.ClickException(_("Could not detect current branch: {error}", error=branch_result.stderr.strip()))
+    branch = branch_result.stdout.strip()
+    if branch == "HEAD":
+        raise click.ClickException(_("Cannot rebase: not on a branch (detached HEAD)."))
+
+    click.echo(_("Fetching origin/master..."))
+    fetch = _run_git(["fetch", "origin", "master"], check=False)
+    if fetch.returncode != 0:
+        raise click.ClickException(_("Fetch failed: {error}", error=fetch.stderr.strip()))
+
+    # Check if behind master
+    behind = _run_git(
+        ["rev-list", "--count", "HEAD..origin/master"],
+        check=False,
+    )
+    behind_count = int(behind.stdout.strip()) if behind.stdout.strip().isdigit() else 0
+
+    if behind_count == 0:
+        click.echo(_("Branch is already up-to-date with origin/master."))
+        if not no_push:
+            click.echo(_("Nothing to push."))
+        return
+
+    click.echo(_("Branch is {count} commit(s) behind master. Rebasing...", count=behind_count))
+    rebase = _run_git(["rebase", "origin/master"], check=False)
+    if rebase.returncode != 0:
+        raise click.ClickException(
+            _(
+                "Rebase failed (conflicts or other error):\n{error}\nResolve conflicts and run: git rebase --continue",
+                error=rebase.stderr.strip() or rebase.stdout.strip(),
+            )
+        )
+
+    click.echo(_("Rebase successful."))
+
+    if not no_push:
+        click.echo(_("Force-pushing..."))
+        push = _run_git(["push", "--force-with-lease", "origin", branch], check=False)
+        if push.returncode != 0:
+            raise click.ClickException(
+                _(
+                    "Force-push failed:\n{error}\nThe remote may have unexpected commits. Fetch and try again.",
+                    error=push.stderr.strip(),
+                )
+            )
+        click.echo(_("Pushed {branch} to origin.", branch=branch))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/setup.py

@@ -26,15 +26,24 @@ def _run(cmd: list[str]) -> None:
 
 
 def _install_python_deps(bin_dir: str, extras: str = "dev") -> None:
-    """Install the project with the specified extras in editable mode."""
+    """Install the project with the specified extras in editable mode.
+
+    In CI (system Python with PIP_BREAK_SYSTEM_PACKAGES=1), a first attempt
+    uses --break-system-packages. If that fails (e.g. debian-installed
+    packages without RECORD files), retry with --ignore-installed to skip
+    uninstalling system packages entirely.
+    """
     pip = str(Path(bin_dir) / "pip")
     cmd = [pip, "install", "-e", f".[{extras}]"]
-    # In CI (system Python), --break-system-packages allows installing to
-    # system site-packages, and --ignore-installed avoids uninstall failures
-    # for debian-installed packages (e.g. platformdirs) that lack RECORD files.
     if os.environ.get("PIP_BREAK_SYSTEM_PACKAGES") == "1":
-        cmd.extend(["--break-system-packages", "--ignore-installed"])
-    _run(cmd)
+        cmd.append("--break-system-packages")
+    result = subprocess.run(cmd, check=False)  # nosec B603
+    if result.returncode != 0 and os.environ.get("PIP_BREAK_SYSTEM_PACKAGES") == "1":
+        click.echo("  Retrying with --ignore-installed to bypass system packages...")
+        cmd.append("--ignore-installed")
+        _run(cmd)
+    elif result.returncode != 0:
+        raise subprocess.CalledProcessError(result.returncode, cmd)
 
 
 def _install_pre_commit_hooks(bin_dir: str) -> None:
@@ -46,7 +55,7 @@ def _install_pre_commit_hooks(bin_dir: str) -> None:
 
 def _install_ansible_collections(bin_dir: str) -> None:
     """Install required Ansible Galaxy collections if requirements exist."""
-    galaxy = str(Path(bin_dir) / "ansible-galaxy")
+    galaxy = shutil.which("ansible-galaxy") or str(Path(bin_dir) / "ansible-galaxy")
     requirements = Path("ansible/requirements.yml")
     if not requirements.exists():
         click.echo("  ansible/requirements.yml not found — skipping collections.")
@@ -55,19 +64,19 @@ def _install_ansible_collections(bin_dir: str) -> None:
 
 
 def _configure_tea_login() -> None:
-    """Configure tea CLI login from .env if REPO_TOKEN is set.
+    """Configure tea CLI login from .env if CI_GITEA_TOKEN is set.
 
     Idempotent: if a login with the same name already exists, it is not re-added.
-    Skips if tea is not installed or REPO_TOKEN is not set.
+    Skips if tea is not installed or CI_GITEA_TOKEN is not set.
     """
     tea_bin = shutil.which("tea")
     if tea_bin is None:
         click.echo("tea: not installed — run 'make install-tools' to install it.")
         return
 
-    token = os.environ.get("REPO_TOKEN", "")
+    token = os.environ.get("CI_GITEA_TOKEN", "")
     if not token:
-        click.echo("tea: REPO_TOKEN not set — skipping login configuration.")
+        click.echo("tea: CI_GITEA_TOKEN not set — skipping login configuration.")
         return
 
     api_url = os.environ.get("DEVX_GITEA_API_URL", "https://git.oblachno.oblachno.fyi/api/v1")
@@ -141,19 +150,29 @@ def _verify(bin_dir: str) -> None:
     default=False,
     help="Skip Ansible Galaxy collection installation.",
 )
+@click.option(
+    "--skip-install",
+    is_flag=True,
+    default=False,
+    help="Skip pip install (use when deps already installed, e.g. devx came via ci extra).",
+)
 def main(
     bin_dir: str,
     extras: str,
     no_pre_commit: bool,
     no_tea_login: bool,
     no_ansible_collections: bool,
+    skip_install: bool,
 ) -> None:
     """Install Python deps, pre-commit hooks, and configure tea CLI."""
     if not Path(bin_dir).exists():
         raise click.ClickException(f"Bin directory not found: {bin_dir}. Run 'python3 -m venv .venv' first.")
 
-    click.echo(f"Installing Python dependencies (extras: {extras})...")
-    _install_python_deps(bin_dir, extras)
+    if not skip_install:
+        click.echo(f"Installing Python dependencies (extras: {extras})...")
+        _install_python_deps(bin_dir, extras)
+    else:
+        click.echo("Skipping pip install (--skip-install).")
 
     if not no_ansible_collections:
         click.echo("Installing Ansible Galaxy collections...")

src/devx/tools/setup_image.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Set up the project inside a pre-built CI image.
+
+CI images (e.g. ``ci-quality:latest``) ship with a Python virtualenv at
+``/opt/venv`` that already contains the runtime dependencies. This tool
+links that venv to ``.venv`` in the project root and installs the project
+itself in editable mode, optionally with extras.
+
+If ``/opt/venv`` does not exist (local development), falls back to
+``make setup-ci`` via ``subprocess``.
+
+Usage::
+
+    python3 -m devx.tools.setup_image                 # runtime deps only
+    python3 -m devx.tools.setup_image --extras lint   # runtime + lint deps
+    python3 -m devx.tools.setup_image --extras ci,lint
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess  # nosec B404
+from pathlib import Path
+
+import click
+
+DEFAULT_VENV = ".venv"
+OPT_VENV = "/opt/venv"
+FALLBACK_TARGET = "setup-ci"
+
+
+def _build_pip_extra_index_url(
+    gitea_host: str,
+    gitea_org: str,
+    username: str,
+    token: str,
+) -> str:
+    """Build the PIP_EXTRA_INDEX_URL for the Gitea PyPI registry.
+
+    Returns a URL of the form:
+        https://<user>:<token>@<host>/api/packages/<org>/pypi/simple/
+    """
+    return f"https://{username}:{token}@{gitea_host}/api/packages/{gitea_org}/pypi/simple/"
+
+
+def _install_in_image(
+    venv_link: str,
+    opt_venv: str,
+    extras: str,
+    gitea_host: str,
+    gitea_org: str,
+) -> None:
+    """Link /opt/venv to .venv, activate it, and pip install the project.
+
+    Sets ``PIP_EXTRA_INDEX_URL`` when ``CI_GITEA_TOKEN`` is available so
+    that private packages from the Gitea PyPI registry can be installed.
+    """
+    # Symlink /opt/venv → .venv
+    link = Path(venv_link)
+    if link.exists() or link.is_symlink():
+        link.unlink()
+    link.symlink_to(opt_venv)
+
+    # Build pip install command
+    spec = f".[{extras}]" if extras else "."
+    pip_bin = str(Path(venv_link) / "bin" / "pip")
+    cmd = [pip_bin, "install", "--no-cache-dir", "-e", spec]
+
+    env = os.environ.copy()
+    token = env.get("CI_GITEA_TOKEN", "")
+    if token:
+        username = env.get("CI_GITEA_USERNAME", "emil")
+        env["PIP_EXTRA_INDEX_URL"] = _build_pip_extra_index_url(
+            gitea_host,
+            gitea_org,
+            username,
+            token,
+        )
+
+    click.echo(f"[setup-image] Linked {opt_venv}" + (f" with [{extras}]" if extras else "") + ".")
+    subprocess.run(cmd, check=True, env=env)  # nosec B603
+
+
+def _fallback_to_setup_ci() -> None:
+    """Fall back to ``make setup-ci`` when /opt/venv is not present."""
+    click.echo(f"[setup-image] {OPT_VENV} not found — falling back to {FALLBACK_TARGET}")
+    subprocess.run(  # nosec B603, B607
+        ["make", FALLBACK_TARGET],
+        check=True,
+    )
+
+
+@click.command()
+@click.option(
+    "--venv",
+    default=DEFAULT_VENV,
+    show_default=True,
+    help="Path to the local venv symlink (e.g. .venv).",
+)
+@click.option(
+    "--opt-venv",
+    default=OPT_VENV,
+    show_default=True,
+    help="Path to the pre-built venv inside the CI image.",
+)
+@click.option(
+    "--extras",
+    default="",
+    help="Comma-separated dependency extras (e.g. 'ci,lint'). Empty for runtime only.",
+)
+@click.option(
+    "--gitea-host",
+    default="git.oblachno.oblachno.fyi",
+    show_default=True,
+    help="Gitea host for the PyPI registry.",
+)
+@click.option(
+    "--gitea-org",
+    default="oblachno-oss",
+    show_default=True,
+    help="Gitea org for the PyPI registry.",
+)
+def cli(
+    venv: str,
+    opt_venv: str,
+    extras: str,
+    gitea_host: str,
+    gitea_org: str,
+) -> None:
+    """Set up the project using a pre-built CI image venv."""
+    if Path(opt_venv).is_dir():
+        _install_in_image(venv, opt_venv, extras, gitea_host, gitea_org)
+    else:
+        _fallback_to_setup_ci()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/setup_ssh_key.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Set up SSH private key for CI jobs that need SSH access to remote hosts.
+
+Writes the ``SSH_PRIVATE_KEY`` env var to ``~/.ssh/id_rsa``, starts
+``ssh-agent``, and adds the key.  Replaces the repeated inline shell
+pattern in CI workflow files.
+
+Usage::
+
+    python3 -m devx.tools.setup_ssh_key
+
+Reads ``SSH_PRIVATE_KEY`` from the environment.  Exits 0 on success,
+1 on missing key.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess  # nosec B404
+import sys
+from pathlib import Path
+
+import click
+
+from devx.i18n import _
+
+
+def setup_ssh_key(private_key: str | None = None) -> bool:
+    """Set up SSH private key and start ssh-agent.
+
+    Args:
+        private_key: The SSH private key content. If None, reads from
+            ``SSH_PRIVATE_KEY`` environment variable.
+
+    Returns:
+        True if setup succeeded, False if key is missing.
+    """
+    key = private_key or os.environ.get("SSH_PRIVATE_KEY", "")
+    if not key:
+        click.echo(_("SSH_PRIVATE_KEY not set — skipping SSH key setup"), err=True)
+        return False
+
+    ssh_dir = Path.home() / ".ssh"
+    ssh_dir.mkdir(parents=True, exist_ok=True)
+
+    key_path = ssh_dir / "id_rsa"
+    key_path.write_text(f"{key}\n", encoding="utf-8")
+    key_path.chmod(0o600)
+
+    # Start ssh-agent and add the key
+    agent_result = subprocess.run(  # nosec B603, B607
+        ["ssh-agent", "-s"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if agent_result.returncode != 0:
+        click.echo(_("Failed to start ssh-agent: {error}", error=agent_result.stderr), err=True)
+        return False
+
+    # Parse ssh-agent output to set env vars
+    for raw_line in agent_result.stdout.splitlines():
+        stripped = raw_line.strip()
+        if "=" in stripped and ";" in stripped:
+            var, val = stripped.split("=", 1)
+            val = val.rstrip(";")
+            os.environ[var] = val
+
+    # Add the key (non-fatal if it fails — key may already be loaded)
+    subprocess.run(  # nosec B603, B607
+        ["ssh-add", str(key_path)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return True
+
+
+@click.command()
+def cli() -> None:
+    """Set up SSH private key from SSH_PRIVATE_KEY env var."""
+    if setup_ssh_key():
+        click.echo(_("SSH key set up successfully"))
+        sys.exit(0)
+    click.echo(_("SSH key setup skipped (no key provided)"), err=True)
+    sys.exit(1)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/tools/tofu_ops.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""OpenTofu operations: init and validate across directories.
+
+Handles initialization and validation of OpenTofu configurations across
+multiple directories (modules + environments). Supports CI mode with
+``-backend=false`` to avoid state backend access.
+
+Usage::
+
+    python3 -m devx.tools.tofu_ops init --env staging
+    python3 -m devx.tools.tofu_ops validate
+    python3 -m devx.tools.tofu_ops validate --ci
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+from pathlib import Path
+
+import click
+
+from devx.i18n import _
+
+DEFAULT_ENV_DIRS = ["tofu/environments/{env}", "tofu/environments/dns"]
+DEFAULT_VALIDATE_DIRS = [
+    "tofu/modules/hetzner-vm",
+    "tofu/modules/hetzner-network",
+    "tofu/environments/staging",
+    "tofu/environments/production",
+    "tofu/environments/dns",
+]
+
+
+def _run_tofu(cmd: list[str], cwd: Path) -> None:
+    """Run a tofu command in the given directory, raising on failure."""
+    click.echo(_("  -> {dir}", dir=cwd))
+    result = subprocess.run(  # nosec B603, B607
+        cmd,
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise click.ClickException(
+            _("tofu command failed in {dir}: {error}", dir=cwd, error=result.stderr.strip()),
+        )
+
+
+def tofu_init(env: str, root: str = ".", extra_dirs: list[str] | None = None) -> None:
+    """Run ``tofu init`` in the environment directory and DNS directory.
+
+    Args:
+        env: Environment name (e.g. staging, production).
+        root: Repository root directory.
+        extra_dirs: Additional directory patterns to initialize.
+    """
+    root_path = Path(root)
+    dirs = [d.format(env=env) for d in (extra_dirs or DEFAULT_ENV_DIRS)]
+    for dir_pattern in dirs:
+        dir_path = root_path / dir_pattern
+        if dir_path.is_dir():
+            click.echo(_("[tofu-init] Initializing {dir}...", dir=dir_path))
+            _run_tofu(["tofu", "init"], dir_path)
+    click.echo(_("[tofu-init] Done."))
+
+
+def tofu_validate(
+    root: str = ".",
+    dirs: list[str] | None = None,
+    ci: bool = False,
+) -> None:
+    """Run ``tofu validate`` in all OpenTofu directories.
+
+    In CI mode, runs ``tofu init -backend=false`` before validate to avoid
+    state backend access.
+
+    Args:
+        root: Repository root directory.
+        dirs: List of directory paths to validate (relative to root).
+        ci: If True, use CI mode with -backend=false.
+    """
+    root_path = Path(root)
+    target_dirs = dirs or DEFAULT_VALIDATE_DIRS
+    mode = "ci" if ci else "validate"
+    click.echo(_("[tofu-{mode}] Validating OpenTofu configurations...", mode=mode))
+    for dir_rel in target_dirs:
+        dir_path = root_path / dir_rel
+        if not dir_path.is_dir():
+            continue
+        if ci:
+            _run_tofu(["tofu", "init", "-backend=false", "-input=false"], dir_path)
+        _run_tofu(["tofu", "validate"], dir_path)
+    click.echo(_("[tofu-{mode}] All configurations valid.", mode=mode))
+
+
+@click.group()
+def cli() -> None:
+    """OpenTofu operations."""
+
+
+@cli.command()
+@click.option("--env", required=True, help="Environment name (staging, production).")
+@click.option("--root", default=".", help="Repository root directory.")
+def init(env: str, root: str) -> None:
+    """Initialize OpenTofu in an environment."""
+    tofu_init(env, root)
+
+
+@cli.command()
+@click.option("--root", default=".", help="Repository root directory.")
+@click.option("--ci", is_flag=True, default=False, help="CI mode: use -backend=false.")
+def validate(root: str, ci: bool) -> None:
+    """Validate OpenTofu configurations."""
+    tofu_validate(root, ci=ci)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/utils/__init__.py

@@ -0,0 +1,3 @@
+"""Shared utility functions for devx and consumer projects."""
+
+from __future__ import annotations

src/devx/utils/api.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Utilities for handling API response values.
+
+Many APIs return boolean values as strings (``"true"``, ``"false"``)
+rather than native JSON booleans.  The Mattermost ``/api/v4/config/client``
+endpoint is a notable example.  These helpers handle both string and
+boolean responses safely.
+
+Usage::
+
+    from devx.utils.api import is_truthy, is_falsy
+
+    if not is_truthy(config.get("EnableOpenServer")):
+        raise ValueError("EnableOpenServer not enabled")
+"""
+
+from __future__ import annotations
+
+
+def is_truthy(value: str | bool | None) -> bool:
+    """Check if an API config value is truthy.
+
+    The API may return strings (``"true"``/``"false"``) or native
+    booleans.  This helper handles both.
+
+    Args:
+        value: The value to check (string, bool, or None).
+
+    Returns:
+        True if the value represents a truthy boolean.
+    """
+    if isinstance(value, bool):
+        return value
+    return str(value).lower() == "true"
+
+
+def is_falsy(value: str | bool | None) -> bool:
+    """Check if an API config value is falsy.
+
+    The API may return strings (``"true"``/``"false"``) or native
+    booleans.  This helper handles both.
+
+    Args:
+        value: The value to check (string, bool, or None).
+
+    Returns:
+        True if the value represents a falsy boolean.
+    """
+    if isinstance(value, bool):
+        return not value
+    return str(value).lower() == "false"

tests/unit/test_api_clients.py

@@ -6,7 +6,7 @@ from unittest.mock import MagicMock, patch
 import pytest
 import requests
 
-from devx.api_clients import GiteaClient, VikunjaClient, _is_retryable, _parse_error
+from devx.api_clients import GiteaClient, VikunjaClient, _parse_error
 from devx.config import (
     DEFAULT_PER_PAGE,
     DEFAULT_TIMEOUT,
@@ -137,6 +137,19 @@ class TestGiteaClient:
         assert result is None
         client.create_label.assert_not_called()
 
+    def test_ensure_label_creates_when_others_exist(self) -> None:
+        """When labels exist but none match the target name, create a new one."""
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client.list_labels = MagicMock(
+            return_value=[{"name": "bug", "color": "ff0000"}, {"name": "docs", "color": "007ec6"}]
+        )
+        client.create_label = MagicMock(return_value={"name": "ready-to-merge", "color": "2ecc71"})
+
+        result = client.ensure_label("ready-to-merge", "2ecc71", "desc")
+        assert result is not None
+        assert result["name"] == "ready-to-merge"
+        client.create_label.assert_called_once_with("ready-to-merge", "2ecc71", "desc")
+
     def test_list_branch_protections(self) -> None:
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
         client._session.request = MagicMock(
@@ -196,6 +209,18 @@ class TestGiteaClient:
         expected_update = {k: v for k, v in TEST_BP_CONFIG.items() if k != "branch_name"}
         client.update_branch_protection.assert_called_once_with("master", expected_update)
 
+    def test_ensure_branch_protection_creates_when_none_match(self) -> None:
+        """When existing protections exist but none match the target branch, create a new one."""
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client.list_branch_protections = MagicMock(
+            return_value=[{"branch_name": "develop"}, {"branch_name": "staging"}]
+        )
+        client.create_branch_protection = MagicMock(return_value={"id": 5, "branch_name": "master"})
+
+        result = client.ensure_branch_protection("master", TEST_BP_CONFIG)
+        assert result["id"] == 5
+        client.create_branch_protection.assert_called_once_with(TEST_BP_CONFIG)
+
     def test_merge_pr(self) -> None:
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
         client._session.request = MagicMock(return_value=_mock_response())
@@ -208,6 +233,18 @@ class TestGiteaClient:
             json={"Do": "squash", "MergeTitleField": "fix: bug"},
         )
 
+    def test_update_pr_branch(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(return_value=_mock_response())
+
+        client.update_pr_branch(7, style="rebase")
+        client._session.request.assert_called_once_with(
+            "POST",
+            "https://git.example.com/repos/owner/repo/pulls/7/update",
+            timeout=DEFAULT_TIMEOUT,
+            params={"style": "rebase"},
+        )
+
     def test_get_pr_labels(self) -> None:
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
         client._session.request = MagicMock(return_value=_mock_response([{"name": "ready-to-merge"}]))
@@ -248,6 +285,37 @@ class TestGiteaClient:
             timeout=DEFAULT_TIMEOUT,
         )
 
+    def test_create_pr(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(
+            return_value=_mock_response({"number": 15, "html_url": "https://git.example.com/pr/15"})
+        )
+        result = client.create_pr(title="DEVX-42: Add feature", head="DEVX-42-fix", body="desc")
+        assert result["number"] == 15
+        client._session.request.assert_called_once_with(
+            "POST",
+            "https://git.example.com/repos/owner/repo/pulls",
+            timeout=DEFAULT_TIMEOUT,
+            json={"title": "DEVX-42: Add feature", "head": "DEVX-42-fix", "base": "master", "body": "desc"},
+        )
+
+    def test_create_pr_no_body(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(
+            return_value=_mock_response({"number": 16, "html_url": "https://git.example.com/pr/16"})
+        )
+        result = client.create_pr(title="DEVX-43: Fix bug", head="DEVX-43-fix")
+        assert result["number"] == 16
+        call_kwargs = client._session.request.call_args.kwargs
+        assert "body" not in call_kwargs["json"]
+
+    def test_create_pr_custom_base(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(return_value=_mock_response({"number": 17}))
+        client.create_pr(title="Test", head="branch", base="develop")
+        call_kwargs = client._session.request.call_args.kwargs
+        assert call_kwargs["json"]["base"] == "develop"
+
     def test_get_pr_files(self) -> None:
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
         client._session.request = MagicMock(
@@ -278,6 +346,35 @@ class TestGiteaClient:
             timeout=DEFAULT_TIMEOUT,
         )
 
+    def test_list_prs(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(
+            return_value=_mock_response([{"number": 1, "title": "feat: add"}, {"number": 2, "title": "fix: bug"}])
+        )
+
+        result = client.list_prs()
+        assert len(result) == 2
+        assert result[0]["number"] == 1
+        client._session.request.assert_called_once_with(
+            "GET",
+            "https://git.example.com/repos/owner/repo/pulls",
+            params={"state": "all"},
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+    def test_list_prs_with_params(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(return_value=_mock_response([{"number": 3, "title": "docs: update"}]))
+
+        result = client.list_prs(state="closed", q="docs")
+        assert len(result) == 1
+        client._session.request.assert_called_once_with(
+            "GET",
+            "https://git.example.com/repos/owner/repo/pulls",
+            params={"state": "closed", "q": "docs"},
+            timeout=DEFAULT_TIMEOUT,
+        )
+
     def test_get_pr_reviews(self) -> None:
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
         client._session.request = MagicMock(return_value=_mock_response([{"id": 1, "state": "APPROVED"}]))
@@ -422,7 +519,7 @@ class TestGiteaClient:
         assert result["id"] == 1
         assert client._session.request.call_count == 2
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_request_retries_on_429(self, mock_sleep: MagicMock) -> None:
         """Should retry on 429 rate limit with exponential backoff."""
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
@@ -435,7 +532,7 @@ class TestGiteaClient:
         assert client._session.request.call_count == 3
         assert mock_sleep.call_count == 2
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_request_retries_on_503(self, mock_sleep: MagicMock) -> None:
         """Should retry on 503 service unavailable."""
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
@@ -447,7 +544,7 @@ class TestGiteaClient:
         assert result.json() == {"ok": True}
         assert client._session.request.call_count == 2
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_request_no_retry_on_404(self, mock_sleep: MagicMock) -> None:
         """Should NOT retry on 404 — it's not a transient error."""
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
@@ -460,7 +557,7 @@ class TestGiteaClient:
         assert client._session.request.call_count == 1
         mock_sleep.assert_not_called()
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_request_retries_on_connection_error(self, mock_sleep: MagicMock) -> None:
         """Should retry on connection errors."""
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
@@ -470,7 +567,7 @@ class TestGiteaClient:
         assert result.json() == {"ok": True}
         assert client._session.request.call_count == 2
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_request_max_retries_exhausted(self, mock_sleep: MagicMock) -> None:
         """Should raise APIError after max retries on persistent 503."""
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
@@ -482,7 +579,7 @@ class TestGiteaClient:
         assert exc_info.value.status == 503
         assert client._session.request.call_count == 3  # MAX_RETRIES
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_request_connection_error_exhausted(self, mock_sleep: MagicMock) -> None:
         """Should raise APIError after max retries on persistent connection errors."""
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
@@ -566,7 +663,47 @@ class TestVikunjaClient:
             json={"done": True},
         )
 
-    @patch("devx.api_clients.time.sleep")
+    def test_list_comments(self) -> None:
+        client = VikunjaClient("https://work.example.com", "tok")
+        client._session.request = MagicMock(
+            return_value=_mock_response([{"id": 1, "comment": "first"}, {"id": 2, "comment": "second"}])
+        )
+
+        result = client.list_comments(42)
+        assert len(result) == 2
+        assert result[0]["comment"] == "first"
+        client._session.request.assert_called_once_with(
+            "GET",
+            "https://work.example.com/tasks/42/comments",
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+    def test_update_task_safe(self) -> None:
+        client = VikunjaClient("https://work.example.com", "tok")
+        client._session.request = MagicMock(
+            side_effect=[
+                _mock_response({"id": 42, "title": "My task", "done": False}),
+                _mock_response({"id": 42, "title": "My task", "done": True}),
+            ]
+        )
+
+        result = client.update_task_safe(42, done=True)
+        assert result["done"] is True
+        assert result["title"] == "My task"
+        assert client._session.request.call_count == 2
+        client._session.request.assert_any_call(
+            "GET",
+            "https://work.example.com/tasks/42",
+            timeout=DEFAULT_TIMEOUT,
+        )
+        client._session.request.assert_any_call(
+            "POST",
+            "https://work.example.com/tasks/42",
+            timeout=DEFAULT_TIMEOUT,
+            json={"id": 42, "title": "My task", "done": True},
+        )
+
+    @patch("time.sleep")
     def test_http_error_raises_api_error(self, mock_sleep: MagicMock) -> None:
         client = VikunjaClient("https://work.example.com", "tok")
         mock_resp = MagicMock()
@@ -588,7 +725,7 @@ class TestVikunjaClient:
             client.list_tasks()
         assert "connection failed" in str(exc_info.value)
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_vikunja_retries_on_503(self, mock_sleep: MagicMock) -> None:
         """VikunjaClient should also retry on 503."""
         client = VikunjaClient("https://work.example.com", "tok")
@@ -600,7 +737,7 @@ class TestVikunjaClient:
         assert len(result) == 1
         assert client._session.request.call_count == 2
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_vikunja_retries_on_connection_error(self, mock_sleep: MagicMock) -> None:
         """VikunjaClient should retry on connection errors."""
         client = VikunjaClient("https://work.example.com", "tok")
@@ -610,7 +747,7 @@ class TestVikunjaClient:
         assert len(result) == 1
         assert client._session.request.call_count == 2
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_vikunja_max_retries_exhausted(self, mock_sleep: MagicMock) -> None:
         """VikunjaClient should raise APIError after max retries on persistent 503."""
         client = VikunjaClient("https://work.example.com", "tok")
@@ -622,7 +759,7 @@ class TestVikunjaClient:
         assert exc_info.value.status == 503
         assert client._session.request.call_count == 3  # MAX_RETRIES
 
-    @patch("devx.api_clients.time.sleep")
+    @patch("time.sleep")
     def test_vikunja_connection_error_exhausted(self, mock_sleep: MagicMock) -> None:
         """VikunjaClient should raise APIError after max retries on persistent connection errors."""
         client = VikunjaClient("https://work.example.com", "tok")
@@ -632,21 +769,143 @@ class TestVikunjaClient:
         assert exc_info.value.status == 0
         assert client._session.request.call_count == 3  # MAX_RETRIES
 
+    def test_vikunja_create_task(self) -> None:
+        client = VikunjaClient("https://work.example.com", "tok")
+        client._session.request = MagicMock(
+            return_value=_mock_response({"id": 1, "identifier": "DEVX-1", "title": "Test"})
+        )
+        result = client.create_task(6, "Test", "<p>desc</p>")
+        assert result["identifier"] == "DEVX-1"
+        client._session.request.assert_called_once_with(
+            "PUT",
+            "https://work.example.com/projects/6/tasks",
+            timeout=DEFAULT_TIMEOUT,
+            json={"title": "Test", "description": "<p>desc</p>"},
+        )
 
-class TestIsRetryable:
-    def test_connection_error_is_retryable(self) -> None:
-        assert _is_retryable(requests.ConnectionError("refused")) is True
+    def test_vikunja_create_task_no_description(self) -> None:
+        client = VikunjaClient("https://work.example.com", "tok")
+        client._session.request = MagicMock(
+            return_value=_mock_response({"id": 2, "identifier": "DEVX-2", "title": "No desc"})
+        )
+        result = client.create_task(6, "No desc")
+        assert result["id"] == 2
+        call_kwargs = client._session.request.call_args.kwargs
+        assert call_kwargs["json"]["description"] == ""
 
-    def test_timeout_is_retryable(self) -> None:
-        assert _is_retryable(requests.Timeout("timed out")) is True
+    def test_find_task_by_identifier_found(self) -> None:
+        client = VikunjaClient("https://work.example.com", "tok")
+        client._session.request = MagicMock(
+            return_value=_mock_response([{"identifier": "DEVX-1"}, {"identifier": "DEVX-42", "title": "Found"}])
+        )
+        result = client.find_task_by_identifier(6, "DEVX-42", per_page=50)
+        assert result is not None
+        assert result["title"] == "Found"
 
-    def test_429_is_retryable(self) -> None:
-        err = _mock_http_error(429, "rate limited")
-        assert _is_retryable(err) is True
+    def test_find_task_by_identifier_not_found(self) -> None:
+        client = VikunjaClient("https://work.example.com", "tok")
+        client._session.request = MagicMock(
+            return_value=_mock_response([{"identifier": "DEVX-1"}, {"identifier": "DEVX-2"}])
+        )
+        result = client.find_task_by_identifier(6, "DEVX-99", per_page=50)
+        assert result is None
 
-    def test_404_is_not_retryable(self) -> None:
-        err = _mock_http_error(404, "not found")
-        assert _is_retryable(err) is False
+    def test_find_task_by_identifier_empty_project(self) -> None:
+        client = VikunjaClient("https://work.example.com", "tok")
+        client._session.request = MagicMock(return_value=_mock_response([]))
+        result = client.find_task_by_identifier(6, "DEVX-1", per_page=50)
+        assert result is None
 
-    def test_generic_exception_is_not_retryable(self) -> None:
-        assert _is_retryable(ValueError("oops")) is False
+    def test_find_task_by_identifier_paginates(self) -> None:
+        client = VikunjaClient("https://work.example.com", "tok")
+        full_page = [{"identifier": f"DEVX-{i}"} for i in range(50)]
+        client._session.request = MagicMock(
+            side_effect=[
+                _mock_response(full_page),
+                _mock_response([{"identifier": "DEVX-50", "title": "Found on page 2"}]),
+            ]
+        )
+        result = client.find_task_by_identifier(6, "DEVX-50", per_page=50)
+        assert result is not None
+        assert result["title"] == "Found on page 2"
+
+
+class TestGiteaClientPrLabels:
+    def test_add_pr_label(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(return_value=_mock_response({}))
+        client.add_pr_label(42, ["ready-to-merge"])
+        client._session.request.assert_called_once_with(
+            "POST",
+            "https://git.example.com/repos/owner/repo/issues/42/labels",
+            timeout=DEFAULT_TIMEOUT,
+            json={"labels": ["ready-to-merge"]},
+        )
+
+    def test_add_pr_label_multiple(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(return_value=_mock_response({}))
+        client.add_pr_label(42, ["ready-to-merge", "reviewed"])
+        call_kwargs = client._session.request.call_args.kwargs
+        assert call_kwargs["json"]["labels"] == ["ready-to-merge", "reviewed"]
+
+    def test_get_pr_label_names(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(return_value=_mock_response([{"name": "bug"}, {"name": "ready-to-merge"}]))
+        result = client.get_pr_label_names(42)
+        assert result == ["bug", "ready-to-merge"]
+        client._session.request.assert_called_once_with(
+            "GET",
+            "https://git.example.com/repos/owner/repo/issues/42/labels",
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+
+class TestGiteaClientActions:
+    def test_list_action_runs(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(
+            return_value=_mock_response({"workflow_runs": [{"id": 1, "status": "completed"}], "total_count": 1})
+        )
+        result = client.list_action_runs(branch="feature-branch", limit=1)
+        assert result["total_count"] == 1
+        client._session.request.assert_called_once_with(
+            "GET",
+            "https://git.example.com/repos/owner/repo/actions/runs",
+            timeout=DEFAULT_TIMEOUT,
+            params={"branch": "feature-branch", "limit": 1},
+        )
+
+    def test_get_action_run_jobs(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(
+            return_value=_mock_response({"jobs": [{"id": 100, "name": "quality", "conclusion": "failure"}]})
+        )
+        result = client.get_action_run_jobs(1410)
+        assert len(result) == 1
+        assert result[0]["name"] == "quality"
+        client._session.request.assert_called_once_with(
+            "GET",
+            "https://git.example.com/repos/owner/repo/actions/runs/1410/jobs",
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+    def test_get_action_run_jobs_empty(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(return_value=_mock_response({}))
+        result = client.get_action_run_jobs(1410)
+        assert result == []
+
+    def test_get_action_job_logs(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        mock_resp = MagicMock()
+        mock_resp.text = "log line 1\nlog line 2"
+        mock_resp.raise_for_status = MagicMock()
+        client._session.request = MagicMock(return_value=mock_resp)
+        result = client.get_action_job_logs(10026)
+        assert "log line 1" in result
+        client._session.request.assert_called_once_with(
+            "GET",
+            "https://git.example.com/repos/owner/repo/actions/jobs/10026/logs",
+            timeout=DEFAULT_TIMEOUT,
+        )