m/yino
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: m:6c6a82937fe942db80df6d4fd95eeb0d8cff9f7e
Branches Tags
m:main
..
compare: m:91e1d32f1c6e0973ef50b29aae983871a476dd7b
Branches Tags
m:main

No commits in common. "6c6a82937fe942db80df6d4fd95eeb0d8cff9f7e" and "91e1d32f1c6e0973ef50b29aae983871a476dd7b" have entirely different histories.
6c6a82937f ... 91e1d32f1c

6 changed files with 19 additions and 828 deletions
Show Stats Expand all files Collapse all files

169
CONCLUSIONS.md
View File

@ -1,169 +0,0 @@
# Conclusions: Yino Project Post-Mortem
> Written: 2026-02-21
> Status: Project abandoned
> Duration: ~1 week (2026-02-15 to 2026-02-21)
## What Yino was
Yino ("Yino Is Not Omarchy") was an attempt to port [Omarchy](https://github.com/basecamp/omarchy) — an
opinionated, keyboard-driven Hyprland desktop environment built on Arch Linux — to a stable Debian base.
The motivation was simple: Omarchy's curated desktop experience is excellent, but Arch Linux's rolling
release model introduces instability. Debian's conservative, long-term-support release cycle seemed like
the ideal stable foundation to deliver the same experience without the rolling-release risk.
## What we built
- A QEMU VM helper (`bin/yino-vm`) with KVM acceleration for development and testing
- A preseed configuration (`iso/preseed.cfg`) achieving unattended Debian installation with LUKS + btrfs
- ISO build tooling for injecting preseed and packages into the stock Debian DVD image
- Comprehensive requirements documentation (`REQUIREMENTS.md`) with 87 numbered requirement IDs
- A detailed upstream analysis (`docs/Omarchy.md`) mapping Omarchy's full architecture at commit `463417a`
- An Arch-to-Debian package mapping covering ~100+ packages across all components
## The core problem: Hyprland doesn't fit stable distros
The central discovery of this project is that **Hyprland is too fast-moving for any traditional stable
Linux distribution to keep up with.**
### Debian
The entire Hyprland ecosystem was deliberately removed from Debian Trixie (stable) via
[Debian Bug #1107152](https://bugs.debian.org/1107152). Hyprland remains in sid (unstable), but
installing sid packages on a stable base is a known source of dependency conflicts and system
instability — the exact problem Yino was trying to avoid.
The Yino approach was to download Hyprland ecosystem packages from sid, cache them, and slipstream them
into the installation ISO. This is workable in theory but creates a significant maintenance burden:
- **12+ packages** from the Hyprland ecosystem need to be sourced from sid
- **Library compatibility** between sid packages and the Trixie base is not guaranteed
- **Every Debian stable point release** could break the cached sid packages
- **Every Hyprland update** requires re-testing against the Trixie base
- **Several additional packages** (Walker, Ghostty, Hyprsunset) aren't in Debian at all and need to be
built from source
### Fedora (investigated as alternative)
Initially, Fedora appeared promising — semi-stable with 6-month releases and what we believed was a
Hyprland Spin. **Investigation revealed this was wrong on both counts:**
- **There is no Fedora Hyprland Spin.** It doesn't exist, has never existed, and has no proposal in the
pipeline. The Fedora Sway Spin exists; Hyprland does not.
- **Hyprland was retired from Fedora 43.** The package was present in Fedora 41 and 42, but was removed
from Fedora 43 because `hyprland-qtutils` depended on Qt 6.9 private APIs, and Fedora 43 moved to
Qt 6.10. Nobody stepped up to fix it. It was flagged via Bugzilla #2366813 as "F43FailsToInstall" and
subsequently retired (Pagure issue #12969).
- **Community COPR repos** (`solopasha/hyprland`, `sdegler/hyprland`, etc.) exist but are volunteer-
maintained and fragile.
Fedora's Hyprland situation is arguably **worse** than Debian's — Debian at least still has Hyprland
in sid. Fedora's packaging is entirely gone from official repos and trending in the wrong direction.
### openSUSE Tumbleweed (investigated as alternative)
Tumbleweed is the strongest traditional option for Hyprland:
- Hyprland is in **official repos** and actively maintained
- Btrfs + Snapper is Tumbleweed's flagship feature (they pioneered the pattern Omarchy adopted)
- KIWI image builder is world-class ISO tooling
- openQA automated testing catches regressions before they reach users
However, Tumbleweed is a **rolling release** — continuous updates, not periodic stable releases. This
conflicts directly with the project's goal of providing a stable, predictable base. The whole point of
Yino was to escape rolling-release churn, and Tumbleweed — however well-tested — is still rolling.
### NixOS (investigated as alternative)
NixOS is the most philosophically interesting option:
- Hyprland is well-maintained in nixpkgs with first-class NixOS module support
- The entire system is defined declaratively in configuration files — which aligns perfectly with
"an opinionated set of configuration files"
- Versions are pinned, updates happen when you choose, rollbacks are atomic
- ISO generation is trivial (a Nix expression)
- `henrysipp/omarchy-nix` (657 stars) demonstrates significant community interest
However, NixOS represents a **complete paradigm shift** from Omarchy's architecture. Omarchy is shell
scripts overlaying dotfiles onto a traditional Linux system. NixOS would require reimagining the entire
project as a Nix flake with home-manager modules. This violates the "match upstream Omarchy" design
principle that was paramount for Yino.
## The landscape at a glance
| Distribution | Hyprland in official repos | Stability model | Trend |
|:---|:---:|:---|:---|
| Arch Linux | ✅ Always | Rolling (untested) | Stable — it's the native platform |
| Debian sid | ✅ Yes | Unstable | Was in testing, yanked from stable |
| Debian Trixie | ❌ Removed | Stable | Gone (Bug #1107152) |
| Fedora 43 | ❌ Retired | 6-month releases | Gone (Qt 6.10 breakage) |
| Fedora COPR | ⚠️ Community | Fragile | Depends on volunteers |
| openSUSE TW | ✅ Official | Rolling (QA-tested) | Healthy |
| NixOS | ✅ Official | Pinned by user | Very healthy |
**Only rolling distros and NixOS maintain healthy Hyprland packaging.** Every traditional stable distro
has dropped it.
## Related community projects
During research, we found these existing efforts to port Omarchy to other bases:
| Project | Base | Stars | Notes |
|:---|:---|---:|:---|
| `henrysipp/omarchy-nix` | NixOS | 657 | Full Omarchy port as a Nix flake |
| `elpritchos/omadora` | Fedora | 70 | Minimal Fedora + Hyprland, Omarchy-like |
The NixOS port has nearly 10x the community interest of the Fedora attempt, suggesting the declarative
approach resonates more strongly with the audience that wants "Omarchy but not on Arch."
## Why we're stopping
The fundamental tension is irreconcilable:
> **Hyprland moves fast. Stable distros move slow. Bridging this gap is a full-time packaging job,
> not a configuration project.**
Yino was conceived as "an opinionated set of configuration files" — the same identity as Omarchy.
But on Debian (or Fedora), the project would spend most of its effort on **packaging** (building,
caching, testing, and maintaining 12+ Hyprland ecosystem packages against a stable base), leaving
little room for the actual value proposition: the curated desktop experience.
On Arch, Omarchy can focus on the experience because the packaging is handled by the distribution.
On any stable distro, Yino would have to handle both — and the packaging burden dominates.
## What would change this conclusion
- **Hyprland stabilizes its ABI** and gets re-accepted into Debian stable or Fedora — unlikely given
the ecosystem's development velocity
- **A third party maintains Hyprland packages for Debian/Fedora** reliably (a PPA, COPR, or OBS repo
with serious commitment) — possible but not something to bet a project on
- **The project embraces NixOS** and accepts the paradigm shift — viable, and `omarchy-nix` proves
demand exists, but it's a different project with a different identity
- **The project embraces Tumbleweed** and accepts rolling release (with snapshot safety) — the most
natural fit technically, but contradicts the original motivation
## Open questions that were never resolved
These were identified during requirements analysis but never investigated due to the project being
abandoned:
- **OQ-001:** Would the Hyprland stack from sid actually install cleanly on Trixie, or would it pull
cascading dependencies that destabilize the system?
- **OQ-002:** What are Walker's build dependencies? Static binary or proper .deb packaging?
- **OQ-003:** Ghostty sourcing — build from source (Zig toolchain), community .debs, or use Alacritty?
- **OQ-004:** Hyprsunset vs. wlsunset — is the Omarchy-compatible version worth the build effort?
- **OQ-006:** ISO build tool choice — live-build, simple-cdd, or manual remastering?
## Artifacts produced
All artifacts remain in the repository for reference:
| File | Description |
|:---|:---|
| `REQUIREMENTS.md` | Full requirements document (87 requirement IDs, user stories, acceptance criteria) |
| `docs/Omarchy.md` | Comprehensive Omarchy analysis at commit `463417a` (architecture, packages, ISO, theming) |
| `docs/yino-fsd.md` | Functional specification document |
| `iso/preseed.cfg` | Working preseed config for unattended Debian install (LUKS + btrfs + Hyprland) |
| `bin/yino-vm` | QEMU VM helper with KVM acceleration |
| `CONCLUSIONS.md` | This document |

486
REQUIREMENTS.md
View File

@ -1,486 +0,0 @@
# 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 |

2
bin/yino-vm
View File

@ -32,7 +32,6 @@ find_ovmf_code() {
/usr/share/OVMF/OVMF_CODE.fd
/usr/share/qemu/OVMF_CODE_4M.fd
/usr/share/qemu/OVMF_CODE.fd
/usr/share/edk2/x64/OVMF_CODE.4m.fd
/usr/share/edk2/x64/OVMF_CODE.fd
)
fi
@ -65,7 +64,6 @@ find_ovmf_vars_template() {
/usr/share/OVMF/OVMF_VARS.fd
/usr/share/qemu/OVMF_VARS_4M.fd
/usr/share/qemu/OVMF_VARS.fd
/usr/share/edk2/x64/OVMF_VARS.4m.fd
/usr/share/edk2/x64/OVMF_VARS.fd
)
fi

100
iso/preseed.cfg
View File

@ -83,10 +83,7 @@ d-i cdrom-checker/start boolean false
# Finish
d-i finish-install/reboot_in_progress note
# Post-install: configure serial console, sid repo, and first-boot desktop setup
# NOTE: preseed interprets \n as literal newlines, breaking shell commands.
# Use multiple echo commands instead of printf with \n for multi-line files.
# Heavy package installation is deferred to a first-boot systemd service.
# Post-install: configure serial console, SDDM + UWSM + Hyprland desktop
d-i preseed/late_command string \
USER=$(grep ':x:1000:' /target/etc/passwd | cut -d: -f1); \
LOG=/target/var/log/yino-late-command.log; \
@ -102,81 +99,22 @@ d-i preseed/late_command string \
echo "nameserver 1.1.1.1" > /target/etc/resolv.conf; \
echo "--- sid repo ---" >> $LOG; \
echo 'deb http://deb.debian.org/debian sid main contrib non-free-firmware' > /target/etc/apt/sources.list.d/sid.list; \
F=/target/etc/apt/preferences.d/sid-low-priority; \
echo 'Package: *' > $F; \
echo 'Pin: release a=unstable' >> $F; \
echo 'Pin-Priority: 100' >> $F; \
echo "--- first-boot setup script ---" >> $LOG; \
S=/target/usr/local/sbin/yino-first-boot; \
echo '#!/bin/sh' > $S; \
echo 'set -ex' >> $S; \
echo 'LOG=/var/log/yino-first-boot.log' >> $S; \
echo 'exec > "$LOG" 2>&1' >> $S; \
echo 'echo "=== Yino first-boot start ==="' >> $S; \
echo 'USER=$(grep ":x:1000:" /etc/passwd | cut -d: -f1)' >> $S; \
echo 'export DEBIAN_FRONTEND=noninteractive' >> $S; \
echo 'apt-get update' >> $S; \
echo 'apt-get -y install sddm' >> $S; \
echo 'apt-get -y -t unstable install hyprland uwsm foot' >> $S; \
echo 'mkdir -p /etc/sddm.conf.d' >> $S; \
echo 'echo "[Autologin]" > /etc/sddm.conf.d/autologin.conf' >> $S; \
echo 'echo "User=$USER" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
echo 'echo "Session=hyprland-uwsm" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
echo 'echo "" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
echo 'echo "[Theme]" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
echo 'echo "Current=breeze" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
echo 'systemctl enable sddm' >> $S; \
echo 'mkdir -p /usr/share/wayland-sessions' >> $S; \
echo 'echo "[Desktop Entry]" > /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
echo 'echo "Name=Hyprland (UWSM)" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
echo 'echo "Comment=Hyprland via Universal Wayland Session Manager" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
echo 'echo "Exec=uwsm start hyprland.desktop" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
echo 'echo "Type=Application" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
echo 'echo "DesktopNames=Hyprland" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
echo 'UHOME=/home/$USER' >> $S; \
echo 'mkdir -p $UHOME/.config/hyprland' >> $S; \
echo 'F=$UHOME/.config/hyprland/hyprland.conf' >> $S; \
echo 'echo "monitor = ,preferred,auto,1" > $F' >> $S; \
echo 'echo "" >> $F' >> $S; \
echo 'echo "env = WLR_NO_HARDWARE_CURSORS,1" >> $F' >> $S; \
echo 'echo "env = WLR_RENDERER_ALLOW_SOFTWARE,1" >> $F' >> $S; \
echo 'echo "" >> $F' >> $S; \
echo 'echo "exec-once = foot --server" >> $F' >> $S; \
echo 'echo "" >> $F' >> $S; \
echo 'echo "\$mainMod = SUPER" >> $F' >> $S; \
echo 'echo "" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, Return, exec, foot" >> $F' >> $S; \
echo 'echo "bind = \$mainMod SHIFT, Q, killactive" >> $F' >> $S; \
echo 'echo "bind = \$mainMod SHIFT, E, exit" >> $F' >> $S; \
echo 'echo "" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, 1, workspace, 1" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, 2, workspace, 2" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, 3, workspace, 3" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, 4, workspace, 4" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, 5, workspace, 5" >> $F' >> $S; \
echo 'echo "" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, left, movefocus, l" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, right, movefocus, r" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, up, movefocus, u" >> $F' >> $S; \
echo 'echo "bind = \$mainMod, down, movefocus, d" >> $F' >> $S; \
echo 'chown -R 1000:1000 $UHOME/.config' >> $S; \
echo 'systemctl disable yino-first-boot.service' >> $S; \
echo 'rm -f /usr/local/sbin/yino-first-boot' >> $S; \
echo 'echo "=== Yino first-boot done ==="' >> $S; \
chmod 755 $S; \
F=/target/etc/systemd/system/yino-first-boot.service; \
echo '[Unit]' > $F; \
echo 'Description=Yino first-boot desktop setup' >> $F; \
echo 'After=network-online.target' >> $F; \
echo 'Wants=network-online.target' >> $F; \
echo 'ConditionPathExists=/usr/local/sbin/yino-first-boot' >> $F; \
echo '' >> $F; \
echo '[Service]' >> $F; \
echo 'Type=oneshot' >> $F; \
echo 'ExecStart=/usr/local/sbin/yino-first-boot' >> $F; \
echo 'RemainAfterExit=yes' >> $F; \
echo '' >> $F; \
echo '[Install]' >> $F; \
echo 'WantedBy=multi-user.target' >> $F; \
in-target systemctl enable yino-first-boot.service >> $LOG 2>&1; \
printf 'Package: *\nPin: release a=unstable\nPin-Priority: 100\n' > /target/etc/apt/preferences.d/sid-low-priority; \
echo "--- apt-get update ---" >> $LOG; \
in-target apt-get update >> $LOG 2>&1 || echo "FAILED: apt-get update (exit $?)" >> $LOG; \
echo "--- install sddm ---" >> $LOG; \
in-target env DEBIAN_FRONTEND=noninteractive apt-get -y install sddm >> $LOG 2>&1 || echo "FAILED: install sddm (exit $?)" >> $LOG; \
echo "--- install hyprland uwsm foot ---" >> $LOG; \
in-target env DEBIAN_FRONTEND=noninteractive apt-get -y -t unstable install hyprland uwsm foot >> $LOG 2>&1 || echo "FAILED: install hyprland (exit $?)" >> $LOG; \
echo "--- SDDM config ---" >> $LOG; \
mkdir -p /target/etc/sddm.conf.d; \
printf '[Autologin]\nUser=%s\nSession=hyprland-uwsm\n\n[Theme]\nCurrent=breeze\n' "$USER" > /target/etc/sddm.conf.d/autologin.conf; \
in-target systemctl enable sddm >> $LOG 2>&1 || echo "FAILED: enable sddm" >> $LOG; \
mkdir -p /target/usr/share/wayland-sessions; \
printf '[Desktop Entry]\nName=Hyprland (UWSM)\nComment=Hyprland via Universal Wayland Session Manager\nExec=uwsm start hyprland.desktop\nType=Application\nDesktopNames=Hyprland\n' > /target/usr/share/wayland-sessions/hyprland-uwsm.desktop; \
echo "--- Hyprland config ---" >> $LOG; \
UHOME=/target/home/$USER; \
mkdir -p $UHOME/.config/hyprland; \
printf 'monitor = ,preferred,auto,1\n\nenv = WLR_NO_HARDWARE_CURSORS,1\nenv = WLR_RENDERER_ALLOW_SOFTWARE,1\n\nexec-once = foot --server\n\n$mainMod = SUPER\n\nbind = $mainMod, Return, exec, foot\nbind = $mainMod SHIFT, Q, killactive\nbind = $mainMod SHIFT, E, exit\n\nbind = $mainMod, 1, workspace, 1\nbind = $mainMod, 2, workspace, 2\nbind = $mainMod, 3, workspace, 3\nbind = $mainMod, 4, workspace, 4\nbind = $mainMod, 5, workspace, 5\n\nbind = $mainMod, left, movefocus, l\nbind = $mainMod, right, movefocus, r\nbind = $mainMod, up, movefocus, u\nbind = $mainMod, down, movefocus, d\n' > $UHOME/.config/hyprland/hyprland.conf; \
chown -R 1000:1000 $UHOME/.config; \
echo "=== Yino late_command done ===" >> $LOG

20
openspec/config.yaml
View File

@ -1,20 +0,0 @@
schema: spec-driven
# Project context (optional)
# This is shown to AI when creating artifacts.
# Add your tech stack, conventions, style guides, domain knowledge, etc.
# Example:
# context: |
# Tech stack: TypeScript, React, Node.js
# We use conventional commits
# Domain: e-commerce platform
# Per-artifact rules (optional)
# Add custom rules for specific artifacts.
# Example:
# rules:
# proposal:
# - Keep proposals under 500 words
# - Always include a "Non-goals" section
# tasks:
# - Break tasks into chunks of max 2 hours

70
prompts/REQUIREMENTS-ANALYST-PROMPT.md
View File

@ -1,70 +0,0 @@
# Requirements Analyst — for use with /opsx:explore
You are a senior requirements analyst for this session. Your job is to bring structured interview discipline to the exploration phase, ensuring that when the conversation transitions to /opsx:new, the requirements are thorough enough for an architect to work from.
## How this works with /opsx:explore
You are an overlay, not a replacement. Respect the explore mode's rules: no implementation, no code. You ARE allowed to create artifacts like REQUIREMENTS.md — that's capturing thinking, not implementing.
When the user invokes /opsx:explore, bring your requirements expertise to the freeform conversation. Don't override explore's conversational style — enhance it with the discipline of a structured interview. Be curious, ask follow-up questions, use diagrams when helpful, but make sure the important bases get covered before the user transitions to /opsx:new.
## Interview Phases
Use these as a mental checklist, not a rigid script. Weave them into the natural exploration. If the user is already deep in one area, go with them — but gently steer toward gaps before wrapping up.
**Vision & Context:** Elevator pitch, problem being solved, who it's for, why now, greenfield vs. existing system, integrations, success criteria.
**Users & Stakeholders:** Primary and secondary users, roles and technical ability, stakeholder map, expected scale, accessibility and i18n needs.
**Functional Requirements:** Major features, user stories, critical day-one journeys, business rules and constraints, workflows with approvals or state transitions, key data entities and relationships.
**Non-Functional Requirements:** Performance targets, availability needs, security model and data sensitivity, scalability expectations, data retention and migration, compliance and audit requirements, deployment model.
**Constraints & Boundaries:** Technology mandates or restrictions, budget range, timeline and hard deadlines, what's explicitly out of scope, known risks, team size and skills.
**Priorities:** MoSCoW ranking (Must/Should/Could/Won't), gap check, confirmation of key decisions.
## Your approach
- Ask 2–4 questions at a time, grouped naturally. Don't interrogate.
- Paraphrase answers back to confirm understanding before moving on.
- When the user says "I don't know," note it as an open question. Don't pressure.
- Stay in problem/outcome language, not implementation language. The architect handles the "how."
- Track which phases you've covered and which have gaps. Before the user moves to /opsx:new, surface any uncovered areas: "Before we move on, we haven't discussed security or deployment expectations — worth covering now?"
## When insights crystallize
When the exploration feels substantive enough, offer to capture the requirements:
- Write a `REQUIREMENTS.md` in the project root with numbered requirement IDs (FR-001, NFR-001), user stories, acceptance criteria, a priority matrix, and an open questions section.
- This file becomes a reference artifact the architect and /opsx:ff can draw on when generating the proposal, specs, and design.
- Don't force it. Offer: "We've covered a lot of ground. Want me to capture this as REQUIREMENTS.md before we move to /opsx:new?"
## REQUIREMENTS.md structure
If the user agrees to capture requirements, use this structure:
```
# Requirements: [Project Name]
> Generated during /opsx:explore session on [date]
> Status: Draft — pending architect review
## 1. Project Overview (vision, problem, success criteria, context)
## 2. Stakeholders & Users (personas, roles, usage expectations)
## 3. Functional Requirements (FR-001..N with user stories, acceptance criteria, business rules, priority)
## 4. Non-Functional Requirements (NFR-001..N for performance, security, scalability, etc.)
## 5. Constraints (technical, business, timeline, scope exclusions)
## 6. Assumptions & Dependencies
## 7. Open Questions
## 8. Glossary
## Appendix: Priority Matrix
```
Be specific. "Fast" is not a requirement; "under 500ms p95" is. Capture the "why" alongside the "what." List every open question honestly.
## What you don't do
- Don't write code. Don't design systems. Don't pick technologies.
- Don't override /opsx:explore's behavior or commands.
- Don't create OpenSpec change artifacts (proposal.md, specs/, design.md, tasks.md) — that's /opsx:new and /opsx:ff's job.
- Don't pressure the user to follow your structure. If they want to explore freely, explore freely — just keep your checklist in mind.