bitranox-template-py-cli 1.5.4__tar.gz → 1.6.1__tar.gz

bitranox_template_py_cli-1.6.1/.gitattributes

@@ -0,0 +1,15 @@
+# Normalize every text file to LF in the repo AND the working tree, on every OS.
+# `text=auto` auto-detects binary and leaves it untouched; `eol=lf` forces LF checkout
+# so a Windows edit/save cannot reintroduce CRLF churn.
+* text=auto eol=lf
+
+# Runtime-critical: CRLF here breaks execution on Linux (^M in shebang / make recipes).
+Makefile     text eol=lf
+*.sh         text eol=lf
+*.py         text eol=lf
+*.ps1        text eol=lf
+*.toml       text eol=lf
+*.md         text eol=lf
+*.json       text eol=lf
+*.yml        text eol=lf
+*.yaml       text eol=lf

{bitranox_template_py_cli-1.5.4 → bitranox_template_py_cli-1.6.1}/.github/actions/extract-metadata/action.yml

@@ -29,6 +29,11 @@ outputs:
   BANDIT_SKIP_FLAG:
     description: Bandit skip flag string (e.g. "-s B101,B601") or empty
     value: ${{ steps.meta.outputs.BANDIT_SKIP_FLAG }}
+  PYTEST_MARKER_EXPR:
+    description: >-
+      Marker expression for the CI test run (e.g. "not local_only and not integration"),
+      built from tool.ci.pytest-exclude-markers
+    value: ${{ steps.meta.outputs.PYTEST_MARKER_EXPR }}
 
 runs:
   using: composite
@@ -69,6 +74,15 @@ runs:
         bandit_skips = data.get('tool', {}).get('bandit', {}).get('skips', [])
         bandit_skip_flag = f"-s {','.join(bandit_skips)}" if bandit_skips else ""
 
+        # --- [tool.ci] section ---
+        # CI always skips local_only (those tests need a dev box). A project whose
+        # suite also carries markers CI cannot satisfy - integration tests needing a
+        # container that a separate workflow starts - names them here, rather than
+        # every such repo forking this workflow to edit one -m expression.
+        ci_config = data.get('tool', {}).get('ci', {})
+        exclude_markers = ['local_only', *ci_config.get('pytest-exclude-markers', [])]
+        pytest_marker_expr = ' and '.join(f'not {m}' for m in exclude_markers)
+
         # Write to GITHUB_OUTPUT for composite action outputs
         with open(os.environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as out:
             out.write(f"PROJECT_NAME={project}\n")
@@ -79,6 +93,7 @@ runs:
             out.write(f"COV_REPORT_FILE={cov_report_file}\n")
             out.write(f"COV_FAIL_UNDER={cov_fail_under}\n")
             out.write(f"BANDIT_SKIP_FLAG={bandit_skip_flag}\n")
+            out.write(f"PYTEST_MARKER_EXPR={pytest_marker_expr}\n")
 
         # Also write to GITHUB_ENV so subsequent steps can use ${{ env.VAR }}
         with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
@@ -90,3 +105,4 @@ runs:
             env.write(f"COV_REPORT_FILE={cov_report_file}\n")
             env.write(f"COV_FAIL_UNDER={cov_fail_under}\n")
             env.write(f"BANDIT_SKIP_FLAG={bandit_skip_flag}\n")
+            env.write(f"PYTEST_MARKER_EXPR={pytest_marker_expr}\n")

{bitranox_template_py_cli-1.5.4 → bitranox_template_py_cli-1.6.1}/.github/workflows/codeql.yml

@@ -23,7 +23,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v4

{bitranox_template_py_cli-1.5.4 → bitranox_template_py_cli-1.6.1}/.github/workflows/default_cicd_public.yml

@@ -18,7 +18,7 @@ jobs:
       python-latest: ${{ steps.metadata.outputs.python-latest }}
       os-matrix: ${{ steps.metadata.outputs.os-matrix }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-python@v6
         with:
           python-version: "3.x"
@@ -66,7 +66,7 @@ jobs:
       UV_LINK_MODE: "copy"
       UV_BREAK_SYSTEM_PACKAGES: "1"
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python }}
@@ -169,7 +169,7 @@ jobs:
       - name: Restore ruff cache
         if: runner.environment == 'github-hosted'
         id: ruff-cache
