neovim-ide/README.md

# arch-dev
### Riced Neovim IDE · Arch Linux · Stateful · Mobile-Aware

> *"Like Gentoo without the compiling."*
> *I use Arch BTW*

Kanagawa Wave · rolling release · AUR-powered · git-snapshotted home

---

## Branches

| Branch | Purpose |
|---|---|
| `main` | Latest stable |
| `v2` | Active development |
| `v1.7` (tag) | Frozen v1.7 reference |

---

## What's in v2

### v2.0 — AI tooling
- Claude Code CLI (snapshot after install + login)
- Gemini CLI
- Aider
- nvm + Node.js (for any AI tool that needs it)

### v2.1 — Image & ASCII tooling
- ImageMagick — image manipulation
- chafa — modern terminal image rendering (truecolor + sixel)
- jp2a — fast JPEG/PNG to ASCII art

Workflow: AI rough sketch → `chafa --symbols ascii` → hand-tweak

---

## v1.7 — What's there now

- Stateful `/home/dev` via named Docker volume
- Git-backed snapshot/rollback system (`snap`, `snaps`, `rollback`)
- Auto-snapshot on dotfile updates
- Mobile detection (`MOBILE=1` for Termius)
- Kanagawa Wave colorscheme (desktop) / habamax (mobile)
- LSP/lint/format for Python, Bash, Lua
- Telescope, oil, lazygit, leap, treesitter

---

## Quick Start

```bash
docker compose build
docker compose run --rm arch-dev
```

First run seeds `/home/dev` from the baked-in skeleton and creates a
`skeleton` snapshot you can always roll back to.

---

## Snapshot System

Your home is a git repo (state in `~/.arch-dev-state/`). Save good states,
roll back when things break.

```bash
snap node-working "NodeJS env with nvm + pnpm"  # save state
snaps                                            # list snapshots
snapd                                            # diff vs last snapshot
rollback node-working                            # reset to snapshot
```

---

## Volume Architecture

| Path | Type | Purpose |
|---|---|---|
| `/workspace` | bind mount → `./workspace` | Project files, host-visible |
| `/home/dev` | named volume | Stateful user home |
| `/etc/skel-arch-dev/` | image layer | Read-only template |

Reset home to factory: `docker volume rm <project>_arch-dev-home`

---

## State Tracking — Two Systems

| System | What | Where |
|---|---|---|
| **git on v2 branch** | Dockerfile, dotfiles, build recipe | Gitea repo |
| **`snap` inside container** | Runtime state, installed tools, auth | Docker volume |

Both required for full reproducibility — Dockerfile builds the OS,
snapshots restore the user state on top of it.

---

## Mobile (Termius)

Set `MOBILE=1` in Termius host profile env vars to activate:
- Single-line minimal starship prompt
- Auto-attach screen on connect
- habamax colorscheme (kanagawa needs truecolor)
- termguicolors disabled in neovim
- Bufferline disabled