From 21f583beefb558db98330f0c5a62219dccc5ce86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Fr=C3=B3es=20Franco?= <gffranco@gmail.com>
Date: Sun, 31 May 2026 21:58:06 -0300
Subject: [PATCH] docs(calendar): fix stale comments and integration docs

- diary.vim: correct calendar_action doc comment (dir is used for split
  direction; only week is unused)
- calendar-vim-integration.md: use real nuwiki var names
  (g:nuwiki_use_calendar / g:nuwiki_no_calendar / g:nuwiki_wikis), document
  auto-detect wiring and calendar-window close behavior; drop the
  non-existent refresh-on-close autocmd
- vimwiki-gap.md: remove stale 'no calendar.vim integration' entry now
  that the integration is implemented
---
 autoload/nuwiki/diary.vim               |  3 ++-
 development/calendar-vim-integration.md | 22 +++++++++++++++-------
 development/vimwiki-gap.md              |  1 -
 3 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/autoload/nuwiki/diary.vim b/autoload/nuwiki/diary.vim
index a6c28b2..f0c2cbd 100644
--- a/autoload/nuwiki/diary.vim
+++ b/autoload/nuwiki/diary.vim
@@ -5,7 +5,8 @@
 
 " Function: nuwiki#diary#calendar_action(day, month, year, week, dir)
 " Called by calendar-vim when user presses Enter on a date.
-" day/month/year are numeric integers. week and dir are not used.
+" day/month/year are numeric integers; dir is 'V' for a vertical split (any
+" other value means a horizontal split). week is unused.
 " Opens or creates the diary entry for the given date.
 function! nuwiki#diary#calendar_action(day, month, year, week, dir) abort
   " Build YYYY-MM-DD from the parts passed by calendar-vim
diff --git a/development/calendar-vim-integration.md b/development/calendar-vim-integration.md
index 7eb711a..af929cc 100644
--- a/development/calendar-vim-integration.md
+++ b/development/calendar-vim-integration.md
@@ -4,10 +4,15 @@
 This document describes how nuwiki (vimwiki) integrates with calendar-vim to provide graphical calendar navigation for wiki diary entries.
 
 ## Integration Mechanism
-Nuwiki activates the integration by setting calendar-vim's hook variables when `g:vimwiki_use_calendar` is enabled (default: true):
+Nuwiki auto-detects calendar-vim on the runtimepath (via a `FileType vimwiki`
+autocmd in `plugin/nuwiki.vim`) and wires calendar-vim's hook variables, unless
+the integration is disabled (default: enabled):
 - `g:calendar_action = 'vimwiki#diary#calendar_action'`
 - `g:calendar_sign = 'vimwiki#diary#calendar_sign'`
 
+These hooks are only set when unset or still at calendar-vim's own defaults
+(`calendar#diary` / `calendar#sign`), so a user-chosen custom hook is preserved.
+
 ## Primary Use Case: Viewing/Create Diary Entries
 1. User executes `:Calendar` command
 2. Calendar-vim displays navigable calendar interface
@@ -15,9 +20,9 @@ Nuwiki activates the integration by setting calendar-vim's hook variables when `
 4. User presses `<Enter>` on selected date
 5. `vimwiki#diary#calendar_action` function executes:
    - Formats date as YYYY-MM-DD
-   - Opens existing diary file or creates new one
-   - Applies appropriate wiki filetype
-   - Sets up autocmd to refresh calendar on file close
+   - Opens existing diary file or creates new one (split/vsplit per `dir`)
+   - Applies the vimwiki filetype to a brand-new entry
+   - Closes the calendar window once the diary entry is open
 6. User views/edits diary entry for selected date
 
 ## Date Marking Functionality
@@ -30,12 +35,15 @@ Nuwiki activates the integration by setting calendar-vim's hook variables when `
 - Automatic file creation/opening for selected dates
 - Visual indicators for dates with existing content
 - Proper window splitting based on calendar orientation
-- Automatic calendar refresh after editing diary entries
+- Calendar window closed automatically once the diary entry opens
 
 ## Configuration
 Controlled by:
-- `g:vimwiki_use_calendar` (global toggle)
-- Individual wiki configurations in `g:vimwiki_list` (path, diary_rel_path, ext)
+- `use_calendar` Lua option (Neovim `setup()`), default `true`
+- `g:nuwiki_use_calendar` / `g:nuwiki_no_calendar` (VimL global toggles)
+- Individual wiki configurations in `g:nuwiki_wikis` (root, diary_rel_path,
+  file_extension), or the scalar `g:nuwiki_wiki_root` / `g:nuwiki_diary_rel_path`
+  / `g:nuwiki_file_extension` fallbacks
 - Standard calendar-vim variables for appearance/customization
 
 This integration leverages calendar-vim's strong date presentation while using nuwiki's diary system for file management, creating a cohesive experience for journal-style wiki usage.
\ No newline at end of file
diff --git a/development/vimwiki-gap.md b/development/vimwiki-gap.md
index 12f55c9..fc79b6c 100644
--- a/development/vimwiki-gap.md
+++ b/development/vimwiki-gap.md
@@ -179,7 +179,6 @@ audits don't re-flag them.
   backed by LSP foldingRange.
 - `key_mappings` (dict) — replaced by Lua `mappings.<group>` + the
   `g:nuwiki_no_<group>_mappings` globals.
-- `use_calendar` — no calendar.vim integration.
 - `CJK_length`, `listing_hl*`, `schemes_*`, `w32_dir_enc`, `menu`,
   `rx_todo` / `tag_format` — syntax internals, menu, or Vim/Win shims.