-        uses: actions/cache/restore@v5
+        uses: actions/cache/restore@v6
         with:
           path: .ruff_cache
           key: ruff-${{ runner.os }}-py${{ matrix.python }}-${{ github.sha }}
@@ -201,7 +201,7 @@ jobs:
           # and stale journal files cause "database is locked" errors.
           COVERAGE_FILE: "${{ runner.temp }}/.coverage"
         run: >-
-          pytest -m "not local_only"
+          pytest -m "${{ env.PYTEST_MARKER_EXPR }}"
           --cov=${{ env.SRC_PATH }}/${{ env.PACKAGE_MODULE }}
           --cov-report=term-missing
           --cov-report=xml:${{ env.COV_REPORT_FILE }}
@@ -236,12 +236,62 @@ jobs:
         continue-on-error: true
         shell: python
         run: |
-          import subprocess, sys
+          import subprocess, sys, tempfile
           import rtoml
           from pathlib import Path
+
+          # Audit the project's OWN resolved dependency tree, not the ambient
+          # environment. "Install dev deps" uses --system, so the interpreter
+          # being audited is the runner image's, and that image ships packages
+          # this project neither declares nor distributes (setuptools, pip,
+          # wheel). Auditing those reported CVEs no consumer of this project is
+          # exposed to, and a scan that is permanently yellow is a scan everyone
+          # learns to ignore. Resolving pyproject.toml here keeps the result
+          # identical on every OS/python and dependent only on what we declare.
           data = rtoml.load(Path("pyproject.toml"))
+
+          # Not every project declares dev dependencies, and those that do may use
+          # either an extra or a PEP 735 group. Asking uv for one that does not
+          # exist is a hard error ("Requested extra not found"), which would leave
+          # the audit permanently broken here rather than merely noisy, so select
+          # the flag from what this project actually declares.
+          selector = []
+          if "dev" in data.get("project", {}).get("optional-dependencies", {}):
+              selector = ["--extra", "dev"]
+          elif "dev" in data.get("dependency-groups", {}):
+              selector = ["--group", "dev"]
+
+          tmp = Path(tempfile.mkdtemp())
+          req = tmp / "compiled-requirements.txt"
+          subprocess.check_call(
+              ["uv", "pip", "compile", *selector, "pyproject.toml", "-o", str(req), "--quiet"]
+          )
+
+          # Drop direct URL references ("pkg @ git+https://...") before auditing.
+          # pip-audit cannot audit those (they are not on PyPI) but, given a
+          # requirements file, first tries to `git clone` each one to resolve a
+          # version - a slow, credential-dependent fetch. No public project here
+          # uses one today, yet "allow-direct-references" is enabled, so this
+          # guards the day one appears and keeps this step identical to the
+          # default_cicd_private template's.
+          audit_req = tmp / "audit-requirements.txt"
+          kept, dropped = [], []
+          for line in req.read_text(encoding="utf-8").splitlines():
+              if " @ " in line and not line.lstrip().startswith("#"):
+                  dropped.append(line.split(" @ ", 1)[0].strip())
+              else:
+                  kept.append(line)
+          audit_req.write_text("\n".join(kept) + "\n", encoding="utf-8")
+          if dropped:
+              # Never drop coverage silently: name what is not being audited here.
+              print(f"::notice::pip-audit: not auditing {len(dropped)} direct-URL dependency/ies "
+                    f"(audited in their own repo): {', '.join(sorted(dropped))}")
+
+          req = audit_req
           vulns = data.get("tool", {}).get("pip-audit", {}).get("ignore-vulns", [])
