diff --git a/README.md b/README.md
index 9a99b69..650e184 100644
--- a/README.md
+++ b/README.md
@@ -260,6 +260,95 @@ let g:nuwiki_no_folding           = 0   " set to 1 to skip foldexpr setup
 let g:nuwiki_mouse_mappings       = 0   " set to 1 to enable mouse maps
 ```
 
+### Reference
+
+#### Top-level options
+
+| Key | Type | Default | Accepted values |
+|-----|------|---------|-----------------|
+| `wiki_root` | string (path) | `'~/vimwiki'` | any directory path |
+| `file_extension` | string | `'.wiki'` | any extension, leading `.` |
+| `syntax` | string | `'vimwiki'` | `'vimwiki'` (`'markdown'` planned) |
+| `log_level` | string | `'warn'` | `'error'` \| `'warn'` \| `'info'` \| `'debug'` |
+| `folding` | string | `'lsp'` | `'lsp'` \| `'expr'` \| `'off'` |
+| `wikis` | list of tables | `nil` | per-wiki tables (see below); wins over the single-wiki shorthand |
+| `mappings` | table | all on | keymap subgroups (see below) |
+| `diagnostic` | table | — | `{ link_severity = … }` (see note below) |
+
+#### `mappings` subgroups
+
+Each is a boolean. All default to `true` except `mouse`.
+
+| Key | Default | Controls |
+|-----|---------|----------|
+| `enabled` | `true` | master switch for the whole keymap layer |
+| `wiki_prefix` | `true` | `<Leader>w*` |
+| `links` | `true` | `<CR>`, `<S-CR>`, `<Tab>`, `<BS>`, `+`, … |
+| `lists` | `true` | `<C-Space>`, `gln`/`glp`/`glx`, `gl<Space>`, `o`/`O`, … |
+| `headers` | `true` | `=`, `-`, `]]`, `[[`, `]=`, `[=`, `]u`, `[u` |
+| `table_editing` | `true` | `gqq`, `<A-Left>`, `<A-Right>`, `<Tab>` (insert) |
+| `diary` | `true` | `<C-Down>`, `<C-Up>` |
+| `html_export` | `true` | `<Leader>wh`, `<Leader>whh` |
+| `text_objects` | `true` | `ah`, `ih`, `aH`, `iH`, `al`, `il`, `a\`, `i\`, `ac`, `ic` |
+| `mouse` | `false` | `<2-LeftMouse>`, `<RightMouse>`, … (opt-in) |
+
+#### Per-wiki keys (`wikis[]`)
+
+| Key | Type | Default | Accepted values |
+|-----|------|---------|-----------------|
+| `name` | string | — | any label |
+| `root` | string (path) | — | any directory path |
+| `file_extension` | string | `'.wiki'` | any extension |
+| `syntax` | string | `'vimwiki'` | `'vimwiki'` |
+| `index` | string | `'index'` | index page stem |
+| `diary_rel_path` | string | `'diary'` | path relative to `root` |
+| `diary_index` | string | `'diary'` | diary index page stem |
+| `diary_frequency` | string | `'daily'` | `'daily'` \| `'weekly'` \| `'monthly'` \| `'yearly'` |
+| `diary_start_week_day` | string | `'monday'` | weekday name |
+| `diary_caption_level` | int | `1` | `0`–`6` |
+| `diary_sort` | string | `'desc'` | `'desc'` \| `'asc'` |
+| `diary_header` | string | `'Diary'` | any heading text |
+| `maxhi` | int (bool) | `1` | `0` \| `1` |
+| `listsyms` | string | `' .oOX'` | checkbox progression chars |
+| `listsyms_propagate` | bool | `true` | `true` \| `false` |
+| `list_margin` | int | `-1` | `-1` (auto) or `≥ 0` |
+| `links_space_char` | string | `' '` | char that replaces spaces in synthesised link paths |
+| `nested_syntaxes` | table | `{}` | `{ ['fence-lang'] = 'vim-syntax', … }` |
+| `auto_toc` | bool | `false` | `true` \| `false` |
+
+#### HTML export keys (per-wiki)
+
+| Key | Type | Default | Accepted values |
+|-----|------|---------|-----------------|
+| `html_path` | string (path) | `'<root>/_html'` | output directory |
+| `template_path` | string (path) | `'<root>/_templates'` | template directory |
+| `template_default` | string | `'default'` | template stem |
+| `template_ext` | string | `'.tpl'` | template extension |
+| `template_date_format` | string | `'%Y-%m-%d'` | strftime format |
+| `css_name` | string | `'style.css'` | stylesheet filename |
+| `auto_export` | bool | `false` | `true` \| `false` (export on save) |
+| `html_filename_parameterization` | bool | `false` | `true` \| `false` |
+| `exclude_files` | list | `{}` | glob patterns |
+| `color_dic` | table | `{}` | `{ name = 'color', … }` |
+
+#### Vim globals (`g:nuwiki_*`)
+
+For users configuring without Lua.
+
+| Global | Default | Meaning |
+|--------|---------|---------|
+| `g:nuwiki_wiki_root` | `'~/vimwiki'` | single-wiki root |
+| `g:nuwiki_file_extension` | `'.wiki'` | wiki file extension |
+| `g:nuwiki_log_level` | `'warn'` | `error` \| `warn` \| `info` \| `debug` |
+| `g:nuwiki_no_default_mappings` | `0` | `1` skips the keymap layer |
+| `g:nuwiki_no_folding` | `0` | `1` skips foldexpr setup |
+| `g:nuwiki_mouse_mappings` | `0` | `1` enables mouse maps |
+
+> **Note:** `diagnostic.link_severity` is accepted in the config surface but
+> the server currently always uses its default (`'warn'`); the client value is
+> not yet wired through. Track this if you rely on changing broken-link
+> severity.
+
 ---
 
 ## Usage
diff --git a/crates/nuwiki-lsp/src/config.rs b/crates/nuwiki-lsp/src/config.rs
index 2998111..d216cff 100644
--- a/crates/nuwiki-lsp/src/config.rs
+++ b/crates/nuwiki-lsp/src/config.rs
@@ -65,7 +65,8 @@ pub struct WikiConfig {
     /// that many extra columns. Layout hint for the renderer.
     pub list_margin: i32,
     /// Character used in place of literal spaces inside wikilink
-    /// targets when writing to disk (`_` by default).
+    /// targets when writing to disk (a single space `" "` by default,
+    /// i.e. spaces are kept verbatim).
     pub links_space_char: String,
     /// `nested_syntaxes` — code-block language → editor filetype map
     /// used for syntax-highlighting fenced blocks. Empty by default.