karnel-termux 4.17.10 → 4.17.19

package/README.md

@@ -8,7 +8,7 @@
 
 <p align="center">
   <a href="https://github.com/israelmarques1024-dotcom/karnel-termux">
-    <img src="https://img.shields.io/badge/version-4.17.10-0078D4?style=for-the-badge" alt="Version">
+    <img src="https://img.shields.io/badge/version-4.17.19-0078D4?style=for-the-badge" alt="Version">
   </a>
   <a href="https://www.npmjs.com/package/karnel-termux">
     <img src="https://img.shields.io/npm/v/karnel-termux?style=for-the-badge&logo=npm&color=cb3837" alt="npm">
@@ -23,23 +23,23 @@
     <img src="https://img.shields.io/badge/platform-Termux%20%7C%20Android-0078D4?style=for-the-badge" alt="Platform">
   </a>
   <a href="https://israelmarques1024-dotcom.github.io/karnel-termux">
-    <img src="https://img.shields.io/badge/Site-karneltermux.github.io-0078D4?style=for-the-badge" alt="Website">
+    <img src="https://img.shields.io/badge/Site-israelmarques1024--dotcom.github.io%2Fkarnel--termux-0078D4?style=for-the-badge" alt="Website">
   </a>
 </p>
 
 ---
 
-**Karnel Termux** is a modular development environment that transforms Termux into a complete workstation. With a single CLI (`karnel`), install and manage:
+**Karnel Termux** is a modular development environment that transforms Termux into a complete workstation.
 
-Created by **Israel Marques**.
+Created by **Israel Marques**. Core agent contributions by **devcorex**.
 
-Core agent contributions by **devcorex**.
+With a single CLI (`karnel`), install and manage:
 
 - **45 AI tools** — Claude, Gemini, OpenCode, Cactus, Hugging Face, Ollama, KeelCode, Goose, Factory Droid and more
 - **8 languages** — Node.js, Python, Go, Rust, C/C++, PHP, Perl, Bun
 - **5 databases** — PostgreSQL, MariaDB, SQLite, MongoDB, Redis
 - **22 dev tools** — gh, curl, fzf, bat, lsd, jq, tmux, openssh, snyk and more
-- **12 utility tools** — fconv, notes, treex, qrcode, SuperFile, zork and more
+- **13 utility tools** — fconv, notes, treex, qrcode, SuperFile, zork, herdr and more
 - **2 network tools** — dark, dedsec-network
 - **4 deploy CLIs** — Vercel, Railway, Netlify, Supabase
 - **Responsible OSINT** — Robin v2.8 through Tor with a loopback-only web UI
@@ -54,6 +54,23 @@ Core agent contributions by **devcorex**.
 
 
 