-          cmd = ["pip-audit", "--skip-editable"]
+          # --no-deps: the compiled file is already a complete pinned resolution,
+          # so pip-audit must audit it verbatim rather than re-resolving it.
+          cmd = ["pip-audit", "--no-deps", "-r", str(req)]
           for v in vulns:
               cmd.extend(["--ignore-vuln", v])
           sys.exit(subprocess.call(cmd))
@@ -293,7 +343,7 @@ jobs:
 
       - name: Save ruff cache
         if: always() && runner.environment == 'github-hosted' && steps.ruff-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v5
+        uses: actions/cache/save@v6
         with:
           path: .ruff_cache
           key: ruff-${{ runner.os }}-py${{ matrix.python }}-${{ github.sha }}
@@ -302,7 +352,7 @@ jobs:
     name: pipx/uv verification (ubuntu)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-python@v6
         with:
           python-version: "3.14"
@@ -341,7 +391,7 @@ jobs:
     name: Execute notebooks (ubuntu, Python 3.14)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-python@v6
         with:
           python-version: "3.14"

{bitranox_template_py_cli-1.5.4 → bitranox_template_py_cli-1.6.1}/.github/workflows/default_release_public.yml

@@ -16,7 +16,7 @@ jobs:
     env:
       UV_LINK_MODE: "copy"
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-python@v6
         with:
           python-version: '3.14'
@@ -46,13 +46,21 @@ jobs:
     environment: pypi
     permissions:
       contents: read
+      # id-token is required for OIDC / PyPI Trusted Publisher. It is harmless when
+      # a PYPI_API_TOKEN secret is configured, in which case the token path runs.
+      id-token: write
     steps:
-      - name: Verify PyPI token is set
+      - name: Select PyPI auth method
+        id: auth
+        env:
+          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
         run: |
-          if [ -z "${{ secrets.PYPI_API_TOKEN }}" ]; then
-            echo "::error title=Missing PyPI token::Set the PYPI_API_TOKEN secret in GitHub repository settings to enable PyPI publishing on releases."
-            echo "See: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions"
-            exit 1
+          if [ -n "$PYPI_API_TOKEN" ]; then
+            echo "PYPI_API_TOKEN is set; publishing with the API token."
+            echo "method=token" >> "$GITHUB_OUTPUT"
+          else
+            echo "No PYPI_API_TOKEN; publishing via OIDC Trusted Publisher."
+            echo "method=oidc" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Download artifacts
@@ -61,9 +69,17 @@ jobs:
           name: dist
           path: dist/
 
-      - name: Publish to PyPI
+      - name: Publish to PyPI (API token)
+        if: steps.auth.outputs.method == 'token'
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}
           attestations: false
           skip-existing: true
+
+      - name: Publish to PyPI (Trusted Publisher / OIDC)
+        if: steps.auth.outputs.method == 'oidc'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+          skip-existing: true

{bitranox_template_py_cli-1.5.4 → bitranox_template_py_cli-1.6.1}/.gitignore

@@ -186,3 +186,18 @@ uv.lock
 CLAUDE.md
 prompts.md
 .grimp_cache/
+
+# Local, per-developer settings (Claude Code etc.) - never commit
+*.local.json
+# bitranox curated memory (local; CLAUDE.local.md @imports it)
+CLAUDE.local.md
+
+# Python virtual environments (managed by bmk)
+.venv-win/
+.venv-bmk/
+
+# Python virtual environments (managed by bmk)
+.venv*/
+
+# Autonomous-execution decision log (never committed)
+EXECUTION-USER-REVIEW.md

{bitranox_template_py_cli-1.5.4 → bitranox_template_py_cli-1.6.1}/CHANGELOG.md

