From 2950dd171ec316209863c1d1ed1f4e3d7024ccc0 Mon Sep 17 00:00:00 2001 From: Bernardo Magri Date: Sat, 25 Apr 2026 21:35:28 +0100 Subject: [PATCH] docs: add ROADMAP.md + SCRIPTS.md, retire TODO.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 2 +- TODO.md | 30 ----------- docs/ROADMAP.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/SCRIPTS.md | 84 ++++++++++++++++++++++++++++++ 4 files changed, 219 insertions(+), 31 deletions(-) delete mode 100644 TODO.md create mode 100644 docs/ROADMAP.md create mode 100644 docs/SCRIPTS.md diff --git a/README.md b/README.md index 440e7c6..25465e9 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ Add user-level packages, aliases, and dotfiles here. nomarchy.home.terminal = "kitty"; ``` -For the full list of `nomarchy.*` options you can set in `system.nix` and `home.nix`, see the [Options Reference](docs/OPTIONS.md). +For the full list of `nomarchy.*` options you can set in `system.nix` and `home.nix`, see the [Options Reference](docs/OPTIONS.md). For where the project is heading next, see the [Roadmap](docs/ROADMAP.md). ### Applying Changes After editing your files, apply them instantly. **IMPORTANT:** Nomarchy requires the `--impure` flag for evaluation. You **MUST** use the following aliases rather than standard NixOS commands: diff --git a/TODO.md b/TODO.md deleted file mode 100644 index ad44bd7..0000000 --- a/TODO.md +++ /dev/null @@ -1,30 +0,0 @@ -# Nomarchy Distribution - TODO List - -## 1. Professional Installer [IN PROGRESS] -- [x] Refactor with `gum` for stylized UI. -- [x] Add clear section headers and environment checks. -- [ ] Implement software profile selection. -- [x] Add "Pre-flight Check" summary screen showing all selected options (disk, user, profiles) before proceeding. -- [x] Implement post-install "Success" dashboard with next steps. -- [ ] Improve disk selection to show more metadata (vendor, model, serial). - -## 2. Nomarchy Plymouth Theme [DONE] -- [x] Create custom theme assets in `assets/plymouth/`. -- [x] Center official logo on splash screen. -- [x] Declarative integration in `modules/system/plymouth.nix`. -- [x] Implement full LUKS password entry support (password prompt, bullet indicators). -- [x] Add smooth fade-in/fade-out animations for the logo. -- [x] Add system message display (e.g., "Rebooting...", "Checking Disk..."). - -## 3. System Branding (Fastfetch & Terminal) [DONE] -- [x] Restore and optimize official ASCII logo (`logo.txt`). -- [x] Update `config/fastfetch/config.jsonc` to use new logo and declarative stats. -- [x] Update `nomarchy-show-logo` to use centralized branding path. -- [x] Declaratively map all branding assets via Home Manager. - -## 4. Repo Hygiene & Consistency [DONE] -- [x] Remove legacy Arch Linux imperative scripts. -- [x] Move all dynamic state to unified `state.json`. -- [x] Implement professional state migration via Home Manager activation. -- [x] Declaratively link all `config/` directories with `recursive = true`. -- [x] Transition to Remote-First Upstream model. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..015fc25 --- /dev/null +++ b/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-`. 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/-`. 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`). diff --git a/docs/SCRIPTS.md b/docs/SCRIPTS.md new file mode 100644 index 0000000..3ff9ee1 --- /dev/null +++ b/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`.)