docs: rewrite README with full usage and maintenance guide

Replaces the generic kickstart README with a personalized reference covering: - Requirements and installation - Plugin inventory - Full keymap reference (general, telescope, LSP, AI agent) - ThePrimeagen/99 usage (prompts, AGENT.md, skill files, debugging) - Maintenance guide (adding plugins, LSPs, formatters, updating) - Optional extras reference Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-19 09:43:16 -05:00 · 2026-02-19 09:43:16 -05:00 · 9a5d3cefbb
parent 38e50ed345
commit 9a5d3cefbb
1 changed files with 264 additions and 276 deletions
--- a/README.md
+++ b/README.md
@ -1,322 +1,310 @@
-# kickstart.nvim
+# nvim

-## Introduction
+Personal Neovim configuration based on [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim).
+Single-file, fully documented, no magic.

-A starting point for Neovim that is:
+---

-* Small
-* Single-file
-* Completely Documented
+## Requirements

-**NOT** a Neovim distribution, but instead a starting point for your configuration.
+| Dependency | Purpose |
+|---|---|
+| Neovim `>= 0.10` (latest stable recommended) | Runtime |
+| `git`, `make`, `gcc` / `clang` | Plugin builds |
+| [ripgrep](https://github.com/BurntSushi/ripgrep) | Live grep in Telescope |
+| [fd-find](https://github.com/sharkdp/fd) | File finder |
+| `claude` CLI (Claude Code) | AI agent ([99](#ai-agent--99)) |
+| Clipboard tool (`xclip`, `xsel`, `win32yank`) | System clipboard sync |
+
+Install Neovim on WSL (Ubuntu/Debian):
+
+```sh
+sudo add-apt-repository ppa:neovim-ppa/unstable -y
+sudo apt update
+sudo apt install make gcc ripgrep unzip git xclip neovim
+```
+
+---

 ## Installation

-### Install Neovim
-
-Kickstart.nvim targets *only* the latest
-['stable'](https://github.com/neovim/neovim/releases/tag/stable) and latest
-['nightly'](https://github.com/neovim/neovim/releases/tag/nightly) of Neovim.
-If you are experiencing issues, please make sure you have at least the latest
-stable version. Most likely, you want to install neovim via a [package
-manager](https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-package).
-To check your neovim version, run `nvim --version` and make sure it is not
-below the latest
-['stable'](https://github.com/neovim/neovim/releases/tag/stable) version. If
-your chosen install method only gives you an outdated version of neovim, find
-alternative [installation methods below](#alternative-neovim-installation-methods).
-
-### Install External Dependencies
-
-External Requirements:
- Basic utils: `git`, `make`, `unzip`, C Compiler (`gcc`)
- [ripgrep](https://github.com/BurntSushi/ripgrep#installation),
-  [fd-find](https://github.com/sharkdp/fd#installation)
- Clipboard tool (xclip/xsel/win32yank or other depending on the platform)
- A [Nerd Font](https://www.nerdfonts.com/): optional, provides various icons
-  - if you have it set `vim.g.have_nerd_font` in `init.lua` to true
- Emoji fonts (Ubuntu only, and only if you want emoji!) `sudo apt install fonts-noto-color-emoji`
- Language Setup:
-  - If you want to write Typescript, you need `npm`
-  - If you want to write Golang, you will need `go`
-  - etc.
-
-> [!NOTE]
-> See [Install Recipes](#Install-Recipes) for additional Windows and Linux specific notes
-> and quick install snippets
-
-### Install Kickstart
-
-> [!NOTE]
-> [Backup](#FAQ) your previous configuration (if any exists)
-
-Neovim's configurations are located under the following paths, depending on your OS:
-
-| OS | PATH |
-| :- | :--- |
-| Linux, MacOS | `$XDG_CONFIG_HOME/nvim`, `~/.config/nvim` |
-| Windows (cmd)| `%localappdata%\nvim\` |
-| Windows (powershell)| `$env:LOCALAPPDATA\nvim\` |
-
-#### Recommended Step
-
-[Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) this repo
-so that you have your own copy that you can modify, then install by cloning the
-fork to your machine using one of the commands below, depending on your OS.
-
-> [!NOTE]
-> Your fork's URL will be something like this:
-> `https://github.com/<your_github_username>/kickstart.nvim.git`
-
-You likely want to remove `lazy-lock.json` from your fork's `.gitignore` file
-too - it's ignored in the kickstart repo to make maintenance easier, but it's
-[recommended to track it in version control](https://lazy.folke.io/usage/lockfile).
-
-#### Clone kickstart.nvim
-
-> [!NOTE]
-> If following the recommended step above (i.e., forking the repo), replace
-> `nvim-lua` with `<your_github_username>` in the commands below
-
-<details><summary> Linux and Mac </summary>
-
 ```sh
-git clone https://github.com/nvim-lua/kickstart.nvim.git "${XDG_CONFIG_HOME:-$HOME/.config}"/nvim
-```
+# Back up any existing config first
+mv ~/.config/nvim ~/.config/nvim.bak

-</details>
+# Clone this repo
+git clone https://github.com/0xWheatyz/kickstart.nvim.git ~/.config/nvim

-<details><summary> Windows </summary>
-
-If you're using `cmd.exe`:
-
-```
-git clone https://github.com/nvim-lua/kickstart.nvim.git "%localappdata%\nvim"
-```
-
-If you're using `powershell.exe`
-
-```
-git clone https://github.com/nvim-lua/kickstart.nvim.git "${env:LOCALAPPDATA}\nvim"
-```
-
-</details>
-
-### Post Installation
-
-Start Neovim
-
-```sh
+# Launch — Lazy will bootstrap and install all plugins automatically
 nvim
 ```

-That's it! Lazy will install all the plugins you have. Use `:Lazy` to view
-the current plugin status. Hit `q` to close the window.
+Run `:Lazy` to check plugin status. Run `:checkhealth` if anything looks wrong.

-#### Read The Friendly Documentation
+---

-Read through the `init.lua` file in your configuration folder for more
-information about extending and exploring Neovim. That also includes
-examples of adding popularly requested plugins.
+## Structure

-> [!NOTE]
-> For more information about a particular plugin check its repository's documentation.
+Everything lives in a single file:

+```
+~/.config/nvim/
+├── init.lua          ← entire config (options, keymaps, plugins)
+└── lua/
+    ├── custom/plugins/   ← drop extra plugin files here (optional)
+    └── kickstart/plugins/    ← optional bundled extras (debug, neo-tree, etc.)
+```

-### Getting Started
+The config is intentionally kept in one file so every line is readable
+top-to-bottom without jumping between modules.

-[The Only Video You Need to Get Started with Neovim](https://youtu.be/m8C0Cq9Uv9o)
+---

-### FAQ
+## Plugins

-* What should I do if I already have a pre-existing Neovim configuration?
-  * You should back it up and then delete all associated files.
-  * This includes your existing init.lua and the Neovim files in `~/.local`
-    which can be deleted with `rm -rf ~/.local/share/nvim/`
-* Can I keep my existing configuration in parallel to kickstart?
-  * Yes! You can use [NVIM_APPNAME](https://neovim.io/doc/user/starting.html#%24NVIM_APPNAME)`=nvim-NAME`
-    to maintain multiple configurations. For example, you can install the kickstart
-    configuration in `~/.config/nvim-kickstart` and create an alias:
-    ```
-    alias nvim-kickstart='NVIM_APPNAME="nvim-kickstart" nvim'
-    ```
-    When you run Neovim using `nvim-kickstart` alias it will use the alternative
-    config directory and the matching local directory
-    `~/.local/share/nvim-kickstart`. You can apply this approach to any Neovim
-    distribution that you would like to try out.
-* What if I want to "uninstall" this configuration:
-  * See [lazy.nvim uninstall](https://lazy.folke.io/usage#-uninstalling) information
-* Why is the kickstart `init.lua` a single file? Wouldn't it make sense to split it into multiple files?
-  * The main purpose of kickstart is to serve as a teaching tool and a reference
-    configuration that someone can easily use to `git clone` as a basis for their own.
-    As you progress in learning Neovim and Lua, you might consider splitting `init.lua`
-    into smaller parts. A fork of kickstart that does this while maintaining the
-    same functionality is available here:
-    * [kickstart-modular.nvim](https://github.com/dam9000/kickstart-modular.nvim)
-  * Discussions on this topic can be found here:
-    * [Restructure the configuration](https://github.com/nvim-lua/kickstart.nvim/issues/218)
-    * [Reorganize init.lua into a multi-file setup](https://github.com/nvim-lua/kickstart.nvim/pull/473)
+| Plugin | Purpose |
+|---|---|
+| `folke/lazy.nvim` | Plugin manager |
+| `NMAC427/guess-indent.nvim` | Auto-detect indentation |
+| `lewis6991/gitsigns.nvim` | Git gutter signs |
+| `folke/which-key.nvim` | Keymap hints popup |
+| `nvim-telescope/telescope.nvim` | Fuzzy finder |
+| `neovim/nvim-lspconfig` + `mason-org/mason.nvim` | LSP + auto-install |
+| `stevearc/conform.nvim` | Formatting on save |
+| `saghen/blink.cmp` + `L3MON4D3/LuaSnip` | Completion + snippets |
+| `folke/tokyonight.nvim` | Colorscheme (tokyonight-night) |
+| `folke/todo-comments.nvim` | Highlight TODO/FIXME/NOTE |
+| `nvim-mini/mini.nvim` | Text objects, surround, statusline |
+| `nvim-treesitter/nvim-treesitter` | Syntax highlighting |
+| `ThePrimeagen/99` | AI agent |

-### Install Recipes
+---

-Below you can find OS specific install instructions for Neovim and dependencies.
+## Keymaps

-After installing all the dependencies continue with the [Install Kickstart](#install-kickstart) step.
+`<leader>` is `<Space>`.

-#### Windows Installation
+### General

-<details><summary>Windows with Microsoft C++ Build Tools and CMake</summary>
-Installation may require installing build tools and updating the run command for `telescope-fzf-native`
+| Key | Action |
+|---|---|
+| `<Esc>` | Clear search highlight |
+| `<C-h/j/k/l>` | Move between splits |
+| `<leader>q` | Open diagnostic quickfix list |
+| `<leader>f` | Format buffer |
+| `<leader>th` | Toggle inlay hints (when LSP supports it) |

-See `telescope-fzf-native` documentation for [more details](https://github.com/nvim-telescope/telescope-fzf-native.nvim#installation)
+### Telescope (Search)

-This requires:
+| Key | Action |
+|---|---|
+| `<leader>sf` | Find files |
+| `<leader>sg` | Live grep |
+| `<leader>sw` | Grep word under cursor (or selection) |
+| `<leader>sh` | Search help tags |
+| `<leader>sk` | Search keymaps |
+| `<leader>sd` | Search diagnostics |
+| `<leader>sr` | Resume last search |
+| `<leader>s.` | Recent files |
+| `<leader>sc` | Search commands |
+| `<leader>sn` | Search Neovim config files |
+| `<leader>/` | Fuzzy search current buffer |
+| `<leader>s/` | Live grep in open files |
+| `<leader><leader>` | Open buffer list |

- Install CMake and the Microsoft C++ Build Tools on Windows
+### LSP (active when a language server is attached)
+
+| Key | Action |
+|---|---|
+| `grn` | Rename symbol |
+| `gra` | Code action |
+| `grD` | Go to declaration |
+| `grd` | Go to definition |
+| `grr` | Find references |
+| `gri` | Go to implementation |
+| `grt` | Go to type definition |
+| `gO` | Document symbols |
+| `gW` | Workspace symbols |
+
+### AI Agent (99)
+
+| Key | Mode | Action |
+|---|---|---|
+| `<leader>9v` | visual | Send selection as AI request |
+| `<leader>9s` | normal | Open search / ask AI |
+| `<leader>9x` | normal | Cancel all in-flight requests |
+
+In the 99 prompt:
+- `@<filename>` — fuzzy-attach a project file as context
+- `#<rulename>` — autocomplete and attach a rule/skill file
+
+---
+
+## AI Agent — 99
+
+[ThePrimeagen/99](https://github.com/ThePrimeagen/99) is a Neovim-native AI
+agent that delegates to a CLI backend. This config uses **Claude Code**
+(`claude` CLI) as the provider.
+
+### Prerequisites
+
+Claude Code must be installed and authenticated:
+
+```sh
+npm install -g @anthropic-ai/claude-code
+claude login
+```
+
+### How it works
+
+1. Open any file and make a visual selection (or just use `<leader>9s` for a
+   free-form prompt).
+2. Press `<leader>9v` (visual) or `<leader>9s` (normal) to open the prompt.
+3. Describe what you want. Use `@file` to attach context, `#rule` to attach a
+   skill/rule doc.
+4. 99 streams the response back into the buffer as virtual text, then applies
+   replacements inline.
+5. Press `<leader>9x` at any time to abort.
+
+### Debugging
+
+```vim
+:lua require("99").view_logs()
+```
+
+Navigate log history with `_99.prev_request_logs()` / `_99.next_request_logs()`.
+
+### AGENT.md (optional)
+
+Drop an `AGENT.md` file in any directory (or project root) to give 99
+project-specific context. It is automatically injected into every request
+made from files under that directory.
+
+```
+project-root/
+└── AGENT.md    ← describes conventions, architecture, rules
+```
+
+### Skill files (optional)
+
+Custom rule files enable `#<skill>` autocompletion in the prompt. Each skill
+is a folder with a `SKILL.md` inside:
+
+```
+~/.config/nvim/skills/
+└── my-rule/
+    └── SKILL.md
+```
+
+Point 99 at them by adding to `completion.custom_rules` in the setup call
+inside `init.lua`.
+
+---
+
+## Maintaining the Config
+
+All changes happen in `~/.config/nvim/init.lua`. The file is organized in this order:
+
+1. **Options** — `vim.o.*` / `vim.opt.*` settings
+2. **Keymaps** — `vim.keymap.set(...)` for built-in bindings
+3. **Autocommands** — `vim.api.nvim_create_autocmd(...)`
+4. **Plugin specs** — passed to `require('lazy').setup({...})`
+
+### Adding a plugin
+
+Add an entry anywhere inside the `require('lazy').setup({ ... })` table:

 ```lua
-{'nvim-telescope/telescope-fzf-native.nvim', build = 'cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release && cmake --install build --prefix build' }
-```
-</details>
-<details><summary>Windows with gcc/make using chocolatey</summary>
-Alternatively, one can install gcc and make which don't require changing the config,
-the easiest way is to use choco:
-
-1. install [chocolatey](https://chocolatey.org/install)
-either follow the instructions on the page or use winget,
-run in cmd as **admin**:
-```
-winget install --accept-source-agreements chocolatey.chocolatey
+{ 'author/plugin-name', opts = {} },
 ```

-2. install all requirements using choco, exit the previous cmd and
-open a new one so that choco path is set, and run in cmd as **admin**:
-```
-choco install -y neovim git ripgrep wget fd unzip gzip mingw make
-```
-</details>
-<details><summary>WSL (Windows Subsystem for Linux)</summary>
+For plugins that need configuration:

-```
-wsl --install
-wsl
-sudo add-apt-repository ppa:neovim-ppa/unstable -y
-sudo apt update
-sudo apt install make gcc ripgrep unzip git xclip neovim
-```
-</details>
-
-#### Linux Install
-<details><summary>Ubuntu Install Steps</summary>
-
-```
-sudo add-apt-repository ppa:neovim-ppa/unstable -y
-sudo apt update
-sudo apt install make gcc ripgrep unzip git xclip neovim
-```
-</details>
-<details><summary>Debian Install Steps</summary>
-
-```
-sudo apt update
-sudo apt install make gcc ripgrep unzip git xclip curl
-
-# Now we install nvim
-curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz
-sudo rm -rf /opt/nvim-linux-x86_64
-sudo mkdir -p /opt/nvim-linux-x86_64
-sudo chmod a+rX /opt/nvim-linux-x86_64
-sudo tar -C /opt -xzf nvim-linux-x86_64.tar.gz
-
-# make it available in /usr/local/bin, distro installs to /usr/bin
-sudo ln -sf /opt/nvim-linux-x86_64/bin/nvim /usr/local/bin/
-```
-</details>
-<details><summary>Fedora Install Steps</summary>
-
-```
-sudo dnf install -y gcc make git ripgrep fd-find unzip neovim
-```
-</details>
-
-<details><summary>Arch Install Steps</summary>
-
-```
-sudo pacman -S --noconfirm --needed gcc make git ripgrep fd unzip neovim
-```
-</details>
-
-### Alternative neovim installation methods
-
-For some systems it is not unexpected that the [package manager installation
-method](https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-package)
-recommended by neovim is significantly behind. If that is the case for you,
-pick one of the following methods that are known to deliver fresh neovim versions very quickly.
-They have been picked for their popularity and because they make installing and updating
-neovim to the latest versions easy. You can also find more detail about the
-available methods being discussed
-[here](https://github.com/nvim-lua/kickstart.nvim/issues/1583).
-
-
-<details><summary>Bob</summary>
-
-[Bob](https://github.com/MordechaiHadad/bob) is a Neovim version manager for
-all plattforms. Simply install
-[rustup](https://rust-lang.github.io/rustup/installation/other.html),
-and run the following commands:
-
-```bash
-rustup default stable
-rustup update stable
-cargo install bob-nvim
-bob use stable
+```lua
+{
+  'author/plugin-name',
+  event = 'VimEnter',   -- optional: defer loading
+  config = function()
+    require('plugin-name').setup {
+      -- options here
+    }
+    vim.keymap.set('n', '<leader>x', ...)
+  end,
+},
 ```

-</details>
+Then run `:Lazy sync` (or restart Neovim) to install.

-<details><summary>Homebrew</summary>
+### Updating plugins

-[Homebrew](https://brew.sh) is a package manager popular on Mac and Linux.
-Simply install using [`brew install`](https://formulae.brew.sh/formula/neovim).
-
-</details>
-
-<details><summary>Flatpak</summary>
-
-Flatpak is a package manager for applications that allows developers to package their applications
-just once to make it available on all Linux systems. Simply [install flatpak](https://flatpak.org/setup/)
-and setup [flathub](https://flathub.org/setup) to [install neovim](https://flathub.org/apps/io.neovim.nvim).
-
-</details>
-
-<details><summary>asdf and mise-en-place</summary>
-
-[asdf](https://asdf-vm.com/) and [mise](https://mise.jdx.dev/) are tool version managers,
-mostly aimed towards project-specific tool versioning. However both support managing tools
-globally in the user-space as well:
-
-<details><summary>mise</summary>
-
-[Install mise](https://mise.jdx.dev/getting-started.html), then run:
-
-```bash
-mise plugins install neovim
-mise use neovim@stable
+```vim
+:Lazy update
 ```

-</details>
+This updates all plugins and refreshes `lazy-lock.json`.

-<details><summary>asdf</summary>
+### Adding a language server

-[Install asdf](https://asdf-vm.com/guide/getting-started.html), then run:
+Inside the `servers` table in the `nvim-lspconfig` config block:

-```bash
-asdf plugin add neovim
-asdf install neovim stable
-asdf set neovim stable --home
-asdf reshim neovim
+```lua
+local servers = {
+  gopls = {},
+  pyright = {},
+  ts_ls = {},
+}
 ```

-</details>
+Mason will auto-install it. Run `:Mason` to check status.

-</details>
+### Adding a formatter
+
+Inside the `conform.nvim` `opts.formatters_by_ft` table:
+
+```lua
+formatters_by_ft = {
+  lua = { 'stylua' },
+  python = { 'black' },
+  javascript = { 'prettierd', 'prettier', stop_after_first = true },
+},
+```
+
+Make sure the formatter binary is installed via Mason or your system package
+manager.
+
+### Switching the colorscheme
+
+Replace the `folke/tokyonight.nvim` plugin entry with any other colorscheme,
+and update `vim.cmd.colorscheme 'theme-name'` in its `config` function.
+
+### Checking health
+
+```vim
+:checkhealth
+```
+
+Covers LSP, Treesitter, Telescope, and plugin-specific diagnostics.
+
+---
+
+## Optional Extras
+
+Uncomment any of these lines near the bottom of `init.lua` to enable bundled
+extras:
+
+```lua
+require 'kickstart.plugins.debug',      -- DAP debugger UI
+require 'kickstart.plugins.indent_line', -- indent guides
+require 'kickstart.plugins.lint',       -- async linting
+require 'kickstart.plugins.autopairs',  -- bracket auto-close
+require 'kickstart.plugins.neo-tree',   -- file tree
+require 'kickstart.plugins.gitsigns',   -- extra git keymaps
+```
+
+Drop additional plugin files under `lua/custom/plugins/` and uncomment:
+
+```lua
+{ import = 'custom.plugins' },
+```
+
+at the bottom of the lazy setup call.