docs: add known-issues.md gathering vimwiki divergences

Consolidate the deferred features and intentional divergences from the
parity log (development/vimwiki-gap.md) into a user-facing reference:
- Deferred: the markdown generated-content cluster
  (markdown heading generation, markdown_header_style, markdown_link_ext)
- By-design divergences grouped by area (highlighting/conceal -> LSP,
  syntax detection, config mechanism, auto_tags, mouse maps, list_margin
  negative + diary_caption_level -1 value semantics, Vim/Win shims)
- Default-location differences (html_path/template_path/diary_rel_path)
- Notes on the vars.vim compat shim and additive commands

Link it from the README "Migrating from vimwiki" section so it's
discoverable.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

known-issues.md

@@ -0,0 +1,120 @@
+# Known Issues & Divergences from vimwiki
+
+nuwiki is an LSP-backed reimplementation of [vimwiki](https://github.com/vimwiki/vimwiki),
+not a fork of the original VimL plugin. It targets behavioral parity with
+vimwiki, but a handful of upstream options and behaviors are implemented
+differently — or intentionally not at all — because of that architecture.
+
+This page lists what to expect if you're coming from vimwiki. Everything here
+is either a deliberate design choice or a tracked future task; none of it is an
+accidental bug. For the detailed, per-option parity log (with code references
+and test names), see [`development/vimwiki-gap.md`](development/vimwiki-gap.md).
+
+If you hit a behavior that *isn't* listed here and doesn't match vimwiki, please
+file it — that's a real bug.
+
+---
+
+## Deferred (planned, not yet implemented)
+
+These are genuine feature gaps that we intend to close, grouped because they
+ship together.
+
+### Markdown generated-content
+
+The buffer-side generators — TOC (`:VimwikiTOC`), generated links
+(`:VimwikiGenerateLinks`), the tags index (`:VimwikiGenerateTagLinks`), and the
+diary index — always emit **vimwiki** markup (`= Heading =`), regardless of the
+wiki's `syntax`. Markdown wikis therefore get vimwiki-syntax generated sections.
+
+Dependent on markdown-syntax generation, and deferred until it lands:
+
+- **markdown-style heading generation** in those generators (`# Heading`).
+- **`markdown_header_style`** — blank lines after a generated *markdown* header
+  (no markdown header exists to attach it to yet).
+- **`markdown_link_ext`** — append the file extension in generated markdown links.
+
+Hand-authored markdown content renders fine; only the *generated* sections are
+affected.
+
+---
+
+## Behavioral divergences (by design)
+
+These upstream options have no nuwiki equivalent, because the LSP server
+provides the capability a different way. They will not be re-implemented as-is.
+
+### Highlighting & display
+
+| vimwiki option | nuwiki behavior |
+|----------------|-----------------|
+| `maxhi` | Broken/existence-based link highlighting is provided by **LSP diagnostics** instead (severity is configurable via `diagnostic.link_severity`). |
+| `conceallevel`, `conceal_onechar_markers`, other `conceal*` | Replaced by **LSP semantic tokens**; there is no conceal layer to configure. |
+
+### Syntax detection
+
+| vimwiki option | nuwiki behavior |
+|----------------|-----------------|
+| `nested_syntaxes` / `automatic_nested_syntaxes` | Code-fence languages are auto-detected from the fence tag (` ```python `); always on, no toggle. |
+| `ext2syntax` | Syntax is chosen by file extension / the per-wiki `syntax` key automatically. |
+| `global_ext` | The configured wiki extension(s) always map to the `vimwiki` filetype regardless of location; there is no per-wiki "only inside the root" toggle (effectively always on). |
+| `syntax` default name | nuwiki defaults the per-wiki `syntax` to `vimwiki` where upstream defaults to `default` — a naming difference only, not behavioral. |
+
+### Configuration mechanism
+
+| vimwiki option | nuwiki behavior |
+|----------------|-----------------|
+| `folding` (string) | Replaced by `folding = 'lsp' \| 'expr' \| 'off'`, backed by the LSP `foldingRange` provider. |
+| `key_mappings` (dict) | Replaced by the Lua `mappings.<group>` table and the `g:nuwiki_no_<group>_mappings` globals. |
+
+### Tags
+
+| vimwiki option | nuwiki behavior |
+|----------------|-----------------|
+| `auto_tags` | Upstream maintains an on-disk tag *metadata* file on save. nuwiki has no such file: the server re-indexes tags on every change, so tag search / jump / completion are always fresh. The configurable on-save piece (regenerating the in-buffer links section) is `auto_generate_tags`. |
+
+### Mappings
+
+| vimwiki option | nuwiki behavior |
+|----------------|-----------------|
+| Mouse maps (`<2-LeftMouse>`, `<MiddleMouse>`, …) | Upstream binds these unconditionally; nuwiki ships them **opt-in** via `mappings.mouse` / `g:nuwiki_mouse_mappings`. |
+
+### Value-semantics differences
+
+| vimwiki option | nuwiki behavior |
+|----------------|-----------------|
+| `list_margin` (negative) | Upstream resolves a negative value to the buffer's `'shiftwidth'`. The server can't observe `'shiftwidth'`, so negative values collapse to **zero** leading indent on generated bullets. Set a non-negative number for a fixed indent. |
+| `diary_caption_level = -1` | Accepted (the field is deserializable), but **clamps to `0`**. nuwiki builds the diary index tree from dates, so upstream's `-1` = "no per-page captions" semantic doesn't apply. |
+
+### Vim/Win shims & syntax internals (not applicable)
+
+`CJK_length`, `listing_hl*`, `schemes_*`, `w32_dir_enc`, `menu`, `rx_todo`,
+`tag_format` — these are syntax internals, menu definitions, or Vim/Windows
+shims with no role in an LSP-backed implementation.
+
+---
+
+## Default-location differences
+
+Where you don't set a path explicitly, nuwiki derives a different *default
+location* than upstream — by design, so each wiki is root-relative and
+self-contained. You can set any of these explicitly to match upstream exactly.
+
+| Key | nuwiki default | upstream default |
+|-----|----------------|------------------|
+| `html_path` | `<root>/_html` | sibling `<wikidir>_html/` |
+| `template_path` | `<root>/_templates` | global `~/vimwiki/templates/` |
+| `diary_rel_path` | `diary` | `diary/` (trailing slash only — paths join identically, so behavior matches) |
+
+---
+
+## Notes
+
+- **Third-party plugin compatibility.** A shim at `autoload/vimwiki/vars.vim`
+  exposes the subset of `vimwiki#vars#get_wikilocal` that plugins like
+  vimwiki-sync and vim-zettel call (`path`, `ext`/`extension`, `syntax`,
+  `is_temporary_wiki`), resolved from nuwiki's own config — including the
+  correct per-wiki values in a multi-wiki setup. Add keys there if a plugin you
+  use needs more.
+- **Additive commands.** nuwiki adds some commands with no upstream equivalent
+  (e.g. `:NuwikiFindOrphans`). These are additions, not divergences.