yino/REQUIREMENTS.md

# Requirements: Yino

> Generated during /opsx:explore session on 2026-02-21
> Status: Draft — pending architect review

## 1. Project Overview

### Vision

Yino ("Yino Is Not Omarchy") is a full-fidelity port of [Omarchy](https://github.com/basecamp/omarchy) from Arch
Linux to Debian Linux. It delivers the same opinionated, keyboard-driven Hyprland desktop experience but on a stable
Debian base instead of Arch's rolling release.

### Problem Being Solved

Omarchy is Arch-only. Users who want its curated desktop experience but prefer or require Debian's stability and
ecosystem (enterprise environments, known hardware support, LTS lifecycle) have no option today. Yino fills that gap.

### Success Criteria

- SC-001: A user can boot a Yino ISO, complete an unattended installation (offline-capable), and arrive at a working
  Hyprland desktop identical in look, feel, and functionality to Omarchy
- SC-002: All Omarchy `omarchy-*` commands have working `yino-*` equivalents
- SC-003: Omarchy themes install and work on Yino without modification (file structure compatibility)
- SC-004: Upstream Omarchy changes can be evaluated and ported to Yino with reasonable effort

### Context

- **Greenfield vs. existing:** Partial existing work. A QEMU VM helper (`bin/yino-vm`), a preseed config
  (`iso/preseed.cfg`), and reference documentation exist. The preseed achieves a bootable Hyprland system but uses a
  fragile approach (nested echo statements in `late_command`, network dependency on sid). The project needs a clean
  architecture before proceeding further.
- **Upstream reference:** Omarchy @ `463417a` (`dev` branch), analyzed 2026-02-16. See `docs/Omarchy.md`.
- **Base OS:** Debian 13 "Trixie" (stable, released August 2025)

## 2. Stakeholders & Users

### Primary User

Single-user desktop operator. Same persona as Omarchy's target: a developer who wants an opinionated, pre-configured
Linux desktop and doesn't want to assemble it themselves.

### Technical Ability

Comfortable with Linux basics (terminal, sudo, SSH). Does not want to compile kernels or debug Wayland protocols.
Expects things to work out of the box after installation.

### Scale

Single machine per installation. No fleet management, no multi-user, no remote deployment (for now).

### Target Hardware

- Architecture: amd64 only
- Reference hardware: Framework 13 AMD Ryzen 7040 (future, not immediate)
- Immediate target: QEMU VM (development and testing)

## 3. Functional Requirements

### 3.1 ISO Generation & Installation

**FR-001: Offline-capable installation ISO**
- The project shall produce tooling to generate a custom Debian 13 (Trixie) installation ISO
- The ISO shall contain all packages needed for a complete Yino installation, including packages not in Trixie stable
  (downloaded from sid and cached/slipstreamed into the ISO)
- Installation shall work without network access (offline-capable)
- _Priority: Must_
- _Acceptance criteria:_ Running the ISO build script produces a bootable ISO. Booting that ISO in a network-isolated
  QEMU VM results in a complete Yino installation.

**FR-002: Unattended installation via preseed**
- The Debian installer shall be driven by a preseed configuration
- Preseed scope is limited to base OS concerns: locale, partitioning, encryption, filesystem, user account, bootloader
- The preseed shall configure: LUKS full-disk encryption, btrfs filesystem, a single user account with automatic login,
  GRUB bootloader with serial console support (for VM testing)
- _Priority: Must_
- _Acceptance criteria:_ The installation completes without user interaction beyond the LUKS passphrase (which is
  hardcoded for dev/test, prompted in production).

**FR-003: Post-install configuration via installer script**
- All desktop environment setup, package installation, and configuration shall be handled by a separate installer
  script, not by the preseed `late_command`
- The installer shall follow Omarchy's phased architecture (preflight, packaging, config, login, post-install)
- The installer shall be idempotent (safe to re-run)
- _Priority: Must_
- _Acceptance criteria:_ The preseed triggers the installer (via a first-boot systemd service or equivalent). The
  installer runs the full phase sequence and produces a working desktop.

**FR-004: ISO build script**
- A reproducible build script shall take the stock Debian 13 DVD ISO, inject the preseed, cached packages, and
  installer, and produce the final Yino ISO
- Downloaded assets (Debian ISO, sid .debs) shall be cached in the `download/` directory
- _Priority: Must_
- _Acceptance criteria:_ Running the build script twice with the same inputs produces functionally identical ISOs.

### 3.2 Desktop Environment

**FR-010: Hyprland compositor**
- Hyprland shall be the sole compositor (Wayland-only, no X11)
- Launched via UWSM through SDDM with automatic login
- Configuration shall follow Omarchy's structure: `hyprland.conf` sourcing `bindings.conf`, `monitors.conf`,
  `input.conf`, `looknfeel.conf`
- _Priority: Must_
- _Acceptance criteria:_ After installation, the system boots to a Hyprland desktop with working window tiling,
  workspaces, and keybindings matching Omarchy's defaults.

**FR-011: Status bar (Waybar)**
- Waybar shall provide the top status bar
- Module layout shall match Omarchy: logo + workspaces (left), clock + indicators (center), tray + network + audio +
  cpu + battery (right)
- _Priority: Must_

**FR-012: Application launcher (Walker)**
- Walker shall be the application launcher, bound to Super + Space
- Provides fuzzy search across applications, files, and commands
- _Note:_ Walker is not packaged for Debian. Must be built from source or packaged as .deb.
- _Priority: Must_

**FR-013: Notification daemon (Mako)**
- Mako shall handle desktop notifications with theme-aware styling
- _Priority: Must_

**FR-014: On-screen display (SwayOSD)**
- SwayOSD shall provide OSD for volume, brightness, and caps lock changes
- _Note:_ Trixie has 0.1.0 (old). Sid has 0.3.0. Use sid version.
- _Priority: Should_

**FR-015: Lock screen (Hyprlock)**
- Hyprlock shall provide the lock screen with theme-aware styling
- _Priority: Must_

**FR-016: Idle management (Hypridle)**
- Hypridle shall manage screen dimming, locking, and suspend after configurable idle timeouts
- _Priority: Must_

**FR-017: Night light (Hyprsunset)**
- Hyprsunset shall provide blue light filtering
- _Note:_ Not packaged in any Debian suite. Must be built from source. Alternative: `wlsunset` is in Debian.
- _Priority: Should_

**FR-018: Terminal emulators**
- Ghostty shall be the default terminal
- Alacritty shall also be installed
- _Note:_ Ghostty is not packaged for Debian. Community .deb builds exist (debian.griffo.io). Evaluate whether to
  use community builds or build from source.
- _Priority: Must (Ghostty), Should (Alacritty pre-installed)_

**FR-019: Neovim**
- Neovim shall be installed with a configuration equivalent to Omarchy's `omarchy-nvim`
- The configuration shall include LSP, Treesitter, and the pixel.nvim colorscheme (ANSI-color-adaptive)
- _Note:_ Can be delivered as dotfiles overlay rather than a .deb package.
- _Priority: Must_

**FR-020: Browser**
- Chromium shall be the default browser
- _Note:_ Omarchy ships a custom `omarchy-chromium` with live Material Design 3 theme switching. This is significant
  build effort. Standard Debian Chromium is acceptable for v1; custom build is a future enhancement.
- _Priority: Must (standard Chromium), Could (live theme switching via custom build)_

### 3.3 Configuration System

**FR-030: Three-layer configuration system**
- Yino shall implement Omarchy's 3-layer config system:
  - Layer 1 (Default): `~/.local/share/yino/default/` — factory defaults, overwritten on update
  - Layer 2 (Theme): `~/.local/share/yino/themes/<name>/` — theme overrides
  - Layer 3 (User): `~/.config/` — user customizations, highest priority
- _Priority: Must_

**FR-031: Keybindings**
- All Omarchy default keybindings shall be replicated (Super as primary modifier)
- Super + Return = Terminal, Super + Space = Walker, Super + W = Close, etc.
- Full keybinding reference accessible via Super + K
- _Priority: Must_

**FR-032: User hooks**
- Users shall be able to place scripts in `~/.config/yino/hooks/` for event-driven customization
- The `yino-hook` command shall dispatch named hooks
- _Priority: Should_

### 3.4 Theming

**FR-040: Theme system**
- Yino shall support Omarchy's theme format: a directory containing up to 10 files (alacritty.toml, btop.theme,
  hyprland.conf, hyprlock.conf, mako.ini, neovim.lua, swayosd.css, walker.css, waybar.css, backgrounds/)
