🚀 lagOS-station: Enterprise-Grade Desktop Infrastructure

🏗️ Architectural Overview

The lagOS-station is built on a Modular Application-Centric architecture. Unlike standard dotfile repositories that clutter the root directory, this system uses logical separation to ensure that each component (Hyprland, Kitty, Shell) remains environment-agnostic and easily deployable via GNU Stow.

Core Philosophy: "Cattle, Not Pets"

Every component of this workstation is designed to be idempotent. By utilizing package lists and declarative symlinking, the entire engineering environment can be reproduced on a clean Fedora host in minutes.

---

🌳 Directory Structure

dotfiles/
├── config/             # Application Registry (~/.config)
│   ├── hypr/           # Hyprland WM: Window rules and UI logic
│   ├── kitty/          # GPU-accelerated terminal configuration
│   └── starship.toml   # Cross-shell prompt customization
├── git/                # Global Git provenance: Delta & GPG Signing
├── gpg/                # GPG Environment: Agent logic and TTL cache
│   └── gpg-agent.conf  # Passphrase caching and pinentry rules
├── install.sh          # Idempotent System Bootstrapper
├── nvim/               # Neovim IDE: LazyVim-based development layer
├── scripts/            # The Logic Layer: Modular orchestration
│   ├── build-paper/    # Academic/Research reporting automation
│   ├── lagos-shot/     # Technical capture and Obsidian injection
│   ├── lib/            # Python core libraries (Weather, Keybinds Parser)
│   ├── ops/            # Operational maintenance (sync-dots, repair)
│   └── wm/             # Unified Window Manager control engine
│       ├── Brightness.sh
│       ├── ClipManager.sh
│       └── ... (All UI/OSD control logic)
├── System/             # Infrastructure as Code (IaC) Provisioning
│   ├── flatpaks.txt    # Application-layer dependency list
│   └── pkglist.txt     # DNF system-package registry
└── zsh/                # Modular shell: Senior Aliases and Sentinel logic

🛠️ Key Engineering Modules

1. Global Git Provenance (/git)

The version control layer is optimized for high-velocity code review and cryptographic security.

• Delta Pager: Implements a high-performance, syntax-highlighting pager for all git, diff, and grep outputs, providing an IDE-like experience in the terminal.
• zdiff3 Conflict Resolution: Uses the "Common Ancestor" merge style to provide the baseline context during logic conflicts, essential for complex PR resolution.
• Cryptographic Identity: Enforces GPG-signed commits for all infrastructure changes to ensure non-repudiation and verified status on remote repositories.

2. The Modular Sentinel Shell (/zsh)

A modular, plugin-based shell environment designed for deterministic initialization.

• Entrypoint: .zshrc serves as the lightweight bootstrap.
• Componentized Logic (conf.d/):
  • 00-env.zsh: Infrastructure variables and SDKMAN initialization.
  • 20-security.zsh: GPG agent orchestration and environment hardening.
  • 30-sentinel.zsh: Custom shell-based telemetry and status monitors.
  • 40-plugins.zsh: Version-controlled plugin management.
  • 90-aliases.zsh: "Senior Aliases" for Git efficiency and navigation.

3. The Logic Layer (/scripts)

All application wrappers and custom research tools are managed as discrete, tracked modules in ~/dotfiles/scripts and symlinked to ~/.local/bin.

• wm/: The consolidated control engine for the Window Manager. Unifies notification management, brightness, and OSD logic, replacing legacy third-party daemons.
• lib/: A library of deterministic Python modules that provide data for shell utilities, ensuring robust exception handling.
• ops/: Operational tooling for infrastructure maintenance, including vault synchronization and dotfile state management.
• Research Tools: Specialized utilities (build-paper, lagos-shot) optimized for high-performance academic and technical documentation workflows.

4. GPG Infrastructure (/gpg)

Standardizes the cryptographic environment for secure, frictionless engineering sessions.

• Agent Orchestration: Externalized gpg-agent.conf managing a 12-hour TTL cache, balancing workstation security with operational efficiency.
• TTL Lifecycle: Implements automatic cache expiration to protect identities during inactive periods.

5. System Provisioning (/System)

Adopts an Infrastructure-as-Code (IaC) approach to workstation state management.

• Declarative Lists: Tracks system-level dependencies via pkglist.txt (DNF) and application-layer tools via flatpaks.txt.
• Bootstrapper: Utilizes install.sh for idempotent environment deployment, ensuring the lagOS-station can be reconstructed from a clean install in minutes.

📋 Prerequisites

Before deploying, ensure the core system engine, window manager, and terminal emulator are installed along with the necessary scripting and security dependencies.

On Fedora, these can be provisioned via DNF:

# 1. Install Core Infrastructure & UI
# stow: Symlink farm manager
# hyprland/kitty: Desktop environment and terminal
# zsh: The interactive shell
sudo dnf install stow hyprland kitty zsh -y

# 2. Install Development & Security Tooling
# git-delta: Syntax-highlighting pager
# gnupg2/pinentry-gnome3: Cryptographic signing and secure entry
# python3-pathlib: Required for script-based path manipulations
sudo dnf install git-delta gnupg2 pinentry-gnome3 python3-pathlib -y

# 3. Install SDKMAN! (Software Development Kit Manager)
curl -s "[https://get.sdkman.io](https://get.sdkman.io)" | bash

🚀 Deployment Workflow

This repository utilizes GNU Stow to manage symbolic links across the $HOME directory. The deployment is divided into high-priority infrastructure and application-layer configurations.

📥 Installation & Synchronization

From the root of the ~/dotfiles directory, invoke the orchestration to establish the environment:

# 1. Establish Identity & Security Infrastructure
# Links global git settings to ~/ and GPG logic to ~/.gnupg
stow -v -t ~/ git
stow -v -t ~/.gnupg gpg

# 2. Inject Modular Shell Settings
# Links .zshrc and shell-specific logic
stow -v -t ~/ zsh

# 3. Synchronize Application Configurations
# Links Hyprland, Kitty, and Starship settings
stow -v -t ~/.config config

# 4. Deploy Logic Layer (Scripts)
# Maps custom wrappers (idea, studio, lagos-shot) to the system PATH
stow -v -t ~/.local/bin scripts

# 5. Load Development Environments
# Links Neovim IDE configuration
stow -v -t ~/.config nvim

⚙️ Post-Deployment Verification

After symlinking, refresh the environment and verify the cryptographic chain:

• Shell: source ~/.zshrc
• GPG: gpgconf --kill gpg-agent (Resets the agent with the 12-hour TTL logic)
• PATH Check: which idea (Should point to ~/.local/bin/idea)
• Identity Check: git config --get user.signingkey (Should return 0D06886B74ED962C)

🕵️ DevSecOps & Best Practices

• Secret Management: No raw API keys or private tokens are stored within this repository. Environment variables are injected at runtime via local (Git ignored) files.

• Atomic Refactoring: This repository follows the Conventional Commits standard to maintain a clear audit trail of infrastructure changes.

• Clean Purge Policy: Legacy backup artifacts and corrupted reparse tags are systematically purged to reduce the system's attack surface and cognitive load.

---

Maintained as part of the lagOS-station project, 2026.