From 7f3e51cf19e23292ab2087f521408c70c92f12fe Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Sat, 3 Jan 2026 15:17:56 +0800
Subject: Update track command help text to clarify its conceptual model

The help text for `jv track` has been rewritten to emphasize its role as
a declaration of fact rather than a simple upload/download operation.
The new text explains the three scenarios: creation (when a file is
untracked), update (when you hold the file), and synchronization (when
you don't hold the file). The Chinese locale has been updated
accordingly.
---
 locales/help_docs/en.yml    | 31 ++++++++++++++++++++-----------
 locales/help_docs/zh-CN.yml | 23 +++++++++++++++++------
 2 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/locales/help_docs/en.yml b/locales/help_docs/en.yml
index 02d371c..7b2d200 100644
--- a/locales/help_docs/en.yml
+++ b/locales/help_docs/en.yml
@@ -381,18 +381,27 @@ jv:
     - File's version in `ref`
 
   track: |
-    **Track or Pull Files**
+    **Track Files to Latest Fact**
     **Usage**: jv track <FILE_PATH>
 
-    **Example**: jv track src/main.rs
-    For new files:
-      Create and upload the "First Version", then automatically hold them
-    For *held* files:
-      Upload new versions to the upstream vault to update to the latest version
-    For *unheld* or *non-exist* files:
-      Download or update local file versions to the latest
+    It is not uploading, nor downloading,
+    but a declaration of the result regarding [[cyan]]"which version should be considered fact"[[/]].
 
-    Tracking files is the basic operation of version control, ensuring your upstream and local files are always up to date.
+    **Creation**
+    When there is an untracked file in the workspace, that file does not yet exist in the recognized fact.
+    Executing track will create the factual version of this file, write it to your sheet, and grant you editing rights.
+    At this point, you are **the author of this fact**.
+
+    **Update**
+    When you hold a file and edit based on the current latest fact,
+    the version in your workspace will be considered the new latest fact.
+    Executing track will **update this fact to the upstream**.
+
+    **Synchronization**
+    When you do not hold the file, edit based on outdated facts, or the file does not exist locally,
+    your modifications do not have factual validity; everything follows the upstream latest version.
+    Executing track will **synchronize the upstream fact to local**.
+    To overwrite local modifications, you must explicitly specify `--overwrite`.
 
   hold: |
     **Hold Files: Obtain File Edit Rights from Upstream Vault**
@@ -417,8 +426,8 @@ jv:
   move: |
     **Move Mapping**
     **Usage**:
-    jv move <mapping> <target_mapping> - Modify upstream mapping
-    jv move <mapping> --erase - Erase upstream mapping
+    jv move <MAPPING> <TARGET_MAPPING> - Modify upstream mapping
+    jv move <MAPPING> --erase - Erase upstream mapping
 
     **Examples**:
     jv move draft/character.png done/character.png - Move mapping
diff --git a/locales/help_docs/zh-CN.yml b/locales/help_docs/zh-CN.yml
index 665283b..7d93620 100644
--- a/locales/help_docs/zh-CN.yml
+++ b/locales/help_docs/zh-CN.yml
@@ -373,15 +373,26 @@ jv:
     - 文件在 `ref` 中的版本
 
   track: |
-    **追踪或拉取文件**
+    **追踪文件至最新事实**
     **用法**：jv track <文件路径>
 
-    **例如**：jv track src/main.rs
-    追踪新文件时，会创建并上传 “第一版本”，然后自动持有该文件的编辑权
-    追踪 *已持有* 文件时会上传新版本到上游库，以更新至最新版本。
-    追踪 *未持有* 或 *不存在* 的远程文件时，会下载或更新本地文件版本至最新
+    它不是上传，也不是下载，而是对 [[cyan]]“哪一个版本应被视为事实”[[/]] 的结果声明。
 
-    追踪文件是版本控制的基础操作，确保您的上游和本地文件时刻都是最新的
+    **创建**
+    当工作区存在未被追踪的文件时，该文件尚不存在于公认事实中
+    执行追踪将创建该文件的事实版本，写入您的表，并授予您编辑权
+    此时，您是 **该事实的撰写者**
+
+    **更新**
+    当您持有文件，且基于当前最新事实进行编辑时，
+    您工作区中的版本将被视为新的最新事实
+    执行追踪将 **更新该事实到上游**
+
+    **同步**
+    当您不持有文件、基于过期事实编辑，或本地不存在该文件时，
+    您的修改不具备事实效力，一切以上游最新版为准
+    执行追踪将 **同步上游事实到本地**
+    若需覆盖本地修改，必须显式指定 `--overwrite`
 
   hold: |
     **拿取文件：从上游库获得该文件的编辑权**
-- 
cgit