Defined in modules/desktop/niri/bindings.nix. The full table, the two places the grammar deliberately bends, practice mode, and the rules for adding a bind are in modules/desktop/niri/KEYBINDINGS.md. Mod+Alt+P drills them with keydrill, which reads this config at runtime rather than an exported copy.

Then the existing ciphertext is unreadable to you — nobody can re-key a secret they cannot read. Start your own:

# .sops.yaml: replace the gamingpc key with your own recipient, then
rm secrets/home-assistant.yaml
nix run nixpkgs#sops -- secrets/home-assistant.yaml     # opens $EDITOR, writes fresh ciphertext

Put a hass_token: key in it to match what modules/system/sops.nix declares. If you have no Home Assistant at all, delete modules/system/sops.nix and the homeAssistantMonitor block plus the haTokenPath binding in modules/desktop/dms/plugins.nix — both, because plugins.nix reads config.sops.secrets.hass_token.path and removing only the module breaks evaluation.

• modules/system/sops.nix — imports the sops module, sets the sops file and the decryption key (the machine's SSH host key), and declares each secret.
• .sops.yaml — the age recipients allowed to decrypt (creation rules).
• secrets/*.yaml — the encrypted secret files.

The decryption key is /etc/ssh/ssh_host_ed25519_key, converted to age — which is why modules/system/openssh.nix is part of the always-on baseline rather than a suite: sshd is what creates and preserves that key. Get the matching public key (the recipient for .sops.yaml) with:

nix run nixpkgs#ssh-to-age < /etc/ssh/ssh_host_ed25519_key.pub

Add / edit a secret (opens $EDITOR with decrypted content, re-encrypts on save):

just secret secrets/home-assistant.yaml

The recipe exists because sops searches only user key locations (~/.ssh/, ~/.config/sops/age/keys.txt, a few env vars) and so never finds the SSH host key this repo encrypts to — bare sops secrets/home-assistant.yaml fails with "Failed to get the data key required to decrypt the SOPS file". just secret converts /etc/ssh/ssh_host_ed25519_key (root-only, so it asks for sudo) to age and passes it to sops for that one command, without exporting it into your shell. Don't run sops under sudo instead — it works, but rewrites the file as root inside your checkout.

Then declare it and reference the runtime path:

# modules/system/sops.nix
sops.secrets.hass_token = { owner = "otis"; mode = "0400"; };

# consumer, e.g. modules/desktop/dms/plugins.nix
config.sops.secrets.hass_token.path   # => /run/secrets/hass_token

Adding another machine: add its age key to .sops.yaml, then re-encrypt every existing secret to the new recipient list with just updatekeys secrets/home-assistant.yaml (same host-key handling as just secret). To rotate a secret, edit it as above and replace the value — the old ciphertext is overwritten.

Why gaze replaced howdy

Two reasons, both structural:

• The password prompt is no longer blocked. PAM runs auth modules one at a time, in stack order, and howdy sat ahead of pam_unix — so the password field could not even appear until its scan returned, and its timeout had to be cut to 1s to keep that bearable. Gaze ships pam_gaze_grosshack.so, which runs the scan concurrently with the password prompt, the way DMS already races the fingerprint reader against the password. It is used for login and greetd (hardware.gaze.simultaneousServices); sudo and polkit-1 stay sequential, where the scan is short and there is nothing to race.
• Liveness detection, described in the warning above.

It is also a smaller machine: the dlib / face-recognition / Python stack howdy dragged in left the closure along with it (−2.1 GiB).

Inference runs on the NPU

hardware.gaze.device = "npu" on this host. Face detection and recognition are exactly the small fixed-shape CNNs Panther Lake's NPU exists for, and keeping them off the CPU is what makes a scan that races the password prompt cheap enough to run on every unlock, on battery.

The chain that makes this work, none of which needs anything built specially:

• hardware.cpu.intel.npu.enable on the host ships intel-npu-driver and level-zero, and the ivpu kernel driver exposes /dev/accel/accel0.
• nixpkgs' onnxruntime is built with the OpenVINO execution provider (libonnxruntime_providers_openvino.so), and nixpkgs' openvino carries libopenvino_intel_npu_plugin.so.
• the module rebuilds gaze, its CLI and its GUI with the openvino Cargo feature, which the stock packages do not set — without it the daemon has no OpenVINO provider to register and the CLI and GUI only know device = "cpu". That override is hardware.gaze.openvino.enable, implied by any device other than "cpu".
• the module puts level-zero and /run/opengl-driver/lib on gazed's LD_LIBRARY_PATH. OpenVINO's NPU plugin dlopens libze_loader.so.1 by bare name rather than linking it, and the loader then looks for the driver's libze_intel_npu.so; neither is on a system daemon's link path by default, so without this OpenVINO enumerates no NPU at all.

If OpenVINO ever fails to come up, gaze logs the reason and falls back to the ONNX Runtime CPU provider rather than failing the login. Check which one is live with gaze doctor.

The config is declarative, the enrollment is not: face templates are per-machine data under /var/lib/gaze, so they are a post-install step and never live in the repo. The recognition models themselves are downloaded by the daemon into /var/cache/gaze on first use, so the first scan after a fresh install needs network.

1. Find the IR camera

A Windows Hello module enumerates as two V4L2 devices — the colour webcam and the infrared one. Only the IR node works in the dark, which is the whole point.

lsusb                                        # VID:PID of the camera module
v4l2-ctl --list-devices
v4l2-ctl -d /dev/videoN --list-formats-ext   # the IR one is GREY-only
gaze doctor                                  # what gaze itself sees

2. Point the config at it

# hosts/omnibook/default.nix
hardware.gaze = {
  enable = true;
  irDevice = "usb:0408:5494";
  device = "npu";
};

Give it the usb:VVVV:PPPP hex VID:PID from lsusb, not a device node: gaze resolves that to the module's infrared V4L2 node itself, so it survives the /dev/videoN renumbering that happens when another camera is plugged in. A bare /dev/video2 also works.

Then just rebuild.

Leave irDevice unset and gaze authenticates off the colour camera alone (cameras.rgb = "primary", resolved through PipeWire at runtime).

3. Enrol a face

gaze add-face default          # guided multi-angle capture
gaze refine-face default       # add captures: glasses on, glasses off, dim room
gaze list-faces                # what is enrolled
gaze remove-face default       # drop one
gaze auth --verbose            # test a scan without locking anything

No sudo: enrollment goes through the daemon over D-Bus and is authorized by polkit. Lock the session (Super+L) to try it for real — it should unlock on sight, and drop to the password field if it does not recognise you. The GTK4 settings app (hardware.gaze installs it) does the same thing with a preview.

4. If the image is black

Some Windows Hello modules need their IR LEDs kicked on explicitly. Symptom: the device is right, but every frame comes back dark.

hardware.gaze.irEmitter.enable = true;

Turning it off

hardware.gaze.enable = false;

just rebuild, and PAM goes back to password-only immediately. Enrolled templates are left under /var/lib/gaze; gaze clear-user (or deleting the directory) removes them.

modules/desktop/niri/idle.nix runs the shared swayidle timers (lock at 6 min, blank outputs at 10 min, sleep at 15 min idle). hosts/omnibook/default.nix adds the lid-switch and hibernate-delay config. Both key off boot.resumeDevice, which only omnibook sets (swap sized to RAM in hosts/omnibook/hardware.nix) — so on any other host this is all a no-op and idle-suspend stays plain systemctl suspend.

The behaviour:

• Lid close or 15 min idle → systemctl suspend-then-hibernate: sleeps immediately (RAM suspend), then after HibernateDelaySec (30 min) still suspended, wakes briefly to write RAM to swap and hibernate for real.
• On AC power, hibernate is skipped — plain suspend instead, since there's no point burning a resume-from-hibernate on something that's plugged in. Lid switch uses logind's HandleLidSwitchExternalPower; the idle timer has no such built-in, so it greps /sys/class/power_supply/*/online itself before deciding.

Tune the delay or add a battery-percentage cutoff in systemd.sleep.settings.Sleep (hosts/omnibook/default.nix).

The driver side is already correct, and worth stating plainly so it isn't re-debugged: hosts/omnibook/default.nix sets hardware.intelgpu.driver = "xe" (Panther Lake is xe-only — common/gpu/intel from nixos-hardware still defaults to i915, which is wrong here) and vaapiDriver = "intel-media-driver". vainfo reports the iHD driver with H.264/HEVC/VP9/AV1 decode, and GuC, HuC, GSC and DMC firmware all load. Nothing about video decode is broken.

nixos-hardware has no Panther Lake module. As of the current pin, common/cpu/intel/ and common/gpu/intel/ stop at lunar-lake — no panther-lake, and no hp-omnibook under the vendor directories either. That is why the host imports the generic common-cpu-intel + common-pc-laptop{,-ssd} stack and sets the two GPU options by hand. Recheck this after nix flake update nixos-hardware:

ls "$(nix eval --raw --impure --expr \
  '(builtins.getFlake (toString ./.)).inputs.nixos-hardware.outPath')/common/cpu/intel"

If a panther-lake (or hp/omnibook) directory shows up, import it and drop the hand-set hardware.intelgpu block — upstream will keep it more current than we will.

What actually glitches is the Xe3 display engine, in three separate ways.

One feature is disabled by boot.kernelParams in the host file:

xe.enable_psr=0 (Panel Self Refresh) sat alongside it until 2026-08-26, for Timed out waiting PSR idle state, Selective fetch area calculation failed in pipe A and CPU pipe A FIFO underrun — half the screen randomly going black or garbled. It was dropped to retest on zen 7.1.9, because PSR is the display feature that actually saves idle battery and is therefore the one worth reclaiming. If the blackouts return, put the param back; if they don't, the bug was fixed upstream and it can stay gone.

Both are display-engine only: rendering, VA-API decode and the NPU are untouched.

VRR is the third, and is still open. With PSR and DSB handled, the glitches that remain during video playback log as:

[drm] *ERROR* Atomic update failure on pipe A (start=... time 18 us, min 1836, max 1859, ...)
[drm] *ERROR* [CRTC:151:pipe A] VRR push send still pending

The min/max vblank window shifts from one event to the next, which is VRR retiming the frame window; the compositor misses it and the panel shows a stale or black frame. Video is hit hardest because a varying framerate drives VRR hardest. VRR is enabled on eDP-1 — DMS owns ~/.config/niri/dms/outputs.kdl, so toggle it in the DMS settings UI, not in Nix. niri's variable-refresh-rate on-demand is a middle option, but on-demand activates on fullscreen video, which is precisely the case that glitches. Note that VRR is a poor battery trade here regardless: PSR saves real power, and simply running the panel at 60Hz instead of 120Hz saves more than VRR ever does.

These are workarounds for driver bugs, not permanent settings. After a kernel bump, drop one param at a time, reboot, use the machine for a while, and count:

# `command` bypasses the grep -> rg alias set in modules/apps/fish.nix —
# ripgrep reads -E as --encoding and errors out on this pattern.
journalctl -k -b | command grep -cE "DSB 0 poll error|PSR idle state|FIFO underrun"

Zero means the fix landed upstream and the param can stay gone. Anything else, put it back.

modules/services/rclone.nix turns every entry of services.rclone.remotes into its own rclone-<name>.service:

# hosts/gamingpc/default.nix
services.rclone = {
  enable = true;
  remotes.gdrive_personal = { };   # mounts gdrive_personal: at ~/Cloud/gdrive_personal
};

Adding a Google Drive

1. Make your own OAuth client id (recommended — the id built into rclone is shared by every rclone user on earth and heavily rate-limited): rclone.org → making your own client id.

2. Authenticate. Interactive, once per machine — this is the part that cannot be declarative:

   rclone config
   

   n (new remote) → name it (e.g. gdrive_personal) → storage drive → paste client_id + client_secret → scope 1 (full access) → leave root_folder_id / service_account_file empty → n (no advanced config) → y to open a browser and sign in → n (not a shared drive) → q. Full walkthrough: rclone.org/drive.

3. Declare it under services.rclone.remotes in hosts/<host>/default.nix, using the same name, then just rebuild.

The mount comes up during the rebuild and at every login afterwards. rclone listremotes shows the names rclone knows about — they must match the attribute names.

Everyday use

Options

The default flags worth knowing: --vfs-cache-mode=full means files are cached on disk, so editing in place behaves like a local disk (capped at 5G / 24h), and --dir-cache-time=1000h is paired with --poll-interval=15s — Drive supports change polling, so an effectively infinite directory cache still notices changes made from your phone or the web UI within seconds.

Troubleshooting

modules/services/nas.nix turns each entry of services.nas.shares into a fileSystems entry:

# hosts/<host>/default.nix
services.nas = {
  enable = true;
  server = "192.168.68.148";
  shares = [ "backup" "shared" "media" ];   # => /mnt/nas/backup, …
};

The mounts are noauto + x-systemd.automount: systemd creates the mount point and only runs mount.cifs when something first touches the path. Boot never waits on the NAS, so a laptop away from the home network still boots normally and the mount simply happens once it is back. An idle mount is released again after 10 minutes.

Credentials

secrets/nas.yaml holds one key, nas_credentials, whose value is a mount.cifs credentials file:

just secret secrets/nas.yaml

nas_credentials: |
  username=<smb user>
  password=<smb password>

just secret is what hands sops the decryption key — plain sops secrets/nas.yaml fails with "Failed to get the data key required to decrypt the SOPS file", because sops never looks at the SSH host key this repo encrypts to. See Secrets (sops).

sops-nix decrypts it to /run/secrets/nas_credentials (tmpfs, root-only) and the mount options point credentials= at that path, so the password is never in the nix store, in /etc/fstab, or in git as plaintext.

Everyday use

Files show up owned by otis (uid=1000,gid=100) — SMB carries no usable Unix ownership here, so it is fixed at mount time.

The module also adds a GTK bookmark per share, so they show up in the Nautilus sidebar next to the XDG folders from modules/desktop/xdg.nix. That is the part that has to be declared: gio auto-displays mounts only under /media, /run/media/$USER or $HOME, and the fstab flag that would force it (x-gvfs-show) is read only by GVFS's udisks2 monitor, which handles block devices — a //host/share device is invisible to it. A bookmark works even while the share is idle-unmounted: opening it touches the path, which triggers the automount. Restart the file manager (nautilus -q) after a rebuild that changes the bookmark list.

Options

modules/services/printing.nix is enabled for every host through suites.core (services.printing-cups.enable = true;). It turns on:

services.printing.enable = true;   # CUPS
services.avahi = {
  enable = true;
  nssmdns4 = true;      # resolve .local mDNS names
  openFirewall = true;  # let mDNS/IPP discovery broadcasts through
};

Everyday use

Add a printer with system-config-printer (in every host's packages) or the CUPS web UI at http://localhost:631. A driverless/AirPrint/IPP-Everywhere printer on the same LAN should just appear in the discovery list — no driver to pick.

lpstat -p lists configured printers; lpq / lpq -P <name> shows the queue.

Vendor drivers

If a printer isn't driverless-capable and needs a vendor driver (older HP/Brother/Epson models), add the driver package to drivers in modules/services/printing.nix:

services.printing.drivers = [ pkgs.hplip ];   # example: HP

Options

Enabled by suites.ai.enable.

Everyday use

ccl                            pick a model interactively, then launch
ccl <model-id>                 launch with a specific model
ccl --list                     list selectable models and exit
ccl --print-config <model-id>  print the router config without writing it
ccl <model-id> -- --version    pass everything after -- to claude
ccl -h                         usage summary

Start LM Studio and load a model first — ccl only lists what LM Studio reports.

The router runs detached from ccl and from your shell: once started it keeps serving in the background, surviving Ctrl-C, closing the terminal, and quitting Claude Code. Relaunching ccl with the same model reuses it instantly; a different model restarts it. It only stops when you run ccr stop, or at logout.

Options

ccl owns ~/.claude-code-router/config.json and rewrites it on every launch. A config it did not write is preserved once as config.json.pre-ccl.

Troubleshooting

"LM Studio is not answering" — LM Studio's local server is off. Developer tab → Status: Running.

Context warning at launch — the model was loaded with too small a context window. Claude Code's system prompt and tool definitions alone exceed a few thousand tokens. Raise "Context Length" in the model's settings in LM Studio and reload it.

"the router never became healthy" — something else holds port 4141, or the router rejected the config. The message includes the tail of the router's log.

Picked a ○ not-loaded model and Claude Code hangs — LM Studio loads it on the first request, which can take minutes for a large model. ccl says so at launch; wait it out, or load the model in LM Studio before starting.

A not-loaded model still ran out of context — for those, ccl can only see the model's ceiling (max_context_length), not the context LM Studio will actually load it with, so the context warning can stay silent and the session fail anyway. Load the model in LM Studio first and ccl --list will show its real context.

Malformed tool calls, or the session derails — expected with small quantised models. Claude Code leans hard on well-formed tool calls; a 3-bit quant will not always produce them. This is the model, not ccl.

The VM does not run at boot. That is deliberate: it costs ~4 GB of RAM and a steady slice of CPU, which on the laptop is a battery bill for something used a few times a week. Start it from Mod+Space → Windows → Start VM, or:

systemctl start docker-windows

The submenu's first row is a live readout — Stopped, or Running · CPU 4% · RAM 2.1GiB — sampled when you open the menu. Start and Stop are one button: only whichever one currently does something is on screen.

First boot, once per machine

Everything after just rebuild is unattended, but it is slow and it needs one interactive step at the end. In order:

1. Read your Windows password before you need it. It was generated during setup and you have never seen it:

   sops -d secrets/winapps.yaml
   

2. Start the VM — Mod+Space → Windows → Start VM, or systemctl start docker-windows. Neither prompts for a password; a polkit rule grants exactly start and stop on exactly this unit to wheel.

3. Wait 20–40 minutes, watching the Web Console (http://127.0.0.1:8006). Windows installs itself from a generated answer file, then Office 365 installs from Microsoft's Deployment Tool. Nothing needs clicking during this.

4. Sign in to Office once. In that same browser viewer, open Word and sign in with your Microsoft 365 account. The activation lives in the VM's disk at /var/lib/winapps/storage and survives every restart after this.

   The guest itself is unactivated Windows — a Microsoft 365 sign-in licenses Office, not Windows. Expect a desktop watermark and locked personalization settings. RDP and Office both work fine regardless.

5. Launch Word from Linux. It is a normal application now: hit Mod+Space, type word, press enter. Double-clicking a .docx in Nautilus opens it too. The VM must be running; if it is not, WinApps says so with a notification rather than failing silently.

If Office is missing when the install finishes, look for C:\OfficeSetup\FAILED.txt in the guest — the script writes it on both a failed download and a failed install. C:\OEM\install.bat is re-runnable by hand.

Day to day

Start and stop from the Windows submenu. The applications themselves are ordinary launcher entries, so they are not repeated in that submenu — it owns the VM's lifecycle, nothing else:

On-Demand is a toggle. With it on, opening Word starts the VM and waits for it (with a notification, since a cold boot takes the better part of a minute), and the VM stops itself once no Office window has been open for services.winapps.idleTimeout minutes — 15 by default. With it off the VM is yours to start and stop from the two rows above; the idle watcher will not touch a VM you started by hand.

Idle is counted in consecutive one-minute checks rather than wall-clock, so closing the lid for three hours does not mean the VM is killed the moment you open it again.

The figures come from labelCmd, a condition kind added to dankMenu for this: unlike when/checked/disabled, which are judged by exit status, its stdout replaces the row's label. That is the only way to get a changing number into a menu whose tree is a static file.

All of the VM's notifications are low urgency — starting, up, stopping, off. They are status, not decisions, so they should not interrupt a fullscreen window.

Full Desktop vs Web Console. Full Desktop is the everyday one — the whole Windows desktop over RDP, fast and integrated. The Web Console is dockur's HTTP view of the guest's actual screen; it is slower and clunkier, and it is the only way in when RDP is not answering: during first boot, or afterwards if Windows breaks in a way that takes RDP down with it.

There is no bar widget. dockerManager is installed but disabled (modules/desktop/dms/plugins.nix) — the VM is off most of the time, so a permanent widget would spend its life showing nothing.

Battery. This is a full VM, not a container in the Linux sense: QEMU with KVM running a real Windows 11. Idle Windows is never really idle — Defender, Search indexing, and Update all tick over — so the host CPU never settles into its deep idle states, and the 4 GB is gone for as long as the VM is up. On the laptop, expect a noticeable dent in battery life. Nothing suspends it automatically: WinApps has an AUTOPAUSE feature, but it only works under its libvirt backend, and this setup uses WAFLAVOR="manual" precisely so that WinApps never touches the VM's lifecycle. Stop it when you are done — that is what the menu row is for. On gamingpc (8 GB, 6 cores, wall power) leaving it running is fine.

Your files. The home directory is redirected into the RDP session (services.winapps.rdpFlags), so it appears in Windows Explorer under "This PC" as a drive whenever an app is open. Nothing is copied and there is no share to mount. There used to be a second path in — a ~/Windows folder bind-mounted as \\host.lan\Data — and it was removed: one way in is enough, and two only raised the question of which folder a given file was supposed to be in.

Scaling. services.winapps.rdpScale must match the output scale the windows land on, or Windows renders 1:1 and Office text comes out tiny beside everything else. FreeRDP only accepts 100, 140 or 180; omnibook's panel is niri scale 1.75, so it is set to 180 in its host file.

Disk. The default is 32G, and it is a ceiling rather than a reservation — the image is sparse and only consumes what Windows has written. Raising it later is easy (dockur grows the disk on the next boot); lowering it means deleting /var/lib/winapps/storage and reinstalling. omnibook is pinned at 64G because its VM was built before the default changed.

Adding an application — add it to services.winapps.apps in the host file. The id must name a directory in WinApps' own list:

ls "$(nix build --no-link --print-out-paths 'github:winapps-org/winapps#winapps')/src/apps"

A wrong id fails the build rather than producing a launcher that does nothing — the entry's name, icon and MIME associations are read out of WinApps' own definition for that id at build time, so nothing is hand-maintained here.

Ports are loopback-only (127.0.0.1:3389 and 127.0.0.1:8006). Do not drop those prefixes — the VM has an RDP host with a fixed password, and Docker's default would publish it on every network the laptop joins.

Enabled by suites.media. The module is the whole feature — package wrapper, config.toml, the sops secret and the two niri bits.

The config

~/.config/cliamp/config.toml is written by an activation script, not symlinked. cliamp rewrites that file itself every time you toggle shuffle or repeat, pick a theme, cycle the visualiser or save an EQ curve, so a read-only store symlink would either break those writes or be silently replaced by a real file. Instead the file is installed writable (0600) on every rebuild: your runtime toggles hold until the next just rebuild, then the Nix values win again. It is one of the files in CLAUDE.md's "this repo owns them" list.

What it sets:

Spotify

The [spotify] section is what registers the provider at all; client_id only swaps cliamp's built-in fallback (the librespot keymaster ID, whose rate-limit quota is shared with every librespot client) for our own developer app. Playback needs Spotify Premium.

The ID lives in secrets/cliamp.yaml as cliamp_spotify_client_id, never in the store. cliamp expands a value of exactly "${NAME}" from the environment, so the config file only ever contains client_id = "${CLIAMP_SPOTIFY_CLIENT_ID}" and a makeWrapper wrapper exports that variable from /run/secrets/… at launch. If the secret is missing the expansion yields "" and cliamp falls back to the built-in ID — degraded, not broken.

To register your own app (just secret secrets/cliamp.yaml to store the result):

1. Go to developer.spotify.com/dashboard and sign in.
2. Create app, give it a name (cliamp) and a description.
3. Add http://127.0.0.1:19872/login as a Redirect URI.
4. Tick Web API under "Which API/SDKs are you planning to use?".
5. Save, then copy the Client ID out of the app's Settings.

First sign-in happens in the browser and completes two steps in one tab: the Web API grant for library/playlist/search, and Spotify's own identity for playback.

The binds

Mod+Alt+C — the "run a tool" plane. Its sibling Mod+Alt+F does the same for Spotify (modules/apps/spotify.nix). Both just launch: no workspace switching or pinning, the window opens floating wherever you currently are.

cliamp opens floating and centred at 60% × 60%, Spotify at 75% × 80% — it is a full GUI client with a sidebar, not a 24-row TUI.

cliamp's window rule matches on com.mitchellh.ghostty.cliamp, an app-id the bind sets with ghostty's --class so it never catches an ordinary terminal.

Also installed

pactl (from pulseaudio). cliamp's audio-device picker shells out to it — nothing else on this system did, since the niri volume binds deliberately use wpctl. pipewire-pulse answers pactl fine; only the client binary was missing.

The obvious approach — pkgs.anki.withAddons — was rejected. It replaces addons21 wholesale via ANKI_ADDONS, which makes every addon read-only in the store and breaks Anki's own "save config" flow. So instead a home-manager activation script deploys into the real folder:

• Code is rsynced from the store on every activation, so a rebuild is what updates an addon.
• meta.json and user_files/ are excluded from that rsync. Once they exist, Anki owns them — anything you change in the addon's GUI config sticks.
• First install only, a captured config from _lib/seeds/<id>.json is written as the initial meta.json.

Three things override that "leave it alone" rule on purpose:

Layout

modules/apps/anki/
  default.nix        the module: apps.anki.enable, sops secrets, activation
  _lib/
    default.nix      addon set + mkActivationScript
    fetched/         addons built from upstream sources, with patches
    vendored/        addons committed here (forks, or ones with no clean source)
    seeds/           captured first-install meta.json config per addon id
    recolor-schema.json   ReColor's shipped labels / light values / css vars

_lib is not a typo — import-tree skips any path containing /_, so the addon tree lives beside its module without being loaded as one.

Adding an addon

From upstream — add it to _lib/fetched/default.nix with its source and, if needed, a patch under _lib/fetched/patches/.

Vendored — drop the addon folder into _lib/vendored/<ankiweb-id>/ and add that id to vendoredIds in _lib/default.nix. The id only has to be unique; advanced_deck_maker and efficiency_tracker are locally-written addons whose "id" is just a name.

With a config you want as the default — install it, configure it in the GUI, then copy the config object out of its meta.json into _lib/seeds/<id>.json and add the id to seededIds.

Helium is a Chromium fork, so extensions can be installed by policy rather than by hand: ExtensionSettings in /etc/chromium/policies/ names each extension id, its update URL and whether it gets a toolbar button, and the browser acts on that at startup. That is what makes the extension set reproducible — the set, the pinning and the absence of anything removed all travel with the flake instead of with ~/.config/net.imput.helium.

Four things had to be solved to get there, and each is worth knowing before touching this module:

• The packaging matters. This uses oxcl/nix-flake-helium-browser, which repacks the official .deb with patchelf. The previous input (FKouhai/helium2nix) ran an AppImage inside bwrap and never bound /etc/chromium, so policies could not reach the browser at all — no policies, no declarative extensions.
• Naming any id blocks every id you did not name. The earlier ExtensionInstallForcelist approach combined with a blocklist in a way that blocked everything else, manually-installed extensions included. The fix is the "*".installation_mode = "allowed" catch-all: the declared set is a floor, not a whitelist.
• The update endpoint needs a patched prodversion. Google's update service rejects Helium's version string, so update-proxy.py sits in front of it and rewrites prodversion to a Chrome version the endpoint accepts. Without it every extension update 400s.
• Deleting an id does not uninstall the extension. Because the catch-all is allowed, an extension already sitting in the profile from an earlier generation just stops being managed and keeps running. removedExtensions exists for this: it maps ids to installation_mode = "removed", the only mode that actually uninstalls and blocks a reinstall. Ids stay listed there for as long as any profile might still carry them.

Two smaller things the module decides:

• Pinning is declarative. pin = true on an entry emits toolbar_pin = "force_pinned". Only the extensions worth a one-click button get it; everything else is left at Chromium's default, which is unpinned but still pinnable by hand.
• uBlock Origin comes from the Web Store, not from Helium. Helium ships its own compiled-in uBO with its own fork of the filter lists, and neither a policy nor a pref can turn it off — only the Settings → Services → uBlock switch, which has to be flipped by hand once per profile. Leaving both on gives every page two element pickers and two sets of cosmetic filters.

Policies are read at startup, so a rebuild is not enough: quit Helium completely and reopen it before concluding a change did not apply.

userscripts/ holds page scripts loaded through the extension set rather than through any Nix mechanism — they are data for a userscript manager.

Enabled by suites.development. The design notes are in docs/design/specs/2026-08-05-android-adb-scrcpy-design.md.

Pair the phone once (Developer options → Wireless debugging → Pair device with pairing code):

adb pair <phone-ip>:<pairing-port>
adb connect <phone-ip>:<port>
scrcpy

After that the wireless auto-connect handles reconnection, so scrcpy on its own is usually enough.

Claude Code normally clones plugin marketplaces into ~/.claude/plugins and updates them on its own schedule. This module writes that tree from Nix instead, which means the plugin set is reproducible and moves only when you say so.

Each marketplace is a flake = false input holding a .claude-plugin/marketplace.json:

Two plugins need their own pins because the official marketplace only points at them ({"source":"url"} entries naming another repo, so the marketplace tree does not contain them): claude-plugin-superpowers and claude-plugin-figma.

Bump one with nix flake update <input-name>, then just rebuild.

House rules for the agent

CLAUDE.md at the repo root carries the conventions for working on this flake — one file per feature, the namespace/directory mapping, when a module becomes a directory, what _-prefixed directories are for, which files this repo owns that applications also try to write, and the verification gates.

Claude Code loads it automatically in any session whose working directory is this repo. That is the point: these are rules that only help at the moment you would otherwise break one, so they need to be present unconditionally rather than discovered. It started as a /sitolamix skill pinned into the plugin set above, which was strictly worse — a skill has to match before it loads, and a silent miss gives you exactly the mistake it existed to prevent.

ccl (§ Local models) execs ccr code, which launches claude — so those sessions get this same pinned set.