- `yino-theme-set <name>` shall atomically restyle all themed components
- _Priority: Must_
- _Acceptance criteria:_ Installing an Omarchy community theme (e.g., synthwave84) via its git URL works without
  modification.

**FR-041: Built-in themes**
- All 14 Omarchy built-in themes shall be included
- _Priority: Must_

**FR-042: Community theme support**
- `yino-theme-install <git-url>` shall install third-party themes from Git repositories
- _Priority: Must_

### 3.5 Menu System

**FR-050: Yino menu**
- `yino-menu` shall replicate Omarchy's hierarchical menu system via Walker
- Menu structure: Apps, Learn, Trigger, Style, Setup, Install, Remove, Update, About, System
- All submenus shall have working Debian equivalents of their Omarchy counterparts
- _Priority: Must_

### 3.6 System Management

**FR-060: Update system**
- `yino-update` shall: create a btrfs snapshot, pull latest Yino from git, run pending migrations, re-run the
  installer pipeline idempotently
- _Priority: Must_

**FR-061: Snapshot management**
- Btrfs snapshots via Snapper with configurable limits
- `yino-snapshot` for manual snapshot creation
- _Priority: Must_

**FR-062: Migration system**
- Timestamped migration scripts that run once per system (same mechanism as Omarchy)
- Tracked in a state file so they don't re-run
- _Priority: Must_