+---
+
+## 🌟 Featured: Herdr — terminal AI assistant
+
+Karnel now ships **[Herdr](https://herdr.dev)**, a blazing-fast terminal AI assistant CLI, as a first-class utility. Install it with:
+
+```bash
+karnel install utils --herdr
+```
+
+Why it's great:
+- **Checksum-verified** download from the official Herdr release manifest (`https://herdr.dev/latest.json`).
+- **Atomic, safe install** into `$PREFIX/bin/herdr` with a Karnel ownership marker — so `karnel uninstall utils --herdr` is clean and never touches files it didn't manage.
+- Pairs perfectly with the 45 AI agents Karnel manages.
+
+> Open its docs anytime with `karnel open herdr`.
+
 ---
 
 ## Installation
@@ -61,7 +78,7 @@ Core agent contributions by **devcorex**.
 ### Via checksummed GitHub release (recommended)
 
 ```bash
-version=4.17.10
+version=4.17.19
 tmpdir=$(mktemp -d) && trap 'rm -rf "$tmpdir"' EXIT
 base="https://github.com/israelmarques1024-dotcom/karnel-termux/releases/download/v$version"
 curl -fsSL "$base/karnel-termux-install.sh" -o "$tmpdir/karnel-termux-install.sh"
@@ -106,6 +123,7 @@ aliases, or options; use `karnel help` and the CLI reference for the full set.
 | `karnel update <module>` | Update modules or karnel |
 | `karnel uninstall <module>` | Remove installed modules |
 | `karnel reinstall <module>` | Reinstall modules |
+| `karnel upgrade` | Upgrade the framework (self-update) |
 | `karnel doctor termux` | Diagnose the Termux environment (30+ sections) |
 | `karnel doctor code` | Detect project ecosystems and run code checks |
 | `karnel doctor robin` | Diagnose Robin, Tor, dependencies, and local UI |
@@ -152,7 +170,7 @@ aliases, or options; use `karnel help` and the CLI reference for the full set.
 karnel install ai --keelcode
 
 # Install the SuperFile terminal file manager
-karnel install utils --superfile
+karnel install utils --superfile --herdr
 ```
 
 Both tools support `update`, `reinstall`, and `uninstall` with the same module and flag.
@@ -343,7 +361,7 @@ karnel doctor termux --quick         # Run essential system/package checks only
 karnel doctor termux --fix           # Apply queued fixes without group confirmation
 
 karnel doctor code                   # Quick project analysis
-karnel doctor code --standard .      # Add security, deps, coverage and complexity
+karnel doctor code --standard .      # Add security, deps, dead-code and complexity
 karnel doctor code --deep --json .   # All 76 definitions as standalone JSON
 karnel doctor code --fix .           # Apply fixes classified as safe
 karnel doctor robin                  # Robin/Tor/dependency diagnostics
@@ -357,7 +375,7 @@ definitions across 68 distinct tool labels. It detects subprojects, executes
 checks in the matching project or subproject directory, preserves command exit status, and writes
 timestamped text reports under `$KARNEL_DATA/doctor_code_reports/`.
 
-Read the **[complete Doctor reference](docs/doctor/index.md)** for modes,
+Read the **[complete Doctor reference](https://github.com/israelmarques1024-dotcom/karnel-termux/blob/main/docs/doctor/index.md)** for modes,
 supported ecosystems, tool coverage, JSON schema, reports, and auto-fix safety.
 
 ---
@@ -388,7 +406,7 @@ karnel voice claude-code --lang en # Speak in English -> claude -p
 karnel voice "!"                   # Shortcut for "text"
 ```
 
-### Supported Agents (15)
+### Supported Agents (14)
 
 | Agent | Command executed |
 |-------|-----------------|
@@ -407,6 +425,7 @@ karnel voice "!"                   # Shortcut for "text"
 | `crush` | `crush "..."` |
 | `kiro` | `kiro-cli "..."` |
 | `text` | Prints prompt to terminal |
+| `!` | Alias for `text` |
 
 ### Options
 
@@ -430,7 +449,7 @@ Microphone -> termux-speech-to-text -> editor (edit) -> clipboard -> AI agent
 ### Requirements
 
 - Termux:API: `pkg install termux-api`
-- App Termux:API: https://karneltermux.vercel.app/termux/api
+- App Termux:API: https://github.com/termux/termux-api
 - Editor (optional): `karnel install editor`; otherwise use `--raw` or the automatic raw fallback
 
 ---
@@ -513,12 +532,12 @@ Documentation loads from https://israelmarques1024-dotcom.github.io/karnel-termu
 
 ## Documentation
 
-- [Documentation index](docs/index.md)
-- [CLI reference](docs/cli/index.md)
-- [Doctor reference](docs/doctor/index.md)
-- [Troubleshooting](docs/troubleshooting/index.md)
-- [Architecture](docs/ARCHITECTURE/index.md)
-- [Documentation changelog](docs/CHANGELOG.md)
+- [Documentation index](https://github.com/israelmarques1024-dotcom/karnel-termux/blob/main/docs/index.md)
+- [CLI reference](https://github.com/israelmarques1024-dotcom/karnel-termux/blob/main/docs/cli/index.md)
+- [Doctor reference](https://github.com/israelmarques1024-dotcom/karnel-termux/blob/main/docs/doctor/index.md)
+- [Troubleshooting](https://github.com/israelmarques1024-dotcom/karnel-termux/blob/main/docs/troubleshooting/index.md)
+- [Architecture](https://github.com/israelmarques1024-dotcom/karnel-termux/blob/main/docs/ARCHITECTURE/index.md)
+- [Documentation changelog](https://github.com/israelmarques1024-dotcom/karnel-termux/blob/main/docs/CHANGELOG.md)
 - [Official website](https://israelmarques1024-dotcom.github.io/karnel-termux)
 
 ---
@@ -574,9 +593,12 @@ karnel/
 │   │   ├── ui/        # 4 UI components
 │   │   ├── auto/      # 1 automation tool
 │   │   ├── network/   # 2 network tools
-│   │   ├── utils/     # 12 utility tools
+│   │   ├── utils/     # 13 utility tools
 │   │   ├── games/     # 6 games
 │   │   ├── security/  # 30 security tools
+│   │   ├── osint/     # Robin OSINT (Tor + LLM)
+│   │   ├── voice/     # Speech-to-agent via Termux:API
+│   │   ├── plugins/   # Plugin manager
 │   │   └── deploy/    # 4 deploy CLIs
 │   └── utils/         # Utilities (banner, log, env, etc.)
 ├── install.sh         # Installation script
@@ -626,8 +648,8 @@ once every 24 hours; the check can use npm or GitHub and writes state under
 
 The repository CI validates Bash/Zsh syntax, ShellCheck errors, CLI smoke tests,
 version behavior, Robin contracts, plugin lifecycle contracts, and npm package
-contents. The official documentation site validates its catalog contracts,
-TypeScript, formatting, tests, and production build.
+contents. The documentation site is built by the `Publish Docs` workflow with
+`actions/jekyll-build-pages`, so a broken Jekyll page fails that build.
 
 These checks do not install every external tool or prove behavior on every Android
 device. Before relying on a new installer, test it in native Termux aarch64 with
@@ -654,7 +676,4 @@ MIT © Israel Marques
   <a href="https://israelmarques1024-dotcom.github.io/karnel-termux">
     <img src="https://img.shields.io/badge/Full%20Documentation-0078D4?style=for-the-badge" alt="Documentation">
   </a>
-  <a href="https://www.youtube.com/@capideb">
-    <img src="https://img.shields.io/badge/YouTube-Capi.deb-FF0000?style=for-the-badge&logo=youtube&logoColor=white" alt="YouTube — Capi.deb">
-  </a>
 </p>

package/docs/ARCHITECTURE/index.md

@@ -25,7 +25,7 @@ karnel-termux/
 │   │       ├── voice.sh
 │   │       ├── init.sh
 │   │       ├── deploy.sh
-│   │   ├── ... (27 .sh files + doctor/ subdir)
+│   │   ├── ... (28 .sh files + doctor/ subdir)
 │   ├── modules/                # Module orchestrators
 │   │       ├── ai.sh           # AI agent installer
 │   │       ├── lang.sh         # Language installer
@@ -45,7 +45,7 @@ karnel-termux/
 │   │   ├── deploy/             # 4 deploy CLIs
 │   │   ├── games/              # 6 games
 │   │   ├── network/            # 2 network tools (dark, dedsec-network)
-│   │   ├── utils/              # 12 utility tools (fconv, notes, zork, SuperFile, etc.)
+│   │   ├── utils/              # 13 utility tools (fconv, notes, zork, SuperFile, herdr, etc.)
 │   │   ├── security/           # 30 security tools
 │   │   ├── voice/              # Speech-to-agent via Termux:API
 │   │   ├── plugins/            # Built-in plugin manager
@@ -137,12 +137,20 @@ installation. Uninstall does not delete persistent data.
 
 ### Tool Installer Pattern
 
+Each tool lives in `karnel/tools/<module>/<tool>/install.sh` and exposes
+lifecycle entry points named after the tool:
+
 ```bash
-_tool_dependencies() { ... }    # Declare dependencies
-_tool_install() { ... }          # Install the tool
-_tool_postinstall() { ... }      # Post-installation setup
+install_<tool>()    # Install the tool; 0 = installed, 2 = already installed
+uninstall_<tool>()  # Remove the tool; 0 = removed, 2 = was not installed
+update_<tool>()     # Update the tool
+reinstall_<tool>()  # Uninstall + install
 ```
 
+The module orchestrator (`karnel/modules/<module>.sh`) discovers these
+functions, checks ownership markers before touching files, and treats exit
+code `2` as a no-op rather than a failure.
+
 ## Doctor Subsystem Architecture
 
 See [Doctor System](../doctor/) for the complete breakdown of the doctor code analysis engine.

package/docs/CHANGELOG.md

@@ -6,6 +6,131 @@ layout: base
 
 # Documentation Changelog
 
+## 4.17.19
+
+- **Release gate:** `tests/bun-installer.sh` did not mock the integrity helpers required by the hardened Bun native installer (`github_release_asset_sha256`, `verify_sha256`, `safe_extract_zip`). The test exited 1 before printing its result, causing `tests/run-isolated.sh`, CI, npm publishing, and GitHub release creation to fail from 4.17.14 through 4.17.18 despite the preceding suites passing. The test now supplies contract-faithful stubs; the full isolated suite exits 0.
+- Version references bumped to `4.17.19`.
+
+## 4.17.18
+
+- **Core fixes (2):**
+  - `karnel/cli/commands/ia.sh`: `karnel ia sessions --all` was a silent no-op — the flag was bound and never used, and agent names were always displayed anyway. Removed from the help text; the parser still accepts `--all` for back-compat.
+  - `karnel/cli/commands/open.sh`: `karnel open` help did not list the `robin` target even though the dispatcher handled it (`osint / robin`).
+- **npm/GitHub readme audit + site fixes (10):**
+  - `README.md`: documentation links were repo-relative (`docs/doctor/index.md`, `docs/index.md`, …), which 404 on npmjs.com — the README is also the npm package readme. All seven links now use absolute GitHub URLs.
+  - `README.md`: "Supported Agents (15)" → 14 (the count included `text`, which the same docs describe as "no agent"), and the `!` alias row was missing from the table; added.
+  - `docs/ARCHITECTURE/index.md`: the commands tree said "27 .sh files" — the directory has 28.
+  - `docs/ARCHITECTURE/index.md`: the "Tool Installer Pattern" documented `_tool_dependencies()`/`_tool_install()`/`_tool_postinstall()`, which exist nowhere in the repo; replaced with the real `install_<tool>`/`uninstall_<tool>`/`update_<tool>`/`reinstall_<tool>` contract and the 0/2 exit-code semantics.
+  - `docs/karnel/dev/index.md`: listed `proot-distro` as a dev tool; the module installs `proot` (a different package).
+  - `docs/_layouts/default.html`: Google Fonts was only `rel="preload"` — no stylesheet link existed anywhere, so Open Sans never loaded; replaced with a normal stylesheet link.
+  - `docs/_layouts/base.html`: the "Live Site" nav item linked to the site itself; now points to the GitHub repository.
+  - `docs/assets/css/style.scss`: the dark palette was set unconditionally on `:root`, making every light-mode fallback in the stylesheet unreachable; added a `prefers-color-scheme: light` override so OS theme is respected.
+  - `docs/CHANGELOG.md`: the permanent "## Unreleased - 2026-07-16" heading (for long-shipped features) retitled honestly as historical.
+  - `docs/cli/index.md`: removed the `karnel ia sessions --all` example (flag removed).
+  - Version references bumped to `4.17.18`.
+
+## 4.17.17
+
+- **Core fixes (8, incl. one broken tool and a 4.17.16 regression):**
+  - `karnel/tools/utils/treex/treex.py`: **the entire tool was broken** — an `IndentationError` (a lost `while True:`/`try:`/`os.scandir` block in `explorer_mode`) made every invocation crash. Reconstructed the block; all bundled Python tools now compile.
+  - `karnel/tools/utils/applaunch/applaunch.py`: launched a nonexistent `Settings.py` after every action, printing a Python "can't open file" error on every run; removed.
+  - `karnel/tools/utils/applaunch/applaunch.py`: replaced `os.system` f-string interpolation and `shell=True` (3× `am start`, `mkdir -p`, `aapt dump badging`) with argv-list `subprocess.run` / `os.makedirs` — removes shell-injection surface from package-manager-derived values.
+  - `karnel/cli/commands/doctor/code_exec.sh`: **reverted the 4.17.16 fix-command guard** — it refused the legitimate multi-statement `Go:gofmt` fix (and would refuse `Java:javac`/`bandit` checks), silently disabling Go auto-fix. Check/fix commands come exclusively from the in-repo `LANG_TOOLS` registry, so the guard was a functional regression, not security. A comment now documents this so it is not re-added.
+  - `karnel/cli/commands/brain.sh`: `_brain_update_related` appended the raw `$slug` in its `sed` branch while the escaped `$escaped` value was computed but unused — a slug containing `/` or `&` corrupted memory files. Now uses `$escaped` on both branches.
+  - `karnel/cli/commands/list.sh`: `karnel list utils` showed 12 tools while docs (and the module) promise 13 — the Herdr row was missing from `_list_utils`.
+  - `karnel/tools/utils/splash/splash.py`: `update_delay` rewrote *any* line containing "sleep" inside the loading-screen block, including the embedded `python3 -c "... sed /sleep 12;..."` cleanup line, corrupting the `bash.bashrc` self-cleanup; now only `sleep`-prefixed lines are rewritten.
+  - `karnel/tools/utils/splash/splash.py`: delay prompt crashed with an unhandled `ValueError` on non-numeric input; input is now validated (non-negative integer).
+- **Docs / site fixes (10):**
+  - `docs/cli/index.md`: removed five duplicated rows at the end of the `list` module table (network/utils/osint/voice/security appeared twice).
+  - `docs/index.md`: the Supabase anchor was "fixed" in the wrong direction — kramdown generates `supabase--remote-project-helpers` (double dash) from `## supabase — Remote-project helpers`; restored the double-dash link and corrected the 4.17.16 changelog note.
+  - `docs/troubleshooting/index.md`: corrected the claim that `karnel update karnel` logs to `install_dev.log`/`install_npm.log` — the updater prints to the terminal only; those files belong to the dev/npm module installers.
+  - `README.md`: the Site badge displayed a nonexistent domain (`karneltermux.github.io`); now shows the real `israelmarques1024-dotcom.github.io/karnel-termux`.
+  - `README.md`: removed the false CI claim that the docs site validates "catalog contracts, TypeScript, formatting, tests, and production build" (no TypeScript exists in the repo; `docs.yml` only runs `jekyll-build-pages`).
+  - `README.md`: the "Project Structure" tree omitted `osint/`, `voice/`, and `plugins/` under `karnel/tools/`; added.
+  - `README.md`: fixed the broken intro sentence (the "install and manage:" colon was followed by the credits instead of the feature list).
+  - `docs/karnel/security/index.md`: "30+ tools" → "30 tools" (the module has exactly 30).
+  - `docs/assets/css/style.scss`: removed the dead `.karnel-note` admonition CSS (referenced nowhere, same class of orphaned selector as the removed `.karnel-nav`).
+  - Version references bumped to `4.17.17`.
+
+## 4.17.16
+
+- **Core hardening (10 critical bug fixes):**
+  - `karnel/tools/lang/bun/install.sh`: the proot install/update paths now reject Bun archives containing path-traversal or absolute-path members before `unzip -o` runs (defense-in-depth alongside the SHA-256 check).
+  - `karnel/tools/utils/passman/passman.py`: **fixed a critical defect** — the module referenced `os.*` without importing `os`, which broke the entire password manager. Added `import os`.
+  - `karnel/tools/utils/passman/passman.py`: the encrypted vault is now written with `0600` permissions (was world-readable), and `import_vault` now backs up the existing vault to `<vault>.bak` before overwriting (prevents silent data loss).
+  - `karnel/cli/commands/backup.sh` and `restore.sh`: temporary directories now use a safe `mktemp` template under `TMPDIR`/`KARNEL_CACHE` instead of a bare `mktemp -d` (avoids an insecure `/tmp` fallback).
+  - `karnel/cli/commands/doctor/code_exec.sh`: `_exec_apply_fix` now validates the fix command with `_exec_fix_cmd_is_safe`, rejecting shell operators, stray braces, and destructive leading commands such as `rm`/`sudo`/`mv` — closing a command-injection path via a malicious project doctor config.
+  - `karnel/cli/commands/env.sh`: when a variable name looks like a secret (`SECRET`/`TOKEN`/`KEY`/`PASSWORD`/…), the shell rc file is tightened to `0600` so other local users cannot read stored secrets.
+- **Docs / site fixes:**
+  - Removed the duplicate logo on the documentation homepage (it was rendered both in the header and in the page body).
+  - Fixed two `karnel voice` help URLs that pointed at a custom redirector (`karneltermux.vercel.app/termux/api`); they now point to the official `https://github.com/termux/termux-api`.
+  - `README.md`: "45 other AI agents" → "45 AI agents" (Herdr is a utility, not one of the 45).
+  - `docs/cli/index.md`: the `list` table was missing `network`, `osint`, `voice`, `security`, `utils`, and `plugin`; all six rows were added.
+  - `docs/cli/index.md`: added the `osint --robin` install flag to the per-module flags table.
+  - `docs/index.md`: removed a broken `./ARCHITECTURE/` link (that page does not exist) and corrected the Supabase anchor direction (`#supabase--remote-project-helpers`, double dash as generated by kramdown from `## supabase — Remote-project helpers`).
+  - Bumped version references to `4.17.16` (README badge, install snippet, `package.json`).
+
+## 4.17.15
+
+- **Core hardening (10+ bug fixes):**
+  - `karnel/utils/tools.sh`: `_register_safe_reinstall_handlers` now rejects any tool/module name containing shell metacharacters before `eval`-ing the generated reinstall handler (prevents code injection via a crafted tool directory name).
+  - `karnel/tools/ai/droid/install.sh`: dropped the predictable `/tmp/droid-install` / `/tmp/droid-update` paths inside the proot container in favor of `mktemp -d`.
+  - `karnel/tools/ai/kimchi-code/install.sh`: replaced predictable `/tmp/kimchi-install` with `mktemp -d` and added an archive-member path-traversal check before extraction.
+  - `karnel/tools/ai/oh-my-pi/install.sh`: replaced predictable `/tmp/omp-install` / `/tmp/omp-update` with `mktemp -d`.
+  - `karnel/tools/ai/crush/install.sh`: `mktemp -d` now uses a safe template (no bare `/tmp` fallback).
+  - `karnel/cli/commands/{init,voice,brain,ia}.sh`: bare `mktemp` calls now use a safe `$KARNEL_CACHE`/`$TMPDIR` template instead of falling back to `/tmp`.
+- **Full site overhaul (10+ fixes):**
+  - Removed the YouTube `capi.deb` channel references from the README.
+  - Fixed the README install snippet (stale `4.17.11` → `4.17.15`) and the `45+` AI-agents count (→ `45`).
+  - Fixed a dead `/termux/api` link (now points to the official termux-api repo).
+  - `docs/cli/index.md`: corrected the misleading "resolves the `/cli/#<module>` anchors" note, renamed the duplicate `Modules` heading to `Module documentation pages`, and fixed the `network` module description (no longer misattributes OSINT).
+  - `docs/index.md`: module names are now clickable links to their per-module pages.
+  - All 17 module pages gained a `CLI reference` cross-link in their footer.
+  - Removed dead `.karnel-nav` CSS and added the branding logo site-wide via the `default.html` page header.
+  - Verified the existing GitHub Pages deploy already honors `docs/_config.yml` (baseurl/theme load correctly) — no deploy change needed.
+
+## 4.17.14
+
+- **Core security audit — fixed 12 critical bugs:**
+  - `agent_llm.sh`: config save now uses `%q` instead of `%s`, closing a command-injection/RCE vector when `source`ing saved agent config.
+  - `agent_actions.sh`: PLAN (read-only) mode now enforces a strict allowlist (`_agent_cmd_is_readonly`) so non-inspection commands (ruby, php, lua, etc.) can no longer bypass the guard.
+  - `zork/zork.sh`: rewritten with a self-contained safe extractor that rejects `..`/absolute paths and symlink escapes before moving files into `ZORK_DIR`.
+  - `zork/install.sh` / `bun/install.sh`: removed unsafe `unzip -o` / tar fallbacks; extraction now uses the hardened `safe_extract_zip` / `safe_extract_tar` helpers.
+  - `supabase`, `kiro`, `cline`, `kilocode-cli`, `keelcode` installers: replaced the local `safe_extract_tar` (which fell back to an unsafe `tar -xzf` on missing integrity helpers) with a self-contained, safe implementation that has no unsafe fallback.
+  - `restore.sh` / `pg.sh`: database restore no longer silences `tar` / `pg_restore` errors with `2>/dev/null`; failures are surfaced to the user.
+  - `shell.sh`: `OH_MY_ZSH_REF` is now escaped before being substituted into `sed` patterns, preventing delimiter injection.
+- **Site overhaul:**
+  - Fixed single-brace Liquid (`{{ }}`) on all 17 per-module pages (34 broken links resolved).
+  - `karnel open` gained a `robin` target (opens the OSINT module page) and a `herdr` target row in the CLI reference.
+  - Added a `## Modules` anchor section to the CLI reference so `/cli/#<module>` links resolve.
+  - Moved favicon + SEO meta into `<head>` via a `docs/_layouts/default.html` override of the cayman theme (previously dead `<body>`-level meta); set `logo:` for rich-link previews.
+
+## 4.17.13
+
+- Fixed the shell completion catalog (`scripts/completion.bash` / `completion.zsh`) to include the `herdr` utils tool, satisfying the `completion-catalog` CI gate.
+
+## 4.17.12
+
+- Generated real per-module documentation pages under `/karnel/<module>/` (all 17 modules: ai, auto, db, deploy, dev, editor, games, lang, network, npm, osint, plugin, security, shell, ui, utils, voice).
+- `karnel open <module>` now opens the in-site page (`/karnel/<module>/`) instead of the GitHub source; added a dedicated `herdr` open target that opens the utils page.
+- Featured **Herdr** prominently in the README and on the site landing page, with a `karnel install utils --herdr` callout.
+- Added `karnel/tools/utils/herdr/README.md` so `karnel show utils --herdr` renders proper documentation.
+- Site/CLI audit: fixed the stale "12 scripts" utils summary in the CLI reference (now lists all 13 tools including Herdr).
+
+## 4.17.11
+
+- Added the **Herdr** CLI to the `utils` module (`karnel install utils --herdr`), with checksum-verified download, atomic install, and Karnel ownership markers.
+- Critical runtime fixes:
+  - `cursor-cli`, `hermes-agent` and the `doctor` psutil patch now extract archives with the guarded `safe_extract_tar` (path-traversal/symlink protection).
+  - `pg schedule` now exports `PATH`/`PREFIX` in the cron job and logs failures instead of discarding output.
+  - `pg restore` uses `--single-transaction` and surfaces errors instead of silently retrying.
+  - `doctor --fix` no longer auto-applies destructive fixes (install-class, cache wipes, mass symlink deletion) without explicit confirmation; non-interactive sessions skip them (fail-closed).
+  - `doctor code --fix` now snapshots each rewritten file to `<file>.karnel-bak` before applying in-place formatters.
+  - `_fix_broken_symlinks` only removes broken symlinks that point into Karnel-managed paths.
+  - `karnel upgrade` no longer triggers a concurrent update check.
+  - `shell.sh` temp directory falls back to `KARNEL_CACHE` instead of `/tmp`.
+- Website/documentation overhaul: `karnel open` now resolves to real GitHub source URLs (no more 404s), canonical site URL unified to GitHub Pages, utility-tool count corrected to 13 (Herdr added), cloud-backup docs corrected to rclone, added `karnel upgrade` to the command table, and added favicon/SEO meta + Troubleshooting nav.
+
 ## 4.17.10
 
 - Round 10 security/correctness hardening (23 distinct fixes):
@@ -281,7 +406,7 @@ layout: base
   error gating, npm package inspection, CI, and release automation.
 - Corrected competing stderr redirections in three installers.
 
-## Unreleased - 2026-07-16
+## 2026-07-16 — Doctor command surface (shipped before 4.8.0)
 
 ### Doctor command surface
 

package/docs/_config.yml

@@ -4,10 +4,9 @@ description: >-
   editors, and more with one command.
 author: Israel Marques
 lang: en-US
+logo: /assets/images/karnel-logo.png
 theme: jekyll-theme-cayman
 markdown: kramdown
-logo: /assets/images/karnel-logo.png
-custom_css: /karnel-termux/assets/css/style.css
 baseurl: /karnel-termux
 show_downloads: false
 exclude:

package/docs/_layouts/base.html

@@ -9,7 +9,7 @@ layout: default
   <a href="{{ '/troubleshooting/' | relative_url }}">Troubleshooting</a>
   <a href="{{ '/ARCHITECTURE/' | relative_url }}">Architecture</a>
   <a href="{{ '/CHANGELOG/' | relative_url }}">Changelog</a>
-  <a href="https://israelmarques1024-dotcom.github.io/karnel-termux/">Live Site</a>
+  <a href="https://github.com/israelmarques1024-dotcom/karnel-termux">GitHub</a>
 </nav>
 
 {{ content }}

package/docs/_layouts/default.html

@@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html lang="{{ site.lang | default: "en-US" }}">
+  <head>
+    <meta charset="UTF-8">
+    <link rel="icon" href="{{ '/assets/images/karnel-logo.png' | relative_url }}">
+    <link rel="apple-touch-icon" href="{{ '/assets/images/karnel-logo.png' | relative_url }}">
+{% seo %}
+    <link rel="preconnect" href="https://fonts.gstatic.com">
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700&display=swap" crossorigin>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="theme-color" content="#157878">
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+    <link rel="stylesheet" href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}">
+    {% include head-custom.html %}
+  </head>
+  <body>
+    <a id="skip-to-content" href="#content">Skip to the content.</a>
+
+    <header class="page-header" role="banner">
+      <img class="karnel-logo" src="{{ '/assets/images/karnel-logo.png' | relative_url }}" alt="Karnel Termux" width="120" height="120">
+      <h1 class="project-name">{{ page.title | default: site.title | default: site.github.repository_name }}</h1>
+      <h2 class="project-tagline">{{ page.description | default: site.description | default: site.github.project_tagline }}</h2>
+      {% if site.github.is_project_page %}
+        <a href="{{ site.github.repository_url }}" class="btn">View on GitHub</a>
+      {% endif %}
+      {% if site.show_downloads %}
+        <a href="{{ site.github.zip_url }}" class="btn">Download .zip</a>
+        <a href="{{ site.github.tar_url }}" class="btn">Download .tar.gz</a>
+      {% endif %}
+    </header>
+
+    <main id="content" class="main-content" role="main">
+      {{ content }}
+
+      <footer class="site-footer">
+        {% if site.github.is_project_page %}
+          <span class="site-footer-owner"><a href="{{ site.github.repository_url }}">{{ site.github.repository_name }}</a> is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a>.</span>
+        {% endif %}
+        <span class="site-footer-credits">This page was generated by <a href="https://pages.github.com">GitHub Pages</a>.</span>
+      </footer>
+    </main>
+  </body>
+</html>

package/docs/assets/css/style.scss

@@ -17,6 +17,21 @@
   color-scheme: dark light;
 }
 