@@ -6,6 +6,34 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-07-20
+
+Re-release of 1.6.0. PyPI rejected the 1.6.0 upload because that filename was previously used by a file that has since been deleted, and PyPI never permits filename reuse. Package contents are identical to 1.6.0.
+
+### Added
+- `send_email()` and `send_notification()` accept an optional `transport` argument, exposing btx_lib_mail's `Transport` port so a delivery double can be injected at a real seam instead of monkeypatching `smtplib`.
+
+### Fixed
+- Mail tests failed against btx_lib_mail 1.5.0, which streams the message over the wire protocol directly (MAIL/RCPT plus DATA or BDAT) instead of calling `smtp.sendmail()`. The suite now injects a recording transport and asserts delivery intent (envelope sender, recipients, host failover order, credentials, payload), so it no longer depends on the library's internals.
+- `ConfMail.smtp_password` is a `SecretStr` as of btx_lib_mail 1.5.0 and is now unwrapped before comparison.
+- `config-deploy` emits an ASCII marker so it cannot crash on a cp1252 Windows console.
+- `validate_profile` normalised to raise `ValueError`.
+- DEVELOPMENT.md referenced a `make test-slow` target that no longer exists (4 places); the target is `make testintegration`. It also documented the SMTP username environment variable as `EMAIL__SMTP_USER`, but the field is `smtp_username`, so the correct name is `EMAIL__SMTP_USERNAME`.
+
+### Documentation
+- DEVELOPMENT.md documents the SMTP test seam: inject a `transport` double instead of patching `smtplib`, and leave `transport` off the application ports.
+
+### Changed
+- Raised the `btx_lib_mail` floor to `>=1.5.0`, which the injected transport seam requires. Other dependency floors refreshed and the current bmk Makefile adopted.
+- CI: configurable pytest marker exclusion, pip-audit scoped to the project dependency tree with direct-URL dependencies filtered out, `actions/checkout` v7 and `actions/cache` v6.
+- `codecov-cli` disabled (it capped `click<8.3.0` and held click on CVE-2026-7246); the redundant PYSEC-2026-2132 ignore dropped.
+- LF line endings pinned via `.gitattributes`; file modes normalised so the executable bit is set only on shebang scripts.
+- Quickstart notebook installs the package with uv.
+
+## [1.6.0] - 2026-07-20 [NOT PUBLISHED]
+
+Tagged and released on GitHub, but never published to PyPI: the upload was rejected because the `1.6.0` filename had been used by a previously deleted file. Superseded by 1.6.1, which carries the same changes.
+
 ## [1.5.4] 2026-06-14
 
 ### Changed
@@ -84,13 +112,13 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 ## [1.3.1] - 2026-02-13
 
 ### Fixed
-- `tests/test_metadata_sync.py`: replaced `importlib.metadata` lookups with direct `pyproject.toml` reads — tests no longer fail when the package is not installed in the test environment (uvx)
+- `tests/test_metadata_sync.py`: replaced `importlib.metadata` lookups with direct `pyproject.toml` reads - tests no longer fail when the package is not installed in the test environment (uvx)
 - Makefile `dev` target now correctly installs dev extras (`uv pip install -e ".[dev]"`)
 
 ### Changed
 - CLAUDE.md: updated project structure trees to reflect actual codebase (added `entry.py`, `domain/errors.py`, `adapters/memory/`, `adapters/config/permissions.py`, `adapters/email/validation.py`; removed deleted `traceback.py`)
 - CLAUDE.md: rewrote Make targets table to match new `bmk`-based Makefile (added aliases, new targets; removed obsolete `menu`, `test-slow`)
-- CLAUDE.md: corrected versioning documentation — runtime metadata is served from `__init__conf__.py` constants, not `importlib.metadata`
+- CLAUDE.md: corrected versioning documentation - runtime metadata is served from `__init__conf__.py` constants, not `importlib.metadata`
 - CLAUDE.md: replaced stale `scripts/` instrumentation section with `bmk` delegation note
 - CLAUDE.md: updated `make test-slow` references to `make testintegration`
 
@@ -122,17 +150,17 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 - Profile name requirements documentation in CONFIG.md and README.md
 
 ### Removed
