Revive terminal dotfiles setup

README.md

@@ -1,21 +1,166 @@
-All my dotfiles at one place.
+# Dotfiles
 
-I will delete the i3 and vim dotfiles repos soon.
-I have merged them with this repo, so the version history
-of the two repos is saved in this repo.
+Personal terminal-environment config for machines that should feel familiar:
+music, editor, file navigation, and other CLI workflows.
 
-ranger for file navigation.
+This repo is being revived in stages. The current v1 target is intentionally
+small:
 
-mpd and ncmpcpp for music (command line)
+- macOS music playback with `mpd`, `ncmpcpp`, and local files under
+  `/Users/sourya4/pro/youtube_download/music`
+- baseline Neovim config, plus a minimal Vim fallback
+- AI-enabled Neovim chat through CodeCompanion and Codex ACP
+- ranger config with portable clipboard helpers
+- Git terminal tools such as `gitui`
 
-vimperator is a firefox extension
+`ma08/botfiles` remains the home for coding-agent, orchestration, hooks, skills,
+secrets-aware shell bootstrap, and agent-specific aliases. This repo owns
+general human terminal UX: shell ergonomics, editors, music, file navigation,
+Git terminal tools, and user-facing app config. Botfiles can extend this
+environment for agent workflows, but should not replace it as the general
+dotfiles layer.
 
-The present state of repo is not suitable for anyone to follow.
-Still, if you are interested, you can have a peek. I will clean up
-and write a more descriptive README later outlining all the features and
-the setup process.
+## Quick Start
 
-Look into install.sh to get an idea of the setup (regarding symlinks and git
-    submodules for vim plugins). 
+Preview everything first:
 
-![alt tag](screen.png)
+```bash
+./setup.sh --all
+```
+
+Apply the current v1 config:
+
+```bash
+./setup.sh --all --apply
+```
+
+Install the macOS music packages and apply music config:
+
+```bash
+./setup.sh --music --install-packages --apply
+```
+
+Install Git terminal tools:
+
+```bash
+./setup.sh --git --install-packages --apply
+```
+
+Install packages for the full v1 profile and apply all current config:
+
+```bash
+./setup.sh --all --install-packages --apply
+```
+
+The setup script backs up existing non-matching files before replacing them with
+symlinks. Without `--apply`, it only prints what it would do.
+
+## Music
+
+The macOS music profile installs or configures:
+
+- `mpd`
+- `mpc`
+- `ncmpcpp`
+
+Relevant paths:
+
+- MPD config: `~/.mpd/mpd.conf`
+- MPD music directory: `/Users/sourya4/pro/youtube_download/music`
+- ncmpcpp config: `~/.ncmpcpp/config`
+- ncmpcpp bindings: `~/.ncmpcpp/bindings`
+- MPD CoreAudio restart helper: `~/.local/bin/dotfiles-mpd-restart`
+
+Basic checks:
+
+```bash
+mpd --no-daemon ~/.mpd/mpd.conf
+mpc update
+ncmpcpp
+```
+
+Hammerspoon watches for macOS audio output changes and runs the MPD restart
+helper when MPD is already running. This works around stale CoreAudio device
+handles after plugging, unplugging, or switching output devices.
+
+Hammerspoon also maps macOS media keys to MPD for play/pause, next, and
+previous. To avoid stealing media keys from Chrome or other players, it only
+handles them when MPD is already playing, or when MPD is paused and the
+frontmost app is not a known media app such as Chrome, Safari, Spotify, Music,
+VLC, or IINA.
+
+Terminal playback is the v1 success gate. macOS media keys / Now Playing support
+is a follow-up unless it becomes simple and reliable.
+
+## Editor
+
+Neovim is the primary editor target:
+
+- `nvim/init.lua` -> `~/.config/nvim/init.lua`
+
+With `--install-packages`, the editor profile installs `neovim` through
+Homebrew, plus `node` for `npx`-backed ACP adapters.
+
+The editor profile also sets Git's global editor to `nvim` and enables verbose
+commit templates, so `git commit` opens Neovim with the staged diff available as
+commented context.
+
+Vim gets a minimal fallback:
+
+- `vim/vimrc-basic` -> `~/.vimrc`
+
+The old `vim/.vimrc` and Vim bundle submodules are historical material, not the
+default install path for the revived setup.
+
+### AI In Neovim
+
+The Neovim config bootstraps `lazy.nvim`, installs CodeCompanion, and configures
+the Codex ACP adapter with ChatGPT authentication. It runs the Zed Codex ACP
+adapter through:
+
+```bash
+npx -y @zed-industries/codex-acp
+```
+
+Use `:CodeCompanionChat` inside Neovim to open an AI chat buffer. The first run
+may download plugins and the ACP adapter. ChatGPT auth must be available through
+Codex/Codex ACP on the machine.
+
+Inline edits use Gemini 3.6 Flash through CodeCompanion's Gemini HTTP adapter.
+Set `GEMINI_API_KEY` in the machine-local botfiles secrets loaded by `.botenv`;
+do not place it in this repository. The adapter is intentionally non-streaming
+because CodeCompanion's Gemini inline handler requires a complete response. It
+uses Gemini's `minimal` thinking level to keep inline edits responsive.
+
+In `git commit` buffers, press `,cm` to draft a commit message from the verbose
+commit buffer. Press `,cy` to accept CodeCompanion's proposed edit or `,cn` to
+reject it.
+
+While CodeCompanion is waiting on a chat or inline request, the statusline shows
+an `AI` spinner with the active adapter/model. It briefly changes to `AI done`,
+`AI cancelled`, or `AI error` when the request finishes.
+
+## Ranger
+
+The ranger profile links the repo's ranger config into `~/.config/ranger/` and
+installs `bin/dotfiles-clipboard-copy` into `~/.local/bin/`. The clipboard helper
+uses `pbcopy`, `wl-copy`, `xclip`, or `xsel`, depending on what the machine has.
+With `--install-packages`, the ranger profile installs `ranger` through Homebrew.
+
+## Git Tools
+
+The Git tools profile installs `gitui` through Homebrew/Linuxbrew. GitUI config
+uses vim-style navigation through:
+
+- `config/gitui/key_bindings.ron` -> `~/.config/gitui/key_bindings.ron`
+
+The setup also links `bin/dotfiles-gitui` to `~/.local/bin/gitui` on machines
+where GitUI is installed by Homebrew/Linuxbrew. Keeping config under
+`config/gitui/` avoids a zsh `AUTO_CD` collision with the `gitui` command.
+
+## Historical Material
+
+The old repo includes i3, polybar, Vimperator, X resources, old Linux desktop
+scripts, and large Vim plugin submodule history. Those are preserved for now but
+not installed by the default v1 setup. Audit and resurrect them only after an
+explicit review.

