Update help documentation and move command functionality

- Redesign move command to modify upstream mappings with support for
  erase operations
- Add erased items support to align command and status display
- Update help text to reflect new move mapping semantics and add erased
  item instructions
- Add auto-update timeout configuration via JV_OUTDATED_MINUTES
  environment variable
- Improve status display with separate structural and content change
  modes
- Add force flag to hold/throw commands to skip pre-checks
- Update completion scripts to include erased items in align command

4 files changed, 28 insertions, 4 deletions

diff --git a/scripts/completions/bash/completion_jv.sh b/scripts/completions/bash/completion_jv.sh
index ff600ed..be5afc6 100644
--- a/scripts/completions/bash/completion_jv.sh
+++ b/scripts/completions/bash/completion_jv.sh
@@ -99,7 +99,7 @@ _jv_completion() {
                 ;;
             "align")
                 if [[ $cword -eq 3 ]]; then
-                    local align_items="lost moved"
+                    local align_items="lost moved erased"
                     local unsolved_items
                     unsolved_items=$($cmd sheet align --unsolved --raw 2>/dev/null)
                     COMPREPLY=($(compgen -W "$align_items $unsolved_items" -- "$cur"))
@@ -115,6 +115,8 @@ _jv_completion() {
                         align_operations="confirm $created_items"
                     elif [[ "$item" == "moved" || "$item" == moved:* ]]; then
                         align_operations="local remote"
+                    elif [[ "$item" == "erased" || "$item" == erased:* ]]; then
+                        align_operations="confirm"
                     else
                         align_operations="local remote confirm $created_items"
                     fi
@@ -129,7 +131,7 @@ _jv_completion() {
     # Completion align
     if [[ "$subcmd" == "align" ]]; then
         if [[ $cword -eq 2 ]]; then
-            local align_items="lost moved"
+            local align_items="lost moved erased"
             local unsolved_items
             unsolved_items=$($cmd sheet align --unsolved --raw 2>/dev/null)
             COMPREPLY=($(compgen -W "$align_items $unsolved_items" -- "$cur"))
@@ -145,6 +147,8 @@ _jv_completion() {
                 align_operations="confirm $created_items"
             elif [[ "$item" == "moved" || "$item" == moved:* ]]; then
                 align_operations="local remote"
+            elif [[ "$item" == "erased" || "$item" == erased:* ]]; then
+                align_operations="confirm"
             else
                 align_operations="local remote confirm $created_items"
             fi
diff --git a/scripts/completions/powershell/completion_jv.ps1 b/scripts/completions/powershell/completion_jv.ps1
index 48ab3ec..b756fbd 100644
--- a/scripts/completions/powershell/completion_jv.ps1
+++ b/scripts/completions/powershell/completion_jv.ps1
@@ -89,7 +89,7 @@ Register-ArgumentCompleter -Native -CommandName jv -ScriptBlock {
             }
             "align" {
                 if ($currentIndex -eq 3) {
-                    $alignItems = @("lost", "moved")
+                    $alignItems = @("lost", "moved", "erased")
                     $unsolvedItems = & $cmd sheet align --unsolved --raw 2>$null
                     $completions = $alignItems + $unsolvedItems
                     return $completions | Where-Object { $_ -like "$wordToComplete*" }
@@ -104,6 +104,8 @@ Register-ArgumentCompleter -Native -CommandName jv -ScriptBlock {
                         $alignOperations = @("confirm") + $createdItems
                     } elseif ($item -eq "moved" -or $item -like "moved:*") {
                         $alignOperations = @("local", "remote")
+                    } elseif ($item -eq "erased" -or $item -like "erased:*") {
+                        $alignOperations = @("confirm")
                     } else {
                         $alignOperations = @("local", "remote", "confirm") + $createdItems
                     }
@@ -118,7 +120,7 @@ Register-ArgumentCompleter -Native -CommandName jv -ScriptBlock {
     # Completion for align command
     if ($subcmd -eq "align") {
         if ($currentIndex -eq 2) {
-            $alignItems = @("lost", "moved")
+            $alignItems = @("lost", "moved", "erased")
             $unsolvedItems = & $cmd sheet align --unsolved --raw 2>$null
             $completions = $alignItems + $unsolvedItems
             return $completions | Where-Object { $_ -like "$wordToComplete*" }
@@ -133,6 +135,8 @@ Register-ArgumentCompleter -Native -CommandName jv -ScriptBlock {
                 $alignOperations = @("confirm") + $createdItems
             } elseif ($item -eq "moved" -or $item -like "moved:*") {
                 $alignOperations = @("local", "remote")
+            } elseif ($item -eq "erased" -or $item -like "erased:*") {
+                $alignOperations = @("confirm")
             } else {
                 $alignOperations = @("local", "remote", "confirm") + $createdItems
             }
diff --git a/scripts/jv_cli.ps1 b/scripts/jv_cli.ps1
index 8e16646..22836c7 100644
--- a/scripts/jv_cli.ps1
+++ b/scripts/jv_cli.ps1
@@ -13,6 +13,14 @@ $SCRIPT_DIR = Split-Path -Parent $MyInvocation.MyCommand.Definition
 # Next `jv` command will auto-run `jv update`
 $env:JV_AUTO_UPDATE = "yes"
 
+# Use JV_OUTDATED_MINUTES to set the expiration time (in minutes), requires JV_AUTO_UPDATE to be enabled
+# Next time the `jv` command is used, if the content is outdated, `jv update` will be automatically executed
+# When the set number is < 0, timeout-based update is disabled
+# When the set number = 0, update runs every time (not recommended)
+# When the set number > 0, update according to the specified time
+# If not set, the default is -1
+# $env:JV_OUTDATED_MINUTES = "5"
+
 # Use JV_TEXT_EDITOR to set text editor for `jv track --work` `jv align --work`
 # DEFAULT: $EDITOR environment variable, falling back to "jvii" if not set
 # $env:JV_TEXT_EDITOR = "nano"
diff --git a/scripts/jv_cli.sh b/scripts/jv_cli.sh
index e05df3d..d732d95 100644
--- a/scripts/jv_cli.sh
+++ b/scripts/jv_cli.sh
@@ -14,6 +14,14 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # Next `jv` command will auto-run `jv update`
 export JV_AUTO_UPDATE=yes
 
+# Use JV_OUTDATED_MINUTES to set the expiration time (in minutes), requires JV_AUTO_UPDATE to be enabled
+# Next time the `jv` command is used, if the content is outdated, `jv update` will be automatically executed
+# When the set number is < 0, timeout-based update is disabled
+# When the set number = 0, update runs every time (not recommended)
+# When the set number > 0, update according to the specified time
+# If not set, the default is -1
+# export JV_OUTDATED_MINUTES=5
+
 # Use JV_TEXT_EDITOR to set text editor for `jv track --work` `jv align --work`
 # DEFAULT: $EDITOR environment variable, falling back to "jvii" if not set
 # export JV_TEXT_EDITOR=nano