Improve one-liner → full overlay UX + vendored engine docs

README.md

@@ -16,27 +16,20 @@ Turn Termux + proot Kali into a Linux development environment on your phone, wit
 
 Source: [`website/`](website/) · deploy: push `website/**` or **Actions → Deploy website**.
 
-
 ---
 
-## Quick install
+## Recommended install (copy-paste)
 
 ```bash
-# One-liner (Termux from F-Droid / GitHub — not Play Store)
-bash <(curl -fsSL https://raw.githubusercontent.com/FineComputer14451/GrokHunter/main/install.sh)
-
-# Or clone
+# Termux from F-Droid or GitHub — not Play Store
 git clone https://github.com/FineComputer14451/GrokHunter.git
-cd GrokHunter && bash install.sh
-```
-
-### Recommended full stack
-
-```bash
+cd GrokHunter
 bash install.sh --full --de xfce --browser chromium \
-  --with-grok --with-x11 --with-aider --with-v9-models
+  --with-grok --with-x11 --with-aider --with-v9-models --with-completions
 ```
 
+This is the **full coding lab**: Kali rootfs + XFCE + Grok Build + Termux:X11 + Aider + V9 pickers + agents/skills/menu.
+
 | Component | What you get |
 |-----------|----------------|
 | Kali rootfs | Latest NetHunter **rootless** image (proot) |
@@ -47,12 +40,40 @@ bash install.sh --full --de xfce --browser chromium \
 | Agents / personas / roles | Coding Team + lab specialists (`skills install`) |
 | V9 pickers | `/model chat-expert` · `multi` · `auto` · `grok-v9` aliases |
 
+### One-liner (core only)
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/FineComputer14451/GrokHunter/main/install.sh) \
+  --full --de xfce --with-grok --with-x11
+```
+
+> **Note:** A pure one-liner installs the core modules. For Coding Team agents, personas, Kali menu and shortcuts, also clone the repo and run:
+> ```bash
+> git clone https://github.com/FineComputer14451/GrokHunter.git ~/GrokHunter
+> cd ~/GrokHunter && grokhunter skills install
+> ```
+
 Refresh cached modules after upgrades:
 
 ```bash
 GROKHUNTER_REFRESH=1 bash install.sh --help
 ```
 
+### Reproducible / offline installs
+
+```bash
+git clone https://github.com/FineComputer14451/GrokHunter.git
+cd GrokHunter
+mkdir -p vendor
+curl -fsSL https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh \
+  -o vendor/termux-distro.sh
+# optional integrity pin:
+# export GROKHUNTER_DISTRO_ENGINE_SHA256=$(sha256sum vendor/termux-distro.sh | awk '{print $1}')
+bash install.sh --full --de xfce --with-grok --with-x11 --with-completions
+```
+
+The installer prefers `vendor/termux-distro.sh` when present. See [vendor/README.md](vendor/README.md).
+
 ---
 
 ## Why this stack?
@@ -144,7 +165,7 @@ install.sh                 Termux one-liner entry (wake-lock, module cache)
 lib/
   cli.sh                   Flags & help
   actions.sh               Rootfs / DE / Grok / X11 / Aider / V9 hooks
-  grok.sh                  Grok Build + Aider + V9 helpers
+  grok.sh                  Grok Build + Aider / V9 helpers
   x11.sh                   Termux:X11 + nh-x11 + /tmp bind patch
 bin/
   grokhunter               status | doctor | models | ai-smoke | ensure | plan | install
@@ -161,6 +182,7 @@ skills/                    grokhunter · pair-programming · aider-grok · x11-d
 agents/                    benjamin · lucas · harper · coding-team
                            (install → ~/.grok/agents; Grok runtime /config-agents)
 docs/                      INSTALL, FAQ, X11, PROOT, EDITORS, GROK-45
+vendor/                    Optional vendored termux-distro.sh (reproducible / offline)
 ```
 
 ---