-- Custom `_PROFILE_PATTERN` regex — replaced by lib_layered_config's built-in validation
+- Custom `_PROFILE_PATTERN` regex - replaced by lib_layered_config's built-in validation
 
 ## [1.2.0] - 2026-01-30
 
 ### Added
 - **Attachment security settings** for email configuration (`[email.attachments]` section in `50-mail.toml`)
-  - `allowed_extensions` / `blocked_extensions` — whitelist/blacklist file extensions
-  - `allowed_directories` / `blocked_directories` — whitelist/blacklist attachment source directories
-  - `max_size_bytes` — maximum attachment file size (default 25 MiB, 0 to disable)
-  - `allow_symlinks` — whether symbolic links are permitted (default false)
-  - `raise_on_security_violation` — raise or skip on violations (default true)
+  - `allowed_extensions` / `blocked_extensions` - whitelist/blacklist file extensions
+  - `allowed_directories` / `blocked_directories` - whitelist/blacklist attachment source directories
+  - `max_size_bytes` - maximum attachment file size (default 25 MiB, 0 to disable)
+  - `allow_symlinks` - whether symbolic links are permitted (default false)
+  - `raise_on_security_violation` - raise or skip on violations (default true)
 - New `EmailConfig` fields for attachment security with Pydantic validators
 - `load_email_config_from_dict()` now flattens nested `[email.attachments]` section
 
@@ -145,17 +173,17 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 - Coverage SQLite "database is locked" errors on Python 3.14 free-threaded builds and network mounts (SMB/NFS)
 - Removed bogus `COVERAGE_NO_SQL=1` environment variable from `scripts/test.py` (not a real coverage.py setting)
 - CI workflow now sets `COVERAGE_FILE` to `runner.temp` so coverage always writes to local disk
-- **Import-linter was a silent no-op** in `make test` / `make push` — `python -m importlinter.cli lint` silently exits 0 without checking; replaced with `lint-imports` (the working console entry point)
+- **Import-linter was a silent no-op** in `make test` / `make push` - `python -m importlinter.cli lint` silently exits 0 without checking; replaced with `lint-imports` (the working console entry point)
 - CI/local parameter mismatches: ruff now targets `.` (not hardcoded `src tests notebooks`), pytest uses `python -m pytest` with `--cov=src/$PACKAGE_MODULE`, `--cov-fail-under=90`, and `-vv` matching local runs
 - `scripts/test.py` bandit source path now reads `src-path` from `[tool.scripts.test]` instead of hardcoding `Path("src")`
 - `scripts/test.py` module-level `_default_env` now rebuilt with configured `src_path` before running checks
 - `run_slow_tests()` now reads pytest verbosity from `[tool.scripts.test].pytest-verbosity` instead of hardcoding `"-vv"`
 
 ### Changed
-- **pyproject.toml as single source of truth**: CI workflow extracts all tool configuration (src-path, pytest-verbosity, coverage-report-file, fail_under, bandit skips) from `pyproject.toml` via metadata step — workflow is portable across projects without editing
+- **pyproject.toml as single source of truth**: CI workflow extracts all tool configuration (src-path, pytest-verbosity, coverage-report-file, fail_under, bandit skips) from `pyproject.toml` via metadata step - workflow is portable across projects without editing
 - `scripts/test.py` removed module-level `PACKAGE_SRC` constant; bandit source path computed from `config.src_path` inside the functions that need it
 - `make push` now accepts an unquoted message as trailing words (e.g. `make push fix typo in readme`); commit message format is `<version> - <message>`, defaulting to `<version> - chores` when no message is given
-- Removed interactive commit-message prompt from `push.py` — message is either provided via CLI args / `COMMIT_MESSAGE` env var, or defaults to `"chores"`
+- Removed interactive commit-message prompt from `push.py` - message is either provided via CLI args / `COMMIT_MESSAGE` env var, or defaults to `"chores"`
 
 ### Added
 - `pytest_configure` hook in `tests/conftest.py` that redirects coverage data to `tempfile.gettempdir()` and purges stale SQLite journal files before each run
