🚀 archConfig

A unified, modular, cross-distribution dotfiles and bootstrap system. Designed to deliver an identical, high-performance developer workflow across Fedora, Arch Linux, Ubuntu, macOS, and OmArchy without configuration fragmentation.

---

🏗️ Layered Architecture

The repository separates universal developer tooling from desktop environments, distro-specific package installers, and troubleshooting runbooks:

graph TD
    Sync["🚀 sync.sh (Auto-Detector & Linker)"]
    Core["🌐 core/<br/>(Universal Shell, Neovim, Ghostty, Herdr, Starship, Yazi)"]
    Desktop["🖥️ desktop/<br/>(GNOME, KDE Plasma, Hyprland Lua/Classic)"]
    Distros["📦 distros/<br/>(Fedora, Arch, Ubuntu, macOS, OmArchy)"]
    Troubleshoot["🩺 troubleshoot/<br/>(GRUB, Dual-Boot, Toolchain fixes)"]
    
    Sync --> Core
    Sync --> Desktop
    Sync --> Distros
    Sync --> Troubleshoot

Loading

Layer	Directory	Purpose
Core Configs	core/config/	Universal application configurations (nvim, ghostty, herdr, leaf, starship.toml, yazi, fastfetch, fontconfig).
Core Home	core/home/	Universal shell & Git dotfiles (.bashrc, .bashrc.d/, .bash_profile, .profile, .zshrc, .inputrc, .vimrc, .gitconfig).
Core Scripts & Setup	core/scripts/	Universal cross-platform setup (core/setup.sh), developer tooling (setup_git.sh for Git/SSH profiles, setup_shell_dependencies.sh for unattended curl installation of starship, leaf, zoxide, fzf, lazydocker, herdr, etc.).
Desktop Layer	desktop/	Modular DE configs: GNOME extensions/dconf, KDE Plasma shortcuts, and Hyprland (Lua & classic).
Distro Layer	distros/	Package installation scripts, systemd unit files, and hardware optimizations per distribution.
Troubleshooting	troubleshoot/	Centralized runbooks and scripts for bootloader recovery, GPU switching, and Git credential/SSH fixes.
AI Skills	.agents/skills/	Rules for AI agents (archconfig-guard) to guarantee zero cross-distro breakage and maintain docs.

---

⚡ Quick Start

1. Clone the repository

git clone --depth 1 https://github.com/Codesmith28/archConfig.git ~/archConfig
cd ~/archConfig

Tip

Using --depth 1 creates a shallow clone (~2 MB) for instant bootstrapping on fresh installs.

2. Synchronize dotfiles

The root synchronizer automatically detects your operating system and desktop environment:

# Preview symlink actions (safe dry-run)
./sync.sh --dry-run

# Apply symlinks
./sync.sh

Manual Overrides

You can explicitly override detection when setting up a specific environment:

# Fedora with GNOME
./sync.sh --distro fedora --de gnome

# Arch with Hyprland
./sync.sh --distro arch --de hyprland

# macOS Workstation
./sync.sh --distro mac --de none

---

🛠️ Toolchains & Developer Features

Dynamic Compiler Discovery (C++26)

No more hardcoded compiler names or version mismatches between Homebrew and Linux package managers:

• Dynamically discovers the newest installed GCC/G++ by scanning candidate system directories without hardcoded version ranges.
• Automatically exports $CC, $CXX, and provides modern C++ runner helper:

  run_cpp solution.cpp    # Compiles with -std=c++26 -O2 -Wall using newest available g++

• Neovim's clangd LSP and assistant.lua (competitive programming runner) dynamically detect compiler versions and system include paths across platforms.

Neovim Setup (core/config/nvim)

• Base: Modern LazyVim distribution.
• Python: Integrated with pyrefly fast type-checker and language server.
• Java: Automatic resolve_java_home() supporting macOS Homebrew, Fedora, Arch, and Ubuntu JDK installations.
• C/C++: Clangd configured with universal query-driver for complete standard library intellisense.
• Competitive Programming: Integrated test-case assistant with hotkeys for fast problem verification.

Universal Git & Directory-Scoped SSH Setup (core/scripts/setup_git.sh)

Cross-distro vanilla Git configuration with automated SSH routing and profile isolation:

• Base Config: High-efficiency defaults (pull.rebase = true, push.autoSetupRemote = true, diff.algorithm = histogram, rerere.enabled = true, intuitive aliases).
• Push Interception: Automatically rewrites GitHub HTTPS pushes to SSH via pushInsteadOf to prevent credential prompts.
• Multi-Profile Isolation: Configure directory-scoped identities (e.g. ~/work, ~/uni) with dedicated SSH keys stored directly in ~/.ssh/ (e.g. id_ed25519_work, id_ed25519_uni) and isolated via includeIf and sshCommand, while retaining the default key (id_ed25519 / id_rsa) everywhere else.
• Run Setup:

  # Interactive setup:
  ./core/scripts/setup_git.sh
  
  # Create a directory-scoped profile:
  ./core/scripts/setup_git.sh --profile work --profile-name "Work Name" --profile-email "user@work.com"

Universal Shell Productivity (core/setup.sh)

Automated, unattended bootstrap for essential shell navigation and fuzzy-search tools (automatically executed during ./sync.sh across all Mac and Linux environments):

• zoxide: Installs via the official script into ~/.local/bin (already exported in ~/.profile). Replaces standard cd with smart scoring (z, zi).
• fzf: Clones junegunn/fzf into ~/.fzf and runs with --key-bindings --completion --no-update-rc to generate completion scripts without dirtying tracked dotfiles (.bashrc / .zshrc).
• Run Setup Standalone:

  # Standalone core setup:
  ./core/setup.sh
  
  # Force update:
  ./core/setup.sh --update

---

📦 Distribution Bootstrapping

When setting up a fresh machine, run the setup scripts inside distros/:

Fedora Workstation

cd distros/fedora
# Install core packages, RPM Fusion, and developer tools
bash setup.sh

Arch Linux (KDE, GNOME, or Hyprland)

cd distros/arch
# Install official repos, AUR packages, and hardware services
bash setup.sh

Ubuntu (Desktop or Server)

cd distros/ubuntu
# Install system packages and optimizations
bash setup.sh

macOS (Darwin)

cd distros/mac
# Install Homebrew formulas, casks, and tooling
bash setup.sh

---

🩺 Troubleshooting Runbooks

Common hardware and dual-boot solutions are documented in troubleshoot/:

• KDE Plasma Cross-Distro Setup Guide: Resolving active shortcut persistence (kglobalshortcutsrc), Plasma 6 migration, VM/SSH session detection, default terminal routing, and window management across distros.
• GNOME Cross-Distro Setup Guide: Resolving DBus session attachment, GSettings schema compilation, Ubuntu dock conflicts, and shortcut collision elimination across distros.
• Restoring GRUB Bootloader: Reinstalling EFI entries after Windows updates or BIOS resets; fixing missing Windows dual-boot entries with os-prober.
• Automated GRUB Repair Script: Single-command script to reinstall GRUB on UEFI systems.
• Fixing <bits/stdc++.h> on macOS: Resolving missing C++ bits headers on Darwin systems.

---

🤖 AI Assistant Guidelines

This repository includes an Antigravity Agent Skill in .agents/skills/archconfig-guard. When using AI coding assistants in this repo:

1. Never hardcode compiler versions or platform-exclusive commands in core/.
2. Never break existing symlinks on live systems; use backward-compatible shims when refactoring paths.
3. Always document new solutions in troubleshoot/ whenever resolving a platform-specific bug.

For detailed migration history and architectural rationale, consult MIGRATION.md.