bitranox-template-py-cli 1.0.0__tar.gz

bitranox_template_py_cli-1.0.0/.env.example

@@ -0,0 +1,18 @@
+# Copy to .env and fill values as needed.
+
+# Codecov upload token (required for private repos; optional for public repos)
+CODECOV_TOKEN=
+
+# PyPI API token for release workflow (.github/workflows/release.yml)
+# Format: pypi-AgENdGVzdC5weXBpLm9yZwIk...
+PYPI_API_TOKEN=
+
+# Optional: GitHub token for API-limited tasks (e.g., brew audits against GitHub API)
+GITHUB_TOKEN=
+
+# Optional: Anaconda/conda-forge token if you automate conda uploads (not included in CI)
+ANACONDA_API_TOKEN=
+
+# Optional: Homebrew resources may be fetched via GitHub; token can increase rate limits
+HOMEBREW_GITHUB_API_TOKEN=
+

bitranox_template_py_cli-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,219 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        # Test against Python 3.10 and the latest 3.x available on Actions runners
+        python: ["3.10", "3.x"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install make on Windows
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          choco install -y make
+          echo "C:\\ProgramData\\chocolatey\\bin" >> $env:GITHUB_PATH
+      - name: Install dev deps
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+      - name: Run full test suite (lint, types, tests, coverage, codecov)
+        shell: bash
+        run: make test
+      - name: Build wheel/sdist
+        shell: bash
+        run: python -m build
+      - name: Verify wheel install in clean env
+        shell: bash
+        run: |
+          python -m venv .venv_wheel
+          . .venv_wheel/bin/activate 2>/dev/null || . .venv_wheel/Scripts/activate 2>/dev/null
+          pip install dist/*.whl
+          bitranox_template_py_cli --version || python -m bitranox_template_py_cli --version
+
+  pipx-uv:
+    name: pipx/uv verification (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: pipx install from wheel
+        run: |
+          python -m pip install pipx
+          pipx install dist/*.whl
+          bitranox_template_py_cli --version
+      - name: uv tool install
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$HOME/.local/share/uv/bin:$PATH"
+          uv tool install .
+          bitranox_template_py_cli --version
+
+  # nix and conda packaging builds are disabled for now to keep CI green.
+  nix:
+    name: Nix build (flake)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Nix (flakes)
+        uses: cachix/install-nix-action@v27
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+      - name: Build with Nix flake
+        working-directory: packaging/nix
+        run: |
+          nix build .#default -L
+          echo "Built path: $(readlink -f result || true)"
+
+  conda:
+    name: Conda build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Miniconda
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: true
+          python-version: "3.12"
+      - name: Build conda recipe (local source, no test)
+        shell: bash -l {0}
+        env:
+          CONDA_USE_LOCAL: "1"
+        run: |
+          conda config --add channels conda-forge
+          conda config --add channels defaults
+          conda install -y conda-build
+          conda build packaging/conda/recipe --no-test -c conda-forge -c defaults
+
+  notebooks:
+    name: Execute notebooks (ubuntu, Python 3.10)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install notebook runner deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install nbclient nbformat ipykernel jupyter_client
+          python -m ipykernel install --user --name python3 --display-name "Python 3"
+      - name: Execute Quickstart notebook
+        env:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+          PIP_NO_INPUT: "1"
+        run: |
+          python - << 'PY'
+          import json, sys
+          from pathlib import Path
+          import nbformat
+          try:
+              from nbformat.validator import normalize  # type: ignore
+          except Exception:
+              normalize = None  # type: ignore
+          from nbclient import NotebookClient
+
+          nb_path = Path('notebooks/Quickstart.ipynb')
+          if not nb_path.exists():
+              raise SystemExit(f"Notebook not found: {nb_path}")
+
+          with nb_path.open('r', encoding='utf-8') as f:
+              nb = nbformat.read(f, as_version=4)
+          # Normalize to ensure required fields like cell ids are present (supports older nbformat return types)
+          if normalize is not None:
+              nb_norm = normalize(nb)  # may return notebook or a tuple
+              # pick the first element that looks like a notebook
+              cand = nb_norm
+              if isinstance(nb_norm, tuple):
+                  for item in nb_norm:
+                      if hasattr(item, 'cells') and hasattr(item, 'metadata'):
+                          cand = item
+                          break
+              nb = cand
+          # Final guard for robustness
+          if isinstance(nb, tuple) or not (hasattr(nb, 'cells') and hasattr(nb, 'metadata')):
+              raise SystemExit(f"Unexpected notebook object type after normalize: {type(nb)}")
+
+          client = NotebookClient(nb, timeout=900, kernel_name='python3', allow_errors=False)
+          client.execute()
+
+          # Optionally write executed notebook artifact (not committed)
+          out_path = Path('notebooks/Quickstart-executed.ipynb')
+          with out_path.open('w', encoding='utf-8') as f:
+              nbformat.write(nb, f)
+          print(f"Executed notebook written to: {out_path}")
+          PY
+
+  packaging-consistency:
+    name: Packaging files in sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Verify packaging matches pyproject
+        run: |
+          python - << 'PY'
+          import re, sys
+          from pathlib import Path
+
+          py = Path('pyproject.toml').read_text(encoding='utf-8')
+          m_ver = re.search(r'^version\s*=\s*"([^"]+)"', py, re.M)
+          m_req = re.search(r'^requires-python\s*=\s*"([^"]+)"', py, re.M)
+          if not (m_ver and m_req):
+            print('pyproject missing version or requires-python'); sys.exit(1)
+          version = m_ver.group(1)
+          requires = m_req.group(1)
+          m_min = re.search(r'>=\s*(3\.[0-9]+)', requires)
+          if not m_min:
+            print('requires-python must be like ">=3.X"'); sys.exit(1)
+          min_py = m_min.group(1)
+          min_digits = min_py.replace('.', '')
+
+          # Conda
+          conda = Path('packaging/conda/recipe/meta.yaml').read_text(encoding='utf-8')
+          if not re.search(r'\{\%\s*set\s+version\s*=\s*"' + re.escape(version) + r'"\s*\%\}', conda):
+            print('conda/meta.yaml: version mismatch'); sys.exit(1)
+          if len(re.findall(r'python\s*>?=\s*' + re.escape(min_py), conda)) < 2:
+            print('conda/meta.yaml: python constraint not aligned (host/run)'); sys.exit(1)
+
+          # Brew
+          brew = Path('packaging/brew/Formula/bitranox-template-py-cli.rb').read_text(encoding='utf-8')
+          if f"refs/tags/v{version}.tar.gz" not in brew:
+            print('brew formula: url tag mismatch'); sys.exit(1)
+          if f'"python@{min_py}"' not in brew:
+            print('brew formula: python dependency not aligned'); sys.exit(1)
+
+          # Nix
+          nix = Path('packaging/nix/flake.nix').read_text(encoding='utf-8')
+          if not re.search(r'pname\s*=\s*"bitranox_template_py_cli";\s*[^}]*?version\s*=\s*"' + re.escape(version) + r'";', nix, re.S):
+            print('nix flake: version mismatch'); sys.exit(1)
+          if not re.search(r'pypkgs\s*=\s*pkgs\.python' + re.escape(min_digits) + r'Packages', nix):
+            print('nix flake: python package set not aligned'); sys.exit(1)
+          if not re.search(r'pkgs\.python' + re.escape(min_digits) + r'\b', nix):
+            print('nix flake: devShell python not aligned'); sys.exit(1)
+          print('Packaging files are consistent with pyproject.')
+          PY

bitranox_template_py_cli-1.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,40 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    - cron: '0 8 * * 1'
+
+jobs:
+  analyze:
+    name: CodeQL Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"
+

bitranox_template_py_cli-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch: {}
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify PyPI token is set
+        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
+          fi
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build artifacts
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Publish to PyPI
+        # Use the rolling major tag to get latest Twine/standards support (e.g., Core Metadata 2.4)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

bitranox_template_py_cli-1.0.0/.gitignore

@@ -0,0 +1,179 @@
+# ====================================
+# ROTEK SPEZIFISCH: Git commands you might run once
+# git add .gitignore && git commit -m "Ignore IDE settings"
+# git push
+# git rm -r --cached .idea
+# git commit -m "Remove .idea and add to .gitignore"
+# git push
+# alternative : BE CAREFUL: overwrites remote history
+# git push origin master --force
+
+# ====================================
+# APP
+# ====================================
+website/build/
+website/.docusaurus/
+website/node_modules/
+node_modules/
+web-local-preview/
+translation_app*.log
+translation_web*.log
+tmp_github_web_pages/
+tmp_linkcheck_web_pages/
+.eslintcache
+.vitest/
+npm-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.env.*
+!.env.example
+todo.md
+tmp_*
+
+# ====================================
+# IDEs & Editors
+# ====================================
+# IntelliJ, PyCharm, etc.
+.idea/
+# VS Code workspace settings
+.vscode/
+*.code-workspace
+
+# ====================================
+# Python bytecode & caches
+# ====================================
+# __pycache__: compiled .pyc files at any depth
+# *.py[cod]: catches .pyc, .pyo, .pyd
+__pycache__/
+*.py[cod]
+*$py.class     # other compiled artifacts
+
+# pytest, coverage, MyPy, Hypothesis
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.coverage*
+htmlcov/
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+.nox/
+
+# general cache directories (any project-level caching)
+.cache/
+.run/
+
+# ====================================
+# Build & distribution artifacts
+# ====================================
+# source/package builds
+build/
+dist/
+*.egg-info/    # metadata for pip installs
+*.egg
+*.whl
+pip-wheel-metadata/
+*.manifest     # PyInstaller metadata
+*.spec         # PyInstaller spec files
+
+# Eggs, parts, wheels, sdist, etc.
+develop-eggs/
+.eggs/
+parts/
+sdist/
+wheels/
+downloads/
+var/
+
+# pip logs & installer leftovers
+pip-log.txt
+pip-delete-this-directory.txt
+.installed.cfg
+
+# ====================================
+# Virtual environments & secrets
+# ====================================
+# common venv folder names
+env/
+venv/
+ENV/
+.venv/
+# backups, alternate names
+env.bak/
+venv.bak/
+# dotenv files with credentials
+.env
+
+# ====================================
+# Project-specific & framework files
+# ====================================
+# Django logs & local overrides
+*.log
+local_settings.py
+
+# Flask instance folder
+instance/
+.webassets-cache
+
+# Scrapy cache
+.scrapy
+
+# Sphinx docs
+docs/_build/
+
+# PyBuilder output
+target/
+
+# Jupyter notebooks checkpoints
+.ipynb_checkpoints
+
+# pyenv Python version file
+.python-version
+
+# Celery beat schedule
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Spyder IDE
+.spyderproject
+.spyproject
+
+# Rope IDE
+.ropeproject
+
+# MkDocs static site folder
+/site
+
+# ====================================
+# OS-specific files
+# ====================================
+# macOS
+.DS_Store
+# Windows
+Thumbs.db
+ehthumbs.db
+
+# Archives
+*.zip
+
+# Thunderbird build artifact (created temporarily by pack script)
+sources/manifest.json
+
+# ====================================
+# Tool-specific extras
+# ====================================
+# Codecov uploader script (downloaded during local uploads)
+codecov.sh
+codecov.xml
+
+# Nix build result symlink
+result
+
+# Optional lockfiles (for alternative managers)
+poetry.lock
+pdm.lock
+uv.lock

bitranox_template_py_cli-1.0.0/AGENTS.md

@@ -0,0 +1,131 @@
+# Repository Guidelines
+
+## On session start
+
+- Connect to the `systemprompts` MCP filesystem.
+- Read following files and keep their guidance in working memory:
+  - core_programming_solid.md
+  - bash_clean_architecture.md
+  - bash_clean_code.md
+  - bash_small_functions.md
+  - python_solid_architecture_enforcer.md
+  - python_clean_architecture.md
+  - python_clean_code.md
+  - python_small_functions_style.md
+  - python_libraries_to_use.md
+  - python_structure_template.md
+  - self_documenting.md
+
+
+always apply those Rules :
+
+- core_programming_solid.md
+
+when writing or refracturing Bash scripts, apply those Rules :
+
+- core_programming_solid.md
+- bash_clean_architecture.md
+- bash_clean_code.md
+- bash_small_functions.md
+
+when writing or refracturing Python scripts, apply those Rules :
+- core_programming_solid.md
+- python_solid_architecture_enforcer.md
+- python_clean_architecture.md
+- python_clean_code.md
+- python_small_functions_style.md
+- python_libraries_to_use.md
+- python_lib_structure_template.md
+
+## Project Structure & Module Organization
+
+- `src/bitranox_template_py_cli/`: Python package exposing placeholders for Rich logging helpers.
+- `scripts/`: shared automation (build/test/release) reused from scaffold.
+- `packaging/`: Conda, Homebrew, and Nix specs kept in sync via scripts.
+- `tests/`: placeholder suite skipping until logging features exist.
+
+## Build, Test, and Development Commands
+
+- `make help` — list all targets with one‑line docs.
+- `make test` — run ruff (lint + format check), pyright, pytest with coverage (enabled by default), and upload to Codecov (if configured via `.env`).
+  - Auto‑bootstrap: `make test` installs dev tools (`pip install -e .[dev]`) if linters/test deps are missing. Use `SKIP_BOOTSTRAP=1 make test` to disable.
+  - Coverage control: `COVERAGE=on|auto|off` (default `on` locally). Uses a unique `COVERAGE_FILE` each run to avoid DB locks.
+  - Before uploading to Codecov the harness creates an allow-empty commit (`test: auto commit before Codecov upload`) so the report attaches to a revision. Reset or amend if you do not want to keep it.
+- `make build` — build Python wheel/sdist and attempt Conda/Homebrew/Nix builds (auto‑installs missing tools when needed).
+- `make push` — runs the full `scripts/test.py` flow, prompts for/accepts a commit message (or `COMMIT_MESSAGE`), creates an allow-empty commit if needed, then pushes to the selected remote.
+- `make clean` — remove caches, coverage, and build artifacts (includes `dist/` and `build/`).
+
+### Versioning & Releases
+
+- Single source of truth for the package version is `pyproject.toml` (`[project].version`).
+- Runtime code reads metadata via `importlib.metadata`; do not duplicate the version in code files.
+- On a version bump, update only `pyproject.toml` and the `CHANGELOG.md` entry; do not edit `src/bitranox_template_py_cli/__init__conf__.py` for versioning.
+- Tag releases `vX.Y.Z` and push tags; CI will build artifacts and publish when configured.
+
+### Common Make Targets (Alphabetical)
+
+
+| Target            | One-line description                                                           |
+|-------------------|--------------------------------------------------------------------------------|
+| `build`           | Build wheel/sdist and attempt Conda/Brew/Nix builds (auto-installs tools).     |
+| `bump`            | Bump version (VERSION=X.Y.Z or PART=major\|minor\|patch) and update changelog. |
+| `bump-major`      | Increment major version ((X+1).0.0).                                           |
+| `bump-minor`      | Increment minor version (X.Y.Z → X.(Y+1).0).                                   |
+| `bump-patch`      | Increment patch version (X.Y.Z → X.Y.(Z+1)).                                   |
+| `clean`           | Remove caches, coverage, and build artifacts (includes `dist/` and `build/`).  |
+| `dev`             | Install package with dev extras.                                               |
+| `help`            | Show this table.                                                               |
+| `install`         | Editable install.                                                              |
+| `menu`            | Interactive TUI menu (make menu).                                              |
+| `push`            | Commit changes once and push to GitHub (no CI monitoring).                     |
+| `release`         | Tag vX.Y.Z, push, sync packaging, run gh release if available.                 |
+| `run`             | Run module entry (`python -m ... --help`).                                     |
+| `test`            | Lint, format, type-check, run tests with coverage, upload to Codecov.          |
+| `version-current` | Print current version from `pyproject.toml`.                                   |
+
+## Coding Style & Naming Conventions
+
+- Keep modules and functions snake_case.
+- Prefer dataclasses for configuration objects (see `Config` in `bitranox_template_py_cli`).
+- Rich renderables will live in dedicated helper modules once implemented.
+
+## Testing Guidelines
+
+- Unit and integration-style tests live under `tests/`; keep them up to date when adding features.
+- Extend coverage for new CLI or library behaviour (the suite exercises CLI commands, package metadata, and automation scripts).
+- When adding functionality, replace or remove placeholders and ensure `make test` remains green.
+
+## Commit & Pull Request Guidelines
+
+## Architecture Overview
+
+Placeholder: logging pipeline will organize around Rich renderables managed by a configurable core module and optional CLI utilities.
+
+## Security & Configuration Tips
+
+- `.env` is only for local tooling (CodeCov tokens, etc.); do not commit secrets.
+- Rich logging should sanitize payloads before rendering once implemented.
+
+## Translations (Docs)
+
+## Translations (App UI Strings)
+
+## Changes in WEB Documentation
+
+- when asked to update documentation - only do that in the english docs under /website/docs because other languages will be translated automatically,
+  unless stated otherwise by the user. In doubt - ask the user
+
+## Changes in APP Strings
+
+- when i18 strings are changed, only to that in sources/\_locales/en because other languages will be translated automatically,
+  unless stated otherwise by the user. In doubt - ask the user
+
+## commit/push/GitHub policy
+
+- run "make test" before any push to avoid lint/test breakage.
+- after push, monitor errors in the github actions and try to correct the errors
+
+## documentation
+whenever a new feature, function, configuration, dataclass field, etc. is introduced: 
+  - check first if it aligns with docs/systemdesign/*  
+  - document it in docs/systemdesign/module_reference.md, using the template from self_documenting.md and save it in docs/systemdesign/module_reference.md 

bitranox_template_py_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [1.0.0] - 2025-09-18
+
+- _Describe changes here._
+
+## [Unreleased]
+- Populate once new logging features land.
+
+## [0.1.0] - 2025-09-16
+- Bootstrap `bitranox_template_py_cli` using the shared scaffold.
+- Replace implementation-specific modules with placeholders ready for Rich-based logging.

bitranox_template_py_cli-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing Guide
+
+Thanks for helping improve **bitranox_template_py_cli**. The sections below summarise the day-to-day workflow, highlight the repository automation, and list the checks that must pass before a change is merged.
+
+## 1. Workflow Overview
+
+1. Fork and branch – use short, imperative branch names (`feature/cli-extension`, `fix/codecov-token`).
+2. Make focused commits – keep unrelated refactors out of the same change.
+3. Run `make test` locally before pushing (see the automation note below).
+4. Update documentation and changelog entries that are affected by the change.
+5. Open a pull request referencing any relevant issues.
+
+## 2. Commits & Pushes
+
+- Commit messages should be imperative (`Add rich handler`, `Fix CLI exit codes`).
+- The test harness (`make test`) performs an allow-empty commit named `test: auto commit before Codecov upload` immediately before it sends coverage to Codecov. This guarantees Codecov sees a concrete revision. If you do not want to retain that commit, run `git reset --soft HEAD~1` (or amend) after the test run finishes.
+- `make push` always performs a commit before pushing. It prompts for a message when run interactively, honours `COMMIT_MESSAGE="…"` when provided, and creates an empty commit if nothing is staged. The Textual menu (`make menu → push`) exposes the same behaviour via an input field.
+
+## 3. Coding Standards
+
+- Apply the repository’s Clean Architecture / SOLID rules (see `AGENTS.md` and the system prompts listed there).
+- Prefer small, single-purpose modules and functions; avoid mixing orthogonal concerns.
+- Free functions and modules use `snake_case`; classes are `PascalCase`.
+- Keep runtime dependencies minimal. Use the standard library where practical.
+
+## 4. Tests & Tooling
+
+- `make test` runs Ruff (lint + format check), Pyright, and Pytest with coverage. Coverage is `on` by default; override with `COVERAGE=off` if you explicitly need a no-coverage run.
+- The harness auto-installs dev tools with `pip install -e .[dev]` when Ruff, Pyright, or Pytest are missing. Skip this by exporting `SKIP_BOOTSTRAP=1`.
+- Codecov uploads require a commit (provided by the automatic commit described above). For private repositories set `CODECOV_TOKEN` in your environment or `.env`.
+
+## 5. Packaging Sync
+
+- Packaging definitions in `packaging/` (Conda, Homebrew, Nix) are kept in sync with `pyproject.toml` whenever you run `make test`, `make push`, or version bump scripts.
+- If you need the sync step without tests, use `python scripts/bump_version.py --sync-packaging`.
+
+## 6. Documentation Checklist
+
+Before opening a PR, confirm the following:
+
+- [ ] `make test` passes locally (and you removed the auto-created Codecov commit if you do not want to keep it).
+- [ ] Relevant documentation (`README.md`, `DEVELOPMENT.md`, `docs/systemdesign/*`) is updated.
+- [ ] No generated artefacts or virtual environments are committed.
+- [ ] Version bumps, when required, touch **only** `pyproject.toml` and `CHANGELOG.md`.
+
+## 7. Security & Configuration
+
+- Never commit secrets. Tokens (Codecov, PyPI) belong in `.env` (ignored by git) or CI secrets.
+- Sanitise any payloads you emit via logging once richer logging features ship.
+
+Happy hacking!