# coxn User Manual — Configuration Reference

This manual documents every user-facing configuration option in coxswain (coxn):
where the configuration file lives, how to write it, what each option means, and its
default value. For running and building instructions, see the [README](../README.md).
For the overall design, see [designs/clj-editor.md](../designs/clj-editor.md).

## Contents

1. [Configuration file and loading](#1-configuration-file-and-loading)
2. [API available in init.clj](#2-api-available-in-initclj)
3. [Core options](#3-core-options)
4. [LSP options](#4-lsp-options)
5. [Project tree (treemacs) options](#5-project-tree-treemacs-options)
6. [Clojure REPL (CIDER) options](#6-clojure-repl-cider-options)
7. [Common Lisp REPL (SLIME) options](#7-common-lisp-repl-slime-options)
8. [Other layer options (helm / tree-sitter)](#8-other-layer-options-helm--tree-sitter)
9. [Layer selection](#9-layer-selection)
10. [Themes and faces](#10-themes-and-faces)
11. [User-interface language](#11-user-interface-language)
12. [Hooks and events](#12-hooks-and-events)
13. [Key bindings](#13-key-bindings)
14. [Buffer-local configuration: EditorConfig and file-local variables](#14-buffer-local-configuration-editorconfig-and-file-local-variables)
15. [Environment variables and system properties](#15-environment-variables-and-system-properties)
16. [A complete init.clj example](#16-a-complete-initclj-example)

## 1. Configuration file and loading

The configuration file is `init.clj` (Clojure code, not EDN). Its location is:

| Platform | Path |
|---|---|
| Linux / FreeBSD | `~/.config/coxn/init.clj`, or `$XDG_CONFIG_HOME/coxn/init.clj` when `$XDG_CONFIG_HOME` is set |
| Windows | `%APPDATA%/coxn/init.clj` |
| Any platform | The file named by `$COXN_INIT` takes precedence |

In the editor, press `M-m f e d` (`coxswain-find-dotfile`) to open it.

Key points:

- `init.clj` is loaded in the `coxn.user` namespace, **before editor state is created**.
  Calls such as `set-option!` and `bind-key!` are queued and applied once state exists.
  The file may also contain arbitrary Clojure code.
- Option precedence is: **user `set-option!` > layer default > core default**
  (`coxn.editor/opt`).
- A configuration error does not prevent startup. The error is shown in the echo area
  (`Error in …/init.clj: …`).
- At runtime, `M-:` (`eval-expression`) evaluates in the same `coxn.user` environment.
  `*ed*` is bound to the current editor state; calls such as `set-option!` take effect
  immediately.

## 2. API available in init.clj

These functions are available in `coxn.user`. All of `clojure.core` is available, and the
file also requires `coxn.editor` (alias `ed`, including `defcommand`), `coxn.keymap`
(`km`), `coxn.i18n`, `coxn.hooks`, `coxn.bus`, `coxn.config`, and `coxn.layers`:

| API | Purpose |
|---|---|
| `(set-option! k v)` | Set an option, for example `(set-option! :tab-width 4)`. All options appear below |
| `(bind-key! "C-c g" 'find-file)` | Bind a global key |
| `(unbind-key! "C-c g")` | Remove a global binding |
| `(prefix-name! "C-c l" "lsp")` | Name a prefix for which-key |
| `(set-theme! :doom-dark)` | Change the theme (see §10) |
| `(set-face! :region {:bg "#3a3a5a"})` | Override one face; survives theme changes (see §10) |
| `(register-theme! {...})` | Register your own theme (see §10) |
| `(palette :space-dark)` / `(palette-with pal :keyword "#ff79c6")` | Read or adjust a built-in palette |
| `(add-hook! :after-save-hook f)` / `(remove-hook! ...)` | Manage hooks; `f` takes and returns an editor (see §12) |
| `(subscribe! :document-opened f)` / `(unsubscribe! ...)` | Subscribe to fact events; `f` receives `[event payload]` (see §12) |
| `(configuration-layers! [:treemacs :lsp ...])` | Select layers; no call means all layers (see §9) |
| `(set-language! :zh)` | Set the UI language (see §11) |
| `(defcommand name "doc" [ed] ...)` | Define a command and register it in `M-x` |

## 3. Core options

Core defaults live in `coxn.editor/default-options`. Set every option with
`(set-option! key value)`.

### 3.1 Editing and indentation

| Option | Default | Meaning |
|---|---|---|
| `:tab-width` | `8` | Display width of a Tab character, following Emacs. EditorConfig `tab_width` and file-local values can override it per buffer |
| `:indent-offset` | `4` | Spaces per indentation level. Major modes may provide defaults (Clojure and Lisp modes use 2); EditorConfig / file-local values can override per buffer |
| `:fill-column` | `70` | Line width for `M-q` (`fill-paragraph`) and auto-fill (Emacs default: 70) |
| `:electric-pair` | `false` | Automatically complete parentheses and quotes (`M-x electric-pair-mode`; Emacs default: off) |
| `:show-paren` | `true` | Highlight matching parentheses (`show-paren-mode`; default on since Emacs 28) |
| `:line-move-visual` | `true` | `C-n` / `C-p` move by screen lines when long lines wrap (Emacs default) |
| `:scroll-margin` | `0` | Scroll margin (corresponds to Emacs `scroll-margin`; not consumed in the current release) |

### 3.2 Interface and display

| Option | Default | Meaning |
|---|---|---|
| `:display-line-numbers` | `false` | Line numbers. `M-x display-line-numbers-mode` for the current buffer or `global-display-line-numbers-mode` globally |
| `:mouse` | `true` | Terminal mouse (`xterm-mouse-mode`). While enabled, Shift+drag remains the terminal's own selection; `M-x xterm-mouse-mode` toggles it |
| `:extended-keys` | `true` | kitty keyboard protocol / modifyOtherKeys, so the terminal can send `C-;`, `C-?`, `C-S-a`, and similar combinations |
| `:which-key-delay-ms` | `500` | Delay after pressing a prefix before the which-key popup appears |
| `:tab-bar-mode` | `false` | Top tab bar (`M-x tab-bar-mode`) |
| `:minibuffer-display` | `:bottom` | Minibuffer position for `M-x`, `C-x C-f`, and similar commands: `:bottom` gives a bottom helm-style display (spacemacs feel); `:popup` gives a centered floating frame (vertico-posframe feel) |
| `:eldoc-display` | `:echo` | Where automatic function hints appear: `:echo` uses the bottom line; `:popup` opens a floating frame. Toggle with `M-m t E`; the explicit viewer on `M-m h g` ignores this option |
| `:color-depth` | `:auto` | Color depth: `:auto` probes the terminal (`COLORTERM`, `TERM`, Windows Terminal); `24` forces true color; `8` forces the 256-color palette chosen for each theme |
| `:text-scale` | `1.0` | Text scale (Emacs `text-scale-mode`): `C-x C-+` / `C-x C-=` enlarge, `C-x C--` shrinks, `C-x C-0` resets; each step is ×1.2 and the range is 0.2–8.0. `C-u 3 C-x C-+` applies three steps. GUI recalculates rows and columns with the new font size; in TUI, font size belongs to the terminal. Unlike Emacs, this setting is global |

### 3.3 Completion

| Option | Default | Meaning |
|---|---|---|
| `:completion-auto` | `true` | Open completion automatically after typing pauses (corfu feel). Toggle with `M-m t a` |
| `:completion-auto-delay-ms` | `150` | Pause duration before automatic completion opens |
| `:completion-auto-prefix` | `2` | Minimum symbol characters before automatic completion opens. Trigger characters such as `.`, `->`, and `::` are exempt |
| `:completion-sync-wait-ms` | `300` | Initial synchronous wait after a completion request. If all sources return in time, show results immediately; otherwise switch to asynchronous display (bounded by `:lsp-timeout-ms`) |

### 3.4 Files, auto-saving, and persistence

| Option | Default | Meaning |
|---|---|---|
| `:auto-revert` | `true` | If an unchanged buffer's file changes externally, read it again |
| `:auto-save` | `true` | Save a copy of modified buffers (the original file is untouched) |
| `:auto-save-interval` | `300` | Number of keystrokes between auto-saves |
| `:auto-save-timeout-ms` | `30000` | Idle time in milliseconds before an auto-save |
| `:auto-save-dir` | `<cache>/auto-save` | Auto-save directory; file names follow Emacs encoding (`/#encoded-path#`) |
| `:make-backup-files` | `true` | Before the first save in a session, copy the original file to a backup |
| `:backup-dir` | `<cache>/backup` | Backup directory (file names are `encoded-path~`) |
| `:save-place` | `true` | Remember point and window position per file and restore it on reopening |
| `:save-place-file` | `<config>/save-place.edn` | Storage file for save-place |
| `:bookmark-file` | `<config>/bookmarks.edn` | Bookmarks (`C-x r m` / `C-x r b`) |
| `:projects-file` | `<config>/projects.edn` | Known projects, used by `M-x project-forget-project` and related commands |

`<config>` and `<cache>` are described in §15.

### 3.5 GUI fonts (coxn-gui only; ignored by TUI)

The defaults are all `nil`, meaning follow the system: use the system monospace font as
the primary font, and use system fontconfig fallbacks for CJK, symbols, and emoji. CJK
uses a monospace sans font to preserve double-width alignment. Override with a
**priority list**; the first installed font wins (following spacemacs `my-fonts.el`):

| Option | Default | Meaning |
|---|---|---|
| `:gui-font` | `nil` | Primary font, for example `["JetBrains Mono" "Fira Code"]` |
| `:gui-font-size` | `nil` (= 14) | Font size in sp (about pixels on desktop; follows Emacs `:size`), for example `14` |
| `:gui-font-cjk` | `nil` | Full-width / CJK font, for example `["Noto Sans Mono CJK SC"]` |
| `:gui-font-symbol` | `nil` | Arrow / symbol font, for example `["Symbola"]` |
| `:gui-font-emoji` | `nil` | Color emoji font, for example `["Noto Color Emoji"]` |

### 3.6 Search and process output

| Option | Default | Meaning |
|---|---|---|
| `:grep-program` | `nil` | Program for project grep (`"rg"` / `"grep"`). `nil` uses `rg` when installed, otherwise `grep` |
| `:repos-scan` | `nil` | Root scanned by `magit-repos-view` (`C-x p G`). `nil` uses the parent of the current project root, otherwise the working directory |
| `:repl-buffer-maximum-size` | `1000000` | Maximum characters retained in REPL / process-output buffers (following `comint-buffer-maximum-size`); beyond it, trim from the start to a line boundary. `0` means unlimited |

## 4. LSP options

LSP is provided by the `:lsp` layer (enabled by default). Layer defaults live in
`coxn.layers.lsp`; timeout defaults live in core `default-options`.

### 4.1 Behavior switches

| Option | Default | Meaning |
|---|---|---|
| `:lsp-auto` | `true` | Automatically attach when opening a file with a matching server (`-Dcoxn.lsp.auto=false` changes the default). Use `M-x lsp` to attach manually |
| `:lsp-auto-install` | `true` | If a server is not on `PATH`, asynchronously install it from its official source (GitHub releases / Eclipse / npm) under `<config>/lsp/<name>` and retry. Use `M-x lsp-install-server` manually |
| `:lsp-confirm-edits` | `true` | Show a diff preview for WorkspaceEdit operations such as rename; apply only with `C-c C-c` |
| `:lsp-on-type-formatting` | `true` | After a trigger character (such as clangd's `.` or `;`), format automatically when the server requests it |
| `:lsp-code-action-light` | `true` | When the point has diagnostics and typing pauses for 500 ms, show 💡 in the mode line when a code action is available |
| `:lsp-inlay-hints` | `false` | Inlay hints (types / parameter names). Toggle `M-x lsp-inlay-hints-mode` (`M-m m T i`) |

### 4.2 Timeouts

| Option | Default | Meaning |
|---|---|---|
| `:lsp-timeout-ms` | `3000` | Timeout for synchronous requests such as jump to definition, rename, formatting, and completion |
| `:lsp-eldoc-delay-ms` | `300` | Idle delay before asking for function hints (shared by nREPL and LSP) |
| `:lsp-sync-wait-ms` | `200` | Initial synchronous wait for user-command requests. If the reply arrives, show it immediately; otherwise switch to asynchronous handling (bounded by `:lsp-timeout-ms`) |
| `:lsp-file-operation-timeout-ms` | `1500` | Maximum wait for server `willRename` / `willDelete` edits before renaming or deleting a file; on timeout, proceed without those edits |

### 4.3 Servers and server settings (no defaults; configure as needed)

| Option | Meaning |
|---|---|
| `:lsp-servers` | `{major-mode [[command arguments…] …]}`, **merged** with each language layer's built-in list (same-mode entries override). The first installed command is used. `:workspace-dir` in arguments becomes `<cache>/lsp/<command>/<project-root-hash>` (jdtls needs it). Example: `(set-option! :lsp-servers {:c++ [["clangd" "--background-index" "--clang-tidy"]]})` |
| `:lsp-settings` | `{server-command settings-map}`, deep-merged over built-in defaults and sent to `initializationOptions.settings`, `workspace/didChangeConfiguration`, and `workspace/configuration`. Built-ins include jdtls (inlay-hint parameter names) and useful typescript-language-server settings. Example: `(set-option! :lsp-settings {"jdtls" {:java {:inlayHints {:parameterNames {:enabled "all"}}}}})` |
| `:lsp-init-options` | `{major-mode initializationOptions}`, sent additionally during `initialize` |
| `:lsp-connect` | `(fn [mode root])` returning a fake `{:in :out :process}` connection, for **tests only**; normally leave unset |

## 5. Project tree (treemacs) options

The `:treemacs` layer is enabled by default. Toggle the tree with `C-x t t` or
`M-m f t`.

| Option | Default | Meaning |
|---|---|---|
| `:treemacs-width` | `35` | Sidebar width in columns |
| `:treemacs-wide-toggle-width` | `70` | Width applied by pressing `W` in the tree; press again to restore |
| `:treemacs-collapse-dirs` | `3` | Collapse chains of directories containing one child (`src/demo`); maximum chain depth |
| `:treemacs-show-hidden` | `true` | Show dotfiles; `.git` is never shown |
| `:treemacs-follow-mode` | `true` | Follow the current buffer's file in the tree |
| `:treemacs-filewatch-mode` | `true` | Watch files and redraw (checked every 2 seconds) |
| `:treemacs-git-mode` | `true` | Color nodes according to Git status |
| `:treemacs-sorting` | `:alphabetic-case-insensitive-asc` | Sort order; directories precede files. Options: `:alphabetic-asc`, `:alphabetic-desc`, `:alphabetic-case-insensitive-asc`, `:alphabetic-case-insensitive-desc`, `:size-asc`, `:size-desc`, `:mod-time-asc`, `:mod-time-desc` |
| `:treemacs-space-between-root-nodes` | `false` | In a multi-project workspace, leave a blank line between projects |
| `:treemacs-auto-hide-min-width` | `80` | Hide the project tree when the screen is narrower than this; `nil` disables auto-hiding |
| `:treemacs-persist-file` | `<config>/treemacs-persist.edn` | Workspace storage (projects / expanded state) |

## 6. Clojure REPL (CIDER) options

The `:cider` layer is enabled by default and automatically brings the `:clojure`
language base. Jack in with `M-m m '`.

| Option | Default | Meaning |
|---|---|---|
| `:nrepl-version` | `"1.3.1"` | nREPL version injected when jack-in runs |
| `:cider-nrepl-version` | `"0.52.1"` | cider-nrepl middleware version injected when jack-in runs |
| `:cider-inject-middleware` | `true` | Inject cider-nrepl middleware (completion, documentation, tests, and other enhancements); when off, only plain nREPL is used |
| `:cider-clojure-cli-aliases` | `nil` | Aliases supplied to a deps.edn project during jack-in, for example `":dev:test"` (appended after `-M`) |
| `:cider-repl-pop-on-connect` | `true` | Open the REPL buffer in another window after connecting |
| `:cider-show-error-buffer` | `true` | Open `*cider-error*` automatically on evaluation failure; RET jumps to the selected stack frame |
| `:cider-shadow-default-build` | `nil` | Default build when shadow-cljs jack-in (`C-c M-J`) asks, for example `:app`; `nil` means `node-repl` |

## 7. Common Lisp REPL (SLIME) options

The `:slime` layer is enabled by default and automatically brings the `:lisp` language
base. Start it with `M-x slime` or `M-m m '`.

| Option | Default | Meaning |
|---|---|---|
| `:inferior-lisp-program` | `"sbcl"` | Lisp used by `M-x slime`. With a prefix, `C-u M-x slime` chooses from installed implementations |
| `:slime-lisp-implementations` | `{}` | Implementation map `{name implementation}`. An implementation can be a program name `"sbcl"`, a vector with arguments `["sbcl" "--dynamic-space-size" "4096"]`, or `{:program [...] :eval-flag "..."}`. With this set, `C-u M-x slime` chooses from it |
| `:slime-swank-loader` | `nil` | Path to slime's `swank-loader.lisp` (`~` supported); `nil` loads `swank/exts` through Quicklisp, which requires `~/quicklisp/setup.lisp` |
| `:slime-completion` | `:simple` | Completion style: `:simple` uses ordinary prefix completion; `:fuzzy` uses swank-fuzzy, so abbreviations such as `m-v-b` also work |
| `:slime-repl-history-size` | `200` | Number of REPL input-history entries retained |
| `:slime-compile-file-options` | `nil` | Extra options supplied to `swank:compile-file-for-emacs`, as a plist fragment |
| `:slime-filename-translations` | `[]` | Filename translations for remote / container scenarios: `[{:host-re "regex" :to-lisp (fn [path] ...) :from-lisp (fn [path] ...)}]`. Empty `:host-re` matches every host |
| `:clhs-root` | `"http://www.lispworks.com/documentation/HyperSpec/"` | CLHS root used by `M-m m h h`; may point to a local `file://` mirror |

## 8. Other layer options

### helm layer

The minibuffer already has a helm-like feel (source headers, selected row, flex
matching, orderless tokenization). This layer supplies these defaults. The current
release has minibuffer behavior built in, so these options are retained as conventions
and are not consumed individually yet:

| Option | Default |
|---|---|
| `:helm-fuzzy-matching` | `true` |
| `:helm-follow-mode` | `false` |
| `:helm-display-bottom` | `true` |
| `:helm-completion-style` | `:helm` |

Use the core `:minibuffer-display` option to choose the minibuffer position (§3.2).

### tree-sitter layer

| Option | Default | Meaning |
|---|---|---|
| `:tree-sitter` | `true` | Declarative default. **Actual availability follows layer selection**: if `configuration-layers!` omits `:tree-sitter`, highlighting is disabled and sexp navigation / indentation falls back to treeless algorithms |

## 9. Layer selection

```clojure
(configuration-layers! [:tree-sitter :lsp :treemacs :git :clojure :cider :cpp])
```

- **No call means every built-in layer is enabled** (following spacemacs
  `dotspacemacs-configuration-layers`).
- Unselected layers do not load commands, add bindings, add hooks, or provide option
  defaults.
- Dependencies are included automatically: selecting `:slime` brings `:lisp`; selecting
  `:cider` brings `:clojure`.
- With `:lsp` selected, major modes in language-layer server lists automatically use
  `lsp-deferred`.

Built-in layers, in default load order:

| Layer | Provides |
|---|---|
| `:tree-sitter` | Syntax highlighting + structural editing (sexp navigation / tree-based indentation) |
| `:lsp` | LSP client: definitions / references / rename / formatting / diagnostics / completion / inlay hints |
| `:helm` | Minibuffer completion defaults |
| `:treemacs` | Project-tree sidebar |
| `:git` | magit-status / log / blame / diff / repos, VC, and smerge conflict resolution (project and grep are core features, not in this layer) |
| `:lisp` | Common Lisp language base (major modes / alive-lsp and cl-lsp server lists) |
| `:clojure` | Clojure language base (clojure-lsp server list) |
| `:cider` | Clojure nREPL REPL |
| `:slime` | Common Lisp SWANK REPL |
| `:erlang` | Erlang (ELP / erlang_ls) |
| `:elixir` | Elixir (elixir-ls) |
| `:cpp` | C / C++ (clangd) |
| `:java` | Java (jdtls) |
| `:kotlin` | Kotlin (kotlin-language-server) |
| `:javascript` | JS / TS / TSX (typescript-language-server) |
| `:html` | HTML |
| `:css` | CSS |
| `:markdown` | Markdown |

## 10. Themes and faces

### Change theme

```clojure
(set-theme! :doom-dark)
```

- Built-ins are 14 themes: `:space-dark`, `:space-light`, `:doom-dark`, `:doom-light`,
  `:everforest-dark` (default), `:everforest-light`, `:token-dark`, `:token-light`,
  `:token-flint-dark`, `:token-flint-light`, `:token-temper-dark`,
  `:token-temper-light`, `:paper-light`, and `:paper-dark`, plus `:terminal`, which
  follows the terminal background without repainting normal text.
- `M-x load-theme` offers interactive selection (names use their own foreground color
  and include color swatches); `M-m T n` rotates themes.
- Interactive selection is stored in `<config>/theme.edn` and is used first on the next
  startup; `set-theme!` in `init.clj` overrides it.

### Override faces

```clojure
(set-face! :region {:bg "#3a3a5a"})
(set-face! :font-lock-comment-face {:fg "#7f8c98" :italic true})
```

Colors accept `"#rrggbb"` or `[r g b]`. Available properties are `:fg`, `:bg`, `:bold`,
`:italic`, `:underline`, and `:underline-color`. Overrides are stored in
`:face-overrides` and **survive theme changes**.

### Register your own theme

```clojure
;; Palette style: copy a built-in palette and change selected slots.
(register-theme!
  {:name :my-dark :label "My dark"
   :palette (palette-with (palette :space-dark) :keyword "#ff79c6")})

;; Difference style: only list faces to change. `:base` is the fallback theme
;; (the built-in default theme); `:none` means no fallback.
(register-theme!
  {:name :my-paper :label "My paper" :base :paper-light
   :faces {:region {:bg "#e8e0d0"} :cursor {:bg "#333333"}}})

(set-theme! :my-dark)
```

Palette slot names follow spacemacs-theme (`:bg1`, `:base`, `:keyword`, `:func`,
`:comment`, …; see `:slots` in `resources/coxn/themes.edn`). Each slot accepts one
`"#rrggbb"` or a two-value vector `["#true-color" "#256-color-fallback"]`.

## 11. User-interface language

```clojure
(set-language! :zh)   ; registered: en (source language) / zh
```

Precedence: **init.clj > persisted state (`<config>/language.edn`) > environment
variables > default `en`**. Environment-variable order is `COXN_LANGUAGE` > `LC_ALL` >
`LC_MESSAGES` > `LANG`; `zh_CN.UTF-8` resolves to `zh`. `M-x i18n-set-language` switches
and persists interactively; `M-x i18n-missing` lists messages missing from the current
language.

Add your own translations in `init.clj`:

```clojure
(coxn.i18n/catalog-merge! :zh {"Some message" "某条消息"})
```

## 12. Hooks and events

### Hooks

```clojure
(add-hook! :after-save-hook (fn [ed] (ed/message ed "saved!") ed))
```

A hook receives and returns an editor. An error is written to the echo area and does not
interrupt editing. Available hooks:

| Hook | Runs |
|---|---|
| `:after-init-hook` | After startup completes |
| `:find-file-hook` | After a file opens |
| `:after-save-hook` | After saving |
| `:kill-buffer-hook` | Before a buffer is killed (runs in the killed buffer) |
| `:kill-emacs-hook` | On exit |
| `:post-command-hook` | After every input event |
| `:post-self-insert-hook` | After self-inserting a character |
| `:window-change-hook` | After window layout changes |
| `:tick-hook` | Every main-loop tick (argument is milliseconds now) |
| `:change-major-mode-hook` / `:after-change-major-mode-hook` | Before / after changing a major mode |
| `<mode>-mode-hook` (for example `:clojure-mode-hook`, `:prog-mode-hook`) | After entering a major mode |
| `<minor-mode>-hook` (for example `:slime-mode-hook`) | After a minor mode turns on or off |

The third argument to `add-hook!` is depth (`-100..100`; default 0; `true` means 90,
following Emacs APPEND). Buffer-local hooks use `coxn.hooks/add-local-hook`.

### Events (bus)

```clojure
(subscribe! :document-opened (fn [event {:keys [buffer path new?]}] ...))
```

Events are **facts that already happened** (past tense + immutable payload); handlers do
not return an editor and cannot veto the event. Built-ins are `:document-opened`
(`{:buffer :path :new?}`) and `:document-renamed` (`{:buffer :new-buffer :path}`).
`subscribe!` returns an unsubscribe function.

## 13. Key bindings

```clojure
(bind-key! "C-c g" 'find-file)          ; global key
(unbind-key! "C-c g")
(prefix-name! "C-c l" "lsp")            ; prefix name shown by which-key
```

Key syntax follows Emacs: `C-`, `M-`, and `S-` modifiers, and sequences such as
`"C-x C-f"` separated by spaces. Command names are symbols (the names shown in `M-x`).
Define your own command:

```clojure
(defcommand my-hello "Say hello." [ed]
  (ed/message ed "hello!"))
(bind-key! "C-c h" 'my-hello)
```

## 14. Buffer-local configuration: EditorConfig and file-local variables

These configurations affect only one buffer and take precedence over global options.

### EditorConfig

When a file opens, coxn searches upward for `.editorconfig`, stopping at `root = true`;
sections closer to the file override higher sections. Supported standard properties:

| Property | Effect |
|---|---|
| `indent_style` | `space` / `tab` |
| `indent_size` | Indentation width (`tab` uses tab_width) |
| `tab_width` | Tab display width |
| `end_of_line` | `lf` / `crlf` |
| `trim_trailing_whitespace` | Remove trailing whitespace on save |
| `insert_final_newline` | Ensure a final newline on save |
| `max_line_length` | Maximum line width |

### file-local variables

Only whitelisted variables are recognized; **code in the file is never evaluated**.
Use the first line:

```c
/* -*- mode: c; indent-offset: 2; tab-width: 4 -*- */
```

or the end of the file:

```text
Local Variables:
fill-column: 80
End:
```

Whitelist: `mode` (only an already-registered major mode), `comment-start`,
`comment-end`, `fill-column`, `indent-offset`, `tab-width`, `indent-style`,
`insert-spaces?`, `eol`, `trim-trailing?`, `final-newline?`, `truncate-lines`, and
`eval-minibuffer?`.

## 15. Environment variables and system properties

| Variable / property | Purpose |
|---|---|
| `COXN_INIT` | Name the `init.clj` path (takes precedence over default locations) |
| `COXN_LANGUAGE` | UI language (takes precedence over `LC_ALL` / `LC_MESSAGES` / `LANG`; init.clj and persisted state override it) |
| `XDG_CONFIG_HOME` | Configuration directory `<config>` = `$XDG_CONFIG_HOME/coxn` on Linux/FreeBSD; default `~/.config/coxn`; Windows uses `%APPDATA%/coxn` |
| `XDG_CACHE_HOME` | Cache directory `<cache>` = `$XDG_CACHE_HOME/coxn`; default `~/.cache/coxn`; Windows uses `%LOCALAPPDATA%/coxn`. Auto-save, backup, and automatic LSP installation live beneath it |
| `COXN_DEBUG` | When set, enable TUI debug logging |
| `COXN_NATIVE_PATH` | Additional GUI search directory for tree-sitter native libraries (development) |
| `COLORTERM` / `TERM` / `WT_SESSION` | Inputs used by `:color-depth :auto` probing |
| `-Dcoxn.config.dir` / `-Dcoxn.cache.dir` | Portable installs / tests: point configuration / cache directories elsewhere (no legacy-directory migration is performed) |
| `-Dcoxn.lsp.auto=false` | Change the `:lsp-auto` default to off |
| `COXN_JDK` | Build-time path to the JDK used by `clojure -T:build dist` |

## 16. A complete init.clj example

```clojure
;; ~/.config/coxn/init.clj

;; Select layers (omitting this enables all).
(configuration-layers!
  [:tree-sitter :lsp :treemacs :git :helm
   :clojure :cider :cpp :java :javascript :html :css :markdown])

;; Editing
(set-option! :tab-width 4)
(set-option! :indent-offset 4)
(set-option! :fill-column 80)
(set-option! :electric-pair true)
(set-option! :display-line-numbers true)

;; Interface
(set-theme! :doom-dark)
(set-face! :region {:bg "#3a3a5a"})
(set-option! :minibuffer-display :bottom)
(set-option! :eldoc-display :echo)
(set-language! :zh)

;; GUI fonts (ignored by TUI)
(set-option! :gui-font ["JetBrains Mono" "Fira Code"])
(set-option! :gui-font-size 14)
(set-option! :gui-font-cjk ["Noto Sans Mono CJK SC"])

;; Completion / LSP
(set-option! :completion-auto-delay-ms 200)
(set-option! :lsp-inlay-hints true)
(set-option! :lsp-servers {:c++ [["clangd" "--background-index" "--clang-tidy"]]})
(set-option! :lsp-settings
  {"jdtls" {:java {:inlayHints {:parameterNames {:enabled "all"}}}}})

;; Project tree
(set-option! :treemacs-width 40)
(set-option! :treemacs-follow-mode true)

;; REPL
(set-option! :cider-clojure-cli-aliases ":dev:test")
(set-option! :inferior-lisp-program "sbcl")
(set-option! :slime-completion :fuzzy)

;; Keys and hooks
(bind-key! "C-c g" 'find-file)
(add-hook! :after-save-hook
  (fn [ed] (ed/message ed "saved %s" (or (:file (ed/cur-buffer ed)) "?")) ed))
```
