# notes

## Framework 12 tablet support

The `nixos-hardware` Framework 12 module loads `pinctrl_tigerlake` in the initrd before `soc_button_array`, enables IIO sensors, installs `framework_tool`, and keeps firmware updates available through `fwupd`. `services.iio-niri` forwards accelerometer orientation to Niri for the internal `eDP-1` panel.

`home/tablet.nix` provides two user services:

- `tablet-keyboard.service` keeps `wvkbd` hidden and ready to toggle with `Mod+Shift+K`. It intentionally does not open automatically when entering tablet mode.
- `tablet-gestures.service` reads the internal ILIT2901 touchscreen, maps two-finger swipes from the left/right edges to column navigation, and maps a two-finger swipe from the bottom edge to Niri's overview. It follows accelerometer events and restarts `lisgd` with the matching orientation after the screen rotates.

The gestures are experimental and can interfere with multi-touch drawing applications. Disable them with:

```bash
systemctl --user disable --now tablet-gestures.service
```

Useful diagnostics after a reboot:

```bash
sudo libinput debug-events | grep SWITCH_TOGGLE
monitor-sensor --accel
framework_tool --sensors
systemctl status iio-sensor-proxy.service
systemctl --user status iio-niri.service tablet-keyboard.service tablet-gestures.service
```

The host enables NixOS's Powertop service, which applies `powertop --auto-tune` once at boot. `power-profiles-daemon` remains enabled for switching CPU energy profiles. If a peripheral develops autosuspend problems, test without the tunings using `sudo systemctl stop powertop.service` before disabling `powerManagement.powertop.enable`.

Sources used for this setup:

- [Niri switch events](https://niri-wm.github.io/niri/Configuration%3A-Switch-Events.html) documents tablet-mode hooks. They are not used to show the keyboard automatically here.
- [Niri touchscreen gestures discussion](https://github.com/niri-wm/niri/discussions/463) covers `lisgd`, rotation handling, Roland, and experimental native gesture work.
- [Framework 12 Sway tips](https://community.frame.work/t/sway-on-the-framework-laptop-12/73173) demonstrates the practical `wvkbd`, rotation, and touch-sized bar-control pattern.
- [Framework 12 tablet requirements](https://community.frame.work/t/what-are-the-linux-system-requirements-for-tablet-mode/71466) and the [tablet-mode recovery tracking thread](https://community.frame.work/t/fw12-problems-returning-from-tablet-mode-tracking-thread/71631) cover kernel module ordering and hardware failure modes.
- [The Tangled repository](https://tangled.org/molly.computer/nixos/tree/master) is the primary remote for this configuration. Tangled's public search currently exposes few comparable Framework 12 configurations.

### software to investigate

- `rnote`: touch-first handwritten notes and sketching.
- `xournalpp`: handwriting and PDF annotation.
- `krita`: mature pressure-sensitive drawing and painting.
- `foliate`: touch-friendly ebook reader.
- `papers`: document and PDF reader with a compact GTK interface.
- `kdeconnect` or `localsend`: phone integration and local file transfer.
- `kooha`: simple Wayland screen recording.
- `powerstat`: compare actual battery use before and after Powertop tuning; `sudo powertop` provides interactive wakeup and device diagnostics.
- `zramSwap`: compressed memory fallback during heavy builds or games; less urgent while the system has ample disk swap.
- Framework EC charge limits: cap charging around 80% for battery longevity after confirming support and preferred travel behavior.
- `unl0kr`: touchscreen initrd unlock if disk encryption is added later.
- `roland`: Niri-focused edge gesture daemon with better edge detection than `lisgd`, but it is lightly maintained and not packaged in nixpkgs.
- `sysboard`: another Niri-compatible on-screen keyboard worth comparing with `wvkbd`.
- `squeekboard`: richer input-method behavior if its standalone compositor integration improves.

## pulling this config to a new system

1. Install NixOS and make sure flakes are enabled:
   ```bash
   nix-shell -p git
   ```

2. Clone the repo:
   ```bash
   git clone https://github.com/oomlie/nixos nixos-config
   cd nixos-config
   ```

3. If the target hardware differs from `chi`, regenerate the hardware config:
   ```bash
   sudo nixos-generate-config --root /mnt --show-hardware-config > hosts/chi/hardware-configuration.nix
   ```
   On an already-running NixOS system, you can also copy the generated file from `/etc/nixos/hardware-configuration.nix`.

4. Optional: link it into `/etc/nixos`:
   ```bash
   sudo ln -s $(pwd) /etc/nixos
   ```

5. Apply the configuration:
   ```bash
   sudo nixos-rebuild switch --flake .#chi
   ```

---

## Development environment

The user environment is managed by Home Manager in `home/`.

### Editor: Helix

- Package: `pkgs.helix`
- Default editor (`EDITOR=hx`)
- Theme: generated by Stylix from the wallpaper
- Line numbers: relative
- Language servers on `PATH`: `nil` (Nix), `rust-analyzer`, `bash-language-server`,
  `vscode-langservers-extracted` (JSON/CSS/HTML/ESLint), `yaml-language-server`,
  `marksman` (Markdown), `typescript-language-server`, `pyright` (Python)
- Formatters with auto-format: `alejandra` (Nix), `rustfmt`, `shfmt` (Bash),
  `taplo` (TOML), `prettier` (Markdown/TS/JS)

### Shell & terminal

- zsh: autosuggestions, syntax highlighting, history substring search,
  case-insensitive menu completion, shared 50,000-line history
- fzf: reverse layout, `~40%` height, inline info, `ctrl-j`/`ctrl-k` navigation
  (colors from Stylix)
- eza shows git status; bat pages with `less -FR`
- foot runs as a server and `Mod+Return` spawns `footclient`
- SSH connection multiplexing (`ControlMaster auto`, 10-minute persist)

### Git

Git is fully configured through `programs.git`:

- User: `molly.computer <molly@molly.computer>`
- Default branch: `main`
- `push.autoSetupRemote = true`
- `pull.rebase = false`
- Core editor: Helix (`hx`)
- `git hdiff` / `git hshow`: review changes with Hunk
- `git dft`: structural diffs with Difftastic
- Delta is the git diff pager (`programs.delta` with git integration)
- `git-lfs` enabled
- SSH commit/tag signing with `~/.ssh/mol.pub` (`signByDefault = true`); Jujutsu
  signs its own commits with the same key
- Extra defaults: `merge.conflictStyle = "zdiff3"`, `diff.algorithm = "histogram"`,
  `rerere.enabled`, `fetch.prune`, `rebase.autoStash`, `column.ui`, `branch.sort`

### Agent review tools

- Hunk 0.18.0 is pinned through its upstream flake and configured as Jujutsu's pager.
- Jujutsu is enabled with the same identity as Git.
- Difftastic is installed from nixpkgs and exposed through `git dft`.
- OpenCode's built-in `general`, `explore`, and `scout` subagents use
  `route/gpt-5.6-luna`; its lightweight internal tasks use the same model.
- OpenCode includes focused `nix` and read-only `review` agents, reusable commands, and the
  Hunk live-review skill.

### Future agent tooling

- Rotate credentials found in old local backup files now that `sops-nix` is integrated.
- Evaluate colocated Jujutsu repositories after learning its change-based workflow.
- Evaluate OpenCode references for shared documentation repositories.
- Evaluate a local Ollama utility model for non-subscription background work.

### IDE: VSCodium

VSCodium is installed and managed through `programs.vscodium`. The default profile is themed by Stylix (wallpaper-generated) and comes with the following extensions:

**Language / dev support**
- rust-analyzer
- nix-ide
- Even Better TOML
- YAML
- Markdown All in One
- ESLint
- Prettier

**Quality of life**
- Error Lens
- Todo Tree
- Better Comments
- Git Graph

**AI**
- Kimi Code (`moonshot-ai.kimi-code`)

### Custom Open VSX extensions

Some extensions are not packaged in nixpkgs, so they are built from VSIX files downloaded from Open VSX:

- `moonshot-ai.kimi-code` 0.5.10
- `mhutchie.git-graph` 1.30.0

The `@` character in the upstream filenames is avoided by renaming the downloads in the `fetchurl` calls.

### Desktop & system defaults

- Firefox forces DuckDuckGo as the default engine, ships a small bookmark set,
  and defines Personal/Work/Shopping containers.
- qutebrowser enables EasyList/EasyPrivacy blocking, saves downloads without a
  prompt, and opens the editor with `footclient -e hx`.
- Thunderbird is managed by `programs.thunderbird` with telemetry off; mail
  accounts are still added manually.
- btop uses vim keys and a 1-second interval.
- System (chi): AppImage `binfmt` support, `nix-index` command-not-found, a
  GNOME pinentry for `gpg-agent`, `gvfs` for portal filesystems, and
  `cloudflared` packaged declaratively (previously a `~/.local/bin` download).

### Backup behavior

`flake.nix` sets `home-manager.backupCommand` to a script that moves any existing dotfiles Home Manager wants to overwrite to `<path>.hm-backup` (then `.hm-backup.1`, `.hm-backup.2`, …), so activation never fails on a pre-existing file.

---

## Post-rebuild manual steps

### Firefox profile cleanup

After the first rebuild with the declarative Firefox profile active, consolidate or remove any old orphaned profile directories under `~/.mozilla/firefox/` on `chi` itself.

### nh flake path

Confirm the `programs.nh.flake` path in `hosts/chi/configuration.nix` matches where this repo is cloned on `chi` (default: `/home/mollyw/nixos`).

### Fonts

ComicShannsMono Nerd Font is set as the system-wide default via Stylix and `modules/common.nix`; Firefox uses Noto fonts instead (see `home/apps.nix`). Point sizes may need tweaking on the real laptop.

## Removed: trenchbroom

The custom `pkgs/trenchbroom` AppImage wrapper was removed from `home/default.nix` because it was untracked and broke flake evaluation. nixpkgs no longer provides `trenchbroom` ("removed due to numerous vulnerabilities in freeimage"), so a replacement needs research before Quake-family level editing is available again.


## Host: misty (Media Server & Storage Vault)

`misty` (`192.168.1.174`) is a dedicated NixOS 26.11 media server, high-capacity storage node, YouTube proxy (`yt.daze.lol`), and LAN TV kiosk host (`https://video.daze.lol`).

- **Hardware**: Xeon E5-1650 v4 (6C/12T), 64 GB DDR4 RAM, Quadro K620 (Maxwell GPU with `nvidiaPackages.legacy_580` for Jellyfin NVENC hardware transcoding).
- **Storage Topology (`disko`)**:
  - `sda` (512 GB SSD): system root `/` & `/boot`.
  - `sdc` (12 TB HDD): `/srv/movies` (Movies & Music libraries + torrent/usenet staging). `/srv/movies/media/music` is bind-mounted to `/srv/music`.
  - `sdb` (12 TB HDD): `/srv/tv` (TV library + torrent/usenet staging).
  - *Hardlink/Instant-Move Architecture*: Isolating TV vs Movies+Music onto independent disks alongside their respective download staging directories allows qBittorrent, Usenet downloadders, and Servarr daemons (`sonarr`, `radarr`, `lidarr`, `bazarr`, `prowlarr`) to execute instant hardlinks/atomic moves without cross-disk copying.
- **Media Stack**: Shared `media` group (`gid 2775`, `umask 0002`). Jellyfin (8096), Navidrome (4533), Seerr (5055), qBittorrent (8080), Sonarr (8989), Radarr (7878), Lidarr (8686), Bazarr (6767), Prowlarr (9696), FileBrowser (8088).
- **Web & Auth**: Invidious (`invidious-oidc`, port 3000) backed by PostgreSQL (5432) and Invidious Companion (Podman container, port 8282). Integrated with `ratlogin` OIDC (`auth.daze.lol`). Secrets managed via `sops-nix` (`secrets/misty.yaml`).
- **Kiosk Display**: Wayland Cage compositor (`cage-tty1.service` under user `tv`) rendering Chromium kiosk mode on DP-1 to `https://video.daze.lol`.

Full details, operational runbook, and diagnostic commands are documented in [`misty.md`](./misty.md).


## Clan private network

Chi, halo, and misty use Clan Mycelium for private traffic. Clan administers halo and misty over Iroh, with Mycelium as the secondary route. See [`NETWORK.md`](./NETWORK.md) for topology, deployment, and recovery commands.