setup_env/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

Personal Linux development environment setup. Clone and run one script to get a consistent shell and editor across machines.

## Key Commands

### Fresh machine setup
```bash
git clone git@gitea.hptrow.me:pt/setup_env.git ~/setup_env
cd ~/setup_env && ./setup_env.sh
```

`setup_env.sh` installs packages, downloads Neovim, clones plugin managers, deploys all dotfile symlinks, and sets up NvChad.

### Day-to-day sync
```bash
cd ~/setup_env && ./sync.sh
```

Pulls setup_env and nvim config repos, redeploys symlinks. Safe to run anytime.

### Optional tool installs (run manually per machine)
```bash
./install_postgres.sh      # PostgreSQL from official apt repository
./install_python3.sh       # Latest Python 3 from deadsnakes PPA (includes python3-venv)
./install_node.sh          # Node.js via nvm (needed for prettier formatter in nvim)
./install_java_dev.sh      # SDKMAN for Java development
./install_visidata.sh      # VisiData for terminal data exploration
./reinstall_nvchad.sh      # Wipe and reinstall NvChad from scratch
```

### After plugin manager install
- **Tmux**: press `Ctrl-b + I` to install TPM plugins
- **Vim**: run `:PluginInstall` inside vim

## Architecture

### Scripts

- `setup_env.sh` — fresh machine only. Installs everything in order.
- `sync.sh` — day-to-day. Pulls repos and redeploys symlinks. No apt, no sudo.
- `_lib.sh` — shared deploy functions sourced by both scripts.
- `install_neovim.sh` — downloads Neovim v0.11.3 to `/opt/`, auto-adds to `.bashrc_paths`. Called by `setup_env.sh`.
- `install_nvchad.sh` — clones nvim config from gitea on fresh install, or `git pull`s if already present. Called by both `setup_env.sh` and `sync.sh`.
- `reinstall_nvchad.sh` — wipes all nvim data and re-runs `install_nvchad.sh`. Run manually when nvim is broken.
- `install_*.sh` — optional installs, run manually per machine.

### Dotfile Management

Symlink-based deployment. Editing `~/.<file>` directly edits the repo file. `git status` shows config drift.

`deploy_configs`, `deploy_bin`, and `deploy_nvim` (in `_lib.sh`) handle symlinking. `create_symlink` skips if already correct. `migrate_and_link` (used for gitignored files) migrates existing real files into the repo, or bootstraps from `_example` if nothing exists.

**Tracked dotfiles** (in git):
- `dotfiles/.bashrc` — main shell config
- `dotfiles/.vimrc`, `.gitconfig`, `.tmux.conf`, `.psqlrc`, `.pspgconf`
- `dotfiles/bin/td` — time-tracking CLI
- `dotfiles/nvim/td.lua`, `td_mappings.lua` — nvim time-tracking integration
- `dotfiles/nvim/rename_term.lua` — vault-wide find-and-replace with confirmation popup (`<leader>rn`)
- `dotfiles/nvim/telescope_tasks.lua` — vault-wide task pickers (`<leader>tl` open tasks, `<leader>tL` priority tasks)

**Gitignored** (machine-specific, auto-bootstrapped from examples):
- `dotfiles/.bashrc_local` — secrets and credentials
- `dotfiles/.bashrc_paths` — PATH additions and tool inits

### Two-repo nvim setup

The nvim config lives in a separate repo at `git@gitea.hptrow.me:pt/nvchad.git` (`customize` branch), deployed to `~/.config/nvim`. `install_nvchad.sh` manages it.

**Ownership boundary — important:**
- **nvchad repo owns `mappings.lua`** — this is the keymap entry point. It lives in `~/.config/nvim/lua/mappings.lua` and is tracked by the nvchad git repo. Edit it there, push from `~/.config/nvim`.
- **setup_env owns feature modules** — `td.lua`, `td_mappings.lua`, `rename_term.lua`, `telescope_tasks.lua`. These are deployed as symlinks into `~/.config/nvim/lua/` by `deploy_nvim`. The nvchad repo does NOT track them. `mappings.lua` loads them via `require`.

Do NOT put `mappings.lua` in `dotfiles/nvim/`. It will conflict with the nvchad repo's tracked copy on every `git pull` during sync, producing `.backup` files on all machines.

**Dependency**: `deploy_nvim` must run after `install_nvchad.sh` has created `~/.config/nvim/lua/`. On a fresh machine this is handled automatically by `setup_env.sh` ordering. On existing machines `sync.sh` handles it.

## Custom Bash Workflow

### Database Query Management

PostgreSQL (env var `$PG` defined in `.bashrc_local`):
- `xnspa([args])` — fzf-select an open nvim swap file, run with `$PG`, output CSV to VisiData. Accepts extra psql args.
- `xnsp` — same, output to pspg
- `xns` — same, raw output

SQL Server (env vars `$MS`, `$MSC`, `$MSW` in `.bashrc_local`):
- `xmspa()` — fzf-select swap file, run with `$MSC`, pipe-delimited output to VisiData
- `xmsp` — same, output to pspg
- `xms` — same, raw output

General:
- `ons` — list open nvim swap files in current directory tree

### Git Aliases
- `gs` — git status short
- `ga` — interactive git add via fzf
- `gx` — interactive git checkout via fzf
- `vc()` — `git add -u`, commit with timestamp, push
- `gr`, `gc`, `gd`, `gl` — reset, commit, difftool, log

### Todo Grep (rg-based)
- `td` — find unchecked todos
- `tdp` / `tdtp` — priority todos (🔼 / ⏫)
- `tdo` / `tdop` — open todo in nvim at exact line

### Time Tracking
Shell wrappers around `dotfiles/bin/td` (bypasses the `td` rg alias via `command td`):
- `tstart` / `tstop` / `treport` / `tweek`

Nvim keymaps (via `td_mappings.lua`): `<leader>ts/tp/tr/tw`

### Other Aliases
- `cj` — cd to journal
- `jr` / `hc` — sync journal / hc notes

## Machine-specific Configuration

`.bashrc` sources two gitignored files:

- **`.bashrc_local`** — secrets: DB connection strings, passwords, tokens
- **`.bashrc_paths`** — PATH additions: nvim, cargo, nvm, java, etc.

Both are auto-bootstrapped from `_example` files on first `setup_env.sh` run. When a tool appends to `.bashrc`, `git status` shows it — move those lines to `.bashrc_paths`.

## Git Commit Style

Simple lowercase messages: "add cargo", "visidata", "fix nv alias path"