Files

T

gates / consistency-and-conventions (push) Successful in 1m59s

Details

refactor: ai — merge gemini/openrouter into unified plugin architecture

- bin/pos-ai: single provider-agnostic tool (ask/chat/sessions/capture/models/providers)
- lib/ai-providers/gemini.sh: Gemini adapter (59 ln)
- lib/ai-providers/openrouter.sh: OpenRouter adapter (59 ln)
- bin/pos-ai-gemini/openrouter: thin forwarders for backward compat
- Provider adapter interface: provider_name/default_model/generate/models_list
- Unified session format (OpenAI messages), auto-migrate old gemini contents
- Config: AI_PROVIDER/AI_API_KEY/AI_MODEL/AI_SYSTEM_PROMPT in ai.env
- Config fallback: AI_API_KEY → provider-specific env var → error
- Default system prompt configurable via AI_SYSTEM_PROMPT
- New subcommand: pos ai providers (lists providers + config status)
- Shell hook (pos-ai-hook.sh) for auto-capture

2026-08-25 09:57:10 -04:00

5.3 KiB

Raw Blame History

`pos` HOW-TO Guides

Hands-on, copy-paste guides for every pos category. These are the tutorial layer: flags, examples, configuration, recipes, and troubleshooting. For the authoritative one-line reference (every command + flag), see DOC/POS.md.

Quick start — pick your category

Category	What you can do	Guide
`pos ai`	Chat with Google Gemini from CLI or Telegram	ai
`pos network`	IP info, hotspot, scan, port check, aria2 download daemon	network
`pos docker`	Compose services, container dashboards, disposable VMs	docker
`pos media`	Download audio/video via yt-dlp; incremental YouTube channel sync	media
`pos system`	Backups, firewall, health dashboard	system
`pos system schedule`	Scheduled jobs: run a command on a timer, notify on threshold/change/error or silently	schedule
`pos ssh`	Load keys into the agent	ssh
`pos share`	Share USB devices & filesystems over the network (USB, NFS, SMB)	share
`pos communication`	Send Telegram/Matrix messages & alerts, /command listeners, Android mirroring (scrcpy)	communication
`pos entertainment`	Scheduled auto-messages from public APIs	entertainment

Every tool is bin/pos-<category>-<command>; run pos <category> --help to list a category, and any tool's --help/--help-style usage for full flags.

Cross-cutting concepts (read once)

These apply to several categories at once.

Config files — `~/.config/linux_post_install/`

Runtime tool config lives here as <tool>.env files (chmod 600). Precedence is always flags > environment > config file. postinstall.sh installs the templates (without overwriting an existing file):

File	Used by	Keys
`telegram.env`	`pos communication telegram sender` / `listener`, everything that alerts	`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`
`matrix.env`	`pos communication matrix sender` / `listener`	`MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`, `MATRIX_USER_ID`, `MATRIX_ROOM_ID`
`scrcpy.env`	`pos communication scrcpy`	`SCRCPY_SERIAL`, `SCRCPY_MAX_SIZE`, `SCRCPY_MAX_FPS`, `SCRCPY_BIT_RATE`, `SCRCPY_FULLSCREEN`, `SCRCPY_NEW_DISPLAY`, `SCRCPY_AUDIO`, `SCRCPY_RECORD_DIR`, `SCRCPY_PUSH_TARGET`, `SCRCPY_EXTRA_FLAGS`
`notify.env`	`lib/notify.sh` (all alerting)	`NOTIFY_PLATFORM` (e.g. `telegram,matrix`)
`system.env`	`pos system health`, `pos system backup`	`BACKUP_SERVICE_ROOTS`, `HEALTH_BACKUP_MAX_AGE_DAYS`
`compose.env`	`pos docker compose`	`TS_AUTHKEY`, `TZ`, `DNS_SERVER`, `SERVICES_BASE`
`entertainment.env`	`pos entertainment *`	plugin keys (`WEATHER_LAT`…), `ENABLED`
`ai.env`	`pos ai`	`AI_PROVIDER`, `AI_API_KEY`, `AI_MODEL`, `AI_SYSTEM_PROMPT`, `AI_GEMINI_API_KEY`, `AI_GEMINI_MODEL`, `OPENROUTER_API_KEY`, `OPENROUTER_MODEL`
`schedule.d/`	`pos system schedule`	one `<name>.env` per job: `INTERVAL`, `NOTIFY`, `MSG`, `RULE`, `COMMAND`

pos config telegram                     # set TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID
pos config matrix                       # set MATRIX_HOMESERVER / MATRIX_ROOM_ID, then:
pos communication matrix sender login --user @you:example.org   # fetch an access token
pos entertainment config set WEATHER_LAT=36.51 WEATHER_LON=40.75

The notify system — `lib/notify.sh`

Any tool that "announces" something calls notify_send, which delivers to every platform in NOTIFY_PLATFORM (default telegram). It is silent-fail: if no platform is configured it warns and never breaks the calling tool.

# ~/.config/linux_post_install/notify.env
NOTIFY_PLATFORM=telegram        # comma-separated to send to all

Ship with telegram and matrix — add both to NOTIFY_PLATFORM to fan out alerts (Matrix needs pos config matrix + a login-fetched token first). Adding another platform = create bin/pos-communication-<p> implementing send <value> [--markdown] and list it. See DOC/DEV.md → Alerting for the contract.

Scheduling

Daily health digest — add a daily schedule job COMMAND=pos system health with NOTIFY=always via pos system schedule config (the old pos-health.{service,timer} units are gone). See system.
Entertainment auto-triggers — per-plugin pos entertainment enable <plugin> <interval>, uses systemd user timers (or cron fallback). See entertainment.
pos system schedule jobs — run any command on a per-job timer and notify on threshold/change/error/always or silently. See schedule.

Gotcha: run from anywhere

install.sh copies bin/pos* + lib/* to /usr/local/bin, so pos works after the repo is deleted. After pulling new changes, re-run ./install.sh (or just copy the changed bin//lib/ files) to refresh the installed copies.

How the guides relate to `DOC/POS.md`

DOC/POS.md = reference. One table row per command, full flag lists, compose/ScaleTail config strategy. Use it when you need the exact flag.
This guide set = how-to. Examples, recipes, config walk-throughs, and troubleshooting, linking back to POS.md rather than duplicating it.

5.3 KiB Raw Blame History

pos HOW-TO Guides