# CLI-First Arch Gaming OS

> Performance-first Linux gaming appliance with a unified launcher backend

| **Status**         | Implementation — phases 0–4 complete; phase 5 ready |
|--------------------|----------------------------------------------------|
| **Version**        | 0.23                                               |
| **Created**        | July 17, 2026                                      |
| **Document type**  | Living project specification                       |
| **Current target** | Purpose-built, performance-focused gaming distribution |

**Purpose:** Preserve project context, distinguish requirements from proposals, record decisions, and provide a controlled place to update the plan as it evolves.

## How to use this document

- Treat items marked Required or Confirmed as current project constraints.
- Treat Proposed items as design candidates that still require validation.
- Record significant changes in both the Decision Log and Change Log.
- Do not silently convert an open question into a requirement.

### Mandatory spec-change integrity procedure

Every planning addition, removal, or change must be checked against the complete current numbered specification before it is saved. This applies equally to new features, small wording changes, changed priorities, deferred work, and release-scope changes.

For each change:

1. Identify the affected requirement IDs, decisions, open questions, roadmap phases, acceptance criteria, risks, architecture contracts, and cross-file references.
2. Search all numbered topic files for the affected terms and concepts; do not rely only on the file being edited.
3. Verify that status language is consistent: Required, Confirmed, Proposed, Deferred, Post-v1, and Open must not describe the same item incompatibly.
4. Verify release boundaries and dependency order. A deferred or post-v1 capability must not remain a version 1 acceptance criterion or be required by an earlier roadmap phase.
5. Verify that examples, commands, schemas, and component descriptions do not promise capabilities excluded elsewhere.
6. Update the requirement table, decision log, open questions, roadmap, acceptance criteria, risks, change log, version markers, and index wherever the change materially affects them.
7. Run structural checks for duplicate requirement or decision IDs, stale version markers, and broken internal links.
8. If the intended resolution is already established by a confirmed decision, correct all affected statements consistently. If two or more plausible resolutions would change project scope, architecture, release timing, compatibility, or user-visible behavior, stop and ask the project owner for clarification before recording a choice.

The historical archive is evidence, not a second source of truth. Do not rewrite it to make old versions appear current.

## 1. Executive summary

The project, currently using the temporary internal codename **Project Kiln**, will explore and eventually prototype a purpose-built Arch Linux–based gaming distribution optimized exclusively for gaming. It presents a fullscreen terminal as its default shell, omits a conventional desktop environment, and launches Linux and Windows games through a simple unified command. The normal gaming mode will run inside a persistent, minimal graphical session so launchers, dialogs, frontends, and games can open without constructing and destroying a display environment for every operation. A true TTY-only target remains available for recovery and deliberate headless use.

Performance, predictable behavior, recovery, and clear diagnostics take priority over visual polish. USB and Bluetooth controller support are core requirements. Version 1 remains CLI-first and DE-free, but not display-server-free: the graphical foundation stays available while heavyweight provider interfaces remain lazy by default. After version 1, Pegasus Frontend will be the first reference frontend for a controller-driven interface. It will initially be integrated without a fork by generating metadata whose launch commands call the shared backend CLI.

> **Recommended delivery strategy:** Build and validate a reproducible gaming layer on minimal Arch first. Create a custom installation ISO only after the execution model, controllers, provider adapters, and recovery path work reliably.

### 1.1 Codename and future naming

- **Project Kiln** is a temporary development codename, not the intended public product name.
- User-facing branding must be centralized in a small, documented set of metadata or configuration files rather than duplicated throughout source code.
- Internal crate, module, protocol, schema, and configuration identifiers should use stable functional names where practical. They must not embed the codename merely for decoration.
- The final names of the distribution, launcher CLI, reusable core, packages, configuration namespace, and IPC endpoints should be selected as one related naming system. Technical naming is intentionally deferred until the public project name is chosen.
- Until then, repository-local development uses the temporary Kiln family: `kiln` for the single CLI command and functional component labels such as `kiln-core`, `kiln-cli`, `kiln-session`, and `kiln-adapter-*`. These names inherit the codename's temporary status.
- Development may proceed with clearly marked, repository-local functional labels. Temporary labels must not be installed globally, published as packages or crates, or exposed as stable compatibility promises.
- Places that require a project-specific identifier must be documented in a rename checklist and covered by an automated repository scan.
- Selecting the final name will trigger one deliberate, mechanical rename before stable public compatibility commitments. The source is not required to retain the Kiln codename permanently.

