fix: pos config ai splits llamacpp into its own section

LLAMACPP_* keys lived under a generic General group. Added a conditional '@[AI_PROVIDER=llamacpp] llamacpp' caption (mirrors OpenRouter), so the provider gets its own section; General now only holds AI_SYSTEM_PROMPT plus the HF keys that arrive from pos-ai-hf. AI_PROVIDER description and usage text mention llamacpp. Also: inactive config groups no longer dim the key name — keys stay bold so an inactive provider block is not one uniform grey wall; only values and descriptions dim, and the caption still carries the inactive reason.
fix: pos config ai shows broken LLAMACPP_* entries
2026-09-04 13:13:52 -04:00 · 2026-09-04 13:01:44 -04:00 · 2026-09-04 12:40:50 -04:00 · 2026-09-04 11:54:28 -04:00
10 changed files with 1085 additions and 28 deletions
@@ -42,6 +42,8 @@ summary (newest last).

 ## Done

+- **2026-09-04** — `pos ai hf` (`bin/pos-ai-hf`) — Hugging Face model downloader. Subcommands: `download <repo-id> [filename]` (single file, whole repo, `--gguf` filter, `--branch <rev>`, `--output <dir>`), `search <query>`, `list`, `remove`. Downloads to `~/.local/share/linux_post_install/ai/models/<namespace>-<model-name>/` (seam-guarded `HF_DOWNLOAD_DIR`), writes `.hf-meta` JSON per repo, prints structured summary (📥/📁). Config extends the existing `ai` scope via `# POS_CONFIG: ai` — `HF_TOKEN` (secret) and `HF_DOWNLOAD_DIR` in `~/.config/linux_post_install/ai.env` with env-var precedence. Auth on all requests; HTTP 429 rate-limit sleep + retry once; resume via `curl -C -`; progress bars to stderr. Deps: `curl`/`jq` guards before `--help`; no stdin → not in INTERACTIVE_CMDS. Verified: stub-PATH suite `/tmp/opencode/hf-test/run-tests.sh` 46/46 green (argument parsing, download single/multi/gguf/branch/output, search, list, remove, config/token, output format); `bash -n`; `make gen && make check` green; `make lint` 0 FAIL / 0 WARN. Docs: POS.md ai row + detail block.
+
 - **2026-09-04** — `pos media grab` (`bin/pos-media-grab`) — auto-download a URL as audio or video. Classifies by domain (YouTube Music/SoundCloud/Bandcamp → mp3; YouTube/Vimeo/Twitch → mp4) with `--audio`/`--video` overrides and `GRAB_DEFAULT` config (`pos config grab`, default `video`) for unknown domains; `--best` default for video (non-interactive, `--worst` override); all flags (`--output`, `--no-playlist`, `--cookies`, `--dry-run`) forwarded to mp3/mp4; prints a clean summary (🎵/🎬 title, duration, path, size). Telegram listener (`bin/pos-communication-telegram-listener`) gains `url_detect` + a URL routing step between the prefix map and AI bridge — bare http(s) URLs route to `pos media grab --best` (600s timeout). Verified: `/tmp/opencode/media-grab-test/run-tests.sh` 28 cases / 70 assertions green; `bash -n` on both files; `make gen && make check` green; `make lint` 0 FAIL / 0 WARN.

 - **2026-08-21** — Share suite interactive layer (`lib/share-lib.sh` + menu modes for all five `pos share *` tools): bare invocation now opens an EOF-safe looping menu instead of printing usage. New `lib/share-lib.sh` (436 lines) owns the shared primitives — `share_menu_guard`/`share_menu_run`/`share_pick`/`share_ask_value` (quit on EOF so non-tty callers can't hang), `share_require_bin`/`share_port_probe`/`share_service_active`/`share_path_probe` rc-only probes, `share_usb_records` (blank-line-record parser for usbsrv listings), `share_smb_shares` (smbclient `-g` Disk enumeration incl. guest→auth retry) + `share_usb_devices`/`share_usb_clients`, `share_nfs_exports` (showmount), `share_folder_candidates` (bounded-probe scan of mounted targets + conventional roots; container overlay/tmpfs/nsfs excluded via findmnt; clients build their own mountpoint pickers on top), and advisories `share_ufw_blocks_ports`+`share_offer_fix`. Tools keep every legacy flag/subcommand byte-compatible (verbatim command bodies, thin menu layer on top): nfs-server gains a client-spec presets picker + inactive-service/UFW offers, nfs-client gains idempotent unmount/unpersist (already-absent = report, rc0) + persist-verify-with-rollback + replace-confirm, smb-server gets UFW offer + menu tree, smb-client gets enumerate→pick→mount with account reuse (`SMB_AUTH_USER` contract), usb-server picker-first with raw-listing manual-entry fallback when the server listing is unreadable. New seams: `EXPORTS_FILE` (nfs-server), `UNIT_DIR` (nfs-client); `bin/pos` INTERACTIVE_CMDS += both stdin-reading share tools; install.sh lib list += share-lib.sh; preinstall.sh += smbclient (smb-client enumeration dep). Docs: POS.md share rows/detail, howto/share.md per-tool Interactive-menu notes, SCRIPTS.md phase table + new `## lib/share-lib.sh` section, DEV.md lib row + env-seam registry, AGENT_Context hand-maintained spots (lib table row 436, Phase-2 prose). Verified: 80-case stub battery vs recaptured deterministic golden — only the 9 documented intentional deltas differ (additive help lines, seam-path strings in messages, missing-dep message delta, unmount-idle FLAGGED→rc0, unpersist round-trip now works, usbs-bare usage→menu guard); 12/12 PTY tests (menus open/quit non-tty, filter/zero-match/default/cancel picker semantics, full nfs-server share flow writes the export line, usb-server share via pickers + down-server fallback, smb-client guest-enumerate→manual-share flow); real `/etc/exports` + `/etc/systemd/system` md5-verified untouched; `make gen && make check` green, `make lint` 0 FAIL / 0 WARN.
@@ -10,19 +10,19 @@

 <!-- GEN:START docmap -->
 | ## 1. Project Overview | 28–43 |
-| ## 2. Directory Structure | 44–205 |
-| ## 3. Installation Flow | 206–259 |
-| ## 4. The `pos` CLI System | 260–338 |
-| ## 5. Shared Library — `lib/common.sh` | 339–370 |
-| ## 6. Docker Compose / ScaleTail | 371–413 |
-| ## 7. Optional Apps (`apps/`) | 414–443 |
-| ## 8. Entertainment Module | 444–457 |
-| ## 9. Systemd Services | 458–469 |
-| ## 10. Configuration Files | 470–496 |
-| ## 11. Coding Conventions | 497–529 |
-| ## 12. Development Workflow | 530–582 |
-| ## 13. Key File Quick Reference | 583–655 |
-| ## 14. Common Tasks for Agents | 656–689 |
+| ## 2. Directory Structure | 44–209 |
+| ## 3. Installation Flow | 210–263 |
+| ## 4. The `pos` CLI System | 264–344 |
+| ## 5. Shared Library — `lib/common.sh` | 345–376 |
+| ## 6. Docker Compose / ScaleTail | 377–419 |
+| ## 7. Optional Apps (`apps/`) | 420–449 |
+| ## 8. Entertainment Module | 450–463 |
+| ## 9. Systemd Services | 464–475 |
+| ## 10. Configuration Files | 476–502 |
+| ## 11. Coding Conventions | 503–535 |
+| ## 12. Development Workflow | 536–588 |
+| ## 13. Key File Quick Reference | 589–663 |
+| ## 14. Common Tasks for Agents | 664–697 |
 <!-- GEN:END docmap -->

 ## 1. Project Overview
@@ -63,7 +63,11 @@ Linux_post_install/
 <!-- GEN:START tree -->
 │   ├── pos-ai-alias                        # manage AI agent aliases
 │   ├── pos-ai-gemini                       # Forward to pos ai --provider gemini (backward compat)
+│   ├── pos-ai-hf                           # Download AI models from Hugging Face (search, download, manage)
+│   │   [deps: curl jq]
 │   ├── pos-ai-openrouter                   # Forward to pos ai --provider openrouter (backward compat)
+│   ├── pos-ai-server                       # llama.cpp local inference server (start, stop, status, models, logs)
+│   │   [deps: curl jq]
 │   ├── pos-communication-matrix-listener   # Matrix listener: map /command → bash, run them on room messages
 │   ├── pos-communication-matrix-sender     # Send messages to a Matrix room via the client-server API (send, test, login)
 │   ├── pos-communication-scrcpy            # Mirror/control an Android device via scrcpy+adb (mirror, devices, record, tcpip, connect, push, pull, screenshot, info)
@@ -278,7 +282,9 @@ All non-interactive `pos` commands log output to `~/.local/share/linux_post_inst
 |----------|---------|--------|-------------|------|----------|
 | ai | alias | `pos-ai-alias` | manage AI agent aliases |  |  |
 | ai | gemini | `pos-ai-gemini` | Forward to pos ai --provider gemini (backward compat) |  |  |
+| ai | hf | `pos-ai-hf` | Download AI models from Hugging Face (search, download, manage) | curl jq | pos ai hf search llama 7b → Search Hugging Face for "llama 7b" models · pos ai hf download meta-llama/Llama-3.1-8B-Instruct → Download all files from a repo · pos ai hf download meta-llama/Llama-3.1-8B-Instruct --gguf → Download only GGUF quantized files · pos ai hf download meta-llama/Llama-3.1-8B-Instruct config.json → Download a single file · pos ai hf list → List downloaded models · pos ai hf remove meta-llama-Llama-3.1-8B-Instruct → Remove a downloaded model |
 | ai | openrouter | `pos-ai-openrouter` | Forward to pos ai --provider openrouter (backward compat) |  |  |
+| ai | server | `pos-ai-server` | llama.cpp local inference server (start, stop, status, models, logs) | curl jq |  |
 | communication | matrix-listener | `pos-communication-matrix-listener` | Matrix listener: map /command → bash, run them on room messages |  |  |
 | communication | matrix-sender | `pos-communication-matrix-sender` | Send messages to a Matrix room via the client-server API (send, test, login) |  |  |
 | communication | scrcpy | `pos-communication-scrcpy` | Mirror/control an Android device via scrcpy+adb (mirror, devices, record, tcpip, connect, push, pull, screenshot, info) |  |  |
@@ -607,7 +613,9 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos` | 302 | CLI dispatcher with smart arg matching + logging + category help |
 | `bin/pos-ai-alias` | 760 | manage AI agent aliases |
 | `bin/pos-ai-gemini` | 7 | Forward to pos ai --provider gemini (backward compat) |
+| `bin/pos-ai-hf` | 495 | Download AI models from Hugging Face (search, download, manage) |
 | `bin/pos-ai-openrouter` | 7 | Forward to pos ai --provider openrouter (backward compat) |
+| `bin/pos-ai-server` | 444 | llama.cpp local inference server (start, stop, status, models, logs) |
 | `bin/pos-communication-matrix-listener` | 568 | Matrix listener: map /command → bash, run them on room messages |
 | `bin/pos-communication-matrix-sender` | 224 | Send messages to a Matrix room via the client-server API (send, test, login) |
 | `bin/pos-communication-scrcpy` | 254 | Mirror/control an Android device via scrcpy+adb (mirror, devices, record, tcpip, connect, push, pull, screenshot, info) |
@@ -644,10 +652,10 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-system-health` | 209 | Host health dashboard (disk, RAM, services, backup age, fail2ban, docker); exit 1 if any FAIL |
 | `bin/pos-system-schedule` | 151 | Scheduled jobs: run a command on a timer; notify on threshold/change/error/always or silently |
 | `bin/pos-system-uninstall` | 435 | Remove pos toolkit binaries, services, shell integration, config, and data |
-| `bin/pos-ai` | 692 | AI assistant: ask, chat, sessions, capture, models, providers |
+| `bin/pos-ai` | 702 | AI assistant: ask, chat, sessions, capture, models, providers |
 | `bin/pos-config` | 80 | Interactive editor for the tools' runtime config (reads # POS_CONFIG: registry) |
 | `bin/pos-tree` | 118 | Show the pos CLI command tree: categories, commands, and subcommands |
-| `completions/pos.bash` | 309 | Dynamic bash completion |
+| `completions/pos.bash` | 312 | Dynamic bash completion |
 <!-- GEN:END filetable -->
 | `apps/install.sh` | 171 | App install/uninstall picker/orchestrator |

@@ -55,8 +55,8 @@ Category-less tools (`config`, `tree`) live outside any category and are documen

 ### ai

-**File:** `bin/pos-ai` (provider-agnostic main tool), `bin/pos-ai-gemini` / `bin/pos-ai-openrouter` (backward-compat forwarders → `pos ai --provider <name>`)
-**Provider adapters:** `lib/ai-providers/gemini.sh`, `lib/ai-providers/openrouter.sh`
+**File:** `bin/pos-ai` (provider-agnostic main tool), `bin/pos-ai-gemini` / `bin/pos-ai-openrouter` (backward-compat forwarders → `pos ai --provider <name>`), `bin/pos-ai-hf` (Hugging Face model downloader), `bin/pos-ai-server` (llama.cpp inference server manager)
+**Provider adapters:** `lib/ai-providers/gemini.sh`, `lib/ai-providers/openrouter.sh`, `lib/ai-providers/llamacpp.sh`
 **Purpose:** AI assistant with pluggable providers. Six subcommands: `ask` (scriptable, persistent session), `capture` (run a command and save its output for `--last`), `chat` (interactive multi-turn REPL), `models` (list available models), `providers` (list providers and config status), and `sessions` (list/clear sessions). Providers handle API-specific logic; the main tool handles sessions, rendering, machine context, and all shared logic.

 | Command | Behavior |
@@ -100,6 +100,29 @@ Model precedence: `--model` flag > `AI_MODEL` env > provider-specific fallback (

 **Messaging bridges:** the Telegram and Matrix listeners forward non-command messages starting with `ai ` (case-insensitive) to `pos ai ask` and reply with the model's answer — see [communication → listener](#communication). The Telegram bridge uses one session per chat (`telegram-<chat id>`), the Matrix bridge one per room (`matrix-<room>`).

+`pos ai hf` — Hugging Face model downloader:
+
+| Command | Behavior |
+|---------|----------|
+| `pos ai hf search <query>` | Search Hugging Face models by query (sorted by downloads); prints model ID, download count |
+| `pos ai hf download <repo-id> [filename]` | Download a file or entire repo from Hugging Face. Creates `<namespace>-<model-name>/` under `HF_DOWNLOAD_DIR` (default `~/.local/share/linux_post_install/ai/models/`). Options: `--branch <rev>` (specific branch), `--gguf` (only `.gguf` files), `--output <dir>` (override download dir). Progress bars to stderr; summary with path and size to stdout. Writes `.hf-meta` JSON (repo-id, branch, files, timestamp) for `list` and `remove` |
+| `pos ai hf list` | List all downloaded models with size and date |
+| `pos ai hf remove <repo-id>` | Remove a downloaded model directory and show freed space |
+
+Auth: `HF_TOKEN` in `~/.config/linux_post_install/ai.env` (same scope as `pos ai`; edit via `pos config ai`). Even for public repos, a token increases rate limits from 500/5min to 1000/5min. Resume: `curl -C -` resumes interrupted downloads. Rate limit handling: on HTTP 429, sleeps `Retry-After` or 60s, retries once.
+
+`pos ai server` — llama.cpp local inference server manager:
+
+| Command | Behavior |
+|---------|----------|
+| `pos ai server start [model]` | Generate and start a systemd user service running llama-server. Model resolution: explicit arg > `LLAMACPP_MODEL` config > interactive pick (TTY only). Auto-detects GPU (CUDA via `nvidia-smi`); sets `--n-gpu-layers` accordingly. Writes unit to `~/.config/systemd/user/pos-ai-server.service`, runs `daemon-reload && enable --now`. Warns about linger if needed |
+| `pos ai server stop` | Stop and disable the systemd user service, remove the unit file |
+| `pos ai server status` | Show service state, loaded model (from `/v1/models`), port, host, GPU, context, threads, autostart, endpoint, and health (from `/health`) |
+| `pos ai server models` | List `.gguf` files found in `HF_DOWNLOAD_DIR` with sizes |
+| `pos ai server logs [lines]` | Show recent server logs via `journalctl --user -u pos-ai-server` (default 50 lines) |
+
+Flags: `--port <port>` (default 8088), `--host <addr>` (default 127.0.0.1), `--model <path>` (overrides arg/config), `--ctx <size>` (context window, default 4096), `--gpu <layers>` (-1=auto, 0=CPU, N=explicit, default -1), `--threads <n>` (default nproc). Config keys in `ai.env`: `LLAMACPP_PORT`, `LLAMACPP_HOST`, `LLAMACPP_MODEL`, `LLAMACPP_CTX_SIZE`, `LLAMACPP_GPU_LAYERS`, `LLAMACPP_THREADS`. Requires `curl` + `jq` and a `llama-server` binary on PATH.
+
 ### network

 | Command | File | Purpose | Configuration |
@@ -3,7 +3,7 @@ set -euo pipefail
 # POS: ai ask — AI assistant: ask, chat, sessions, capture, models, providers
 # POS_SUBCMDS: ask chat sessions capture models providers
 # POS_FLAGS: --provider --model --session --system --full --last --trust
-# POS_CONFIG: ai | ai.env | AI_PROVIDER=:Provider (gemini or openrouter, default gemini) | @[AI_PROVIDER=gemini|] Gemini | *providers=gemini | @[AI_PROVIDER=openrouter] OpenRouter | *providers=openrouter | @General | AI_SYSTEM_PROMPT=:Custom system prompt (overrides built-in, empty to reset)
+# POS_CONFIG: ai | ai.env | AI_PROVIDER=:Provider (gemini, openrouter or llamacpp, default gemini) | @[AI_PROVIDER=gemini|] Gemini | *providers=gemini | @[AI_PROVIDER=openrouter] OpenRouter | *providers=openrouter | @[AI_PROVIDER=llamacpp] llamacpp | LLAMACPP_PORT=:Server port (default 8088) | LLAMACPP_HOST=:Bind address (default 127.0.0.1) | LLAMACPP_MODEL=:Default model path (GGUF) | LLAMACPP_CTX_SIZE=num:Context window size (default 4096) | LLAMACPP_GPU_LAYERS=num:GPU layers (-1=auto, 0=CPU, default -1) | LLAMACPP_THREADS=num:CPU threads (default: nproc) | *providers=llamacpp | @General | AI_SYSTEM_PROMPT=:Custom system prompt (overrides built-in, empty to reset)

 source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"

@@ -23,7 +23,7 @@ MAX_SESSION_TURNS=40
 LAST_LOG_MAX_BYTES=4096
 LAST_LOG_STALE_SECS=3600   # --last: warn when the attached log is older than this
 # Built-in terse ask prompt. cmd_ask appends a machine-context clause
-# (see machine_context) unless --system replaces it or --full drops everything.
+# (see machine_context) on EVERY ask — even --system/--full.
 DEFAULT_SYSTEM_PROMPT_HARD="You are a Linux CLI assistant. Rules:
 1. Lead with exact command(s) — no explanations unless asked
 2. One line max per command; short bullets for multi-step only
@@ -78,7 +78,7 @@ Options:
  -h|--help         This help.

 Config:  $CONFIG_FILE  (edit with 'pos config ai')
-  AI_PROVIDER         Provider to use (gemini|openrouter, default gemini)
+  AI_PROVIDER         Provider to use (gemini|openrouter|llamacpp, default gemini)
  AI_SYSTEM_PROMPT    Custom system prompt (overrides built-in; empty to reset)
  Provider keys:      auto-discovered from lib/ai-providers/*.sh
                      (AI_GEMINI_API_KEY, OPENROUTER_API_KEY, etc.)
@@ -167,6 +167,7 @@ resolve_key() {
    case "$p" in
        gemini)     [ -n "${AI_GEMINI_API_KEY:-}" ] && export AI_API_KEY="$AI_GEMINI_API_KEY" && return 0 ;;
        openrouter) [ -n "${OPENROUTER_API_KEY:-}" ] && export AI_API_KEY="$OPENROUTER_API_KEY" && return 0 ;;
+        llamacpp)   return 0 ;;  # No API key needed for local server
    esac
    return 1
 }
@@ -177,6 +178,7 @@ require_key() {
        case "$p" in
            gemini)     err "No Gemini API key — run 'pos config ai' and set AI_GEMINI_API_KEY" ;;
            openrouter) err "No OpenRouter API key — run 'pos config ai' and set OPENROUTER_API_KEY" ;;
+            llamacpp)   ;;  # No key needed for local server
        esac
        err "No API key for provider '$p' — run 'pos config ai'"
    fi
@@ -193,6 +195,7 @@ resolve_model() {
        case "$p" in
            gemini)     [ -n "${AI_GEMINI_MODEL:-}" ] && printf '%s' "$AI_GEMINI_MODEL" && return ;;
            openrouter) [ -n "${OPENROUTER_MODEL:-}" ] && printf '%s' "$OPENROUTER_MODEL" && return ;;
+            llamacpp)   [ -n "${LLAMACPP_MODEL:-}" ] && printf '%s' "$(basename "$LLAMACPP_MODEL")" && return ;;
        esac
        provider_default_model
    fi
@@ -499,7 +502,8 @@ cmd_ask() {
    fi
    require_key
    # Terse by default: user --system replaces the built-in prompt wholesale;
-    # --full skips everything (built-in text AND machine context).
+    # --full skips the built-in text. The machine-context line (hostname,
+    # distro, kernel, arch) is ALWAYS appended so every ask knows the box.
    system="$SYSTEM_PROMPT"
    if [ -z "$system" ] && [ "$FULL_MODE" -eq 0 ]; then
        # Check AI_SYSTEM_PROMPT config first, then fall back to built-in
@@ -507,9 +511,14 @@ cmd_ask() {
        if [ -z "$system" ]; then
            system="$DEFAULT_SYSTEM_PROMPT_HARD"
        fi
-        mc="$(machine_context)"
+    fi
+    mc="$(machine_context)"
+    if [ -n "$system" ]; then
        [ -n "$mc" ] && mc=" $mc"
        system="$system$mc"
+    else
+        # --full (no system text): carry machine context as the sole system turn
+        system="$mc"
    fi
    # Persistent session memory ('default' unless --session).
    messages="$(session_load)"
@@ -620,6 +629,7 @@ cmd_providers() {
        case "$name" in
            gemini)     [ -n "${AI_GEMINI_API_KEY:-}" ] && configured="configured" ;;
            openrouter) [ -n "${OPENROUTER_API_KEY:-}" ] && configured="configured" ;;
+            llamacpp)   configured="configured" ;;  # Local server — always configured
        esac
        current=""
        [ "$name" = "$active" ] && current=" ← active"
@@ -0,0 +1,495 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# POS: ai hf — Download AI models from Hugging Face (search, download, manage)
+# POS_FLAGS: --branch --gguf --output
+# POS_DEPS: curl jq
+# POS_CONFIG: ai | ai.env | HF_TOKEN=secret:Hugging Face API token (https://huggingface.co/settings/tokens) | HF_DOWNLOAD_DIR=:Model download directory (default ~/.local/share/linux_post_install/ai/models)
+# POS_EXAMPLES: pos ai hf search llama 7b | Search Hugging Face for "llama 7b" models
+# POS_EXAMPLES: pos ai hf download meta-llama/Llama-3.1-8B-Instruct | Download all files from a repo
+# POS_EXAMPLES: pos ai hf download meta-llama/Llama-3.1-8B-Instruct --gguf | Download only GGUF quantized files
+# POS_EXAMPLES: pos ai hf download meta-llama/Llama-3.1-8B-Instruct config.json | Download a single file
+# POS_EXAMPLES: pos ai hf list | List downloaded models
+# POS_EXAMPLES: pos ai hf remove meta-llama-Llama-3.1-8B-Instruct | Remove a downloaded model
+
+source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
+
+# ── Dependencies (before --help) ───────────────────────────────
+command -v curl &>/dev/null || err "curl not found (install curl)"
+command -v jq &>/dev/null   || err "jq not found (install jq)"
+
+# ── Config & defaults ──────────────────────────────────────────
+CONFIG_FILE="${CONFIG_FILE:-$HOME/.config/linux_post_install/ai.env}"
+HF_TOKEN="${HF_TOKEN:-}"
+HF_DOWNLOAD_DIR="${HF_DOWNLOAD_DIR:-$HOME/.local/share/linux_post_install/ai/models}"
+
+load_hf_config() {
+    [ -f "$CONFIG_FILE" ] || return 0
+    local k v
+    while IFS='=' read -r k v; do
+        [ -n "$k" ] || continue
+        case "$k" in
+            \#*) continue ;;
+        esac
+        v="${v%\"}"; v="${v#\"}"; v="${v%\'}"; v="${v#\'}"
+        v="${v//$'\r'/}"
+        if [ -z "${!k:-}" ]; then
+            export "$k"="$v"
+        fi
+    done < <(grep -E '^[A-Z_]+=' "$CONFIG_FILE" || true)
+}
+
+load_hf_config
+
+# ── Usage ──────────────────────────────────────────────────────
+usage() {
+    cat <<'EOF'
+Usage: pos ai hf <subcommand> [args]
+
+Hugging Face model downloader — search, download, and manage AI models.
+
+Subcommands:
+  search <query>                     Search Hugging Face models
+  download <repo-id> [filename]      Download a file or entire repo
+  list                               List downloaded models
+  remove <repo-id>                   Remove a downloaded model
+
+Download options:
+  --branch <rev>                     Download from a specific branch/revision
+  --gguf                             Download only .gguf files (inference-ready)
+  --output <dir>                     Override download directory
+
+Examples:
+  pos ai hf search llama 7b
+  pos ai hf download meta-llama/Llama-3.1-8B-Instruct
+  pos ai hf download meta-llama/Llama-3.1-8B-Instruct --gguf
+  pos ai hf download meta-llama/Llama-3.1-8B-Instruct config.json
+  pos ai hf download meta-llama/Llama-3.1-8B-Instruct --branch main
+  pos ai hf list
+  pos ai hf remove meta-llama-Llama-3.1-8B-Instruct
+
+Config (~/.config/linux_post_install/ai.env):
+  HF_TOKEN           Hugging Face API token (better rate limits for public repos)
+  HF_DOWNLOAD_DIR    Model download directory (default ~/.local/share/linux_post_install/ai/models)
+
+Exit codes:
+  0  success
+  1  error (missing deps, invalid input, API failure)
+EOF
+    exit 0
+}
+
+# ── Parse global flags ─────────────────────────────────────────
+SUBCMD=""
+SUBCMD_ARGS=()
+BRANCH=""
+GGUF_ONLY=0
+OUTPUT_DIR=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -h|--help) usage ;;
+        --branch)
+            [ $# -ge 2 ] || err "--branch requires a value"
+            BRANCH="$2"; shift 2 ;;
+        --gguf)
+            GGUF_ONLY=1; shift ;;
+        --output)
+            [ $# -ge 2 ] || err "--output requires a value"
+            OUTPUT_DIR="$2"; shift 2 ;;
+        -*)
+            err "Unknown option '$1' (see --help)" ;;
+        *)
+            if [ -z "$SUBCMD" ]; then
+                SUBCMD="$1"
+            else
+                SUBCMD_ARGS+=("$1")
+            fi
+            shift ;;
+    esac
+done
+
+[ -n "$SUBCMD" ] || usage
+
+# Apply output dir override
+if [ -n "$OUTPUT_DIR" ]; then
+    HF_DOWNLOAD_DIR="$OUTPUT_DIR"
+fi
+HF_DOWNLOAD_DIR="${HF_DOWNLOAD_DIR:-$HOME/.local/share/linux_post_install/ai/models}"
+
+# ── Token warning ──────────────────────────────────────────────
+if [ -z "$HF_TOKEN" ]; then
+    warn "No HF_TOKEN set — using anonymous access"
+fi
+
+# ── HF API helpers ─────────────────────────────────────────────
+HF_BASE="https://huggingface.co"
+HF_API_BASE="https://huggingface.co/api"
+
+hf_auth_header() {
+    if [ -n "$HF_TOKEN" ]; then
+        printf 'Authorization: Bearer %s' "$HF_TOKEN"
+    fi
+}
+
+hf_api() {
+    local endpoint="$1"
+    local url="${HF_API_BASE}${endpoint}"
+    local auth_header
+    auth_header="$(hf_auth_header)"
+
+    local http_code body tmpfile
+    tmpfile="$(mktemp)"
+
+    local curl_args=(-sS -w '%{http_code}' -o "$tmpfile" --max-time 30)
+    if [ -n "$auth_header" ]; then
+        curl_args+=(-H "$auth_header")
+    fi
+
+    # Rate limit retry: on 429, sleep and retry once
+    local attempt=0
+    while [ $attempt -lt 2 ]; do
+        http_code="$(curl "${curl_args[@]}" "$url" 2>/dev/null)" || {
+            rm -f "$tmpfile"
+            err "Connection timed out — check network"
+        }
+
+        if [ "$http_code" = "429" ]; then
+            local retry_after
+            retry_after="$(curl -sI -H "${auth_header:-}" "$url" 2>/dev/null | grep -i 'retry-after:' | tr -d '\r' | awk '{print $2}')"
+            retry_after="${retry_after:-60}"
+            warn "Rate limited — waiting ${retry_after}s before retry"
+            sleep "$retry_after"
+            attempt=$((attempt + 1))
+            continue
+        fi
+
+        break
+    done
+
+    body="$(cat "$tmpfile")"
+    rm -f "$tmpfile"
+
+    case "$http_code" in
+        200) ;;
+        401|403) err "Authentication failed — check HF_TOKEN (pos config ai)" ;;
+        404) err "Model not found: ${endpoint#/api/models/}" ;;
+        429) err "Rate limit exceeded — try again later" ;;
+        *)   err "API request failed (HTTP $http_code)" ;;
+    esac
+
+    # Validate JSON
+    if ! printf '%s' "$body" | jq empty 2>/dev/null; then
+        err "Failed to parse API response — check network or HF status"
+    fi
+
+    printf '%s' "$body"
+}
+
+hf_repo_files() {
+    local repo_id="$1"
+    local branch="${2:-main}"
+    local ns="${repo_id%%/*}"
+    local repo="${repo_id#*/}"
+
+    if [ "$ns" = "$repo" ]; then
+        err "Invalid repo format: use namespace/model-name"
+    fi
+
+    # Try /tree/ endpoint first (has file sizes + LFS info)
+    local endpoint="/models/${ns}/${repo}/tree/${branch}"
+    local result
+    if result="$(hf_api "$endpoint" 2>/dev/null)"; then
+        printf '%s' "$result"
+        return 0
+    fi
+
+    # Fallback: /api/models/{ns}/{repo} (siblings, no sizes)
+    warn "Tree endpoint unavailable, using repo metadata"
+    local fallback
+    fallback="$(hf_api "/models/${ns}/${repo}")" || err "Failed to fetch repo info for $repo_id"
+    printf '%s' "$fallback" | jq '[.siblings[] | {rfilename: .rfilename, size: (.size // 0)}]'
+}
+
+hf_search() {
+    local query="$1"
+    local limit="${2:-10}"
+    local encoded_query
+    encoded_query="$(printf '%s' "$query" | jq -sRr @uri)"
+    local endpoint="/models?search=${encoded_query}&sort=downloads&direction=-1&limit=${limit}"
+    hf_api "$endpoint"
+}
+
+# ── Utility functions ──────────────────────────────────────────
+hf_repo_dir() {
+    local repo_id="$1"
+    printf '%s' "$HF_DOWNLOAD_DIR/${repo_id//\//-}"
+}
+
+hf_human_size() {
+    local bytes="$1"
+    if [ "$bytes" -ge 1073741824 ]; then
+        awk "BEGIN { printf \"%.1f GB\", $bytes / 1073741824 }"
+    elif [ "$bytes" -ge 1048576 ]; then
+        awk "BEGIN { printf \"%.1f MB\", $bytes / 1048576 }"
+    elif [ "$bytes" -ge 1024 ]; then
+        awk "BEGIN { printf \"%.1f KB\", $bytes / 1024 }"
+    else
+        printf '%d B' "$bytes"
+    fi
+}
+
+hf_resolve_branch() {
+    local repo_id="$1"
+    local branch="${2:-}"
+    if [ -n "$branch" ]; then
+        printf '%s' "$branch"
+        return
+    fi
+    # Try to get default branch from API
+    local ns="${repo_id%%/*}"
+    local repo="${repo_id#*/}"
+    local meta
+    if meta="$(hf_api "/models/${ns}/${repo}" 2>/dev/null)"; then
+        local default_branch
+        default_branch="$(printf '%s' "$meta" | jq -r '.defaultBranch // empty' 2>/dev/null)"
+        if [ -n "$default_branch" ]; then
+            printf '%s' "$default_branch"
+            return
+        fi
+    fi
+    printf 'main'
+}
+
+# ── Download helpers ───────────────────────────────────────────
+hf_download_file() {
+    local url="$1"
+    local target="$2"
+    local auth_header
+    auth_header="$(hf_auth_header)"
+
+    local curl_args=(-L -C - --progress-bar -o "$target")
+    if [ -n "$auth_header" ]; then
+        curl_args+=(-H "$auth_header")
+    fi
+
+    if curl "${curl_args[@]}" "$url" 2>&1; then
+        if [ -s "$target" ]; then
+            return 0
+        else
+            warn "Downloaded file is empty: $target"
+            return 1
+        fi
+    else
+        warn "Download interrupted for $(basename "$target") (resume with same command)"
+        return 1
+    fi
+}
+
+# ── Subcommands ────────────────────────────────────────────────
+
+cmd_search() {
+    local query="${SUBCMD_ARGS[*]:-}"
+    [ -n "$query" ] || err "Usage: pos ai hf search <query>"
+
+    local result
+    result="$(hf_search "$query" "10")"
+
+    local count
+    count="$(printf '%s' "$result" | jq 'length')"
+    [ "$count" -gt 0 ] || { warn "No models found for '$query'"; return 0; }
+
+    printf 'Found %d models for "%s":\n' "$count" "$query"
+    printf '%s' "$result" | jq -r '.[] | "  \(.id)\t\(.downloads // 0)\t\(.likes // 0)"' | \
+        while IFS=$'\t' read -r id downloads likes; do
+            local dl_str
+            if [ "$downloads" -ge 1000 ]; then
+                dl_str="$(awk "BEGIN { printf \"%.1fk\", $downloads / 1000 }")"
+            else
+                dl_str="$downloads"
+            fi
+            printf '  %-55s %s downloads\n' "$id" "$dl_str"
+        done
+}
+
+cmd_download() {
+    local repo_id="${SUBCMD_ARGS[0]:-}"
+    [ -n "$repo_id" ] || err "Usage: pos ai hf download <repo-id> [filename]"
+
+    # Validate repo-id contains /
+    [[ "$repo_id" == */* ]] || err "Invalid repo format: use namespace/model-name"
+
+    local filename="${SUBCMD_ARGS[1]:-}"
+    local branch
+    branch="$(hf_resolve_branch "$repo_id" "$BRANCH")"
+
+    # Get file list from API
+    local files_json
+    files_json="$(hf_repo_files "$repo_id" "$branch")"
+
+    # Filter files
+    local filtered_files
+    if [ -n "$filename" ]; then
+        # Single file mode
+        filtered_files="$(printf '%s' "$files_json" | jq -c --arg fn "$filename" '[.[] | select(.rfilename == $fn)]')"
+    elif [ "$GGUF_ONLY" -eq 1 ]; then
+        # GGUF filter
+        filtered_files="$(printf '%s' "$files_json" | jq -c '[.[] | select(.rfilename | endswith(".gguf"))]')"
+    else
+        # All files
+        filtered_files="$(printf '%s' "$files_json" | jq -c '.')"
+    fi
+
+    local file_count
+    file_count="$(printf '%s' "$filtered_files" | jq 'length')"
+    [ "$file_count" -gt 0 ] || err "No files to download"
+
+    # Prepare target directory
+    local target_dir
+    target_dir="$(hf_repo_dir "$repo_id")"
+    mkdir -p "$target_dir"
+
+    # Disk space pre-flight check
+    local total_size
+    total_size="$(printf '%s' "$filtered_files" | jq '[.[].size // 0] | add // 0')"
+    if [ "$total_size" -gt 0 ]; then
+        local avail_kb
+        avail_kb="$(df --output=avail "$target_dir" 2>/dev/null | tail -1 | tr -d ' ')"
+        local need_kb=$((total_size / 1024))
+        if [ "$avail_kb" -lt "$need_kb" ]; then
+            local need_human avail_human
+            need_human="$(hf_human_size "$total_size")"
+            avail_human="$(hf_human_size "$((avail_kb * 1024))")"
+            warn "Low disk space: need $need_human, only $avail_human available"
+        fi
+    fi
+
+    local downloaded=0
+    local ns="${repo_id%%/*}"
+    local repo="${repo_id#*/}"
+
+    while IFS= read -r file_json; do
+        local fname fsize
+        fname="$(printf '%s' "$file_json" | jq -r '.rfilename')"
+        fsize="$(printf '%s' "$file_json" | jq -r '.size // 0')"
+        total_size=$((total_size + fsize))
+
+        local url="${HF_BASE}/${ns}/${repo}/resolve/${branch}/${fname}"
+        local target="${target_dir}/${fname}"
+
+        if [ "$file_count" -gt 1 ]; then
+            downloaded=$((downloaded + 1))
+            printf '[%d/%d] Downloading %s...\n' "$downloaded" "$file_count" "$fname" >&2
+        fi
+
+        # Create parent directory
+        mkdir -p "$(dirname "$target")"
+
+        if ! hf_download_file "$url" "$target"; then
+            warn "Failed to download $fname"
+            continue
+        fi
+    done < <(printf '%s' "$filtered_files" | jq -c '.[]')
+
+    # Write metadata
+    local meta_file="${target_dir}/.hf-meta"
+    local timestamp
+    timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    local file_list
+    file_list="$(printf '%s' "$filtered_files" | jq -c '[.[] | .rfilename]')"
+
+    cat > "$meta_file" <<METAEOF
+{
+  "repo_id": "$repo_id",
+  "branch": "$branch",
+  "downloaded_at": "$timestamp",
+  "files": $file_list
+}
+METAEOF
+
+    # Summary
+    if [ "$file_count" -eq 1 ]; then
+        local fname
+        fname="$(printf '%s' "$filtered_files" | jq -r '.[0].rfilename')"
+        local fsize
+        fsize="$(printf '%s' "$filtered_files" | jq -r '.[0].size // 0')"
+        local human_size
+        human_size="$(hf_human_size "$fsize")"
+        printf '📥 Downloaded: %s/%s (%s)\n' "$repo_id" "$fname" "$human_size"
+        printf '📁 %s/%s\n' "$target_dir" "$fname"
+    else
+        local total_human
+        total_human="$(hf_human_size "$total_size")"
+        printf '📥 Downloaded: %s (%d files, %s)\n' "$repo_id" "$file_count" "$total_human"
+        printf '📁 %s/\n' "$target_dir"
+    fi
+}
+
+cmd_list() {
+    [ -d "$HF_DOWNLOAD_DIR" ] || { warn "No models downloaded yet"; return 0; }
+
+    local models=()
+    while IFS= read -r dir; do
+        [ -d "$dir" ] || continue
+        local meta_file="${dir}/.hf-meta"
+        [ -f "$meta_file" ] || continue
+        models+=("$dir")
+    done < <(find "$HF_DOWNLOAD_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort)
+
+    [ ${#models[@]} -gt 0 ] || { warn "No models downloaded yet"; return 0; }
+
+    printf 'Downloaded models (%d):\n' "${#models[@]}"
+    for dir in "${models[@]}"; do
+        local meta_file="${dir}/.hf-meta"
+        local name
+        name="$(basename "$dir")"
+        local total_size=0
+        local date_str
+        date_str="$(jq -r '.downloaded_at // "unknown"' "$meta_file" 2>/dev/null | cut -dT -f1)"
+
+        # Calculate total size
+        while IFS= read -r file; do
+            [ -f "$file" ] || continue
+            local size
+            size="$(stat -c%s "$file" 2>/dev/null || echo 0)"
+            total_size=$((total_size + size))
+        done < <(find "$dir" -type f ! -name '.hf-meta' 2>/dev/null)
+
+        local human_size
+        human_size="$(hf_human_size "$total_size")"
+        printf '  %-50s %s   %s\n' "$name" "$human_size" "$date_str"
+    done
+}
+
+cmd_remove() {
+    local repo_id="${SUBCMD_ARGS[0]:-}"
+    [ -n "$repo_id" ] || err "Usage: pos ai hf remove <repo-id>"
+
+    local target_dir
+    target_dir="$(hf_repo_dir "$repo_id")"
+
+    [ -d "$target_dir" ] || err "Model not found: $repo_id"
+
+    # Calculate size before removal
+    local total_size=0
+    while IFS= read -r file; do
+        [ -f "$file" ] || continue
+        local size
+        size="$(stat -c%s "$file" 2>/dev/null || echo 0)"
+        total_size=$((total_size + size))
+    done < <(find "$target_dir" -type f 2>/dev/null)
+
+    local human_size
+    human_size="$(hf_human_size "$total_size")"
+
+    rm -rf "$target_dir"
+    printf 'Removed: %s (freed %s)\n' "$repo_id" "$human_size"
+}
+
+# ── Dispatch ───────────────────────────────────────────────────
+case "$SUBCMD" in
+    search)   cmd_search ;;
+    download) cmd_download ;;
+    list)     cmd_list ;;
+    remove)   cmd_remove ;;
+    *)        err "Unknown subcommand '$SUBCMD' (see --help)" ;;
+esac
@@ -0,0 +1,444 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# POS: ai server — llama.cpp local inference server (start, stop, status, models, logs)
+# POS_SUBCMDS: start stop status models logs
+# POS_FLAGS: --port --host --model --ctx --gpu --threads
+# POS_DEPS: curl jq
+
+source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
+
+# ── Dependencies (before --help) ───────────────────────────────
+command -v curl &>/dev/null || err "curl not found (install curl)"
+command -v jq &>/dev/null || err "jq not found (install jq)"
+
+# ── Config / seams ─────────────────────────────────────────────
+CONFIG_FILE="${CONFIG_FILE:-$HOME/.config/linux_post_install/ai.env}"
+USER_SYSTEMD_DIR="${USER_SYSTEMD_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user}"
+SERVICE="pos-ai-server.service"
+HF_DOWNLOAD_DIR="${HF_DOWNLOAD_DIR:-$HOME/.local/share/linux_post_install/ai/models}"
+
+# ── Config loader (env-var precedence, same pattern as pos-ai-hf) ──
+load_config() {
+    [ -f "$CONFIG_FILE" ] || return 0
+    local k v
+    while IFS='=' read -r k v; do
+        [ -n "$k" ] || continue
+        case "$k" in
+            \#*) continue ;;
+        esac
+        v="${v%\"}"; v="${v#\"}"; v="${v%\'}"; v="${v#\'}"
+        v="${v//$'\r'/}"
+        if [ -z "${!k:-}" ]; then
+            export "$k"="$v"
+        fi
+    done < <(grep -E '^[A-Z_]+=' "$CONFIG_FILE" || true)
+}
+
+load_config
+
+# ── Binary detection ───────────────────────────────────────────
+find_llamacpp() {
+    local candidates=("llama-server" "llama.cpp/server" "server" "llama-server-cuda")
+    local bin
+    for bin in "${candidates[@]}"; do
+        command -v "$bin" &>/dev/null && { echo "$bin"; return 0; }
+    done
+    return 1
+}
+
+# ── GPU detection ──────────────────────────────────────────────
+detect_gpu() {
+    if command -v nvidia-smi &>/dev/null && nvidia-smi &>/dev/null 2>&1; then
+        echo "cuda"
+    else
+        echo "cpu"
+    fi
+}
+
+resolve_gpu_layers() {
+    local configured="${LLAMACPP_GPU_LAYERS:-}"
+    if [ -n "$configured" ] && [ "$configured" != "-1" ]; then
+        echo "$configured"
+        return
+    fi
+    # Auto-detect
+    local gpu
+    gpu="$(detect_gpu)"
+    case "$gpu" in
+        cuda) echo "-1" ;;
+        *)    echo "0" ;;
+    esac
+}
+
+# ── Human-readable size ────────────────────────────────────────
+human_size() {
+    local bytes="$1"
+    if [ "$bytes" -ge 1073741824 ]; then
+        awk "BEGIN { printf \"%.1f GB\", $bytes / 1073741824 }"
+    elif [ "$bytes" -ge 1048576 ]; then
+        awk "BEGIN { printf \"%.1f MB\", $bytes / 1048576 }"
+    elif [ "$bytes" -ge 1024 ]; then
+        awk "BEGIN { printf \"%.1f KB\", $bytes / 1024 }"
+    else
+        printf '%d B' "$bytes"
+    fi
+}
+
+# ── Health check ───────────────────────────────────────────────
+check_health() {
+    local port="${LLAMACPP_PORT:-8088}"
+    local resp
+    resp="$(curl -sf "http://127.0.0.1:$port/health" 2>/dev/null)" || { echo "not running"; return 1; }
+    local status
+    status="$(printf '%s' "$resp" | jq -r '.status // "unknown"' 2>/dev/null)"
+    echo "$status"
+}
+
+# ── Interactive model picker (reads /dev/tty, not stdin) ───────
+pick_model() {
+    local models=() i
+    while IFS= read -r f; do
+        [ -f "$f" ] || continue
+        models+=("$f")
+    done < <(find "$HF_DOWNLOAD_DIR" -name '*.gguf' -type f 2>/dev/null | sort)
+
+    [ ${#models[@]} -gt 0 ] || err "No GGUF models found — run 'pos ai hf download <repo> --gguf'"
+
+    echo "Available models:"
+    for ((i = 0; i < ${#models[@]}; i++)); do
+        local name size
+        name="$(basename "${models[$i]}")"
+        size="$(stat -c%s "${models[$i]}" 2>/dev/null || echo 0)"
+        printf '  %2d) %-50s %s\n' "$((i + 1))" "$name" "$(human_size "$size")"
+    done
+    echo
+    local choice
+    printf 'Pick a model [1-%d]: ' "${#models[@]}"
+    IFS= read -r choice </dev/tty || choice=""
+    [[ "$choice" =~ ^[0-9]+$ ]] && [ "$choice" -ge 1 ] && [ "$choice" -le "${#models[@]}" ] || err "Invalid selection"
+    printf '%s' "${models[$((choice - 1))]}"
+}
+
+# ── Model resolution ───────────────────────────────────────────
+resolve_model() {
+    local explicit="${1:-}"
+    # 1. Explicit argument
+    if [ -n "$explicit" ]; then
+        # Absolute path
+        if [[ "$explicit" == /* ]]; then
+            [ -f "$explicit" ] || err "Model not found: $explicit"
+            printf '%s' "$explicit"
+            return
+        fi
+        # Relative to HF_DOWNLOAD_DIR
+        local candidate="$HF_DOWNLOAD_DIR/$explicit"
+        if [ -f "$candidate" ]; then
+            printf '%s' "$candidate"
+            return
+        fi
+        # Also try with the name as-is (could be a relative path)
+        [ -f "$explicit" ] && { printf '%s' "$explicit"; return; }
+        err "Model not found: $explicit (also searched $HF_DOWNLOAD_DIR)"
+    fi
+    # 2. Config
+    if [ -n "${LLAMACPP_MODEL:-}" ]; then
+        [ -f "$LLAMACPP_MODEL" ] || err "Configured model not found: $LLAMACPP_MODEL"
+        printf '%s' "$LLAMACPP_MODEL"
+        return
+    fi
+    # 3. Interactive pick (only on TTY)
+    if [ -t 0 ] || [ -w /dev/tty ]; then
+        local picked
+        picked="$(pick_model)"
+        printf '%s' "$picked"
+        return
+    fi
+    err "No model specified and no LLAMACPP_MODEL configured — run 'pos ai server start <model>' or set LLAMACPP_MODEL in ai.env"
+}
+
+# ── Usage ──────────────────────────────────────────────────────
+usage() {
+    cat <<'EOF'
+Usage: pos ai server <command> [args]
+
+Manage a local llama.cpp inference server via systemd user service.
+
+Commands:
+  start [model]       Start the server (model: argument, config, or interactive pick)
+  stop                Stop and disable the server
+  status              Show service state, config, and health
+  models              List available GGUF files
+  logs [lines]        Show recent server logs
+
+Options:
+  --port <port>       Server port (default: 8088)
+  --host <addr>       Bind address (default: 127.0.0.1)
+  --model <path>      Model path (overrides argument and config)
+  --ctx <size>        Context window size (default: 4096)
+  --gpu <layers>      GPU layers: -1=auto, 0=CPU, N=explicit (default: -1)
+  --threads <n>       CPU threads (default: nproc)
+  -h|--help           This help
+
+Examples:
+  pos ai server start mistral-7b-v0.1.Q4_K_M.gguf
+  pos ai server start /path/to/model.gguf --port 9090 --gpu 0
+  pos ai server status
+  pos ai server logs 50
+  pos ai server models
+  pos ai server stop
+
+Config (~/.config/linux_post_install/ai.env):
+  LLAMACPP_PORT       Server port (default 8088)
+  LLAMACPP_HOST       Bind address (default 127.0.0.1)
+  LLAMACPP_MODEL      Default model path (GGUF file)
+  LLAMACPP_CTX_SIZE   Context window size (default 4096)
+  LLAMACPP_GPU_LAYERS GPU layers: -1=auto, 0=CPU only (default -1)
+  LLAMACPP_THREADS    CPU threads (default: nproc)
+
+Requires: llama-server binary (install llama.cpp: https://github.com/ggerganov/llama.cpp)
+EOF
+    exit 0
+}
+
+# ── Parse flags ────────────────────────────────────────────────
+PORT="${LLAMACPP_PORT:-8088}"
+HOST="${LLAMACPP_HOST:-127.0.0.1}"
+CTX_SIZE="${LLAMACPP_CTX_SIZE:-4096}"
+GPU_LAYERS="${LLAMACPP_GPU_LAYERS:--1}"
+THREADS="${LLAMACPP_THREADS:-}"
+MODEL_ARG=""
+SUBCMD=""
+SUBCMD_ARGS=()
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -h|--help) usage ;;
+        --port)
+            [ $# -ge 2 ] || err "--port requires a value"
+            PORT="$2"; shift 2 ;;
+        --host)
+            [ $# -ge 2 ] || err "--host requires a value"
+            HOST="$2"; shift 2 ;;
+        --model)
+            [ $# -ge 2 ] || err "--model requires a value"
+            MODEL_ARG="$2"; shift 2 ;;
+        --ctx)
+            [ $# -ge 2 ] || err "--ctx requires a value"
+            CTX_SIZE="$2"; shift 2 ;;
+        --gpu)
+            [ $# -ge 2 ] || err "--gpu requires a value"
+            GPU_LAYERS="$2"; shift 2 ;;
+        --threads)
+            [ $# -ge 2 ] || err "--threads requires a value"
+            THREADS="$2"; shift 2 ;;
+        -*)
+            err "Unknown option '$1' (see --help)" ;;
+        *)
+            if [ -z "$SUBCMD" ]; then
+                SUBCMD="$1"
+            else
+                SUBCMD_ARGS+=("$1")
+            fi
+            shift ;;
+    esac
+done
+
+# Apply flag overrides back to config defaults (flags > env > file default)
+LLAMACPP_PORT="$PORT"
+LLAMACPP_HOST="$HOST"
+LLAMACPP_CTX_SIZE="$CTX_SIZE"
+LLAMACPP_GPU_LAYERS="$GPU_LAYERS"
+if [ -z "$THREADS" ]; then
+    THREADS="$(nproc 2>/dev/null || echo 4)"
+fi
+LLAMACPP_THREADS="$THREADS"
+
+# ── Subcommands ────────────────────────────────────────────────
+
+cmd_start() {
+    # Resolve the llama-server binary
+    local llamacpp_bin
+    llamacpp_bin="$(find_llamacpp)" || err "llama-server not found — install llama.cpp (https://github.com/ggerganov/llama.cpp)"
+    local llamacpp_full
+    llamacpp_full="$(command -v "$llamacpp_bin")"
+
+    # Resolve model
+    local explicit_model="${SUBCMD_ARGS[0]:-}"
+    # Flag --model takes precedence over positional arg
+    [ -n "$MODEL_ARG" ] && explicit_model="$MODEL_ARG"
+    local model
+    model="$(resolve_model "$explicit_model")"
+
+    # Resolve GPU layers
+    local gpu_layers
+    gpu_layers="$(resolve_gpu_layers)"
+
+    # Warn if no GPU detected and auto-detect resolved to CPU
+    if [ "$gpu_layers" = "0" ] && [ "${LLAMACPP_GPU_LAYERS:--1}" = "-1" ]; then
+        warn "No NVIDIA GPU detected — running in CPU mode"
+    fi
+
+    # Check port availability (best-effort)
+    if command -v ss &>/dev/null; then
+        if ss -tlnp 2>/dev/null | grep -q ":${PORT} "; then
+            # Port might be our own old instance — only warn
+            warn "Port $PORT may already be in use — check with 'ss -tlnp'"
+        fi
+    fi
+
+    if [ "${DRY_RUN:-0}" -eq 1 ]; then
+        log "(dry-run) generate systemd unit $USER_SYSTEMD_DIR/$SERVICE"
+        log "(dry-run) ExecStart: $llamacpp_full -m $model --port $PORT --host $HOST --n-gpu-layers $gpu_layers --ctx-size $CTX_SIZE --threads $THREADS"
+        log "(dry-run) systemctl --user daemon-reload && enable --now $SERVICE"
+        return 0
+    fi
+
+    # Generate systemd unit
+    mkdir -p "$USER_SYSTEMD_DIR"
+    cat > "$USER_SYSTEMD_DIR/$SERVICE" <<EOF
+[Unit]
+Description=pos llama.cpp inference server (linux-post-install)
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=$llamacpp_full -m $model --port $PORT --host $HOST --n-gpu-layers $gpu_layers --ctx-size $CTX_SIZE --threads $THREADS
+Restart=on-failure
+RestartSec=5
+TimeoutStopSec=10
+KillMode=control-group
+EnvironmentFile=-%h/.config/linux_post_install/ai.env
+
+[Install]
+WantedBy=default.target
+EOF
+    chmod 644 "$USER_SYSTEMD_DIR/$SERVICE"
+
+    # Enable and start
+    systemctl --user daemon-reload
+    systemctl --user enable --now "$SERVICE"
+
+    log "Server starting — model: $(basename "$model"), port: $PORT"
+
+    # Linger warning
+    if command -v loginctl >/dev/null 2>&1; then
+        if ! loginctl show-user "$(id -un)" 2>/dev/null | grep -q '^Linger=yes'; then
+            warn "enable linger so the server survives logout: sudo loginctl enable-linger $(id -un)"
+        fi
+    fi
+
+    # Health check (wait briefly)
+    sleep 2
+    local health
+    health="$(check_health)" || true
+    if [ "$health" != "not running" ]; then
+        ok "Server healthy (status: $health)"
+    else
+        warn "Server may not be ready yet — check with 'pos ai server status'"
+    fi
+}
+
+cmd_stop() {
+    if [ ! -f "$USER_SYSTEMD_DIR/$SERVICE" ]; then
+        warn "No llama.cpp server service installed ($SERVICE)"
+        return 0
+    fi
+    if [ "${DRY_RUN:-0}" -eq 1 ]; then
+        log "(dry-run) systemctl --user disable --now $SERVICE; remove unit"
+    else
+        systemctl --user disable --now "$SERVICE" 2>/dev/null || true
+        rm -f "$USER_SYSTEMD_DIR/$SERVICE"
+        systemctl --user daemon-reload
+    fi
+    log "llama.cpp server stopped and removed"
+}
+
+cmd_status() {
+    # Service state
+    local svc_state="stopped"
+    if systemctl --user is-active "$SERVICE" &>/dev/null; then
+        svc_state="running"
+    fi
+    printf 'service:   %s\n' "$svc_state"
+
+    # Model (from health endpoint if running)
+    if [ "$svc_state" = "running" ]; then
+        local models_resp
+        models_resp="$(curl -sf "http://127.0.0.1:$PORT/v1/models" 2>/dev/null)" || true
+        local model_id
+        model_id="$(printf '%s' "$models_resp" | jq -r '.data[0].id // "unknown"' 2>/dev/null)" || model_id="unknown"
+        printf 'model:     %s\n' "$model_id"
+    else
+        printf 'model:     (not loaded)\n'
+    fi
+
+    # Config
+    printf 'port:      %s\n' "$PORT"
+    printf 'host:      %s\n' "$HOST"
+
+    # GPU
+    local gpu_type
+    gpu_type="$(detect_gpu)"
+    printf 'gpu:       %s (%s layers)\n' "${gpu_type^^}" "$GPU_LAYERS"
+
+    printf 'context:   %s\n' "$CTX_SIZE"
+    printf 'threads:   %s\n' "$THREADS"
+
+    # Autostart
+    if systemctl --user is-enabled "$SERVICE" &>/dev/null; then
+        printf 'autostart: enabled\n'
+    else
+        printf 'autostart: disabled\n'
+    fi
+
+    # Endpoint
+    printf 'endpoint:  http://%s:%s\n' "$HOST" "$PORT"
+
+    # Health
+    if [ "$svc_state" = "running" ]; then
+        local health
+        health="$(check_health)" || health="not responding"
+        printf 'health:    %s\n' "$health"
+    else
+        printf 'health:    not running\n'
+    fi
+}
+
+cmd_models() {
+    local dir="${HF_DOWNLOAD_DIR}"
+    [ -d "$dir" ] || { warn "No models directory — run 'pos ai hf download' first"; return 0; }
+
+    local found=0
+    echo "Available GGUF models:"
+    while IFS= read -r gguf; do
+        [ -f "$gguf" ] || continue
+        found=1
+        local name size
+        name="$(basename "$gguf")"
+        local dir_name
+        dir_name="$(basename "$(dirname "$gguf")")"
+        size="$(stat -c%s "$gguf" 2>/dev/null || echo 0)"
+        local hsize
+        hsize="$(human_size "$size")"
+        printf '  %-50s %s\n' "$dir_name/$name" "$hsize"
+    done < <(find "$dir" -name '*.gguf' -type f 2>/dev/null | sort)
+
+    [ "$found" -eq 0 ] && warn "No .gguf files found — download with 'pos ai hf download <repo> --gguf'"
+}
+
+cmd_logs() {
+    local lines="${SUBCMD_ARGS[0]:-50}"
+    [[ "$lines" =~ ^[0-9]+$ ]] || err "lines must be a number"
+    journalctl --user -u "$SERVICE" -n "$lines" --no-pager 2>/dev/null || warn "No logs found — server may not have been started"
+}
+
+# ── Dispatch ───────────────────────────────────────────────────
+case "${SUBCMD:-}" in
+    "")       usage ;;
+    start)    cmd_start ;;
+    stop)     cmd_stop ;;
+    status)   cmd_status ;;
+    models)   cmd_models ;;
+    logs)     cmd_logs ;;
+    *)        err "Unknown subcommand '$SUBCMD' (see --help)" ;;
+esac
@@ -3,6 +3,8 @@
 # Install: source this file in ~/.bashrc or place in /etc/bash_completion.d/
 # GEN:START posflags
 declare -A _pos_flags
+_pos_flags[ai-hf]="--branch --gguf --output"
+_pos_flags[ai-server]="--port --host --model --ctx --gpu --threads"
 _pos_flags[communication-matrix-listener]="--enable --disable --status --run"
 _pos_flags[communication-telegram-listener]="--enable --disable --status --sync-commands --run"
 _pos_flags[communication-telegram-sender]="--type --caption --parse-mode --no-preview --token --chat-id --markdown"
@@ -29,6 +31,7 @@ declare -A _pos_subcmds
 _pos_subcmds[ai-alias]="create edit remove list show"
 _pos_subcmds[ai-gemini]="ask chat models sessions capture"
 _pos_subcmds[ai-openrouter]="ask chat sessions capture"
+_pos_subcmds[ai-server]="start stop status models logs"
 _pos_subcmds[communication-matrix-sender]="send test login"
 _pos_subcmds[communication-scrcpy]="devices record tcpip connect push pull screenshot info"
 _pos_subcmds[communication-telegram-listener]="prefix"
@@ -44,7 +47,7 @@ _pos_subcmds[share-smb-client]="mount unmount list persist unpersist menu"
 _pos_subcmds[share-smb-server]="status share unshare list adduser deluser reload enable disable menu"
 _pos_subcmds[system-backup]="menu"
 _pos_subcmds[system-schedule]="run list config enable disable status migrate menu"
-_pos_subcmds[ai]="ask chat sessions capture models providers alias gemini openrouter"
+_pos_subcmds[ai]="ask chat sessions capture models providers alias gemini hf openrouter server"
 # GEN:END possubcmds
 # GEN:START posconfigscopes
 declare -a _pos_config_scopes=(ai compose entertainment grab matrix notify scrcpy system telegram ytsync)
@@ -16,3 +16,11 @@
 #
 # System prompt:
 #   AI_SYSTEM_PROMPT=<prompt>     # Custom system prompt (overrides built-in; empty to reset)
+#
+# llama.cpp local inference server (pos ai server):
+#   LLAMACPP_PORT=8088            # Server port (default 8088)
+#   LLAMACPP_HOST=127.0.0.1       # Bind address (default 127.0.0.1)
+#   LLAMACPP_MODEL=<path>         # Default model path (GGUF file)
+#   LLAMACPP_CTX_SIZE=4096        # Context window size (default 4096)
+#   LLAMACPP_GPU_LAYERS=-1        # GPU layers: -1=auto, 0=CPU only (default -1)
+#   LLAMACPP_THREADS=<n>          # CPU threads (default: nproc)
@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Local llama.cpp provider adapter for pos-ai
+# Provider-specific: API call via OpenAI-compatible /v1/chat/completions
+# Part of the R8 provider-agnostic architecture (lib/ai-providers/).
+
+# Provider-specific config variables (auto-discovered by pos config ai):
+# PROVIDER_CONFIG: LLAMACPP_MODEL=:Default model path (GGUF file)
+
+provider_name() { printf 'Local llama.cpp'; }
+
+provider_default_model() {
+    local port="${LLAMACPP_PORT:-8088}"
+    local model
+    model="$(curl -sf "http://127.0.0.1:$port/v1/models" 2>/dev/null | jq -r '.data[0].id // empty')"
+    [ -n "$model" ] && printf '%s' "$model" || printf '(no model loaded)'
+}
+
+# $1=model  $2=messages JSON ({"messages":[{role,content}]})  $3=optional system prompt
+provider_generate() {
+    local model="$1" messages="$2" system="${3:-}" port="${LLAMACPP_PORT:-8088}"
+    local body resp code body_out
+    # Build messages array with optional system prompt
+    if [ -n "$system" ]; then
+        body="$(printf '%s' "$messages" | jq -c --arg s "$system" \
+            '[{role:"system",content:$s}] + .messages')"
+    else
+        body="$(printf '%s' "$messages" | jq -c '.messages')"
+    fi
+    body="$(printf '%s' "$body" | jq -nc --arg m "$model" --argjson msgs "$body" \
+        '{model:$m, messages:$msgs, stream:false}')"
+    resp="$(curl -sS -m 120 -X POST "http://127.0.0.1:$port/v1/chat/completions" \
+        -H "Content-Type: application/json" \
+        --write-out $'\n%{http_code}' \
+        --data "$body")" || { echo "request failed (curl exit $?)" >&2; return 1; }
+    code="${resp##*$'\n'}"
+    body_out="${resp%$'\n'*}"
+    if [ "$code" != "200" ]; then
+        echo "API error $code" >&2
+        return 1
+    fi
+    printf '%s' "$body_out" | jq -r '.choices[0].message.content // ""'
+}
+
+# $1=current default model  → stdout=formatted model list
+provider_models_list() {
+    local model="$1" port="${LLAMACPP_PORT:-8088}" resp code body
+    resp="$(curl -sf "http://127.0.0.1:$port/v1/models" \
+        --write-out $'\n%{http_code}')" || { echo "server not running" >&2; return 1; }
+    code="${resp##*$'\n'}"
+    body="${resp%$'\n'*}"
+    [ "$code" = "200" ] || { echo "API error $code" >&2; return 1; }
+    echo "Local llama.cpp models:"
+    printf '%s' "$body" | jq -r '.data[]? | .id' | while IFS= read -r m; do
+        [ -n "$m" ] || continue
+        if [ "$m" = "$model" ]; then
+            printf '  %-48s <- loaded\n' "$m"
+        else
+            printf '  %-48s\n' "$m"
+        fi
+    done
+}
@@ -552,12 +552,15 @@ cfg_ui() {
                n=$((n + 1))
                v="$(cfg_value "$file" "$k")"
                disp="$(cfg_display "$v" "$f")"
-                [ "$disp" = "(not set)" ] && disp="${DIM}(not set)${RESET}"
-                if [ "$dim" -eq 1 ]; then
-                    printf '%s  %2d) %-28s %s%s\n' "$DIM" "$n" "$k" "$disp" "$RESET"
-                else
-                    printf '  %s%2d)%s %s%-28s%s %s\n' "$DIM" "$n" "$RESET" "$BOLD" "$k" "$RESET" "$disp"
+                if [ "$disp" = "(not set)" ]; then
+                    disp="${DIM}(not set)${RESET}"
+                elif [ "$dim" -eq 1 ]; then
+                    # Inactive group: key name stays bold/colored (readable);
+                    # only the value dims — the caption already carries the
+                    # inactive reason, so a fully grey block adds no signal.
+                    disp="${DIM}${disp}${RESET}"
                fi
+                printf '  %s%2d)%s %s%-28s%s %s\n' "$DIM" "$n" "$RESET" "$BOLD" "$k" "$RESET" "$disp"
                if [ -n "$d" ]; then
                    [ "$dim" -eq 1 ] && printf '%s' "$DIM"
                    _cfg_wrap "$d" "$wrapW" "      "
Author	SHA1	Message	Date
he	adf88cc737	fix: pos config ai splits llamacpp into its own section gates / consistency-and-conventions (push) Successful in 1m35s Details LLAMACPP_* keys lived under a generic General group. Added a conditional '@[AI_PROVIDER=llamacpp] llamacpp' caption (mirrors OpenRouter), so the provider gets its own section; General now only holds AI_SYSTEM_PROMPT plus the HF keys that arrive from pos-ai-hf. AI_PROVIDER description and usage text mention llamacpp. Also: inactive config groups no longer dim the key name — keys stay bold so an inactive provider block is not one uniform grey wall; only values and descriptions dim, and the caption still carries the inactive reason.	2026-09-04 13:13:52 -04:00
he	a9105e2e15	fix: pos config ai shows broken LLAMACPP_* entries gates / consistency-and-conventions (push) Successful in 1m34s Details Missing '=' in LLAMACPP_CTX_SIZE/GPU_LAYERS/THREADS POS_CONFIG entries made the parser treat the whole string as a key, and a stray bare 'llamacpp' field created a bogus 'llamacpp' entry. Removed the stray field, added the '=' delimiters, moved *providers=llamacpp to the end. pos config ai now renders all keys correctly with num flags and intact colons in descriptions.	2026-09-04 13:01:44 -04:00
he	5e312b3207	feat: pos ai server — llama.cpp local inference server gates / consistency-and-conventions (push) Successful in 1m38s Details Service manager (start/stop/status/models/logs) with systemd user service generation, GPU auto-detection, model selection from pos ai hf downloads. Provider adapter integrates with pos ai ask as --provider llamacpp. Config extends existing ai scope with LLAMACPP_* keys. 87 test cases / 0 failed. make gen/check/lint 0 FAIL / 0 WARN.	2026-09-04 12:40:50 -04:00
he	99c033c6c6	feat: pos ai hf — Hugging Face model downloader for local inference gates / consistency-and-conventions (push) Successful in 1m32s Details Bash-native tool using curl/jq to download AI models from HF Hub. Subcommands: download (single file/repo/gguf filter), search, list, remove. Auth via HF_TOKEN in ai.env, resume support, disk space pre-flight, rate limit handling, .hf-meta metadata tracking. 46 test cases / 0 failed. make gen/check/lint 0 FAIL / 0 WARN.	2026-09-04 11:54:28 -04:00