lux/PLAN.md

# Neovim redesign and cleanup plan

## Governing intent

Make Neovim the primary editor and turn its configuration into a small, readable, cohesive system. Refactoring, simplification, runtime performance, reliability and UX are equal deliverables; do not bolt new plugins onto the current structure.

Use Helix's philosophy as the decision framework throughout implementation, including unforeseen choices:

- Prefer a few orthogonal concepts over aliases and special cases.
- Make related commands symmetric, mnemonic and context-aware.
- Provide one canonical interface for each task; hide plugin identity.
- Make first use behave like later use; load order must not affect behavior.
- Keep the screen quiet and reveal information when relevant or requested.
- Prefer native Neovim behavior when it fits this model.
- Remove code, configuration and plugins that do not justify their complexity.

These principles govern the detailed plan. If a minor implementation detail conflicts with them, choose the simpler coherent solution and report the deviation. If resolving a conflict changes the user-facing command model, dependencies or scope, stop and request a plan amendment. Do not use this discretion to expand scope.

## Context and scope

- Neovim module: `modules/capabilities/neovim/default.nix`.
- Lua root: `modules/capabilities/neovim/lua-config`.
- `modules/profiles/host-base.nix` currently selects `primary-editor-helix`; therefore the active shell has no `nvim`.
- Locked versions include Neovim 0.12.4 and Kulala 6.29.0. Target them; add no older-version compatibility.
- Retain `nix-wrapper-modules`, `lz.n` and the custom Svelte Treesitter grammar.
- First-class languages: Nix, TypeScript/JavaScript, Svelte, Rust and Python.
- Also retain Lua, JSON, CSS, HTML, Astro, Typst, TOML, YAML, Markdown/`zk` and snippets. Remove Dafny.
- Add Oil, Grug-far, Dadbod UI, SQL completion, Kulala request/environment/import support and `zk-nvim`.
- Add YAML/JSON schema support and automatic web-tag closing/renaming.
- Exclude sessions, embedded-terminal workflow beyond leaving terminal mode, Git porcelain, debugging, test runners, AI tooling and graphical ER modeling.
- Preserve unrelated worktree changes, including `modules/capabilities/desktop-defaults.nix` if still modified.

Known defects and cleanup targets:

- Nix plugin groups and Lua modules do not share a clear capability structure; Kulala is in `ui.lua`, while `lsp.lua` also owns Telescope loading, diagnostics and breadcrumbs.
- `options.lua` contains mappings and an autocmd.
- Telescope dependency arrays and manual `trigger_load` calls are duplicated. Code-action UI changes after Telescope first loads.
- Treesitter starts through three overlapping events.
- Navic uses a global callback evaluated by winbars.
- LSP attach callbacks recreate shared autocmd groups.
- `project.nvim` changes global cwd; `direnv.vim` runs on every buffer entry although the launching shell owns the environment.
- Dadbod is absent; Kulala installs global mappings; several installed plugins lack explicit setup.

## Required structure and code quality

Before editing, inventory every Neovim option, mapping, autocmd, plugin, runtime package and server. Delete duplicates, unused entries and configuration that restates defaults.

Align Nix plugin groups with these Lua modules:

- `init.lua`: ordered `require` calls only.
- `options.lua`: options only.
- `keymaps.lua`: plugin-independent mappings and intentional default removals.
- `autocmds.lua`: editor-wide autocmds.
- `plugins/editing.lua`: mini.ai/surround/pairs/icons, indentation detection, Treesitter, text objects, rainbow delimiters, automatic tag handling and Grug-far.
- `plugins/navigation.lua`: Telescope, FZF, `ui-select` and Oil.
- `plugins/diagnostics.lua`: native diagnostic presentation and Trouble.
- `plugins/lsp.lua`: servers, attach/detach behavior and Navic attachment.
- `plugins/completion.lua`, `formatting.lua`, `ui.lua`, `database.lua`, `http.lua`, `notes.lua`: one concern each.

