docs: add dev templates + clarify conventions; fix pos help for multi-word commands

templates/app.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ────────────────────────────────────────────────────────────────
+# TEMPLATE — new optional app installer
+#
+#  1. Copy:  cp templates/app.sh apps/<category>/<name>.sh
+#     Categories: browsers, development, media, networking,
+#     remote-access, system, utilities.
+#  2. Fill in install_myapp() / uninstall_myapp() (rename to your app).
+#  3. Docs:  add a row to the catalog table in DOC/APPS.md.
+#
+# Auto-appears in the `apps/install.sh` picker — no registration.
+# Run as:   bash apps/install.sh <name>        (install)
+#           bash apps/install.sh --uninstall <name>
+# ────────────────────────────────────────────────────────────────
+
+source "$(dirname "$0")/../../lib/common.sh"
+
+install_myapp() {
+    command -v myapp &>/dev/null && { log "myapp already installed"; return 0; }
+
+    # Pick one method (see conventions below) and wrap it in spawn:
+    spawn "Installing myapp" sudo apt install -y myapp
+
+    log "Run myapp: myapp"
+}
+
+uninstall_myapp() {
+    command -v myapp &>/dev/null || { log "myapp not installed"; return 0; }
+
+    spawn "Removing myapp" sudo apt purge -y myapp
+    spawn "Cleaning up dependencies" sudo apt autoremove -y
+}
+
+case "${1:-}" in
+    uninstall) uninstall_myapp ;;
+    *)         install_myapp ;;
+esac
+
+# ────────────────────────────────────────────────────────────────
+# CONVENTIONS — pick the install method that fits:
+#
+#   APT package        sudo apt install -y myapp
+#                      remove: sudo apt purge -y myapp + apt autoremove -y
+#
+#   Repo-based app     add the apt repo in install; in uninstall also
+#                      remove the .list file and keyring:
+#                      sudo rm -f /etc/apt/sources.list.d/myapp.list /usr/share/keyrings/...
+#
+#   Official script    spawn "Installing myapp" bash -c "curl -fsSL https://.../install.sh | sh"
+#                      uninstall: remove the installed binary/files
+#
+#   Flatpak            sudo flatpak install -y flathub <app-id>
+#                      remove: sudo flatpak uninstall -y <app-id>
+#
+#   .deb download      download to temp, sudo apt install -y ./file.deb
+#
+#   File/AppImage      install under /opt/<app>; in uninstall remove the
+#                      files, symlinks, and desktop entries
+#
+#   usermod for groups sudo usermod -aG <group> "$USER" + print a
+#                      re-login reminder
+#
+# Every app MUST be idempotent (guard install AND uninstall) and MUST
+# provide uninstall_myapp() + the uninstall case dispatch above.
+# ────────────────────────────────────────────────────────────────

templates/feature.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ────────────────────────────────────────────────────────────────
+# TEMPLATE — new feature script
+#
+#  1. Copy:  cp templates/feature.sh features/<name>.sh
+#  2. Docs:  DOC/AGENT_Context_Project.md file table line counts.
+#
+# Installed on demand with:  ./install.sh --feature
+#   → copied to /usr/local/bin/<name>.sh (chmod 755)
+#   → flag "<name>" is set (basename of the file, minus .sh)
+# Features are user-customizable — install.sh never overwrites an
+# existing /usr/local/bin copy without asking.
+#
+# If a systemd service depends on this feature, gate it in
+# postinstall.sh's systemd loop:
+#   if [ "$svc_name" = "<name>.service" ] && ! flag_is_set <name>; then
+#       warn "<name> feature not installed — skipping <name>.service"
+#       continue
+#   fi
+# ────────────────────────────────────────────────────────────────
+
+# Robust flags.sh load — works from the repo checkout AND from
+# /usr/local/bin after install.sh (which copies lib/flags.sh there).
+source "$(dirname "$0")/../lib/flags.sh" 2>/dev/null || source "$(dirname "$0")/flags.sh"
+
+# Self-name → matches the flag install.sh sets for this feature.
+FEATURE_NAME="$(basename "$0")"
+FEATURE_NAME="${FEATURE_NAME%.sh}"
+
+usage() {
+    cat <<EOF
+Usage: ${FEATURE_NAME}.sh [options]
+
+<describe what this feature does>
+
+Installed via:  ./install.sh --feature
+Flag:           ${FEATURE_NAME}
+EOF
+    exit 0
+}
+
+case "${1:-}" in
+    -h|--help) usage ;;
+esac
+
+# ── script logic ────────────────────────────────────────────────
+# Feature scripts may run repeatedly (e.g. at every boot via a
+# systemd service), so keep them idempotent.
+#
+#   flag_is_set "$FEATURE_NAME" || exit 0      # bail when not installed
+#   v=$(flag_value "$FEATURE_NAME")            # read an optional value
+#   flag_clear "$FEATURE_NAME"                 # uninstall behavior

templates/pos-tool.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ────────────────────────────────────────────────────────────────
+# TEMPLATE — new `pos` CLI tool
+#
+#  1. Copy:     cp templates/pos-tool.sh bin/pos-<category>-<command>
+#  2. Exec bit: chmod +x bin/pos-<category>-<command>
+#  3. Register: add the command to usage() CATEGORIES/EXAMPLES in bin/pos
+#     If it reads stdin (password/selection prompts), also add it to
+#     INTERACTIVE_CMDS in bin/pos or its prompt breaks under the log tee.
+#  4. Docs:     DOC/POS.md section table + detail block,
+#     DOC/AGENT_Context_Project.md (bin tree, dispatch table,
+#     self-contained list, file line-count table), root README.md only
+#     when the category list changes.
+#  5. Deps:     add packages to PACKAGES in preinstall.sh if needed.
+#
+# Invoked as:  pos <category> <command> [args]
+# ────────────────────────────────────────────────────────────────
+
+# Robust common.sh load — works from the repo checkout AND from
+# /usr/local/bin after install.sh (which copies lib/common.sh there).
+source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
+
+# Optional runtime config (see DEV.md "Config files"):
+# CONFIG_FILE="$HOME/.config/linux_post_install/<tool>.env"
+
+usage() {
+    cat <<EOF
+Usage: pos <category> <command> [args]
+
+<describe what this command does>
+
+Examples:
+  pos <category> <command> arg1
+EOF
+    exit 0
+}
+
+case "${1:-}" in
+    -h|--help) usage ;;
+esac
+
+# ── script logic ────────────────────────────────────────────────
+# Use helpers from common.sh: log / warn / err / ok / section /
+# step / run (respects --dry-run) / spawn / confirm.
+#
+#   command -v <dep> &>/dev/null || err "<dep> not found"
+#   run sudo <command>                          # dry-run aware
+#   log "done"                                  # green [+] message
+#
+# Exit 0 on success, err() exits 1 on failure.