Your Name
0b5043a9f3
gates / consistency-and-conventions (push) Successful in 26s
User report after the llamacpp app install: 'installed llama.cpp unknown', valid flags rejected (randomly per run), 'Model not found' for the HF downloader's own layout, and a systemd user-bus failure over SSH. Detective (real b10822 binary, FACT) found four independent causes: - version: llama-server --version prints to STDERR; detect_llama_version's 2>/dev/null swallowed it -> always 'unknown'. Now captures 2>&1 + accepts semver/build tokens (incl. build 1.2.3 edge) - validation: printf|grep -q under pipefail -> SIGPIPE rc=141 race randomly rejected flags present in the 59 KB --help. Now pipe-less grep (no race); 20x determinism regression test - model resolution: resolve_model accepted files only, but the HF downloader creates <models>/<repo>/file.gguf dirs. Now expands a dir with exactly one *.gguf (never silently picks; multi-gguf lists + errs) - port: llama.cpp default 8080 vs tool/adapter 8088; validation reliability means --port is now always pinned in the unit - user bus: headless/SSH sessions lack XDG_RUNTIME_DIR -> ensure_user_bus in lib/common.sh pre-flights all three systemctl --user tools with remediation text; pos ai server --no-unit direct-run escape hatch (pidfile) for boxes with no bus - find_llamacpp narrowed to llama-server/llama-server-cuda (bare 'server' fallback hazard); installer post-install sanity (version+help execute, symlink targets resolve) Architect decisions DQ1-DQ6 recorded. Tester: 4 new regression files (version-from-stderr, 25x flag-validation determinism, model dir expansion, bus pre-flight + E2E) + 3 fixture updates; suite 16 files / 269 checks. Verified: make gen idempotent; make check OK; make lint 0 FAIL, 0 WARN; make test 269/269 (~49s); bash -n clean; git diff --check clean.
Documentation
Everything in this folder is reference material for the Linux_post_install project. The root README is the short intro + quick start; this folder holds the detail.
| Document | What it covers |
|---|---|
| HOWTO.md | Hands-on guides per category (ai, network, docker, media, system, ssh, share, communication, entertainment): flags, recipes, config, troubleshooting |
| SCRIPTS.md | Core installer scripts: install.sh, preinstall.sh, postinstall.sh, lib/common.sh, lib/flags.sh, lib/entertainment-lib.sh, features/autostart.sh, features/usb-automount.sh — purpose, how each works, configuration |
| POS.md | The pos CLI: dispatcher, every pos-* command, Docker Compose / ScaleTail config, legacy wrappers, flag CLIs |
| APPS.md | Optional apps: apps/install.sh picker, installer conventions, full app catalog |
| SYSTEMD.md | Systemd units (autostart.service, usb-automount.service, ssh-agent.service), feature-flag gating, bash completion |
| DEV.md | Developer guide: architecture, conventions, how to add tools/apps/features, commit guidelines |
| AGENT_Context_Project.md | Single-source context doc for AI agents working on the repo |
| algorithm.md | ASCII diagrams: install flow, pos dispatch, compose up, config cascade, logging, vbox lifecycle |
Quick navigation
- Just installed and want to use it? → POS.md
- Adding a package? → SCRIPTS.md → preinstall.sh
- Adding a CLI tool or app? → DEV.md
- First deploy of a self-hosted service? → POS.md → Docker Compose