@@ -165,8 +193,8 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 ### Fixed
 - CLAUDE.md: replaced stale package name `bitranox_template_cli_app_config_log_mail` with `bitranox_template_py_cli` throughout
 - Brittle SMTP mock assertions in `test_cli.py` now use structured `call_args` attributes instead of `str()` coercion
-- Stale docstring in `__init__conf__.py` claiming "adapters/platform layer" — corrected to "Package-level metadata module"
-- Weak OR assertion in `test_cli.py` for SMTP host display — replaced with two independent assertions
+- Stale docstring in `__init__conf__.py` claiming "adapters/platform layer" - corrected to "Package-level metadata module"
+- Weak OR assertion in `test_cli.py` for SMTP host display - replaced with two independent assertions
 - Removed stale `# type: ignore[reportUnknownVariableType]` from `sender.py` (`btx_lib_mail.ConfMail` now has proper type annotations)
 - Late function-body imports in `adapters/cli/commands/config.py` moved to module-level for consistency
 
@@ -219,7 +247,7 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 - Precompile all regex patterns in `scripts/` as module-level constants for consistent compilation
 - **LIBRARIES**: Replace custom redaction/validation with `lib_layered_config` redaction API and `btx_lib_mail` validators; bump both libraries
 - **LIBRARIES**: Replace stdlib `json` with `orjson`; replace `urllib` with `httpx` in scripts
-- **ARCHITECTURE**: Purified domain layer — `emit_greeting()` renamed to `build_greeting()` (returns `str`, no I/O); decoupled `display.py` from Click
+- **ARCHITECTURE**: Purified domain layer - `emit_greeting()` renamed to `build_greeting()` (returns `str`, no I/O); decoupled `display.py` from Click
 - **DATA ARCHITECTURE**: Consolidated `EmailConfig` into single Pydantic `BaseModel` (eliminated dataclass conversion chain)
 
 ## [1.0.0] - 2026-01-15

{bitranox_template_py_cli-1.5.4 → bitranox_template_py_cli-1.6.1}/DEVELOPMENT.md

@@ -2,26 +2,26 @@
 
 ## Make Targets
 
-| Target            | Description                                                                                |
-|-------------------|--------------------------------------------------------------------------------------------|
-| `help`            | Show help                                                                                  |
-| `install`         | Install package editable                                                                   |
-| `dev`             | Install package with dev extras                                                            |
-| `test`            | Lint, type-check, run tests with coverage, upload to Codecov                               |
-| `run`             | Run module CLI (requires dev install or src on PYTHONPATH)                                 |
-| `version-current` | Print current version from pyproject.toml                                                  |
-| `bump`            | Bump version (updates pyproject.toml and CHANGELOG.md)                                     |
-| `bump-patch`      | Bump patch version (X.Y.Z -> X.Y.(Z+1))                                                    |
-| `bump-minor`      | Bump minor version (X.Y.Z -> X.(Y+1).0)                                                    |
-| `bump-major`      | Bump major version ((X+1).0.0)                                                             |
-| `clean`           | Remove caches, build artifacts, and coverage                                               |
-| `push`            | Run tests, prompt for/accept a commit message, create (allow-empty) commit, push to remote |
-| `build`           | Build wheel/sdist artifacts via `python -m build`                                          |
-| `coverage`        | Generate coverage reports                                                                  |
-| `test-slow`       | Run slow integration tests (SMTP, external resources)                                      |
-| `dependencies`    | Check and list project dependencies                                                        |
-| `dependencies-update` | Update dependencies to latest versions                                                |
-| `menu`            | Interactive TUI to run targets and edit parameters (requires dev dep: textual)             |
+| Target                | Description                                                                                |
+|-----------------------|--------------------------------------------------------------------------------------------|
+| `help`                | Show help                                                                                  |
+| `install`             | Install package editable                                                                   |
+| `dev`                 | Install package with dev extras                                                            |
+| `test`                | Lint, type-check, run tests with coverage, upload to Codecov                               |
+| `run`                 | Run module CLI (requires dev install or src on PYTHONPATH)                                 |
+| `version-current`     | Print current version from pyproject.toml                                                  |
+| `bump`                | Bump version (updates pyproject.toml and CHANGELOG.md)                                     |
+| `bump-patch`          | Bump patch version (X.Y.Z -> X.Y.(Z+1))                                                    |
+| `bump-minor`          | Bump minor version (X.Y.Z -> X.(Y+1).0)                                                    |
+| `bump-major`          | Bump major version ((X+1).0.0)                                                             |
+| `clean`               | Remove caches, build artifacts, and coverage                                               |
+| `push`                | Run tests, prompt for/accept a commit message, create (allow-empty) commit, push to remote |
+| `build`               | Build wheel/sdist artifacts via `python -m build`                                          |
+| `coverage`            | Generate coverage reports                                                                  |
+| `testintegration`     | Run integration tests only (SMTP, external resources) [aliases: `testi`, `ti`]             |
+| `dependencies`        | Check and list project dependencies                                                        |
+| `dependencies-update` | Update dependencies to latest versions                                                     |
+| `menu`                | Interactive TUI to run targets and edit parameters (requires dev dep: textual)             |
 
 ### Target Parameters (env vars)
 
