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 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