feat(doc): comprehensive documentation on missing things

doc/cp.txt

@@ -72,9 +72,47 @@ COMMANDS                                                        *cp-commands*
             :CP next            Navigate to next problem in current contest.
                                 Stops at last problem (no wrapping).
 
+        Navigation Commands ~
             :CP prev            Navigate to previous problem in current contest.
                                 Stops at first problem (no wrapping).
 
+Command Flags ~
+                                                                *cp-flags*
+    Flags can be used with setup and action commands:
+
+    --lang={language}           Specify language for the problem.
+    --lang {language}           Alternative syntax for language specification.
+                                Supported languages: cpp, python
+                                Example: >
+                                    :CP atcoder abc324 a --lang=python
+                                    :CP b --lang cpp
+<
+    --debug                     Enable debug compilation with additional flags.
+                                Uses the `debug` command template instead of
+                                `compile`. Typically includes debug symbols and
+                                sanitizers for memory error detection.
+                                Example: >
+                                    :CP run --debug
+<
+                                Note: Debug compilation may be slower but provides
+                                better error reporting for runtime issues.
+
+Template Variables ~
+                                                        *cp-template-vars*
+    Command templates support variable substitution using `{variable}` syntax:
+
+    • {source}      Source file path (e.g. "abc324a.cpp")
+    • {binary}      Output binary path (e.g. "build/abc324a.run")
+    • {version}     Language version when specified in config
+    • {contest}     Contest identifier (e.g. "abc324", "1933")
+    • {problem}     Problem identifier (e.g. "a", "b")
+
+    Example template: >
+        compile = { 'g++', '{source}', '-o', '{binary}', '-std=c++{version}' }
+<    Would expand to: >
+        g++ abc324a.cpp -o build/abc324a.run -std=c++17
+<
+
 ==============================================================================
 CONFIGURATION                                                   *cp-config*
 
@@ -171,7 +209,17 @@ Here's an example configuration with lazy.nvim: >lua
 
                                                             *cp.DiffConfig*
     Fields: ~
-        {git}           (|DiffGitConfig|) Git diff backend configuration.
+        {git}           (|cp.DiffGitConfig|) Git diff backend configuration.
+
+                                                         *cp.DiffGitConfig*
+    Fields: ~
+        {args}          (string[]) Command-line arguments for git diff.
+                        Default: { 'diff', '--no-index', '--word-diff=plain',
+                                  '--word-diff-regex=.', '--no-prefix' }
+                        • --no-index: Compare files outside git repository
+                        • --word-diff=plain: Character-level diff markers
+                        • --word-diff-regex=.: Split on every character
+                        • --no-prefix: Remove a/ b/ prefixes from output
 
                                                                 *cp.Hooks*
     Fields: ~
@@ -184,6 +232,8 @@ Here's an example configuration with lazy.nvim: >lua
                         function(ctx: ProblemContext)
 
                                                          *ProblemContext*
+    Context object passed to hook functions containing problem information.
+
     Fields: ~
         {contest}       (string) Platform name (e.g. "atcoder", "codeforces")
         {contest_id}    (string) Contest ID (e.g. "abc123", "1933")
@@ -195,6 +245,15 @@ Here's an example configuration with lazy.nvim: >lua
         {expected_file} (string) Expected output path (e.g. "io/abc123a.expected")
         {problem_name}  (string) Display name (e.g. "abc123a")
 
+    Example usage in hook: >lua
+        hooks = {
+          setup_code = function(ctx)
+            print("Setting up " .. ctx.problem_name)
+            print("Source file: " .. ctx.source_file)
+          end
+        }
+<
+
 ==============================================================================
 WORKFLOW                                                        *cp-workflow*
 
@@ -209,26 +268,49 @@ AtCoder ~
                                                              *cp-atcoder*
 URL format: https://atcoder.jp/contests/abc123/tasks/abc123_a
 
+AtCoder contests use consistent naming patterns where contest ID and problem
+ID are combined to form the task name.
+
+Platform characteristics:
+• Contest types: ABC (Beginner), ARC (Regular), AGC (Grand), etc.
+• Problem naming: Contest ID + problem letter (e.g. "abc324_a")
+• Multi-test problems: Handled with conditional compilation directives
+• Template features: Includes fast I/O and common competitive programming
+  headers
+
 In terms of cp.nvim, this corresponds to:
 - Platform: atcoder
-- Contest ID: abc123
+- Contest ID: abc123 (from URL path segment)
-- Problem ID: a
+- Problem ID: a (single letter, extracted from task name)
 
 Usage examples: >
