Aether.Nvim

The Ultimate Neovim Experience
Engineered for stability, performance, and strict separation of concerns.

---

1. Philosophy

Aether.nvim solves the maintenance burden of Neovim configurations. Most distributions mix their core logic with user configuration, leading to merge conflicts during updates.

Aether enforces a strict architectural boundary:

1. The Core (lua/aether/): The engine. Managed by the distribution. Read-only.
2. The User (lua/user/): The configuration. Managed by you. Never touched by updates.

It utilizes lazy.nvim for package management, snacks.nvim for UI consolidation, and blink.cmp for high-performance, Rust-based autocompletion.

2. Visuals

The interface uses AetherAmethyst, a custom theme engine designed for cognitive clarity using semantic highlighting.

Dashboard

System Health	Theme Management

---

3. Installation

Prerequisites

Ensure your system meets the following requirements before installation.

• Neovim >= 0.10.0
• Nerd Font (Required for icons. JetBrains Mono or Hack recommended).
• Git (Version control).
• Ripgrep (rg) and Fd (fd) (Required for Telescope search).
• NodeJS & npm (Required for Mason to install LSPs).
• C Compiler (GCC or Clang, required for Treesitter parsers).

Setup Steps

1. Backup your existing configuration:

   mv ~/.config/nvim ~/.config/nvim.bak
   mv ~/.local/share/nvim ~/.local/share/nvim.bak

2. Clone the repository:

   git clone https://github.com/aethersyscall/aether.nvim ~/.config/nvim

3. Launch Neovim:

   nvim

   The bootstrap script will automatically install lazy.nvim, download all plugins, compile parsers, and set up the environment. Wait for the dashboard to appear.

4. Verify Installation: Run the built-in diagnostic tool to check for missing system dependencies.

   :AetherDoctor

---

4. Configuration

You control the distribution through the lua/user/ directory.

Global Settings (lua/user/init.lua)

This file controls the behavior of the core modules.

return {
  -- Editor Behavior
  editor = {
    relative_numbers = true, -- Set false for absolute numbers
    wrap = false,            -- Toggle soft wrapping
    tab_width = 2,           -- Space indentation
  },

  -- UI & Aesthetics
  ui = {
    transparency = false,    -- Toggle transparent background
    animations = true,       -- Toggle cursor animations
  },

  -- Language Server Protocol
  lsp = {
    -- Define which servers Mason should auto-install.
    -- Common options: "lua_ls", "ts_ls", "pyright", "rust_analyzer", "gopls", "clangd"
    servers = { 
        "lua_ls", 
        "ts_ls", 
        "pyright" 
    },
    
    -- Formatting behavior
    formatting = {
      format_on_save = true,
      timeout_ms = 1000,
    },
  },
}

Adding/Modifying Plugins (lua/user/overrides.lua)

Use this file to add new plugins or override the configuration of existing ones using the lazy.nvim spec.

return {
  -- Example 1: Add a new plugin
  {
    "zbirenbaum/copilot.lua",
    cmd = "Copilot",
    event = "InsertEnter",
    config = function()
        require("copilot").setup({})
    end,
  },

  -- Example 2: Modify an existing core plugin
  {
    "nvim-neo-tree/neo-tree.nvim",
    opts = {
      window = { width = 40 }, -- Change width from default 30
    },
  },
}

Custom Keymaps (lua/user/keymaps.lua)

Define your own keybindings here.

local map = vim.keymap.set
local opts = { noremap = true, silent = true }

-- Example: Map Leader+p to paste from system clipboard
map("n", "<leader>p", "\"+p", opts)

---

5. Keybindings

The Leader key is mapped to <Space>.

General

Key	Action	Description
<Space> w	Save	Fast save file
<Space> qq	Quit	Quit all windows
jj	Escape	Exit Insert Mode quickly
;	Command	Enter command mode (maps to :)
<Space> un	Notifications	Dismiss all notifications

Navigation

Key	Action	Description
<C-h/j/k/l>	Window Focus	Move between splits
<C-Arrow>	Window Resize	Resize current split
<S-h>	Buffer Prev	Cycle to previous buffer
<S-l>	Buffer Next	Cycle to next buffer
<Space> bd	Buffer Delete	Close current buffer

File Explorer (Neo-tree)

Key	Action	Description
<Space> e	Toggle	Open/Close Explorer
l	Open	Open file or expand directory
h	Close	Collapse directory
H (Shift+h)	Up	Navigate up to parent directory
L (Shift+l)	CD	Context Switch: Change root to directory

Search (Telescope)

Key	Action	Description
<Space> ff	Find Files	Fuzzy find files in project
<Space> fw	Live Grep	Search text inside files
<Space> fr	Recent	Open recent files history
<Space> fb	Buffers	Search open buffers

Coding & LSP

Key	Action	Description
gd	Definition	Go to definition
gr	References	Find references
K	Hover	Show documentation
<Space> cr	Rename	Rename symbol
<Space> ca	Action	Code action
<Space> cf	Format	Format file
]d / [d	Diagnostics	Jump to next/prev error

---

6. Architecture

Aether is structured to ensure updates are safe and predictable.

aether.nvim/
├── init.lua                 # Bootstrapper & Performance Flags
├── lazy-lock.json           # Plugin Version Lockfile
├── lua/
│   ├── aether/              # CORE ENGINE (Read-Only)
│   │   ├── config.lua       # Configuration Merger
│   │   ├── core/            # Autocommands, Options, Keymaps
│   │   ├── health/          # Doctor & Backup Tools
│   │   └── modules/         # Plugin Specifications
│   └── user/                # USER CONFIG (Writable)
│       ├── init.lua         # Global Settings
│       ├── keymaps.lua      # Custom Keybindings
│       └── overrides.lua    # Plugin Overrides

---

7. Maintenance

Aether includes custom commands to manage the distribution.

• :AetherUpdate - Pulls the latest core code, syncs plugins to the lockfile, and updates parsers/tools.
• :AetherDoctor - Checks your system environment and reports missing dependencies or misconfigurations.
• :AetherBackup - Creates a timestamped snapshot of your lua/user folder inside lua/user/snapshots/.

---

8. License

Copyright (c) 2025 AetherSyscall

Licensed under the Apache License, Version 2.0. See LICENSE for details.

---

Enjoy the ULTIMATE NEOVIM EXPERIENCE.