Enforce these rules:

- One owner per option, mapping, autocmd and plugin setup.
- Keep plugin-backed mappings in their plugin specification; declare Which-key groups centrally.
- Give every lazy plugin an explicit `keys`, `cmd`, `ft` or `event` trigger. Only dependency entries may omit one.
- Use `lz.n` declaratively. Remove scattered `trigger_load` wrappers.
- Create each augroup once and scope buffer behavior with `buffer = args.buf`.
- Keep state local; add no `_G` callbacks.
- Add a helper only when at least two capabilities use it and it reduces conceptual complexity.
- Comments explain non-obvious constraints or decisions, not syntax. Delete commented-out code.
- Prefer current native APIs and defaults. Add no speculative guards, fallbacks or compatibility layers.
- Move Kanagawa setup into `ui.lua`; delete the generated Lua string and `_kanagawa-theme.nix`. Use `nix-info` only for Nix expressions and store paths.
- Group Nix packages by capability/language and remove obsolete entries.

## Interaction model

| Task | Canonical interface |
| --- | --- |
| Filesystem operations | Oil editable directory buffer |
| Files, text, symbols, references, diagnostics, commands | Telescope |
| Project-wide text or regex replacement | Grug-far |
| Syntax movement/selection in the current buffer | Treesitter |
| Code relationships and semantic refactors | LSP; Telescope renders result collections |
| Persistent diagnostics/promoted results | Trouble |
| Database inspection/queries | Dadbod UI |
| HTTP requests | Kulala |
| Note capture and discovery | `zk-nvim`; Telescope renders note collections |

Use buffers, not tabs or sessions, as the open-file model. Root project searches at `vim.fs.root(0, { ".git" })`, falling back to the process cwd; never change cwd implicitly. Keep Telescope's default result behavior. Provide one Telescope action that sends results to quickfix and opens Trouble.

Keep LSP rename and code actions as the semantic project-wide refactoring interface. Use Grug-far for explicit text or regular-expression replacement; do not add an integration layer between them.

Make Oil the directory handler. `<leader>e` opens the current file's directory. Keep filesystem-change confirmation.

## Keymap and discovery contract

Set `<leader>` to space and `<localleader>` to comma. Every custom mapping needs an action-oriented `desc`. Remove displaced plugin/native aliases.

- `g…`: `gd` definition, `gD` declaration, `gr` references, `gI` implementation, `gy` type definition, `gO` document symbols, `K` hover.
- `[x`/`]x`: previous/next diagnostic `d`, Git hunk `h`, function `f`, class/type `c`, parameter `a`. Replace conflicting defaults for these exact keys as one family.
- `<leader>s…`: Telescope project files/grep, cursor word, current buffer, recent files, workspace symbols, diagnostics, help, commands, keymaps and resume.
- `<leader>c…`: `ca` code action, `cr` rename, `cf` format, `cR` project-wide replacement. Remove displaced `gr*` LSP mappings.
- `<leader>d…`: persistent workspace/buffer diagnostics. Remove `<leader>x…` Trouble and location-list diagnostic mappings.
- `<leader>b…`: buffer picker/delete. Remove the duplicate `<leader><leader>` picker.
- `<leader>q…`: database workspace; `qo` toggles Dadbod UI.
- `<leader>r…`: global HTTP facilities, including the scratchpad.
- `<leader>n…`: central notes; `nn` captures, `nf` finds notes and `nt` finds tags. Inside a `zk` note, `ni` inserts a link.
- `<leader>u…`: UI toggles only.
- `gl`: diagnostic details; `<C-h/j/k/l>`: window focus; `<Esc><Esc>`: leave terminal mode.
- Keep native `gg`, `G` and word motions. Do not alias `ge` to end-of-file. Replace native mappings only as part of a complete family.