bin/dotfiles-clipboard-copy

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v pbcopy >/dev/null 2>&1; then
+  exec pbcopy
+fi
+
+if command -v wl-copy >/dev/null 2>&1; then
+  exec wl-copy
+fi
+
+if command -v xclip >/dev/null 2>&1; then
+  exec xclip -selection clipboard
+fi
+
+if command -v xsel >/dev/null 2>&1; then
+  exec xsel -ib
+fi
+
+cat >/dev/null
+echo "dotfiles-clipboard-copy: no clipboard command found" >&2
+exit 1

bin/dotfiles-gitui

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -x /opt/homebrew/bin/gitui ]; then
+  exec /opt/homebrew/bin/gitui "$@"
+fi
+
+if [ -x /home/linuxbrew/.linuxbrew/bin/gitui ]; then
+  exec /home/linuxbrew/.linuxbrew/bin/gitui "$@"
+fi
+
+resolved="$(command -v gitui 2>/dev/null || true)"
+if [ -n "$resolved" ] && [ "$resolved" != "$0" ]; then
+  exec "$resolved" "$@"
+fi
+
+echo "ERROR: gitui binary not found; install GitUI or rerun setup with --install-packages" >&2
+exit 127

bin/dotfiles-mpd-restart

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+only_if_running=0
+reason="manual"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --if-running)
+      only_if_running=1
+      ;;
+    --reason)
+      shift
+      reason="${1:-manual}"
+      ;;
+    *)
+      echo "ERROR: unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+  shift
+done
+
+mpd_bin="${MPD_BIN:-}"
+mpc_bin="${MPC_BIN:-}"
+mpd_config="${MPD_CONFIG:-$HOME/.mpd/mpd.conf}"
+mpd_log_dir="$HOME/.mpd"
+restart_log="$mpd_log_dir/restart.log"
+
+if [ -z "$mpd_bin" ]; then
+  if [ -x /opt/homebrew/bin/mpd ]; then
+    mpd_bin=/opt/homebrew/bin/mpd
+  elif [ -x /home/linuxbrew/.linuxbrew/bin/mpd ]; then
+    mpd_bin=/home/linuxbrew/.linuxbrew/bin/mpd
+  else
+    mpd_bin="$(command -v mpd 2>/dev/null || true)"
+  fi
+fi
+
+if [ -z "$mpc_bin" ]; then
+  if [ -x /opt/homebrew/bin/mpc ]; then
+    mpc_bin=/opt/homebrew/bin/mpc
+  elif [ -x /home/linuxbrew/.linuxbrew/bin/mpc ]; then
+    mpc_bin=/home/linuxbrew/.linuxbrew/bin/mpc
+  else
+    mpc_bin="$(command -v mpc 2>/dev/null || true)"
+  fi
+fi
+
+if [ -z "$mpd_bin" ] || [ -z "$mpc_bin" ]; then
+  echo "ERROR: mpd/mpc not found" >&2
+  exit 127
+fi
+
+mkdir -p "$mpd_log_dir"
+
+log() {
+  printf '%s %s\n' "$(date '+%Y-%m-%dT%H:%M:%S%z')" "$*" >> "$restart_log"
+}
+
+if ! pgrep -x mpd >/dev/null 2>&1; then
+  if [ "$only_if_running" -eq 1 ]; then
+    log "skip: mpd not running reason=$reason"
+    exit 0
+  fi
+fi
+
+status="$("$mpc_bin" -h 127.0.0.1 -p 6600 status 2>/dev/null || true)"
+was_playing=0
+if printf '%s\n' "$status" | grep -q '\[playing\]'; then
+  was_playing=1
+fi
+
+log "restart begin reason=$reason was_playing=$was_playing"
+
+pkill -x mpd >/dev/null 2>&1 || true
+for _ in 1 2 3 4 5; do
+  if ! pgrep -x mpd >/dev/null 2>&1; then
+    break
+  fi
+  sleep 0.2
+done
+
+if pgrep -x mpd >/dev/null 2>&1; then
+  pkill -KILL -x mpd >/dev/null 2>&1 || true
+  sleep 0.5
+fi
+
+"$mpd_bin" "$mpd_config"
+sleep 0.8
+
+if [ "$was_playing" -eq 1 ]; then
+  "$mpc_bin" -h 127.0.0.1 -p 6600 play >/dev/null 2>&1 || true
+fi
+
+log "restart complete reason=$reason"

