lib-cli-exit-tools 1.3.0__tar.gz → 1.4.0__tar.gz

{lib_cli_exit_tools-1.3.0 → lib_cli_exit_tools-1.4.0}/AGENTS.md

@@ -13,6 +13,8 @@ Review the system prompt files in `/media/srv-main/softdev/*/projects/softwarest
 - python_structure_template.md
 - self_documenting.md
 - self_documenting_template.md
+- python_jupyter_notebooks.md
+- python_testing.md
 
 always apply those Rules :
 
@@ -41,18 +43,6 @@ when writing or refracturing Python scripts, apply those Rules :
 - `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`).
@@ -84,13 +74,6 @@ when writing or refracturing Python scripts, apply those Rules :
 
 ## Coding Style & Naming Conventions
 
-## 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.
-- write good doctests which clearly show how the function works and what are the intensions. Use it as an enhancement of the inline documentation
-
 ## Commit & Pull Request Guidelines
 
 ## Architecture Overview
@@ -119,13 +102,10 @@ when writing or refracturing Python scripts, apply those Rules :
 - 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
 
-## Jupyter Notebooks
-use at least nbformat >=4.5 
- - "nbformat": 4,
- - "nbformat_minor": 5
-
 ---
 
+# ONLY ON USER REQEST !!!! :
+
 # 📘 Documentation Review & Enhancement Prompt
 
 You are a **senior software developer specializing in code documentation and system design clarity**. Your task is to review, correct, and enhance all documentation (external and inline) across the codebase with the following principles and workflow.

{lib_cli_exit_tools-1.3.0 → lib_cli_exit_tools-1.4.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.4.0] - 2025-09-26
+
+- Reafracture, TestSuite
+
+## [1.3.1] - 2025-09-26
+
+- patch colored traceback
+
 ## [1.3.0] - 2025-09-25
 
 - colored traceback
@@ -47,6 +55,8 @@
 - Metadata lookup in `__init__conf__` resolved once and reused.
 - Coverage gate relaxed to 80% and removed `# pragma: no cover` comments.
 - Quickstart notebook defaults to install from GitHub; added cell IDs; last cell prints exit code example instead of exiting.
+- Repartitioned the exit tooling into `core`, `adapters`, and `application` packages with `lib_cli_exit_tools` now acting as a facade to preserve import paths.
+- `run_cli` accepts injectable `exception_handler` and `signal_installer` hooks; CLI rich-click configuration now runs during `main()` execution instead of at import time.
 
 ### Fixed
 - Pyright 3.10 compatibility in `__init__conf__` by typing to a minimal metadata protocol; resolved unknown `.get` errors.

lib_cli_exit_tools-1.4.0/INSTALL.md