+/* Respect the OS theme: without this the dark palette above is unconditional
+   and the light fallbacks used across the stylesheet are unreachable. */
+@media (prefers-color-scheme: light) {
+  :root {
+    --karnel-bg: #ffffff;
+    --karnel-panel: #f6f8fa;
+    --karnel-border: #d0d7de;
+    --karnel-accent: #0969da;
+    --karnel-accent-2: #0078d4;
+    --karnel-text: #24292f;
+    --karnel-muted: #57606a;
+    --karnel-code-bg: #f6f8fa;
+  }
+}
+
 html {
   scroll-behavior: smooth;
 }
@@ -79,45 +94,6 @@ body {
   font-size: 1.1rem;
 }
 
-/* Landing navigation */
-.karnel-nav {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.6rem;
-  margin: 1.5rem 0 2rem;
-  padding: 0;
-  list-style: none;
-}
-
-.karnel-nav li {
-  margin: 0;
-}
-
-.karnel-nav a {
-  display: inline-block;
-  padding: 0.5rem 1rem;
-  border: 1px solid var(--karnel-accent-2, #0078d4);
-  border-radius: 999px;
-  text-decoration: none;
-  font-weight: 600;
-  font-size: 0.92rem;
-  color: #fff;
-  background: rgba(0, 120, 212, 0.12);
-  transition: background 0.15s ease, transform 0.15s ease;
-}
-
-.karnel-nav a:hover {
-  background: rgba(0, 120, 212, 0.28);
-  transform: translateY(-1px);
-}
-
-@media (prefers-color-scheme: dark) {
-  .karnel-nav a {
-    color: #c9d1d9;
-    border-color: var(--karnel-border);
-  }
-}
-
 /* Tables */
 .main-content table {
   display: table;
@@ -184,16 +160,6 @@ body {
   border-radius: 0 6px 6px 0;
 }
 
-/* Admonition callouts */
-.karnel-note {
-  border: 1px solid var(--karnel-accent-2, #0078d4);
-  border-left-width: 4px;
-  border-radius: 8px;
-  padding: 0.75rem 1rem;
-  margin: 1.25rem 0;
-  background: rgba(0, 120, 212, 0.06);
-}
-
 /* Section spacing */
 .main-content h2 {
   margin-top: 2.5rem;