## 2. Vision and problem statement

### 2.1 Vision

Provide a gaming-focused Linux appliance that feels closer to the directness of a console or old text-first gaming system than a general-purpose desktop, while retaining Arch Linux transparency, package access, and user control.

### 2.2 Problem

Linux gaming is fragmented across launchers, compatibility runtimes, prefixes, compositors, overlays, and provider-specific metadata. Existing gaming distributions reduce setup work but generally center a graphical shell, bundle more software, or conceal launch details. A minimal system can provide a smaller and more predictable operating environment, but only if it avoids replacing desktop complexity with brittle shell-script complexity.

### 2.3 Product hypothesis

A unified backend and CLI can make a CLI-presented gaming system practical while a minimal compositor supplies the graphical plumbing modern games and launchers expect. The same backend can support terminal, controller, desktop, web, or third-party frontends without coupling game management to one interface.

## 3. Goals, non-goals, and principles

### 3.1 Goals

- Enter a minimal graphical gaming session whose default visible shell is a fullscreen terminal, with no conventional desktop environment required.
- Launch installed games by human-readable name through a consistent command.
- Support Steam, Lutris, Heroic-managed Epic, GOG, and Amazon libraries, native games, and custom Windows games using appropriate Wine/Proton runtimes, including UMU where suitable. Third-party vendor launchers are post-v1.
- Provide reliable USB and Bluetooth controller operation, hotplugging, reconnection, and diagnostics.
- Keep a minimal graphical foundation available for launchers and games while retaining a true TTY recovery path.
- Optimize for frametime consistency, latency, stability, and low background overhead.
- Keep launch behavior inspectable, reproducible, and recoverable.
- Preserve a clean path to future lightweight desktop and controller-driven frontends.

### 3.2 Non-goals for version 1

- Building a general-purpose desktop distribution.
- Matching every Steam Deck or SteamOS user-interface feature.
- Supporting every launcher operation through the unified API on day one.
- Bypassing unsupported anti-cheat, DRM, platform restrictions, or Windows-only kernel components.
- Guaranteeing higher average FPS than every conventional Arch installation.
- Supporting handheld hardware, touch-first controls, or immutable system images initially.

### 3.3 Guiding principles

| **Principle**                                         | **Meaning**                                                                                                      |
|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| Measure, do not mythologize                           | A tuning change belongs only when benchmarking or reliability evidence supports it.                              |
| CLI is the interface, not the graphics implementation | The default shell may look like a console while running inside a persistent minimal Wayland/Xwayland or Xorg session. |
| Adapters own provider details                         | The core consumes normalized capabilities rather than embedding every launcher's internals.                      |
| Safe fallback beats clever failure                    | Every optimized path needs a simpler recovery or diagnostic path.                                                |
| Minimal does not mean incomplete                      | Fonts, portals, 32-bit libraries, udev rules, audio, and authentication dependencies are included when required. |
| Modularity over monoliths                             | Install profiles and packages should allow components to be added or removed cleanly.                            |
| Project frontends are replaceable clients             | No project-integrated catalogue frontend owns provider discovery, normalized identity, launch logic, or session policy; provider-native clients retain their own native behavior. |
| Upstream before forks                                 | Integrate and contribute upstream before accepting permanent maintenance of a project-specific frontend fork.     |

## 4. Confirmed requirements