Provide operator-pending and visual Treesitter objects: `if/af` function, `ic/ac` class/type, `ia/aa` parameter, `ii/ai` conditional, `il/al` loop, `ib/ab` block. Retain `ci<object>` grammar and make structural bracket movements repeatable.

Context-local mappings:

- SQL: `,r` execute query/selection, `,s` save query, `,p` edit bind parameters.
- HTTP: `,r` execute request at cursor, `,a` execute file, `,e` select environment.
- Dadbod drawer/output: keep normal motions and `<CR>`; describe local mutation/refresh actions instead of adding globals.

Configure Which-key with the `helix` preset and automatic normal, visual, select and operator-pending triggers. Enable its operator, motion, text-object, window, navigation, `g`, `z`, mark, register and spelling documentation. Define groups once without duplicating mappings. Use Telescope keymap, command and help pickers as the full-catalog fallback; do not remap single-key built-ins only to display them.

## Feature changes

### Editing, navigation and UI

- Stop configuring `mini.files`; add `pkgs.vimPlugins.oil-nvim`.
- Remove `project.nvim`, `direnv.vim` and `mini.indentscope`.
- Start Treesitter once on `FileType` for normal file buffers. Configure text objects and rainbow delimiters explicitly.
- Add `nvim-ts-autotag` for Svelte, Astro, HTML, JSX and TSX only.
- Retain mini.ai/surround/pairs/icons and indentation detection. Benchmark `mini.hipatterns`; retain hex/TODO highlighting only if it adds no measurable scrolling cost.
- Configure Grug-far as the only project-wide text/regex replacement interface. Open it with the cursor word or visual selection when available and retain its editable-buffer workflow.
- Reduce Gitsigns to signs, hunk navigation and preview.
- Keep Kanagawa Wave and colorful semantic completion. Use opaque surfaces and one border style for popups.
- Use absolute line numbers, no tabline and markers only for tabs, trailing spaces and non-breaking spaces.
- Use one global statusline containing mode, branch, filename, diagnostics, filetype, location and a truncated Navic breadcrumb when available. Remove diff/LSP-status duplication and all winbars.

### LSP, completion and formatting

- Remove the Dafny package/server. Keep current servers for retained languages.
- Add `yaml-language-server` (`yamlls`) and `SchemaStore.nvim` for schema-aware YAML and JSON completion and validation. Disable LSP formatting in favor of Conform.
- Remove `oxfmt` as an LSP; invoke Conform's `oxfmt` CLI formatter.
- Remove `typst-preview.nvim`, `websocat` and their `nix-info` settings. Invoke the locked Tinymist server's preview commands.
- Enable supported inlay hints by default with one toggle. Retain semantic tokens unless profiling identifies them as a bottleneck.
- Show diagnostics through signs, underlines and severity sorting. Remove virtual lines; use `gl` for text.
- Install one buffer-local document-highlight autocmd set on attach; remove it on detach without affecting other buffers.
- Ensure every Telescope-backed LSP action and `telescope-ui-select` works on first invocation.
- Retain Blink, colorful-menu and friendly-snippets with `<C-j>/<C-k>` selection. Use Blink's native `vim.snippet` support and convert the custom Nix snippets to VS Code JSON; remove LuaSnip.
- Define one Conform pipeline per filetype. Prefer packaged CLIs; use LSP formatting only as an explicit fallback. Run one Ruff fix plus Ruff format for Python and one Oxfmt pass for supported web files.
- Keep format-on-save synchronous with a finite timeout; keep manual formatting asynchronous.

### Databases and HTTP

