# vamp

A modal Rust editor with a replaceable frontend and subprocess-isolated Ruby plugins.

## Run

Requires current stable Rust and an interactive terminal. Ruby 2.6+ with its standard-library JSON support is required only for configuration/plugins; no Ruby gems are needed to run vamp itself.

```sh
cargo run -- --no-config notes.txt
cargo run -- --config examples/config.rb notes.txt
```

Without a file, vamp opens an unnamed buffer. A nonexistent file opens an empty buffer. `cargo run -- --help` lists the command-line options.

## Getting started

Vamp starts in Normal mode. Press `i`, type text, then Esc to return to Normal. Type `:w` and Enter to save, or `:w path` to name an unnamed buffer. Type `:q` and Enter to quit; it refuses unsaved changes in any open buffer. `:q!` explicitly discards changes and quits.

| Task | Default keys |
| --- | --- |
| Move in Normal | `h`/`j`/`k`/`l` or arrows; `w`/`b`/`e` for words |
| Enter/leave Insert | `i` / Esc |
| Save in Normal | Space then `w`, or `:w` then Enter |
| Undo/redo in Normal | `u` / `U` (Shift+u) |
| Search in Normal | `/`, type a literal query, Enter; `n`/`N` for next/previous |
| Select/copy/cut | `v` characterwise or `V` whole rows, move to extend, then `y`/`d` in Visual |
| Paste in Normal | `p`/`P` after/before the caret or row for linewise fragments; system clipboard by default |
| Command palette | Ctrl+p; type to filter, arrows select, Enter accepts, Esc cancels |
| Floating/docked explorer in Normal or Visual | Space then `o` / Space then `e` |

Space is the default leader: press its suffix keys in order, not simultaneously. The [editing guide](docs/editing.md) contains the complete key table and behavior reference.

## Configuration

By default, vamp loads `$XDG_CONFIG_HOME/vamp/config.rb`, or `~/.config/vamp/config.rb` when that environment variable is unset. `--config path` selects a file explicitly; `--no-config` bypasses Ruby entirely and uses defaults.

Start with [`examples/config.rb`](examples/config.rb). The [configuration reference](docs/configuration.md) covers preferences, bindings, and native LSP setup. Language servers are **disabled by default**; install a trusted server and explicitly enable it.

Ruby configuration and plugins run with your account's filesystem/process permissions. Subprocess isolation is **not a security sandbox**; load only trusted scripts.

## Current limits

- One visible buffer at a time; no splits/tabs or graphical frontend.
- Modal editing, not full Vim compatibility: characterwise and linewise Visual selections, but no block selection, named registers, or Vim operators. Search is literal, case-sensitive, and single-line.
- Native opt-in LSP supports diagnostics, go-to-definition, plain-text hover, and automatic semantic highlighting—not completion, rename, formatting, or code actions.
- System clipboard access supports macOS and Linux. Separate clipboard mode keeps internal editing available on unsupported/headless environments.

Performance and subprocess limits are documented in [development](docs/development.md#performance-and-process-limits).

## Documentation

| Guide | Contents |
| --- | --- |
| [Editing](docs/editing.md) | Keys, motions/counts, selections, repeat, clipboard, search, buffers, explorer, palette, syntax highlighting |
| [Configuration](docs/configuration.md) | Ruby startup, preferences, action/mode reference, key notation, leader/list/tree bindings, native LSP |
| [Plugins](docs/plugins.md) | Ruby API, capabilities, effects, asynchronous callbacks, isolation, messaging protocol |
| [Architecture](docs/architecture.md) | Module ownership, session/frontend contracts, terminal lifecycle, syntax caches, native workers |
| [Development](docs/development.md) | Verification commands, test organization, performance and process limits |
| [Project context](CONTEXT.md) | Terminology and configuration-interface conventions |