| **ID** | **Status** | **Area**       | **Requirement**                                                                                                            |
|--------|------------|----------------|----------------------------------------------------------------------------------------------------------------------------|
| R-001  | Required   | Base system    | Arch Linux–based and reconstructable from recorded repository state, package versions, project configuration, and build inputs; bit-for-bit reproducibility is a later hardening goal. |
| R-002  | Required   | User interface | Normal gaming mode presents a fullscreen terminal inside a persistent minimal graphical session; no conventional DE is required. |
| R-003  | Required   | Performance    | Performance and frametime consistency are primary design priorities.                                                       |
| R-004  | Required   | Controllers    | USB and Bluetooth controllers are supported as core functionality.                                                         |
| R-005  | Required   | Providers      | Version 1 supports Steam, Lutris, Heroic-managed Epic, GOG, and Amazon libraries, native games, and custom Windows games; each store is a separate adapter/capability target, and UMU is an execution runtime rather than a library provider. |
| R-006  | Required   | Launch UX      | A game can be launched by typing its name or selecting it from a searchable CLI/TUI list.                                  |
| R-007  | Required   | Gaming tools   | GameMode, Gamescope, MangoHud/MangoApp, Proton/Wine tooling, and relevant diagnostics are included.                        |
| R-008  | Required   | Lifecycle      | Closing a game, launcher, or frontend returns to the existing session shell without rebuilding the graphical environment.  |
| R-009  | Required   | Extensibility  | The unified backend must not depend on a future desktop frontend.                                                          |
| R-010  | Required   | Recovery       | A true TTY-only mode remains available for recovery, diagnostics, and explicit user choice.                               |
| R-011  | Required   | Development    | Use libvirt/QEMU for routine development and disposable testing; validate hardware behavior and performance on bare metal. |
| R-012  | Required   | Architecture   | The CLI and all project-integrated catalogue frontends consume the same normalized backend behavior rather than implementing provider launch logic independently. Provider-native interfaces such as Steam Big Picture may retain their native library and launch behavior when opened explicitly. |
| R-013  | Required   | Frontend       | The initial visible shell may be the terminal, Steam Big Picture, another configured frontend, or a custom command, and this policy is changeable after installation. Pegasus becomes a supported reference option after version 1. |
| R-014  | Post-v1    | Pegasus        | After version 1, support upstream Pegasus as the first reference controller frontend without requiring a fork.    |
| R-015  | Required   | Profiles       | Lean is the default runtime profile; users may instead keep selected launchers resident or autostart a frontend.           |
| R-016  | Required   | Providers      | Provider adapters use the lightest reliable supported path and advertise actual capabilities instead of assuming every provider is symmetrical. |
| R-017  | Required   | Windowing      | Users can quickly focus or switch among the terminal, resident launchers, frontends, and a running game.                   |
| R-018  | Required   | Lifecycle      | The system tracks game lifetime as reliably as each provider permits so temporary performance, sleep-inhibition, logging, and cleanup policy can follow the game; ordinary operation does not automatically close provider clients after play. |
| R-019  | Post-v1    | Providers      | Third-party vendor launchers such as Battle.net, EA App, Ubisoft Connect, and Rockstar are added after version 1 through tested managed-prefix integrations. |
| R-020  | Required   | Input tooling  | Use Bluetui as the standard interactive Bluetooth TUI; retain structured project-owned diagnostics and automation, and offer Blueman as the optional desktop Bluetooth GUI. |
| R-021  | Required   | Installation   | Build the eventual guided installer on archinstall using a maintained project profile/configuration and, only where necessary, a pinned local plugin or custom script; do not reimplement partitioning, encryption, account creation, or base Arch installation. |
| R-022  | Optional   | Recovery       | Offer a Btrfs installation profile using Snapper and pacman transaction hooks; do not require Btrfs for the default or filesystem-neutral installation path. |
| R-023  | Post-v1    | Frontends      | Evaluate OpenGamepadUI after version 1 as an additional replaceable controller frontend without transferring backend authority to its internal catalog. |
| R-024  | Required   | Security       | Provider data, custom manifests, artwork, and frontend descriptors are untrusted input; ordinary discovery and launch remain unprivileged, argument-safe, path-confined, and covered by adversarial tests. |
| R-025  | Required   | Packaging      | Every shipped non-Arch component has an explicit source, pinned build or release input, license/provenance record, update owner, and removal or fallback plan before it enters a release profile. |
| R-026  | Required   | Platform       | Version 1 supports x86_64 UEFI systems; legacy BIOS and non-x86 architectures are outside the v1 support boundary. |
| R-027  | Required   | Users          | Version 1 is a single-local-gaming-user appliance. Per-user state, services, paths, identities, and permissions must preserve a clean path to post-v1 multi-user libraries, saves, credentials, and profiles. |
| R-028  | Required   | Graphics       | AMD and NVIDIA are release-blocking v1 GPU/driver families; Intel graphics are tested where practical and labeled best-effort until representative hardware coverage exists. |
| R-029  | Required   | Configuration  | User-editable project configuration uses versioned TOML with generated commented defaults and equivalent CLI operations; JSON remains the machine-output and contract encoding. |