docs(gap): record 2026-06-03 codebase-review findings (R1-R18)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

development/vimwiki-gap.md

@@ -785,3 +785,74 @@ audits don't re-flag them.
   generated headers) remains one future effort; `list_ignore_newline` /
   `text_ignore_newline` = `false` (→ `<br>`) needs a parser-level soft-break
   node (the `= true` default, which is upstream's default, already works).
+
+---
+
+## Codebase review findings (2026-06-03)
+
+Full read-only review (4 parallel agents: dead code, optimization, docs,
+client) + verification. Clippy/compiler clean overall. Tracked here so we
+don't lose them; checked off as fixed.
+
+### P1 — user-facing / real bugs
+- [ ] **R1 Docs: the 2026-06-03 config batch is undocumented** in `README.md`
+  + `doc/nuwiki.txt` (~22 options: per-wiki `create_link`/`dir_link`/
+  `bullet_types`/`cycle_bullets`/`generated_links_caption`/`toc_link_format`/
+  `table_reduce_last_col`/`diary_months`; HtmlConfig `rss_name`/`rss_max_items`/
+  `valid_html_tags`/`list_ignore_newline`/`text_ignore_newline`/`emoji_enable`/
+  `user_htmls`/`color_tag_template`; client `auto_header`/`auto_chdir`/
+  `autowriteall`/`table_auto_fmt`/`use_calendar`).
+- [ ] **R2 `wiki_root_for` falls back to the first wiki when the file is under
+  no wiki** (`autoload/nuwiki/commands.vim`, `lua/nuwiki/config.lua`, inlined in
+  `search`). `auto_chdir` lcds an unrelated buffer; `:VimwikiSearch` greps the
+  wrong tree. Fix: return empty/nil on no match; callers no-op / fall back to CWD.
+
+### P2 — dead code, correctness, perf
+- [ ] **R3 Color render chain unreached** — the vimwiki parser never builds
+  `InlineNode::Color`, so `render_color`/`colors`/`with_colors`/`default_color_dic`
+  are dead on the parse path (verified). Fix: make `render_color` honour
+  `color_tag_template` (so the field is consumed) + document ColorNode as a
+  wired extension point (colour currently flows via `:Colorize` span +
+  `valid_html_tags`).
+- [ ] **R4 `color_tag_template` (Rust HtmlConfig) stored but never read** —
+  resolved by R3 (render_color consumes it).
+- [ ] **R5 `Wiki.config` cloned wholesale on every `wiki_for_uri`** — make it
+  `Arc<WikiConfig>` (clone → refcount bump). Hot path.
+- [ ] **R6 `WorkspaceIndex::remove` is O(n²)** — scans every backlink/tag value
+  vec per `upsert`. Track per-source contributed keys.
+- [ ] **R7 `auto_header` ignores `links_space_char`** — H1 uses the raw stem;
+  a `links_space_char='_'` wiki gets `= My_Page =` not `= My Page =`.
+- [ ] **R8 `cursor_inside_wikilink` off-by-one** (`commands.vim`, `commands.lua`)
+  — `< len` misses a `]]`/`[[` ending at EOL.
+- [ ] **R9 Doc contradictions**: `doc/nuwiki.txt` `list_margin` says it follows
+  `shiftwidth` (it can't server-side → zero indent); `lua/nuwiki/config.lua`
+  per-wiki key comment stale; gap-doc trailing "Deferred" note still lists
+  `list/text_ignore_newline` though done.
+
+### P3 — cleanups, dedup, cold-path opts
+- [ ] **R10 Dead `#[allow(dead_code)]` import-retention stubs** —
+  `config.rs` `_ensure_url_is_used`, `commands.rs` `_retain_tag_occurrence_import`
+  + `export_ops::_silence_unused`, `lib.rs` `DocumentState.version`. Remove
+  stubs + narrow imports.
+- [ ] **R11 Uncalled `pub` helpers** — `registry::register_arc`,
+  `WorkspaceEditBuilder::edits`, `export::html_output_dir`,
+  `index::diary_date_for_uri`. Remove (verify zero callers).
+- [ ] **R12 Duplicated `span_of_inline` ×3** (parser/nav/semantic_tokens) →
+  one `InlineNode::span()` method. Also `s:wiki_cfg` duplicated
+  (commands.vim+diary.vim) and wiki-root resolution inlined 3 ways.
+- [ ] **R13 Cold-path opts** — RSS `render_entry_body` re-reads/parses open
+  docs + rebuilds renderer per entry; `page_captions` double-lookup + wasted
+  sort; `push_level_edit_for_line` walks from offset 0 per line; diary next/prev
+  rebuild+sort for one neighbor; `diary_step` double lock.
+- [ ] **R14 `auto_header` Neovim loop fragile** (`for i=0,64`, dead break) → use
+  `wiki_list()`; add `auto_header = false` to lua config defaults.
+- [ ] **R15 `autoload/vimwiki/vars.vim` shim ignores the wiki index** —
+  `get_wikilocal(key, N)` always returns wiki 0 (latent multi-wiki bug for
+  third-party plugins).
+
+### P4 — trivial
+- [ ] **R16** `ftplugin/vimwiki.vim` header comment says `ftplugin/nuwiki.vim`.
+- [ ] **R17** `:VimwikiNormalizeLink` uses `<args>` not `<q-args>` → E121 on a
+  non-numeric arg.
+- [ ] **R18** `lua/nuwiki/commands.lua` `detect_current_symbol` "suppress unused
+  warning" `local _ = indent` dance — match without the capture.