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 AI tools that need 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

### v2.2 — Tailscale
- Tailscale baked in via AUR
- `/dev/net/tun` device pass-through for kernel-mode networking
- `NET_ADMIN` + `NET_RAW` capabilities granted
- First-run auth, then `snap tailscale` for persistence

```bash
# Inside container, first time:
sudo tailscaled &
sudo tailscale up    # follow auth URL
snap tailscale "authenticated to tailnet"
```

### v2.3 — Companion plugin (separate repo)
**`tailscale.nvim`** — original FOSS work, no equivalent exists yet:
- Lualine status component
- Telescope peer picker
- Quick IP copy + status window
- Repo: github.com/<you>/tailscale.nvim

---

## 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`

---

## Container Capabilities

The container drops ALL capabilities then re-adds only what's needed:

| Cap | Why |
|---|---|
| `NET_BIND_SERVICE` | Bind to ports < 1024 (mosh) |
| `SETUID` / `SETGID` | sudo |
| `AUDIT_WRITE` | sudoers_audit plugin |
| `NET_ADMIN` / `NET_RAW` | Tailscale |

Plus device pass-through for `/dev/net/tun` (Tailscale kernel mode).

---

## 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

With Tailscale (v2.2+), you can reach arch-dev from any device on your
tailnet without exposing ports — perfect for mobile dev anywhere.