- Add `vim-dadbod`, `vim-dadbod-ui`, `vim-dadbod-completion` and `blink-compat`; load them on database commands/filetypes only.
- Add wrapper-local `postgresql`, `mariadb` and `mongosh`. PostgreSQL is primary; retain MySQL and MongoDB adapters.
- Integrate relational SQL completion into Blink through `blink.compat`; do not enable it for MongoDB.
- Expose schemas, tables, views, constraints/index helpers, saved queries, results and relational foreign-key jumps.
- Use `DATABASE_URL` as the default project connection when set. Never store credentials in Nix or committed files. Store ad-hoc saved queries under XDG data; keep schema/migration SQL in projects.
- Treat MongoDB as collection/document exploration, not relational navigation.
- Move Kulala from `ui.lua` to `http.lua`; load it on `http`/`rest` files and explicit commands only. Disable its global mappings.
- Add wrapper-local `kulala-core`, `kulala-fmt`, `curl`, `jq` and `openssl`. Pass the packaged core path through `nix-info`; disable backend downloads.
- Use the Nix-provided `http` Treesitter grammar; disable Kulala parser downloads/builds.
- Use JetBrains-compatible `.http` files. Commit non-secret `http-client.env.json`; keep credentials in ignored `http-client.private.env.json` or shell/direnv variables.
- Support conversion with `kulala-fmt convert --from openapi --to http -o <output> <spec>`. Add no editor wrapper until repeated use justifies it.

### Notes

- Add wrapper-local `zk` and `zk-nvim` with Telescope as its picker. Let `zk-nvim` start `zk lsp` only for Markdown buffers inside a notebook; do not also configure `zk` through `nvim-lspconfig`.
- Set `ZK_NOTEBOOK_DIR` to `~/sync/notes`. Global capture and discovery always target this notebook; new notes use its existing filename and template rules and never prompt for a directory.
- Use the standard LSP mappings to follow links, find backlinks and preview linked notes. Add only the three global mappings and notebook-local insert-link mapping defined above.

### Nix integration

Keep the wrapper self-contained; do not rely on login-shell packages. Align Nix groups with the Lua structure and delete unused declarations. After validation, change `host-base.nix` to `primary-editor-neovim` and remove its Helix cache import; retain the optional Helix capability.

## Performance and reliability

1. Before refactoring, build the current wrapper without switching the running system. Record median headless startup time over repeated runs. Profile scrolling in representative large Nix, TypeScript/Svelte, Rust and Python buffers with LSP attached.
2. Remove known hot-path duplication: repeated Treesitter starts, winbar evaluation, virtual-line layout changes, unused visual scanners, the formatter-only LSP and the separate Typst preview process layer.
3. Re-profile after editing/navigation, LSP and UI changes. Add no size thresholds, caches, debounce wrappers or feature cutoffs without a measured problem.
4. Keep inlay hints, semantic tokens and required servers unless measurements identify a specific offender.
5. Temporary files, non-file buffers, inaccessible parent directories and files outside Git repositories must not change cwd or emit configuration errors.

## Verification and completion

- Run `nix fmt`, `nix flake check --no-build` and no-switch builds for `zenith`, `polaris` and `orion`.
- Run the built wrapper headlessly with no arguments and with Nix, TypeScript, JavaScript, Svelte, Rust and Python files. Run `:checkhealth`; resolve errors from configured providers instead of suppressing them.
- In fresh processes, test every semantic mapping, code action before any other Telescope command, Trouble promotion, Oil directory handling, Grug-far replacement, YAML/JSON schemas, automatic tag handling, central note capture/discovery, native Tinymist preview, SQL completion/query actions and Kulala request/environment actions.
- Open a temporary prompt file outside a project and confirm no workspace, cwd or access error.
- With disposable data, test Oil multi-create/rename/move/copy/delete, Dadbod against PostgreSQL, MySQL/MongoDB client and adapter loading, a local Kulala request and a small OpenAPI conversion.
- Repeat startup and attached-LSP scrolling measurements; report before/after results and any remaining bottleneck.
- Apply the governing Helix principles throughout, not only at final review. Completion requires no duplicate mapping/setup, misplaced capability, lazy plugin that fails on first action or retained code without a current purpose.