config/gitui/key_bindings.ron

@@ -0,0 +1,35 @@
+// Vim-style GitUI key bindings.
+//
+// GitUI reads this file from ~/.config/gitui/key_bindings.ron.
+// Unspecified keys keep GitUI's built-in defaults.
+(
+    open_help: Some(( code: F(1), modifiers: "")),
+
+    move_left: Some(( code: Char('h'), modifiers: "")),
+    move_right: Some(( code: Char('l'), modifiers: "")),
+    move_up: Some(( code: Char('k'), modifiers: "")),
+    move_down: Some(( code: Char('j'), modifiers: "")),
+
+    popup_up: Some(( code: Char('p'), modifiers: "CONTROL")),
+    popup_down: Some(( code: Char('n'), modifiers: "CONTROL")),
+    page_up: Some(( code: Char('b'), modifiers: "CONTROL")),
+    page_down: Some(( code: Char('f'), modifiers: "CONTROL")),
+    home: Some(( code: Char('g'), modifiers: "")),
+    end: Some(( code: Char('G'), modifiers: "SHIFT")),
+    shift_up: Some(( code: Char('K'), modifiers: "SHIFT")),
+    shift_down: Some(( code: Char('J'), modifiers: "SHIFT")),
+
+    edit_file: Some(( code: Char('I'), modifiers: "SHIFT")),
+
+    status_reset_item: Some(( code: Char('U'), modifiers: "SHIFT")),
+
+    diff_reset_lines: Some(( code: Char('u'), modifiers: "")),
+    diff_stage_lines: Some(( code: Char('s'), modifiers: "")),
+
+    stashing_save: Some(( code: Char('w'), modifiers: "")),
+    stashing_toggle_index: Some(( code: Char('m'), modifiers: "")),
+
+    stash_open: Some(( code: Char('l'), modifiers: "")),
+
+    abort_merge: Some(( code: Char('M'), modifiers: "SHIFT")),
+)