updated and fixed doc (markdown spellcheck)

README.md

@@ -1,25 +1,30 @@
 # profile
+
 This project aims to create an advanced bash profile. It includes aliases,
 a customized prompt and several functions for different purposes. It's mostly
 targeted to system administrators but might satisfy some regular users.
 
 ## 1. Requirements
+
 profile requires **Bash 4.3 or higher** (for associative arrays and namerefs).
 It will refuse to load on older versions and will also refuse to load if the
 current shell is not bash.
 
 ## 2. Getting started
+
 Download and extract (or use git clone) the profile archive into your home
 directory.
 
 The profile is designed to be **sourced**, not executed directly.
 
 Manual setup:
+
 ```bash
 source <installpath>/profile/profile.sh
 ```
 
 Automatic setup (recommended):
+
 ```bash
 bash <installpath>/profile/profile.sh --install
 ```
@@ -34,6 +39,7 @@ bash <installpath>/profile/profile.sh --install --profile
 
 You may also set the `PROFILE_PATH` environment variable before sourcing if you
 want to override the automatic path detection:
+
 ```bash
 export PROFILE_PATH=/opt/profile
 source /opt/profile/profile.sh
@@ -48,6 +54,7 @@ files might interfere with some aliases and functions defined in profile.
 
 In interactive shells (typical terminal sessions), profile enables
 interactive-only features such as:
+
 - aliases from `[aliases]`
 - bash completion scripts from `profile.d/bash-completion/`
 - prompt initialization (`PROMPT_COMMAND` and timer hook)
@@ -58,20 +65,25 @@ intentionally skipped to avoid side effects and startup noise. Public functions
 remain available after sourcing, so scripts can still call profile helpers.
 
 ### 2.2. Initial configuration
+
 Copy the example configuration file and customise it to your needs:
+
 ```bash
 cp <installpath>/profile/doc/profile.conf.example <installpath>/profile/profile.conf
 ```
+
 `profile.conf` is git-ignored so your personal settings will never be
 accidentally committed. All keys are optional — sensible defaults apply when
 unset. See [section 4](#4-configuration) for the full reference.
 
 ## 3. What's the purpose?
+
 profile gives access to numerous functions, aliases and to an advanced prompt.
 All functions are organized into modules under the `profile.d/` directory and
 are loaded automatically at startup.
 
 ### 3.1. Prompt
+
 A bar-style prompt showing current time, execution time of the last command
 (with sub-millisecond precision), and the exit code of the last command.
 
@@ -129,6 +141,7 @@ A bar-style prompt showing current time, execution time of the last command
 | `showinfo` | info | Display welcome banner and system information (figlet + neofetch/fastfetch) |
 | `ssr` | ssh | SSH into a server as root, forwarding extra ssh options |
 | `taz` | compress | Compress files and directories into a chosen archive format |
+| `term_set` | conf | Set `TERM` to the best available terminal capability |
 | `urlencode` | net | URL-encode a string |
 | `utaz` | compress | Smartly uncompress archives (zip, tar.gz/bz2/xz/lz, rar, arj, lha, ace, 7z, zst, cpio, cab, deb, rpm) |
 | `ver` | info | Display the installed profile version |
@@ -144,6 +157,7 @@ any custom completion definitions. profile already ships completions for its git
 helper functions there (`git-completion.sh`).
 
 ## 4. Configuration
+
 profile uses an INI-style configuration file (`profile.conf`) located in the
 same directory as `profile.sh`. Sections are declared with `[section_name]` and
 keys follow `key = value` syntax. Each module calls `load_conf "<section>"` at
@@ -159,10 +173,31 @@ template at `doc/profile.conf.example` (see [section 2.2](#22-initial-configurat
 
 | Section | Purpose |
 | --- | --- |
-| `[system]` | Bash history size, pager, and other shell behaviours |
+| `[system]` | Bash history size, pager, terminal type, and other shell behaviours |
 | `[general]` | General-purpose variables (e.g. compilation flags, `MAKEFLAGS`) |
 | `[aliases]` | User command aliases, loaded for interactive shells only |
 
+#### `TERM` — terminal type detection
+
+The `TERM` key in `[system]` has special handling via `term_set`, which runs
+automatically at startup:
+
+| Value | Behaviour |
+| --- | --- |
+| *(absent or `smart`)* | Auto-detect the best available `terminfo` entry (default) |
+| any other string | Exported as-is — standard Unix behaviour |
+
+When auto-detection runs, emulator hints are checked in order, and the best
+`terminfo` entry confirmed to exist on the system is selected:
+
+1. **`$COLORTERM`** — `truecolor` or `24bit` → `xterm-direct`, then `xterm-256color`
+2. **`$TERM_PROGRAM`** — `iTerm.app`, `WezTerm`, `Hyper`, `vscode` → appropriate entry
+3. **`$VTE_VERSION`** — GNOME Terminal, Tilix, … → `vte-256color`, then `xterm-256color`
+4. **`$WT_SESSION`** — Windows Terminal → `xterm-256color`
+5. **`$TMUX`** — tmux session → `tmux-256color`, then `screen-256color`
+6. **`$STY`** — GNU screen session → `screen-256color`, then `screen`
+7. **Generic probe** — `xterm-256color` → `xterm-color` → `xterm` → `vt100`
+
 ### 4.2. Module defaults
 
 Each module exposes its hardcoded defaults as configuration keys. Set a key to
@@ -397,19 +432,23 @@ and other colour-aware tools.
 True-colour themes (`solarized`, `solarized-light`) require a terminal with
 24-bit colour support (Konsole, iTerm2, kitty, Alacritty, Windows Terminal).
 Verify support with:
+
 ```bash
 printf '\e[38;2;38;139;210mTrue colour test\e[0m\n'
 ```
 
 ## 5. Contact and more information
+
 ### 5.1. New users
+
 If you use (or plan to use) `profile`, I'll be happy if you simply mail me to
 let me know, especially if you don't plan to contribute. If you plan to
 contribute, I'll be twice happier for sure!
 
 ### 5.2. Bugs
+
 **profile** bug tracker is hosted on its Gitea instance. Check the
-https://git.geoffray-levasseur.org/fatalerrors/profile page. If you find a bug,
+<https://git.geoffray-levasseur.org/fatalerrors/profile> page. If you find a bug,
 you can also submit a bug report to the maintainer mail address mentioned at
 the end of that document. A bug report may contain the command line parameters
 where the bug happens, OS details, the module that triggered it, if any, and the
@@ -422,6 +461,7 @@ Check the [FAQ](./doc/FAQ.md) and the [to-do list](./doc/todo.md) before
 sending any feature request or bug report, as it might already be documented.
 
 ### 5.3. How to contribute?
+
 You are free to improve and contribute as you wish. If you have no idea what to
 do or want some direction, you can check the [to-do list](./doc/todo.md),
 containing desired future improvements. Make sure you always have the latest
@@ -443,6 +483,7 @@ installation will probably be rejected.
 If you want to make a financial contribution, please contact me by mail.
 
 ### 5.4. License, website, and maintainer
+
 Everything except configuration files is licensed under the BSD-3 license.
 Please check the license file alongside this one.
 
@@ -455,4 +496,4 @@ You can mail the author at fatalerrors \<at\> geoffray-levasseur \<dot\> org.
 Documentation (c) 2021-2026 Geoffray Levasseur.
 
 This file is distributed under the 3-clause BSD license. The complete license
-agreement can be obtained at: https://opensource.org/licenses/BSD-3-Clause
+agreement can be obtained at: <https://opensource.org/licenses/BSD-3-Clause>

doc/CHANGELOG.md

@@ -10,6 +10,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
 ## [4.1.0] — 2026-05-07
 
 ### Added
+
 - `profile.sh --install` command to automatically configure profile loading in
   shell startup files.
 - `--install --bashrc` and `--install --profile` target selectors for
@@ -20,16 +21,17 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
   automatically in interactive sessions from `profile.d/bash-completion/*.sh`.
 
 ### Changed
+
 - `disp` now wraps long messages on terminal width, avoids mid-word splits, and
   aligns continuation lines with the message body after the prefix.
 - `help` now supports `help <command>` and delegates to `<command> --help`.
 - `taz` now supports `-p auto` / `--parallel=auto` to automatically use the
   runtime CPU count. This mode is now the default via
-  `TAZ_DEFAULT_THREADS=auto`.
+  `TAZ_DEFAULT_THREADS=auto`. Backward compatibility with 0 being interpreted as
-- `taz` keeps backward compatibility with legacy `TAZ_DEFAULT_THREADS=0`
+  auto is maintained.
-  values by interpreting `0` as `auto`.
 
 ### Fixed
+
 - Startup responsiveness improved: `check_updates -q` now uses a short network
   timeout so unavailable/slow networks no longer delay prompt readiness.
 - `dwl` gained timeout support (`-t` / `--timeout`) and is now used by quiet
@@ -40,6 +42,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
 ## [4.0.0] — 2026-04-23
 
 ### Added
+
 - New `profile.conf` reference template at `doc/profile.conf.example`.
 - Dynamic locale shortcuts generated from `SET_LOCALE` and startup default
   language selection through `DEFAULT_LANG`.
@@ -49,11 +52,13 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
 - Module defaults exposed as configuration keys in `profile.conf`.
 
 ### Changed
+
 - `utaz` now supports a wider range of archive formats.
 - Prompt and theme rendering improved, including better 24-bit color support.
 - Overall code quality and maintainability improved across modules.
 
 ### Documentation
+
 - README updated with full function reference and configuration tables.
 - New and expanded docs in `doc/` (`CONTRIBUTING.md`, `FAQ.md`, `todo.md`).
 - Historical releases imported from `history.txt` into this changelog.
@@ -63,6 +68,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
 ## [3.99.2-4_rc_2] — 2026-04-21
 
 ### Fixed
+
 - **`prompt.sh`** — `\$Last_Command` in PS1 was escaped, preventing the exit
   code from ever appearing in the prompt (the local variable no longer exists
   when PS1 is rendered by bash). Removed the backslash so the value is embedded
@@ -77,6 +83,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
   `"Usage: ppg <string>"` instead of `"Usage: kt <pid>"`.
 
 ### Added
+
 - **`packages.sh` — `get_pkgmgr()`** — new exported helper that detects the
   active package manager of the running distribution. Detection first reads
   `/etc/os-release` (`ID` then `ID_LIKE`), then falls back to a
@@ -89,6 +96,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
 ## [3.99.1-4_rc_1] — 2026
 
 ### Added
+
 - **Theming system** — `load_theme` in `profile.d/prompt.sh` loads `.theme`
   files from `profile.d/themes/` (or a custom directory set via
   `PROMPT_THEME_DIR`). Theme files are **parsed, not executed** — no shell code
@@ -116,6 +124,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
   never accidentally staged.
 
 ### Changed
+
 - README §2 now explains how to create `profile.conf` from
   `doc/profile.conf.example` (new section 2.1 "Initial configuration").
 - README §4 updated with full module-defaults tables, theming reference, and a
@@ -124,6 +133,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
   variables, only data).
 
 ### Security
+
 - `load_theme` uses a strict allowlist (no `eval`, no sourcing). Only
   `PROMPT_COLOR_*` keys and known `disp.sh` colour variable names are accepted.
   Values must match `\$[A-Za-z_][A-Za-z0-9_]*` or `\\e\[[0-9;]*m`; any other
@@ -134,6 +144,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
 ## [3.95.3-4_beta_3] — 2024
 
 ### Added
+
 - Initial public release candidate series.
 - Core modules: `compress`, `disp`, `filefct`, `fun`, `help`, `info`, `lang`,
   `net`, `packages`, `processes`, `prompt`, `pwd`, `rain`, `ssh`, `updates`.
@@ -151,35 +162,43 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
 ## Legacy releases (imported from `history.txt`)
 
 ### [3.6.1] — 2026-03-05
+
 - Fix typo in `compress.sh`.
 
 ### [3.6.0] — 2026-03-05
+
 - Improved `utaz` with broader multi-format support.
 - Introduced `ppu` and `ppn`.
 - Improved update system.
 
 ### [3.5.0] — 2026-03-04
+
 - `rain` now has configurable speed and color.
 - `showinfo` adapted to `fastfetch` (in addition to `neofetch`).
 
 ### [3.3.1] — 2022-02-24
+
 - Fixed version detection.
 - Added `busy`.
 - Fixed use of library functions before loading.
 
 ### [3.3.0] — 2022-11-28
+
 - Initial version update support.
 - Changed versioning code.
 - Added installation path detection.
 
 ### [3.2.3] — 2022-11-28
+
 - Improved README.
 
 ### [3.2.2] — 2022-11-21
+
 - Fixed `taz` compression level parsing.
 - Fixed typo in `dpkgs`.
 
 ### [3.2.1] — 2022-11-20
+
 - Fixed several messages.
 - Made `dpkgs` RPM-aware (initial support).
 - Removed version history from main script and reverted declaration order.
@@ -187,108 +206,139 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
 - Completed `LICENSE` file.
 
 ### [3.2.0] — 2022-11-18
+
 - Created `disp` command and integrated it across the codebase.
 
 ### [3.1.1] — 2022-11-10
+
 - `genpwd`: added feasibility check for requested password constraints.
 
 ### [3.1.0] — 2022-11-08
+
 - Added password generator.
 
 ### [3.0.1] — 2022-11-07
+
 - Added concatenation option to `rmspc`.
 - Added `ku`.
 - Improved error handling in `meteo`.
 
 ### [3.0.0] — 2022-08-27
+
 - Split code into several files/modules.
 - Added `rain` screensaver.
 
 ### [2.8.2] — 2022-07-29
+
 - Added warning for non-bash users.
 
 ### [2.8.1] — 2022-07-19
+
 - Cleanup, fixes and optimizations.
 
 ### [2.8.0] — 2022-06-24
+
 - Added `backtrace`, `error` and `settrace`.
 - Bugfixes in `showinfo`.
 
 ### [2.7.1] — 2022-06-22
+
 - Minor corrections.
 - Added `help` command.
 
 ### [2.7.0] — 2022-06-21
+
 - Added `isipv4` and `isipv6`, integrated into `rmhost`.
 - Removed broken Konsole save/restore support.
 
 ### [2.6.3] — 2021-10-18
+
 - Changed PS1 to status-bar style.
 - Minor improvements.
 
 ### [2.6.2] — 2021-02-26
+
 - Bugfix in `taz` for directories with trailing slash.
 
 ### [2.6.1] — 2020-12-25
+
 - Added checks in `rmhost`.
 - Improved `rmspc`.
 - Created `expandlist`.
 
 ### [2.6.0] — 2020-10-24
+
 - Added Konsole session save/restore.
 
 ### [2.5.3] — 2020-09-11
+
 - Added aliases, improved code consistency and fixed typos.
 - Improved `utaz`, removed `showdiskmap`, removed remaining French text.
 - Added license information for future publication.
 
 ### [2.5.2] — 2020-03-06
+
 - Sorted and improved aliases.
 
 ### [2.5.1] — 2020-03-05
+
 - Language consistency fixes.
 - Added `pigz` support in `taz`.
 
 ### [2.5.0] — 2020-03-03
+
 - Added `taz` and `rmspc`.
 - Renamed `auzip` to `utaz` and improved it.
 
 ### [2.4.0] — 2020-03-02
+
 - Added `auzip`.
 
 ### [2.3.2] — 2020-01-31
+
 - `figlet`: changed default font to `ansi_shadow`.
 
 ### [2.3.1] — 2020-01-16
+
 - Bugfix: non-interactive shells were blocked by some functions.
 
 ### [2.3.0] — 2020-01-08
+
 - Added `figlet` and `neofetch` as MOTD replacement.
 
 ### [2.2.0] — 2019-12-16
+
 - Added `showinfo`.
 - First implementation of `showdiskmap`.
 
 ### [2.1.2] — 2019-09-24
+
 - Bugfix in profile version display.
 
 ### [2.1.1] — 2019-09-23
+
 - Bugfix in `dpkgs`.
 
 ### [2.1.0] — 2018-09-16
+
 - Added `rmhost`, `setc`, `setfr`.
 - Improved locale management.
 
 ### [2.0.1] — 2017-02-04
+
 - `clean` improvements (`--shell`).
 
 ### [2.0.0] — 2015-10-24
+
 - Added advanced functions (`clean`, `ssr`, etc.).
 
 ### [1.0.0] — 2013-02-16
+
 - Initial version.
 
 ### [Initial fork]
-Forked default Bash profile from Beyond Linux From Scratch by
+
-  * James Robertson <jameswrobertson@earthlink.net>
+Forked default Bash profile from Beyond Linux From Scratch by:
-  * Dagmar d'Surreal <rivyqntzne@pbzpnfg.arg>
+
+- James Robertson <jameswrobertson@earthlink.net>
+- Dagmar d'Surreal <rivyqntzne@pbzpnfg.arg>

doc/CONTRIBUTING.md

@@ -39,6 +39,7 @@ to target). Stale forks cause avoidable merge conflicts.
 **New functionality** must always target `master`.
 
 **Bugfixes** must target the branch where the bug was introduced:
+
 - If the bug exists in a released version, open the fix against that version's
   maintenance branch first, then cherry-pick onto `master`.
 - If the bug is only in `master` (unreleased), fix it directly on `master`.
@@ -71,6 +72,7 @@ Any experimental version must have it's dedicated branch.
 ---
 
 ## 5. Development environment
+
 | --- | --- | --- |
 | Bash | 4.3 | Namerefs (`local -n`) required |
 | shellcheck | any recent | Run before every commit |
@@ -78,6 +80,7 @@ Any experimental version must have it's dedicated branch.
 | bats-core | 1.x | Optional — for running the test suite |
 
 Install shellcheck:
+
 ```bash
 # Debian / Ubuntu
 apt-get install shellcheck
@@ -94,6 +97,7 @@ brew install shellcheck
 ## 6. Code style
 
 ### General rules
+
 - **Bash only** — no external interpreters in core modules. Python or Perl is
   acceptable for completely self-contained, optional utilities that have no
   dependencies beyond a minimal Debian or CentOS installation.
@@ -109,6 +113,7 @@ brew install shellcheck
   `${VAR:-default}` and document the key in `profile.conf` and `README.md §4`.
 
 ### Function conventions
+
 - Public functions **must** be exported: `export -f funcname`.
 - Every public function **must** support `-h` / `--help` and print usage to
   stdout, returning 0.
@@ -120,6 +125,7 @@ brew install shellcheck
   to prevent collisions with caller-scope variables.
 
 ### Module structure
+
 Every new module should follow this pattern:
 
 ```bash
@@ -172,20 +178,25 @@ comment explaining why the suppression is necessary.
 ## 10. Submitting a contribution
 
 ### Via Git (preferred)
+
 1. Contact the maintainer to obtain push access, or fork on the Gitea instance.
 2. Create a branch: `git checkout -b feature/my-feature`.
 3. Commit with a clear subject line: `module: short description (≤ 72 chars)`.
 4. Push and open a pull request against `master`.
 
 ### Via patch
+
 If you do not have push access:
+
 ```bash
 git format-patch origin/master
 ```
+
 Send the resulting `.patch` file(s) to
 `fatalerrors <at> geoffray-levasseur <dot> org`.
 
 ### Commit message format
+
 ```
 module: imperative short description
 
@@ -197,7 +208,7 @@ Reference issue numbers if applicable: closes #42.
 
 ## 11. What will be rejected
 
-- Code requiring packages not in a minimal Debian or CentOS install.
+- Code requiring packages not in a minimal Debian or CentOS install, unless optionnal.
 - Use of `eval`, `source`-based config loading, or other code-injection vectors.
 - Changes that break Bash 4.3 compatibility.
 - Patches without a passing `shellcheck` run.

doc/FAQ.md

@@ -7,15 +7,19 @@
 **Q: How do I install profile automatically into my shell startup files?**
 
 Run the installer directly (no need to source first):
+
 ```bash
 bash <installpath>/profile/profile.sh --install
 ```
+
 This appends the required `source` line to both `~/.bashrc` and `~/.profile`.
 To target only one file:
+
 ```bash
 bash <installpath>/profile/profile.sh --install --bashrc
 bash <installpath>/profile/profile.sh --install --profile
 ```
+
 The operation is idempotent — running it again will not add a duplicate line.
 
 ---
@@ -23,9 +27,11 @@ The operation is idempotent — running it again will not add a duplicate line.
 **Q: I ran `profile.sh` directly and got a warning about sourcing.**
 
 profile.sh is designed to be *sourced*, not executed:
+
 ```bash
 source <installpath>/profile/profile.sh
 ```
+
 The only exception is `--install`, which must be passed to a direct execution
 (`bash profile.sh --install`) to set up the sourcing line automatically.
 
@@ -35,11 +41,13 @@ The only exception is `--install`, which must be passed to a direct execution
 
 Your system's default shell is an older Bash (common on macOS, which ships
 Bash 3.x for licensing reasons). Install a newer Bash:
+
 ```bash
 # macOS
 brew install bash
 # then add /opt/homebrew/bin/bash to /etc/shells and chsh
 ```
+
 Or point your terminal emulator at the newer binary explicitly.
 
 ---
@@ -55,12 +63,14 @@ scripts start with `#!/usr/bin/env bash`.
 **Q: Can I use profile functions in scripts?**
 
 Yes. The supported way is to source `profile.sh` from a Bash script:
+
 ```bash
 #!/usr/bin/env bash
 source /path/to/profile/profile.sh
 
 taz -p auto -f lz mydir
 ```
+
 You can also source one module directly (for example
 `profile.d/compress.sh`) if you only need a subset of functions.
 
@@ -82,10 +92,12 @@ behave differently in non-interactive execution.
 **Q: I set `PROFILE_PATH` but profile still can't find its modules.**
 
 `PROFILE_PATH` must be exported *before* you source `profile.sh`:
+
 ```bash
 export PROFILE_PATH=/opt/profile
 source /opt/profile/profile.sh
 ```
+
 If set after sourcing, `MYPATH` is already locked in and the variable has
 no effect.
 
@@ -119,6 +131,7 @@ See also `README.md §4.2` for a consolidated table.
 **Q: A key I set in `profile.conf` is being ignored.**
 
 Check that:
+
 1. The key is inside the correct `[section]` header.
 2. There is no leading space before the section name (`[section]` not
    `[ section ]`).
@@ -128,15 +141,39 @@ Check that:
 
 ---
 
+**Q: How do I force or auto-detect the correct `TERM` value?**
+
+Set `TERM` in the `[system]` section of `profile.conf`:
+
+```ini
+[system]
+# Auto-detect best available terminfo entry at startup (default)
+#TERM=smart
+
+# Force a specific entry
+#TERM=xterm-256color
+```
+
+When `TERM` is absent or set to `smart`, `term_set` probes your terminal
+emulator's environment variables (`COLORTERM`, `TERM_PROGRAM`, `VTE_VERSION`,
+`WT_SESSION`, `TMUX`, `STY`) and then tests terminfo entries in preference
+order.  If you are experiencing display issues, run `term_set` interactively
+and check the result with `echo $TERM`.  See *Prompt & theming* below for
+symptoms caused by a wrong `TERM` value.
+
+---
+
 ## Prompt & theming
 
 **Q: How do I change the prompt theme?**
 
 Add to `profile.conf`:
+
 ```ini
 [prompt]
 PROMPT_THEME = dark
 ```
+
 Built-in names: `default`, `dark`, `light`, `solarized`, `solarized-light`,
 `monokai`, `monochrome`, `abyss`, `plasma`, `adwaita`, but you can create your
 own theme.
@@ -147,16 +184,45 @@ own theme.
 
 Those themes use 24-bit / true-colour ANSI sequences (`\e[38;2;R;G;Bm`).
 Test your terminal:
+
 ```bash
 printf '\e[38;2;38;139;210mTrue colour test\e[0m\n'
 ```
+
 If you see a solid blue word your terminal supports true colour.  
 If you see garbage or plain text, switch to a 16-colour theme
 (`dark`, `default`, etc.) or upgrade your terminal emulator.
 
 ---
 
-**Q: I created a custom theme but `load_theme` emits "key not allowed" warnings.**
+**Q: My prompt colours are missing, wrong, or ANSI escape codes appear as raw text.**
+
+The most common cause is a `TERM` value that does not match what your terminal
+emulator actually supports — either it points to an entry that does not exist
+in the local `terminfo` database, or it under-describes the real capabilities
+(e.g. `TERM=xterm` when the emulator supports 256 colours).
+
+Diagnose with:
+
+```bash
+echo "TERM=$TERM"
+tput colors        # should print 256 (or higher) for a capable terminal
+infocmp | head -5  # verify the loaded terminfo entry looks sane
+```
+
+Common scenarios and fixes:
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `tput: unknown terminal` | `TERM` value has no terminfo entry | Remove the forced value and let `TERM=smart` auto-detect |
+| Only 8 colours instead of 256 | `TERM=xterm` instead of `xterm-256color` | Set `TERM=smart` or force `xterm-256color` |
+| Colours correct in plain shell but wrong inside tmux | tmux overwrites `TERM` | Set `TERM=smart` — `term_set` picks `tmux-256color` |
+| Colours correct outside screen but wrong inside it | Same, for GNU screen | Set `TERM=smart` — `term_set` picks `screen-256color` |
+| Prompt renders correctly but `rain` / `matrix` shows garbage | Terminal doesn't support the ANSI codes implied by `TERM` | Match `TERM` to the real emulator capability |
+
+The recommended approach is to leave `TERM` unset (or set it to `smart`) in
+`profile.conf` and let `term_set` choose the best available entry automatically.
+Only force a specific value if auto-detection picks the wrong one.
 
 Theme files are parsed, not executed. Only `PROMPT_COLOR_*` keys and the
 standard colour variable names from `disp.sh` (`Black`, `Blue`, `On_IBlack`,
@@ -200,12 +266,14 @@ All commands accept `-h` / `--help`.
 Profile ships dedicated completions in `profile.d/bash-completion/git-completion.sh`,
 loaded automatically in interactive sessions. If completions are missing,
 check that the system git completion is installed:
+
 ```bash
 # Debian / Ubuntu
 apt-get install bash-completion
 # Fedora / RHEL
 dnf install bash-completion
 ```
+
 When the native git completion helpers are available, `gacp` path completion
 behaves exactly like `git add` (modified files, untracked files, directories).
 
@@ -215,10 +283,12 @@ behaves exactly like `git add` (modified files, untracked files, directories).
 
 The `-a` / `--auto` flag adds all modified files (equivalent to `git add -A`).
 The default depends on `GIT_GACP_AUTO_ADD` in `profile.conf`:
+
 ```ini
 [git]
 GIT_GACP_AUTO_ADD = 1
 ```
+
 Set to `1` to make `-a` the default.
 
 ---
@@ -229,6 +299,7 @@ Set to `1` to make `-a` the default.
 
 The key is `METEO_DEFAULT_CITY` (not `DEFAULT_CITY`), and it must be in the
 `[info]` section:
+
 ```ini
 [info]
 METEO_DEFAULT_CITY = Paris
@@ -240,6 +311,7 @@ METEO_DEFAULT_CITY = Paris
 
 `dwl` requires one of `curl`, `wget`, or `fetch` to be installed.
 Install curl:
+
 ```bash
 # Debian / Ubuntu
 apt-get install curl
@@ -247,6 +319,7 @@ apt-get install curl
 # Fedora / RHEL
 dnf install curl
 ```
+
 Or set `DWL_PREFERRED_TOOL` in `[net]` to whichever tool you have.
 
 ---
@@ -254,9 +327,11 @@ Or set `DWL_PREFERRED_TOOL` in `[net]` to whichever tool you have.
 **Q: How do I limit how long `dwl` waits for a download?**
 
 Use the `-t` / `--timeout` option:
+
 ```bash
 dwl -t 5 https://example.com/file.txt /tmp/file.txt
 ```
+
 This sets a 5-second cap on both the connection and the overall transfer.
 The timeout is propagated to `curl` (`--max-time` + `--connect-timeout`),
 `wget` (`--timeout`), or `fetch` (`-T`) transparently.
@@ -274,11 +349,13 @@ fails silently and the prompt appears immediately.
 **Q: `help` only shows a list of functions. Can I get usage for a specific one?**
 
 Yes — pass the command name as an argument:
+
 ```bash
 help gacp
 help dwl
 help taz
 ```
+
 This calls `<command> --help` and prints the full usage for that function.
 
 ---
@@ -299,9 +376,11 @@ identified, and check that the package manager binary is in your `PATH`.
 `check_updates` compares the content of the remote `version` file against
 `$PROFVERSION`. If `UPDT_DEFAULT_BRANCH` in `[updates]` points to a different
 branch than your installation, the version files may not match. Check:
+
 ```bash
 cat "$MYPATH/version"
 ```
+
 and make sure `UPDT_DEFAULT_BRANCH` matches the branch you track.
 
 ---
@@ -332,6 +411,7 @@ has not been implemented yet.
 ```bash
 PROFILE_DISABLED=1 bash --norc
 ```
+
 Or simply open a shell without sourcing `~/.bashrc` (`bash --norc`).
 
 ---
@@ -341,6 +421,7 @@ Or simply open a shell without sourcing `~/.bashrc` (`bash --norc`).
 Open an issue on the
 [Gitea tracker](https://git.geoffray-levasseur.org/fatalerrors/profile/issues)
 or send a mail to `fatalerrors <at> geoffray-levasseur <dot> org` with:
+
 - The exact command that triggered the bug
 - Your OS and Bash version (`bash --version`)
 - The module involved

doc/todo.md

@@ -47,23 +47,27 @@ version-bump.
 ## Module improvements
 
 ### compress
+
 - [ ] **`taz` progress bar** — show a `pv` / `dd`-based progress indicator when
   compressing large trees, gated behind a `-p` flag. **[medium]**
 - [ ] **`utaz` integrity check** — run `tar -tOf` / `unzip -t` / `7z t` before
   extracting and abort if the archive is corrupt. **[easy]**
 
 ### filefct
+
 - [ ] **`findbig` / `findzero` / `finddead` — `fd` integration** — optionally
   use `fd` instead of `find` when available for faster traversal. **[easy]**
 - [ ] **`file_stats` — human-readable totals** — add `--human` flag to emit
   sizes in K/M/G instead of bytes. **[easy]**
 
 ### info
+
 - [X] **`showinfo` fallback** — when neither `neofetch` nor `fastfetch` is
   installed, print a minimal sysinfo block (hostname, OS, kernel, uptime,
   CPU, RAM) using pure Bash + `/proc`. **[medium]**
 
 ### net
+
 - [X] **`dwl` resume support** — pass `-C -` to curl / `--continue-at -` to
   wget for interrupted downloads; gate behind a `-r` flag. **[easy]**
 - [ ] **`myextip` multiple providers** — fall back to a secondary URL
@@ -71,15 +75,18 @@ version-bump.
   **[easy]**
 
 ### processes
+
 - [X] **`ku` dry-run flag** — add `-n` / `--dry-run` to print what would be
   killed without acting. **[easy]**
 
 ### pwd
+
 - [ ] **`genpwd` passphrase mode** — add `-w` / `--words N` to generate
   word-based passphrases (diceware-style) from `/usr/share/dict/words`.
   **[medium]**
 
 ### ssh
+
 - [ ] **SSH agent management** — add `ssh_agent_start` / `ssh_agent_stop` helpers
   that start a persistent `ssh-agent`, add configured keys, and survive
   re-login via a socket stored in `~/.ssh/agent.env`. **[medium]**
@@ -87,6 +94,7 @@ version-bump.
   matching entries in one call. **[easy]**
 
 ### updates
+
 - [ ] **Automatic update check age** — store a timestamp in `~/.cache/profile_last_check`;
   skip the network request in `check_updates -q` if the last check was less
   than `UPDT_CHECK_INTERVAL` hours ago (configurable, default 24). **[medium]**