diff --git a/development/calendar-vim-integration.md b/development/calendar-vim-integration.md
new file mode 100644
index 0000000..7eb711a
--- /dev/null
+++ b/development/calendar-vim-integration.md
@@ -0,0 +1,41 @@
+# Calendar-Vim Integration Use Case Specification
+
+## Overview
+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):
+- `g:calendar_action = 'vimwiki#diary#calendar_action'`
+- `g:calendar_sign = 'vimwiki#diary#calendar_sign'`
+
+## Primary Use Case: Viewing/Create Diary Entries
+1. User executes `:Calendar` command
+2. Calendar-vim displays navigable calendar interface
+3. User navigates to target date using arrow keys
+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
+6. User views/edits diary entry for selected date
+
+## Date Marking Functionality
+- `vimwiki#diary#calendar_sign` function determines which dates show markers (*)
+- Returns true if diary file exists for that date using wiki's path configuration
+- Provides visual indication of dates with existing diary entries
+
+## Key Features
+- Seamless navigation between calendar and diary entries
+- 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
+
+## Configuration
+Controlled by:
+- `g:vimwiki_use_calendar` (global toggle)
+- Individual wiki configurations in `g:vimwiki_list` (path, diary_rel_path, ext)
+- 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