feat: add link metadata and safe local sync discovery

.changeset/clear-moves-report.md

@@ -0,0 +1,6 @@
+---
+"docz-cli": patch
+---
+
+Clarify that `mv` destinations are complete Space-root-relative paths and
+improve failed and unknown move outcomes with actionable destination context.

.changeset/fuzzy-links-report.md

@@ -0,0 +1,7 @@
+---
+"docz-cli": minor
+---
+
+Add separate `link info` and `share info` commands for ordinary and shared
+DocSync links, with human-readable and JSON output for link status, document
+status, folder type, permissions, ownership, and share access metadata.

.changeset/tidy-plants-search.md

@@ -0,0 +1,7 @@
+---
+"docz-cli": minor
+---
+
+Add `docz local root` to discover the configured DocSync synchronization
+directory without enumerating files, including existence and freshness
+metadata for consent-based, read-only local search with remote-only writes.

README.md

@@ -83,10 +83,12 @@ export DOCSYNC_API_TOKEN=<your-token>
 | `write <space>:<path> <content>` | Write content to file (`-` for stdin) |
 | `mkdir <space>:<path>` | Create folder |
 | `rm <space>:<path>` | Delete file/folder (30-day trash) |
-| `mv <space>:<from> <to>` | Rename or move |
+| `mv <source> <destination-path>` | Rename or move within a Space |
 | `log <space>[:<path>]` | Show change history |
 | `rollback <space>:<path> <commit>` | Rollback file to a specific commit |
 | `shortlink <space>:<path>` | Get short URL for file |
+| `link info <url> [--json]` | Inspect ordinary link, Space permission, path, and document status |
+| `local root [--json]` | Print the configured local synchronization root |
 | `trash <space>` | Show deleted files |
 | `restore <space>:<path> <commit>` | Restore file from trash |
 | `diff <space>[:<path>] <commit> [<from>]` | Show changes (file or space level) |
@@ -99,7 +101,7 @@ export DOCSYNC_API_TOKEN=<your-token>
 | `share list <space>` | List share links |
 | `share update <space> <link-id>` | Update share link |
 | `share cat <token-or-url>` | Read shared file |
-| `share info <token-or-url>` | Show share link info |
+| `share info <token-or-url> [--json]` | Inspect share lifecycle, access, and target status |
 | `share rm <space> <link-id>` | Delete share link |
 | `mcp` | Start MCP stdio server |
 
@@ -132,6 +134,47 @@ docz-cli ls https://docz.zhenguanyu.com/s/yanfa
 docz-cli log https://docz.zhenguanyu.com/s/yanhongkang/f/NNjrcj8c
 ```
 
+### Link Metadata
+
+Ordinary and share links use separate commands and output contracts. Link
+lifecycle and target document status are reported independently.
+
+```bash
+# Ordinary stable/path/root/legacy links (authentication required)
+docz-cli link info https://docz.zhenguanyu.com/s/yanfa/f/NNjrcj8c
+docz-cli link info https://docz.zhenguanyu.com/s/yanfa/docs/guide.md --json
+
+# Share token or URL (public shares can be inspected without a token)
+docz-cli share info https://docz.zhenguanyu.com/share/xYz123AbC
+docz-cli share info xYz123AbC --json
+```
+
+Ordinary JSON includes `link_status`, `space_permission`, `document_path`,
+`document_status`, `space_admin`, and `is_folder`. Share JSON additionally uses
+share-specific fields such as `access_status`, `visibility`, `role`,
+`shared_by`, and `expires_at`. Technical failures produce `unknown` values and
+exit code 2 instead of incorrectly reporting a missing link or document.
+
+### Local Sync Root
+
+```bash
+docz local root
+docz local root --json
+DOCSYNC_CLIENT_DATA_DIR=/custom/client-data docz local root --json
+```
+
+This command only reads `sync_dir` from the local DocSync client configuration.
+It does not connect to the daemon, enumerate or read synchronized files, or
+claim that the local copy is current. JSON therefore reports
+`"freshness":"unknown"`. If the configured root is missing, the command still
+prints the path and exits with code 2.
+
+AI agents must ask for task-scoped user confirmation before searching or
+reading files below this root. The synchronized directory is always read-only
+to agents: existing documents are edited through `collab cat/write`, new text
+documents through `write`, and other mutations through the corresponding Docz
+CLI commands.
+
 ### Write
 
 ```bash
@@ -155,7 +198,9 @@ docz-cli image upload ./screenshot.png
 ### Manage
 
 ```bash
-docz-cli mv G160-研发:old.md new.md              # Rename
+docz-cli mv G160-研发:old.md new.md                   # Rename in the Space root
+docz-cli mv G160-研发:docs/old.md archive/new.md      # Move and rename
+docz-cli mv https://docz.example.com/s/abc docs/new.md # URL source
 docz-cli rm G160-研发:deprecated.md               # Delete (recoverable for 30 days)
 docz-cli log G160-研发                             # Space history
 docz-cli log G160-研发:docs/guide.md              # File history
@@ -164,6 +209,9 @@ docz-cli trash G160-研发                           # View deleted files
 docz-cli restore G160-研发:deleted.md del1234      # Restore file from trash
 ```
 
+`mv` 的第二个参数是相对于 Space 根目录的完整目标路径（包含最终文件名），
+不是相对于源文件所在目录的路径。目标父目录必须已存在。
+
 ### Comments
 
 ```bash
@@ -189,8 +237,9 @@ docz-cli share cat xYz123AbC
 docz-cli share cat https://docz.zhenguanyu.com/share/xYz123AbC
 docz-cli share cat xYz123AbC --raw | grep "部署"  # Raw output for pipes
 
-# View share link info
+# View share link info (human or JSON)
 docz-cli share info xYz123AbC
+docz-cli share info xYz123AbC --json
 
 # Update and delete (requires space context)
 docz-cli share update G160-研发 <link-id> --expires 30d

openspec/changes/task-2363-add-docz-cli-link-metadata/.claroflow

@@ -0,0 +1,27 @@
+{
+  "taskId": "2363",
+  "title": "Docz CLI 支持普通链接和分享链接元信息查询",
+  "storyId": "1688",
+  "assignee": {
+    "ldapUid": "yanhongkang",
+    "name": "闫洪康"
+  },
+  "repositories": [
+    {
+      "repoName": "docz-cli",
+      "branch": "feature/task-2363-add-docz-cli-link-metadata"
+    },
+    {
+      "repoName": "conan-docz",
+      "branch": "feature/task-2363-add-docz-cli-link-metadata"
+    }
+  ],
+  "prd": {
+    "syncedAt": "2026-07-28T20:48:34+08:00",
+    "doczLinks": []
+  },
+  "lifecycle": {
+    "lastState": "coding",
+    "lastTransitionAt": "2026-07-28T20:53:12+08:00"
+  }
+}

openspec/changes/task-2363-add-docz-cli-link-metadata/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: conan
+created: 2026-07-28