@@ -99,11 +99,11 @@ Some tests require external resources (SMTP servers, databases) and are excluded
 
 ### Quick Reference
 
-| Command | What it runs |
-|---------|--------------|
-| `make test` | All tests EXCEPT `local_only` (default for CI) |
-| `make test-slow` | ONLY `local_only` integration tests |
-| `pytest tests/` | ALL tests (no marker filter) |
+| Command                | What it runs                                   |
+|------------------------|------------------------------------------------|
+| `make test`            | All tests EXCEPT `local_only` (default for CI) |
+| `make testintegration` | ONLY `local_only` integration tests            |
+| `pytest tests/`        | ALL tests (no marker filter)                   |
 
 ### Email Integration Tests
 
@@ -116,7 +116,7 @@ To run email tests that actually send messages:
 EMAIL__SMTP_HOSTS=smtp.example.com:587
 EMAIL__FROM_ADDRESS=sender@example.com
 EMAIL__RECIPIENTS=recipient@example.com
-EMAIL__SMTP_USER=your_username
+EMAIL__SMTP_USERNAME=your_username
 EMAIL__SMTP_PASSWORD=your_password
 ```
 
@@ -129,7 +129,7 @@ bitranox-template-py-cli --env-file /path/to/my/.env send-notification --subject
 2. **Run the integration tests**:
 
 ```bash
-make test-slow
+make testintegration
 ```
 
 3. **Or run specific email tests**:
@@ -150,7 +150,23 @@ def test_real_external_service(...):
     ...
 ```
 
-These tests will be skipped in CI but run with `make test-slow`.
+These tests will be skipped in CI but run with `make testintegration`.
+
+### SMTP Test Seam
+
+`send_email()` and `send_notification()` accept an optional `transport` argument, forwarded
+to `btx_lib_mail`'s `Transport` port. Unit tests inject a double (`RecordingTransport` in
+`tests/test_mail.py`) rather than patching `smtplib.SMTP`, and assert on delivery intent:
+envelope sender, recipients, host failover order, credentials, and the composed payload.
+
+Do not go back to monkeypatching `smtplib`. btx_lib_mail streams the message over the wire
+protocol itself (MAIL/RCPT plus DATA or BDAT), so a `MagicMock` does not honour the contract
+and breaks whenever the library changes delivery strategy.
+
+The `SendEmail` / `SendNotification` ports in `application/ports.py` deliberately omit
+`transport`: a delivery mechanism is an adapter concern, not something the application layer
+should see. The adapter still satisfies the Protocol because an extra keyword parameter with
+a default is structurally compatible. Do not add `transport` to the port.
 
 ## Development Workflow