@@ -0,0 +1,184 @@
+# Installation Guide
+
+This document collects every supported installation path for `lib_cli_exit_tools`, plus notes on platform quirks and troubleshooting. If you only need the standard release from PyPI, see the short "Install" section in `README.md` or run:
+
+```bash
+pip install lib_cli_exit_tools
+```
+
+The sections below cover more specialised workflows, from editable installs to package-manager builds.
+
+## Table of Contents
+- [Supported Python Versions](#supported-python-versions)
+- [Installation Flows](#installation-flows)
+  - [PyPI (latest release)](#pypi-latest-release)
+  - [Editable install in a virtual environment](#editable-install-in-a-virtual-environment)
+  - [Per-user installs (`pip --user`)](#per-user-installs-pip---user)
+  - [pipx](#pipx)
+  - [uv](#uv)
+  - [Installing from local artifacts](#installing-from-local-artifacts)
+  - [Poetry / PDM](#poetry--pdm)
+  - [Install directly from Git](#install-directly-from-git)
+  - [Conda / Mamba environments](#conda--mamba-environments)
+  - [System package managers](#system-package-managers)
+- [Path configuration](#path-configuration)
+- [Troubleshooting](#troubleshooting)
+  - [PEP 668 “externally managed environment” errors](#pep-668-externally-managed-environment-errors)
+  - [Missing command on PATH](#missing-command-on-path)
+  - [Colour output not appearing](#colour-output-not-appearing)
+
+## Supported Python Versions
+
+`lib_cli_exit_tools` targets Python 3.9 and newer. Wheels are published for CPython on Linux, macOS, and Windows. For alternative interpreters (PyPy) install from source using `pip install lib_cli_exit_tools`.
+
+## Installation Flows
+
+### PyPI (latest release)
+
+The quickest path for production use:
+
+```bash
+pip install lib_cli_exit_tools
+# Pin to a specific release when reproducibility matters
+pip install "lib_cli_exit_tools==1.1.0"
+# Upgrade later
+pip install --upgrade lib_cli_exit_tools
+```
+
+This command registers the `lib_cli_exit_tools`, `cli-exit-tools`, and `lib-cli-exit-tools` entry points on your PATH.
+
+### Editable install in a virtual environment
+
+Use this flow when developing the library locally:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e .[dev]
+# Alternatively, install runtime dependencies only
+pip install .
+```
+
+### Per-user installs (`pip --user`)
+
+Install to the user site-packages directory without creating a virtual environment:
+
+```bash
+pip install --user lib_cli_exit_tools
+```
+
+Ensure `~/.local/bin` (POSIX) or `%APPDATA%\Python\PythonXY\Scripts` (Windows) is on your PATH. This approach respects [PEP 668](https://peps.python.org/pep-0668/)—avoid running it in system-managed Python installs that disallow modifications.
+
+### pipx
+
+`pipx` isolates CLI tools in dedicated environments, making upgrades easy:
+
+```bash
+pipx install lib_cli_exit_tools
+pipx upgrade lib_cli_exit_tools
+# Install directly from a tagged release or commit
+pipx install "git+https://github.com/bitranox/lib_cli_exit_tools@v1.1.0"
+```
+
+### uv
+
+[uv](https://github.com/astral-sh/uv) provides fast installs and execution:
+
+```bash
+uv pip install -e .[dev]
+uv tool install lib_cli_exit_tools
+uvx lib_cli_exit_tools --help
+```
+
+### Installing from local artifacts
+
+Build a wheel or sdist locally and install it in offline environments:
+
+```bash
+python -m build
+pip install dist/lib_cli_exit_tools-*.whl
+pip install dist/lib_cli_exit_tools-*.tar.gz
+```
+
+### Poetry / PDM
+
+Add the library to a project managed by Poetry or PDM:
+
+```bash
+# Poetry
+poetry add lib_cli_exit_tools
+poetry install
+
+# PDM
+pdm add lib_cli_exit_tools
+pdm install
+```
+
+### Install directly from Git
+
+CI systems or early adopters can install from a specific revision:
+
+```bash
+pip install "git+https://github.com/bitranox/lib_cli_exit_tools@v1.1.0#egg=lib_cli_exit_tools"
+```
+
+### Conda / Mamba environments
+
+Create a dedicated Conda environment and install via `pip` inside it:
+
+```bash
+mamba create -n cli-exit python=3.12 pip
+mamba activate cli-exit
+pip install lib_cli_exit_tools
+```
+
+### System package managers
+
+Packages may be published for platform-native installers:
+
+- **Homebrew (macOS):** `brew install lib_cli_exit_tools`
+- **Nix:** `nix run github:bitranox/lib_cli_exit_tools` or `nix develop` with the provided flake
+- **Deb/RPM:** build with `fpm` using the project’s `packaging/` scripts
+
+Check the repository’s release notes for the current distribution status.
+
+## Path configuration
+
+After installation the following commands should resolve:
+
+- `lib_cli_exit_tools`
+- `cli-exit-tools`
+- `python -m lib_cli_exit_tools`
+
+If you installed inside a virtual environment, activate it before running the commands. For user installs, ensure the relevant `bin`/`Scripts` directory is included in your PATH:
+
+- Linux/macOS venv: `<venv>/bin`
+- Linux/macOS user site: `~/.local/bin`
+- Windows venv: `<venv>\Scripts`
+- Windows user site: `%APPDATA%\Python\PythonXY\Scripts`
+
+## Troubleshooting
+
+### PEP 668 “externally managed environment” errors
+
+Some OS distributions (Ubuntu, Fedora, Debian) mark the system Python as externally managed. Running `pip install` directly into that interpreter raises an error similar to:
+
+```
+error: externally-managed-environment
+```
+
+**Fix:**
+- Create a virtual environment (`python -m venv .venv`) and install inside it, or
+- Use `pipx`, `conda`, `uv`, or another isolated environment manager.
+
+### Missing command on PATH
+
+If `lib_cli_exit_tools --help` returns “command not found”, confirm that the installation location is on PATH. The most common fix is adding `~/.local/bin` (POSIX) or `%APPDATA%\Python\PythonXY\Scripts` (Windows) to your PATH environment variable, then re-opening the shell.
+
+### Colour output not appearing
+
+Set `lib_cli_exit_tools.config.traceback_force_color = True` in your application to force Rich to emit coloured tracebacks even when stderr is not detected as a TTY. Alternatively, export `RICH_FORCE_TERMINAL=1` before running the CLI.
+
+---
+
+For additional environment automation (Conda, Nix, Homebrew formulas), consult the scripts under `packaging/` and the Makefile targets described in `README.md`.

{lib_cli_exit_tools-1.3.0 → lib_cli_exit_tools-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lib_cli_exit_tools
-Version: 1.3.0
+Version: 1.4.0
 Summary: CLI exit handling helpers: clean signals, exit codes, and error printing
 Project-URL: Homepage, https://github.com/bitranox/lib_cli_exit_tools
 Project-URL: Repository, https://github.com/bitranox/lib_cli_exit_tools.git
@@ -50,93 +50,11 @@ Small helpers for robust CLI exit handling:
 
 ## Install
 
-Pick one of the options below. All methods register the `lib_cli_exit_tools`, `cli-exit-tools`, and `lib-cli-exit-tools` commands on your PATH.
-
-### 0) PyPI (latest release)
-
 ```bash
 pip install lib_cli_exit_tools
-# Pin to the current release if you need reproducibility
-pip install "lib_cli_exit_tools==1.1.0"
-# Upgrade to the newest release later
-pip install --upgrade lib_cli_exit_tools
-```
-
-### 1) Standard virtualenv (pip)
-
-```bash
-python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
-pip install -e .[dev]       # dev install
-# or for runtime only:
-pip install .
-```
-
-### 2) Per-user (no venv)
-
-```bash
-pip install --user .
-```
-
-Note: respects PEP 668; avoid on system Python if “externally managed”. Ensure `~/.local/bin` (POSIX) is on PATH.
-
-### 3) pipx (isolated, recommended for end users)
-
-```bash
-pipx install .
-pipx upgrade lib_cli_exit_tools
-# From Git tag/commit:
-pipx install "git+https://github.com/bitranox/lib_cli_exit_tools@v1.1.0"
-```
-
-### 4) uv (fast installer/runner)
-
-```bash
-uv pip install -e .[dev]
-uv tool install .
-uvx lib_cli_exit_tools --help
-```
-
-### 5) From artifacts
-
-```bash
-python -m build
-pip install dist/lib_cli_exit_tools-*.whl
-pip install dist/lib_cli_exit_tools-*.tar.gz   # sdist
-```
-
-### 6) Poetry / PDM (project-managed envs)
-
-```bash
-# Poetry
-poetry add lib_cli_exit_tools     # as dependency
-poetry install                    # for local dev
-
-# PDM
-pdm add lib_cli_exit_tools
-pdm install
-```
-
-### 7) From Git via pip (CI-friendly)
-
-```bash
-pip install "git+https://github.com/bitranox/lib_cli_exit_tools@v1.1.0#egg=lib_cli_exit_tools"
 ```
 
-### 8) Conda/mamba (optional)
-
-```bash
-mamba create -n cli-exit python=3.12 pip
-mamba activate cli-exit
-pip install .
-```
-
-### 9) System package managers (optional distribution)
-
-- Homebrew formula (macOS): `brew install lib_cli_exit_tools` (if published)
-- Nix: flake/package for reproducible installs
-- Deb/RPM via `fpm` for OS-native packages
-
+See [INSTALL.md](INSTALL.md) for editable installs, pipx/uv, package-manager builds, and troubleshooting tips.
 
 ## Usage
 
@@ -225,6 +143,91 @@ Field reference:
 
 Remember that `config` is module-level—if you call the library from multiple threads or embed it in another CLI, configure it once during bootstrap before handing control to user code.
 
+## Public API Reference
+
+The package re-exports the helpers below via `lib_cli_exit_tools.__all__`. Import them directly with `from lib_cli_exit_tools import …`.
+
+### `config`
+Mutable dataclass-like singleton holding process-wide settings. Configure it during CLI startup.
+
+- `traceback` (`bool`): `True` to surface full Python tracebacks; `False` keeps short, coloured summaries.
+- `exit_code_style` (`'errno' | 'sysexits'`): Selects POSIX/Windows errno-style exit codes or BSD `sysexits` semantics.
+- `broken_pipe_exit_code` (`int`): Overrides the exit status for `BrokenPipeError` (default `141`).
+- `traceback_force_color` (`bool`): Forces Rich-coloured tracebacks even when stderr is not a TTY.
+
+### `run_cli(cli, argv=None, *, prog_name=None, signal_specs=None, install_signals=True, exception_handler=None, signal_installer=None) -> int`
+Wrap a Click command or group so every invocation shares the same signal handling and exit-code policy. Returns the numeric exit code instead of exiting the process.
+
+Parameters:
+- `cli`: `click.BaseCommand` to execute.
+- `argv`: Optional iterable of CLI arguments (excluding program name).
+- `prog_name`: Override the program name shown in help/version output.
+- `signal_specs`: Iterable of `SignalSpec` objects to customise signal handling; defaults to `default_signal_specs()`.
+- `install_signals`: Set `False` when the host application already manages signal handlers.
+- `exception_handler`: Optional callable receiving the raised exception and returning an exit code; defaults to ``handle_cli_exception``.
+- `signal_installer`: Optional callable mirroring ``install_signal_handlers`` for embedding scenarios.
+
+### `handle_cli_exception(exc, *, signal_specs=None, echo=None) -> int`
+Translate exceptions raised by Click commands into deterministic exit codes, honouring configured signal mappings and traceback policy.
+
+Parameters:
+- `exc`: Exception instance to classify.
+- `signal_specs`: Optional iterable of `SignalSpec` objects for custom signal handling.
+- `echo`: Callable matching `click.echo` signature, allowing custom stderr routing during tests or embedding.
+
+### `get_system_exit_code(exc) -> int`
+Compute a platform-aware exit status for arbitrary exceptions (errno mappings on POSIX/Windows or BSD `sysexits` when enabled).
+
+Parameters:
+- `exc`: Exception instance to classify.
+
+### `print_exception_message(trace_back=config.traceback, length_limit=500, stream=None) -> None`
+Emit the active exception using Rich formatting. Produces a coloured traceback when `trace_back` is `True`, otherwise prints a truncated summary in red. Respects `config.traceback_force_color`.
+
+Parameters:
+- `trace_back`: Toggle between full traceback rendering (`True`) and short summary (`False`).
+- `length_limit`: Maximum characters for summary output.
+- `stream`: Target text stream; defaults to `sys.stderr`.
+
+### `flush_streams() -> None`
+Best-effort flush of `sys.stdout` and `sys.stderr`, ensuring buffered output is written before exit.
+
+### `default_signal_specs() -> list[SignalSpec]`
+Return the default signal mapping for the current platform (always includes `SIGINT`, plus `SIGTERM`/`SIGBREAK` when available).
+
+### `install_signal_handlers(specs=None) -> Callable[[], None]`
+Register handlers that raise structured exceptions for the provided specs and return a restoration callback. Invoke the callback (typically in a `finally` block) to restore previous handlers.
+
+Parameters:
+- `specs`: Iterable of `SignalSpec` objects; defaults to `default_signal_specs()`.
+
+### `SignalSpec(signum: int, exception: type[BaseException], message: str, exit_code: int)`
+Lightweight dataclass describing how a signal maps to an exception, stderr message, and exit code.
+
+Fields:
+- `signum`: Numeric signal value passed to `signal.signal`.
+- `exception`: Exception type raised by the handler.
+- `message`: Human-readable text echoed when the signal fires.
+- `exit_code`: Exit status returned to the OS.
+
+### `CliSignalError` and subclasses
+Hierarchy of marker exceptions raised when signal handlers trigger. Use them to differentiate signal-driven exits from other failures.
+
+- `CliSignalError`: Base class.
+- `SigIntInterrupt`: Raised on `SIGINT` (Ctrl+C); maps to exit code `130`.
+- `SigTermInterrupt`: Raised on `SIGTERM`; maps to exit code `143`.
+- `SigBreakInterrupt`: Raised on Windows `SIGBREAK`; maps to exit code `149`.
+
+### `default_signal_specs`, `install_signal_handlers`, and `run_cli` contract summary
+When `run_cli` executes your Click command it will:
+1. Build a signal spec list (custom or default).
+2. Optionally install handlers that raise the exceptions above.
+3. Execute the command with `standalone_mode=False`.
+4. Funnel any exception through `handle_cli_exception`.
+5. Restore prior signal handlers and flush streams before returning (or rely on any injected replacements).
+
+This behaviour keeps CLI wiring consistent across projects embedding `lib_cli_exit_tools` while still allowing custom hooks when needed.
+
 ### Advanced CLI wiring
 
 For larger applications, keep module execution, console scripts, and shared helpers aligned. The snippet below shows how `__main__.py` can catch unexpected errors and map them through `lib_cli_exit_tools` before exiting:
@@ -327,11 +330,11 @@ When installed, the generated console scripts (`lib_cli_exit_tools`, `cli-exit-t
 - Set `config.exit_code_style = "sysexits"` to map ValueError/TypeError → EX_USAGE(64),
   FileNotFoundError → EX_NOINPUT(66), PermissionError → EX_NOPERM(77), generic OSError → EX_IOERR(74).
 
-## Development
-
-See [DEVELOPMENT.md](DEVELOPMENT.md) for contributor workflows, make targets, packaging sync details, and CI/publishing guidance.
-
-
-## License
+## Additional Documentation
 
-MIT
+- [INSTALL](INSTALL.md)
+- [CHANGELOG](CHANGELOG.md)
+- [CONTRIBUTING](CONTRIBUTING.md)
+- [DEVELOPMENT](DEVELOPMENT.md)
+- [MODULE REFERENCE](docs/system-design/module_reference.md)
+- [LICENSE](LICENSE)

{lib_cli_exit_tools-1.3.0 → lib_cli_exit_tools-1.4.0}/README.md

@@ -19,93 +19,11 @@ Small helpers for robust CLI exit handling:
 
 ## Install
 
-Pick one of the options below. All methods register the `lib_cli_exit_tools`, `cli-exit-tools`, and `lib-cli-exit-tools` commands on your PATH.
-
-### 0) PyPI (latest release)
-
 ```bash
 pip install lib_cli_exit_tools
-# Pin to the current release if you need reproducibility
-pip install "lib_cli_exit_tools==1.1.0"
-# Upgrade to the newest release later
-pip install --upgrade lib_cli_exit_tools
-```
-
-### 1) Standard virtualenv (pip)
-
-```bash
-python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
-pip install -e .[dev]       # dev install
-# or for runtime only:
-pip install .
-```
-
-### 2) Per-user (no venv)
-
-```bash
-pip install --user .
-```
-
-Note: respects PEP 668; avoid on system Python if “externally managed”. Ensure `~/.local/bin` (POSIX) is on PATH.
-
-### 3) pipx (isolated, recommended for end users)
-
-```bash
-pipx install .
-pipx upgrade lib_cli_exit_tools
-# From Git tag/commit:
-pipx install "git+https://github.com/bitranox/lib_cli_exit_tools@v1.1.0"
-```
-
-### 4) uv (fast installer/runner)
-
-```bash
-uv pip install -e .[dev]
-uv tool install .
-uvx lib_cli_exit_tools --help
-```
-
-### 5) From artifacts
-
-```bash
-python -m build
-pip install dist/lib_cli_exit_tools-*.whl
-pip install dist/lib_cli_exit_tools-*.tar.gz   # sdist
-```
-
-### 6) Poetry / PDM (project-managed envs)
-
-```bash
-# Poetry
-poetry add lib_cli_exit_tools     # as dependency
-poetry install                    # for local dev
-
-# PDM
-pdm add lib_cli_exit_tools
-pdm install
-```
-
-### 7) From Git via pip (CI-friendly)
-
-```bash
-pip install "git+https://github.com/bitranox/lib_cli_exit_tools@v1.1.0#egg=lib_cli_exit_tools"
 ```
 
-### 8) Conda/mamba (optional)
-
-```bash
-mamba create -n cli-exit python=3.12 pip
-mamba activate cli-exit
-pip install .
-```
-
-### 9) System package managers (optional distribution)
-
-- Homebrew formula (macOS): `brew install lib_cli_exit_tools` (if published)
-- Nix: flake/package for reproducible installs
-- Deb/RPM via `fpm` for OS-native packages
-
+See [INSTALL.md](INSTALL.md) for editable installs, pipx/uv, package-manager builds, and troubleshooting tips.
 
 ## Usage
 
@@ -194,6 +112,91 @@ Field reference:
 
 Remember that `config` is module-level—if you call the library from multiple threads or embed it in another CLI, configure it once during bootstrap before handing control to user code.
 
+## Public API Reference
+
+The package re-exports the helpers below via `lib_cli_exit_tools.__all__`. Import them directly with `from lib_cli_exit_tools import …`.
+
+### `config`
+Mutable dataclass-like singleton holding process-wide settings. Configure it during CLI startup.
+
+- `traceback` (`bool`): `True` to surface full Python tracebacks; `False` keeps short, coloured summaries.
+- `exit_code_style` (`'errno' | 'sysexits'`): Selects POSIX/Windows errno-style exit codes or BSD `sysexits` semantics.
+- `broken_pipe_exit_code` (`int`): Overrides the exit status for `BrokenPipeError` (default `141`).
+- `traceback_force_color` (`bool`): Forces Rich-coloured tracebacks even when stderr is not a TTY.
+
+### `run_cli(cli, argv=None, *, prog_name=None, signal_specs=None, install_signals=True, exception_handler=None, signal_installer=None) -> int`
+Wrap a Click command or group so every invocation shares the same signal handling and exit-code policy. Returns the numeric exit code instead of exiting the process.
+
+Parameters:
+- `cli`: `click.BaseCommand` to execute.
+- `argv`: Optional iterable of CLI arguments (excluding program name).
+- `prog_name`: Override the program name shown in help/version output.
+- `signal_specs`: Iterable of `SignalSpec` objects to customise signal handling; defaults to `default_signal_specs()`.
+- `install_signals`: Set `False` when the host application already manages signal handlers.
+- `exception_handler`: Optional callable receiving the raised exception and returning an exit code; defaults to ``handle_cli_exception``.
+- `signal_installer`: Optional callable mirroring ``install_signal_handlers`` for embedding scenarios.
+
+### `handle_cli_exception(exc, *, signal_specs=None, echo=None) -> int`
+Translate exceptions raised by Click commands into deterministic exit codes, honouring configured signal mappings and traceback policy.
+
+Parameters:
+- `exc`: Exception instance to classify.
+- `signal_specs`: Optional iterable of `SignalSpec` objects for custom signal handling.
+- `echo`: Callable matching `click.echo` signature, allowing custom stderr routing during tests or embedding.
+
+### `get_system_exit_code(exc) -> int`
+Compute a platform-aware exit status for arbitrary exceptions (errno mappings on POSIX/Windows or BSD `sysexits` when enabled).
+
+Parameters:
+- `exc`: Exception instance to classify.
+
+### `print_exception_message(trace_back=config.traceback, length_limit=500, stream=None) -> None`
+Emit the active exception using Rich formatting. Produces a coloured traceback when `trace_back` is `True`, otherwise prints a truncated summary in red. Respects `config.traceback_force_color`.
+
+Parameters:
+- `trace_back`: Toggle between full traceback rendering (`True`) and short summary (`False`).
+- `length_limit`: Maximum characters for summary output.
+- `stream`: Target text stream; defaults to `sys.stderr`.
+
+### `flush_streams() -> None`
+Best-effort flush of `sys.stdout` and `sys.stderr`, ensuring buffered output is written before exit.
+
+### `default_signal_specs() -> list[SignalSpec]`
+Return the default signal mapping for the current platform (always includes `SIGINT`, plus `SIGTERM`/`SIGBREAK` when available).
+
+### `install_signal_handlers(specs=None) -> Callable[[], None]`
+Register handlers that raise structured exceptions for the provided specs and return a restoration callback. Invoke the callback (typically in a `finally` block) to restore previous handlers.
+
+Parameters:
+- `specs`: Iterable of `SignalSpec` objects; defaults to `default_signal_specs()`.
+
+### `SignalSpec(signum: int, exception: type[BaseException], message: str, exit_code: int)`
+Lightweight dataclass describing how a signal maps to an exception, stderr message, and exit code.
+
+Fields:
+- `signum`: Numeric signal value passed to `signal.signal`.
+- `exception`: Exception type raised by the handler.
+- `message`: Human-readable text echoed when the signal fires.
+- `exit_code`: Exit status returned to the OS.
+
+### `CliSignalError` and subclasses
+Hierarchy of marker exceptions raised when signal handlers trigger. Use them to differentiate signal-driven exits from other failures.
+
+- `CliSignalError`: Base class.
+- `SigIntInterrupt`: Raised on `SIGINT` (Ctrl+C); maps to exit code `130`.
+- `SigTermInterrupt`: Raised on `SIGTERM`; maps to exit code `143`.
+- `SigBreakInterrupt`: Raised on Windows `SIGBREAK`; maps to exit code `149`.
+
+### `default_signal_specs`, `install_signal_handlers`, and `run_cli` contract summary
+When `run_cli` executes your Click command it will:
+1. Build a signal spec list (custom or default).
+2. Optionally install handlers that raise the exceptions above.
+3. Execute the command with `standalone_mode=False`.
+4. Funnel any exception through `handle_cli_exception`.
+5. Restore prior signal handlers and flush streams before returning (or rely on any injected replacements).
+
+This behaviour keeps CLI wiring consistent across projects embedding `lib_cli_exit_tools` while still allowing custom hooks when needed.
+
 ### Advanced CLI wiring
 
 For larger applications, keep module execution, console scripts, and shared helpers aligned. The snippet below shows how `__main__.py` can catch unexpected errors and map them through `lib_cli_exit_tools` before exiting:
@@ -296,11 +299,11 @@ When installed, the generated console scripts (`lib_cli_exit_tools`, `cli-exit-t
 - Set `config.exit_code_style = "sysexits"` to map ValueError/TypeError → EX_USAGE(64),
   FileNotFoundError → EX_NOINPUT(66), PermissionError → EX_NOPERM(77), generic OSError → EX_IOERR(74).
 
-## Development
-
-See [DEVELOPMENT.md](DEVELOPMENT.md) for contributor workflows, make targets, packaging sync details, and CI/publishing guidance.
-
-
-## License
+## Additional Documentation
 
-MIT
+- [INSTALL](INSTALL.md)
+- [CHANGELOG](CHANGELOG.md)
+- [CONTRIBUTING](CONTRIBUTING.md)
+- [DEVELOPMENT](DEVELOPMENT.md)
+- [MODULE REFERENCE](docs/system-design/module_reference.md)
+- [LICENSE](LICENSE)