docs: add ROADMAP.md + SCRIPTS.md, retire TODO.md

ROADMAP.md is the durable mid-term plan: vision, guardrails, Now/Next/
Later board, and seven pillars (audit, installer, power/presets,
onboarding/docs, test/CI/release, process). SCRIPTS.md is the
scaffolding for the Pillar 3 script & menu audit — methodology,
generator commands, and a snapshot of currently orphaned callers.

The two open items in TODO.md (software-profile multi-select, richer
disk metadata) move into the roadmap's Now column; the rest of TODO.md
was already shipped, so the file is removed.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/ROADMAP.md

@@ -0,0 +1,134 @@
+# Nomarchy Roadmap
+
+This is the mid-term plan for Nomarchy. It exists so future sessions — human or agent — can pick up work without re-deriving context. Items move from **Now** → **Next** → **Later** as priorities shift, and from any column into **Shipped** at the bottom when done. There are no dates: ship-when-ready.
+
+If you're new here, also read [`docs/STRUCTURE.md`](STRUCTURE.md) and [`docs/OPTIONS.md`](OPTIONS.md). Existing-NixOS users should also read [`MIGRATION.md`](../MIGRATION.md).
+
+## 1. Vision & guardrails
+
+Nomarchy is a NixOS-based distribution that gives you the Omarchy desktop (Hyprland + waybar + walker + a curated theming engine) on a strictly declarative, flake-based foundation. Goal: power-user polish without giving up reproducibility.
+
+Guardrails (apply when adding anything):
+
+- **Declarative-first.** No imperative state in `core/`. Anything mutable lives in `~/.config/nomarchy/state.json` or in NixOS options.
+- **Downstream-flake friendly.** Every behavior toggle is a `nomarchy.*` option documented in `docs/OPTIONS.md`. Adding a feature without a corresponding option is a bug.
+- **Opt-in by default.** New features default off (or default to the existing behavior). The installer can flip defaults for the user, but the option must read sensibly when set by hand.
+- **Reuse before invent.** Before adding a script, grep `core/system/scripts/`, `features/scripts/utils/`, and `themes/engine/scripts/` — there are ~155 of them, and many of the things you want already exist.
+
+## 2. Now / Next / Later board
+
+### Now (ready to pick up)
+
+- **Software-profile multi-select in the installer.** Carryover from the old TODO. Add a `gum choose --no-limit` step in `installer/install.sh` (between hardware and impermanence) for opt-in profiles (Dev, Gaming, Office, Media, …). Each profile maps to a list of `home.packages` and optional `nomarchy.system.*` toggles emitted into the generated `home.nix`/`system.nix`.
+- **Richer disk metadata.** Carryover from the old TODO. Replace the bare `lsblk` line in `select_disk` with `lsblk -O -J` parsed via `jq`, surfacing vendor, model, serial, and size in the picker.
+- **Menu cleanup of orphaned references.** Walk `features/scripts/utils/nomarchy-menu` (379 lines, 23 submenus) and either wire each menu item to a real script or replace the `case` arm with a stubbed `notify-send` until the script is ported. See Pillar 3 below.
+- **Form-factor → laptop preset auto-enable.** When the installer writes `nomarchy.system.formFactor = "laptop"`, also flip on a yet-to-be-built laptop preset (TLP, brightness keys, lid handling). The option exists; the preset module doesn't.
+- **`docs/KEYBINDINGS.md`.** Auto-generate from the `bindd =` lines in `core/home/config/nomarchy/default/hypr/bindings/*.conf` and `features/desktop/hyprland/config/bindings.conf` so the README's keybinding table stops drifting from the source of truth.
+
+### Next (bigger lifts that build on Now)
+
+- **Laptop preset module** (`core/system/laptop.nix`). Gated on `formFactor = "laptop"`. Wires TLP defaults, `services.upower`, `services.thermald` where applicable, brightness key handlers, and a sane logind lid-switch policy that defers to `nomarchy.system.hibernation.enable`.
+- **Desktop preset module.** CPU governor `performance` by default, no battery widget (already done), ZFS-friendly defaults for users who later add a pool.
+- **Accessibility preset.** Larger cursor, slower key-repeat defaults, `services.orca`, screen reader keybinding, high-contrast theme variant.
+- **Gaming preset.** `programs.steam.enable`, `programs.gamemode.enable`, `services.flatpak.enable` with a curated remote, and a Hyprland window-rule to fullscreen Steam-launched apps.
+- **First-run welcome wizard.** Extend `nomarchy-welcome` from a one-shot greeter into a guided picker: theme, panel position, monospace font, "what's a sane home.nix to start with?". Runs once, persists "done" in `state.json`.
+- **Plymouth theme variants per palette.** Currently one Plymouth theme; could template per-palette so the boot splash matches the active theme.
+- **`docs/TROUBLESHOOTING.md`.** The five most common rebuild errors (`option ... already declared`, `attribute ... missing`, Stylix target conflicts, home-manager backupFileExtension churn, impermanence path missing) with copy-paste fixes.
+- **Installer pre-flight resume polish.** If the user Ctrl-Cs mid-install and runs `--resume`, re-show the review screen before re-prompting for any unsaved fields.
+
+### Later (speculative or research-shaped)
+
+- **Declarative-state migration.** Move the bits of `state.json` that don't actually need runtime mutability (theme, font, isLightMode) into NixOS / home-manager options, leaving only genuinely runtime-only state behind. Reduces the "two sources of truth" surface.
+- **Rolling vs pinned channel choice in the installer.** Today the generated flake pins `nomarchy` to a rev. Offer a "rolling" option that follows `main` and a `nomarchy-rollback` helper for stuck rebuilds.
+- **Theme creation wizard.** A `nomarchy-theme-new` script that scaffolds a new palette from a base16 hex set (or by sampling a wallpaper), runs `nomarchy-themes-prebuild`, and opens a PR template.
+- **CI matrix on Forgejo Actions.** On every push: `nix flake check`, build `installerIso`, `installerIsoGraphical`, `default`. On tag: publish ISOs as release artefacts.
+- **Golden-image VM tests per palette.** A `nixosTest` per palette that boots the `default` config, takes a screenshot, and diffs against a golden image. Catches Stylix regressions before they hit users.
+- **Forgejo release pipeline.** `vYY.MM.x` tags matching the upstream NixOS channel; the pipeline pushes the three ISOs and an updated `flake.lock` snapshot.
+- **Optional `nomarchy-installer-vm`** rebuilt as a real flake app (not a one-off shell script) so users can install Nomarchy into a libvirt VM declaratively.
+- **Surface support module** via the relevant `nixos-hardware` profile + Surface kernel patches behind a `nomarchy.hardware.isSurface` toggle.
+
+## 3. Pillar: Script & menu audit
+
+Nomarchy ships **~155** `nomarchy-*` scripts across three directories, plus a 379-line `nomarchy-menu` with 23 submenu functions. Some are first-class Nomarchy work; some are direct Omarchy ports that haven't been adapted; some are dangling references the menu calls but no script implements (e.g. `nomarchy-backup`, `nomarchy-debug`, `nomarchy-pkg`, `nomarchy-pkg-aur-add`, `nomarchy-plymouth`, `nomarchy-refresh-hyprland`, `nomarchy-reinstall`, `nomarchy-rollback`, `nomarchy-screenrecord-filename`, `nomarchy-theme`, `nomarchy-update-firmware`, `nomarchy-upload-log`, `nomarchy-version`, `nomarchy-wallpaper`, `nomarchy-skill`, `nomarchy-luks`).
+
+This pillar fixes that. It runs as two phases.
+
+### Phase A — Inventory & triage
+
+Lands as a single PR. Output is `docs/SCRIPTS.md` populated with rows for every script and every menu item.
+
+1. Run a generator (one-shot helper, doesn't have to be checked in) that produces three lists:
+   - All `nomarchy-*` scripts under `core/system/scripts/`, `features/scripts/utils/`, `themes/engine/scripts/`.
+   - All `nomarchy-*` *callers* (grep `core/`, `features/`, `themes/`, `installer/`, `bin/`).
+   - The set difference (orphaned callers ↔ unreferenced scripts).
+2. Walk `features/scripts/utils/nomarchy-menu` and list every menu entry with its target script.
+3. Tag each row with a status:
+   - `kept` — works on Nomarchy, no change needed.
+   - `port-from-omarchy` — exists upstream, needs adapting (drop pacman/yay/AUR, repath to NixOS, talk to `nomarchy.system.*` options).
+   - `delete-dead` — neither used nor needed; remove and update callers.
+   - `stub-with-notify` — temporarily replace with a `notify-send "Not yet implemented in Nomarchy"` so the menu stops looking broken until the work is scheduled.
+   - `unknown` — needs a deeper look before tagging.
+4. The completed table lives at [`docs/SCRIPTS.md`](SCRIPTS.md). The roadmap links to it; this section just sets the methodology.
+
+### Phase B — Adapt or remove
+
+Lands as PR batches of ~10 scripts each, branch named `wave/audit-<batch>`. Per script:
+
+- For `port-from-omarchy`: rewrite the script for Nomarchy paths (`/etc/nixos`, `nixos-rebuild`, `home-manager`, no Arch idioms), wire it into `nomarchy.system.*` where applicable, and update every caller (menu, waybar, keybindings).
+- For `delete-dead`: `git rm` the script *and* fix every caller — a `find` + `sed` pass against `nomarchy-menu`, every `*.conf`, and every nix file.
+- For `stub-with-notify`: write the one-liner stub in place. The roadmap row stays open until the real implementation lands.
+
+Each PR description should reference the row(s) in `docs/SCRIPTS.md` it closes, and reviewers spot-check that no caller still points at a stale name.
+
+## 4. Pillar: Installer
+
+- Software-profile multi-select (Now).
+- Richer disk metadata (Now).
+- Form-factor → laptop preset (Now, depends on Pillar 5).
+- `disko-golden.nix` variants for software-RAID and BTRFS-pool-as-root.
+- Pre-flight resume polish (Next).
+- "What's installed?" summary screen on boot of a freshly-installed system, sourced from `state.json` + `nomarchy-system-scripts` introspection.
+- Optional non-LUKS branch in the installer for users who explicitly opt out of FDE.
+
+## 5. Pillar: Power, hardware, presets
+
+- Laptop preset (Next): TLP, upower, brightness, lid, hypridle tuning.
+- Desktop preset (Next): performance governor, no laptop UI (already filtered), ZFS hooks.
+- Accessibility preset (Next).
+- Gaming preset (Next).
+- Vendor matchers in `installer/hardware-db.sh`: Steam Deck, Surface, ROG Ally, Snapdragon X laptops.
+- Surface support behind `nomarchy.hardware.isSurface` (Later).
+- Auto-detect dGPU presence and offer `programs.envycontrol`-style switching for the hybrid case (already gated behind `nomarchy.system.features.hybridGPU`, but the wiring is minimal).
+
+## 6. Pillar: Onboarding & docs
+
+- `nomarchy-welcome` first-run wizard (Next).
+- `docs/KEYBINDINGS.md` auto-generator (Now).
+- `docs/TROUBLESHOOTING.md` (Next).
+- `docs/index.md` (or just enrich `README.md`) so `OPTIONS.md`, `STRUCTURE.md`, `MIGRATION.md`, `ROADMAP.md`, `SCRIPTS.md`, and `creating-themes.md` are all one click from the front page.
+- `nomarchy-manual` — orphaned reference today; either implement as a curated `xdg-open` to the docs index, or delete.
+
+## 7. Pillar: Test, CI, release
+
+- Forgejo Actions workflow:
+  - on every push to `main`: `nix flake check` (≈ what we run by hand today).
+  - on every PR: also build all three ISOs (cache hit on most of them).
+  - on tag `vYY.MM.x`: publish ISOs as release artefacts.
+- Versioning scheme: `vYY.MM.x` matching the upstream NixOS channel (e.g. `v25.11.3`).
+- `nixosTest` per palette: boots `default` in a VM, screenshots the SDDM splash and the Hyprland desktop, diffs vs golden. Failure surfaces as CI red.
+- A small `bin/utils/nomarchy-bench-iso-build` that records ISO build time + size into a per-commit JSON so we notice regressions.
+
+## 8. Process notes
+
+- **Branch naming:** `wave/<pillar>-<short-slug>`. Examples: `wave/audit-pkg-scripts`, `wave/installer-disk-metadata`, `wave/laptop-preset`.
+- **One PR per audit batch.** Reference rows in `docs/SCRIPTS.md`. Smaller PRs review faster.
+- **Living roadmap.** When an item ships, move it to the **Shipped** section at the bottom of this file rather than deleting it. Future-us gets a free changelog.
+- **Plan files live separately.** Detailed implementation plans (the per-feature design docs Claude writes in plan mode) belong under `~/.claude/plans/` per session, not in the repo. The roadmap is the durable reference; plan files are working notes.
+- **Don't widen scope mid-PR.** If the audit reveals a missing feature, file a new roadmap row, don't graft it onto the current PR.
+
+## Shipped
+
+(Move items here when they land — keep them brief, link the commit/PR.)
+
+- _2026-04-25_ — Installer prompts for keyboard layout + locale, applies live; new `nomarchy.{system,}.formFactor` option; waybar drops battery widget on desktop; nm-applet visibility fix in default theme; live-ISO baseline keymap/locale (`a7e7fa9`).
+- _2026-04-25_ — `docs/OPTIONS.md` reference; `MIGRATION.md` linked from `README.md` (`3cb012b`, `6ef28f0`).

docs/SCRIPTS.md

@@ -0,0 +1,84 @@
+# Nomarchy Script & Menu Audit
+
+This is the working table for [Pillar 3 of the roadmap](ROADMAP.md#3-pillar-script--menu-audit). It catalogues every `nomarchy-*` script, its callers, and an action tag.
+
+> **Status as of writing:** scaffolding only. Phase A (the inventory PR) has not yet populated this table — see the roadmap for the methodology. Add rows as you triage.
+
+## Status legend
+
+- `kept` — works on Nomarchy, no change needed.
+- `port-from-omarchy` — exists upstream, needs adapting (drop pacman/yay/AUR, repath to NixOS, talk to `nomarchy.system.*` options).
+- `delete-dead` — neither used nor needed; remove and update callers.
+- `stub-with-notify` — temporarily replaced with a `notify-send "Not yet implemented in Nomarchy"` until real work is scheduled.
+- `unknown` — needs a deeper look.
+
+## Generating the inventory
+
+The triage PR should regenerate this table by running these commands in repo root:
+
+```bash
+# 1. all nomarchy-* scripts
+find core/system/scripts features/scripts/utils themes/engine/scripts \
+  -type f -name 'nomarchy-*' -printf '%f\t%h\n' | sort
+
+# 2. all nomarchy-* callers
+grep -rohE 'nomarchy-[a-z][a-z0-9-]*' core/ features/ themes/ installer/ bin/ \
+  | sort -u
+
+# 3. orphaned callers (in code but no script)
+comm -23 <(grep -rohE 'nomarchy-[a-z][a-z0-9-]*' core/ features/ themes/ installer/ bin/ | sort -u) \
+        <(find core/system/scripts features/scripts/utils themes/engine/scripts \
+            -type f -name 'nomarchy-*' -printf '%f\n' | sort -u)
+```
+
+## Scripts
+
+| Script | Location | Used by | Status | Notes |
+| --- | --- | --- | --- | --- |
+| _(rows go here — Phase A populates this section)_ |  |  | `unknown` |  |
+
+## Menu items (`features/scripts/utils/nomarchy-menu`)
+
+The menu has 23 `show_*_menu` functions. List each entry with its target script and tag whether it's wired, broken, or an Omarchy leftover.
+
+| Submenu | Entry | Calls | Status | Notes |
+| --- | --- | --- | --- | --- |
+| _(rows go here — Phase A populates this section)_ |  |  | `unknown` |  |
+
+## Known orphans (snapshot at audit kickoff)
+
+These appear as callers in code but have no matching script today. Each needs triage:
+
+- `nomarchy-backup`
+- `nomarchy-debug`
+- `nomarchy-dryrun`
+- `nomarchy-font`
+- `nomarchy-font-selector`
+- `nomarchy-install`
+- `nomarchy-install-docker-dbs`
+- `nomarchy-installer-vm`
+- `nomarchy-luks`
+- `nomarchy-manual`
+- `nomarchy-pkg`
+- `nomarchy-pkg-aur-add`
+- `nomarchy-pkg-drop`
+- `nomarchy-pkg-install`
+- `nomarchy-plymouth`
+- `nomarchy-refresh-hyprland`
+- `nomarchy-refresh-waybar`
+- `nomarchy-reinstall`
+- `nomarchy-rollback`
+- `nomarchy-screenrecord-filename`
+- `nomarchy-sddm-theme`
+- `nomarchy-skill`
+- `nomarchy-theme`
+- `nomarchy-theme-next`
+- `nomarchy-theme-selector`
+- `nomarchy-themes-no-images`
+- `nomarchy-update-firmware`
+- `nomarchy-upload-log`
+- `nomarchy-version`
+- `nomarchy-vm`
+- `nomarchy-wallpaper`
+
+(Re-run the generator to refresh this list before each audit batch — the snapshot above is from `2026-04-25`.)