-    :CP atcoder abc123 a        " Full setup: problem A from contest ABC123
+    :CP atcoder abc324 a        " Full setup: problem A from contest ABC324
-    :CP atcoder abc123          " Contest setup: load contest metadata only
+    :CP atcoder abc324          " Contest setup: load contest metadata only
     :CP b                       " Switch to problem B (if contest loaded)
     :CP next                    " Navigate to next problem in contest
 <
+                                Note: AtCoder template includes optimizations
+                                for multi-test case problems commonly found
+                                in contests.
 
 Codeforces ~
                                                           *cp-codeforces*
 URL format: https://codeforces.com/contest/1234/problem/A
 
+Codeforces uses numeric contest IDs with letter-based problem identifiers.
+Educational rounds, gym contests, and regular contests all follow this pattern.
+
+Platform characteristics:
+• Contest types: Regular, Educational, Div. 1/2/3, Global rounds
+• Problem naming: Numeric contest + problem letter
+• Multi-test support: Template includes test case loop structure
+• Interactive problems: Supported with flush handling
+• Time/memory limits: Typically 1-2 seconds, 256 MB
+
 In terms of cp.nvim, this corresponds to:
 - Platform: codeforces
-- Contest ID: 1234
+- Contest ID: 1234 (numeric, from URL)
-- Problem ID: a (lowercase)
+- Problem ID: a (lowercase letter, normalized from URL)
 
 Usage examples: >
     :CP codeforces 1934 a       " Full setup: problem A from contest 1934
@@ -236,24 +318,35 @@ Usage examples: >
     :CP c                       " Switch to problem C (if contest loaded)
     :CP prev                    " Navigate to previous problem in contest
 <
+                                Note: Problem IDs are automatically converted
+                                to lowercase for consistency.
 
 CSES ~
                                                                 *cp-cses*
 URL format: https://cses.fi/problemset/task/1068
 
-CSES is organized by categories rather than contests. Currently all problems
+CSES (Code Submission Evaluation System) is organized by problem categories
-are grouped under "CSES Problem Set" category.
+rather than traditional contests. All problems are accessible individually.
+
+Platform characteristics:
+• Organization: Category-based (Introductory, Sorting, Dynamic Programming)
+• Problem numbering: Sequential numeric IDs (1001, 1068, etc.)
+• Difficulty progression: Problems increase in complexity within categories
+• No time pressure: Educational focus rather than contest environment
+• Cache expiry: 30 days (problems may be updated periodically)
 
 In terms of cp.nvim, this corresponds to:
 - Platform: cses
-- Contest ID: "CSES Problem Set" (category)
+- Contest ID: Problem ID (1068) - used as both contest and problem identifier
-- Problem ID: 1068 (numeric)
+- Problem ID: nil (not applicable for CSES structure)
 
 Usage examples: >
     :CP cses 1068               " Set up problem 1068 from CSES
-    :CP 1070                    " Switch to problem 1070 (if CSES loaded)
+    :CP 1070                    " Switch to problem 1070 (if CSES context loaded)
-    :CP next                    " Navigate to next problem in CSES
+    :CP next                    " Navigate to next problem in CSES sequence
 <
+                                Note: CSES problems are treated as individual
+                                entities rather than contest problems.
 ==============================================================================
 COMPLETE WORKFLOW EXAMPLE                                        *cp-example*
 
@@ -312,20 +405,26 @@ Activation ~
 
 Interface ~
 
-The run panel uses a professional table layout with precise column alignment: >
+The run panel uses the following table layout: >
 
-    ┌──┬────────┬────────┬───────────┐ ┌─ Expected vs Actual ─────────┐
+    ┌─────┬────────┬──────────────┬───────────┬──────────┬─────────────┐
-    │# │ Status │  Time  │ Exit Code │ │ 45.70ms │ Exit: 0           │
+    │  #  │ Status │ Runtime (ms) │ Time (ms) │ Mem (MB) │  Exit Code  │
-    ├──┼────────┼────────┼───────────┤ ├───────────────────────────────┤
+    ├─────┼────────┼──────────────┼───────────┼──────────┼─────────────┤
-    │1 │   AC   │12.00ms │     0     │ │                               │
+    │ 1   │     AC │         12.0 │      2000 │      256 │           0 │
-    │>2│   WA   │45.70ms │     1     │ │ 4[-2-]{+3+}                  │
+    │> 2  │     WA │        45.70 │      2000 │      256 │           1 │
-    ├──┴────────┴────────┴───────────┤ │ 100                          │
+    ├─────┴────────┴──────────────┴───────────┴──────────┴─────────────┤
-    │5 3                             │ │ hello w[-o-]r{+o+}ld         │
+    │Input:                                                            │
-    ├──┬────────┬────────┬───────────┤ │                               │
+    │5 3                                                               │
-    │3 │   AC   │ 9.00ms │     0     │ └───────────────────────────────┘
+    ├─────┬────────┬──────────────┬───────────┬──────────┬─────────────┤
-    │4 │   RTE  │ 0.00ms │139 (SIGUSR2)│
+    │ 3   │     AC │          9.0 │      2000 │      256 │           0 │
-    └──┴────────┴────────┴───────────┘
+    │ 4   │    RTE │          0.0 │      2000 │      256 │139 (SIGUSR2)│
-<
+    └─────┴────────┴──────────────┴───────────┴──────────┴─────────────┘
+    ┌──────────────────────────────────────────────────────────────────┐
+    │Expected vs Actual                                                │
+    │4[-2-]{+3+}                                                       │
+    │100                                                               │
+    │hello w[-o-]r{+o+}ld                                              │
+    └──────────────────────────────────────────────────────────────────┘
 
 Status Indicators ~
 