@@ -192,6 +214,7 @@ Keep API keys in `~/.grok/secrets.env` (mode `600`).
 | [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Fixes |
 | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design |
 | [CREDITS.md](CREDITS.md) | **jorexdeveloper** + upstream attribution |
+| [vendor/README.md](vendor/README.md) | Vendoring the install engine |
 
 ---
 

docs/ARCHITECTURE.md

@@ -39,7 +39,7 @@ GrokHunter does **not** require Magisk, custom recovery, HID, or firmware module
 
 1. Detect Termux + architecture  
 2. Load `lib/*` (local clone or versioned cache; never leave engines in CWD)  
-3. Load `termux-distro` engine (vendored next to `install.sh` → `~/.cache/grokhunter/termux-distro.sh` → download into cache; override with `GROKHUNTER_DISTRO_ENGINE_URL`)  
+3. Load `termux-distro` engine (`vendor/termux-distro.sh` → `./termux-distro.sh` → `~/.cache/grokhunter/termux-distro.sh` → download; override with `GROKHUNTER_DISTRO_ENGINE_URL`)  
 4. Pull latest NetHunter rootfs (`/current/`, live SHA256) + storage pre-check  
 5. Optional: desktop + browser (session name saved for `nh-x11`; Chromium gets `--no-sandbox`)  
 6. Optional: Grok Build via `scripts/ensure_grok.sh`  
@@ -85,10 +85,37 @@ One-liner installs **download and execute** remote scripts (this repo’s module
 | Engine cache | `termux-distro.sh` under `~/.cache/grokhunter`, not CWD |
 | Override URLs | `GROKHUNTER_DISTRO_ENGINE_URL`, `GROKHUNTER_GROK_*_URL` |
 | Refresh | `GROKHUNTER_REFRESH=1 bash install.sh …` |
-| Pin later | Vendor `termux-distro.sh` next to `install.sh` |
+| Vendor | Place `vendor/termux-distro.sh` (preferred) or `./termux-distro.sh` |
+| Integrity | Optional `GROKHUNTER_DISTRO_ENGINE_SHA256=<hex>` |
 
 Remote `curl | bash` remains a residual risk shared with most CLI installers.
 
+## Vendoring the install engine
+
+GrokHunter can run completely offline / air-gapped once the engine is vendored:
+
+```bash
+mkdir -p vendor
+curl -fsSL \
+  https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh \
+  -o vendor/termux-distro.sh
+```
+
+Priority inside `resolve_distro_engine()`:
+
+1. `vendor/termux-distro.sh`
+2. `./termux-distro.sh`
+3. `~/.cache/grokhunter/termux-distro.sh`
+4. Network download
+
+Optional integrity pin:
+
+```bash
+export GROKHUNTER_DISTRO_ENGINE_SHA256=$(sha256sum vendor/termux-distro.sh | awk '{print $1}')
+```
+
+See [vendor/README.md](../vendor/README.md).
+
 ## Uninstall policy
 
 Removes wrappers, skills, shell markers. Keeps Grok binary, auth, and user projects.  

docs/UX-VENDOR-PATCH-NOTES.md

@@ -0,0 +1,29 @@
+# UX + vendor engine improvements (v1.0.8 prep)
+
+This branch applies:
+
+1. **lib/actions.sh** — post-install full-overlay nudge when one-liner is used
+2. **README.md** — recommended full stack first; one-liner note; reproducible/offline section
+3. **docs/ARCHITECTURE.md** — vendoring priority + SHA pin docs
+4. **vendor/README.md** — how to vendor termux-distro.sh
+
+## Remaining code patches (apply locally or follow-up PR)
+
+See the review conversation for full diffs of:
+
+- `install.sh` → `resolve_distro_engine()` with `vendor/` preference + optional `GROKHUNTER_DISTRO_ENGINE_SHA256`
+- `lib/grok.sh` → clearer incomplete-overlay reporting in `install_cli_bins`
+- `bin/grokhunter-doctor` → new "Overlay completeness" section + tip in summary
+
+## Test
+
+```bash
+# With vendored engine
+mkdir -p vendor
+curl -fsSL https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh \
+  -o vendor/termux-distro.sh
+GROKHUNTER_REFRESH=1 bash install.sh --overlay-only --with-completions --help
+
+# Doctor should surface overlay completeness after doctor patch lands
+grokhunter doctor
+```

lib/actions.sh

@@ -179,6 +179,36 @@ post_complete_actions() {
   msg -a "    grokhunter doctor      # health report"
   msg -a "    source ~/.grok/profile.sh  # zsh/bash completions"
   echo
+
+  # Detect whether the user has a full overlay tree (agents/skills/bin)
+  local has_full_tree=0
+  local root=""
+  for d in "${SCRIPT_DIR:-}" "${GROKHUNTER_HOME:-}" "${HOME}/GrokHunter"; do
+    if [[ -n "${d}" && -d "${d}/bin" && -d "${d}/skills" && -d "${d}/agents" ]]; then
+      root="${d}"
+      has_full_tree=1
+      break
+    fi
+  done
+
+  if [[ ${has_full_tree} -eq 0 ]]; then
+    msg -a "  ${Y}────────────────────────────────────────────────────────────${S}"
+    msg -a "  ${Y}Full agents / skills / menu not installed yet${S}"
+    msg -a "  ${Y}(one-liner only installed the core modules)${S}"
+    echo
+    msg -a "  To unlock Coding Team, personas, Kali menu & shortcuts:"
+    msg -a "    git clone https://github.com/FineComputer14451/GrokHunter.git ~/GrokHunter"
+    msg -a "    cd ~/GrokHunter"
+    msg -a "    grokhunter skills install          # or: bash install.sh --overlay-only --with-completions"
+    msg -a "    grokhunter doctor"
+    msg -a "  ${Y}────────────────────────────────────────────────────────────${S}"
+    echo
+  else
+    msg -a "  ${T}Full overlay detected:${S} ${root}"
+    msg -a "  Agents / skills / menu already available."
+    echo
+  fi
+
   msg -a "  ${T}Auth:${S}  export XAI_API_KEY=xai-...  or put it in ~/.grok/secrets.env"
   msg -a "  ${T}Docs:${S}   docs/EDITORS.md  docs/GROK-45.md  docs/X11-PERFORMANCE.md"
   echo

vendor/README.md

@@ -0,0 +1,50 @@
+# Vendored upstream components
+
+## termux-distro.sh
+
+GrokHunter prefers a **vendored** copy of jorexdeveloper’s `termux-distro.sh`
+when present. This makes installs reproducible and works offline / air-gapped.
+
+### How to vendor
+
+```bash
+# From a GrokHunter clone
+mkdir -p vendor
+curl -fsSL \
+  https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh \
+  -o vendor/termux-distro.sh
+
+# Optional: record the SHA for integrity checks
+sha256sum vendor/termux-distro.sh
+# → set GROKHUNTER_DISTRO_ENGINE_SHA256=<that-hash>
+```
+
+Current upstream tip (2026-08-21) SHA256 example:
+
+```
+f96add579ba2f4c54428b7a668c9b6732c6b59cfc18f258edd497677890faf16
+```
+
+(Re-compute after every upstream update.)
+
+### Priority used by install.sh
+
+1. `vendor/termux-distro.sh`          ← preferred
+2. `./termux-distro.sh`               (next to install.sh)
+3. `~/.cache/grokhunter/termux-distro.sh`
+4. Fresh download (or `GROKHUNTER_DISTRO_ENGINE_URL`)
+
+### Integrity (optional)
+
+```bash
+export GROKHUNTER_DISTRO_ENGINE_SHA256="<sha256 of the vendored file>"
+bash install.sh --full --de xfce --with-grok --with-x11
+```
+
+If the SHA does not match, the installer refuses the mismatched file and falls
+through (or aborts on download mismatch).
+
+### License
+
+`termux-distro.sh` is **GPL-3.0** © jorexdeveloper and contributors.  
+See `../CREDITS.md`. GrokHunter does not re-claim authorship.