### 3.7 Security

**FR-070: Full-disk encryption**
- LUKS encryption is mandatory during installation
- _Priority: Must_

**FR-071: Firewall**
- UFW enabled by default
- _Priority: Must_

**FR-072: GPG and keyring**
- GPG agent configured for signing
- GNOME keyring auto-unlocked on login
- _Priority: Must_

**FR-073: SSH configuration**
- Connection stability tweaks matching Omarchy
- _Priority: Should_

### 3.8 Boot

**FR-080: Plymouth boot splash**
- Custom Yino-branded Plymouth theme (adapted from Omarchy's Tokyo Night theme)
- LUKS passphrase prompt over the splash, progress bar animation
- _Priority: Should_

**FR-081: SDDM auto-login**
- SDDM configured for automatic login to hyprland-uwsm session
- Single-user model: disk decryption authenticates the user
- _Priority: Must_

### 3.9 Applications & Utilities

**FR-090: Pre-installed applications**
- The following shall be installed: Chromium, Nautilus (file manager), evince (PDF viewer), mpv (media player),
  LibreOffice
- _Priority: Must_

**FR-091: Pre-installed CLI utilities**
- The following shall be installed: btop, fastfetch, ripgrep, fzf, bat, eza, zoxide, dust, jq, gum, lazygit
- _Priority: Must_

**FR-092: Development tools**
- Docker and docker-compose, GitHub CLI (gh), mise (dev tool version manager)
- _Priority: Should_

**FR-093: Optional applications**
- Spotify, Typora, Obsidian, Signal, 1Password — installable via `yino-menu` > Install
- These should be available to install, not necessarily pre-installed
- _Priority: Could_

### 3.10 Shell Scripts (yino-* commands)

**FR-100: Command parity**
- Every `omarchy-*` command shall have a `yino-*` equivalent
- Package management wrappers shall use `apt` instead of `pacman`/`yay`
- All Arch-specific logic shall be replaced with Debian equivalents
- _Priority: Must_

**FR-101: Hardware detection and fixes**
- Hardware-specific fixes from Omarchy shall be ported where applicable to Debian
- NVIDIA, Bluetooth, printing, audio, Wi-Fi power save, USB autosuspend
- Apple-specific fixes: evaluate relevance, defer if not needed for target hardware
- _Priority: Should_

## 4. Non-Functional Requirements

**NFR-001: Debian stable as base**
- Trixie (Debian 13) is the base. All packages shall come from Trixie stable where available.
- Packages not in Trixie (primarily the Hyprland ecosystem) shall be sourced from sid, cached, and included in the ISO.
- No runtime dependency on sid repositories. After installation, the system shall be fully functional without network.
- _Rationale:_ Debian stable's conservative updates are the whole point of Yino over Omarchy/Arch.

**NFR-002: Package sourcing tiers**
- Tier 1 — Trixie stable (use directly): ~90% of packages (Mako, swaybg, SDDM, Alacritty, Neovim, all CLI tools,
  pipewire, cups, fonts, etc.)
- Tier 2 — sid .debs (download, cache, slipstream): Hyprland ecosystem (12+ packages), UWSM, newer Waybar (0.15),
  newer SwayOSD (0.3.0)
- Tier 3 — Build from source or external (cache as .debs): Walker, Ghostty, Hyprsunset, lazydocker
- _Rationale:_ The entire Hyprland ecosystem was deliberately removed from Trixie (Debian Bug #1107152). sid is the
  only official Debian source.

**NFR-003: Offline installation**
- A completed Yino ISO shall contain all packages needed for installation. No network required during install.
- Network may be used during ISO build to download and cache packages.

**NFR-004: Reproducible ISO builds**
- The ISO build process shall be scripted and deterministic given the same input packages.
- All downloaded assets cached in `download/`.

**NFR-005: Upstream tracking**
- Yino shall track upstream Omarchy development on the `dev` branch.
- The `docs/Omarchy.md` analysis document shall be kept current.
- Changes shall be evaluated and ported where applicable using the Arch-to-Debian mapping in `docs/Omarchy.md` §14.

**NFR-006: Naming convention**
- All scripts shall use the `yino-` prefix (not `omarchy-`).
- Internal paths shall use `yino` (e.g., `~/.local/share/yino/`, `yino-first-boot.service`).
- Config directory: `~/.config/yino/` (for Yino-specific config; component configs like Hyprland remain in their
  standard locations).

**NFR-007: QEMU testability**
- The system shall boot and be fully functional in a QEMU VM (including software-rendered cursors and virtual GPU).
- The `bin/yino-vm` helper shall remain the primary development/test tool.

**NFR-008: Idempotent installer**
- The installer script shall be safe to run multiple times. Re-running shall bring the system to the desired state
  without duplication or breakage.

**NFR-009: Maintainability**
- No shell scripts written as nested echo statements inside preseed `late_command`.
- Preseed handles base OS only. Installer is a separate, readable, version-controlled script tree.
- Clear separation: preseed → first-boot trigger → installer phases.

## 5. Constraints

### Technical

- **Debian 13 Trixie only.** No support for Bookworm (12) or older.
- **amd64 only.** No arm64 or other architectures.
- **Wayland only.** No X11 support or fallback.
- **No custom Debian package repository** (for now). Packages not in Debian are cached as .deb files and included
  in the ISO. A proper apt repo is future work.
- **No Secure Boot.** Same as Omarchy — explicitly not supported.

### Business / Process

- **Minimize dependencies.** Discuss with owner before adding anything not in Omarchy.
- **Match upstream Omarchy.** When multiple approaches exist, prefer the one Omarchy uses. Deviate only where strictly
  necessary for Debian compatibility.
- **KISS.** Simple solutions preferred. Less is more.

### Scope Exclusions (explicit "Won't" for now)

- Custom Chromium build with live theme switching (use standard Debian Chromium)
- Custom apt package repository infrastructure
- Multi-architecture support (arm64)
- Fleet deployment or multi-user scenarios
- Apple hardware-specific fixes (T2 chip, SPI keyboard, NVMe suspend)

## 6. Assumptions & Dependencies

### Assumptions

- A-001: Debian 13 Trixie remains the current stable release throughout development
- A-002: Hyprland ecosystem packages in sid remain buildable/installable on a Trixie base (library compatibility)
- A-003: Omarchy's `dev` branch remains the active development branch
- A-004: The QEMU VM provides sufficient test coverage for the initial development phase
- A-005: Community Ghostty .deb builds (e.g., debian.griffo.io) are trustworthy for development; production may
  require building from source

### Dependencies

- D-001: Upstream Omarchy repository (`basecamp/omarchy`) for reference configs, themes, and scripts
- D-002: Debian sid repository for Hyprland ecosystem .debs
- D-003: Stock Debian 13 DVD ISO (`debian-13.x.x-amd64-DVD-1.iso`) as build input
- D-004: QEMU + OVMF for development testing

## 7. Open Questions

- OQ-001: **sid library compatibility** — Will the Hyprland stack from sid install cleanly on a Trixie base, or will
  it pull in cascading sid dependencies that destabilize the system? Needs a spike: download the Hyprland .debs from
  sid and attempt install on a clean Trixie system.
- OQ-002: **Walker build** — Walker is a Go application. What are its build dependencies? Can we produce a static
  binary and ship it without a .deb? Or should we package it properly?
- OQ-003: **Ghostty sourcing** — Build from source (Zig toolchain needed), use community .debs, or defer Ghostty and
  use Alacritty/foot as default terminal?
- OQ-004: **Hyprsunset vs. wlsunset** — Hyprsunset is not in Debian at all. `wlsunset` is in Trixie stable and
  provides similar functionality. Is Omarchy compatibility worth the build effort, or is wlsunset an acceptable
  substitute?
- OQ-005: **Waybar version** — Trixie ships 0.12.0, sid has 0.15.0. Does Omarchy's Waybar config require features
  from 0.15? If so, Waybar moves to Tier 2 (sid).
- OQ-006: **ISO build tool** — `live-build`, `simple-cdd`, or manual ISO remastering (extract, inject preseed +
  packages, repackage)? Each has tradeoffs in complexity vs. control.
- OQ-007: **Omarchy theme names** — The analysis document doesn't list all 14 built-in theme names. Need to inspect
  the upstream `themes/` directory to enumerate them.
- OQ-008: **Update channel model** — Omarchy has 4 channels (stable/rc/edge/dev). Yino on Debian stable likely needs
  only 1-2. What's the right model?

## 8. Glossary

| Term | Definition |
|:-----|:-----------|
| **Omarchy** | Upstream Arch Linux-based desktop distribution by Basecamp/DHH |
| **Yino** | "Yino Is Not Omarchy" — this project; Debian-based port of Omarchy |
| **Trixie** | Debian 13, the current stable release (August 2025) |
| **sid** | Debian unstable — rolling release, always the newest packages |
| **forky** | Debian testing — the future Debian 14 |
| **Hyprland** | Wayland compositor and tiling window manager |
| **UWSM** | Universal Wayland Session Manager — launches Hyprland via SDDM |
| **Walker** | Application launcher used by Omarchy (fuzzy search over apps/files/commands) |
| **SDDM** | Simple Desktop Display Manager — handles login/auto-login |
| **preseed** | Debian installer automation format (answer file for `debian-installer`) |
| **OPR** | Omarchy Package Repository — custom Arch packages built by the Omarchy team |
| **Snapper** | Btrfs snapshot management tool |
| **LUKS** | Linux Unified Key Setup — full-disk encryption |
| **Plymouth** | Boot splash screen system |
| **pixel.nvim** | Neovim colorscheme that adapts to terminal ANSI colors (0-15) |
| **slipstream** | To inject additional packages/files into an existing ISO image |

## Appendix: Priority Matrix

### Must Have (required for a functional system)

| ID | Requirement |
|:---|:------------|
| FR-001 | Offline-capable installation ISO |
| FR-002 | Unattended installation via preseed |
| FR-003 | Post-install configuration via installer script |
| FR-004 | ISO build script |
| FR-010 | Hyprland compositor |
| FR-011 | Waybar status bar |
| FR-012 | Walker application launcher |
| FR-013 | Mako notifications |
| FR-015 | Hyprlock lock screen |
| FR-016 | Hypridle idle management |
| FR-018 | Ghostty terminal (or acceptable substitute) |
| FR-019 | Neovim with config |
| FR-020 | Chromium browser (standard) |
| FR-030 | Three-layer configuration system |
| FR-031 | Keybindings (Omarchy defaults) |
| FR-040 | Theme system (Omarchy-compatible format) |
| FR-041 | 14 built-in themes |
| FR-042 | Community theme support |
| FR-050 | Yino menu |
| FR-060 | Update system |
| FR-061 | Snapshot management |
| FR-062 | Migration system |
| FR-070 | LUKS full-disk encryption |
| FR-071 | UFW firewall |
| FR-072 | GPG and keyring |
| FR-081 | SDDM auto-login |
| FR-090 | Pre-installed GUI applications |
| FR-091 | Pre-installed CLI utilities |
| FR-100 | yino-* command parity |

### Should Have (expected but not blocking)

| ID | Requirement |
|:---|:------------|
| FR-014 | SwayOSD on-screen display |
| FR-017 | Hyprsunset / night light |
| FR-032 | User hooks |
| FR-073 | SSH configuration |
| FR-080 | Plymouth boot splash |
| FR-092 | Development tools (Docker, gh, mise) |
| FR-101 | Hardware detection and fixes |

### Could Have (desirable, defer if needed)

| ID | Requirement |
|:---|:------------|
| FR-020 | Custom Chromium with live theme switching |
| FR-093 | Optional applications (Spotify, Typora, Obsidian, Signal, 1Password) |

### Won't Have (explicitly out of scope)

| Item | Reason |
|:-----|:-------|
| Custom apt repository | Premature; cache .debs directly for now |
| arm64 support | amd64 only |
| Multi-user / fleet deployment | Single-user desktop only |
| Apple hardware fixes | Not relevant to target hardware |
| Secure Boot | Same as Omarchy — not supported |