neovim-ide/CLAUDE.md

# arch-dev — Project Context for Claude Code

## What this is
A portable, stateless Arch Linux development environment running in Docker.
Headless, riced, mobile-aware. Built for serious dev work from any box —
including from a phone via Termius.

The tagline that stuck: **"Riced Neovim IDE"**

---

## The Human

Wayne. Works primarily from mobile (Android + Termius). 
Prefers vim keybindings everywhere. Wants things clean and professional — 
"Apple good" was the benchmark set early on. Doesn't want walls of text.
Will call you out if you guess instead of reading docs.
Has a Gitea instance at https://code.waynehayesdevelopment.com

---

## Architecture

```
arch-dev/
├── Dockerfile              # Arch rolling release, pacman + AUR (yay)
├── docker-compose.yml      # Named volume for stateful /home/dev
├── entrypoint.sh           # First-run seeding + dotfile update detection
├── .gitignore
├── workspace/              # Bind mount — host-visible project files
└── dotfiles/               # Baked into /etc/skel-arch-dev/ in image
    ├── .zshrc              # 256-color only, mobile detection, snapshot fns
    ├── .aliases
    ├── .screenrc           # Mobile multiplexer
    ├── .config/
    │   ├── starship.toml          # Desktop: 256-color Kanagawa Wave approx
    │   ├── starship-mobile.toml   # Mobile: single line, no icons
    │   ├── tmux/tmux.conf         # Desktop mux, Ctrl+Space prefix
    │   └── nvim/                  # Full LSP/lint/format setup
```

---

## The Stateful Home System (v1.7)

`/home/dev` is a **named Docker volume** (`arch-dev-home`). Persists across
`--rm` container exits. NOT wiped on exit — only on `docker volume rm`.

On first run, entrypoint seeds the volume from `/etc/skel-arch-dev/`
(baked into the image). Subsequent runs detect if image dotfiles are newer
and auto-update (with auto-snapshot first).

### Git-backed snapshots

`~/.arch-dev-state/` is a separate-git-dir tracking `/home/dev`.
No `.git` folder in `~` — avoids nested git conflicts with project repos.

Shell functions (defined in .zshrc):
- `snapshot <name> [msg]` / `snap` — tag current state
- `snapshots` / `snaps` — list tags + recent commits
- `rollback <name>` / `snapr` — reset to tag (confirms first, auto-snaps)
- `diff-state` / `snapd` — what's changed since last commit
- `show-snapshot <name>` — inspect a tag
- `unsnapshot <name>` — delete a tag
- `_archdev_git` — raw git wrapper (separate git dir)

---

## The Color Problem (solved in v1.4+)

Termius on Android cannot render truecolor RGB escape codes.
They show as **purple/magenta backgrounds** on everything.

**Rules:**
- No `COLORTERM=truecolor` in compose or shell
- No hex colors (`#7E9CD8`) in starship, zsh-syntax-highlighting, tmux
- All shell-visible configs use 256-color ANSI codes (`fg=110` etc.)
- `termguicolors` in neovim is conditional: `vim.env.MOBILE ~= "1"`
- Mobile colorscheme: `habamax` (built-in, 256-color clean)
- Desktop colorscheme: `kanagawa-wave` (needs termguicolors)
- Bufferline disabled on mobile (emits RGB for tab backgrounds)
- noice.nvim removed entirely (bled colors into terminal)

**Kanagawa Wave 256-color approximations:**
```
110 = crystalBlue    106 = springGreen    139 = oniViolet
173 = boatYellow     167 = peachRed        66 = waveAqua
242 = fujiGray       250 = fujiWhite      236 = waveBlue
```

---

## Mobile Detection

`MOBILE=1` env var (set in Termius host profile) activates:
- Minimal single-line starship prompt (no icons)
- screen auto-attach instead of tmux
- habamax colorscheme in neovim
- termguicolors disabled
- Bufferline disabled
- Compact aliases (`g` for git, etc.)

---

## Plugin API Changes (hard-won knowledge)

Every one of these bit us. Read docs before touching:

| Plugin | Issue | Fix |
|--------|-------|-----|
| `leap.nvim` | Moved GitHub→Codeberg | `url = "https://codeberg.org/andyg/leap.nvim"` |
| `leap.nvim` | `add_default_mappings()` removed | Use `<Plug>(leap)` keymaps directly |
| `nvim-treesitter` | `.configs` module gone | `require("nvim-treesitter").setup{}`, `branch="main"`, `lazy=false` |
| `nvim-surround` | v4 removed `keymaps` table | `require("nvim-surround").setup()` defaults only |
| `nvim-lspconfig` | Framework deprecated in 0.11 | `vim.lsp.config()` + `vim.lsp.enable()` |
| `vim.lsp.with()` | Deprecated | Handlers in `vim.lsp.config("*", { handlers = {} })` |
| `on_attach` | Old pattern | `LspAttach` autocmd |

---

## What's NOT in v1 (coming in v2)

- nvm + nodejs
- Claude CLI
- Gemini CLI  
- Aider
- nvim AI plugin (copilot/avante/codecompanion)

v2 plan: install AI tools in the stateful container, snapshot as `ai-tools`,
then layer nodejs on top.

---

## Git / Repo

- Gitea: https://code.waynehayesdevelopment.com/wayne/neovim-ide
- `main` branch = current stable (v1.7)
- `v2` branch = active development
- `v1.7` tag = frozen reference

Wayne is new to multi-branch git workflow — be explicit about which branch
to be on before any git operations.

---

## Tone / Style Notes

- Short responses. Wayne reads on mobile.
- No bullet-point walls. Prose or tight tables.
- Don't guess at APIs — fetch the docs first.
- When something breaks, ask for the actual error before debugging.
- Wayne will test each version and report back with screenshots.
- "Apple good" is the visual quality bar.