@@ -396,6 +495,97 @@ cp.nvim creates the following file structure upon problem setup: >
 The plugin automatically manages this structure and navigation between problems
 maintains proper file associations.
 
+==============================================================================
+CACHING SYSTEM                                                  *cp-caching*
+
+cp.nvim maintains a persistent cache to improve performance and enable offline
+functionality. The cache stores contest metadata, problem lists, test cases,
+and file-to-context mappings.
+
+Cache Location ~
+                                                          *cp-cache-location*
+Cache is stored at: >
+    vim.fn.stdpath('data') .. '/cp-nvim.json'
+<
+Typically resolves to:
+• Linux/macOS: `~/.local/share/nvim/cp-nvim.json`
+• Windows: `%LOCALAPPDATA%\nvim-data\cp-nvim.json`
+
+Cache Structure ~
+                                                         *cp-cache-structure*
+The cache contains four main sections:
+
+contest_data                    Contest metadata and problem lists
+• Indexed by: `platform:contest_id`
+• Contains: Problem names, IDs, URLs, constraints
+• Expiry: Platform-dependent (see |cp-cache-expiry|)
+
+test_cases                      Scraped test case input/output pairs
+• Indexed by: `platform:contest_id:problem_id`
+• Contains: Input data, expected output, test case count
+• Expiry: Never (local test data persists)
+
+file_states                     File-to-context mapping
+• Indexed by: Absolute file path
+• Contains: Platform, contest_id, problem_id, language
+• Purpose: Enables context restoration with `:CP`
+
+timestamps                      Last update times for cache validation
+• Tracks: When each cache entry was last refreshed
+• Used for: Expiry checking and incremental updates
+
+Cache Expiry Policy ~
+                                                           *cp-cache-expiry*
+Different data types have different expiry policies:
+
+AtCoder/Codeforces contest data Never expires (contests are immutable)
+CSES problem data              30 days (problems may be updated)
+Test cases                     Never expires (local test data)
+File states                    Never expires (tracks user workspace)
+
+Manual Cache Management ~
+                                                      *cp-cache-management*
+While cache management is automatic, you can manually intervene:
+
+Clear specific contest cache: >
+    :lua require('cp.cache').clear_contest('atcoder', 'abc324')
+<
+Clear all cache data: >
+    :lua require('cp.cache').clear_all()
+<
+Force refresh contest metadata: >
+    :lua require('cp.cache').refresh_contest('codeforces', '1934')
+<
+View cache statistics: >
+    :lua print(vim.inspect(require('cp.cache').get_stats()))
+<
+                                Note: Manual cache operations require Lua
+                                knowledge and are primarily for debugging.
+
+Offline Functionality ~
+                                                         *cp-cache-offline*
+The cache enables limited offline functionality:
+
+✓ Restore context from cached file states
+✓ Navigate between cached problems in a contest
+✓ Access cached test cases for local development
+✓ Use cached templates and configuration
+
+✗ Scrape new problems without internet connection
+✗ Download new contest metadata
+✗ Update problem constraints or test cases
+
+Performance Considerations ~
+                                                      *cp-cache-performance*
+The cache provides several performance benefits:
+
+• Instant context restoration: No network requests needed
+• Fast problem navigation: Problem lists loaded from cache
+• Reduced scraping: Test cases cached after first download
+• Batch operations: Multiple problems can be set up quickly
+
+Cache size typically remains under 1MB even with extensive usage.
+
 ==============================================================================
 SNIPPETS                                                        *cp-snippets*