diff --git a/.agents/skills/logseq-cli-maintenance/SKILL.md b/.agents/skills/logseq-cli-maintenance/SKILL.md
new file mode 100644
index 0000000000..29e4a53556
--- /dev/null
+++ b/.agents/skills/logseq-cli-maintenance/SKILL.md
@@ -0,0 +1,139 @@
+---
+name: logseq-cli-maintenance
+description: Improve readability, consistency, and long-term maintainability of Logseq CLI-related code, command flows, and tests.
+---
+
+# logseq-cli-maintenance
+
+## Purpose
+
+Use this skill when working on Logseq CLI-related code and you want to improve:
+
+- Readability
+- Maintainability
+- Consistency across command modules
+- Long-term development ergonomics
+
+This skill focuses on practical refactoring and guardrails, without changing behavior unless explicitly requested.
+
+---
+
+## When to use
+
+Trigger this skill when tasks include any of the following:
+
+1. “Refactor Logseq CLI code”
+2. “Clean up command implementation”
+3. “Improve readability/structure of CLI logic”
+4. “Make CLI easier to extend and test”
+5. “Reduce duplication in argument parsing/output handling”
+
+Do **not** use this skill for pure feature delivery unless the request also asks for code quality improvements.
+
+---
+
+## Core maintenance principles
+
+### 1) Separate concerns clearly
+
+Keep these responsibilities isolated:
+
+- **Input parsing** (args/options/env)
+- **Validation** (schema/rules/errors)
+- **Execution** (domain logic)
+- **Presentation** (stdout/stderr formatting, exit codes)
+
+A command handler should orchestrate these steps, not mix all logic in one large function.
+
+### 2) Prefer small, composable functions
+
+- Keep functions single-purpose.
+- Use descriptive names that explain intent.
+- Extract repeated logic into shared helpers.
+- Avoid deep nesting; use early returns for invalid states.
+
+### 3) Keep command contracts explicit
+
+For each command/subcommand, make explicit:
+
+- Required and optional args
+- Defaults
+- Validation constraints
+- Output shape and error format
+- Exit code semantics
+
+### 4) Make errors actionable
+
+- Show concise error messages with next-step hints.
+- Keep error wording consistent across commands.
+- Distinguish user errors (invalid input) from internal errors.
+
+### 5) Standardize CLI output
+
+- Use one style for success, warning, and error output.
+- Ensure machine-readable mode (if supported) is stable and documented.
+- Avoid hidden format drift across subcommands.
+
+### 6) Preserve behavior while refactoring
+
+When request is maintenance-focused, avoid feature changes.
+If behavior must change, call it out explicitly and add tests.
+
+---
+
+## Suggested workflow
+
+1. **Map current command flow**
+   - Locate parse → validate → execute → print boundaries.
+2. **Identify maintenance hotspots**
+   - Long functions, duplicated parsing/output logic, hidden side effects.
+3. **Refactor in small, reviewable steps**
+   - One concern per change.
+4. **Add/update tests around behavior contracts**
+   - Especially for error cases and output format.
+5. **Run relevant CLI tests and linters**
+   - Confirm no regressions.
+6. **Run relevant cmds in logseq-cli**
+   - Use logseq-cli skill
+   - Confirm no regressions.
+7. **Document extension points**
+   - Show where future subcommands/options should be added.
+
+---
+
+## Refactoring checklist
+
+Use this checklist before finishing:
+
+- [ ] Command entrypoint is concise and easy to scan.
+- [ ] Parsing/validation/execution/output are separated.
+- [ ] Repeated logic is extracted to shared helpers.
+- [ ] Names are intention-revealing.
+- [ ] Error messages are consistent and actionable.
+- [ ] Output and exit code behavior are tested.
+- [ ] No behavior changes were introduced unintentionally.
+- [ ] `bb lint:large-vars` passes for touched vars.
+- [ ] Existing `^:large-vars/cleanup-todo` annotations were removed when possible.
+- [ ] New structure is easy for future contributors to extend.
+
+---
+
+## Common anti-patterns to remove
+
+- God-function command handlers
+- Implicit defaults scattered across files
+- Inconsistent option names/aliases
+- Silent failures or ambiguous exit codes
+- Copy-pasted output formatting logic
+- Mixing domain logic directly with terminal I/O
+
+---
+
+## Deliverable expectations
+
+When applying this skill, produce:
+
+1. Cleaner structure with equivalent behavior (unless requested otherwise)
+2. Focused tests for command contracts
+3. Brief rationale for key refactors
+4. Clear future extension path for new CLI commands/options
diff --git a/.agents/skills/logseq-cli/SKILL.md b/.agents/skills/logseq-cli/SKILL.md
new file mode 100644
index 0000000000..51536dcf31
--- /dev/null
+++ b/.agents/skills/logseq-cli/SKILL.md
@@ -0,0 +1,87 @@
+---
+name: logseq-cli
+description: Operate the current Logseq command-line interface to inspect or modify graphs, pages, blocks, tags, and properties; run Datascript queries; show page/block trees; manage graphs; and manage db-worker-node servers. Use when a request involves running `logseq` commands or interpreting CLI output.
+---
+
+# Logseq CLI
+
+## Overview
+
+Use `logseq` to inspect and edit graph entities, run Datascript queries, and control graph/server lifecycle.
+
+## Quick start
+
+- Run `logseq --help` to see top-level commands and global flags.
+- Run `logseq <command> --help` to see command-specific options.
+- Use `--graph` to target a specific graph.
+- Omit `--output` for human output. Set `--output json` or `--output edn` only when machine-readable output is required.
+
+## Command groups (from `logseq --help`)
+
+- Graph inspect/edit:
+- `list node`, `list page`, `list tag`, `list property`, `list task`, `list asset`
+- `upsert block`, `upsert page`, `upsert tag`, `upsert property`, `upsert task`, `upsert assert`
+- `remove block`, `remove page`, `remove tag`, `remove property`
+- `query`, `query list`, `show`, `search`
+- Graph management: `graph list|create|switch|remove|validate|info|export|import|backup`
+- Server management: `server list|cleanup|start|stop|restart`
+- Diagnostics: `doctor`, `debug`
+
+## Global options
+
+- `--config` Path to `cli.edn` (default `~/logseq/cli.edn`)
+- `--graph` Graph name
+- `--data-dir` Path to db-worker data dir (default `~/logseq/graphs`)
+- `--timeout-ms` Request timeout in ms (default `10000`)
+- `--output` Output format (`human`, `json`, `edn`)
+- `--verbose` Enable verbose debug logging to stderr
+
+## Command option policy
+
+- Do not memorize or hardcode command options in this skill.
+- Before running any command, always check live options with:
+- `logseq <command> --help`
+- `logseq <command> <subcommand> --help`
+
+## Examples policy
+
+- Do not maintain long static command examples in this skill.
+- Use `logseq example` as the source of truth for runnable examples.
+- Before proposing runnable commands, always inspect live examples with:
+  - `logseq example`
+  - `logseq example <command-or-prefix...>`
+  - `logseq example <command-or-prefix...> --help`
+- Prefer exact selectors when possible (for example, `logseq example upsert page`).
+- Use prefix selectors when grouped examples are needed (for example, `logseq example upsert`).
+- Replace placeholder ids/uuids in retrieved examples with real entities from the target graph.
+- Use `logseq list ...`, `logseq show ...`, or `logseq query ...` first to discover valid ids/uuids.
+- For graph transfer flows, keep `graph export --file` and `graph import --input` paths consistent.
+
+
+## Tag association semantics
+
+- For block or page tag association, prefer explicit CLI tag options such as `--update-tags` and `--remove-tags`.
+- Do not treat writing `#TagName` inside `--content` as equivalent guidance to explicit tag association.
+- `upsert block` supports `--update-tags` in both create mode and update mode.
+- `--update-tags` expects an EDN vector.
+- Tag values may be tag title/name strings, db/id, UUID, or `:db/ident` values.
+- String tag values may include a leading `#`, but they should still be passed inside `--update-tags` rather than embedded in content as a substitute for association.
+- If the user asks to tag a block or page, prefer explicit tag association over embedding hashtags in content.
+- Tags must already exist and be public. If needed, create the tag first with `upsert tag --name "<TagName>"`.
+
+## Pitfalls
+
+- `--content "Summary #AI-GENERATED"` is not the same guidance as `--update-tags '["AI-GENERATED"]'`.
+- Do not pass `--update-tags` as a comma-separated string. Use an EDN vector.
+- Do not assume a hashtag in block text will replace the need for explicit tag association when the user asks for a tagged block.
+- If tag association fails, verify the tag exists and is public before retrying.
+
+## Tips
+
+- `query list` returns both built-ins and `custom-queries` from `cli.edn`.
+- `show --id` accepts either one db/id or an EDN vector of ids.
+- `remove block --id` also accepts one db/id or an EDN vector.
+- `upsert block` enters update mode when `--id` or `--uuid` is provided.
+- Always verify command flags with `logseq --help` and `logseq <...> --help` before execution.
+- If `logseq` reports that it doesn’t have read/write permission for data-dir, then add read/write permission for data-dir in the agent’s config.
+- In sandboxed environments, `graph create` may print a process-scan warning to stderr; if command status is `ok`, the graph is still created.
\ No newline at end of file
diff --git a/.agents/skills/logseq-debug-workflow/SKILL.md b/.agents/skills/logseq-debug-workflow/SKILL.md
new file mode 100644
index 0000000000..ce581a5a9d
--- /dev/null
+++ b/.agents/skills/logseq-debug-workflow/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: logseq-debug-workflow
+description: Debug Logseq bugs with the right runtime, concrete before/after evidence, and end-to-end reproduction steps.
+---
+
+# Logseq Debug Workflow
+
+Use for any Logseq bug investigation.
+
+## Core rule
+
+Treat this as a debugging workflow, not a code-only change.
+
+Before claiming a fix, you must:
+
+1. Choose the correct *runtime repl* and say why:
+   - `:app` for renderer, DOM, UI, frontend state
+   - `:electron` for main-process, BrowserWindow, IPC, app config
+   - `:db-worker-node` for worker DB behavior, worker IPC, queries, transactions
+   - CLI for `logseq` command behavior
+2. Reproduce the bug in *runtime REPL* before editing code.
+3. Capture concrete evidence from that runtime: REPL output, CLI output, logs, or a failing test that matches the real runtime path.
+4. Check relevant logs early.
+5. Apply the smallest justified fix.
+6. Re-run the same reproduction flow after the fix and capture evidence again.
+7. Include restart/reload/reopen verification when the bug involves settings, startup, persistence, window creation, or cross-process behavior.
+
+## Do not conclude early
+
+Do **not** say the bug is fixed if any of these is missing:
+
+- pre-fix reproduction evidence
+- relevant log evidence, or an explicit statement that checked logs had nothing useful
+- post-fix evidence from the same runtime/path
+- required end-to-end lifecycle verification
+
+Unit tests alone are **not** enough when this skill applies, unless the bug is truly unit-level and you explicitly justify that.
+
+If the environment blocks full verification, report:
+
+- the blocker
+- what you tried
+- which evidence is still missing
+- the strongest partial evidence you have
+
+## Debugging tools
+
+### General
+
+- Add labeled `prn` checkpoints when helpful.
+- Use small REPL/eval checks.
+- Use targeted tests to confirm behavior.
+- Inspect only relevant inputs, branches, transformed values, outputs, and errors.
+- For async flows, inspect both sides of the async boundary.
+
+### Logseq REPL
+
+check `logseq-repl` skill.
+
+### Logs
+
+Logs are evidence. Check them early for Electron, CLI, worker, IPC, async, or persistence issues.
+
+Common locations:
+- `tmp/desktop-app-repl/desktop-electron.log` (logseq-repl skill)
+- `tmp/logseq-repl/shared-shadow-watch.log` (logseq-repl skill)
+- `~/Library/Logs/Logseq/main.log`
+- `~/Library/Logs/Logseq/main.old.log`
+- `~/Library/Application Support/Logseq/configs.edn`
+- graph-local `db-worker-node-<timestamp>.log`
+
+### Logseq CLI
+
+Before using `logseq`, load `logseq-cli` skill.
+
+## Required final output
+
+The final response must include these sections or an equivalent structure:
+
+1. **Runtime chosen** — which *runtime REPL* you used and why
+2. **Pre-fix reproduction** — reproduce bug in *runtime REPL*, exact steps and evidence
+3. **Root cause** — concrete cause and relevant files/flow
+4. **Fix applied** — short description of the change
+5. **Post-fix verification** — same steps again with new evidence
+6. **Additional verification** — tests/checks run, and what was not verified
+7. **Gaps or blockers** — any missing evidence and why
+
+## Quick checklist
+
+Before ending, make sure the answer is yes to all:
+
+- Did I reproduce the bug before fixing it?
+- Did I show evidence, not just claim reproduction?
+- Did I inspect relevant logs?
+- Did I verify in the correct runtime?
+- Did I rerun the same scenario after the fix?
+- Did I include both before and after evidence in the final output?
+- Did I avoid claiming completion if required evidence is missing?
+
+## Verification reminders
+
+- Never run tests, lint, build, or E2E verification in the background.
+- Check logs before trusting REPL/CLI output alone.
+- For performance bugs, compare `--profile` before/after on the same graph and command.
+- For CLI bugs, reuse the same `--graph`, `--data-dir`, and output mode.
+- For REPL debugging, verify against the intended runtime, not a stale one.
+
+Common checks: `bb dev:test -v <namespace/testcase-name>`, `bb dev:lint-and-test`, `bb dev:cli-e2e`.
diff --git a/.agents/skills/logseq-i18n/SKILL.md b/.agents/skills/logseq-i18n/SKILL.md
index a0c3fff2b8..fdffe6e494 100644
--- a/.agents/skills/logseq-i18n/SKILL.md
+++ b/.agents/skills/logseq-i18n/SKILL.md
@@ -74,7 +74,10 @@ If the English text matches but the meaning differs, create a new key and follow
 ### Rule 3: English source lives in `en.edn`
 
 - Add new English source text to `src/resources/dicts/en.edn`.
-- Add non-English entries only when you are also providing actual translations.
+- **When introducing a new key for the first time, you must also add the
+  Simplified Chinese (`zh-CN`) translation in the same change.** English and
+  `zh-CN` are the two required locales for any new key.
+- Add other non-English entries only when you are also providing actual translations.
 - When renaming or removing keys, update affected locale files so stale keys do
   not remain behind.
 - Do not copy English into non-English locale files just to fill gaps. Tongue
diff --git a/.agents/skills/logseq-repl/SKILL.md b/.agents/skills/logseq-repl/SKILL.md
new file mode 100644
index 0000000000..1b0a587898
--- /dev/null
+++ b/.agents/skills/logseq-repl/SKILL.md
@@ -0,0 +1,205 @@
+---
+name: logseq-repl
+description: Start and coordinate Logseq development REPL workflows for the Desktop renderer `:app`, Electron main-process `:electron`, and `:db-worker-node` runtimes through one unified workflow.
+---
+
+# Logseq REPL Workflow
+
+Use this skill when the user needs a Logseq development REPL for:
+
+- Desktop renderer `:app`
+- Electron main process `:electron`
+- `:db-worker-node`
+- any combination of those runtimes
+
+The workflow uses one shared state directory: `<repo>/tmp/logseq-repl/`.
+
+## Scripts
+
+Start everything with the default Logseq data root (`$LOGSEQ_CLI_ROOT_DIR` or `~/logseq`):
+
+```bash
+./scripts/start-repl.sh --repo demo
+```
+
+Start everything with an explicit Logseq data root:
+
+```bash
+./scripts/start-repl.sh --repo demo --root-dir ~/logseq
+```
+
+Clean up everything:
+
+```bash
+./scripts/cleanup-repl.sh
+```
+
+Verify all REPL targets after startup:
+
+```bash
+./scripts/verify-repls.sh
+```
+
+`start-repl.sh` starts:
+
+1. shared `pnpm watch`
+2. Desktop dev app via `pnpm dev-electron-app`
+3. `db-worker-node` via `node ./static/db-worker-node.js --repo <name> --root-dir <path> --owner-source cli`
+
+`start-repl.sh` is a small shell wrapper around `start-repl.py`. The Python script verifies that `:app`, `:electron`, and `:db-worker-node` runtimes are live, runs `verify-repls.sh` to connect to each target REPL and print a small result, then prints attach commands. It does not attach an interactive REPL by itself and exits after verification.
+
+`cleanup-repl.sh` stops all workflow-managed processes without requiring a target selection. It also removes legacy state files from older split workflows and attempts to stop repo-owned listeners on the standard REPL ports.
+
+`verify-repls.sh` connects to `app`, `electron`, and `db-worker-node` with `pnpm exec shadow-cljs cljs-repl`, evaluates one target-specific expression in each REPL, and prints the output.
+
+## Standard Flow
+
+Before starting or attaching:
+
+```bash
+./scripts/cleanup-repl.sh
+```
+
+Then start all runtimes:
+
+```bash
+./scripts/start-repl.sh --repo demo
+```
+
+Use `--root-dir <path>` if the target graph lives outside `$LOGSEQ_CLI_ROOT_DIR` or `~/logseq`.
+
+Attach only to the target you need:
+
+```bash
+pnpm exec shadow-cljs cljs-repl app
+pnpm exec shadow-cljs cljs-repl electron
+pnpm exec shadow-cljs cljs-repl db-worker-node
+```
+
+## Runtime Selection
+
+- Need DOM, UI, renderer state, or page rendering? Use `:app`.
+- Need Electron main process APIs, menus, window lifecycle, or main-process filesystem behavior? Use `:electron`.
+- Need Node worker behavior or db-worker-node code paths? Use `:db-worker-node`.
+
+Runtime reminders:
+
+- `:app` = Electron renderer
+- `:electron` = Electron main process
+- `:db-worker` = browser worker
+- `:db-worker-node` = Node worker
+
+## Readiness Model
+
+Keep these separate:
+
+1. watch alive: a `shadow-cljs` server or `pnpm watch` process exists
+2. build ready: the target build completed successfully
+3. runtime attached: a live JS runtime is connected for `:app`, `:electron`, or `:db-worker-node`
+
+If runtime count is `0`, do not attach yet. Fix runtime startup first.
+
+Check runtime counts:
+
+```bash
+pnpm exec shadow-cljs clj-eval "(do (require '[shadow.cljs.devtools.api :as api]) (println {:app (count (api/repl-runtimes :app)) :electron (count (api/repl-runtimes :electron)) :db-worker-node (count (api/repl-runtimes :db-worker-node))}))"
+```
+
+Interpretation:
+
+- `:app > 0` means a Desktop renderer runtime is attached
+- `:electron > 0` means an Electron main-process runtime is attached
+- `:db-worker-node > 0` means a worker-node runtime is attached
+- `0` means not ready, even if watch/build logs look healthy
+
+## Logs
+
+Look here first:
+
+- `<repo>/tmp/logseq-repl/shared-shadow-watch.log`
+- `<repo>/tmp/logseq-repl/desktop-electron.log`
+- `<repo>/tmp/logseq-repl/db-worker-node.log`
+
+## Port Audit
+
+After cleanup, verify standard ports if startup still reports conflicts:
+
+```bash
+lsof -nP -iTCP:8701 -sTCP:LISTEN
+lsof -nP -iTCP:3001 -sTCP:LISTEN
+lsof -nP -iTCP:3002 -sTCP:LISTEN
+lsof -nP -iTCP:9630 -sTCP:LISTEN
+lsof -nP -iTCP:9631 -sTCP:LISTEN
+```
+
+Interpretation:
+
+- no listeners: clean enough to continue
+- listeners after cleanup: resolve the external conflict first
+- listeners only after startup: expected if owned by the workflow
+
+## Non-Interactive Verification Examples
+
+Desktop `:app`:
+
+```bash
+cat <<'EOF' | pnpm exec shadow-cljs cljs-repl app
+(prn {:runtime :app :document? (some? js/document) :title (.-title js/document)})
+:cljs/quit
+EOF
+```
+
+Electron `:electron`:
+
+```bash
+cat <<'EOF' | pnpm exec shadow-cljs cljs-repl electron
+(prn {:runtime :electron :process? (some? js/process) :type (.-type js/process)})
+:cljs/quit
+EOF
+```
+
+`db-worker-node`:
+
+```bash
+cat <<'EOF' | pnpm exec shadow-cljs cljs-repl db-worker-node
+(prn {:runtime :db-worker-node :process? (some? js/process) :platform (.-platform js/process)})
+:cljs/quit
+EOF
+```
+
+## Editor Attach Helpers
+
+```clojure
+(shadow.user/cljs-repl)
+(shadow.user/electron-repl)
+(shadow.user/worker-node-repl)
+```
+
+## Troubleshooting
+
+Failure triage order:
+
+1. inspect `tmp/logseq-repl/shared-shadow-watch.log`
+2. inspect `tmp/logseq-repl/desktop-electron.log`
+3. inspect `tmp/logseq-repl/db-worker-node.log`
+4. inspect standard port listeners with `lsof`
+5. inspect runtime counts with `shadow.cljs.devtools.api/repl-runtimes`
+
+Common cases:
+
+- `No available JS runtime`: the build may be ready, but the runtime has not connected. Check runtime counts before retrying attach.
+- multiple `:app` runtimes: close browser dev app instances so only the Desktop renderer remains.
+- ports already in use after cleanup: another Logseq/shadow-cljs dev session is still running.
+- `db-worker-node` repo mismatch: rerun `start-repl.sh --repo <name>`; it restarts the worker runtime for the requested repo.
+
+## Recommended Response Pattern
+
+When helping a user connect to a REPL:
+
+1. identify whether they need `:app`, `:electron`, `:db-worker-node`, or a combination
+2. run `cleanup-repl.sh`
+3. if standard ports remain occupied, resolve that conflict first
+4. run `start-repl.sh --repo <name>`
+5. verify runtime counts if attach fails
+6. attach to the matching build or helper
+7. run `cleanup-repl.sh` when finished
diff --git a/.agents/skills/logseq-repl/scripts/cleanup-repl.sh b/.agents/skills/logseq-repl/scripts/cleanup-repl.sh
new file mode 100755
index 0000000000..b627603bcc
--- /dev/null
+++ b/.agents/skills/logseq-repl/scripts/cleanup-repl.sh
@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_REPO_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+REPO_ROOT="${REPO_ROOT:-$DEFAULT_REPO_ROOT}"
+FORCE_KILL=0
+
+usage() {
+  cat <<'EOF'
+Stop all processes started by start-repl.sh.
+
+Usage:
+  cleanup-repl.sh [options]
+
+Options:
+  --repo-root <path>    Logseq repository root (default: auto-detect from script location)
+  --force               Use SIGKILL if a process does not stop gracefully
+  -h, --help            Show this help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root)
+      shift
+      REPO_ROOT="${1:?missing value for --repo-root}"
+      ;;
+    --force)
+      FORCE_KILL=1
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+LOG_DIR="$REPO_ROOT/tmp/logseq-repl"
+LEGACY_DESKTOP_LOG_DIR="$REPO_ROOT/tmp/desktop-app-repl"
+LEGACY_DB_LOG_DIR="$REPO_ROOT/tmp/db-worker-node-repl"
+
+is_running_pid() {
+  local pid="$1"
+  [[ "$pid" =~ ^[0-9]+$ ]] && kill -0 "$pid" 2>/dev/null
+}
+
+read_pid() {
+  local file="$1"
+  if [[ -f "$file" ]]; then
+    tr -d '[:space:]' < "$file"
+  fi
+}
+
+process_group_id() {
+  local pid="$1"
+  ps -o pgid= -p "$pid" 2>/dev/null | tr -d '[:space:]'
+}
+
+current_process_group_id() {
+  process_group_id "$$"
+}
+
+signal_process_group() {
+  local signal="$1"
+  local pid="$2"
+
+  local current_pgid pgid
+  pgid="$(process_group_id "$pid" || true)"
+  current_pgid="$(current_process_group_id || true)"
+
+  if [[ -n "${pgid:-}" && "$pgid" =~ ^[0-9]+$ && "$pgid" != "${current_pgid:-}" ]]; then
+    kill "-$signal" "-$pgid" 2>/dev/null || true
+  fi
+
+  kill "-$signal" "$pid" 2>/dev/null || true
+}
+
+stop_by_pid_file() {
+  local pid_file="$1"
+  local label="$2"
+
+  local pid
+  pid="$(read_pid "$pid_file" || true)"
+
+  if [[ -z "${pid:-}" ]]; then
+    rm -f "$pid_file"
+    return 0
+  fi
+
+  if ! is_running_pid "$pid"; then
+    echo "$label: process already stopped (pid=$pid)"
+    rm -f "$pid_file"
+    return 0
+  fi
+
+  echo "$label: stopping pid=$pid"
+  signal_process_group TERM "$pid"
+
+  local i
+  for ((i=0; i<10; i++)); do
+    if ! is_running_pid "$pid"; then
+      echo "$label: stopped"
+      rm -f "$pid_file"
+      return 0
+    fi
+    sleep 1
+  done
+
+  if [[ "$FORCE_KILL" -eq 1 ]]; then
+    echo "$label: force killing pid=$pid"
+    signal_process_group KILL "$pid"
+    sleep 1
+  fi
+
+  if is_running_pid "$pid"; then
+    echo "$label: failed to stop pid=$pid" >&2
+    return 1
+  fi
+
+  echo "$label: stopped"
+  rm -f "$pid_file"
+}
+
+repo_owns_pid() {
+  local pid="$1"
+  local cwd
+  cwd="$(lsof -nP -a -p "$pid" -d cwd 2>/dev/null | awk 'NR > 1 {print $NF; exit}' || true)"
+  [[ "$cwd" == "$REPO_ROOT" ]]
+}
+
+stop_repo_port_listener() {
+  local port="$1"
+  local pid
+
+  while read -r pid; do
+    [[ -n "${pid:-}" ]] || continue
+    if is_running_pid "$pid" && repo_owns_pid "$pid"; then
+      echo "port $port listener: stopping pid=$pid"
+      signal_process_group TERM "$pid"
+    fi
+  done < <(lsof -nP -tiTCP:"$port" -sTCP:LISTEN 2>/dev/null || true)
+}
+
+if [[ ! -d "$LOG_DIR" && ! -d "$LEGACY_DESKTOP_LOG_DIR" && ! -d "$LEGACY_DB_LOG_DIR" ]]; then
+  echo "State directory not found: $LOG_DIR"
+  echo "Nothing to clean up."
+  exit 0
+fi
+
+stop_by_pid_file "$LOG_DIR/db-worker-node.pid" "db-worker-node"
+stop_by_pid_file "$LOG_DIR/desktop-electron.pid" "desktop-electron"
+stop_by_pid_file "$LOG_DIR/shared-shadow-watch.pid" "shadow-cljs watch"
+
+stop_by_pid_file "$LEGACY_DB_LOG_DIR/db-worker-node.pid" "legacy db-worker-node"
+stop_by_pid_file "$LEGACY_DB_LOG_DIR/shadow-db-worker-node.pid" "legacy shadow-cljs watch"
+stop_by_pid_file "$LEGACY_DESKTOP_LOG_DIR/desktop-electron.pid" "legacy desktop-electron"
+stop_by_pid_file "$LEGACY_DESKTOP_LOG_DIR/shadow-watch.pid" "legacy shadow-cljs watch"
+
+rm -f "$LOG_DIR/db-worker-node.repo" \
+      "$LOG_DIR/db-worker-node.options.json" \
+      "$LEGACY_DB_LOG_DIR/db-worker-node.repo"
+
+for port in 8701 3001 3002 9630 9631; do
+  stop_repo_port_listener "$port"
+done
+
+rm -f "$LOG_DIR"/*.pid "$LEGACY_DB_LOG_DIR"/*.pid "$LEGACY_DESKTOP_LOG_DIR"/*.pid 2>/dev/null || true
+
+echo "Cleanup done."
diff --git a/.agents/skills/logseq-repl/scripts/common.sh b/.agents/skills/logseq-repl/scripts/common.sh
new file mode 100644
index 0000000000..c8598c57b3
--- /dev/null
+++ b/.agents/skills/logseq-repl/scripts/common.sh
@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+
+logseq_repl_is_running_pid() {
+  local pid="$1"
+  [[ "$pid" =~ ^[0-9]+$ ]] && kill -0 "$pid" 2>/dev/null
+}
+
+logseq_repl_read_pid() {
+  local file="$1"
+  if [[ -f "$file" ]]; then
+    tr -d '[:space:]' < "$file"
+  fi
+}
+
+logseq_repl_port_check_line() {
+  local port="$1"
+  lsof -nP -iTCP:"$port" -sTCP:LISTEN 2>/dev/null || true
+}
+
+logseq_repl_audit_standard_ports() {
+  local had_conflict=0
+  local ports=(8701 3001 3002 9630 9631)
+  local port output
+
+  for port in "${ports[@]}"; do
+    output="$(logseq_repl_port_check_line "$port")"
+    if [[ -n "$output" ]]; then
+      had_conflict=1
+      echo "Port $port is already listening:" >&2
+      echo "$output" >&2
+      echo >&2
+    fi
+  done
+
+  return "$had_conflict"
+}
+
+logseq_repl_require_clean_standard_ports() {
+  if logseq_repl_audit_standard_ports; then
+    return 0
+  fi
+
+  echo "Error: standard Logseq REPL ports are still occupied after cleanup." >&2
+  echo "Resolve the external conflict first, then retry." >&2
+  return 1
+}
+
+logseq_repl_runtime_count() {
+  local repo_root="$1"
+  local build_name="$2"
+  local output
+
+  pushd "$repo_root" >/dev/null
+  if ! output="$(pnpm exec shadow-cljs clj-eval "(do (require '[shadow.cljs.devtools.api :as api]) (println (count (api/repl-runtimes :$build_name))))" 2>&1)"; then
+    popd >/dev/null
+    echo "Error: failed to inspect :$build_name runtimes." >&2
+    echo "--- clj-eval output ---" >&2
+    echo "$output" >&2
+    echo "-----------------------" >&2
+    return 1
+  fi
+  popd >/dev/null
+
+  local runtime_count
+  runtime_count="$(printf '%s\n' "$output" | awk '/^[0-9]+$/{n=$0} END{if (n != "") print n; else exit 1}')" || {
+    echo "Error: could not parse :$build_name runtime count." >&2
+    echo "--- clj-eval output ---" >&2
+    echo "$output" >&2
+    echo "-----------------------" >&2
+    return 1
+  }
+
+  printf '%s\n' "$runtime_count"
+}
diff --git a/.agents/skills/logseq-repl/scripts/start-repl.py b/.agents/skills/logseq-repl/scripts/start-repl.py
new file mode 100755
index 0000000000..5df4b522b1
--- /dev/null
+++ b/.agents/skills/logseq-repl/scripts/start-repl.py
@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+DEFAULT_REPO_ROOT = SCRIPT_DIR.parents[3]
+STANDARD_PORTS = (8701, 3001, 3002, 9630, 9631)
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(line_buffering=True)
+    sys.stderr.reconfigure(line_buffering=True)
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        prog="start-repl.sh",
+        description="Start the unified Logseq REPL workflow.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "This starts shared pnpm watch, the Desktop dev app, and the\n"
+            "db-worker-node runtime, verifies the REPL targets, and exits."
+        ),
+    )
+    parser.add_argument("--repo", default=os.environ.get("DB_REPO", "demo"),
+                        help="Graph repo name passed to db-worker-node (default: demo)")
+    parser.add_argument("--root-dir", default=os.environ.get("LOGSEQ_CLI_ROOT_DIR", str(Path.home() / "logseq")),
+                        help="Logseq data root passed to db-worker-node (default: $LOGSEQ_CLI_ROOT_DIR or ~/logseq)")
+    parser.add_argument("--repo-root", default=os.environ.get("REPO_ROOT", str(DEFAULT_REPO_ROOT)),
+                        help="Logseq repository root (default: auto-detect from script location)")
+    parser.add_argument("extra_node_args", nargs=argparse.REMAINDER,
+                        help="Arguments after -- are passed to db-worker-node")
+    args = parser.parse_args()
+    if args.extra_node_args and args.extra_node_args[0] == "--":
+        args.extra_node_args = args.extra_node_args[1:]
+    return args
+
+
+def require_command(name):
+    if subprocess.run(["/usr/bin/env", "sh", "-c", f"command -v {name} >/dev/null 2>&1"]).returncode != 0:
+        raise SystemExit(f"Error: {name} not found in PATH")
+
+
+def read_pid(path):
+    try:
+        text = path.read_text().strip()
+    except FileNotFoundError:
+        return None
+    return int(text) if re.fullmatch(r"\d+", text) else None
+
+
+def is_running(pid):
+    if not pid:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
+def write_pid(path, pid):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"{pid}\n")
+
+
+def wait_for_patterns(path, timeout, patterns, all_required=True):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if path.exists():
+            text = path.read_text(errors="replace")
+            if all_required and all(pattern in text for pattern in patterns):
+                return True
+            if not all_required and any(pattern in text for pattern in patterns):
+                return True
+        time.sleep(1)
+    return False
+
+
+def process_group_kwargs():
+    if os.name == "nt":
+        return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP}
+    return {"start_new_session": True}
+
+
+def start_process(repo_root, log_path, command):
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    log_file = log_path.open("wb")
+    return subprocess.Popen(
+        command,
+        cwd=repo_root,
+        stdin=subprocess.DEVNULL,
+        stdout=log_file,
+        stderr=subprocess.STDOUT,
+        **process_group_kwargs(),
+    )
+
+
+def port_listener_pid(port):
+    try:
+        output = subprocess.check_output(
+            ["lsof", "-nP", f"-iTCP:{port}", "-sTCP:LISTEN", "-t"],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return None
+    for line in output.splitlines():
+        if line.strip().isdigit():
+            return int(line.strip())
+    return None
+
+
+def has_managed_processes(paths):
+    return any(is_running(read_pid(path)) for path in paths)
+
+
+def read_json(path):
+    try:
+        return json.loads(path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def write_json(path, payload):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, sort_keys=True) + "\n")
+
+
+def require_clean_ports():
+    had_conflict = False
+    for port in STANDARD_PORTS:
+        pid = port_listener_pid(port)
+        if pid:
+            had_conflict = True
+            print(f"Port {port} is already listening (pid={pid})", file=sys.stderr)
+    if had_conflict:
+        print("Error: standard Logseq REPL ports are still occupied after cleanup.", file=sys.stderr)
+        print("Resolve the external conflict first, then retry.", file=sys.stderr)
+        return False
+    return True
+
+
+def ensure_shadow_watch(repo_root, shadow_pid_file, shadow_log):
+    pid = read_pid(shadow_pid_file)
+    if is_running(pid):
+        print(f"Reusing shared shadow-cljs watch (pid={pid})")
+        return pid
+
+    print("Starting shared shadow-cljs watch via pnpm watch ...")
+    process = start_process(repo_root, shadow_log, ["pnpm", "watch"])
+    write_pid(shadow_pid_file, process.pid)
+    time.sleep(1)
+
+    if process.poll() is not None:
+        raise SystemExit(f"Error: pnpm watch exited early. Check {shadow_log}")
+
+    if not wait_for_patterns(shadow_log, 180, [
+        "[:electron] Build completed.",
+        "[:app] Build completed.",
+        "[:db-worker-node] Build completed.",
+    ]):
+        raise SystemExit(f"Error: pnpm watch did not finish the expected builds in time. Check {shadow_log}")
+
+    listener_pid = port_listener_pid(8701)
+    if listener_pid and is_running(listener_pid):
+        write_pid(shadow_pid_file, listener_pid)
+        pid = listener_pid
+    else:
+        pid = process.pid
+
+    print("shadow-cljs watch builds are ready")
+    return pid
+
+
+def ensure_desktop_app(repo_root, desktop_pid_file, desktop_log):
+    pid = read_pid(desktop_pid_file)
+    if is_running(pid):
+        print(f"Reusing Desktop dev app (pid={pid})")
+        return pid
+
+    print("Starting Desktop dev app via pnpm dev-electron-app ...")
+    process = start_process(repo_root, desktop_log, ["pnpm", "dev-electron-app"])
+    write_pid(desktop_pid_file, process.pid)
+    time.sleep(1)
+
+    if process.poll() is not None:
+        raise SystemExit(f"Error: pnpm dev-electron-app exited early. Check {desktop_log}")
+
+    if not wait_for_patterns(desktop_log, 120, ["shadow-cljs - #", "Logseq App("], all_required=False):
+        raise SystemExit(f"Error: Desktop dev app did not report startup in time. Check {desktop_log}")
+
+    print(f"Desktop dev app is running (pid={process.pid})")
+    return process.pid
+
+
+def ensure_db_worker_node(repo_root, db_pid_file, db_options_file, db_log, repo, root_dir, extra_args):
+    pid = read_pid(db_pid_file)
+    startup_options = {
+        "repo": repo,
+        "root_dir": str(root_dir),
+        "owner_source": "cli",
+        "extra_args": list(extra_args),
+    }
+    existing_options = read_json(db_options_file)
+
+    if is_running(pid):
+        if existing_options == startup_options:
+            print(f"Reusing db-worker-node runtime (pid={pid}, repo={repo}, root-dir={root_dir})")
+            return pid
+        print(f"Stopping existing db-worker-node (pid={pid}) due to startup option mismatch")
+        terminate_pid(pid)
+        time.sleep(1)
+
+    print(f"Starting db-worker-node (repo={repo}, root-dir={root_dir}) ...")
+    process = start_process(
+        repo_root,
+        db_log,
+        [
+            "node",
+            "./static/db-worker-node.js",
+            "--repo",
+            repo,
+            "--root-dir",
+            str(root_dir),
+            "--owner-source",
+            "cli",
+            *extra_args,
+        ],
+    )
+    write_pid(db_pid_file, process.pid)
+    write_json(db_options_file, startup_options)
+    time.sleep(1)
+
+    if process.poll() is not None:
+        raise SystemExit(f"Error: db-worker-node exited early. Check {db_log}")
+
+    print(f"db-worker-node is running (pid={process.pid}, repo={repo}, root-dir={root_dir})")
+    return process.pid
+
+
+def runtime_count(repo_root, build_name):
+    form = f"(do (require '[shadow.cljs.devtools.api :as api]) (println (count (api/repl-runtimes :{build_name}))))"
+    proc = subprocess.run(
+        ["pnpm", "exec", "shadow-cljs", "clj-eval", form],
+        cwd=repo_root,
+        text=True,
+        capture_output=True,
+    )
+    if proc.returncode != 0:
+        raise SystemExit(
+            f"Error: failed to inspect :{build_name} runtimes.\n"
+            f"--- clj-eval output ---\n{proc.stdout}{proc.stderr}\n-----------------------"
+        )
+    matches = re.findall(r"^(\d+)$", proc.stdout + proc.stderr, flags=re.MULTILINE)
+    if not matches:
+        raise SystemExit(
+            f"Error: could not parse :{build_name} runtime count.\n"
+            f"--- clj-eval output ---\n{proc.stdout}{proc.stderr}\n-----------------------"
+        )
+    return int(matches[-1])
+
+
+def wait_for_runtime_count(repo_root, build_name, expected, timeout):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        count = runtime_count(repo_root, build_name)
+        if expected == "exactly-one":
+            if count == 1:
+                print(f"Detected exactly one live :{build_name} runtime")
+                return
+            if count != 0:
+                raise SystemExit(f"Error: Expected exactly one live :{build_name} runtime, found {count}.")
+        elif expected == "nonzero" and count != 0:
+            print(f"Detected live :{build_name} runtime count: {count}")
+            return
+        time.sleep(1)
+
+    if expected == "exactly-one":
+        raise SystemExit(f"Error: Expected exactly one live :{build_name} runtime, found 0 after waiting.")
+    raise SystemExit(f"Error: expected a live :{build_name} runtime, but runtime count stayed 0.")
+
+
+def verify_repls(repo_root):
+    subprocess.run([str(SCRIPT_DIR / "verify-repls.sh"), "--repo-root", str(repo_root)], check=True)
+
+
+def print_summary(shadow_log, desktop_log, db_log, shadow_pid_file, desktop_pid_file, db_pid_file):
+    print()
+    print("Logs:")
+    print(f"  shared shadow-cljs: {shadow_log}")
+    print(f"  desktop-app:        {desktop_log}")
+    print(f"  db-worker-node:     {db_log}")
+    print("PID files:")
+    print(f"  {shadow_pid_file}")
+    print(f"  {desktop_pid_file}")
+    print(f"  {db_pid_file}")
+    print()
+    print("Attach commands:")
+    print("  pnpm exec shadow-cljs cljs-repl app")
+    print("  pnpm exec shadow-cljs cljs-repl electron")
+    print("  pnpm exec shadow-cljs cljs-repl db-worker-node")
+    print()
+    print("Startup complete. Attach to the needed REPL manually.")
+
+
+def terminate_pid(pid):
+    if not pid:
+        return
+    try:
+        if os.name == "nt":
+            os.kill(pid, signal.CTRL_BREAK_EVENT)
+        else:
+            os.kill(pid, signal.SIGTERM)
+    except OSError:
+        pass
+
+
+def main():
+    args = parse_args()
+    repo_root = Path(args.repo_root).resolve()
+    db_root_dir = Path(args.root_dir).expanduser().resolve()
+    if not repo_root.is_dir():
+        raise SystemExit(f"Error: repo root not found: {repo_root}")
+
+    require_command("pnpm")
+    require_command("node")
+
+    log_dir = repo_root / "tmp" / "logseq-repl"
+    legacy_desktop_dir = repo_root / "tmp" / "desktop-app-repl"
+    legacy_db_dir = repo_root / "tmp" / "db-worker-node-repl"
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    shadow_pid_file = log_dir / "shared-shadow-watch.pid"
+    desktop_pid_file = log_dir / "desktop-electron.pid"
+    db_pid_file = log_dir / "db-worker-node.pid"
+    db_options_file = log_dir / "db-worker-node.options.json"
+    shadow_log = log_dir / "shared-shadow-watch.log"
+    desktop_log = log_dir / "desktop-electron.log"
+    db_log = log_dir / "db-worker-node.log"
+
+    managed_pid_files = [
+        shadow_pid_file,
+        desktop_pid_file,
+        db_pid_file,
+        legacy_desktop_dir / "shadow-watch.pid",
+        legacy_desktop_dir / "desktop-electron.pid",
+        legacy_db_dir / "shadow-db-worker-node.pid",
+        legacy_db_dir / "db-worker-node.pid",
+    ]
+
+    if not has_managed_processes(managed_pid_files) and not require_clean_ports():
+        return 1
+
+    ensure_shadow_watch(repo_root, shadow_pid_file, shadow_log)
+    ensure_desktop_app(repo_root, desktop_pid_file, desktop_log)
+    ensure_db_worker_node(repo_root, db_pid_file, db_options_file, db_log, args.repo, db_root_dir, args.extra_node_args)
+    wait_for_runtime_count(repo_root, "app", "exactly-one", 60)
+    wait_for_runtime_count(repo_root, "electron", "nonzero", 60)
+    wait_for_runtime_count(repo_root, "db-worker-node", "nonzero", 60)
+    verify_repls(repo_root)
+    print_summary(shadow_log, desktop_log, db_log, shadow_pid_file, desktop_pid_file, db_pid_file)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/.agents/skills/logseq-repl/scripts/start-repl.sh b/.agents/skills/logseq-repl/scripts/start-repl.sh
new file mode 100755
index 0000000000..6047d810a0
--- /dev/null
+++ b/.agents/skills/logseq-repl/scripts/start-repl.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec python3 "$SCRIPT_DIR/start-repl.py" "$@"
diff --git a/.agents/skills/logseq-repl/scripts/verify-repls.sh b/.agents/skills/logseq-repl/scripts/verify-repls.sh
new file mode 100755
index 0000000000..4f84abf51a
--- /dev/null
+++ b/.agents/skills/logseq-repl/scripts/verify-repls.sh
@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_REPO_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+REPO_ROOT="${REPO_ROOT:-$DEFAULT_REPO_ROOT}"
+
+usage() {
+  cat <<'EOF'
+Verify that all Logseq CLJS REPL targets are usable.
+
+Usage:
+  verify-repls.sh [options]
+
+Options:
+  --repo-root <path>    Logseq repository root (default: auto-detect from script location)
+  -h, --help            Show this help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root)
+      shift
+      REPO_ROOT="${1:?missing value for --repo-root}"
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+if [[ ! -d "$REPO_ROOT" ]]; then
+  echo "Error: repo root not found: $REPO_ROOT" >&2
+  exit 1
+fi
+
+if ! command -v pnpm >/dev/null 2>&1; then
+  echo "Error: pnpm not found in PATH" >&2
+  exit 1
+fi
+
+verify_target() {
+  local target="$1"
+  local form="$2"
+
+  echo "Checking :$target ..."
+
+  local repl_output
+  pushd "$REPO_ROOT" >/dev/null
+  if ! repl_output="$(printf '%s\n' "$form" | pnpm exec shadow-cljs cljs-repl "$target" 2>&1)"; then
+    popd >/dev/null
+    echo "Error: REPL verification failed for :$target." >&2
+    echo "--- :$target output ---" >&2
+    echo "$repl_output" >&2
+    echo "-----------------------" >&2
+    return 1
+  fi
+  popd >/dev/null
+
+  if [[ "$repl_output" != *"shadow-cljs - connected to server"* ]]; then
+    echo "Error: REPL verification did not connect for :$target." >&2
+    echo "--- :$target output ---" >&2
+    echo "$repl_output" >&2
+    echo "-----------------------" >&2
+    return 1
+  fi
+
+  echo "--- :$target result ---"
+  echo "$repl_output"
+  echo "-----------------------"
+  echo "REPL verification passed for :$target"
+}
+
+echo "Verifying CLJS REPL targets ..."
+verify_target app "(prn {:runtime :app :document? (some? js/document)})"
+verify_target electron "(prn {:runtime :electron :process? (some? js/process) :type (some-> js/process .-type)})"
+verify_target db-worker-node "(prn {:runtime :db-worker-node :process? (some? js/process) :platform (some-> js/process .-platform)})"
+echo "All CLJS REPL targets verified."
diff --git a/.agents/skills/logseq-repl/tests/test-lib.sh b/.agents/skills/logseq-repl/tests/test-lib.sh
new file mode 100644
index 0000000000..27be12e615
--- /dev/null
+++ b/.agents/skills/logseq-repl/tests/test-lib.sh
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+
+fail() {
+  echo "FAIL: $*" >&2
+  return 1
+}
+
+assert_file_exists() {
+  local path="$1"
+  [[ -e "$path" ]] || fail "expected file to exist: $path"
+}
+
+assert_not_exists() {
+  local path="$1"
+  [[ ! -e "$path" ]] || fail "expected path to be absent: $path"
+}
+
+assert_contains() {
+  local needle="$1"
+  local haystack_file="$2"
+  if ! grep -Fq "$needle" "$haystack_file"; then
+    echo "Expected to find: $needle" >&2
+    echo "--- file: $haystack_file ---" >&2
+    cat "$haystack_file" >&2
+    echo "----------------------------" >&2
+    return 1
+  fi
+}
+
+assert_not_contains_text() {
+  local needle="$1"
+  local file="$2"
+  if grep -Fq "$needle" "$file"; then
+    echo "Did not expect to find: $needle" >&2
+    echo "--- file: $file ---" >&2
+    cat "$file" >&2
+    echo "--------------------" >&2
+    return 1
+  fi
+}
+
+assert_not_matches() {
+  local pattern="$1"
+  local file="$2"
+  if grep -Eq "$pattern" "$file"; then
+    echo "Did not expect regex match: $pattern" >&2
+    echo "--- file: $file ---" >&2
+    cat "$file" >&2
+    echo "--------------------" >&2
+    return 1
+  fi
+}
+
+assert_equals() {
+  local expected="$1"
+  local actual="$2"
+  [[ "$expected" == "$actual" ]] || fail "expected '$expected' but got '$actual'"
+}
+
+portable_path_pattern() {
+  local slash='/'
+  local windows_drive='[A-Za-z]:\\[^[:space:]]+'
+  printf '%s' "${slash}Users${slash}[^[:space:]]+|${slash}home${slash}[^[:space:]]+|${windows_drive}"
+}
+
+run_test() {
+  local name="$1"
+  local fn="$2"
+
+  local status
+  set +e
+  (set -e; "$fn")
+  status=$?
+  set -e
+
+  if [[ "$status" -eq 0 ]]; then
+    echo "PASS: $name"
+    PASS_COUNT=$((PASS_COUNT + 1))
+  else
+    echo "FAIL: $name" >&2
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+  fi
+}
diff --git a/.agents/skills/logseq-repl/tests/test-logseq-repl.sh b/.agents/skills/logseq-repl/tests/test-logseq-repl.sh
new file mode 100755
index 0000000000..e521c26769
--- /dev/null
+++ b/.agents/skills/logseq-repl/tests/test-logseq-repl.sh
@@ -0,0 +1,438 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TEST_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$TEST_DIR/.." && pwd)"
+START_SCRIPT="$SKILL_DIR/scripts/start-repl.sh"
+START_PY_SCRIPT="$SKILL_DIR/scripts/start-repl.py"
+CLEANUP_SCRIPT="$SKILL_DIR/scripts/cleanup-repl.sh"
+VERIFY_SCRIPT="$SKILL_DIR/scripts/verify-repls.sh"
+SKILL_FILE="$SKILL_DIR/SKILL.md"
+ORIGINAL_PATH="$PATH"
+
+# shellcheck source=./test-lib.sh
+source "$TEST_DIR/test-lib.sh"
+
+PASS_COUNT=0
+FAIL_COUNT=0
+
+create_fake_env() {
+  TEST_ROOT="$(mktemp -d)"
+  REPO_ROOT="$TEST_ROOT/repo"
+  DB_ROOT_DIR="$TEST_ROOT/logseq-root"
+  BIN_DIR="$TEST_ROOT/bin"
+  CMD_LOG="$TEST_ROOT/commands.log"
+
+  mkdir -p "$REPO_ROOT/static" "$DB_ROOT_DIR" "$BIN_DIR"
+  DB_ROOT_DIR="$(cd "$DB_ROOT_DIR" && pwd -P)"
+  : > "$CMD_LOG"
+
+  cat > "$BIN_DIR/pnpm" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "pnpm $*" >> "$FAKE_CMD_LOG"
+
+case "${1:-}" in
+  watch)
+    echo "shadow-cljs - nREPL server started on port 8701"
+    echo "[:electron] Build completed."
+    echo "[:app] Build completed."
+    echo "[:db-worker-node] Build completed."
+    while true; do sleep 1; done
+    ;;
+  dev-electron-app)
+    echo "17:12:00.841 Logseq App(2.0.1) Starting..."
+    echo "shadow-cljs - #6 ready!"
+    while true; do sleep 1; done
+    ;;
+  exec)
+    shift
+    if [[ "${1:-}" != "shadow-cljs" ]]; then
+      echo "Unexpected pnpm exec command: $*" >&2
+      exit 1
+    fi
+    shift
+
+    input=""
+    if [[ "${1:-}" == "cljs-repl" ]] && [[ -p /dev/stdin ]]; then
+      input="$(cat)"
+    fi
+
+    if [[ "${1:-}" == "clj-eval" ]]; then
+      echo "pnpm-exec-clj-eval shadow-cljs $*" >> "$FAKE_CMD_LOG"
+      echo "shadow-cljs - connected to server"
+      case "$*" in
+        *"repl-runtimes :app"*) echo "${FAKE_APP_RUNTIME_COUNT:-1}" ;;
+        *"repl-runtimes :electron"*) echo "${FAKE_ELECTRON_RUNTIME_COUNT:-1}" ;;
+        *"repl-runtimes :db-worker-node"*) echo "${FAKE_DB_RUNTIME_COUNT:-1}" ;;
+        *) echo "0" ;;
+      esac
+      exit 0
+    fi
+
+    if [[ "${1:-}" == "cljs-repl" ]]; then
+      echo "pnpm-exec-repl ${2:-missing}" >> "$FAKE_CMD_LOG"
+      echo "shadow-cljs - connected to server"
+
+      if [[ "$input" == *":cljs/quit"* ]]; then
+        echo "verification must not send :cljs/quit" >&2
+        exit 1
+      fi
+
+      case "${2:-}" in
+        app)
+          if [[ "$input" != *":runtime :app"* ]]; then
+            echo "unexpected app verification form" >&2
+            exit 1
+          fi
+          echo 'cljs.user=> {:runtime :app, :document? true}'
+          ;;
+        electron)
+          if [[ "$input" != *":runtime :electron"* ]]; then
+            echo "unexpected electron verification form" >&2
+            exit 1
+          fi
+          echo 'cljs.user=> {:runtime :electron, :process? true}'
+          ;;
+        db-worker-node)
+          if [[ "$input" != *":runtime :db-worker-node"* ]]; then
+            echo "unexpected db-worker-node verification form" >&2
+            exit 1
+          fi
+          echo 'cljs.user=> {:runtime :db-worker-node, :process? true}'
+          ;;
+        *)
+          echo "Unexpected cljs-repl target: ${2:-}" >&2
+          exit 1
+          ;;
+      esac
+
+      echo "cljs.user=>"
+      exit 0
+    fi
+
+    echo "Unexpected shadow-cljs command: $*" >&2
+    exit 1
+    ;;
+    *)
+      echo "Unexpected pnpm command: $*" >&2
+      exit 1
+      ;;
+esac
+EOF
+
+  cat > "$BIN_DIR/node" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "node $*" >> "$FAKE_CMD_LOG"
+
+repo=""
+root_dir=""
+owner_source=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    ./static/db-worker-node.js)
+      shift
+      ;;
+    --repo)
+      repo="${2:-}"
+      shift 2
+      ;;
+    --root-dir)
+      root_dir="${2:-}"
+      shift 2
+      ;;
+    --owner-source)
+      owner_source="${2:-}"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$repo" ]]; then
+  echo "repo is required" >&2
+  exit 1
+fi
+
+if [[ -z "$root_dir" ]]; then
+  echo "root-dir is required" >&2
+  exit 1
+fi
+
+if [[ "$owner_source" != "cli" ]]; then
+  echo "owner-source cli is required" >&2
+  exit 1
+fi
+
+echo "shadow-cljs - #6 ready!"
+while true; do sleep 1; done
+EOF
+
+  cat > "$BIN_DIR/lsof" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+exit 1
+EOF
+
+  cat > "$BIN_DIR/python3" <<EOF
+#!/usr/bin/env bash
+exec "$(command -v python3)" "\$@"
+EOF
+
+  chmod +x "$BIN_DIR/pnpm" "$BIN_DIR/node" "$BIN_DIR/lsof" "$BIN_DIR/python3"
+
+  export PATH="$BIN_DIR:$ORIGINAL_PATH"
+  export FAKE_CMD_LOG="$CMD_LOG"
+  export FAKE_APP_RUNTIME_COUNT="${FAKE_APP_RUNTIME_COUNT:-1}"
+  export FAKE_ELECTRON_RUNTIME_COUNT="${FAKE_ELECTRON_RUNTIME_COUNT:-1}"
+  export FAKE_DB_RUNTIME_COUNT="${FAKE_DB_RUNTIME_COUNT:-1}"
+}
+
+cleanup_fake_env() {
+  if [[ -n "${REPO_ROOT:-}" ]]; then
+    local pid_file pid
+    for pid_file in "$REPO_ROOT"/tmp/logseq-repl/*.pid; do
+      [[ -e "$pid_file" ]] || continue
+      pid="$(tr -d '[:space:]' < "$pid_file")"
+      if [[ "$pid" =~ ^[0-9]+$ ]]; then
+        kill -9 "$pid" 2>/dev/null || true
+      fi
+    done
+  fi
+
+  PATH="$ORIGINAL_PATH"
+  unset FAKE_CMD_LOG FAKE_APP_RUNTIME_COUNT FAKE_ELECTRON_RUNTIME_COUNT FAKE_DB_RUNTIME_COUNT || true
+
+  if [[ -n "${TEST_ROOT:-}" && -d "$TEST_ROOT" ]]; then
+    rm -rf "$TEST_ROOT"
+  fi
+}
+
+scripts_exist_test() {
+  assert_file_exists "$START_SCRIPT"
+  assert_file_exists "$START_PY_SCRIPT"
+  assert_file_exists "$CLEANUP_SCRIPT"
+  assert_file_exists "$VERIFY_SCRIPT"
+}
+
+start_launches_all_repl_processes_without_attaching_test() {
+  create_fake_env
+  trap cleanup_fake_env RETURN
+
+  bash "$START_SCRIPT" --repo-root "$REPO_ROOT" --root-dir "$DB_ROOT_DIR" --repo demo > "$TEST_ROOT/start.log" 2>&1
+
+  assert_contains "Verifying CLJS REPL targets ..." "$TEST_ROOT/start.log"
+  assert_contains "REPL verification passed for :app" "$TEST_ROOT/start.log"
+  assert_contains "REPL verification passed for :electron" "$TEST_ROOT/start.log"
+  assert_contains "REPL verification passed for :db-worker-node" "$TEST_ROOT/start.log"
+  assert_contains "Startup complete. Attach to the needed REPL manually." "$TEST_ROOT/start.log"
+  assert_contains "pnpm exec shadow-cljs cljs-repl app" "$TEST_ROOT/start.log"
+  assert_contains "pnpm exec shadow-cljs cljs-repl electron" "$TEST_ROOT/start.log"
+  assert_contains "pnpm exec shadow-cljs cljs-repl db-worker-node" "$TEST_ROOT/start.log"
+  assert_contains "pnpm watch" "$CMD_LOG"
+  assert_contains "pnpm dev-electron-app" "$CMD_LOG"
+  assert_contains "node ./static/db-worker-node.js --repo demo --root-dir $DB_ROOT_DIR --owner-source cli" "$CMD_LOG"
+  assert_file_exists "$REPO_ROOT/tmp/logseq-repl/shared-shadow-watch.pid"
+  assert_file_exists "$REPO_ROOT/tmp/logseq-repl/desktop-electron.pid"
+  assert_file_exists "$REPO_ROOT/tmp/logseq-repl/db-worker-node.pid"
+  assert_file_exists "$REPO_ROOT/tmp/logseq-repl/shared-shadow-watch.log"
+  assert_file_exists "$REPO_ROOT/tmp/logseq-repl/desktop-electron.log"
+  assert_file_exists "$REPO_ROOT/tmp/logseq-repl/db-worker-node.log"
+}
+
+verify_script_checks_all_targets_test() {
+  create_fake_env
+  trap cleanup_fake_env RETURN
+
+  bash "$VERIFY_SCRIPT" --repo-root "$REPO_ROOT" > "$TEST_ROOT/verify.log" 2>&1
+
+  assert_contains "Verifying CLJS REPL targets ..." "$TEST_ROOT/verify.log"
+  assert_contains "REPL verification passed for :app" "$TEST_ROOT/verify.log"
+  assert_contains "REPL verification passed for :electron" "$TEST_ROOT/verify.log"
+  assert_contains "REPL verification passed for :db-worker-node" "$TEST_ROOT/verify.log"
+  assert_contains "All CLJS REPL targets verified." "$TEST_ROOT/verify.log"
+  assert_contains "pnpm-exec-repl app" "$CMD_LOG"
+  assert_contains "pnpm-exec-repl electron" "$CMD_LOG"
+  assert_contains "pnpm-exec-repl db-worker-node" "$CMD_LOG"
+}
+
+verify_script_fails_when_target_repl_fails_test() {
+  create_fake_env
+  trap cleanup_fake_env RETURN
+
+  cat > "$BIN_DIR/pnpm" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "pnpm $*" >> "$FAKE_CMD_LOG"
+
+if [[ "${1:-}" == "exec" && "${2:-}" == "shadow-cljs" && "${3:-}" == "cljs-repl" && "${4:-}" == "electron" ]]; then
+  echo "No available JS runtime" >&2
+  exit 1
+fi
+
+echo "shadow-cljs - connected to server"
+echo "cljs.user=> {:ok true}"
+EOF
+  chmod +x "$BIN_DIR/pnpm"
+
+  if bash "$VERIFY_SCRIPT" --repo-root "$REPO_ROOT" > "$TEST_ROOT/verify.log" 2>&1; then
+    fail "expected verify script to fail when one target REPL fails"
+  fi
+
+  assert_contains "Error: REPL verification failed for :electron." "$TEST_ROOT/verify.log"
+  assert_contains "No available JS runtime" "$TEST_ROOT/verify.log"
+}
+
+start_reuses_all_running_processes_test() {
+  create_fake_env
+  trap cleanup_fake_env RETURN
+
+  bash "$START_SCRIPT" --repo-root "$REPO_ROOT" --root-dir "$DB_ROOT_DIR" --repo demo > "$TEST_ROOT/first.log" 2>&1
+  bash "$START_SCRIPT" --repo-root "$REPO_ROOT" --root-dir "$DB_ROOT_DIR" --repo demo > "$TEST_ROOT/second.log" 2>&1
+
+  assert_equals "1" "$(grep -c '^pnpm watch$' "$CMD_LOG")"
+  assert_equals "1" "$(grep -c '^pnpm dev-electron-app$' "$CMD_LOG")"
+  assert_equals "1" "$(grep -Fc "node ./static/db-worker-node.js --repo demo --root-dir $DB_ROOT_DIR --owner-source cli" "$CMD_LOG")"
+  assert_contains "Reusing shared shadow-cljs watch" "$TEST_ROOT/second.log"
+  assert_contains "Reusing Desktop dev app" "$TEST_ROOT/second.log"
+  assert_contains "Reusing db-worker-node runtime" "$TEST_ROOT/second.log"
+}
+
+start_restarts_db_worker_when_root_dir_changes_test() {
+  create_fake_env
+  trap cleanup_fake_env RETURN
+
+  local first_root second_root
+  first_root="$TEST_ROOT/logseq-root-a"
+  second_root="$TEST_ROOT/logseq-root-b"
+  mkdir -p "$first_root" "$second_root"
+  first_root="$(cd "$first_root" && pwd -P)"
+  second_root="$(cd "$second_root" && pwd -P)"
+
+  bash "$START_SCRIPT" --repo-root "$REPO_ROOT" --root-dir "$first_root" --repo demo > "$TEST_ROOT/first.log" 2>&1
+  bash "$START_SCRIPT" --repo-root "$REPO_ROOT" --root-dir "$second_root" --repo demo > "$TEST_ROOT/second.log" 2>&1
+
+  assert_equals "1" "$(grep -Fc "node ./static/db-worker-node.js --repo demo --root-dir $first_root --owner-source cli" "$CMD_LOG")"
+  assert_equals "1" "$(grep -Fc "node ./static/db-worker-node.js --repo demo --root-dir $second_root --owner-source cli" "$CMD_LOG")"
+  assert_contains "Stopping existing db-worker-node" "$TEST_ROOT/second.log"
+}
+
+start_fails_when_app_runtime_is_ambiguous_test() {
+  create_fake_env
+  trap cleanup_fake_env RETURN
+  export FAKE_APP_RUNTIME_COUNT=2
+
+  if bash "$START_SCRIPT" --repo-root "$REPO_ROOT" --root-dir "$DB_ROOT_DIR" --repo demo > "$TEST_ROOT/start.log" 2>&1; then
+    fail "expected start script to fail when more than one :app runtime exists"
+  fi
+
+  assert_contains "Expected exactly one live :app runtime" "$TEST_ROOT/start.log"
+}
+
+cleanup_stops_all_repl_processes_test() {
+  create_fake_env
+  trap cleanup_fake_env RETURN
+
+  bash "$START_SCRIPT" --repo-root "$REPO_ROOT" --root-dir "$DB_ROOT_DIR" --repo demo > "$TEST_ROOT/start.log" 2>&1
+
+  local watch_pid desktop_pid db_pid
+  watch_pid="$(tr -d '[:space:]' < "$REPO_ROOT/tmp/logseq-repl/shared-shadow-watch.pid")"
+  desktop_pid="$(tr -d '[:space:]' < "$REPO_ROOT/tmp/logseq-repl/desktop-electron.pid")"
+  db_pid="$(tr -d '[:space:]' < "$REPO_ROOT/tmp/logseq-repl/db-worker-node.pid")"
+
+  bash "$CLEANUP_SCRIPT" --repo-root "$REPO_ROOT" > "$TEST_ROOT/cleanup.log" 2>&1
+
+  if kill -0 "$watch_pid" 2>/dev/null; then
+    fail "expected shared watch to stop"
+  fi
+
+  if kill -0 "$desktop_pid" 2>/dev/null; then
+    fail "expected Desktop dev app to stop"
+  fi
+
+  if kill -0 "$db_pid" 2>/dev/null; then
+    fail "expected db-worker-node to stop"
+  fi
+
+  assert_not_exists "$REPO_ROOT/tmp/logseq-repl/shared-shadow-watch.pid"
+  assert_not_exists "$REPO_ROOT/tmp/logseq-repl/desktop-electron.pid"
+  assert_not_exists "$REPO_ROOT/tmp/logseq-repl/db-worker-node.pid"
+  assert_contains "Cleanup done." "$TEST_ROOT/cleanup.log"
+}
+
+cleanup_removes_legacy_state_files_test() {
+  create_fake_env
+  trap cleanup_fake_env RETURN
+
+  mkdir -p "$REPO_ROOT/tmp/desktop-app-repl" "$REPO_ROOT/tmp/db-worker-node-repl" "$REPO_ROOT/tmp/logseq-repl"
+  sleep 30 &
+  local legacy_desktop_pid=$!
+  sleep 30 &
+  local legacy_db_pid=$!
+  echo "$legacy_desktop_pid" > "$REPO_ROOT/tmp/desktop-app-repl/desktop-electron.pid"
+  echo "$legacy_db_pid" > "$REPO_ROOT/tmp/db-worker-node-repl/db-worker-node.pid"
+  echo "$legacy_db_pid" > "$REPO_ROOT/tmp/db-worker-node-repl/shadow-db-worker-node.pid"
+
+  bash "$CLEANUP_SCRIPT" --repo-root "$REPO_ROOT" > "$TEST_ROOT/cleanup.log" 2>&1
+
+  if kill -0 "$legacy_desktop_pid" 2>/dev/null; then
+    fail "expected legacy desktop pid to stop"
+  fi
+
+  if kill -0 "$legacy_db_pid" 2>/dev/null; then
+    fail "expected legacy db-worker pid to stop"
+  fi
+
+  assert_not_exists "$REPO_ROOT/tmp/desktop-app-repl/desktop-electron.pid"
+  assert_not_exists "$REPO_ROOT/tmp/db-worker-node-repl/db-worker-node.pid"
+  assert_not_exists "$REPO_ROOT/tmp/db-worker-node-repl/shadow-db-worker-node.pid"
+}
+
+help_and_docs_describe_unified_scripts_test() {
+  local temp_dir start_help cleanup_help
+  temp_dir="$(mktemp -d)"
+  start_help="$temp_dir/start-help.txt"
+  cleanup_help="$temp_dir/cleanup-help.txt"
+
+  bash "$START_SCRIPT" --help > "$start_help"
+  bash "$CLEANUP_SCRIPT" --help > "$cleanup_help"
+
+  assert_contains "start-repl.sh" "$start_help"
+  assert_contains "start-repl.py" "$SKILL_FILE"
+  assert_contains "cleanup-repl.sh" "$cleanup_help"
+  assert_contains "start-repl.sh" "$SKILL_FILE"
+  assert_contains "cleanup-repl.sh" "$SKILL_FILE"
+  assert_contains "verify-repls.sh" "$SKILL_FILE"
+  assert_not_contains_text "start-desktop-app-repl.sh" "$SKILL_FILE"
+  assert_not_contains_text "start-db-worker-node-repl.sh" "$SKILL_FILE"
+  assert_not_contains_text "cleanup-desktop-app-repl.sh" "$SKILL_FILE"
+  assert_not_contains_text "cleanup-db-worker-node-repl.sh" "$SKILL_FILE"
+
+  rm -rf "$temp_dir"
+}
+
+run_test "scripts exist" scripts_exist_test
+run_test "start launches all REPL processes without attaching" start_launches_all_repl_processes_without_attaching_test
+run_test "verify script checks all targets" verify_script_checks_all_targets_test
+run_test "verify script fails when target REPL fails" verify_script_fails_when_target_repl_fails_test
+run_test "start reuses all running processes" start_reuses_all_running_processes_test
+run_test "start restarts db-worker when root-dir changes" start_restarts_db_worker_when_root_dir_changes_test
+run_test "start fails when app runtime is ambiguous" start_fails_when_app_runtime_is_ambiguous_test
+run_test "cleanup stops all REPL processes" cleanup_stops_all_repl_processes_test
+run_test "cleanup removes legacy state files" cleanup_removes_legacy_state_files_test
+run_test "help and docs describe unified scripts" help_and_docs_describe_unified_scripts_test
+
+echo
+if [[ "$FAIL_COUNT" -gt 0 ]]; then
+  echo "$FAIL_COUNT test(s) failed; $PASS_COUNT passed." >&2
+  exit 1
+fi
+
+echo "All $PASS_COUNT test(s) passed."
diff --git a/.carve/ignore b/.carve/ignore
index 7145230ed3..0bf7dec926 100644
--- a/.carve/ignore
+++ b/.carve/ignore
@@ -60,6 +60,10 @@ frontend.ui/_emoji-init-data
 frontend.worker.rtc.op-mem-layer/_sync-loop-canceler
 ;; Used by shadow.cljs
 frontend.worker.db-worker/init
+;; Used by shadow.cljs (node entrypoint)
+frontend.worker.db-worker-node/main
+;; CLI entrypoint (shadow-cljs :node-script)
+logseq.cli.main/main
 ;; Future use?
 frontend.worker.rtc.hash/hash-blocks
 ;; Repl fn
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index f2d0a3cb57..d66d42db48 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -62,6 +62,7 @@ jobs:
         uses: DeLaGuardo/setup-clojure@13.5
         with:
           cli: ${{ env.CLOJURE_VERSION }}
+          bb: ${{ env.BABASHKA_VERSION }}
 
       - name: Clojure cache
         uses: actions/cache@v4
@@ -84,11 +85,21 @@ jobs:
         run: clojure -M:test compile test
 
       - name: Run ClojureScript query tests against basic query type
-        run: DB_QUERY_TYPE=basic node static/tests.js -r frontend.db.query-dsl-test
+        run: DB_QUERY_TYPE=basic pnpm cljs:run-test -r frontend.db.query-dsl-test
 
       - name: Run ClojureScript tests
         run: pnpm cljs:run-test
 
+      - name: Setup CLI integration test
+        # logseq-cli.js needed just for test-cli-query-human-output-pipes-to-show
+        run: clojure -M:cljs compile logseq-cli && pnpm db-worker-node:release:bundle
+
+      - name: Run ClojureScript integration tests
+        run: pnpm cljs:run-integration-test
+
+      - name: Run CLI E2E tests
+        run: bb dev:cli-e2e --verbose --skip-build
+
   lint:
     runs-on: ubuntu-22.04
 
diff --git a/.github/workflows/deps-graph-parser.yml b/.github/workflows/deps-graph-parser.yml
index e98d7ea2d5..ad8fb53636 100644
--- a/.github/workflows/deps-graph-parser.yml
+++ b/.github/workflows/deps-graph-parser.yml
@@ -83,9 +83,6 @@ jobs:
       - name: Fetch pnpm deps
         run: pnpm install --frozen-lockfile
 
-      - name: Run ClojureScript tests
-        run: clojure -M:test
-
       - name: Run nbb-logseq tests
         run: pnpm test
 
diff --git a/.gitignore b/.gitignore
index d4eeb375e7..5e58de6737 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,7 @@ node_modules/
 static/**
 tmp
 cljs-test-runner-out
+.tmp/
 
 .cpcache/
 /src/gen
@@ -44,6 +45,7 @@ resources/electron.js
 /libs/dist/
 charlie/
 .vscode
+/.claude
 /.preprocessor-cljs
 docker
 android/app/src/main/assets/capacitor.plugin.json
@@ -79,3 +81,12 @@ clj-e2e/e2e-dump
 .dir-locals.el
 .projectile
 deps/db-sync/data
+*.map
+/dist/db-worker-node.js
+/dist/build/
+/dist/db-worker-node-assets.json
+/dist/*.wasm
+/dist/cljs-runtime/
+/.agent-shell/
+
+clj-e2e/.clj-kondo/imports
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index 94ee64e1f0..c7b3d66e2d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,20 +1,20 @@
 # Repository Guidelines
 
-## Project Structure & Module Organization
-- `src/` is the main codebase.
-  - `src/main/` contains core application logic.
-  - `src/main/mobile/` is the mobile app code.
-  - `src/main/frontend/components/` houses UI components.
-  - `src/main/frontend/worker/` holds webworker code, including RTC in `src/main/frontend/worker/rtc/`.
-- `src/electron/` is Electron-specific code.
-- `src/test/` contains unit tests.
-- `deps/` contains internal dependencies/modules.
-- `clj-e2e/` contains end-to-end tests.
-
 ## Build, Test, and Development Commands
 - `bb dev:lint-and-test` runs linters and unit tests.
 - `bb dev:test -v <namespace/testcase-name>` runs a single unit test (example: `bb dev:test -v logseq.some-test/foo`).
-- E2E tests live in `clj-e2e/`; run them from that directory if needed.
+- App E2E tests live in `clj-e2e/`; run from that directory with `bb test` (or `bb -f clj-e2e/bb.edn test` from repo root).
+- CLI E2E tests live in `cli-e2e/`; run with `bb -f cli-e2e/bb.edn test --skip-build` (or `bb -f cli-e2e/bb.edn build` first when needed).
+- If a request says only “e2e”, clarify whether it targets `clj-e2e/` or `cli-e2e/` before planning changes.
+
+## Error handling and compatibility
+- When modifying code, first consider removing compatibility layers rather than extending them.
+- Prefer fail-fast over fallback.
+- Do not add backward compatibility unless explicitly requested.
+- Do not introduce default values to mask invalid state.
+- Do not silently recover from programmer errors.
+- Keep one clear code path whenever possible.
+- Internal code may assume well-formed inputs from controlled callers.
 
 ## Coding Style & Naming Conventions
 - ClojureScript keywords are defined via `logseq.common.defkeywords/defkeyword`; use existing keywords and add new ones in the shared definitions.
@@ -29,12 +29,16 @@
 - Name tests after their namespaces; use `-v` to target a specific test case.
 - Run lint/tests before submitting PRs; keep changes green.
 
+## *IMPORTANT*: Always respect directory-specific AGENTS.md based on file path
+- when editing code in a specific directory, you must recursively read `AGENTS.md` files up the directory tree, and `AGENTS.md` in subdirectories takes precedence over the root-level one
+
 ## Commit & Pull Request Guidelines
 - Commit subjects are short and imperative; optional scope prefixes appear (e.g., `fix:` or `enhance(rtc):`).
 - PRs should describe the behavior change, link relevant issues, and note any test coverage added or skipped.
 
 ## Agent-Specific Notes
-- Project-specific skills live under `.agents/skills/`; load `.agents/skills/logseq-i18n/SKILL.md` for i18n/localization/hardcoded UI text tasks.
+- Use repo-local skills discovered under `.agents/skills/`; load the matching `SKILL.md` before editing files or proposing changes.
+- **i18n (mandatory)**: Always load `.agents/skills/logseq-i18n/SKILL.md` before any change that adds, edits, or removes user-facing UI text, regardless of whether other skills also apply.
 - Review notes live in `prompts/review.md`; check them when preparing changes.
 - DB-sync feature guide for AI agents: `docs/agent-guide/db-sync/db-sync-guide.md`.
 - DB-sync protocol reference: `docs/agent-guide/db-sync/protocol.md`.
diff --git a/README.md b/README.md
index d5f8c0ba89..04e75f892e 100644
--- a/README.md
+++ b/README.md
@@ -169,6 +169,10 @@ If you want to set up a development environment for the Logseq web or desktop ap
 
 In addition to these guides, you can also find other helpful resources in the [docs/](docs/) folder, such as the [Guide for Contributing to Translations](docs/contributing-to-translations.md), the [Docker Web App Guide](docs/docker-web-app-guide.md) and the [mobile development guide](docs/develop-logseq-on-mobile.md)
 
+### 🧰 Logseq CLI (Node)
+
+Logseq CLI documentation is maintained in `docs/cli/logseq-cli.md`.
+
 ## ✨ Inspiration
 
 Logseq is inspired by several unique tools and projects, including [Roam Research](https://roamresearch.com/), [Org Mode](https://orgmode.org/), [TiddlyWiki](https://tiddlywiki.com/), [Workflowy](https://workflowy.com/), and [Cuekeeper](https://github.com/talex5/cuekeeper).
diff --git a/bb.edn b/bb.edn
index 71f92b5491..2d447a6429 100644
--- a/bb.edn
+++ b/bb.edn
@@ -68,6 +68,7 @@
            (run '-dev:publishing-dev {:parallel true})
            (run '-dev:publishing-release))}
 
+  ;; legacy cli
   dev:cli
   {:doc "Run CLI with current deps/db code. Commands with JS deps are not usable e.g. mcp-server"
    :task (apply shell {:dir "deps/db"}
@@ -192,6 +193,24 @@
   dev:gen-malli-kondo-config
   logseq.tasks.dev/gen-malli-kondo-config
 
+  dev:db-worker-node
+  {:doc "Compile and start db-worker-node (pass-through args forwarded to node)"
+   :task (do
+           (shell "clojure" "-M:cljs" "compile" "db-worker-node")
+           (apply shell "node" "./static/db-worker-node.js" *command-line-args*))}
+
+  dev:cli-e2e
+  {:doc "Run shell-first CLI end-to-end tests"
+   :task (apply shell {:shutdown nil} "bb" "-f" "cli-e2e/bb.edn" "test" *command-line-args*)}
+
+  dev:cli-e2e-cleanup
+  {:doc "Run shell-first CLI end-to-end cleanup"
+   :task (apply shell {:shutdown nil} "bb" "-f" "cli-e2e/bb.edn" "cleanup" *command-line-args*)}
+
+  dev:cli-e2e-sync
+  {:doc "Run shell-first CLI sync end-to-end tests"
+   :task (apply shell {:shutdown nil} "bb" "-f" "cli-e2e/bb.edn" "test-sync" *command-line-args*)}
+
   lint:dev
   logseq.tasks.dev.lint/dev
 
diff --git a/cli-e2e/AGENTS.md b/cli-e2e/AGENTS.md
new file mode 100644
index 0000000000..e872a40c81
--- /dev/null
+++ b/cli-e2e/AGENTS.md
@@ -0,0 +1,38 @@
+# cli-e2e
+
+Shell-first end-to-end tests for logseq CLI.
+
+## Test cli-e2e itself
+- Run internal cli-e2e harness unit tests: `bb unit-test`
+
+## cleanup first
+- Execute cleanup: terminate stale db-worker-node processes, terminate stale db-sync listeners on port `18080`, and remove cli-e2e temp roots: `bb cleanup`
+- Preview cleanup actions only (no kill/delete): `bb cleanup --dry-run`
+
+## Run non-sync suite
+- List declared non-sync case ids: `bb list-cases`
+- Run non-sync cases with build preflight unless `--skip-build` is provided: `bb test`
+  - `bb test --help` for options
+  - Increase case-level parallelism with `--jobs N` (default: `4`), for example: `bb test --skip-build --jobs 4`
+  - Parallelism is case-scoped only; each case still runs setup/main/cleanup sequentially in the existing ephemeral shell model
+
+## Run sync suite
+- List declared sync case ids: `bb list-sync-cases`
+- Run sync cases with build preflight by default: `bb test-sync`
+  - Add `--skip-build` only when you intentionally want to reuse existing artifacts
+  - `bb test-sync --help` for options
+  - Increase case-level parallelism with `--jobs N` (default: `4`), for example: `bb test-sync --jobs 4`
+  - Parallelism is case-scoped only; each sync case still runs its own setup/main/cleanup sequentially
+  - The local db-sync server is shared per suite and starts once before cases begin, then stops once after all cases complete
+  - Each sync case gets its own isolated temp root, data directories, home directory, auth copy, and generated config files
+  - Configure sync E2EE password: `--e2ee-password <value>` (default: `11111`)
+  - Run only sync MVP case: `bb test-sync --case sync-upload-download-mvp`
+
+### Sync suite prerequisites
+- CLI auth file must exist at `~/logseq/auth.json` (generated by `logseq login`).
+- Sync suite starts/stops one shared local db-sync server per suite run.
+- Required build artifact for local db-sync server:
+  - `deps/db-sync/worker/dist/node-adapter.js`
+- If artifact is missing, build it before running sync suite:
+  - `pnpm --dir deps/db-sync build:node-adapter`
+
diff --git a/cli-e2e/README.md b/cli-e2e/README.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/cli-e2e/README.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/cli-e2e/bb.edn b/cli-e2e/bb.edn
new file mode 100644
index 0000000000..8011c614e5
--- /dev/null
+++ b/cli-e2e/bb.edn
@@ -0,0 +1,47 @@
+{:paths ["src" "test"]
+ :deps {cheshire/cheshire {:mvn/version "5.12.0"}}
+ :tasks
+ {:requires ([babashka.cli :as cli]
+             [logseq.cli.e2e.main :as main]
+             [logseq.cli.e2e.test-runner :as test-runner])
+  :init (def cli-opts
+          (cli/parse-opts
+           *command-line-args*
+           {:alias {:i :include
+                    :h :help}
+            :spec {:jobs {:default 4}}
+            :coerce {:include []
+                     :help :boolean
+                     :dry-run :boolean
+                     :skip-build :boolean
+                     :verbose :boolean
+                     :timings :boolean
+                     :jobs :long}}))
+
+  unit-test
+  {:doc "Run internal cli-e2e harness unit tests"
+   :task (test-runner/run! cli-opts)}
+
+  build
+  {:doc "Compile required CLI artifacts and verify expected outputs exist"
+   :task (main/build! cli-opts)}
+
+  list-cases
+  {:doc "List declared non-sync cli-e2e case ids"
+   :task (main/list-cases! cli-opts)}
+
+  list-sync-cases
+  {:doc "List declared sync cli-e2e case ids"
+   :task (main/list-sync-cases! cli-opts)}
+
+  test
+  {:doc "Run non-sync cli-e2e cases with build preflight unless --skip-build is provided"
+   :task (main/test! cli-opts)}
+
+  test-sync
+  {:doc "Run sync cli-e2e cases with build preflight unless --skip-build is provided; use --jobs for case-level parallelism"
+   :task (main/test-sync! cli-opts)}
+
+  cleanup
+  {:doc "Terminate cli-e2e db-worker-node processes, terminate stale db-sync listeners, and remove cli-e2e temp roots"
+   :task (main/cleanup! cli-opts)}}}
diff --git a/cli-e2e/scripts/compare_graph_queries.py b/cli-e2e/scripts/compare_graph_queries.py
new file mode 100644
index 0000000000..b5d95c1e35
--- /dev/null
+++ b/cli-e2e/scripts/compare_graph_queries.py
@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Compare normalized query payloads between two cli graph contexts."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+IGNORED_KEYS = {
+    "db/id",
+    "db/created-at",
+    "db/updated-at",
+    "block/uuid",
+    "block/updated-at",
+    "block/created-at",
+}
+
+
+def fail(message: str, **context: object) -> None:
+    payload = {"status": "error", "message": message}
+    if context:
+        payload["context"] = context
+    print(json.dumps(payload), file=sys.stderr)
+    raise SystemExit(1)
+
+
+def normalize(value: Any) -> Any:
+    if isinstance(value, dict):
+        normalized = {}
+        for key in sorted(value.keys(), key=str):
+            key_str = str(key)
+            if key_str in IGNORED_KEYS:
+                continue
+            normalized[key_str] = normalize(value[key])
+        return normalized
+    if isinstance(value, list):
+        normalized_list = [normalize(item) for item in value]
+        try:
+            return sorted(normalized_list, key=lambda item: json.dumps(item, sort_keys=True))
+        except TypeError:
+            return normalized_list
+    return value
+
+
+def run_query(cli_path: Path, config_path: Path, root_dir: Path, graph: str, query: str) -> Dict[str, Any]:
+    command = [
+        "node",
+        str(cli_path),
+        "--root-dir",
+        str(root_dir),
+        "--config",
+        str(config_path),
+        "--output",
+        "json",
+        "query",
+        "--graph",
+        graph,
+        "--query",
+        query,
+    ]
+
+    result = subprocess.run(command, capture_output=True, text=True)
+    if result.returncode != 0:
+        fail(
+            "query command failed",
+            command=command,
+            exit=result.returncode,
+            stdout=result.stdout,
+            stderr=result.stderr,
+        )
+
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        fail(
+            "query command did not return valid JSON",
+            command=command,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            detail=str(error),
+        )
+
+    if payload.get("status") != "ok":
+        fail("query command returned non-ok status", command=command, payload=payload)
+
+    data = payload.get("data") or {}
+    return {
+        "payload": payload,
+        "result": data.get("result"),
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Compare normalized query payloads between two cli contexts")
+    parser.add_argument("--cli", required=True, help="Path to static/logseq-cli.js")
+    parser.add_argument("--graph", required=True)
+    parser.add_argument("--query", required=True, action="append")
+    parser.add_argument("--config-a", required=True)
+    parser.add_argument("--root-dir-a", required=True)
+    parser.add_argument("--config-b", required=True)
+    parser.add_argument("--root-dir-b", required=True)
+    parser.add_argument("--require-result", action="store_true")
+    return parser.parse_args()
+
+
+
+def main() -> None:
+    args = parse_args()
+
+    cli_path = Path(args.cli).expanduser().resolve()
+    if not cli_path.exists():
+        fail("cli entry file does not exist", cli=str(cli_path))
+
+    queries = args.query
+    left_config = Path(args.config_a).expanduser().resolve()
+    left_root_dir = Path(args.root_dir_a).expanduser().resolve()
+    right_config = Path(args.config_b).expanduser().resolve()
+    right_root_dir = Path(args.root_dir_b).expanduser().resolve()
+
+    normalized_results = {}
+
+    for query in queries:
+        left = run_query(
+            cli_path,
+            left_config,
+            left_root_dir,
+            args.graph,
+            query,
+        )
+        right = run_query(
+            cli_path,
+            right_config,
+            right_root_dir,
+            args.graph,
+            query,
+        )
+
+        left_result = left["result"]
+        right_result = right["result"]
+
+        if args.require_result and (left_result is None or right_result is None):
+            fail(
+                "query result is empty",
+                query=query,
+                left_result=left_result,
+                right_result=right_result,
+            )
+
+        left_normalized = normalize(left_result)
+        right_normalized = normalize(right_result)
+
+        if left_normalized != right_normalized:
+            fail(
+                "normalized query results differ",
+                query=query,
+                left_result=left_normalized,
+                right_result=right_normalized,
+                left_payload=left["payload"],
+                right_payload=right["payload"],
+            )
+
+        normalized_results[query] = left_normalized
+
+    payload_key = "result" if len(normalized_results) == 1 else "results"
+    payload_value = next(iter(normalized_results.values())) if len(normalized_results) == 1 else normalized_results
+    print(
+        json.dumps(
+            {
+                "status": "ok",
+                payload_key: payload_value,
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/cli-e2e/scripts/db_sync_server.py b/cli-e2e/scripts/db_sync_server.py
new file mode 100644
index 0000000000..fe041a4f92
--- /dev/null
+++ b/cli-e2e/scripts/db_sync_server.py
@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""Manage local db-sync server process for cli-e2e sync suite."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import ctypes
+import json
+import os
+import signal
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+DEFAULT_COGNITO_ISSUER = "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_kAqZcxIeM"
+DEFAULT_COGNITO_CLIENT_ID = "1qi1uijg8b6ra70nejvbptis0q"
+
+
+def fail(message: str, **context: object) -> None:
+    payload = {"status": "error", "message": message}
+    if context:
+        payload["context"] = context
+    print(json.dumps(payload), file=sys.stderr)
+    raise SystemExit(1)
+
+
+def load_pid(pid_file: Path) -> Optional[int]:
+    if not pid_file.exists():
+        return None
+    raw = pid_file.read_text(encoding="utf-8").strip()
+    if not raw:
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        return None
+
+
+def process_running(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    if os.name == "nt":
+        kernel32 = ctypes.windll.kernel32
+        access = 0x00100000 | 0x1000  # SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION
+        handle = kernel32.OpenProcess(access, False, pid)
+        if handle:
+            kernel32.CloseHandle(handle)
+            return True
+        return ctypes.get_last_error() == 5
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    else:
+        return True
+
+
+def terminate_process(pid: int, force: bool) -> bool:
+    if pid <= 0:
+        return True
+    if os.name == "nt":
+        cmd = ["taskkill", "/PID", str(pid), "/T"]
+        if force:
+            cmd.append("/F")
+        result = subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
+        return result.returncode == 0 or not process_running(pid)
+    try:
+        os.kill(pid, signal.SIGKILL if force else signal.SIGTERM)
+    except ProcessLookupError:
+        return True
+    except PermissionError:
+        return False
+    return True
+
+
+def parse_json_file(path: Path) -> Dict[str, Any]:
+    if not path.exists():
+        fail("sync auth file is missing", auth_path=str(path), hint="Run `logseq login` first.")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        fail("sync auth file is invalid JSON", auth_path=str(path), detail=str(error))
+    if not isinstance(payload, dict):
+        fail("sync auth file must be a JSON object", auth_path=str(path))
+    return payload
+
+
+def decode_jwt_claims(token: str) -> Optional[Dict[str, Any]]:
+    if not isinstance(token, str):
+        return None
+    parts = token.split(".")
+    if len(parts) != 3:
+        return None
+    payload = parts[1]
+    padded = payload + "=" * ((4 - (len(payload) % 4)) % 4)
+    try:
+        decoded = base64.urlsafe_b64decode(padded.encode("utf-8")).decode("utf-8")
+        claims = json.loads(decoded)
+    except (ValueError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    return claims if isinstance(claims, dict) else None
+
+
+def auth_cognito_from_auth_file(auth_path: Path) -> Dict[str, str]:
+    payload = parse_json_file(auth_path)
+    token = payload.get("id-token") or payload.get("access-token")
+    claims = decode_jwt_claims(token) if isinstance(token, str) else None
+
+    issuer = claims.get("iss") if isinstance(claims, dict) else None
+    client_id = None
+    if isinstance(claims, dict):
+        client_id = claims.get("aud") or claims.get("client_id")
+
+    return {
+        "issuer": issuer if isinstance(issuer, str) and issuer else "",
+        "client_id": client_id if isinstance(client_id, str) and client_id else "",
+    }
+
+
+def wait_health(base_url: str, timeout_s: float, interval_s: float) -> bool:
+    deadline = time.time() + timeout_s
+    url = base_url.rstrip("/") + "/health"
+    opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+    while time.time() < deadline:
+        try:
+            with opener.open(url, timeout=2) as response:
+                if response.status == 200:
+                    return True
+        except (urllib.error.URLError, TimeoutError, socket.timeout):
+            pass
+        time.sleep(interval_s)
+    return False
+
+
+def start_server(args: argparse.Namespace) -> None:
+    repo_root = Path(args.repo_root).expanduser().resolve()
+    entry = repo_root / "deps" / "db-sync" / "worker" / "dist" / "node-adapter.js"
+    if not entry.exists():
+        fail("db-sync node adapter build artifact is missing", entry=str(entry), hint="Run: yarn --cwd deps/db-sync build:node-adapter")
+
+    pid_file = Path(args.pid_file).expanduser().resolve()
+    log_file = Path(args.log_file).expanduser().resolve()
+    data_dir = Path(args.data_dir).expanduser().resolve()
+
+    pid_file.parent.mkdir(parents=True, exist_ok=True)
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    existing_pid = load_pid(pid_file)
+    if existing_pid and process_running(existing_pid):
+        fail("db-sync server already running", pid=existing_pid, pid_file=str(pid_file))
+
+    auth_path = Path(args.auth_path).expanduser().resolve() if args.auth_path else None
+    auth_derived = auth_cognito_from_auth_file(auth_path) if auth_path else {"issuer": "", "client_id": ""}
+
+    issuer = args.cognito_issuer or auth_derived.get("issuer") or DEFAULT_COGNITO_ISSUER
+    client_id = args.cognito_client_id or auth_derived.get("client_id") or DEFAULT_COGNITO_CLIENT_ID
+    jwks_url = args.cognito_jwks_url or f"{issuer}/.well-known/jwks.json"
+
+    env = os.environ.copy()
+    env.update(
+        {
+            "DB_SYNC_PORT": str(args.port),
+            "DB_SYNC_DATA_DIR": str(data_dir),
+            "COGNITO_ISSUER": issuer,
+            "COGNITO_CLIENT_ID": client_id,
+            "COGNITO_JWKS_URL": jwks_url,
+            # CLI e2e sync suite should remain runnable without outbound internet.
+            "DB_SYNC_ALLOW_UNVERIFIED_JWT_CLAIMS": "true",
+        }
+    )
+
+    with log_file.open("a", encoding="utf-8") as stream:
+        stream.write(f"\n=== cli-e2e db-sync start {time.strftime('%Y-%m-%d %H:%M:%S')} ===\n")
+        stream.flush()
+        process = subprocess.Popen(
+            ["node", str(entry)],
+            stdout=stream,
+            stderr=stream,
+            cwd=str(repo_root),
+            env=env,
+            start_new_session=True,
+        )
+
+    base_url = f"http://{args.host}:{args.port}"
+    if not wait_health(base_url, args.startup_timeout_s, args.poll_interval_s):
+        terminate_process(process.pid, force=False)
+        fail(
+            "db-sync server failed health check before timeout",
+            base_url=base_url,
+            pid=process.pid,
+            log_file=str(log_file),
+        )
+
+    pid_file.write_text(f"{process.pid}\n", encoding="utf-8")
+    print(
+        json.dumps(
+            {
+                "status": "ok",
+                "pid": process.pid,
+                "pid_file": str(pid_file),
+                "log_file": str(log_file),
+                "base_url": base_url,
+                "data_dir": str(data_dir),
+                "cognito_issuer": issuer,
+                "cognito_client_id": client_id,
+                "auth_path": str(auth_path) if auth_path else None,
+            }
+        )
+    )
+
+
+def stop_server(args: argparse.Namespace) -> None:
+    pid_file = Path(args.pid_file).expanduser().resolve()
+    pid = load_pid(pid_file)
+
+    if pid is None:
+        print(json.dumps({"status": "ok", "stopped": False, "reason": "pid-file-missing-or-empty", "pid_file": str(pid_file)}))
+        return
+
+    if not process_running(pid):
+        try:
+            pid_file.unlink(missing_ok=True)
+        except OSError:
+            pass
+        print(json.dumps({"status": "ok", "stopped": False, "reason": "process-not-running", "pid": pid, "pid_file": str(pid_file)}))
+        return
+
+    if not terminate_process(pid, force=False):
+        fail("db-sync server stop failed", pid=pid, signal="SIGTERM", pid_file=str(pid_file))
+    deadline = time.time() + args.shutdown_timeout_s
+    while time.time() < deadline:
+        if not process_running(pid):
+            pid_file.unlink(missing_ok=True)
+            print(json.dumps({"status": "ok", "stopped": True, "signal": "SIGTERM", "pid": pid, "pid_file": str(pid_file)}))
+            return
+        time.sleep(args.poll_interval_s)
+
+    if not terminate_process(pid, force=True):
+        fail("db-sync server force stop failed", pid=pid, signal="SIGKILL", pid_file=str(pid_file))
+    pid_file.unlink(missing_ok=True)
+    print(json.dumps({"status": "ok", "stopped": True, "signal": "SIGKILL", "pid": pid, "pid_file": str(pid_file)}))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Manage db-sync local server for cli-e2e sync tests")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    start = subparsers.add_parser("start", help="Start server and wait for /health")
+    start.add_argument("--repo-root", required=True)
+    start.add_argument("--pid-file", required=True)
+    start.add_argument("--log-file", required=True)
+    start.add_argument("--data-dir", required=True)
+    start.add_argument("--host", default="127.0.0.1")
+    start.add_argument("--port", type=int, default=8080)
+    start.add_argument("--startup-timeout-s", type=float, default=25.0)
+    start.add_argument("--poll-interval-s", type=float, default=0.5)
+    start.add_argument("--auth-path", default="~/logseq/auth.json")
+    start.add_argument("--cognito-issuer")
+    start.add_argument("--cognito-client-id")
+    start.add_argument("--cognito-jwks-url")
+
+    stop = subparsers.add_parser("stop", help="Stop server if running")
+    stop.add_argument("--pid-file", required=True)
+    stop.add_argument("--shutdown-timeout-s", type=float, default=10.0)
+    stop.add_argument("--poll-interval-s", type=float, default=0.25)
+
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    if args.command == "start":
+        start_server(args)
+    elif args.command == "stop":
+        stop_server(args)
+    else:
+        fail("unknown command", command=args.command)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/cli-e2e/scripts/prepare_sync_config.py b/cli-e2e/scripts/prepare_sync_config.py
new file mode 100644
index 0000000000..9b750f6ae6
--- /dev/null
+++ b/cli-e2e/scripts/prepare_sync_config.py
@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Prepare per-case CLI config for sync e2e tests."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def fail(message: str, **context: object) -> None:
+    payload = {"status": "error", "message": message}
+    if context:
+        payload["context"] = context
+    print(json.dumps(payload), file=sys.stderr)
+    raise SystemExit(1)
+
+
+def read_auth(auth_path: Path) -> dict:
+    if not auth_path.exists():
+        fail("sync auth file is missing", auth_path=str(auth_path), hint="Run `logseq login` first.")
+    try:
+        payload = json.loads(auth_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        fail("sync auth file is invalid JSON", auth_path=str(auth_path), detail=str(error))
+
+    has_token = any(payload.get(key) for key in ("refresh-token", "id-token", "access-token"))
+    if not has_token:
+        fail(
+            "sync auth file does not contain usable tokens",
+            auth_path=str(auth_path),
+            required_any_of=["refresh-token", "id-token", "access-token"],
+        )
+    return payload
+
+
+def write_config(output_path: Path, http_base: str, ws_url: str) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = "\n".join(
+        [
+            "{",
+            " :output-format :json",
+            f' :http-base "{http_base}"',
+            f' :ws-url "{ws_url}"',
+            "}",
+            "",
+        ]
+    )
+    output_path.write_text(payload, encoding="utf-8")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Prepare cli.edn for sync e2e")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--auth-path", default="~/logseq/auth.json")
+    parser.add_argument("--http-base", required=True)
+    parser.add_argument("--ws-url", required=True)
+    args = parser.parse_args()
+
+    auth_path = Path(args.auth_path).expanduser().resolve()
+    _auth = read_auth(auth_path)
+
+    output_path = Path(args.output).expanduser().resolve()
+    write_config(output_path, args.http_base, args.ws_url)
+
+    print(
+        json.dumps(
+            {
+                "status": "ok",
+                "auth_path": str(auth_path),
+                "config_path": str(output_path),
+                "http_base": args.http_base,
+                "ws_url": args.ws_url,
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/cli-e2e/scripts/random_bidirectional_block_ops.py b/cli-e2e/scripts/random_bidirectional_block_ops.py
new file mode 100644
index 0000000000..d68c1ef5cd
--- /dev/null
+++ b/cli-e2e/scripts/random_bidirectional_block_ops.py
@@ -0,0 +1,480 @@
+#!/usr/bin/env python3
+"""Run randomized bidirectional block operations on two synced graph peers."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import random
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List
+
+
+class CliCommandError(RuntimeError):
+    """Raised when a CLI command does not complete successfully."""
+
+    def __init__(self, message: str, *, context: Dict[str, Any]) -> None:
+        super().__init__(message)
+        self.context = context
+
+
+@dataclass(frozen=True)
+class ClientContext:
+    name: str
+    config: Path
+    root_dir: Path
+
+
+def fail(message: str, **context: object) -> None:
+    payload = {"status": "error", "message": message}
+    if context:
+        payload["context"] = context
+    print(json.dumps(payload), file=sys.stderr)
+    raise SystemExit(1)
+
+
+def run_cli_json(
+    *,
+    cli_path: Path,
+    graph: str,
+    client: ClientContext,
+    args: List[str],
+) -> Dict[str, Any]:
+    command = [
+        "node",
+        str(cli_path),
+        "--root-dir",
+        str(client.root_dir),
+        "--config",
+        str(client.config),
+        "--output",
+        "json",
+        *args,
+        "--graph",
+        graph,
+    ]
+    result = subprocess.run(command, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise CliCommandError(
+            "cli command exited with non-zero status",
+            context={
+                "client": client.name,
+                "command": command,
+                "exit": result.returncode,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+            },
+        )
+
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise CliCommandError(
+            "cli command did not return valid json",
+            context={
+                "client": client.name,
+                "command": command,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+                "detail": str(error),
+            },
+        ) from error
+
+    if payload.get("status") != "ok":
+        raise CliCommandError(
+            "cli command returned non-ok status",
+            context={
+                "client": client.name,
+                "command": command,
+                "payload": payload,
+            },
+        )
+    return payload
+
+
+def page_block_ids(
+    *,
+    cli_path: Path,
+    graph: str,
+    client: ClientContext,
+    page_title: str,
+) -> List[int]:
+    query = (
+        "[:find [?e ...] "
+        ":where "
+        f"[?p :block/title {json.dumps(page_title)}] "
+        "[?e :block/page ?p] "
+        "[?e :block/uuid]]"
+    )
+    payload = run_cli_json(
+        cli_path=cli_path,
+        graph=graph,
+        client=client,
+        args=["query", "--query", query],
+    )
+    result = (payload.get("data") or {}).get("result")
+    if not isinstance(result, list):
+        return []
+    output: List[int] = []
+    for item in result:
+        try:
+            output.append(int(item))
+        except (TypeError, ValueError):
+            continue
+    return output
+
+
+def upsert_page(
+    *,
+    cli_path: Path,
+    graph: str,
+    client: ClientContext,
+    page_title: str,
+) -> None:
+    run_cli_json(
+        cli_path=cli_path,
+        graph=graph,
+        client=client,
+        args=["upsert", "page", "--page", page_title],
+    )
+
+
+def create_block(
+    *,
+    cli_path: Path,
+    graph: str,
+    client: ClientContext,
+    page_title: str,
+    content: str,
+    ids: List[int],
+    rng: random.Random,
+) -> None:
+    if ids and rng.random() < 0.6:
+        target_id = str(rng.choice(ids))
+        run_cli_json(
+            cli_path=cli_path,
+            graph=graph,
+            client=client,
+            args=[
+                "upsert",
+                "block",
+                "--target-id",
+                target_id,
+                "--pos",
+                "first-child",
+                "--content",
+                content,
+            ],
+        )
+        return
+
+    run_cli_json(
+        cli_path=cli_path,
+        graph=graph,
+        client=client,
+        args=[
+            "upsert",
+            "block",
+            "--target-page",
+            page_title,
+            "--content",
+            content,
+        ],
+    )
+
+
+def move_block(
+    *,
+    cli_path: Path,
+    graph: str,
+    client: ClientContext,
+    page_title: str,
+    ids: List[int],
+    rng: random.Random,
+) -> bool:
+    if not ids:
+        return False
+    source_id = str(rng.choice(ids))
+    run_cli_json(
+        cli_path=cli_path,
+        graph=graph,
+        client=client,
+        args=[
+            "upsert",
+            "block",
+            "--id",
+            source_id,
+            "--target-page",
+            page_title,
+            "--pos",
+            "last-child",
+        ],
+    )
+    return True
+
+
+def delete_block(
+    *,
+    cli_path: Path,
+    graph: str,
+    client: ClientContext,
+    ids: List[int],
+    rng: random.Random,
+) -> bool:
+    if len(ids) <= 2:
+        return False
+    source_id = str(rng.choice(ids))
+    run_cli_json(
+        cli_path=cli_path,
+        graph=graph,
+        client=client,
+        args=["remove", "block", "--id", source_id],
+    )
+    return True
+
+
+def feasible(operation: str, ids: List[int]) -> bool:
+    if operation == "create":
+        return True
+    if operation == "move":
+        return len(ids) >= 1
+    if operation == "delete":
+        return len(ids) > 2
+    return False
+
+
+def choose_operation(op_counts: Dict[str, int], ids: List[int], rng: random.Random) -> str:
+    for required in ("create", "move", "delete"):
+        if op_counts.get(required, 0) == 0 and feasible(required, ids):
+            return required
+
+    candidates = ["create", "create", "move"]
+    if feasible("delete", ids):
+        candidates.append("delete")
+    if feasible("move", ids):
+        candidates.append("move")
+    return rng.choice(candidates)
+
+
+def apply_operation(
+    *,
+    cli_path: Path,
+    graph: str,
+    client: ClientContext,
+    page_title: str,
+    op_counts: Dict[str, int],
+    round_index: int,
+    rng: random.Random,
+) -> None:
+    last_error: Dict[str, Any] | None = None
+    for attempt in range(1, 7):
+        ids = page_block_ids(
+            cli_path=cli_path,
+            graph=graph,
+            client=client,
+            page_title=page_title,
+        )
+        operation = choose_operation(op_counts, ids, rng)
+        content = f"{client.name}-rnd-{round_index:03d}-{rng.randint(100000, 999999)}"
+
+        try:
+            if operation == "create":
+                create_block(
+                    cli_path=cli_path,
+                    graph=graph,
+                    client=client,
+                    page_title=page_title,
+                    content=content,
+                    ids=ids,
+                    rng=rng,
+                )
+                op_counts["create"] = op_counts.get("create", 0) + 1
+                return
+
+            if operation == "move":
+                moved = move_block(
+                    cli_path=cli_path,
+                    graph=graph,
+                    client=client,
+                    page_title=page_title,
+                    ids=ids,
+                    rng=rng,
+                )
+                if moved:
+                    op_counts["move"] = op_counts.get("move", 0) + 1
+                    return
+                continue
+
+            if operation == "delete":
+                deleted = delete_block(
+                    cli_path=cli_path,
+                    graph=graph,
+                    client=client,
+                    ids=ids,
+                    rng=rng,
+                )
+                if deleted:
+                    op_counts["delete"] = op_counts.get("delete", 0) + 1
+                    return
+                continue
+        except CliCommandError as error:
+            last_error = {
+                "attempt": attempt,
+                "operation": operation,
+                "context": error.context,
+            }
+            continue
+
+    fail(
+        "failed to apply random operation after retries",
+        client=client.name,
+        round_index=round_index,
+        last_error=last_error,
+    )
+
+
+def ensure_non_empty_page(
+    *,
+    cli_path: Path,
+    graph: str,
+    client: ClientContext,
+    page_title: str,
+    rng: random.Random,
+) -> None:
+    ids = page_block_ids(
+        cli_path=cli_path,
+        graph=graph,
+        client=client,
+        page_title=page_title,
+    )
+    if ids:
+        return
+    content = f"{client.name}-reseed-{rng.randint(100000, 999999)}"
+    create_block(
+        cli_path=cli_path,
+        graph=graph,
+        client=client,
+        page_title=page_title,
+        content=content,
+        ids=[],
+        rng=rng,
+    )
+
+
+PROFILE_DEFAULT_ROUNDS = {
+    "default": 40,
+    "high-stress": 100,
+}
+
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run randomized bidirectional block operations on two synced graph clients"
+    )
+    parser.add_argument("--cli", required=True, help="Path to static/logseq-cli.js")
+    parser.add_argument("--graph", required=True)
+    parser.add_argument("--config-a", required=True)
+    parser.add_argument("--root-dir-a", required=True)
+    parser.add_argument("--config-b", required=True)
+    parser.add_argument("--root-dir-b", required=True)
+    parser.add_argument("--page", required=True)
+    parser.add_argument(
+        "--profile",
+        choices=sorted(PROFILE_DEFAULT_ROUNDS.keys()),
+        default="default",
+        help="Execution profile controlling default stress level",
+    )
+    parser.add_argument("--rounds-per-client", type=int, default=None)
+    parser.add_argument("--seed", type=int, default=424242)
+    args = parser.parse_args()
+    if args.rounds_per_client is None:
+        args.rounds_per_client = PROFILE_DEFAULT_ROUNDS[args.profile]
+    return args
+
+
+def main() -> None:
+    args = parse_args()
+    cli_path = Path(args.cli).expanduser().resolve()
+    if not cli_path.exists():
+        fail("cli path does not exist", cli=str(cli_path))
+
+    rng = random.Random(args.seed)
+    client_a = ClientContext(
+        name="a",
+        config=Path(args.config_a).expanduser().resolve(),
+        root_dir=Path(args.root_dir_a).expanduser().resolve(),
+    )
+    client_b = ClientContext(
+        name="b",
+        config=Path(args.config_b).expanduser().resolve(),
+        root_dir=Path(args.root_dir_b).expanduser().resolve(),
+    )
+    clients = [client_a, client_b]
+
+    for client in clients:
+        upsert_page(
+            cli_path=cli_path,
+            graph=args.graph,
+            client=client,
+            page_title=args.page,
+        )
+
+    # Seed both peers so move/delete have available targets from the beginning.
+    for seed_round in range(3):
+        for client in clients:
+            create_block(
+                cli_path=cli_path,
+                graph=args.graph,
+                client=client,
+                page_title=args.page,
+                content=f"{client.name}-seed-{seed_round}-{rng.randint(100000, 999999)}",
+                ids=[],
+                rng=rng,
+            )
+
+    op_stats: Dict[str, Dict[str, int]] = {
+        client.name: {"create": 0, "move": 0, "delete": 0} for client in clients
+    }
+
+    for round_index in range(args.rounds_per_client):
+        for client in clients:
+            apply_operation(
+                cli_path=cli_path,
+                graph=args.graph,
+                client=client,
+                page_title=args.page,
+                op_counts=op_stats[client.name],
+                round_index=round_index,
+                rng=rng,
+            )
+
+    for client in clients:
+        ensure_non_empty_page(
+            cli_path=cli_path,
+            graph=args.graph,
+            client=client,
+            page_title=args.page,
+            rng=rng,
+        )
+
+    print(
+        json.dumps(
+            {
+                "status": "ok",
+                "graph": args.graph,
+                "page": args.page,
+                "rounds_per_client": args.rounds_per_client,
+                "seed": args.seed,
+                "stats": op_stats,
+                "total_operations": args.rounds_per_client * len(clients),
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/cli-e2e/scripts/wait_sync_status.py b/cli-e2e/scripts/wait_sync_status.py
new file mode 100644
index 0000000000..0c2804112d
--- /dev/null
+++ b/cli-e2e/scripts/wait_sync_status.py
@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+"""Poll `logseq sync status` until queues settle and tx converges."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict
+
+
+def fail(message: str, **context: object) -> None:
+    payload = {"status": "error", "message": message}
+    if context:
+        payload["context"] = context
+    print(json.dumps(payload), file=sys.stderr)
+    raise SystemExit(1)
+
+
+def parse_int(value: Any) -> int:
+    if value is None:
+        return 0
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, (int, float)):
+        return int(value)
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return 0
+
+
+def status_command(args: argparse.Namespace) -> list[str]:
+    existing = getattr(args, "status_command", None)
+    if existing is not None:
+        return existing
+
+    command = [
+        "node",
+        str(Path(args.cli).expanduser().resolve()),
+        "--root-dir",
+        str(Path(args.root_dir).expanduser().resolve()),
+        "--config",
+        str(Path(args.config).expanduser().resolve()),
+        "--output",
+        "json",
+        "sync",
+        "status",
+        "--graph",
+        args.graph,
+    ]
+    args.status_command = command
+    return command
+
+
+
+def run_status(args: argparse.Namespace) -> Dict[str, Any]:
+    command = status_command(args)
+
+    result = subprocess.run(command, capture_output=True, text=True)
+    if result.returncode != 0:
+        fail(
+            "sync status command failed",
+            command=command,
+            exit=result.returncode,
+            stdout=result.stdout,
+            stderr=result.stderr,
+        )
+
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        fail(
+            "sync status command did not return valid JSON",
+            command=command,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            detail=str(error),
+        )
+
+    if payload.get("status") != "ok":
+        fail("sync status returned non-ok status", payload=payload)
+
+    return payload
+
+
+def pending_counts(status_payload: Dict[str, Any]) -> Dict[str, int]:
+    data = status_payload.get("data") or {}
+    return {
+        "pending-local": parse_int(data.get("pending-local")),
+        "pending-asset": parse_int(data.get("pending-asset")),
+        "pending-server": parse_int(data.get("pending-server")),
+    }
+
+
+def all_settled(counts: Dict[str, int]) -> bool:
+    required_keys = ("pending-local", "pending-asset", "pending-server")
+    return all(counts.get(key, 0) == 0 for key in required_keys)
+
+
+def parse_required_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, str) and value.strip() == "":
+        return None
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, (int, float)):
+        return int(value)
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return None
+
+
+def tx_sync_status(status_payload: Dict[str, Any]) -> Dict[str, Any]:
+    data = status_payload.get("data") or {}
+    local_tx = parse_required_int(data.get("local-tx"))
+    remote_tx = parse_required_int(data.get("remote-tx"))
+    synced = (
+        local_tx is not None
+        and remote_tx is not None
+        and local_tx == remote_tx
+    )
+    return {
+        "local-tx": local_tx,
+        "remote-tx": remote_tx,
+        "synced": synced,
+    }
+
+
+def tx_deltas(
+    tx_status: Dict[str, Any],
+    baseline_tx: Dict[str, Any],
+) -> Dict[str, int | None]:
+    local_tx = tx_status.get("local-tx")
+    remote_tx = tx_status.get("remote-tx")
+    baseline_local_tx = baseline_tx.get("local-tx")
+    baseline_remote_tx = baseline_tx.get("remote-tx")
+
+    local_tx_delta = (
+        None
+        if local_tx is None or baseline_local_tx is None
+        else local_tx - baseline_local_tx
+    )
+    remote_tx_delta = (
+        None
+        if remote_tx is None or baseline_remote_tx is None
+        else remote_tx - baseline_remote_tx
+    )
+
+    return {
+        "local-tx-delta": local_tx_delta,
+        "remote-tx-delta": remote_tx_delta,
+    }
+
+
+def min_tx_delta_reached(
+    tx_status: Dict[str, Any],
+    baseline_tx: Dict[str, Any],
+    min_tx_delta: int,
+) -> bool:
+    if min_tx_delta <= 0:
+        return True
+
+    deltas = tx_deltas(tx_status, baseline_tx)
+    local_tx_delta = deltas.get("local-tx-delta")
+    remote_tx_delta = deltas.get("remote-tx-delta")
+    if local_tx_delta is None or remote_tx_delta is None:
+        return False
+
+    return local_tx_delta >= min_tx_delta and remote_tx_delta >= min_tx_delta
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Wait for sync status to settle"
+    )
+    parser.add_argument(
+        "--cli",
+        required=True,
+        help="Path to static/logseq-cli.js",
+    )
+    parser.add_argument("--root-dir", required=True)
+    parser.add_argument("--config", required=True)
+    parser.add_argument("--graph", required=True)
+    parser.add_argument("--timeout-s", type=float, default=120.0)
+    parser.add_argument("--interval-s", type=float, default=1.0)
+    parser.add_argument(
+        "--min-tx-delta",
+        type=int,
+        default=0,
+        help=(
+            "Require synced tx delta to be >= this value: "
+            "(new-tx - old-tx) >= min-tx-delta "
+            "(default: 0)"
+        ),
+    )
+    parser.add_argument(
+        "--baseline-tx",
+        type=int,
+        default=None,
+        help=(
+            "Optional explicit baseline tx used as old-tx for both local "
+            "and remote; if omitted, first observed tx values "
+            "are used"
+        ),
+    )
+    args = parser.parse_args()
+
+    if args.min_tx_delta < 0:
+        invalid_min_tx_delta = args.min_tx_delta
+        fail(
+            "min-tx-delta must be non-negative",
+            min_tx_delta=invalid_min_tx_delta,
+        )
+
+    started = time.time()
+    deadline = started + args.timeout_s
+    last_payload: Dict[str, Any] | None = None
+    baseline_tx: Dict[str, Any] | None = (
+        {
+            "local-tx": args.baseline_tx,
+            "remote-tx": args.baseline_tx,
+        }
+        if args.baseline_tx is not None
+        else None
+    )
+
+    while time.time() < deadline:
+        payload = run_status(args)
+        last_payload = payload
+        data = payload.get("data") or {}
+        last_error = data.get("last-error")
+
+        if last_error is not None:
+            fail("sync status reports last-error", payload=payload)
+
+        counts = pending_counts(payload)
+        tx_status = tx_sync_status(payload)
+        if baseline_tx is None:
+            baseline_tx = {
+                "local-tx": tx_status.get("local-tx"),
+                "remote-tx": tx_status.get("remote-tx"),
+            }
+
+        deltas = tx_deltas(tx_status, baseline_tx)
+        if (
+            all_settled(counts)
+            and tx_status["synced"]
+            and min_tx_delta_reached(
+                tx_status,
+                baseline_tx,
+                args.min_tx_delta,
+            )
+        ):
+            print(
+                json.dumps(
+                    {
+                        "status": "ok",
+                        "elapsed_s": round(time.time() - started, 3),
+                        "counts": counts,
+                        "tx": {
+                            "local-tx": tx_status["local-tx"],
+                            "remote-tx": tx_status["remote-tx"],
+                        },
+                        "tx-delta": deltas,
+                        "baseline-tx": baseline_tx,
+                        "min_tx_delta": args.min_tx_delta,
+                        "payload": payload,
+                    }
+                )
+            )
+            return
+
+        time.sleep(max(args.interval_s, 0.0))
+
+    last_tx_status = tx_sync_status(last_payload or {})
+    last_baseline_tx = baseline_tx or {"local-tx": None, "remote-tx": None}
+    fail(
+        (
+            "sync status polling timed out before queues settled, tx synced, "
+            "and min tx delta reached"
+        ),
+        timeout_s=args.timeout_s,
+        min_tx_delta=args.min_tx_delta,
+        baseline_tx=last_baseline_tx,
+        last_payload=last_payload,
+        last_counts=pending_counts(last_payload or {}),
+        last_tx=last_tx_status,
+        last_tx_delta=tx_deltas(
+            last_tx_status,
+            last_baseline_tx,
+        ),
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/cli-e2e/spec/non_sync_cases.edn b/cli-e2e/spec/non_sync_cases.edn
new file mode 100644
index 0000000000..130892edf0
--- /dev/null
+++ b/cli-e2e/spec/non_sync_cases.edn
@@ -0,0 +1,1100 @@
+{:templates
+ {:non-sync/graph-json-env
+  {:setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"],
+   :cleanup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{graph-arg}}"]},
+  :non-sync/graph-json-secondary-env
+  {:extends :non-sync/graph-json-env,
+   :vars
+   {:secondary-graph "graph-two", :secondary-graph-arg "graph-two"},
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{secondary-graph-arg}} >/dev/null"],
+   :cleanup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{secondary-graph-arg}}"]},
+  :non-sync/source-graph-json-env
+  {:extends :non-sync/graph-json-secondary-env,
+   :vars
+   {:secondary-graph "source-graph",
+    :secondary-graph-arg "source-graph"}},
+  :non-sync/example-command
+  {:tags [:example],
+   :covers {:options {:global ["--output"]}},
+   :expect {:exit 0},
+   :vars {:example-output "json"},
+   :cmds
+   ["{{cli}} --output {{example-output}} example {{example-selector}}"]},
+  :non-sync/example-human-command
+  {:extends :non-sync/example-command,
+   :vars {:example-output "human"}},
+  :non-sync/example-json-command
+  {:extends :non-sync/example-command,
+   :expect {:stdout-json-paths {[:status] "ok"}}},
+  :non-sync/example-edn-command
+  {:extends :non-sync/example-command,
+   :vars {:example-output "edn"},
+   :expect {:stdout-edn-paths {[:status] :ok}}},
+  :non-sync/completion-command
+  {:tags [:completion],
+   :covers {:commands ["completion"]},
+   :expect {:exit 0},
+   :cmds ["{{cli}} completion {{completion-selector}}"]}},
+ :cases
+ [{:id "global-help",
+   :cmds ["{{cli}} --help"],
+   :expect
+   {:exit 0,
+    :stdout-contains
+    ["Usage: logseq <command> [options]" "graph create" "completion"]},
+   :covers {:options {:global ["--help"]}},
+   :tags [:global :smoke]}
+  {:id "global-version",
+   :cmds ["{{cli}} --version"],
+   :expect {:exit 0, :stdout-contains ["Build time:" "Revision:"]},
+   :covers {:options {:global ["--version"]}},
+   :tags [:global :smoke]}
+  {:id "verbose-graph-list-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json --verbose graph list"],
+   :expect
+   {:exit 0,
+    :stderr-contains [":cli/parsed-options"],
+    :stdout-json-paths {[:status] "ok"}},
+   :covers
+   {:commands ["graph list"],
+    :options
+    {:global ["--config" "--root-dir" "--output" "--verbose"]}},
+   :tags [:global :graph]}
+  {:id "graph-create-and-info-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph info --graph {{graph-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok", [:data :graph] "{{graph}}"}},
+   :covers
+   {:commands ["graph create" "graph info"],
+    :options {:global ["--config" "--graph" "--root-dir" "--output"]}},
+   :cleanup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{graph-arg}}"],
+   :tags [:graph :smoke]}
+  {:id "graph-list-human",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human graph list"],
+   :expect {:exit 0, :stdout-contains ["{{graph}}"]},
+   :covers
+   {:commands ["graph list"],
+    :options {:global ["--config" "--root-dir" "--output"]}},
+   :tags [:graph],
+   :extends :non-sync/graph-json-env}
+  {:id "graph-list-edn",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output edn graph list"],
+   :expect
+   {:exit 0,
+    :stdout-edn-paths {[:status] :ok, [:data :graphs] ["{{graph}}"]}},
+   :covers
+   {:commands ["graph list"],
+    :options {:global ["--config" "--root-dir" "--output"]}},
+   :tags [:graph],
+   :extends :non-sync/graph-json-env}
+  {:tags [:graph],
+   :extends :non-sync/graph-json-secondary-env,
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok",
+     [:data :message] "switched to {{secondary-graph}}"}},
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph switch --graph {{secondary-graph-arg}}"],
+   :id "graph-switch-json",
+   :covers
+   {:commands ["graph switch"],
+    :options {:global ["--config" "--graph" "--root-dir" "--output"]}}}
+  {:id "graph-validate-fix-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph validate --graph {{graph-arg}} --fix"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok", [:data :result :errors] nil}},
+   :covers
+   {:commands ["graph validate"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :graph ["--fix"]}},
+   :tags [:graph],
+   :extends :non-sync/graph-json-env}
+  {:id "graph-export-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page ExportHome >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph export --graph {{graph-arg}} --type edn --file {{export-path-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok"},
+    :stdout-contains ["{{export-path}}"]},
+   :covers
+   {:commands ["graph export"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :graph ["--type" "--file"]}},
+   :tags [:graph],
+   :extends :non-sync/graph-json-env}
+  {:tags [:graph],
+   :extends :non-sync/source-graph-json-env,
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok"},
+    :stdout-contains ["Imported edn from" "{{export-path}}"]},
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{secondary-graph-arg}} --page ImportSeed >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph export --graph {{secondary-graph-arg}} --type edn --file {{export-path-arg}} >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph import --graph {{graph-arg}} --type edn --input {{export-path-arg}}"],
+   :id "graph-import-json",
+   :covers
+   {:commands ["graph import"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :graph ["--type" "--input"]}}}
+  {:tags [:graph],
+   :extends :non-sync/graph-json-env,
+   :expect {:exit 0, :stdout-json-paths {[:status] "ok"}},
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page BackupSeed >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph backup create --graph {{graph-arg}} --name nightly >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph backup list"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph backup restore --src \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph backup list | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"backups\"][0][\"name\"])')\" --dst {{restore-graph-arg}} >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph backup remove --src \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph backup list | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"backups\"][0][\"name\"])')\""],
+   :id "graph-backup-lifecycle-json",
+   :covers
+   {:commands
+    ["graph backup create"
+     "graph backup list"
+     "graph backup restore"
+     "graph backup remove"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :graph ["--name" "--src" "--dst"]}},
+   :vars
+   {:restore-graph "backup-restore",
+    :restore-graph-arg "backup-restore"},
+   :cleanup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{restore-graph-arg}}"]}
+  {:id "page-upsert-and-list-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list page --graph {{graph-arg}} --fields title,id --sort updated-at --order desc --limit 1"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :items 0 :block/title] "Home"}},
+   :covers
+   {:commands ["upsert page" "list page"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--page"],
+     :list ["--fields" "--limit" "--sort" "--order"]}},
+   :tags [:upsert :list :smoke],
+   :extends :non-sync/graph-json-env}
+  {:id "task-upsert-and-list-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert task --graph {{graph-arg}} --page TaskHome --status todo --priority high --scheduled '2026-02-10T08:00:00.000Z' --deadline '2026-02-12T18:00:00.000Z' >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list task --graph {{graph-arg}} --status todo --priority high --content task --fields id,title,status,priority,scheduled,deadline --sort updated-at --order desc --limit 1"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok",
+     [:data :items 0 :block/title] "TaskHome",
+     [:data :items 0 :logseq.property/status]
+     "logseq.property/status.todo",
+     [:data :items 0 :logseq.property/priority]
+     "logseq.property/priority.high",
+     [:data :items 0 :logseq.property/scheduled] 1770710400000,
+     [:data :items 0 :logseq.property/deadline] 1770919200000}},
+   :covers
+   {:commands ["upsert task" "list task"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert
+     ["--page" "--status" "--priority" "--scheduled" "--deadline"],
+     :list
+     ["--status"
+      "--priority"
+      "--content"
+      "--fields"
+      "--limit"
+      "--sort"
+      "--order"]}},
+   :tags [:upsert :list :smoke],
+   :extends :non-sync/graph-json-env}
+  {:id "task-upsert-clear-properties-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert task --graph {{graph-arg}} --page TaskHome --status todo --priority high --scheduled '2026-02-10T08:00:00.000Z' --deadline '2026-02-12T18:00:00.000Z' >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert task --graph {{graph-arg}} --page TaskHome --no-status --no-priority --no-scheduled --no-deadline >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list task --graph {{graph-arg}} --content taskhome --fields id,title,status,priority,scheduled,deadline --sort updated-at --order desc --limit 1"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :items 0 :block/title] "TaskHome"},
+    :stdout-not-contains
+    ["logseq.property/priority.high"
+     "2026-02-10T08:00:00.000Z"
+     "2026-02-12T18:00:00.000Z"]},
+   :covers
+   {:commands ["upsert task" "list task"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert
+     ["--page"
+      "--no-status"
+      "--no-priority"
+      "--no-scheduled"
+      "--no-deadline"],
+     :list ["--content" "--fields" "--limit" "--sort" "--order"]}},
+   :tags [:upsert :list],
+   :extends :non-sync/graph-json-env}
+  {:id "task-upsert-set-clear-conflict-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert task --graph {{graph-arg}} --page TaskHome --status todo --no-status"],
+   :expect
+   {:exit 1,
+    :stdout-contains
+    ["invalid-options"
+     "--status and --no-status are mutually exclusive"]},
+   :covers
+   {:commands ["upsert task"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--page" "--status" "--no-status"]}},
+   :tags [:upsert],
+   :extends :non-sync/graph-json-env}
+  {:id "page-upsert-invalid-update-properties-atomic-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert tag --graph {{graph-arg}} --name AtomicTag >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page AtomicPage --update-tags '[\"AtomicTag\"]' --update-properties '{:missing-prop \"value\"}'"],
+   :expect
+   {:exit 1,
+    :stdout-json-paths
+    {[:status] "error",
+     [:error :code] "property-not-found",
+     [:error :option] "--update-properties",
+     [:error :phase] "resolve-options"},
+    :stdout-contains ["missing-prop"]},
+   :covers
+   {:commands ["upsert page"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--page" "--update-tags" "--update-properties"]}},
+   :tags [:upsert],
+   :extends :non-sync/graph-json-env}
+  {:id "node-list-by-tags-properties-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert tag --graph {{graph-arg}} --name NodeTag >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert property --graph {{graph-arg}} --name node-prop >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page NodeHome --update-tags '[\"NodeTag\"]' --update-properties '{:node-prop \"v\"}' >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list node --graph {{graph-arg}} --tags NodeTag --properties node-prop --fields id,title,type --sort updated-at --order desc --limit 20"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok",
+     [:data :items 0 :block/title] "NodeHome",
+     [:data :items 0 :node/type] "page"}},
+   :covers
+   {:commands
+    ["upsert tag" "upsert property" "upsert page" "list node"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--name" "--page" "--update-tags" "--update-properties"],
+     :list
+     ["--tags"
+      "--properties"
+      "--fields"
+      "--limit"
+      "--sort"
+      "--order"]}},
+   :tags [:upsert :list],
+   :extends :non-sync/graph-json-env}
+  {:id "asset-upsert-and-list-json",
+   :setup ["printf 'asset-content' > {{export-path-arg}}.png"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert asset --graph {{graph-arg}} --path {{export-path-arg}}.png --content 'Asset One' --target-page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list asset --graph {{graph-arg}} --fields id,title,asset-type,size --sort updated-at --order desc --limit 1"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok",
+     [:data :items 0 :block/title] "Asset One",
+     [:data :items 0 :logseq.property.asset/type] "png",
+     [:data :items 0 :logseq.property.asset/size] 13}},
+   :covers
+   {:commands ["upsert asset" "list asset"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--path" "--content" "--target-page"],
+     :list ["--fields" "--limit" "--sort" "--order"]}},
+   :tags [:upsert :list],
+   :extends :non-sync/graph-json-env}
+  {:id "asset-upsert-update-json",
+   :setup
+   ["printf 'asset-content' > {{export-path-arg}}.png"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert asset --graph {{graph-arg}} --path {{export-path-arg}}.png --content 'Asset Original' --target-page Home >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert asset --graph {{graph-arg}} --id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?e . :where [?e :block/title \"Asset Original\"]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\" --content 'Asset Updated' >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list asset --graph {{graph-arg}} --fields id,title --sort updated-at --order desc --limit 1"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :items 0 :block/title] "Asset Updated"}},
+   :covers
+   {:commands ["upsert asset" "list asset"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--id" "--content"],
+     :list ["--fields" "--limit" "--sort" "--order"]}},
+   :tags [:upsert :list],
+   :extends :non-sync/graph-json-env}
+  {:id "block-upsert-and-show-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Alpha block' >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json show --graph {{graph-arg}} --page Home --level 2 --linked-references false"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok",
+     [:data :root :block/children 0 :block/title] "Alpha block"}},
+   :covers
+   {:commands ["upsert block" "show"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--target-page" "--content"],
+     :show ["--page" "--level" "--linked-references"]}},
+   :tags [:upsert :show :smoke],
+   :extends :non-sync/graph-json-env}
+  {:id "tag-upsert-and-list-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert tag --graph {{graph-arg}} --name TagOne >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list tag --graph {{graph-arg}} --with-properties --sort updated-at --order desc --limit 1"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :items 0 :block/title] "TagOne"}},
+   :covers
+   {:commands ["upsert tag" "list tag"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--name"],
+     :list ["--with-properties" "--sort" "--order" "--limit"]}},
+   :tags [:upsert :list],
+   :extends :non-sync/graph-json-env}
+  {:id "property-upsert-and-list-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert property --graph {{graph-arg}} --name score --type number --cardinality one >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list property --graph {{graph-arg}} --with-type --sort updated-at --order desc --limit 1"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok",
+     [:data :items 0 :block/title] "score",
+     [:data :items 0 :logseq.property/type] "number",
+     [:data :items 0 :db/cardinality] "db.cardinality/one"}},
+   :covers
+   {:commands ["upsert property" "list property"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--name" "--type" "--cardinality"],
+     :list ["--with-type" "--sort" "--order" "--limit"]}},
+   :tags [:upsert :list],
+   :extends :non-sync/graph-json-env}
+  {:id "list-tag-expand-offset-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert tag --graph {{graph-arg}} --name TagA >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert tag --graph {{graph-arg}} --name TagB >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list tag --graph {{graph-arg}} --expand --with-extends --sort updated-at --order desc --offset 0 --limit 20"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok"},
+    :stdout-contains ["TagA" "TagB"]},
+   :covers
+   {:commands ["list tag"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :list
+     ["--expand"
+      "--with-extends"
+      "--offset"
+      "--sort"
+      "--order"
+      "--limit"]}},
+   :tags [:list],
+   :extends :non-sync/graph-json-env}
+  {:id "list-property-classes-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert property --graph {{graph-arg}} --name alpha --type number --cardinality one >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert property --graph {{graph-arg}} --name beta --type number --cardinality one >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list property --graph {{graph-arg}} --with-classes --sort updated-at --order desc --offset 0 --limit 20"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok"},
+    :stdout-contains ["alpha" "beta"]},
+   :covers
+   {:commands ["list property"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :list
+     ["--with-classes" "--sort" "--order" "--offset" "--limit"]}},
+   :tags [:list],
+   :extends :non-sync/graph-json-env}
+  {:id "list-page-journal-only-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list page --graph {{graph-arg}} --journal-only"],
+   :expect
+   {:exit 0, :stdout-json-paths {[:status] "ok", [:data :items] []}},
+   :covers
+   {:commands ["list page"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :list ["--journal-only"]}},
+   :tags [:list],
+   :extends :non-sync/graph-json-env}
+  {:id "search-block-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SearchBlockTarget >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} search block --content blocktarget --output json --graph {{graph-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok"},
+    :stdout-contains ["SearchBlockTarget"]},
+   :covers
+   {:commands ["search block"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :search ["--content"]}},
+   :tags [:search :smoke],
+   :extends :non-sync/graph-json-env}
+  {:id "search-page-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SearchPageTarget >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json search page --content target --graph {{graph-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok"},
+    :stdout-contains ["SearchPageTarget"]},
+   :covers
+   {:commands ["search page"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :search ["--content"]}},
+   :tags [:search],
+   :extends :non-sync/graph-json-env}
+  {:id "search-property-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert property --graph {{graph-arg}} --name SearchOwner --type default >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json search property --content owner --graph {{graph-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok"},
+    :stdout-contains ["SearchOwner"]},
+   :covers
+   {:commands ["search property"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :search ["--content"]}},
+   :tags [:search],
+   :extends :non-sync/graph-json-env}
+  {:id "search-tag-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert tag --graph {{graph-arg}} --name SearchTagTarget >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json search tag --content target --graph {{graph-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok"},
+    :stdout-contains ["SearchTagTarget"]},
+   :covers
+   {:commands ["search tag"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :search ["--content"]}},
+   :tags [:search],
+   :extends :non-sync/graph-json-env}
+  {:id "block-upsert-blocks-file-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Anchor block' >/dev/null"
+    "printf '[{:block/title \"Inserted from file\"}]' > {{export-path-arg}}"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human upsert block --graph {{graph-arg}} --target-id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?e . :where [?e :block/title \"Anchor block\"]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\" --blocks-file {{export-path-arg}} --pos sibling >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human show --graph {{graph-arg}} --page Home"],
+   :expect {:exit 0, :stdout-contains ["Inserted from file"]},
+   :covers
+   {:commands ["upsert block"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--blocks-file" "--target-id" "--pos"]}},
+   :tags [:upsert],
+   :extends :non-sync/graph-json-env}
+  {:id "block-upsert-target-uuid-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Anchor block' >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human upsert block --graph {{graph-arg}} --target-uuid \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?uuid . :where [?e :block/title \"Anchor block\"] [?e :block/uuid ?uuid]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\" --content 'Inserted by uuid' >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human show --graph {{graph-arg}} --page Home"],
+   :expect {:exit 0, :stdout-contains ["Inserted by uuid"]},
+   :covers
+   {:commands ["upsert block"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--target-uuid"]}},
+   :tags [:upsert],
+   :extends :non-sync/graph-json-env}
+  {:id "block-upsert-update-id-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Alpha block' >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human upsert block --graph {{graph-arg}} --id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?e . :where [?e :block/title \"Alpha block\"]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\" --content 'Updated by id' --update-tags '[:logseq.class/Quote-block]' --update-properties '{:logseq.property/publishing-public? true}' >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human show --graph {{graph-arg}} --page Home"],
+   :expect {:exit 0, :stdout-contains ["Updated by id"]},
+   :covers
+   {:commands ["upsert block"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--id" "--update-tags" "--update-properties"]}},
+   :tags [:upsert],
+   :extends :non-sync/graph-json-env}
+  {:id "block-upsert-update-id-custom-many-property-json",
+   :vars {:prop-name "Reproducible steps"},
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert property --graph {{graph-arg}} --name '{{prop-name}}' --type default --cardinality many --public true >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Alpha block' >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?e . :where [?e :block/title \"Alpha block\"]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\" --update-properties '{\"{{prop-name}}\" [\"Step 1\" \"Step 2\" \"Step 3\"]}' >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human show --graph {{graph-arg}} --id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?e . :where [?e :block/title \"Alpha block\"]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\""],
+   :expect
+   {:exit 0,
+    :stdout-contains ["{{prop-name}}" "Step 1" "Step 2" "Step 3"]},
+   :covers
+   {:commands ["upsert block" "show"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert
+     ["--id" "--target-page" "--content" "--update-properties"],
+     :show ["--id"]}},
+   :tags [:upsert :show]}
+  {:id "block-upsert-update-uuid-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Alpha block' --update-tags '[:logseq.class/Quote-block]' --update-properties '{:logseq.property/publishing-public? true}' >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human upsert block --graph {{graph-arg}} --uuid \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?uuid . :where [?e :block/title \"Alpha block\"] [?e :block/uuid ?uuid]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\" --content 'Updated by uuid' --remove-tags '[:logseq.class/Quote-block]' --remove-properties '[:logseq.property/publishing-public?]' >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human show --graph {{graph-arg}} --page Home"],
+   :expect {:exit 0, :stdout-contains ["Updated by uuid"]},
+   :covers
+   {:commands ["upsert block"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--uuid" "--remove-tags" "--remove-properties"]}},
+   :tags [:upsert],
+   :extends :non-sync/graph-json-env}
+  {:id "property-upsert-update-id-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert property --graph {{graph-arg}} --name score --type number --cardinality one >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert property --graph {{graph-arg}} --id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list property --graph {{graph-arg}} --fields title,id --limit 200 --sort updated-at --order desc | python3 -c 'import sys,json; print(next(item[\"db/id\"] for item in json.load(sys.stdin)[\"data\"][\"items\"] if item[\"block/title\"] == \"score\"))')\" --hide true --public false"],
+   :expect {:exit 0, :stdout-json-paths {[:status] "ok"}},
+   :covers
+   {:commands ["upsert property"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :upsert ["--id" "--hide" "--public"]}},
+   :tags [:upsert],
+   :extends :non-sync/graph-json-env}
+  {:id "query-custom-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Alpha block' >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?title . :where [?b :block/title ?title] [(= ?title \"Alpha block\")]]'"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :result] "Alpha block"}},
+   :covers
+   {:commands ["query"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :query ["--query"]}},
+   :tags [:query],
+   :extends :non-sync/graph-json-env}
+  {:id "query-named-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --name recent-updated --inputs '[1]'"],
+   :expect {:exit 0, :stdout-json-paths {[:status] "ok"}},
+   :covers
+   {:commands ["query"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :query ["--name" "--inputs"]}},
+   :tags [:query],
+   :extends :non-sync/graph-json-env}
+  {:id "query-list-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query list --graph {{graph-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :queries 0 :name] "list-priority"}},
+   :covers
+   {:commands ["query list"],
+    :options {:global ["--config" "--graph" "--root-dir" "--output"]}},
+   :tags [:query],
+   :extends :non-sync/graph-json-env}
+  {:id "example-show-human",
+   :expect
+   {:exit 0,
+    :stdout-contains
+    ["Selector: show" "Matched commands:" "show" "Examples:"]},
+   :covers {:commands ["example show"]},
+   :tags [:example],
+   :extends :non-sync/example-human-command,
+   :vars {:example-selector "show"}}
+  {:id "example-upsert-page-json",
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:data :selector] "upsert page",
+     [:data :matched-commands 0] "upsert page"}},
+   :covers {:commands ["example upsert page"]},
+   :tags [:example],
+   :extends :non-sync/example-json-command,
+   :vars {:example-selector "upsert page"}}
+  {:id "example-upsert-prefix-json",
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:data :selector] "upsert",
+     [:data :matched-commands 0] "upsert block"}},
+   :covers {:commands ["example upsert"]},
+   :tags [:example],
+   :extends :non-sync/example-json-command,
+   :vars {:example-selector "upsert"}}
+  {:id "example-list-prefix-json",
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:data :selector] "list",
+     [:data :matched-commands 0] "list page"}},
+   :covers {:commands ["example list"]},
+   :tags [:example],
+   :extends :non-sync/example-json-command,
+   :vars {:example-selector "list"}}
+  {:id "example-list-page-json",
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:data :selector] "list page",
+     [:data :matched-commands] ["list page"]}},
+   :covers {:commands ["example list page"]},
+   :tags [:example],
+   :extends :non-sync/example-json-command,
+   :vars {:example-selector "list page"}}
+  {:id "example-query-prefix-json",
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:data :selector] "query", [:data :matched-commands 0] "query"}},
+   :covers {:commands ["example query"]},
+   :tags [:example],
+   :extends :non-sync/example-json-command,
+   :vars {:example-selector "query"}}
+  {:id "example-query-list-json",
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:data :selector] "query list",
+     [:data :matched-commands] ["query list"]}},
+   :covers {:commands ["example query list"]},
+   :tags [:example],
+   :extends :non-sync/example-json-command,
+   :vars {:example-selector "query list"}}
+  {:id "example-remove-prefix-json",
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:data :selector] "remove",
+     [:data :matched-commands 0] "remove block"}},
+   :covers {:commands ["example remove"]},
+   :tags [:example],
+   :extends :non-sync/example-json-command,
+   :vars {:example-selector "remove"}}
+  {:id "example-remove-page-json",
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:data :selector] "remove page",
+     [:data :matched-commands] ["remove page"]}},
+   :covers {:commands ["example remove page"]},
+   :tags [:example],
+   :extends :non-sync/example-json-command,
+   :vars {:example-selector "remove page"}}
+  {:id "example-search-prefix-json",
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:data :selector] "search",
+     [:data :matched-commands 0] "search block"}},
+   :covers {:commands ["example search"]},
+   :tags [:example],
+   :extends :non-sync/example-json-command,
+   :vars {:example-selector "search"}}
+  {:id "example-search-block-edn",
+   :expect
+   {:exit 0,
+    :stdout-edn-paths
+    {[:data :selector] "search block",
+     [:data :matched-commands] ["search block"]}},
+   :covers {:commands ["example search block"]},
+   :tags [:example],
+   :extends :non-sync/example-edn-command,
+   :vars {:example-selector "search block"}}
+  {:id "show-id-human",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Alpha block' >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --graph {{graph-arg}} --output human show --id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --graph {{graph-arg}} --output human query --query '[:find ?e . :where [?e :block/title \"Alpha block\"]]')\""],
+   :expect {:exit 0, :stdout-contains ["Alpha block"]},
+   :covers
+   {:commands ["show"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :show ["--id"]}},
+   :tags [:show],
+   :extends :non-sync/graph-json-env}
+  {:id "show-uuid-human",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Alpha block' >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --graph {{graph-arg}} --output human show --uuid \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --graph {{graph-arg}} --output json query --query '[:find ?uuid . :where [?e :block/title \"Alpha block\"] [?e :block/uuid ?uuid]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\""],
+   :expect {:exit 0, :stdout-contains ["Alpha block"]},
+   :covers
+   {:commands ["show"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :show ["--uuid"]}},
+   :tags [:show],
+   :extends :non-sync/graph-json-env}
+  {:id "show-stdin-id-human",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Alpha block' >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --graph {{graph-arg}} --output human query --query '[:find [?e ...] :in $ ?q :where [?e :block/title ?title] [(clojure.string/includes? ?title ?q)]]' --inputs '[\"Alpha\"]' | {{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --graph {{graph-arg}} --output human show --id"],
+   :expect {:exit 0, :stdout-contains ["Alpha block"]},
+   :covers
+   {:commands ["show"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :show ["stdin:--id"]}},
+   :tags [:show :pipe],
+   :extends :non-sync/graph-json-env}
+  {:id "debug-pull-id-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json debug pull --graph {{graph-arg}} --id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?e . :where [?e :block/title \"Home\"]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\""],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :entity :block/title] "Home"}},
+   :covers
+   {:commands ["debug pull"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :debug ["--id"]}},
+   :tags [:debug],
+   :extends :non-sync/graph-json-env}
+  {:id "debug-pull-uuid-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json debug pull --graph {{graph-arg}} --uuid \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?uuid . :where [?e :block/title \"Home\"] [?e :block/uuid ?uuid]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\""],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :entity :block/title] "Home"}},
+   :covers
+   {:commands ["debug pull"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :debug ["--uuid"]}},
+   :tags [:debug],
+   :extends :non-sync/graph-json-env}
+  {:id "debug-pull-ident-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json debug pull --graph {{graph-arg}} --ident :logseq.class/Tag"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :entity :db/ident] "logseq.class/Tag"}},
+   :covers
+   {:commands ["debug pull"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :debug ["--ident"]}},
+   :tags [:debug],
+   :extends :non-sync/graph-json-env}
+  {:id "debug-pull-current-graph-fallback-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json debug pull --id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?e . :where [?e :block/title \"Home\"]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\""],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :entity :block/title] "Home"}},
+   :covers
+   {:commands ["debug pull"],
+    :options
+    {:global ["--config" "--root-dir" "--output"], :debug ["--id"]}},
+   :tags [:debug],
+   :extends :non-sync/graph-json-env}
+  {:id "remove-page-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json remove page --graph {{graph-arg}} --page Home"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok", [:data :result] true}},
+   :covers
+   {:commands ["remove page"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :remove ["--page"]}},
+   :tags [:remove],
+   :extends :non-sync/graph-json-env}
+  {:id "graph-remove-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{graph-arg}} >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph remove --graph {{graph-arg}}"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph list"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok"},
+    :stdout-not-contains ["{{graph}}"]},
+   :covers
+   {:commands ["graph remove" "graph list"],
+    :options {:global ["--config" "--graph" "--root-dir" "--output"]}},
+   :tags [:graph :remove]}
+  {:id "remove-block-uuid-human",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page Home >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page Home --content 'Alpha block' >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human remove block --graph {{graph-arg}} --uuid \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json query --graph {{graph-arg}} --query '[:find ?uuid . :where [?e :block/title \"Alpha block\"] [?e :block/uuid ?uuid]]' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"data\"][\"result\"])')\" >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output human show --graph {{graph-arg}} --page Home --linked-references false"],
+   :expect {:exit 0, :stdout-not-contains ["Alpha block"]},
+   :covers
+   {:commands ["remove block"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :remove ["--uuid"]}},
+   :tags [:remove],
+   :extends :non-sync/graph-json-env}
+  {:id "remove-tag-name-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert tag --graph {{graph-arg}} --name TagOne >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json remove tag --graph {{graph-arg}} --name TagOne >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list tag --graph {{graph-arg}} --fields title,id"],
+   :expect {:exit 0, :stdout-not-contains ["TagOne"]},
+   :covers
+   {:commands ["remove tag"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :remove ["--name"]}},
+   :tags [:remove],
+   :extends :non-sync/graph-json-env}
+  {:id "remove-property-id-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert property --graph {{graph-arg}} --name score --type number --cardinality one >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json remove property --graph {{graph-arg}} --id \"$({{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list property --graph {{graph-arg}} --fields title,id --limit 200 --sort updated-at --order desc | python3 -c 'import sys,json; print(next(item[\"db/id\"] for item in json.load(sys.stdin)[\"data\"][\"items\"] if item[\"block/title\"] == \"score\"))')\" >/dev/null"
+    "{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json list property --graph {{graph-arg}} --fields title,id"],
+   :expect {:exit 0, :stdout-not-contains ["score"]},
+   :covers
+   {:commands ["remove property"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :remove ["--id"]}},
+   :tags [:remove],
+   :extends :non-sync/graph-json-env}
+  {:id "server-cleanup-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server cleanup"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok",
+     [:data :mismatched] 0,
+     [:data :eligible] 0,
+     [:data :skipped-owner] 0}},
+   :covers
+   {:commands ["server cleanup"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :server []}},
+   :tags [:server],
+   :extends :non-sync/graph-json-env}
+  {:id "server-list-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server list"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :servers 0 :repo] "{{graph}}"}},
+   :covers
+   {:commands ["server list"],
+    :options {:global ["--config" "--root-dir" "--output"]}},
+   :tags [:server],
+   :extends :non-sync/graph-json-env}
+  {:id "server-restart-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server restart --graph {{graph-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :repo] "{{graph}}", [:data :owned?] true}},
+   :covers
+   {:commands ["server restart"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :server ["--graph"]}},
+   :tags [:server],
+   :extends :non-sync/graph-json-env}
+  {:id "server-stop-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{graph-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths {[:status] "ok", [:data :repo] "{{graph}}"}},
+   :covers
+   {:commands ["server stop"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :server ["--graph"]}},
+   :tags [:server]}
+  {:id "server-start-json",
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{graph-arg}} >/dev/null"],
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server start --graph {{graph-arg}}"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok", [:data :repo] "{{graph}}", [:data :owned?] true}},
+   :covers
+   {:commands ["server start"],
+    :options
+    {:global ["--config" "--graph" "--root-dir" "--output"],
+     :server ["--graph"]}},
+   :tags [:server],
+   :extends :non-sync/graph-json-env}
+  {:id "skill-show-human",
+   :cmds ["{{cli}} skill show"],
+   :expect
+   {:exit 0, :stdout-contains ["name: logseq-cli" "# Logseq CLI"]},
+   :covers {:commands ["skill show"], :options {:skill []}},
+   :tags [:skill :smoke]}
+  {:id "skill-show-json-still-raw-markdown",
+   :cmds ["{{cli}} --output json skill show"],
+   :expect
+   {:exit 0,
+    :stdout-contains ["name: logseq-cli" "# Logseq CLI"],
+    :stdout-not-contains ["\"status\"" "\"data\""]},
+   :covers {:commands ["skill show"], :options {:global ["--output"]}},
+   :tags [:skill]}
+  ;; Repo root already contains tracked `.agents/skills/logseq-cli/SKILL.md`,
+  ;; so this local-install case must run from an isolated cwd.
+  {:id "skill-install-local",
+   :setup
+   ["rm -rf ./tmp/cli-e2e-skill-install-local"
+    "mkdir -p ./tmp/cli-e2e-skill-install-local"],
+   :cmds
+   ["cd ./tmp/cli-e2e-skill-install-local && {{cli}} skill install >/dev/null"
+    "python3 -c 'import pathlib; p=pathlib.Path(\"./tmp/cli-e2e-skill-install-local/.agents/skills/logseq-cli/SKILL.md\"); print(\"installed\" if p.exists() else \"missing\")'"],
+   :expect {:exit 0, :stdout-contains ["installed"]},
+   :covers {:commands ["skill install"], :options {:skill []}},
+   :cleanup ["rm -rf ./tmp/cli-e2e-skill-install-local"],
+   :tags [:skill]}
+  {:id "skill-install-global-preserves-other-skills",
+   :setup
+   ["rm -rf ./tmp/cli-e2e-skill-home"
+    "mkdir -p ./tmp/cli-e2e-skill-home/.agents/skills/existing-skill"
+    "python3 -c 'import pathlib; pathlib.Path(\"./tmp/cli-e2e-skill-home/.agents/skills/existing-skill/SKILL.md\").write_text(\"keep\", encoding=\"utf8\")'"],
+   :cmds
+   ["HOME=\"$(pwd)/tmp/cli-e2e-skill-home\" {{cli}} skill install --global >/dev/null"
+    "python3 -c 'import pathlib; home=pathlib.Path(\"./tmp/cli-e2e-skill-home\"); existing=(home / \".agents/skills/existing-skill/SKILL.md\").read_text(encoding=\"utf8\"); installed=(home / \".agents/skills/logseq-cli/SKILL.md\").exists(); print(\"ok\" if existing==\"keep\" and installed else \"bad\")'"],
+   :expect {:exit 0, :stdout-contains ["ok"]},
+   :covers
+   {:commands ["skill install"], :options {:skill ["--global"]}},
+   :cleanup ["rm -rf ./tmp/cli-e2e-skill-home"],
+   :tags [:skill]}
+  {:id "completion-zsh",
+   :expect
+   {:exit 0,
+    :stdout-contains
+    ["#compdef logseq" "Auto-generated by `logseq completion zsh`"]},
+   :covers {:options {:completion ["zsh"]}},
+   :tags [:smoke],
+   :extends :non-sync/completion-command,
+   :vars {:completion-selector "zsh"}}
+  {:id "completion-bash-flag",
+   :expect
+   {:exit 0,
+    :stdout-contains
+    ["Auto-generated by `logseq completion bash`"
+     "_logseq_json_names_bash"]},
+   :covers {:options {:completion ["--shell" "bash"]}},
+   :extends :non-sync/completion-command,
+   :vars {:completion-selector "--shell bash"}}
+  {:id "completion-invalid-shell",
+   :expect {:exit 1, :stdout-contains ["unsupported shell: fish"]},
+   :extends :non-sync/completion-command,
+   :vars {:completion-selector "fish"}}
+  {:id "doctor-dev-script-json",
+   :cmds
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json doctor --dev-script"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok",
+     [:data :status] "ok",
+     [:data :checks 0 :id] "db-worker-script"},
+    :stdout-contains ["static/db-worker-node.js"]},
+   :covers
+   {:commands ["doctor"],
+    :options
+    {:global ["--config" "--root-dir" "--output"],
+     :doctor ["--dev-script"]}},
+   :tags [:doctor :smoke]}]}
diff --git a/cli-e2e/spec/non_sync_inventory.edn b/cli-e2e/spec/non_sync_inventory.edn
new file mode 100644
index 0000000000..01c70a2168
--- /dev/null
+++ b/cli-e2e/spec/non_sync_inventory.edn
@@ -0,0 +1,165 @@
+{:excluded-command-prefixes ["sync" "login" "logout"]
+ :scopes
+ {:global
+  {:options ["--help"
+             "--version"
+             "--config"
+             "--graph"
+             "--root-dir"
+             "--output"
+             "--verbose"]}
+
+  :graph
+  {:commands ["graph list"
+              "graph create"
+              "graph switch"
+              "graph remove"
+              "graph validate"
+              "graph info"
+              "graph export"
+              "graph import"
+              "graph backup list"
+              "graph backup create"
+              "graph backup restore"
+              "graph backup remove"]
+   :options ["--fix"
+             "--type"
+             "--file"
+             "--input"
+             "--name"
+             "--src"
+             "--dst"]}
+
+  :list
+  {:commands ["list page"
+              "list tag"
+              "list property"
+              "list task"
+              "list node"
+              "list asset"]
+   :options ["--expand"
+             "--fields"
+             "--limit"
+             "--offset"
+             "--sort"
+             "--order"
+             "--status"
+             "--priority"
+             "--content"
+             "--tags"
+             "--properties"
+             "--journal-only"
+             "--with-properties"
+             "--with-extends"
+             "--with-classes"
+             "--with-type"]}
+
+  :upsert
+  {:commands ["upsert block"
+              "upsert page"
+              "upsert task"
+              "upsert asset"
+              "upsert tag"
+              "upsert property"]
+   :options ["--id"
+             "--uuid"
+             "--target-id"
+             "--target-uuid"
+             "--target-page"
+             "--pos"
+             "--content"
+             "--path"
+             "--blocks-file"
+             "--status"
+             "--priority"
+             "--scheduled"
+             "--deadline"
+             "--no-status"
+             "--no-priority"
+             "--no-scheduled"
+             "--no-deadline"
+             "--update-tags"
+             "--update-properties"
+             "--remove-tags"
+             "--remove-properties"
+             "--page"
+             "--name"
+             "--type"
+             "--cardinality"
+             "--hide"
+             "--public"]}
+
+  :remove
+  {:commands ["remove block"
+              "remove page"
+              "remove tag"
+              "remove property"]
+   :options ["--id"
+             "--uuid"
+             "--name"]}
+
+  :query
+  {:commands ["query"
+              "query list"]
+   :options ["--query"
+             "--name"
+             "--inputs"]}
+
+  :search
+  {:commands ["search block"
+              "search page"
+              "search property"
+              "search tag"]
+   :options ["--content"]}
+
+  :show
+  {:commands ["show"]
+   :options ["--id"
+             "--uuid"
+             "--page"
+             "--linked-references"
+             "--level"
+             "stdin:--id"]}
+
+  :debug
+  {:commands ["debug pull"]
+   :options ["--id"
+             "--uuid"
+             "--ident"]}
+
+  :example
+  {:commands ["example list"
+              "example list page"
+              "example upsert"
+              "example upsert page"
+              "example remove"
+              "example remove page"
+              "example query"
+              "example query list"
+              "example search"
+              "example search block"
+              "example show"]
+   :options []}
+
+  :server
+  {:commands ["server list"
+              "server cleanup"
+              "server start"
+              "server stop"
+              "server restart"]
+   :options ["--graph"]}
+
+  :doctor
+  {:commands ["doctor"]
+   :options ["--dev-script"]}
+
+  :completion
+  {:commands ["completion"]
+   :options ["bash"
+             "zsh"
+             "--shell"]}
+
+  :skill
+  {:commands ["skill show"
+              "skill install"]
+   :options ["--global"]}}}
diff --git a/cli-e2e/spec/sync_cases.edn b/cli-e2e/spec/sync_cases.edn
new file mode 100644
index 0000000000..3b3e369bc1
--- /dev/null
+++ b/cli-e2e/spec/sync_cases.edn
@@ -0,0 +1,171 @@
+{:templates
+ {:sync/base
+  {:cleanup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{graph-arg}}"
+    "{{cli}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json server stop --graph {{graph-arg}}"],
+   :tags [:sync],
+   :vars
+   {:sync-port "18080",
+    :sync-http-base "http://127.0.0.1:18080",
+    :sync-ws-url "ws://127.0.0.1:18080/sync/%s",
+    :home-dir "{{tmp-dir}}/home",
+    :auth-path "{{tmp-dir}}/home/logseq/auth.json",
+    :cli-home "HOME='{{tmp-dir}}/home' {{cli}}"},
+   :setup
+   ["mkdir -p '{{tmp-dir}}/graphs-b'"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync ensure-keys --graph {{graph-arg}} --e2ee-password {{e2ee-password-arg}}"]},
+  :sync/common
+  {:extends :sync/base,
+   :cmds
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync upload --graph {{graph-arg}}"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync start --graph {{graph-arg}} --e2ee-password {{e2ee-password-arg}}"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{root-dir}}' --config '{{config-path}}' --graph '{{graph}}' --timeout-s 120 --interval-s 1"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync download --graph {{graph-arg}} --e2ee-password {{e2ee-password-arg}}"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync start --graph {{graph-arg}} --e2ee-password {{e2ee-password-arg}}"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --graph '{{graph}}' --timeout-s 120 --interval-s 1"],
+   :expect
+   {:exit 0,
+    :stdout-json-paths
+    {[:status] "ok",
+     [:data :pending-local] 0,
+     [:data :pending-asset] 0,
+     [:data :pending-server] 0,
+     [:data :last-error] nil}},
+   :covers
+   {:commands ["sync upload" "sync download" "sync status"],
+    :options {:global ["--config" "--graph" "--root-dir" "--output"]}}}}
+ :cases
+ [{:tags [:happy-path :bootstrap :a-to-b],
+   :extends :sync/common,
+   :setup
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SyncBootstrapHome >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page SyncBootstrapHome --content '{{marker-content}}' >/dev/null"],
+   :cmds
+   ["python3 '{{repo-root}}/cli-e2e/scripts/compare_graph_queries.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --query '[:find ?title :where [?b :block/title ?title] [(= ?title \"{{marker-content}}\")] ]' --require-result"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync status --graph {{graph-arg}}"],
+   :id "sync-bootstrap-upload-download-a-to-b",
+   :graph "sync-e2e-bootstrap-a-to-b",
+   :vars {:marker-content "sync-happy-bootstrap-a-to-b-marker"}}
+  {:tags [:happy-path :incremental :a-to-b],
+   :extends :sync/common,
+   :setup
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SyncIncrementalHome >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page SyncIncrementalHome --content '{{seed-marker}}' >/dev/null"],
+   :cmds
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page SyncIncrementalHome --content '{{incremental-marker}}' >/dev/null"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --graph '{{graph}}' --timeout-s 120 --interval-s 1"
+    "python3 '{{repo-root}}/cli-e2e/scripts/compare_graph_queries.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --query '[:find ?title :where [?b :block/title ?title] [(= ?title \"{{incremental-marker}}\")] ]' --require-result"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync status --graph {{graph-arg}}"],
+   :id "sync-incremental-update-a-to-b",
+   :graph "sync-e2e-incremental-a-to-b",
+   :vars
+   {:seed-marker "sync-happy-incremental-seed-marker",
+    :incremental-marker "sync-happy-incremental-update-marker"}}
+  {:tags [:happy-path :bidirectional :roundtrip],
+   :extends :sync/common,
+   :setup
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SyncRoundtripAHome >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page SyncRoundtripAHome --content '{{marker-a}}' >/dev/null"],
+   :cmds
+   ["{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json upsert page --graph {{graph-arg}} --page SyncRoundtripBHome >/dev/null"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json upsert block --graph {{graph-arg}} --target-page SyncRoundtripBHome --content '{{marker-b}}' >/dev/null"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{root-dir}}' --config '{{config-path}}' --graph '{{graph}}' --timeout-s 120 --interval-s 1"
+    "python3 '{{repo-root}}/cli-e2e/scripts/compare_graph_queries.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --query '[:find ?title :where [?b :block/title ?title] [(= ?title \"{{marker-b}}\")] ]' --require-result"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync status --graph {{graph-arg}}"],
+   :id "sync-bidirectional-roundtrip",
+   :graph "sync-e2e-bidirectional-roundtrip",
+   :vars
+   {:marker-a "sync-happy-roundtrip-a-seed-marker",
+    :marker-b "sync-happy-roundtrip-b-origin-marker"}}
+  {:tags [:happy-path :multi-batch :a-to-b],
+   :extends :sync/common,
+   :setup
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SyncMultiBatchHome >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page SyncMultiBatchHome --content '{{seed-marker}}' >/dev/null"],
+   :cmds
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SyncMultiBatchOne >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page SyncMultiBatchOne --content '{{batch-marker-1}}' >/dev/null"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --graph '{{graph}}' --timeout-s 30 --interval-s 1"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SyncMultiBatchTwo >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page SyncMultiBatchTwo --content '{{batch-marker-2}}' >/dev/null"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --graph '{{graph}}' --timeout-s 30 --interval-s 1"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SyncMultiBatchThree >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page SyncMultiBatchThree --content '{{batch-marker-3}}' >/dev/null"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --graph '{{graph}}' --timeout-s 30 --interval-s 1"
+    "python3 '{{repo-root}}/cli-e2e/scripts/compare_graph_queries.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --query '[:find ?title :where [?b :block/title ?title] [(= ?title \"{{batch-marker-1}}\")] ]' --query '[:find ?title :where [?b :block/title ?title] [(= ?title \"{{batch-marker-2}}\")] ]' --query '[:find ?title :where [?b :block/title ?title] [(= ?title \"{{batch-marker-3}}\")] ]' --require-result"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync status --graph {{graph-arg}}"],
+   :id "sync-multi-batch-operations",
+   :graph "sync-e2e-multi-batch-operations",
+   :vars
+   {:seed-marker "sync-happy-multi-batch-seed-marker",
+    :batch-marker-3 "sync-happy-multi-batch-marker-3",
+    :batch-marker-1 "sync-happy-multi-batch-marker-1",
+    :batch-marker-2 "sync-happy-multi-batch-marker-2"}}
+  {:tags [:negative :upload :duplicate],
+   :extends :sync/base,
+   :setup
+   ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{graph-arg}}"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync upload --graph {{graph-arg}} >/dev/null"],
+   :cmds
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync upload --graph {{graph-arg}}"],
+   :expect
+   {:exit 1,
+    :stdout-json-paths
+    {[:status] "error",
+     [:error :code] "graph-already-exists",
+     [:error :context :graph-name] "{{graph}}"},
+    :stdout-contains ["delete it before uploading again"]},
+   :id "sync-upload-rejects-duplicate-remote-graph",
+   :graph "sync-e2e-upload-rejects-duplicate-remote-graph"}
+  {:tags [:happy-path :steady-state :status],
+   :extends :sync/common,
+   :setup
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page SyncSteadyStateHome >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page SyncSteadyStateHome --content '{{marker-content}}' >/dev/null"],
+   :cmds
+   ["python3 '{{repo-root}}/cli-e2e/scripts/compare_graph_queries.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --query '[:find ?title :where [?b :block/title ?title] [(= ?title \"{{marker-content}}\")] ]' --require-result"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --graph '{{graph}}' --timeout-s 30 --interval-s 1"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync status --graph {{graph-arg}}"],
+   :id "sync-status-steady-state",
+   :graph "sync-e2e-status-steady-state",
+   :vars {:marker-content "sync-happy-steady-state-marker"}}
+  {:tags [:stress :bidirectional :random :block-ops],
+   :extends :sync/common,
+   :setup
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page '{{random-page}}' >/dev/null"],
+   :cmds
+   ["python3 '{{repo-root}}/cli-e2e/scripts/random_bidirectional_block_ops.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --page '{{random-page}}' --profile default --rounds-per-client {{rounds-per-client}} --seed {{random-seed}}"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{root-dir}}' --config '{{config-path}}' --graph '{{graph}}' --timeout-s 180 --interval-s 1 --min-tx-delta 1 --baseline-tx 0"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --graph '{{graph}}' --timeout-s 180 --interval-s 1 --min-tx-delta 1 --baseline-tx 0"
+    "python3 '{{repo-root}}/cli-e2e/scripts/compare_graph_queries.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --query '[:find (pull ?b [:block/uuid :block/title :block/order {:block/parent [:block/uuid]}]) :where [?p :block/title \"{{random-page}}\"] [?b :block/page ?p] [?b :block/uuid]]' --require-result"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync status --graph {{graph-arg}}"],
+   :id "sync-random-bidirectional-block-ops",
+   :graph "sync-e2e-random-bidirectional-block-ops",
+   :vars
+   {:random-seed "424242",
+    :random-page "SyncRandomOpsHome",
+    :rounds-per-client "40"}}
+  {:tags [:stress :offline :bidirectional :random :block-ops],
+   :extends :sync/common,
+   :setup
+   ["{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert page --graph {{graph-arg}} --page '{{random-page}}' >/dev/null"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json upsert block --graph {{graph-arg}} --target-page '{{random-page}}' --content '{{seed-marker}}' >/dev/null"],
+   :cmds
+   ["python3 '{{repo-root}}/cli-e2e/scripts/compare_graph_queries.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --query '[:find ?title :where [?b :block/title ?title] [(= ?title \"{{seed-marker}}\")] ]' --require-result"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync stop --graph {{graph-arg}}"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync stop --graph {{graph-arg}}"
+    "python3 '{{repo-root}}/cli-e2e/scripts/random_bidirectional_block_ops.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --page '{{random-page}}' --profile high-stress --rounds-per-client {{rounds-per-client}} --seed {{random-seed}}"
+    "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync start --graph {{graph-arg}} --e2ee-password {{e2ee-password-arg}}"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync start --graph {{graph-arg}} --e2ee-password {{e2ee-password-arg}}"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{root-dir}}' --config '{{config-path}}' --graph '{{graph}}' --timeout-s 240 --interval-s 1 --min-tx-delta 1 --baseline-tx 0"
+    "python3 '{{repo-root}}/cli-e2e/scripts/wait_sync_status.py' --cli '{{repo-root}}/static/logseq-cli.js' --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --graph '{{graph}}' --timeout-s 240 --interval-s 1 --min-tx-delta 1 --baseline-tx 0"
+    "python3 '{{repo-root}}/cli-e2e/scripts/compare_graph_queries.py' --cli '{{repo-root}}/static/logseq-cli.js' --graph '{{graph}}' --config-a '{{config-path}}' --root-dir-a '{{root-dir}}' --config-b '{{tmp-dir}}/cli-b.edn' --root-dir-b '{{tmp-dir}}/graphs-b' --query '[:find (pull ?b [:block/uuid :block/title :block/order {:block/parent [:block/uuid]}]) :where [?p :block/title \"{{random-page}}\"] [?b :block/page ?p] [?b :block/uuid]]' --require-result"
+    "{{cli-home}} --root-dir '{{tmp-dir}}/graphs-b' --config '{{tmp-dir}}/cli-b.edn' --output json sync status --graph {{graph-arg}}"],
+   :id "sync-offline-random-bidirectional-block-ops",
+   :graph "sync-e2e-offline-random-bidirectional-block-ops",
+   :vars
+   {:seed-marker "sync-offline-random-seed-marker",
+    :random-seed "989898",
+    :random-page "SyncOfflineRandomOpsHome",
+    :rounds-per-client "40"}}]}
diff --git a/cli-e2e/spec/sync_inventory.edn b/cli-e2e/spec/sync_inventory.edn
new file mode 100644
index 0000000000..7a664eb15f
--- /dev/null
+++ b/cli-e2e/spec/sync_inventory.edn
@@ -0,0 +1,13 @@
+{:excluded-command-prefixes ["login" "logout"]
+ :scopes
+ {:global
+  {:options ["--config"
+             "--graph"
+             "--root-dir"
+             "--output"]}
+
+  :sync
+  {:commands ["sync upload"
+              "sync download"
+              "sync status"]
+   :options []}}}
diff --git a/cli-e2e/src/logseq/cli/e2e/cleanup.clj b/cli-e2e/src/logseq/cli/e2e/cleanup.clj
new file mode 100644
index 0000000000..906f69d5f1
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/cleanup.clj
@@ -0,0 +1,184 @@
+(ns logseq.cli.e2e.cleanup
+  (:require [babashka.fs :as fs]
+            [clojure.java.shell :as java-shell]
+            [clojure.string :as string]))
+
+(def ^:private cli-e2e-temp-prefix "logseq-cli-e2e-")
+(def ^:private db-sync-default-port 18080)
+
+(defn- parse-ps-line
+  [line]
+  (when-let [[_ pid-str command] (re-matches #"\s*(\d+)\s+(.*)" (or line ""))]
+    {:pid (Long/parseLong pid-str)
+     :command command}))
+
+(defn- cli-e2e-db-worker-command?
+  [command]
+  (and (re-find #"db-worker-node(?:\.js)?\b" command)
+       (re-find #"logseq-cli-e2e-" command)))
+
+(defn list-cli-e2e-db-worker-pids
+  ([]
+   (list-cli-e2e-db-worker-pids {}))
+  ([{:keys [shell-fn]
+     :or {shell-fn java-shell/sh}}]
+   (let [{:keys [exit out err]} (shell-fn "ps" "-ax" "-o" "pid=" "-o" "command=")]
+     (when-not (zero? exit)
+       (throw (ex-info "Unable to scan processes"
+                       {:exit exit
+                        :err err})))
+     (->> (string/split-lines (or out ""))
+          (keep parse-ps-line)
+          (filter (fn [{:keys [command]}]
+                    (cli-e2e-db-worker-command? command)))
+          (mapv :pid)))))
+
+(defn- pid-alive?
+  [pid]
+  (zero? (:exit (java-shell/sh "kill" "-0" (str pid)))))
+
+(defn- kill-pid!
+  [pid]
+  (try
+    (if-not (pid-alive? pid)
+      :not-found
+      (do
+        (java-shell/sh "kill" "-TERM" (str pid))
+        (Thread/sleep 100)
+        (if-not (pid-alive? pid)
+          :killed
+          (do
+            (java-shell/sh "kill" "-KILL" (str pid))
+            (Thread/sleep 50)
+            (if (pid-alive? pid)
+              :failed
+              :killed)))))
+    (catch Exception _
+      :failed)))
+
+(defn cleanup-db-worker-processes!
+  ([]
+   (cleanup-db-worker-processes! {}))
+  ([{:keys [dry-run list-pids-fn kill-pid-fn]}]
+   (let [list-pids-fn (or list-pids-fn list-cli-e2e-db-worker-pids)
+         kill-pid-fn (or kill-pid-fn kill-pid!)
+         found-pids (vec (list-pids-fn))]
+     (if dry-run
+       {:dry-run? true
+        :found-pids found-pids
+        :would-kill-pids found-pids
+        :killed-pids []
+        :failed-pids []}
+       (let [{:keys [killed-pids failed-pids]}
+             (reduce (fn [acc pid]
+                       (if (= :failed (kill-pid-fn pid))
+                         (update acc :failed-pids conj pid)
+                         (update acc :killed-pids conj pid)))
+                     {:killed-pids []
+                      :failed-pids []}
+                     found-pids)]
+         {:dry-run? false
+          :found-pids found-pids
+          :would-kill-pids []
+          :killed-pids killed-pids
+          :failed-pids failed-pids})))))
+
+(defn- parse-long-safe
+  [value]
+  (try
+    (Long/parseLong value)
+    (catch Exception _
+      nil)))
+
+(defn list-cli-e2e-db-sync-port-pids
+  ([]
+   (list-cli-e2e-db-sync-port-pids {}))
+  ([{:keys [shell-fn port]
+     :or {shell-fn java-shell/sh
+          port db-sync-default-port}}]
+   (let [{:keys [exit out err]} (shell-fn "lsof" "-nP" (str "-iTCP:" port) "-sTCP:LISTEN")
+         out-lines (->> (string/split-lines (or out ""))
+                        (map string/trim)
+                        (remove string/blank?)
+                        vec)]
+     (when (and (not (zero? exit))
+                (or (not (string/blank? err))
+                    (seq out-lines)))
+       (throw (ex-info "Unable to scan db-sync server port listeners"
+                       {:exit exit
+                        :err err
+                        :port port})))
+     (->> out-lines
+          (filter #(re-find (re-pattern (str ":" port "\\b")) %))
+          (keep (fn [line]
+                  (some-> (string/split line #"\s+")
+                          (nth 1 nil)
+                          parse-long-safe)))
+          distinct
+          vec))))
+
+(defn cleanup-db-sync-port-processes!
+  ([]
+   (cleanup-db-sync-port-processes! {}))
+  ([{:keys [dry-run list-pids-fn kill-pid-fn]
+     :as _opts}]
+   (let [list-pids-fn (or list-pids-fn list-cli-e2e-db-sync-port-pids)
+         kill-pid-fn (or kill-pid-fn kill-pid!)
+         found-pids (vec (list-pids-fn))]
+     (if dry-run
+       {:dry-run? true
+        :found-pids found-pids
+        :would-kill-pids found-pids
+        :killed-pids []
+        :failed-pids []}
+       (let [{:keys [killed-pids failed-pids]}
+             (reduce (fn [acc pid]
+                       (if (= :failed (kill-pid-fn pid))
+                         (update acc :failed-pids conj pid)
+                         (update acc :killed-pids conj pid)))
+                     {:killed-pids []
+                      :failed-pids []}
+                     found-pids)]
+         {:dry-run? false
+          :found-pids found-pids
+          :would-kill-pids []
+          :killed-pids killed-pids
+          :failed-pids failed-pids})))))
+
+(defn- list-cli-e2e-temp-roots
+  [tmp-root]
+  (->> (fs/list-dir tmp-root)
+       (filter fs/directory?)
+       (filter #(string/starts-with? (fs/file-name %) cli-e2e-temp-prefix))
+       (mapv str)))
+
+(defn cleanup-temp-roots!
+  ([]
+   (cleanup-temp-roots! {}))
+  ([{:keys [dry-run tmp-root list-dirs-fn delete-dir-fn]
+     :or {tmp-root (System/getProperty "java.io.tmpdir")
+          delete-dir-fn fs/delete-tree}}]
+   (let [list-dirs-fn (or list-dirs-fn
+                          #(list-cli-e2e-temp-roots tmp-root))
+         found-dirs (vec (list-dirs-fn))]
+     (if dry-run
+       {:dry-run? true
+        :found-dirs found-dirs
+        :would-remove-dirs found-dirs
+        :removed-dirs []
+        :failed-dirs []}
+       (let [{:keys [removed-dirs failed-dirs]}
+             (reduce (fn [acc dir]
+                       (try
+                         (delete-dir-fn dir)
+                         (update acc :removed-dirs conj dir)
+                         (catch Exception _
+                           (update acc :failed-dirs conj dir))))
+                     {:removed-dirs []
+                      :failed-dirs []}
+                     found-dirs)]
+         {:dry-run? false
+          :found-dirs found-dirs
+          :would-remove-dirs []
+          :removed-dirs removed-dirs
+          :failed-dirs failed-dirs})))))
diff --git a/cli-e2e/src/logseq/cli/e2e/coverage.clj b/cli-e2e/src/logseq/cli/e2e/coverage.clj
new file mode 100644
index 0000000000..2b5e13fb2b
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/coverage.clj
@@ -0,0 +1,120 @@
+(ns logseq.cli.e2e.coverage
+  (:require [clojure.set :as set]
+            [clojure.string :as string]))
+
+(defn- normalize-commands
+  [commands]
+  (->> commands
+       (map str)
+       (remove string/blank?)
+       distinct
+       sort
+       vec))
+
+(defn- normalize-options
+  [options]
+  (->> options
+       (map str)
+       (remove string/blank?)
+       distinct
+       sort
+       vec))
+
+(defn- excluded-command?
+  [excluded-prefixes command]
+  (let [head (first (string/split (str command) #" "))]
+    (contains? (set excluded-prefixes) head)))
+
+(defn validate-inventory!
+  [{:keys [excluded-command-prefixes scopes] :as inventory}]
+  (let [invalid-commands (->> scopes
+                              vals
+                              (mapcat :commands)
+                              (filter #(excluded-command? excluded-command-prefixes %))
+                              normalize-commands)
+        invalid-scopes (->> scopes
+                            (keep (fn [[scope {:keys [commands]}]]
+                                    (when (some #(excluded-command? excluded-command-prefixes %) commands)
+                                      scope)))
+                            sort
+                            vec)]
+    (when (seq invalid-commands)
+      (throw (ex-info "Excluded commands cannot appear in cli-e2e inventory"
+                      {:invalid-commands invalid-commands
+                       :invalid-scopes invalid-scopes
+                       :inventory inventory})))
+    inventory))
+
+(defn validate-cases!
+  [{:keys [excluded-command-prefixes] :as inventory} cases]
+  (let [invalid-cases (->> cases
+                           (filter (fn [{:keys [covers]}]
+                                     (some #(excluded-command? excluded-command-prefixes %)
+                                           (get covers :commands []))))
+                           (mapv :id))]
+    (when (seq invalid-cases)
+      (throw (ex-info "Excluded commands cannot be covered by cli-e2e cases"
+                      {:invalid-case-ids invalid-cases
+                       :inventory inventory})))
+    cases))
+
+(defn command->scope
+  [{:keys [scopes]}]
+  (into {}
+        (mapcat (fn [[scope {:keys [commands]}]]
+                  (map (fn [command]
+                         [command scope])
+                       commands)))
+        scopes))
+
+(defn required-commands
+  [{:keys [scopes]}]
+  (->> scopes
+       vals
+       (mapcat :commands)
+       normalize-commands))
+
+(defn covered-commands
+  [cases]
+  (->> cases
+       (mapcat #(get-in % [:covers :commands]))
+       normalize-commands))
+
+(defn required-options-by-scope
+  [{:keys [scopes]}]
+  (into {}
+        (map (fn [[scope {:keys [options]}]]
+               [scope (normalize-options options)]))
+        scopes))
+
+(defn covered-options-by-scope
+  [cases]
+  (reduce (fn [acc {:keys [covers]}]
+            (reduce-kv (fn [acc' scope options]
+                         (update acc' scope (fnil into #{}) options))
+                       acc
+                       (get covers :options {})))
+          {}
+          cases))
+
+(defn coverage-report
+  [inventory cases]
+  (validate-inventory! inventory)
+  (validate-cases! inventory cases)
+  (let [required-commands* (set (required-commands inventory))
+        covered-commands* (set (covered-commands cases))
+        covered-options* (covered-options-by-scope cases)
+        required-options* (required-options-by-scope inventory)]
+    {:missing-commands (->> (set/difference required-commands* covered-commands*)
+                            normalize-commands)
+     :missing-options (into {}
+                            (map (fn [[scope options]]
+                                   [scope (->> (set/difference (set options)
+                                                               (get covered-options* scope #{}))
+                                               normalize-options)]))
+                            required-options*)}))
+
+(defn complete?
+  [{:keys [missing-commands missing-options]}]
+  (and (empty? missing-commands)
+       (every? empty? (vals missing-options))))
diff --git a/cli-e2e/src/logseq/cli/e2e/main.clj b/cli-e2e/src/logseq/cli/e2e/main.clj
new file mode 100644
index 0000000000..87f5daf0f4
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/main.clj
@@ -0,0 +1,467 @@
+(ns logseq.cli.e2e.main
+  (:require [clojure.set :as set]
+            [logseq.cli.e2e.cleanup :as cleanup]
+            [logseq.cli.e2e.coverage :as coverage]
+            [logseq.cli.e2e.manifests :as manifests]
+            [logseq.cli.e2e.preflight :as preflight]
+            [logseq.cli.e2e.report :as report]
+            [logseq.cli.e2e.runner :as runner]
+            [logseq.cli.e2e.shell :as shell]
+            [logseq.cli.e2e.sync-fixture :as sync-fixture])
+  (:import (java.util.concurrent Executors LinkedBlockingQueue TimeUnit)))
+
+(defn select-cases
+  [cases {:keys [case include]}]
+  (cond
+    case
+    (filterv #(= case (:id %)) cases)
+
+    (seq include)
+    (let [include-tags (set (map keyword include))]
+      (filterv (fn [{:keys [tags]}]
+                 (not-empty (set/intersection include-tags (set tags))))
+               cases))
+
+    :else
+    (vec cases)))
+
+(def default-suite :non-sync)
+(def default-jobs 1)
+(def default-cli-jobs 4)
+
+(defn- suite-from-opts
+  [opts]
+  (or (:suite opts) default-suite))
+
+(defn- elapsed-ms
+  [started-at]
+  (long (/ (- (System/nanoTime) started-at) 1000000)))
+
+(defn- format-duration
+  [started-at]
+  (format "%.2fs" (/ (double (- (System/nanoTime) started-at)) 1000000000.0)))
+
+(defn- positive-jobs
+  [jobs]
+  (let [jobs (or jobs default-jobs)]
+    (when-not (and (integer? jobs) (pos? jobs))
+      (throw (ex-info "--jobs must be a positive integer"
+                      {:jobs jobs})))
+    jobs))
+
+(defn run-selected-cases!
+  [selected-cases run-case run-command {:keys [on-case-start on-case-success on-case-failure detailed-log? timings? jobs]}]
+  (let [total (count selected-cases)
+        _ (positive-jobs jobs)]
+    (reduce (fn [acc [idx case]]
+              (let [index (inc idx)
+                    started-at (System/nanoTime)]
+                (when on-case-start
+                  (on-case-start {:index index
+                                  :total total
+                                  :case case}))
+                (try
+                  (let [result (run-case case {:run-command run-command
+                                               :detailed-log? detailed-log?
+                                               :timings? timings?})
+                        payload {:index index
+                                 :total total
+                                 :case case
+                                 :result result
+                                 :elapsed-ms (elapsed-ms started-at)}]
+                    (when on-case-success
+                      (on-case-success payload))
+                    (conj acc result))
+                  (catch Exception error
+                    (when on-case-failure
+                      (on-case-failure {:index index
+                                        :total total
+                                        :case case
+                                        :error error
+                                        :elapsed-ms (elapsed-ms started-at)}))
+                    (throw error)))))
+            []
+            (map-indexed vector selected-cases))))
+
+(defn run-selected-cases-in-parallel!
+  [selected-cases run-case run-command {:keys [on-case-start on-case-success on-case-failure detailed-log? timings? jobs]}]
+  (let [total (count selected-cases)
+        jobs (positive-jobs jobs)
+        executor (Executors/newFixedThreadPool jobs)
+        completions (LinkedBlockingQueue.)]
+    (try
+      (doseq [[idx case] (map-indexed vector selected-cases)]
+        (let [index (inc idx)]
+          (when on-case-start
+            (on-case-start {:index index
+                            :total total
+                            :case case}))
+          (.submit executor
+                   ^Runnable
+                   (fn []
+                     (let [started-at (System/nanoTime)]
+                       (.put completions
+                             (try
+                               (let [result (run-case case {:run-command run-command
+                                                            :detailed-log? detailed-log?
+                                                            :timings? timings?})]
+                                 {:index index
+                                  :total total
+                                  :case case
+                                  :result result
+                                  :elapsed-ms (elapsed-ms started-at)})
+                               (catch Exception error
+                                 {:index index
+                                  :total total
+                                  :case case
+                                  :error error
+                                  :elapsed-ms (elapsed-ms started-at)}))))))))
+      (loop [remaining total
+             results []
+             failure nil]
+        (if (zero? remaining)
+          (do
+            (when failure
+              (throw failure))
+            (->> results
+                 (sort-by :index)
+                 (mapv :result)))
+          (let [payload (.take completions)]
+            (if-let [error (:error payload)]
+              (do
+                (when on-case-failure
+                  (on-case-failure payload))
+                (recur (dec remaining) results (or failure error)))
+              (do
+                (when on-case-success
+                  (on-case-success payload))
+                (recur (dec remaining) (conj results payload) failure))))))
+      (finally
+        (.shutdown executor)
+        (.awaitTermination executor 1 TimeUnit/MINUTES)))))
+
+(defn run!
+  [{:keys [inventory cases skip-build run-command jobs]
+    :as opts}]
+  (let [run-command (or run-command shell/run!)
+        run-case (or (:run-case opts) runner/run-case!)
+        suite (suite-from-opts opts)
+        sync-suite? (= suite :sync)
+        jobs (positive-jobs jobs)
+        targeted-run? (or (:case opts) (seq (:include opts)))
+        on-preflight-start (:on-preflight-start opts)
+        on-preflight-complete (:on-preflight-complete opts)
+        on-cases-ready (:on-cases-ready opts)]
+    (when on-preflight-start
+      (on-preflight-start {:skip-build skip-build}))
+    (let [preflight-result (preflight/run! {:skip-build skip-build
+                                            :run-command run-command})
+          inventory (or inventory (manifests/load-inventory suite))
+          cases (or cases (manifests/load-cases suite))]
+      (when on-preflight-complete
+        (on-preflight-complete preflight-result))
+      (let [selected-cases (select-cases cases opts)
+            coverage-result (when-not targeted-run?
+                              (coverage/coverage-report inventory selected-cases))]
+        (when (and coverage-result
+                   (not (coverage/complete? coverage-result)))
+          (throw (ex-info "Missing coverage"
+                          {:coverage coverage-result
+                           :message (report/format-missing-coverage coverage-result)})))
+        (when on-cases-ready
+          (on-cases-ready {:total (count selected-cases)
+                           :targeted-run? targeted-run?}))
+        (let [suite-context (when sync-suite?
+                              (sync-fixture/before-suite! {:run-command run-command}))
+              sync-context (if suite-context
+                             (assoc suite-context :e2ee-password (:e2ee-password opts))
+                             suite-context)
+              run-case* (if sync-suite?
+                          (fn [case case-opts]
+                            (run-case (sync-fixture/prepare-case case sync-context)
+                                      case-opts))
+                          run-case)]
+          (try
+            {:status :ok
+             :cases selected-cases
+             :coverage coverage-result
+             :results ((if (> jobs 1)
+                         run-selected-cases-in-parallel!
+                         run-selected-cases!)
+                       selected-cases
+                       run-case*
+                       run-command
+                       (assoc opts :jobs jobs))}
+            (finally
+              (when suite-context
+                (sync-fixture/after-suite! suite-context {:run-command run-command})))))))))
+(defn build!
+  [opts]
+  (preflight/run! opts))
+
+(defn list-cases!
+  [opts]
+  (doseq [{:keys [id]} (manifests/load-cases (suite-from-opts opts))]
+    (println id)))
+
+(defn list-sync-cases!
+  [opts]
+  (list-cases! (assoc opts :suite :sync)))
+
+(defn- print-cleanup-help!
+  []
+  (println "Usage: bb -f cli-e2e/bb.edn cleanup [options]")
+  (println)
+  (println "Options:")
+  (println "  -h, --help           Show this help and exit")
+  (println "      --dry-run        Scan and report only; do not kill/delete")
+  (println)
+  (println "Cleanups performed:")
+  (println "  - Terminate cli-e2e db-worker-node processes")
+  (println "  - Terminate db-sync server listeners on port 18080")
+  (println "  - Remove cli-e2e temp roots")
+  (flush))
+
+(defn cleanup!
+  [opts]
+  (if (:help opts)
+    (do
+      (print-cleanup-help!)
+      {:status :help})
+    (let [dry-run? (boolean (:dry-run opts))
+          cleanup-opts (cond-> {}
+                         dry-run? (assoc :dry-run true))
+          processes (cleanup/cleanup-db-worker-processes! cleanup-opts)
+          db-sync-port-processes (cleanup/cleanup-db-sync-port-processes! cleanup-opts)
+          temp-roots (cleanup/cleanup-temp-roots! cleanup-opts)]
+      (println "==> Running cli-e2e cleanup")
+      (if dry-run?
+        (do
+          (println (format "[dry-run] db-worker-node processes: found %d, would kill %d"
+                           (count (:found-pids processes))
+                           (count (:would-kill-pids processes))))
+          (println (format "[dry-run] db-sync server processes (port 18080): found %d, would kill %d"
+                           (count (:found-pids db-sync-port-processes))
+                           (count (:would-kill-pids db-sync-port-processes))))
+          (println (format "[dry-run] temp roots: found %d, would remove %d"
+                           (count (:found-dirs temp-roots))
+                           (count (:would-remove-dirs temp-roots)))))
+        (do
+          (println (format "db-worker-node processes: found %d, killed %d, failed %d"
+                           (count (:found-pids processes))
+                           (count (:killed-pids processes))
+                           (count (:failed-pids processes))))
+          (println (format "db-sync server processes (port 18080): found %d, killed %d, failed %d"
+                           (count (:found-pids db-sync-port-processes))
+                           (count (:killed-pids db-sync-port-processes))
+                           (count (:failed-pids db-sync-port-processes))))
+          (println (format "temp roots: found %d, removed %d, failed %d"
+                           (count (:found-dirs temp-roots))
+                           (count (:removed-dirs temp-roots))
+                           (count (:failed-dirs temp-roots))))))
+      (flush)
+      {:status :ok
+       :dry-run? dry-run?
+       :processes processes
+       :db-sync-port-processes db-sync-port-processes
+       :temp-roots temp-roots})))
+
+(defn- print-failure-details!
+  [error]
+  (let [data (ex-data error)]
+    (println (str "      reason: " (.getMessage error)))
+    (when-let [cmd (:cmd data)]
+      (println (str "      cmd: " cmd)))
+    (when-let [stream (:stream data)]
+      (println (str "      stream: " stream)))
+    (when-let [snippet (:snippet data)]
+      (println (str "      snippet: " snippet)))
+    (flush)))
+
+(defn- format-step-label
+  [{:keys [phase step-index step-total]}]
+  (let [phase-name (name (or phase :command))]
+    (format "%s %d/%d" phase-name (or step-index 1) (or step-total 1))))
+
+(defn- print-case-timings!
+  [timings]
+  (when (seq timings)
+    (println "      step timings:")
+    (doseq [{:keys [elapsed-ms status cmd] :as timing} timings]
+      (println (format "      - [%-12s] %6dms (%s) $ %s"
+                       (format-step-label timing)
+                       elapsed-ms
+                       (name (or status :ok))
+                       cmd)))
+    (flush)))
+
+(defn- print-slow-steps!
+  [all-step-timings]
+  (when (seq all-step-timings)
+    (println "Slow steps (top 10):")
+    (doseq [{:keys [case-id elapsed-ms cmd] :as timing}
+            (->> all-step-timings
+                 (sort-by :elapsed-ms >)
+                 (take 10))]
+      (println (format "  - %-45s [%-12s] %6dms $ %s"
+                       case-id
+                       (format-step-label timing)
+                       elapsed-ms
+                       cmd)))
+    (flush)))
+
+(defn- progress-prefix
+  [{:keys [parallel? index total]} symbol]
+  (if parallel?
+    (str symbol " ")
+    (format "[%d/%d] %s " index total symbol)))
+
+(defn- print-test-help!
+  [command-name suite]
+  (let [sync-suite? (= suite :sync)]
+    (println (str "Usage: bb -f cli-e2e/bb.edn " command-name " [options]"))
+    (println)
+    (println "Options:")
+    (println "  -h, --help           Show this help and exit")
+    (println "      --skip-build     Skip build preflight steps")
+    (println "  -i, --include TAG    Run only cases with matching tag (repeatable)")
+    (println "      --case ID        Run a single case by id")
+    (println (format "      --jobs N         %s (Default: %d)"
+                     (if sync-suite?
+                       "Run up to N sync cases in parallel"
+                       "Run up to N non-sync cases in parallel")
+                     default-cli-jobs))
+    (when sync-suite?
+      (println "      --e2ee-password VALUE  E2EE password for sync commands (Default: 11111)"))
+    (println "      --verbose        Enable verbose output")
+    (println "      --timings        Print per-step timings and slow-step summary")
+    (println)
+    (println "Examples:")
+    (if sync-suite?
+      (println (str "  bb -f cli-e2e/bb.edn " command-name))
+      (println (str "  bb -f cli-e2e/bb.edn " command-name " --skip-build")))
+    (println (str "  bb -f cli-e2e/bb.edn " command-name
+                  (if sync-suite?
+                    " --jobs 4"
+                    " --skip-build --jobs 4")))
+    (println (str "  bb -f cli-e2e/bb.edn " command-name " -i smoke"))
+    (if sync-suite?
+      (println (str "  bb -f cli-e2e/bb.edn " command-name " --case sync-upload-download-mvp"))
+      (println (str "  bb -f cli-e2e/bb.edn " command-name " --skip-build --case global-help")))
+    (when sync-suite?
+      (println (str "  bb -f cli-e2e/bb.edn " command-name " --e2ee-password 'my-secret'")))
+    (flush)))
+
+(defn- test-suite!
+  [opts {:keys [suite command-name]
+         :or {suite default-suite
+              command-name "test"}}]
+  (let [suite (or suite default-suite)
+        opts (assoc opts :suite suite)]
+    (if (:help opts)
+      (do
+        (print-test-help! command-name suite)
+        {:status :help})
+      (let [started-at (System/nanoTime)
+            passed (atom 0)
+            failed (atom 0)
+            total-count (atom 0)
+            timings? (boolean (:timings opts))
+            all-step-timings (atom [])
+            detailed-case-log? (some? (:case opts))
+            parallel? (> (positive-jobs (:jobs opts)) 1)
+            base-run-command (or (:run-command opts) shell/run!)
+            run-command (if detailed-case-log?
+                          (fn [{:keys [cmd phase step-index step-total] :as command-opts}]
+                            (let [prefix (case phase
+                                           :setup (format "    [setup %d/%d]" step-index step-total)
+                                           :main (format "    [main %d/%d]" (or step-index 1) (or step-total 1))
+                                           :cleanup (format "    [cleanup %d/%d]" step-index step-total)
+                                           "    [command]")]
+                              (println (str prefix " $ " cmd))
+                              (flush)
+                              (base-run-command (assoc command-opts :stream-output? true))))
+                          base-run-command)]
+        (println "==> Running cli-e2e cases")
+        (when detailed-case-log?
+          (println (format "==> Detailed case logging enabled (--case %s)" (:case opts))))
+        (when timings?
+          (println "==> Step timing enabled (--timings)"))
+        (flush)
+        (try
+          (run! (assoc opts
+                       :run-command run-command
+                       :detailed-log? detailed-case-log?
+                       :timings? timings?
+                       :on-preflight-start (fn [_]
+                                             (println "==> Build preflight: running...")
+                                             (flush))
+                       :on-preflight-complete (fn [{:keys [status]}]
+                                                (println (case status
+                                                           :skipped "==> Build preflight: skipped (--skip-build)"
+                                                           "==> Build preflight: completed"))
+                                                (flush))
+                       :on-cases-ready (fn [{:keys [total]}]
+                                         (reset! total-count total)
+                                         (println (format "==> Prepared %d case(s), starting execution" total))
+                                         (flush))
+                       :on-case-start (fn [{:keys [index total case]}]
+                                        (println (str (progress-prefix {:parallel? parallel?
+                                                                        :index index
+                                                                        :total total}
+                                                                       "▶")
+                                                      (:id case)))
+                                        (flush))
+                       :on-case-success (fn [{:keys [index total result elapsed-ms]}]
+                                          (swap! passed inc)
+                                          (println (format "%s%s (%dms)"
+                                                           (progress-prefix {:parallel? parallel?
+                                                                             :index index
+                                                                             :total total}
+                                                                            "✓")
+                                                           (:id result)
+                                                           elapsed-ms))
+                                          (when timings?
+                                            (let [case-timings (vec (:timings result))]
+                                              (swap! all-step-timings into
+                                                     (map #(assoc % :case-id (:id result)) case-timings))
+                                              (print-case-timings! case-timings)))
+                                          (flush))
+                       :on-case-failure (fn [{:keys [index total case error elapsed-ms]}]
+                                          (swap! failed inc)
+                                          (println (format "%s%s (%dms)"
+                                                           (progress-prefix {:parallel? parallel?
+                                                                             :index index
+                                                                             :total total}
+                                                                            "✗")
+                                                           (:id case)
+                                                           elapsed-ms))
+                                          (print-failure-details! error)
+                                          (when timings?
+                                            (let [case-timings (vec (:timings (ex-data error)))]
+                                              (swap! all-step-timings into
+                                                     (map #(assoc % :case-id (:id case)) case-timings))
+                                              (print-case-timings! case-timings))))))
+          (println (format "Summary: %d passed, %d failed" @passed @failed))
+          (println (str "Selected cases: " @total-count))
+          (println (str "Duration: " (format-duration started-at)))
+          (when timings?
+            (print-slow-steps! @all-step-timings))
+          (catch Exception error
+            (let [failed-count (max 1 @failed)]
+              (println (format "Summary: %d passed, %d failed" @passed failed-count))
+              (println (str "Selected cases: " (max @total-count failed-count)))
+              (println (str "Duration: " (format-duration started-at)))
+              (when timings?
+                (print-slow-steps! @all-step-timings)))
+            (throw error)))))))
+
+(defn test!
+  [opts]
+  (test-suite! opts {:suite :non-sync
+                     :command-name "test"}))
+
+(defn test-sync!
+  [opts]
+  (test-suite! opts {:suite :sync
+                     :command-name "test-sync"}))
diff --git a/cli-e2e/src/logseq/cli/e2e/manifests.clj b/cli-e2e/src/logseq/cli/e2e/manifests.clj
new file mode 100644
index 0000000000..3032052f5d
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/manifests.clj
@@ -0,0 +1,237 @@
+(ns logseq.cli.e2e.manifests
+  (:require [clojure.edn :as edn]
+            [logseq.cli.e2e.paths :as paths]))
+
+(def suite->manifest-files
+  {:non-sync {:inventory "non_sync_inventory.edn"
+              :cases "non_sync_cases.edn"}
+   :sync {:inventory "sync_inventory.edn"
+          :cases "sync_cases.edn"}})
+
+(def default-suite :non-sync)
+
+(def ^:private append-merge-keys
+  #{:setup :cmds :cleanup :tags})
+
+(def ^:private deep-merge-keys
+  #{:vars :covers :expect})
+
+(defn read-edn-file
+  [path]
+  (edn/read-string (slurp path)))
+
+(defn- normalize-suite
+  [suite]
+  (let [suite' (cond
+                 (nil? suite) default-suite
+                 (keyword? suite) suite
+                 (string? suite) (keyword suite)
+                 :else suite)]
+    (when-not (contains? suite->manifest-files suite')
+      (throw (ex-info "Unknown cli-e2e suite"
+                      {:suite suite
+                       :known-suites (sort (keys suite->manifest-files))})))
+    suite'))
+
+(defn- manifest-file
+  [suite kind]
+  (get-in suite->manifest-files [(normalize-suite suite) kind]))
+
+(defn load-inventory
+  ([]
+   (load-inventory nil))
+  ([suite]
+   (read-edn-file (paths/spec-path (manifest-file suite :inventory)))))
+
+(defn- normalize-extends
+  [extends]
+  (let [extends' (cond
+                   (nil? extends) []
+                   (keyword? extends) [extends]
+                   (vector? extends) extends
+                   :else
+                   (throw (ex-info "Invalid :extends value in cli-e2e manifest"
+                                   {:extends extends
+                                    :expected "keyword | vector<keyword> | nil"})))
+        invalid-entries (remove keyword? extends')]
+    (when (seq invalid-entries)
+      (throw (ex-info "Invalid :extends entries in cli-e2e manifest"
+                      {:extends extends
+                       :invalid-entries (vec invalid-entries)
+                       :expected "keyword | vector<keyword> | nil"})))
+    extends'))
+
+(defn- parse-manifest
+  [manifest-data]
+  (if-not (map? manifest-data)
+    (throw (ex-info "Invalid cli-e2e manifest format"
+                    {:manifest-type (type manifest-data)
+                     :expected "{:templates {...} :cases [...]}"}))
+    (let [templates (or (:templates manifest-data) {})
+          cases (:cases manifest-data)]
+      (when-not (map? templates)
+        (throw (ex-info "Invalid cli-e2e manifest :templates format"
+                        {:templates templates
+                         :expected "map"})))
+      (when-not (vector? cases)
+        (throw (ex-info "Invalid cli-e2e manifest :cases format"
+                        {:cases cases
+                         :expected "vector"})))
+      (doseq [case cases]
+        (when-not (map? case)
+          (throw (ex-info "Invalid cli-e2e case format"
+                          {:case case
+                           :expected "map"}))))
+      {:templates templates
+       :cases cases})))
+
+(defn- reachable-template-ids
+  [templates roots]
+  (loop [stack (vec roots)
+         visited #{}]
+    (if-let [template-id (peek stack)]
+      (if (contains? visited template-id)
+        (recur (pop stack) visited)
+        (let [template (get templates template-id)
+              parent-ids (if template
+                           (normalize-extends (:extends template))
+                           [])]
+          (recur (into (pop stack) parent-ids)
+                 (conj visited template-id))))
+      visited)))
+
+(defn- lint-manifest!
+  [{:keys [templates cases]}]
+  (let [template-ids (set (keys templates))
+        template-refs (mapcat (fn [[template-id template]]
+                                (map (fn [target]
+                                       {:type :invalid-extends
+                                        :source-type :template
+                                        :source template-id
+                                        :target target})
+                                     (normalize-extends (:extends template))))
+                              templates)
+        case-refs (mapcat (fn [[index case]]
+                            (map (fn [target]
+                                   {:type :invalid-extends
+                                    :source-type :case
+                                    :source (or (:id case)
+                                                (str "case#" (inc index)))
+                                    :target target})
+                                 (normalize-extends (:extends case))))
+                          (map-indexed vector cases))
+        invalid-extends-issues (->> (concat template-refs case-refs)
+                                    (filter (fn [{:keys [target]}]
+                                              (not (contains? template-ids target)))))
+        duplicate-id-issues (->> cases
+                                 (keep :id)
+                                 frequencies
+                                 (filter (fn [[_ count]] (> count 1)))
+                                 (sort-by first)
+                                 (map (fn [[case-id count]]
+                                        {:type :duplicate-case-id
+                                         :id case-id
+                                         :count count})))
+        roots (->> cases
+                   (mapcat #(normalize-extends (:extends %)))
+                   distinct)
+        used-template-ids (reachable-template-ids templates roots)
+        unused-template-issues (->> (keys templates)
+                                    (remove used-template-ids)
+                                    sort
+                                    (map (fn [template-id]
+                                           {:type :unused-template
+                                            :template template-id})))
+        issues (vec (concat invalid-extends-issues
+                            duplicate-id-issues
+                            unused-template-issues))]
+    (when (seq issues)
+      (throw (ex-info "cli-e2e manifest lint failed"
+                      {:issues issues})))))
+
+(defn- as-seq
+  [value]
+  (cond
+    (nil? value) []
+    (sequential? value) value
+    :else [value]))
+
+(defn- deep-merge-maps
+  [left right]
+  (merge-with (fn [left-val right-val]
+                (if (and (map? left-val)
+                         (map? right-val))
+                  (deep-merge-maps left-val right-val)
+                  right-val))
+              (or left {})
+              (or right {})))
+
+(defn- merge-entry
+  [parent child]
+  (let [all-keys (set (concat (keys parent) (keys child)))]
+    (reduce (fn [acc key]
+              (let [parent-val (get parent key)
+                    child-val (get child key)]
+                (assoc acc
+                       key
+                       (cond
+                         (contains? append-merge-keys key)
+                         (if (contains? child key)
+                           (vec (concat (as-seq parent-val)
+                                        (as-seq child-val)))
+                           (vec (as-seq parent-val)))
+
+                         (contains? deep-merge-keys key)
+                         (if (contains? child key)
+                           (deep-merge-maps parent-val child-val)
+                           parent-val)
+
+                         (contains? child key)
+                         child-val
+
+                         :else
+                         parent-val))))
+            {}
+            all-keys)))
+
+(defn- resolve-template
+  [templates template-id stack]
+  (when (some #{template-id} stack)
+    (throw (ex-info "Circular template inheritance detected in cli-e2e manifest"
+                    {:template template-id
+                     :cycle (conj (vec stack) template-id)})))
+  (let [template (get templates template-id)]
+    (when-not template
+      (throw (ex-info "Unknown template in cli-e2e manifest"
+                      {:template template-id
+                       :known-templates (sort (keys templates))})))
+    (let [parent-ids (normalize-extends (:extends template))
+          parent-values (map #(resolve-template templates % (conj stack template-id))
+                             parent-ids)]
+      (reduce merge-entry
+              {}
+              (concat parent-values
+                      [(dissoc template :extends)])))))
+
+(defn- expand-manifest-cases
+  [{:keys [templates cases]}]
+  (mapv (fn [case]
+          (let [parent-ids (normalize-extends (:extends case))
+                parent-values (map #(resolve-template templates % [])
+                                   parent-ids)]
+            (reduce merge-entry
+                    {}
+                    (concat parent-values
+                            [(dissoc case :extends)]))))
+        cases))
+
+(defn load-cases
+  ([]
+   (load-cases nil))
+  ([suite]
+   (let [manifest-data (-> (manifest-file suite :cases)
+                           paths/spec-path
+                           read-edn-file
+                           parse-manifest)]
+     (lint-manifest! manifest-data)
+     (expand-manifest-cases manifest-data))))
diff --git a/cli-e2e/src/logseq/cli/e2e/paths.clj b/cli-e2e/src/logseq/cli/e2e/paths.clj
new file mode 100644
index 0000000000..7fcac572b6
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/paths.clj
@@ -0,0 +1,48 @@
+(ns logseq.cli.e2e.paths
+  (:require [babashka.fs :as fs]))
+
+(defn- ancestors
+  [path]
+  (take-while some? (iterate fs/parent path)))
+
+(defn- find-parent-named
+  [path name]
+  (some (fn [candidate]
+          (when (= name (fs/file-name candidate))
+            candidate))
+        (ancestors (fs/canonicalize path))))
+
+(def ^:private cli-e2e-root-path
+  (or (some-> *file*
+              (find-parent-named "cli-e2e")
+              str)
+      (throw (ex-info "Unable to locate cli-e2e root"
+                      {:file *file*}))))
+
+(defn cli-e2e-root
+  []
+  cli-e2e-root-path)
+
+(defn repo-root
+  []
+  (str (fs/parent cli-e2e-root-path)))
+
+(defn repo-path
+  [& segments]
+  (str (apply fs/path (repo-root) segments)))
+
+(defn cli-e2e-path
+  [& segments]
+  (str (apply fs/path (cli-e2e-root) segments)))
+
+(defn spec-path
+  [filename]
+  (cli-e2e-path "spec" filename))
+
+(defn required-artifacts
+  []
+  [(repo-path "static" "logseq-cli.js")
+   (repo-path "static" "db-worker-node.js")
+   (repo-path "dist" "db-worker-node.js")
+   (repo-path "dist" "db-worker-node-assets.json")
+   (repo-path "deps" "db-sync" "worker" "dist" "node-adapter.js")])
diff --git a/cli-e2e/src/logseq/cli/e2e/preflight.clj b/cli-e2e/src/logseq/cli/e2e/preflight.clj
new file mode 100644
index 0000000000..8e48e3f375
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/preflight.clj
@@ -0,0 +1,37 @@
+(ns logseq.cli.e2e.preflight
+  (:require [babashka.fs :as fs]
+            [logseq.cli.e2e.paths :as paths]
+            [logseq.cli.e2e.shell :as shell]))
+
+(def build-plan
+  [{:cmd "clojure -M:cljs compile logseq-cli"}
+   {:cmd "pnpm db-worker-node:compile:bundle"}
+   {:cmd "pnpm --dir deps/db-sync build:node-adapter"}])
+
+(defn missing-artifacts
+  ([]
+   (missing-artifacts (paths/required-artifacts) fs/exists?))
+  ([artifacts file-exists?]
+   (->> artifacts
+        (remove file-exists?)
+        vec)))
+
+(defn run!
+  [{:keys [skip-build run-command file-exists?]
+    :or {run-command shell/run!
+         file-exists? fs/exists?}}]
+  (if skip-build
+    {:status :skipped
+     :commands []
+     :missing-artifacts []}
+    (let [artifacts (paths/required-artifacts)]
+      (doseq [{:keys [cmd]} build-plan]
+        (run-command {:cmd cmd
+                      :dir (paths/repo-root)}))
+      (let [missing-after-build (missing-artifacts artifacts file-exists?)]
+        (when (seq missing-after-build)
+          (throw (ex-info "Build preflight completed but required artifacts are missing"
+                          {:missing-artifacts missing-after-build})))
+        {:status :ok
+         :commands build-plan
+         :missing-artifacts []}))))
diff --git a/cli-e2e/src/logseq/cli/e2e/report.clj b/cli-e2e/src/logseq/cli/e2e/report.clj
new file mode 100644
index 0000000000..33c217e0ec
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/report.clj
@@ -0,0 +1,18 @@
+(ns logseq.cli.e2e.report
+  (:require [clojure.string :as string]))
+
+(defn format-missing-coverage
+  [{:keys [missing-commands missing-options]}]
+  (str
+   "Missing coverage\n"
+   (when (seq missing-commands)
+     (str "Commands:\n"
+          (string/join "\n" (map #(str "- " %) missing-commands))
+          "\n"))
+   (string/join
+    "\n"
+    (keep (fn [[scope options]]
+            (when (seq options)
+              (str (name scope) " options:\n"
+                   (string/join "\n" (map #(str "- " %) options)))))
+          missing-options))))
diff --git a/cli-e2e/src/logseq/cli/e2e/runner.clj b/cli-e2e/src/logseq/cli/e2e/runner.clj
new file mode 100644
index 0000000000..42c619b959
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/runner.clj
@@ -0,0 +1,280 @@
+(ns logseq.cli.e2e.runner
+  (:require [babashka.fs :as fs]
+            [cheshire.core :as json]
+            [clojure.edn :as edn]
+            [clojure.string :as string]
+            [logseq.cli.e2e.paths :as paths]
+            [logseq.cli.e2e.shell :as shell]))
+
+(defn shell-escape
+  [value]
+  (let [text (str value)]
+    (if (re-find #"[^\w@%+=:,./-]" text)
+      (str "'" (string/replace text #"'" "'\"'\"'") "'")
+      text)))
+
+(def template-pattern #"\{\{([^}]+)\}\}")
+(def ^:private e2e-env {"CLI_E2E_TEST" "1"
+                        "NO_COLOR" "1"})
+
+(defn- render-string
+  [template context]
+  (string/replace template
+                  template-pattern
+                  (fn [[_ key]]
+                    (let [lookup-key (keyword (string/trim key))]
+                      (when-not (contains? context lookup-key)
+                        (throw (ex-info "Missing case template value"
+                                        {:template template
+                                         :key lookup-key
+                                         :context context})))
+                      (str (get context lookup-key))))))
+
+(defn- render-value
+  [value context]
+  (cond
+    (string? value) (render-string value context)
+    (map? value) (into {}
+                       (map (fn [[k v]]
+                              [k (render-value v context)]))
+                       value)
+    (vector? value) (mapv #(render-value % context) value)
+    (seq? value) (doall (map #(render-value % context) value))
+    :else value))
+
+(defn render-case
+  [case context]
+  (render-value case context))
+
+(defn- ensure-contains!
+  [id cmd output snippets stream]
+  (doseq [snippet (or snippets [])]
+    (let [normalize-pathish-text (fn [text]
+                                   (-> (str text)
+                                       (string/replace "\\\\" "\\")
+                                       (string/replace "\\" "/")
+                                       (string/replace "\r" "")))
+          matches? (or (string/includes? output snippet)
+                       (string/includes? (normalize-pathish-text output)
+                                         (normalize-pathish-text snippet)))]
+      (when-not matches?
+      (throw (ex-info (str stream " did not contain expected text")
+                      {:id id
+                       :cmd cmd
+                       :snippet snippet
+                       :output output
+                       :stream stream}))))))
+
+(defn- ensure-not-contains!
+  [id cmd output snippets stream]
+  (doseq [snippet (or snippets [])]
+    (when (string/includes? output snippet)
+      (throw (ex-info (str stream " contained forbidden text")
+                      {:id id
+                       :cmd cmd
+                       :snippet snippet
+                       :output output
+                       :stream stream})))))
+
+(defn- ensure-equals!
+  [id cmd actual expected label]
+  (when (and (some? expected)
+             (not= expected actual))
+    (throw (ex-info (str label " did not match")
+                    {:id id
+                     :cmd cmd
+                     :expected expected
+                     :actual actual}))))
+
+(defn- ensure-json-paths!
+  [id cmd output expected-paths]
+  (when expected-paths
+    (let [payload (json/parse-string output true)]
+      (doseq [[path expected] expected-paths]
+        (let [actual (get-in payload path)]
+          (when-not (= expected actual)
+            (throw (ex-info "stdout JSON path did not match"
+                            {:id id
+                             :cmd cmd
+                             :path path
+                             :expected expected
+                             :actual actual
+                             :payload payload}))))))))
+
+(defn- ensure-edn-paths!
+  [id cmd output expected-paths]
+  (when expected-paths
+    (let [payload (edn/read-string output)]
+      (doseq [[path expected] expected-paths]
+        (let [actual (get-in payload path)]
+          (when-not (= expected actual)
+            (throw (ex-info "stdout EDN path did not match"
+                            {:id id
+                             :cmd cmd
+                             :path path
+                             :expected expected
+                             :actual actual
+                             :payload payload}))))))))
+
+(defn assert-result!
+  [{:keys [id expect]} {:keys [cmd exit out err] :as result}]
+  (when-let [expected-exit (:exit expect)]
+    (when-not (= expected-exit exit)
+      (throw (ex-info "Unexpected exit code"
+                      {:id id
+                       :cmd cmd
+                       :expected expected-exit
+                       :actual exit
+                       :result result}))))
+  (ensure-equals! id cmd out (:stdout-equals expect) "stdout")
+  (ensure-equals! id cmd err (:stderr-equals expect) "stderr")
+  (ensure-contains! id cmd out (:stdout-contains expect) "stdout")
+  (ensure-contains! id cmd err (:stderr-contains expect) "stderr")
+  (ensure-not-contains! id cmd out (:stdout-not-contains expect) "stdout")
+  (ensure-not-contains! id cmd err (:stderr-not-contains expect) "stderr")
+  (ensure-json-paths! id cmd out (:stdout-json-paths expect))
+  (ensure-edn-paths! id cmd out (:stdout-edn-paths expect))
+  nil)
+
+(defn- default-context
+  [case context]
+  (let [tmp-dir (or (:tmp-dir context)
+                    (str (fs/create-temp-dir {:prefix (str "logseq-cli-e2e-" (:id case) "-")})))
+        root-dir (or (:root-dir context)
+                     tmp-dir)
+        config-path (or (:config-path context)
+                        (str (fs/path root-dir "cli.edn")))
+        export-path (or (:export-path context)
+                        (str (fs/path tmp-dir "graph-export.edn")))
+        graph (or (:graph context)
+                  (:graph case)
+                  (str "cli-e2e-" (:id case)))]
+    (fs/create-dirs (fs/path root-dir "graphs"))
+    (spit config-path "{:output-format :json}\n")
+    {:tmp-dir tmp-dir
+     :tmp-dir-arg (shell-escape tmp-dir)
+     :root-dir root-dir
+     :root-dir-arg (shell-escape root-dir)
+     :config-path config-path
+     :config-path-arg (shell-escape config-path)
+     :export-path export-path
+     :export-path-arg (shell-escape export-path)
+     :repo-root (paths/repo-root)
+     :repo-root-arg (shell-escape (paths/repo-root))
+     :cli (str "node " (shell-escape (paths/repo-path "static" "logseq-cli.js")))
+     :graph graph
+     :graph-arg (shell-escape graph)}))
+
+(defn- case-context
+  [case {:keys [context]}]
+  (merge (default-context case context)
+         context
+         (:vars case)))
+
+(defn- run-command!
+  [command context {:keys [run-command stdin allow-failure phase step-index step-total case-id]}]
+  (run-command {:cmd (render-string command context)
+                :dir (paths/repo-root)
+                :env e2e-env
+                :stdin (some-> stdin (render-string context))
+                :phase phase
+                :step-index step-index
+                :step-total step-total
+                :case-id case-id
+                :throw? (not allow-failure)}))
+
+(defn- elapsed-ms
+  [started-at]
+  (long (/ (- (System/nanoTime) started-at) 1000000)))
+
+(defn- run-step!
+  [timings command context {:keys [timings? phase step-index step-total]
+                            :as run-opts}]
+  (if-not timings?
+    (run-command! command context run-opts)
+    (let [started-at (System/nanoTime)]
+      (try
+        (let [result (run-command! command context run-opts)]
+          (swap! timings conj {:phase phase
+                               :step-index step-index
+                               :step-total step-total
+                               :cmd (:cmd result)
+                               :elapsed-ms (elapsed-ms started-at)
+                               :status :ok})
+          result)
+        (catch Exception error
+          (swap! timings conj {:phase phase
+                               :step-index step-index
+                               :step-total step-total
+                               :cmd (or (:cmd (ex-data error))
+                                        (render-string command context))
+                               :elapsed-ms (elapsed-ms started-at)
+                               :status :failed})
+          (throw error))))))
+
+(defn run-case!
+  [case {:keys [run-command detailed-log? timings?]
+         :or {run-command shell/run!}
+         :as opts}]
+  (let [context (case-context case opts)
+        rendered (render-case case context)
+        case-id (:id rendered)
+        timings? (boolean timings?)
+        timings (atom [])
+        cleanup-commands (vec (:cleanup rendered))
+        setup-commands (vec (:setup rendered))
+        main-commands (vec (:cmds rendered))
+        cleanup! (fn []
+                   (doseq [[idx command] (map-indexed vector cleanup-commands)]
+                     (try
+                       (run-step! timings command context {:run-command run-command
+                                                           :timings? timings?
+                                                           :allow-failure true
+                                                           :phase (when (or detailed-log? timings?) :cleanup)
+                                                           :step-index (inc idx)
+                                                           :step-total (count cleanup-commands)
+                                                           :case-id case-id})
+                       (catch Exception _
+                         nil))))]
+    (try
+      (doseq [[idx command] (map-indexed vector setup-commands)]
+        (run-step! timings command context {:run-command run-command
+                                            :timings? timings?
+                                            :phase (when (or detailed-log? timings?) :setup)
+                                            :step-index (inc idx)
+                                            :step-total (count setup-commands)
+                                            :case-id case-id}))
+      (let [main-total (count main-commands)
+            _ (when (zero? main-total)
+                (throw (ex-info "Missing case commands"
+                                {:id case-id
+                                 :case rendered})))
+            result (reduce (fn [_ [idx command]]
+                             (let [last-step? (= idx (dec main-total))]
+                               (run-step! timings command context {:run-command run-command
+                                                                   :timings? timings?
+                                                                   :stdin (when last-step? (:stdin rendered))
+                                                                   :allow-failure last-step?
+                                                                   :phase (when (or detailed-log? timings?) :main)
+                                                                   :step-index (inc idx)
+                                                                   :step-total main-total
+                                                                   :case-id case-id})))
+                           nil
+                           (map-indexed vector main-commands))]
+        (assert-result! rendered result)
+        (cleanup!)
+        (cond-> {:id case-id
+                 :status :ok
+                 :cmd (:cmd result)
+                 :result result
+                 :context context}
+          timings? (assoc :timings @timings)))
+      (catch Exception error
+        (cleanup!)
+        (if timings?
+          (throw (ex-info (.getMessage error)
+                          (assoc (or (ex-data error) {})
+                                 :timings @timings
+                                 :case-id case-id)
+                          error))
+          (throw error))))))
diff --git a/cli-e2e/src/logseq/cli/e2e/shell.clj b/cli-e2e/src/logseq/cli/e2e/shell.clj
new file mode 100644
index 0000000000..4cbc052e8d
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/shell.clj
@@ -0,0 +1,67 @@
+(ns logseq.cli.e2e.shell
+  (:require [babashka.process :as process])
+  (:import [java.io ByteArrayOutputStream OutputStream]))
+
+(defn- utf8-string
+  [^ByteArrayOutputStream payload]
+  (.toString payload "UTF-8"))
+
+(defn- capture-stream
+  [target stream-output?]
+  (let [payload (ByteArrayOutputStream.)]
+    {:payload payload
+     :stream (if stream-output?
+               (proxy [OutputStream] []
+                 (write
+                   ([byte]
+                    (.write payload byte)
+                    (.write target byte)
+                    (.flush target))
+                   ([bytes offset length]
+                    (.write payload bytes offset length)
+                    (.write target bytes offset length)
+                    (.flush target)))
+                 (flush []
+                   (.flush target))
+                 (close []
+                   (.flush target)))
+               payload)}))
+
+(defn- default-executor
+  [cmd {:keys [dir extra-env in stream-output?]}]
+  (let [{out-payload :payload
+         out-stream :stream} (capture-stream System/out stream-output?)
+        {err-payload :payload
+         err-stream :stream} (capture-stream System/err stream-output?)
+        result @(process/process {:continue true
+                                  :dir dir
+                                  :extra-env extra-env
+                                  :in in
+                                  :out out-stream
+                                  :err err-stream}
+                                 "bash"
+                                 "-c"
+                                 cmd)]
+    {:exit (:exit result 0)
+     :out (utf8-string out-payload)
+     :err (utf8-string err-payload)}))
+
+(defn run!
+  [{:keys [cmd dir env stdin executor throw? stream-output?]
+    :or {throw? true}}]
+  (let [runner (or executor default-executor)
+        result (runner cmd {:dir dir
+                            :extra-env env
+                            :in stdin
+                            :stream-output? stream-output?})
+        exit (:exit result 0)
+        payload {:cmd cmd
+                 :dir dir
+                 :exit exit
+                 :out (:out result "")
+                 :err (:err result "")}]
+    (when (and throw?
+               (not (zero? exit)))
+      (throw (ex-info "Shell command failed"
+                      payload)))
+    payload))
diff --git a/cli-e2e/src/logseq/cli/e2e/sync_fixture.clj b/cli-e2e/src/logseq/cli/e2e/sync_fixture.clj
new file mode 100644
index 0000000000..6d8b1cc6e9
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/sync_fixture.clj
@@ -0,0 +1,132 @@
+(ns logseq.cli.e2e.sync-fixture
+  (:require [babashka.fs :as fs]
+            [clojure.string :as string]
+            [logseq.cli.e2e.paths :as paths]
+            [logseq.cli.e2e.runner :as runner]
+            [logseq.cli.e2e.shell :as shell]))
+
+(def default-sync-port "18080")
+(def default-e2ee-password "11111")
+
+(def ^:private heavy-setup-patterns
+  [#"^mkdir -p '\{\{tmp-dir\}\}/home/logseq'$"
+   #"^cp ~/logseq/auth\.json\b"
+   #"prepare_sync_config\.py"
+   #"db_sync_server\.py'? start"])
+
+(def ^:private heavy-cleanup-patterns
+  [#"db_sync_server\.py'? stop"])
+
+(defn- shell-quote
+  [value]
+  (runner/shell-escape value))
+
+(defn- heavy-command?
+  [command patterns]
+  (boolean (some #(re-find % command) patterns)))
+
+(defn- case-local-setup-prefix
+  []
+  ["mkdir -p '{{tmp-dir}}/home/logseq'"
+   "cp ~/logseq/auth.json '{{tmp-dir}}/home/logseq/auth.json'"
+   "python3 '{{repo-root}}/cli-e2e/scripts/prepare_sync_config.py' --output '{{config-path}}' --auth-path '{{tmp-dir}}/home/logseq/auth.json' --http-base '{{sync-http-base}}' --ws-url '{{sync-ws-url}}'"
+   "python3 '{{repo-root}}/cli-e2e/scripts/prepare_sync_config.py' --output '{{tmp-dir}}/cli-b.edn' --auth-path '{{tmp-dir}}/home/logseq/auth.json' --http-base '{{sync-http-base}}' --ws-url '{{sync-ws-url}}'"])
+
+(def ^:private case-local-resource-markers
+  ["{{cli-home}}"
+   "{{config-path}}"
+   "{{config-path-arg}}"
+   "{{tmp-dir}}/cli-b.edn"
+   "{{auth-path}}"
+   "{{home-dir}}"])
+
+(defn- requires-case-local-resources?
+  [command]
+  (boolean (some #(string/includes? command %) case-local-resource-markers)))
+
+(defn- suite-user-keys-bootstrap-command
+  [suite-tmp-dir]
+  (let [lock-dir (shell-quote (str (fs/path suite-tmp-dir "user-rsa-keys.lock")))
+        done-file (shell-quote (str (fs/path suite-tmp-dir "user-rsa-keys.ready")))]
+    (format (str "LOCK_DIR=%s; DONE_FILE=%s; "
+                 "if [ -f \"$DONE_FILE\" ]; then exit 0; fi; "
+                 "while ! mkdir \"$LOCK_DIR\" 2>/dev/null; do [ -f \"$DONE_FILE\" ] && exit 0; sleep 0.1; done; "
+                 "trap 'rmdir \"$LOCK_DIR\" 2>/dev/null || true' EXIT; "
+                 "if [ ! -f \"$DONE_FILE\" ]; then "
+                 "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync ensure-keys --graph {{graph-arg}} --e2ee-password {{e2ee-password-arg}} --upload-keys >/dev/null && touch \"$DONE_FILE\"; "
+                 "fi")
+            lock-dir
+            done-file)))
+
+(defn before-suite!
+  [{:keys [run-command sync-port]
+    :or {run-command shell/run!
+         sync-port default-sync-port}}]
+  (let [sync-port (str sync-port)
+        suite-tmp-dir (str (fs/create-temp-dir {:prefix "logseq-cli-e2e-sync-suite-"}))
+        db-sync-pid-file (str (fs/path suite-tmp-dir "db-sync-server.pid"))
+        db-sync-log-file (str (fs/path suite-tmp-dir "db-sync-server.log"))
+        db-sync-root-dir (str (fs/path suite-tmp-dir "db-sync-server-data"))
+        sync-http-base (str "http://127.0.0.1:" sync-port)
+        sync-ws-url (str "ws://127.0.0.1:" sync-port "/sync/%s")
+        auth-path (str (fs/path (System/getProperty "user.home") "logseq" "auth.json"))
+        start-db-sync-cmd (format "python3 %s start --repo-root %s --pid-file %s --log-file %s --data-dir %s --port %s --startup-timeout-s 60 --auth-path %s"
+                                  (shell-quote (paths/repo-path "cli-e2e" "scripts" "db_sync_server.py"))
+                                  (shell-quote (paths/repo-root))
+                                  (shell-quote db-sync-pid-file)
+                                  (shell-quote db-sync-log-file)
+                                  (shell-quote db-sync-root-dir)
+                                  sync-port
+                                  (shell-quote auth-path))]
+    (run-command {:cmd start-db-sync-cmd
+                  :dir (paths/repo-root)})
+    {:suite-tmp-dir suite-tmp-dir
+     :db-sync-pid-file db-sync-pid-file
+     :db-sync-log-file db-sync-log-file
+     :db-sync-root-dir db-sync-root-dir
+     :sync-port sync-port
+     :sync-http-base sync-http-base
+     :sync-ws-url sync-ws-url}))
+
+(defn prepare-case
+  [case {:keys [suite-tmp-dir sync-port sync-http-base sync-ws-url e2ee-password]}]
+  (let [e2ee-password (or e2ee-password default-e2ee-password)
+        setup-commands (vec (:setup case))
+        insertion-point? (fn [command]
+                           (or (heavy-command? command heavy-setup-patterns)
+                               (requires-case-local-resources? command)))
+        leading-setup (->> setup-commands
+                           (take-while #(not (insertion-point? %)))
+                           vec)
+        trailing-setup (->> setup-commands
+                            (drop (count leading-setup))
+                            (remove #(heavy-command? % heavy-setup-patterns))
+                            vec)
+        bootstrap-setup (when suite-tmp-dir
+                          [(suite-user-keys-bootstrap-command suite-tmp-dir)])
+        cleanup' (->> (:cleanup case)
+                      (remove #(heavy-command? % heavy-cleanup-patterns))
+                      vec)]
+    (-> case
+        (update :vars merge {:sync-port sync-port
+                             :sync-http-base sync-http-base
+                             :sync-ws-url sync-ws-url
+                             :e2ee-password e2ee-password
+                             :e2ee-password-arg (shell-quote e2ee-password)})
+        (assoc :setup (vec (concat leading-setup
+                                   (case-local-setup-prefix)
+                                   bootstrap-setup
+                                   trailing-setup)))
+        (assoc :cleanup cleanup'))))
+
+(defn after-suite!
+  [{:keys [db-sync-pid-file]}
+   {:keys [run-command]
+    :or {run-command shell/run!}}]
+  (when (and (string? db-sync-pid-file)
+             (not (string/blank? db-sync-pid-file)))
+    (run-command {:cmd (format "python3 %s stop --pid-file %s"
+                               (shell-quote (paths/repo-path "cli-e2e" "scripts" "db_sync_server.py"))
+                               (shell-quote db-sync-pid-file))
+                  :dir (paths/repo-root)
+                  :throw? false})))
diff --git a/cli-e2e/src/logseq/cli/e2e/test_runner.clj b/cli-e2e/src/logseq/cli/e2e/test_runner.clj
new file mode 100644
index 0000000000..447015b3c4
--- /dev/null
+++ b/cli-e2e/src/logseq/cli/e2e/test_runner.clj
@@ -0,0 +1,23 @@
+(ns logseq.cli.e2e.test-runner
+  (:require [clojure.test :as test]))
+
+(def test-namespaces
+  '[logseq.cli.e2e.coverage-test
+    logseq.cli.e2e.preflight-test
+    logseq.cli.e2e.paths-test
+    logseq.cli.e2e.shell-test
+    logseq.cli.e2e.runner-test
+    logseq.cli.e2e.cleanup-test
+    logseq.cli.e2e.manifests-test
+    logseq.cli.e2e.sync-fixture-test
+    logseq.cli.e2e.main-test])
+
+(defn run!
+  [_opts]
+  (doseq [ns-sym test-namespaces]
+    (require ns-sym))
+  (let [{:keys [fail error]} (apply test/run-tests test-namespaces)]
+    (when (pos? (+ fail error))
+      (throw (ex-info "cli-e2e unit tests failed"
+                      {:fail fail
+                       :error error})))))
diff --git a/cli-e2e/test/logseq/cli/e2e/cleanup_test.clj b/cli-e2e/test/logseq/cli/e2e/cleanup_test.clj
new file mode 100644
index 0000000000..2f61fa460b
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/cleanup_test.clj
@@ -0,0 +1,149 @@
+(ns logseq.cli.e2e.cleanup-test
+  (:require [babashka.fs :as fs]
+            [clojure.test :refer [deftest is testing]]
+            [logseq.cli.e2e.cleanup :as cleanup]))
+
+(deftest list-cli-e2e-db-worker-pids-filters-processes
+  (let [shell-fn (fn [& _]
+                   {:exit 0
+                    :out (str " 101 node /repo/dist/db-worker-node.js --repo graph-a --root-dir /tmp/logseq-cli-e2e-graph-a-123/graphs --owner-source cli\n"
+                              " 202 node /repo/dist/db-worker-node.js --repo production --root-dir /tmp/production-graphs --owner-source cli\n"
+                              " 303 node /repo/static/logseq-cli.js graph list\n"
+                              " 404 /usr/bin/python3 background.py\n"
+                              " 505 node /repo/static/db-worker-node.js --repo graph-b --root-dir /private/tmp/logseq-cli-e2e-graph-b-999/graphs --owner-source cli\n")
+                    :err ""})]
+    (is (= [101 505]
+           (cleanup/list-cli-e2e-db-worker-pids {:shell-fn shell-fn}))))
+
+  (testing "throws when ps invocation fails"
+    (is (thrown-with-msg?
+         clojure.lang.ExceptionInfo
+         #"Unable to scan processes"
+         (cleanup/list-cli-e2e-db-worker-pids {:shell-fn (fn [& _]
+                                                            {:exit 1
+                                                             :out ""
+                                                             :err "permission denied"})})))))
+
+(deftest cleanup-db-worker-processes-separates-killed-and-failed
+  (let [killed (atom [])
+        result (cleanup/cleanup-db-worker-processes! {:list-pids-fn (fn [] [11 22 33])
+                                                      :kill-pid-fn (fn [pid]
+                                                                     (swap! killed conj pid)
+                                                                     (if (= pid 22)
+                                                                       :failed
+                                                                       :killed))})]
+    (is (= [11 22 33] (:found-pids result)))
+    (is (= [11 33] (:killed-pids result)))
+    (is (= [22] (:failed-pids result)))
+    (is (= [11 22 33] @killed))))
+
+(deftest cleanup-db-worker-processes-dry-run-does-not-kill
+  (let [killed (atom [])
+        result (cleanup/cleanup-db-worker-processes! {:dry-run true
+                                                      :list-pids-fn (fn [] [11 22])
+                                                      :kill-pid-fn (fn [pid]
+                                                                     (swap! killed conj pid)
+                                                                     :killed)})]
+    (is (= [11 22] (:found-pids result)))
+    (is (true? (:dry-run? result)))
+    (is (= [11 22] (:would-kill-pids result)))
+    (is (= [] (:killed-pids result)))
+    (is (= [] (:failed-pids result)))
+    (is (= [] @killed))))
+
+(deftest list-cli-e2e-db-sync-port-pids-filters-port-18080
+  (let [shell-fn (fn [& _]
+                   {:exit 0
+                    :out (str "COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME\n"
+                              "node    111 me    13u  IPv6 0x0 0t0 TCP *:18080 (LISTEN)\n"
+                              "python  222 me    13u  IPv4 0x0 0t0 TCP 127.0.0.1:18080 (LISTEN)\n"
+                              "node    333 me    13u  IPv6 0x0 0t0 TCP *:18081 (LISTEN)\n")
+                    :err ""})]
+    (is (= [111 222]
+           (cleanup/list-cli-e2e-db-sync-port-pids {:shell-fn shell-fn}))))
+
+  (testing "returns empty when no listener exists"
+    (is (= []
+           (cleanup/list-cli-e2e-db-sync-port-pids {:shell-fn (fn [& _]
+                                                                 {:exit 1
+                                                                  :out ""
+                                                                  :err ""})}))))
+
+  (testing "throws when lsof invocation fails"
+    (is (thrown-with-msg?
+         clojure.lang.ExceptionInfo
+         #"Unable to scan db-sync server port listeners"
+         (cleanup/list-cli-e2e-db-sync-port-pids {:shell-fn (fn [& _]
+                                                               {:exit 1
+                                                                :out ""
+                                                                :err "permission denied"})})))))
+
+(deftest cleanup-db-sync-port-processes-separates-killed-and-failed
+  (let [killed (atom [])
+        result (cleanup/cleanup-db-sync-port-processes! {:list-pids-fn (fn [] [44 55])
+                                                         :kill-pid-fn (fn [pid]
+                                                                        (swap! killed conj pid)
+                                                                        (if (= pid 55)
+                                                                          :failed
+                                                                          :killed))})]
+    (is (= [44 55] (:found-pids result)))
+    (is (= [44] (:killed-pids result)))
+    (is (= [55] (:failed-pids result)))
+    (is (= [44 55] @killed))))
+
+(deftest cleanup-db-sync-port-processes-dry-run-does-not-kill
+  (let [killed (atom [])
+        result (cleanup/cleanup-db-sync-port-processes! {:dry-run true
+                                                         :list-pids-fn (fn [] [44])
+                                                         :kill-pid-fn (fn [pid]
+                                                                        (swap! killed conj pid)
+                                                                        :killed)})]
+    (is (= [44] (:found-pids result)))
+    (is (true? (:dry-run? result)))
+    (is (= [44] (:would-kill-pids result)))
+    (is (= [] (:killed-pids result)))
+    (is (= [] (:failed-pids result)))
+    (is (= [] @killed))))
+
+(deftest cleanup-temp-roots-removes-only-cli-e2e-temp-roots
+  (let [tmp-root (fs/create-temp-dir {:prefix "cleanup-e2e-test-"})
+        matching-root (fs/path tmp-root "logseq-cli-e2e-case-a-123")
+        another-matching-root (fs/path tmp-root "logseq-cli-e2e-case-b-456")
+        non-matching-root (fs/path tmp-root "other-case")]
+    (try
+      (fs/create-dirs (fs/path matching-root "graphs"))
+      (fs/create-dirs (fs/path matching-root "home" "logseq"))
+      (fs/create-dirs (fs/path another-matching-root "graphs"))
+      (fs/create-dirs (fs/path non-matching-root "graphs"))
+
+      (let [result (cleanup/cleanup-temp-roots! {:tmp-root (str tmp-root)})
+            expected-dirs (sort [(str matching-root)
+                                 (str another-matching-root)])]
+        (is (= expected-dirs
+               (sort (:found-dirs result))))
+        (is (= expected-dirs
+               (sort (:removed-dirs result))))
+        (is (empty? (:failed-dirs result)))
+        (is (false? (fs/exists? matching-root)))
+        (is (false? (fs/exists? another-matching-root)))
+        (is (true? (fs/exists? non-matching-root))))
+      (finally
+        (fs/delete-tree tmp-root)))))
+
+(deftest cleanup-temp-roots-dry-run-does-not-delete
+  (let [deleted (atom [])
+        result (cleanup/cleanup-temp-roots! {:dry-run true
+                                             :list-dirs-fn (fn [] ["/tmp/logseq-cli-e2e-a"
+                                                                    "/tmp/logseq-cli-e2e-b"])
+                                             :delete-dir-fn (fn [dir]
+                                                              (swap! deleted conj dir))})]
+    (is (= ["/tmp/logseq-cli-e2e-a"
+            "/tmp/logseq-cli-e2e-b"]
+           (:found-dirs result)))
+    (is (true? (:dry-run? result)))
+    (is (= ["/tmp/logseq-cli-e2e-a"
+            "/tmp/logseq-cli-e2e-b"]
+           (:would-remove-dirs result)))
+    (is (= [] (:removed-dirs result)))
+    (is (= [] (:failed-dirs result)))
+    (is (= [] @deleted))))
diff --git a/cli-e2e/test/logseq/cli/e2e/compare_graph_queries_test.py b/cli-e2e/test/logseq/cli/e2e/compare_graph_queries_test.py
new file mode 100644
index 0000000000..cbea01104a
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/compare_graph_queries_test.py
@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+
+MODULE_PATH = Path(__file__).resolve().parents[4] / "scripts" / "compare_graph_queries.py"
+spec = importlib.util.spec_from_file_location("compare_graph_queries", MODULE_PATH)
+compare_graph_queries = importlib.util.module_from_spec(spec)
+assert spec.loader is not None
+spec.loader.exec_module(compare_graph_queries)
+
+
+def test_parse_args_supports_repeated_queries(monkeypatch) -> None:
+    monkeypatch.setattr(
+        compare_graph_queries.sys,
+        "argv",
+        [
+            "compare_graph_queries.py",
+            "--cli",
+            "/tmp/logseq-cli.js",
+            "--graph",
+            "demo",
+            "--config-a",
+            "/tmp/a.edn",
+            "--root-dir-a",
+            "/tmp/a",
+            "--config-b",
+            "/tmp/b.edn",
+            "--root-dir-b",
+            "/tmp/b",
+            "--query",
+            "[:find ?x]",
+            "--query",
+            "[:find ?y]",
+        ],
+    )
+
+    args = compare_graph_queries.parse_args()
+
+    assert args.root_dir_a == "/tmp/a"
+    assert args.root_dir_b == "/tmp/b"
+    assert args.query == ["[:find ?x]", "[:find ?y]"]
+
+
+def test_main_batches_multiple_queries_in_one_process(tmp_path: Path) -> None:
+    left_queries = []
+    right_queries = []
+    printed = []
+    cli_path = tmp_path / "logseq-cli.js"
+    cli_path.write_text("// mock cli\n")
+
+    def fake_run_query(cli_path, config_path, root_dir, graph, query):
+        record = {
+            "cli_path": str(cli_path),
+            "config_path": str(config_path),
+            "root_dir": str(root_dir),
+            "graph": graph,
+            "query": query,
+        }
+        if str(config_path).endswith("a.edn"):
+            left_queries.append(record)
+        else:
+            right_queries.append(record)
+        return {
+            "payload": {"status": "ok"},
+            "result": [{"title": query}],
+        }
+
+    compare_graph_queries.run_query = fake_run_query
+    compare_graph_queries.parse_args = lambda: SimpleNamespace(
+        cli=str(cli_path),
+        graph="demo",
+        query=["[:find ?x]", "[:find ?y]"],
+        config_a="/tmp/a.edn",
+        root_dir_a="/tmp/a",
+        config_b="/tmp/b.edn",
+        root_dir_b="/tmp/b",
+        require_result=False,
+    )
+    compare_graph_queries.print = lambda value, **kwargs: printed.append(json.loads(value))
+
+    compare_graph_queries.main()
+
+    assert [item["query"] for item in left_queries] == ["[:find ?x]", "[:find ?y]"]
+    assert [item["query"] for item in right_queries] == ["[:find ?x]", "[:find ?y]"]
+    assert printed == [
+        {
+            "status": "ok",
+            "results": {
+                "[:find ?x]": [{"title": "[:find ?x]"}],
+                "[:find ?y]": [{"title": "[:find ?y]"}],
+            },
+        }
+    ]
diff --git a/cli-e2e/test/logseq/cli/e2e/coverage_test.clj b/cli-e2e/test/logseq/cli/e2e/coverage_test.clj
new file mode 100644
index 0000000000..883a27edef
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/coverage_test.clj
@@ -0,0 +1,58 @@
+(ns logseq.cli.e2e.coverage-test
+  (:require [clojure.test :refer [deftest is testing]]
+            [logseq.cli.e2e.coverage :as coverage]
+            [logseq.cli.e2e.manifests :as manifests]))
+
+(def sample-inventory
+  {:excluded-command-prefixes ["sync" "login" "logout"]
+   :scopes {:global {:options ["--help" "--version"]}
+            :graph {:commands ["graph list" "graph create"]
+                    :options ["--file" "--type"]}}})
+
+(deftest reports-missing-commands-and-options
+  (let [cases [{:id "global-help"
+                :covers {:options {:global ["--help"]}}}
+               {:id "graph-list"
+                :covers {:commands ["graph list"]
+                         :options {:graph ["--file"]}}}]
+        report (coverage/coverage-report sample-inventory cases)]
+    (is (= ["graph create"] (:missing-commands report)))
+    (is (= ["--version"] (get-in report [:missing-options :global])))
+    (is (= ["--type"] (get-in report [:missing-options :graph])))))
+
+(deftest rejects-excluded-commands-in-inventory
+  (let [inventory (assoc-in sample-inventory [:scopes :bad :commands] ["login"])]
+    (is (thrown-with-msg?
+         clojure.lang.ExceptionInfo
+         #"Excluded commands"
+         (coverage/validate-inventory! inventory)))))
+
+(deftest rejects-excluded-commands-in-case-covers
+  (let [cases [{:id "bad-login"
+                :covers {:commands ["logout"]}}]]
+    (is (thrown-with-msg?
+         clojure.lang.ExceptionInfo
+         #"Excluded commands"
+         (coverage/validate-cases! sample-inventory cases)))))
+
+(deftest complete-coverage-is-recognized
+  (let [cases [{:id "global"
+                :covers {:options {:global ["--help" "--version"]}}}
+               {:id "graph-create"
+                :covers {:commands ["graph create"]
+                         :options {:graph ["--type"]}}}
+               {:id "graph-list"
+                :covers {:commands ["graph list"]
+                         :options {:graph ["--file"]}}}]
+        report (coverage/coverage-report sample-inventory cases)]
+    (is (coverage/complete? report))))
+
+(deftest sync-suite-manifests-cover-mvp-commands
+  (let [inventory (manifests/load-inventory :sync)
+        cases (manifests/load-cases :sync)
+        covered-commands (set (mapcat #(get-in % [:covers :commands]) cases))
+        report (coverage/coverage-report inventory cases)]
+    (is (contains? covered-commands "sync upload"))
+    (is (contains? covered-commands "sync download"))
+    (is (contains? covered-commands "sync status"))
+    (is (coverage/complete? report))))
diff --git a/cli-e2e/test/logseq/cli/e2e/main_test.clj b/cli-e2e/test/logseq/cli/e2e/main_test.clj
new file mode 100644
index 0000000000..977d6523af
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/main_test.clj
@@ -0,0 +1,812 @@
+(ns logseq.cli.e2e.main-test
+  (:require [babashka.cli :as cli]
+            [clojure.string :as string]
+            [clojure.test :refer [deftest is testing]]
+            [logseq.cli.e2e.cleanup :as cleanup]
+            [logseq.cli.e2e.main :as main]
+            [logseq.cli.e2e.manifests :as manifests]
+            [logseq.cli.e2e.sync-fixture :as sync-fixture]))
+
+(def sample-cases
+  [{:id "global-help"
+    :cmds ["node static/logseq-cli.js --help"]
+    :covers {:options {:global ["--help"]}}
+    :tags [:global :smoke]}
+   {:id "graph-create"
+    :cmds ["node static/logseq-cli.js graph create --graph demo"]
+    :covers {:commands ["graph create"]
+             :options {:graph ["--type"]}}
+    :tags [:graph]}
+   {:id "graph-list"
+    :cmds ["node static/logseq-cli.js graph list"]
+    :covers {:commands ["graph list"]
+             :options {:graph ["--file"]}}
+    :tags [:graph :smoke]}])
+
+(def complete-inventory
+  {:excluded-command-prefixes ["sync" "login" "logout"]
+   :scopes {:global {:options ["--help"]}
+            :graph {:commands ["graph create" "graph list"]
+                    :options ["--type" "--file"]}}})
+
+(def cli-parse-config
+  {:alias {:i :include
+           :h :help}
+   :spec {:jobs {:default 4}}
+   :coerce {:include []
+            :help :boolean
+            :dry-run :boolean
+            :skip-build :boolean
+            :verbose :boolean
+            :timings :boolean
+            :jobs :long}})
+
+(deftest cli-opts-parses-jobs-as-integer
+  (is (= 3
+         (:jobs (cli/parse-opts ["--jobs" "3"] cli-parse-config)))))
+
+(deftest cli-opts-defaults-jobs-to-four
+  (is (= 4
+         (:jobs (cli/parse-opts [] cli-parse-config)))))
+
+(deftest cli-opts-rejects-non-integer-jobs
+  (is (thrown-with-msg?
+       clojure.lang.ExceptionInfo
+       #"Coerce failure"
+       (cli/parse-opts ["--jobs" "nope"] cli-parse-config))))
+
+(deftest run-rejects-jobs-less-than-one
+  (is (thrown-with-msg?
+       clojure.lang.ExceptionInfo
+       #"--jobs must be a positive integer"
+       (main/run! {:inventory complete-inventory
+                   :cases sample-cases
+                   :skip-build true
+                   :jobs 0
+                   :run-command (fn [_]
+                                  {:exit 0
+                                   :out ""
+                                   :err ""})
+                   :run-case (fn [case _opts]
+                               {:id (:id case)
+                                :status :ok})}))))
+
+(deftest run-non-sync-uses-parallel-runner-when-jobs-greater-than-one
+  (let [parallel-call (atom nil)
+        serial-called? (atom false)]
+    (with-redefs [main/run-selected-cases-in-parallel! (fn [selected-cases run-case run-command opts]
+                                                         (reset! parallel-call {:case-ids (mapv :id selected-cases)
+                                                                                :run-case run-case
+                                                                                :run-command run-command
+                                                                                :jobs (:jobs opts)})
+                                                         [{:id "global-help" :status :ok}
+                                                          {:id "graph-list" :status :ok}])
+                  main/run-selected-cases! (fn [& _]
+                                             (reset! serial-called? true)
+                                             (throw (ex-info "serial runner should not be used" {})))]
+      (let [result (main/run! {:inventory complete-inventory
+                               :cases sample-cases
+                               :include ["smoke"]
+                               :skip-build true
+                               :jobs 2
+                               :run-command (fn [_]
+                                              {:exit 0
+                                               :out ""
+                                               :err ""})
+                               :run-case (fn [case _opts]
+                                           {:id (:id case)
+                                            :status :ok})})]
+        (is (= :ok (:status result)))
+        (is (= ["global-help" "graph-list"] (:case-ids @parallel-call)))
+        (is (= 2 (:jobs @parallel-call)))
+        (is (false? @serial-called?))))))
+
+(deftest run-sync-suite-uses-parallel-runner-when-jobs-greater-than-one
+  (let [parallel-call (atom nil)
+        serial-called? (atom false)
+        sync-inventory {:excluded-command-prefixes ["login" "logout"]
+                        :scopes {:sync {:commands ["sync upload" "sync status"]
+                                        :options []}}}
+        sync-cases [{:id "sync-upload"
+                     :cmds ["node static/logseq-cli.js sync upload"]
+                     :covers {:commands ["sync upload"]}}
+                    {:id "sync-status"
+                     :cmds ["node static/logseq-cli.js sync status"]
+                     :covers {:commands ["sync status"]}}]]
+    (with-redefs [main/run-selected-cases-in-parallel! (fn [selected-cases run-case run-command opts]
+                                                         (reset! parallel-call {:case-ids (mapv :id selected-cases)
+                                                                                :run-case run-case
+                                                                                :run-command run-command
+                                                                                :jobs (:jobs opts)})
+                                                         (mapv (fn [case]
+                                                                 {:id (:id case)
+                                                                  :status :ok})
+                                                               selected-cases))
+                  main/run-selected-cases! (fn [& _]
+                                             (reset! serial-called? true)
+                                             (throw (ex-info "serial runner should not be used" {})))]
+      (let [result (main/run! {:suite :sync
+                               :inventory sync-inventory
+                               :cases sync-cases
+                               :skip-build true
+                               :jobs 4
+                               :run-command (fn [_]
+                                              {:exit 0
+                                               :out ""
+                                               :err ""})
+                               :run-case (fn [case _opts]
+                                           {:id (:id case)
+                                            :status :ok})})]
+        (is (= :ok (:status result)))
+        (is (= ["sync-upload" "sync-status"] (:case-ids @parallel-call)))
+        (is (= 4 (:jobs @parallel-call)))
+        (is (false? @serial-called?))))))
+
+(deftest run-jobs-one-keeps-serial-runner
+  (let [serial-call (atom nil)
+        parallel-called? (atom false)]
+    (with-redefs [main/run-selected-cases! (fn [selected-cases run-case run-command opts]
+                                             (reset! serial-call {:case-ids (mapv :id selected-cases)
+                                                                  :run-case run-case
+                                                                  :run-command run-command
+                                                                  :jobs (:jobs opts)})
+                                             (mapv (fn [case]
+                                                     {:id (:id case)
+                                                      :status :ok})
+                                                   selected-cases))
+                  main/run-selected-cases-in-parallel! (fn [& _]
+                                                         (reset! parallel-called? true)
+                                                         (throw (ex-info "parallel runner should not be used" {})))]
+      (let [result (main/run! {:inventory complete-inventory
+                               :cases sample-cases
+                               :include ["smoke"]
+                               :skip-build true
+                               :jobs 1
+                               :run-command (fn [_]
+                                              {:exit 0
+                                               :out ""
+                                               :err ""})
+                               :run-case (fn [case _opts]
+                                           {:id (:id case)
+                                            :status :ok})})]
+        (is (= :ok (:status result)))
+        (is (= ["global-help" "graph-list"] (:case-ids @serial-call)))
+        (is (= 1 (:jobs @serial-call)))
+        (is (false? @parallel-called?))))))
+
+(deftest parallel-runner-collects-completions-before-rethrowing-failure
+  (let [started (atom [])
+        finished (atom [])
+        started-latch (java.util.concurrent.CountDownLatch. 2)
+        release-success (promise)
+        cases [{:id "global-help"}
+               {:id "graph-list"}]
+        error (try
+                (main/run-selected-cases-in-parallel!
+                 cases
+                 (fn [case _opts]
+                   (swap! started conj (:id case))
+                   (.countDown started-latch)
+                   (.await started-latch)
+                   (if (= "graph-list" (:id case))
+                     (do
+                       (swap! finished conj [:failed (:id case)])
+                       (deliver release-success true)
+                       (throw (ex-info "boom" {:id (:id case)})))
+                     (do
+                       @release-success
+                       (swap! finished conj [:ok (:id case)])
+                       {:id (:id case)
+                        :status :ok})))
+                 (fn [_]
+                   {:exit 0
+                    :out ""
+                    :err ""})
+                 {:jobs 2})
+                nil
+                (catch Exception ex
+                  ex))]
+    (is (instance? Exception error))
+    (is (= #{"global-help" "graph-list"}
+           (set @started)))
+    (is (= #{[:ok "global-help"]
+             [:failed "graph-list"]}
+           (set @finished)))))
+
+(deftest parallel-runner-elapsed-ms-starts-when-case-begins-running
+  (let [events (atom [])]
+    (main/run-selected-cases-in-parallel!
+     [{:id "slow-1"}
+      {:id "slow-2"}
+      {:id "fast-after-queue"}]
+     (fn [test-case _opts]
+       (clojure.core/case (:id test-case)
+         "slow-1" (Thread/sleep 180)
+         "slow-2" (Thread/sleep 180)
+         "fast-after-queue" (Thread/sleep 10))
+       {:id (:id test-case)
+        :status :ok})
+     (fn [_]
+       {:exit 0
+        :out ""
+        :err ""})
+     {:jobs 2
+      :on-case-success (fn [payload]
+                         (swap! events conj [(:id (:result payload)) (:elapsed-ms payload)]))})
+    (let [elapsed-map (into {} @events)]
+      (is (< (get elapsed-map "fast-after-queue" 1000) 120)
+          "queued case should measure only its own execution time, not time spent waiting in the pool")
+      (is (>= (get elapsed-map "slow-1" 0) 150))
+      (is (>= (get elapsed-map "slow-2" 0) 150)))))
+
+(deftest select-cases-supports-case-id
+  (is (= ["graph-create"]
+         (mapv :id (main/select-cases sample-cases {:case "graph-create"})))))
+
+(deftest select-cases-supports-include-tags
+  (is (= ["global-help" "graph-list"]
+         (mapv :id (main/select-cases sample-cases {:include ["smoke"]})))))
+
+(deftest run-fails-on-missing-coverage-before-case-execution
+  (let [ran? (atom false)]
+    (is (thrown-with-msg?
+         clojure.lang.ExceptionInfo
+         #"Missing coverage"
+         (main/run! {:inventory complete-inventory
+                     :cases [{:id "global-help"
+                              :cmds ["node static/logseq-cli.js --help"]
+                              :covers {:options {:global ["--help"]}}}]
+                     :skip-build true
+                     :run-command (fn [_]
+                                    (reset! ran? true)
+                                    {:exit 0
+                                     :out ""
+                                     :err ""})})))
+    (is (false? @ran?))))
+
+(deftest run-succeeds-when-coverage-is-complete
+  (let [result (main/run! {:inventory complete-inventory
+                           :cases [{:id "global-help"
+                                    :cmds ["node static/logseq-cli.js --help"]
+                                    :covers {:options {:global ["--help"]}}}
+                                   {:id "graph-create"
+                                    :cmds ["node static/logseq-cli.js graph create --type markdown"]
+                                    :covers {:commands ["graph create"]
+                                             :options {:graph ["--type"]}}}
+                                   {:id "graph-list"
+                                    :cmds ["node static/logseq-cli.js graph list --file demo.edn"]
+                                    :covers {:commands ["graph list"]
+                                             :options {:graph ["--file"]}}}]
+                           :skip-build true
+                           :run-command (fn [_]
+                                          {:exit 0
+                                           :out ""
+                                           :err ""})})]
+    (is (= :ok (:status result)))
+    (is (= 3 (count (:cases result))))))
+
+(deftest targeted-run-skips-full-coverage-check
+  (let [executed (atom [])]
+    (let [result (main/run! {:inventory complete-inventory
+                             :cases [{:id "global-help"
+                                      :cmds ["node static/logseq-cli.js --help"]
+                                      :covers {:options {:global ["--help"]}}}
+                                     {:id "graph-create"
+                                      :cmds ["node static/logseq-cli.js graph create --graph demo"]
+                                      :covers {:commands ["graph create"]
+                                               :options {:graph ["--type"]}}}]
+                             :case "global-help"
+                             :skip-build true
+                             :run-command (fn [_]
+                                            {:exit 0
+                                             :out ""
+                                             :err ""})
+                             :run-case (fn [case _opts]
+                                         (swap! executed conj (:id case))
+                                         {:id (:id case)
+                                          :status :ok})})]
+      (is (= :ok (:status result)))
+      (is (= ["global-help"] @executed)))))
+
+(deftest run-invokes-case-progress-hooks
+  (let [events (atom [])]
+    (main/run! {:inventory complete-inventory
+                :cases sample-cases
+                :include ["smoke"]
+                :skip-build true
+                :run-command (fn [_]
+                               {:exit 0
+                                :out ""
+                                :err ""})
+                :run-case (fn [case _opts]
+                            {:id (:id case)
+                             :status :ok})
+                :on-case-start (fn [{:keys [index total case]}]
+                                 (swap! events conj [:start index total (:id case)]))
+                :on-case-success (fn [{:keys [index total result]}]
+                                   (swap! events conj [:ok index total (:id result)]))})
+    (is (= [[:start 1 2 "global-help"]
+            [:ok 1 2 "global-help"]
+            [:start 2 2 "graph-list"]
+            [:ok 2 2 "graph-list"]]
+           @events))))
+
+(deftest run-loads-non-sync-suite-by-default
+  (let [suite-calls (atom [])]
+    (with-redefs [manifests/load-inventory (fn [suite]
+                                             (swap! suite-calls conj [:inventory suite])
+                                             complete-inventory)
+                  manifests/load-cases (fn [suite]
+                                         (swap! suite-calls conj [:cases suite])
+                                         sample-cases)]
+      (let [result (main/run! {:skip-build true
+                               :run-command (fn [_]
+                                              {:exit 0
+                                               :out ""
+                                               :err ""})
+                               :run-case (fn [case _opts]
+                                           {:id (:id case)
+                                            :status :ok})})]
+        (is (= :ok (:status result))))
+      (is (= [[:inventory :non-sync]
+              [:cases :non-sync]]
+             @suite-calls)))))
+
+(deftest run-loads-sync-suite-when-explicit
+  (let [suite-calls (atom [])
+        sync-inventory {:excluded-command-prefixes ["login" "logout"]
+                        :scopes {:sync {:commands ["sync upload"]
+                                        :options []}}}
+        sync-cases [{:id "sync-upload"
+                     :cmds ["node static/logseq-cli.js sync upload"]
+                     :covers {:commands ["sync upload"]}}]]
+    (with-redefs [manifests/load-inventory (fn [suite]
+                                             (swap! suite-calls conj [:inventory suite])
+                                             sync-inventory)
+                  manifests/load-cases (fn [suite]
+                                         (swap! suite-calls conj [:cases suite])
+                                         sync-cases)]
+      (let [result (main/run! {:suite :sync
+                               :skip-build true
+                               :run-command (fn [_]
+                                              {:exit 0
+                                               :out ""
+                                               :err ""})
+                               :run-case (fn [case _opts]
+                                           {:id (:id case)
+                                            :status :ok})})]
+        (is (= :ok (:status result))))
+      (is (= [[:inventory :sync]
+              [:cases :sync]]
+             @suite-calls)))))
+
+(deftest run-sync-suite-uses-suite-fixture-once-with-parallel-runner
+  (let [before-called (atom 0)
+        after-called (atom 0)
+        prepared-case-ids (atom [])
+        run-case-seen (atom [])
+        parallel-call (atom nil)
+        sync-inventory {:excluded-command-prefixes ["login" "logout"]
+                        :scopes {:sync {:commands ["sync upload" "sync status"]
+                                        :options []}}}
+        sync-cases [{:id "sync-upload"
+                     :cmds ["node static/logseq-cli.js sync upload"]
+                     :covers {:commands ["sync upload"]}}
+                    {:id "sync-status"
+                     :cmds ["node static/logseq-cli.js sync status"]
+                     :covers {:commands ["sync status"]}}]]
+    (with-redefs [sync-fixture/before-suite! (fn [_]
+                                               (swap! before-called inc)
+                                               {:suite :sync})
+                  sync-fixture/prepare-case (fn [case _suite-context]
+                                              (swap! prepared-case-ids conj (:id case))
+                                              (assoc case :prepared? true))
+                  sync-fixture/after-suite! (fn [_ _]
+                                              (swap! after-called inc))
+                  main/run-selected-cases-in-parallel! (fn [selected-cases run-case run-command opts]
+                                                         (reset! parallel-call {:case-ids (mapv :id selected-cases)
+                                                                                :jobs (:jobs opts)})
+                                                         (mapv (fn [case]
+                                                                 (run-case case {:run-command run-command}))
+                                                               selected-cases))]
+      (let [result (main/run! {:suite :sync
+                               :inventory sync-inventory
+                               :cases sync-cases
+                               :skip-build true
+                               :jobs 2
+                               :run-command (fn [_]
+                                              {:exit 0
+                                               :out ""
+                                               :err ""})
+                               :run-case (fn [case _opts]
+                                           (swap! run-case-seen conj [(:id case) (:prepared? case)])
+                                           {:id (:id case)
+                                            :status :ok})})]
+        (is (= :ok (:status result)))))
+    (is (= 1 @before-called))
+    (is (= 1 @after-called))
+    (is (= ["sync-upload" "sync-status"] (:case-ids @parallel-call)))
+    (is (= 2 (:jobs @parallel-call)))
+    (is (= ["sync-upload" "sync-status"] @prepared-case-ids))
+    (is (= [["sync-upload" true]
+            ["sync-status" true]]
+           @run-case-seen))))
+
+(deftest run-sync-suite-forwards-e2ee-password-to-prepare-case
+  (let [seen-passwords (atom [])
+        sync-inventory {:excluded-command-prefixes ["login" "logout"]
+                        :scopes {:sync {:commands ["sync status"]
+                                        :options []}}}
+        sync-cases [{:id "sync-status"
+                     :cmds ["node static/logseq-cli.js sync status"]
+                     :covers {:commands ["sync status"]}}]]
+    (with-redefs [sync-fixture/before-suite! (fn [_]
+                                               {:suite :sync})
+                  sync-fixture/prepare-case (fn [case suite-context]
+                                              (swap! seen-passwords conj (:e2ee-password suite-context))
+                                              case)
+                  sync-fixture/after-suite! (fn [_ _] nil)]
+      (main/run! {:suite :sync
+                  :inventory sync-inventory
+                  :cases sync-cases
+                  :skip-build true
+                  :e2ee-password "abc 123"
+                  :run-command (fn [_]
+                                 {:exit 0
+                                  :out ""
+                                  :err ""})
+                  :run-case (fn [case _opts]
+                              {:id (:id case)
+                               :status :ok})}))
+    (is (= ["abc 123"] @seen-passwords))))
+
+(deftest list-cases-defaults-to-non-sync
+  (let [selected-suite (atom nil)
+        output (with-out-str
+                 (with-redefs [manifests/load-cases (fn [suite]
+                                                      (reset! selected-suite suite)
+                                                      [{:id "non-sync-case"}])]
+                   (main/list-cases! {})))]
+    (is (= :non-sync @selected-suite))
+    (is (string/includes? output "non-sync-case"))))
+
+(deftest list-sync-cases-uses-sync-suite
+  (let [selected-suite (atom nil)
+        output (with-out-str
+                 (with-redefs [manifests/load-cases (fn [suite]
+                                                      (reset! selected-suite suite)
+                                                      [{:id "sync-case"}])]
+                   (main/list-sync-cases! {})))]
+    (is (= :sync @selected-suite))
+    (is (string/includes? output "sync-case"))))
+
+(deftest test-prints-progress-and-summary
+  (let [output (with-out-str
+                 (main/test! {:inventory complete-inventory
+                              :cases sample-cases
+                              :include ["smoke"]
+                              :skip-build true
+                              :run-command (fn [_]
+                                             {:exit 0
+                                              :out ""
+                                              :err ""})
+                              :run-case (fn [case _opts]
+                                          {:id (:id case)
+                                           :status :ok
+                                           :cmd (last (:cmds case))})}))]
+    (is (string/includes? output "==> Running cli-e2e cases"))
+    (is (string/includes? output "==> Build preflight: running..."))
+    (is (string/includes? output "==> Build preflight: skipped (--skip-build)"))
+    (is (string/includes? output "==> Prepared 2 case(s), starting execution"))
+    (is (string/includes? output "[1/2] ▶ global-help"))
+    (is (string/includes? output "[1/2] ✓ global-help"))
+    (is (string/includes? output "[2/2] ▶ graph-list"))
+    (is (string/includes? output "[2/2] ✓ graph-list"))
+    (is (string/includes? output "Summary: 2 passed, 0 failed"))))
+
+(deftest test-parallel-output-omits-meaningless-index-prefixes
+  (let [output (with-out-str
+                 (main/test! {:inventory complete-inventory
+                              :cases sample-cases
+                              :include ["smoke"]
+                              :skip-build true
+                              :jobs 2
+                              :run-command (fn [_]
+                                             {:exit 0
+                                              :out ""
+                                              :err ""})
+                              :run-case (fn [case _opts]
+                                          (Thread/sleep (if (= "global-help" (:id case)) 25 5))
+                                          {:id (:id case)
+                                           :status :ok})}))]
+    (is (string/includes? output "▶ global-help"))
+    (is (string/includes? output "✓ global-help"))
+    (is (string/includes? output "✓ graph-list"))
+    (is (not (string/includes? output "[1/2]")))
+    (is (not (string/includes? output "[2/2]")))))
+
+(deftest test-timings-prints-step-details-and-slow-summary
+  (let [output (with-out-str
+                 (main/test! {:inventory complete-inventory
+                              :cases sample-cases
+                              :include ["smoke"]
+                              :skip-build true
+                              :timings true
+                              :run-command (fn [_]
+                                             {:exit 0
+                                              :out ""
+                                              :err ""})
+                              :run-case (fn [case _opts]
+                                          (if (= "global-help" (:id case))
+                                            {:id "global-help"
+                                             :status :ok
+                                             :timings [{:phase :setup
+                                                        :step-index 1
+                                                        :step-total 1
+                                                        :elapsed-ms 12
+                                                        :status :ok
+                                                        :cmd "setup-global"}
+                                                       {:phase :main
+                                                        :step-index 1
+                                                        :step-total 1
+                                                        :elapsed-ms 55
+                                                        :status :ok
+                                                        :cmd "main-global"}]}
+                                            {:id "graph-list"
+                                             :status :ok
+                                             :timings [{:phase :main
+                                                        :step-index 1
+                                                        :step-total 1
+                                                        :elapsed-ms 210
+                                                        :status :ok
+                                                        :cmd "main-graph-list"}]}))}))]
+    (is (string/includes? output "==> Step timing enabled (--timings)"))
+    (is (string/includes? output "step timings:"))
+    (is (string/includes? output "Slow steps (top 10):"))
+    (is (string/includes? output "main-graph-list"))))
+
+(deftest test-without-timings-keeps-output-concise
+  (let [output (with-out-str
+                 (main/test! {:inventory complete-inventory
+                              :cases sample-cases
+                              :include ["smoke"]
+                              :skip-build true
+                              :run-command (fn [_]
+                                             {:exit 0
+                                              :out ""
+                                              :err ""})
+                              :run-case (fn [case _opts]
+                                          {:id (:id case)
+                                           :status :ok
+                                           :timings [{:phase :main
+                                                      :step-index 1
+                                                      :step-total 1
+                                                      :elapsed-ms 88
+                                                      :status :ok
+                                                      :cmd "hidden-step"}]})}))]
+    (is (not (string/includes? output "==> Step timing enabled (--timings)")))
+    (is (not (string/includes? output "step timings:")))
+    (is (not (string/includes? output "Slow steps (top 10):")))))
+
+(deftest test-sync-timings-prints-step-details-and-slow-summary
+  (let [sync-inventory {:excluded-command-prefixes ["login" "logout"]
+                        :scopes {:sync {:commands ["sync status"]
+                                        :options []}}}
+        sync-cases [{:id "sync-status-case"
+                     :cmds ["node static/logseq-cli.js sync status"]
+                     :covers {:commands ["sync status"]}}]
+        output (with-out-str
+                 (main/test-sync! {:inventory sync-inventory
+                                   :cases sync-cases
+                                   :skip-build true
+                                   :timings true
+                                   :run-command (fn [_]
+                                                  {:exit 0
+                                                   :out ""
+                                                   :err ""})
+                                   :run-case (fn [case _opts]
+                                               {:id (:id case)
+                                                :status :ok
+                                                :timings [{:phase :setup
+                                                           :step-index 1
+                                                           :step-total 1
+                                                           :elapsed-ms 10
+                                                           :status :ok
+                                                           :cmd "sync-setup"}
+                                                          {:phase :main
+                                                           :step-index 1
+                                                           :step-total 1
+                                                           :elapsed-ms 150
+                                                           :status :ok
+                                                           :cmd "sync-main"}
+                                                          {:phase :cleanup
+                                                           :step-index 1
+                                                           :step-total 1
+                                                           :elapsed-ms 20
+                                                           :status :ok
+                                                           :cmd "sync-cleanup"}]})}))]
+    (is (string/includes? output "==> Running cli-e2e cases"))
+    (is (string/includes? output "==> Step timing enabled (--timings)"))
+    (is (string/includes? output "step timings:"))
+    (is (string/includes? output "Slow steps (top 10):"))
+    (is (string/includes? output "sync-main"))))
+
+(deftest test-help-prints-usage-and-skips-execution
+  (let [ran? (atom false)
+        result (atom nil)
+        output (with-out-str
+                 (reset! result
+                         (main/test! {:help true
+                                      :run-command (fn [_]
+                                                     (reset! ran? true)
+                                                     {:exit 0
+                                                      :out ""
+                                                      :err ""})
+                                      :run-case (fn [_ _]
+                                                  (reset! ran? true)
+                                                  {:id "unexpected"
+                                                   :status :ok})}))) ]
+    (is (= :help (:status @result)))
+    (is (false? @ran?))
+    (is (string/includes? output "Usage: bb -f cli-e2e/bb.edn test [options]"))
+    (is (string/includes? output "--skip-build"))
+    (is (not (string/includes? output "--force-build")))
+    (is (string/includes? output "--include TAG"))
+    (is (string/includes? output "--case ID"))
+    (is (string/includes? output "--jobs N"))
+    (is (string/includes? output "Run up to N non-sync cases in parallel"))
+    (is (string/includes? output "--skip-build --jobs 4"))
+    (is (string/includes? output "Default: 4"))
+    (is (string/includes? output "--timings"))
+    (is (not (string/includes? output "--e2ee-password")))))
+
+(deftest test-sync-help-prints-usage-and-skips-execution
+  (let [ran? (atom false)
+        result (atom nil)
+        output (with-out-str
+                 (reset! result
+                         (main/test-sync! {:help true
+                                           :run-command (fn [_]
+                                                          (reset! ran? true)
+                                                          {:exit 0
+                                                           :out ""
+                                                           :err ""})
+                                           :run-case (fn [_ _]
+                                                       (reset! ran? true)
+                                                       {:id "unexpected"
+                                                        :status :ok})})))]
+    (is (= :help (:status @result)))
+    (is (false? @ran?))
+    (is (string/includes? output "Usage: bb -f cli-e2e/bb.edn test-sync [options]"))
+    (is (string/includes? output "--skip-build"))
+    (is (not (string/includes? output "--force-build")))
+    (is (string/includes? output "--include TAG"))
+    (is (string/includes? output "--case ID"))
+    (is (string/includes? output "--jobs N"))
+    (is (string/includes? output "Run up to N sync cases in parallel"))
+    (is (string/includes? output "--jobs 4"))
+    (is (string/includes? output "bb -f cli-e2e/bb.edn test-sync"))
+    (is (string/includes? output "--case sync-upload-download-mvp"))
+    (is (not (string/includes? output "--skip-build --case sync-upload-download-mvp")))
+    (is (string/includes? output "Default: 4"))
+    (is (string/includes? output "--timings"))
+    (is (string/includes? output "--e2ee-password VALUE"))
+    (is (string/includes? output "Default: 11111"))))
+
+(deftest run-does-not-pass-force-build-to-preflight
+  (let [preflight-call (atom nil)]
+    (with-redefs [logseq.cli.e2e.preflight/run! (fn [opts]
+                                                  (reset! preflight-call opts)
+                                                  {:status :ok
+                                                   :commands []
+                                                   :missing-artifacts []})]
+      (let [result (main/run! {:inventory complete-inventory
+                               :cases sample-cases
+                               :include ["smoke"]
+                               :skip-build false
+                               :force-build true
+                               :run-command (fn [_]
+                                              {:exit 0
+                                               :out ""
+                                               :err ""})
+                               :run-case (fn [case _opts]
+                                           {:id (:id case)
+                                            :status :ok})})]
+        (is (= :ok (:status result)))
+        (is (not (contains? @preflight-call :force-build)))))))
+
+(deftest test-single-case-enables-detailed-command-logging
+  (let [command-opts (atom nil)
+        output (with-out-str
+                 (main/test! {:inventory complete-inventory
+                              :cases [{:id "global-help"
+                                       :cmds ["node static/logseq-cli.js --help"]
+                                       :covers {:options {:global ["--help"]}}}]
+                              :case "global-help"
+                              :skip-build true
+                              :run-command (fn [{:keys [cmd] :as opts}]
+                                             (reset! command-opts opts)
+                                             {:cmd cmd
+                                              :exit 0
+                                              :out "ok"
+                                              :err ""})
+                              :run-case (fn [case {:keys [run-command]}]
+                                          (let [result (run-command {:cmd (first (:cmds case))
+                                                                     :phase :main
+                                                                     :step-index 1
+                                                                     :step-total 1})]
+                                            {:id (:id case)
+                                             :status :ok
+                                             :cmd (:cmd result)}) )}))]
+    (is (string/includes? output "==> Detailed case logging enabled (--case global-help)"))
+    (is (string/includes? output "    [main 1/1] $ node static/logseq-cli.js --help"))
+    (is (true? (:stream-output? @command-opts)))))
+
+(deftest cleanup-help-prints-usage
+  (let [output (with-out-str (main/cleanup! {:help true}))]
+    (is (string/includes? output "Usage: bb -f cli-e2e/bb.edn cleanup"))
+    (is (string/includes? output "Terminate cli-e2e db-worker-node processes"))
+    (is (string/includes? output "Terminate db-sync server listeners on port 18080"))
+    (is (string/includes? output "Remove cli-e2e temp roots"))
+    (is (string/includes? output "--dry-run"))))
+
+(deftest cleanup-prints-summary-and-returns-status
+  (with-redefs [cleanup/cleanup-db-worker-processes! (fn [_] {:found-pids [101 202]
+                                                               :killed-pids [101]
+                                                               :failed-pids [202]})
+                cleanup/cleanup-db-sync-port-processes! (fn [_] {:found-pids [303]
+                                                                  :killed-pids [303]
+                                                                  :failed-pids []})
+                cleanup/cleanup-temp-roots! (fn [_] {:found-dirs ["/tmp/logseq-cli-e2e-a"
+                                                                   "/tmp/logseq-cli-e2e-b"]
+                                                      :removed-dirs ["/tmp/logseq-cli-e2e-a"]
+                                                      :failed-dirs ["/tmp/logseq-cli-e2e-b"]})]
+    (let [result (atom nil)
+          output (with-out-str
+                   (reset! result (main/cleanup! {})))]
+      (is (= :ok (:status @result)))
+      (is (= [101] (get-in @result [:processes :killed-pids])))
+      (is (= [303] (get-in @result [:db-sync-port-processes :killed-pids])))
+      (is (= ["/tmp/logseq-cli-e2e-a"] (get-in @result [:temp-roots :removed-dirs])))
+      (is (string/includes? output "db-worker-node processes: found 2, killed 1, failed 1"))
+      (is (string/includes? output "db-sync server processes (port 18080): found 1, killed 1, failed 0"))
+      (is (string/includes? output "temp roots: found 2, removed 1, failed 1")))))
+
+(deftest cleanup-dry-run-prints-summary-and-passes-option
+  (let [process-opts (atom nil)
+        db-sync-opts (atom nil)
+        dir-opts (atom nil)]
+    (with-redefs [cleanup/cleanup-db-worker-processes! (fn [opts]
+                                                          (reset! process-opts opts)
+                                                          {:dry-run? true
+                                                           :found-pids [101 202]
+                                                           :would-kill-pids [101 202]
+                                                           :killed-pids []
+                                                           :failed-pids []})
+                  cleanup/cleanup-db-sync-port-processes! (fn [opts]
+                                                            (reset! db-sync-opts opts)
+                                                            {:dry-run? true
+                                                             :found-pids [303]
+                                                             :would-kill-pids [303]
+                                                             :killed-pids []
+                                                             :failed-pids []})
+                  cleanup/cleanup-temp-roots! (fn [opts]
+                                                (reset! dir-opts opts)
+                                                {:dry-run? true
+                                                 :found-dirs ["/tmp/logseq-cli-e2e-a"]
+                                                 :would-remove-dirs ["/tmp/logseq-cli-e2e-a"]
+                                                 :removed-dirs []
+                                                 :failed-dirs []})]
+      (let [result (atom nil)
+            output (with-out-str
+                     (reset! result (main/cleanup! {:dry-run true})))]
+        (is (= {:dry-run true} @process-opts))
+        (is (= {:dry-run true} @db-sync-opts))
+        (is (= {:dry-run true} @dir-opts))
+        (is (= :ok (:status @result)))
+        (is (true? (get-in @result [:processes :dry-run?])))
+        (is (true? (get-in @result [:db-sync-port-processes :dry-run?])))
+        (is (true? (get-in @result [:temp-roots :dry-run?])))
+        (is (string/includes? output "[dry-run] db-worker-node processes: found 2, would kill 2"))
+        (is (string/includes? output "[dry-run] db-sync server processes (port 18080): found 1, would kill 1"))
+        (is (string/includes? output "[dry-run] temp roots: found 1, would remove 1"))))))
diff --git a/cli-e2e/test/logseq/cli/e2e/manifests_test.clj b/cli-e2e/test/logseq/cli/e2e/manifests_test.clj
new file mode 100644
index 0000000000..70f535230b
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/manifests_test.clj
@@ -0,0 +1,225 @@
+(ns logseq.cli.e2e.manifests-test
+  (:require [clojure.test :refer [deftest is testing]]
+            [logseq.cli.e2e.manifests :as manifests]))
+
+(deftest load-cases-requires-new-map-format
+  (with-redefs [manifests/read-edn-file (fn [_]
+                                          [{:id "legacy-a"}
+                                           {:id "legacy-b"}])]
+    (let [error (try
+                  (manifests/load-cases :non-sync)
+                  nil
+                  (catch clojure.lang.ExceptionInfo error
+                    error))]
+      (is (some? error))
+      (is (re-find #"Invalid cli-e2e manifest format" (.getMessage error)))
+      (is (= "{:templates {...} :cases [...]}"
+             (:expected (ex-data error)))))))
+
+(deftest load-cases-merges-templates-and-cases-by-rules
+  (with-redefs [manifests/read-edn-file
+                (fn [_]
+                  {:templates
+                   {:base {:setup ["setup-a"]
+                           :cmds ["cmd-a"]
+                           :cleanup ["cleanup-a"]
+                           :tags [:base]
+                           :vars {:nested {:left 1}
+                                  :only-base true}
+                           :covers {:commands ["base-command"]
+                                    :options {:global ["--base"]}}
+                           :expect {:stdout-json-paths {[:status] "ok"
+                                                        [:data :base] 1}}
+                           :graph "base-graph"}
+                    :addon {:setup ["setup-b"]
+                            :cmds ["cmd-b"]
+                            :cleanup ["cleanup-b"]
+                            :tags [:addon]
+                            :vars {:nested {:right 2}}
+                            :covers {:options {:graph ["--addon"]}}
+                            :expect {:stdout-json-paths {[:data :addon] 2}}
+                            :graph "addon-graph"}
+                    :shared {:setup ["setup-shared"]
+                             :cmds ["cmd-shared"]
+                             :cleanup ["cleanup-shared"]
+                             :tags [:shared]
+                             :vars {:nested {:shared 9}}
+                             :graph "shared-graph"}}
+                   :cases
+                   [{:id "single-parent"
+                     :extends :base
+                     :cmds ["cmd-case"]
+                     :expect {:stdout-json-paths {[:data :case] 3}}
+                     :graph "single-parent-graph"}
+                    {:id "multi-parent"
+                     :extends [:base :addon]
+                     :setup ["setup-case"]
+                     :cmds ["cmd-case"]
+                     :cleanup ["cleanup-case"]
+                     :tags [:case]
+                     :vars {:nested {:leaf 3}
+                            :only-case true}
+                     :covers {:commands ["case-command"]
+                              :options {:graph ["--case"]}}
+                     :expect {:stdout-json-paths {[:data :case] 3}}
+                     :graph "case-graph"}
+                    {:id "negative-case"
+                     :extends :shared
+                     :expect {:exit 1
+                              :stdout-json-paths {[:error :code] "boom"}}
+                     :graph "negative-graph"}]})]
+    (let [[single-parent multi-parent negative-case] (manifests/load-cases :sync)]
+      (testing "supports :extends keyword"
+        (is (= "single-parent" (:id single-parent)))
+        (is (= ["cmd-a" "cmd-case"] (:cmds single-parent)))
+        (is (= "single-parent-graph" (:graph single-parent))))
+      (testing "append merge keys"
+        (is (= ["setup-a" "setup-b" "setup-case"] (:setup multi-parent)))
+        (is (= ["cmd-a" "cmd-b" "cmd-case"] (:cmds multi-parent)))
+        (is (= ["cleanup-a" "cleanup-b" "cleanup-case"] (:cleanup multi-parent)))
+        (is (= [:base :addon :case] (:tags multi-parent))))
+      (testing "deep merge keys"
+        (is (= {:nested {:left 1 :right 2 :leaf 3}
+                :only-base true
+                :only-case true}
+               (:vars multi-parent)))
+        (is (= {:commands ["case-command"]
+                :options {:global ["--base"]
+                          :graph ["--case"]}}
+               (:covers multi-parent)))
+        (is (= {[:status] "ok"
+                [:data :base] 1
+                [:data :addon] 2
+                [:data :case] 3}
+               (get-in multi-parent [:expect :stdout-json-paths]))))
+      (testing "child expect overrides inherited maps when parent omits them"
+        (is (= {:exit 1
+                :stdout-json-paths {[:error :code] "boom"}}
+               (:expect negative-case))))
+      (testing "base templates can omit happy-path defaults"
+        (is (= ["setup-shared"] (:setup negative-case)))
+        (is (= ["cmd-shared"] (:cmds negative-case)))
+        (is (= ["cleanup-shared"] (:cleanup negative-case))))
+      (testing "scalar keys are overridden by child"
+        (is (= "case-graph" (:graph multi-parent)))))))
+
+(deftest load-cases-detects-circular-template-inheritance-with-cycle-path
+  (with-redefs [manifests/read-edn-file (fn [_]
+                                          {:templates
+                                           {:a {:extends :b
+                                                :setup ["a"]}
+                                            :b {:extends :a
+                                                :setup ["b"]}}
+                                           :cases [{:id "cycle" :extends :a}]})]
+    (let [error (try
+                  (manifests/load-cases :sync)
+                  nil
+                  (catch clojure.lang.ExceptionInfo error
+                    error))]
+      (is (some? error))
+      (is (re-find #"Circular template inheritance" (.getMessage error)))
+      (is (= [:a :b :a] (:cycle (ex-data error)))))))
+
+(deftest load-cases-validates-extends-entries
+  (with-redefs [manifests/read-edn-file (fn [_]
+                                          {:templates {:base {:cmds ["base"]}}
+                                           :cases [{:id "invalid-extends"
+                                                    :extends [:base "bad"]
+                                                    :cmds ["case"]}]})]
+    (let [error (try
+                  (manifests/load-cases :non-sync)
+                  nil
+                  (catch clojure.lang.ExceptionInfo error
+                    error))]
+      (is (some? error))
+      (is (re-find #"Invalid :extends entries" (.getMessage error)))
+      (is (= ["bad"] (:invalid-entries (ex-data error)))))))
+
+(deftest load-cases-lint-detects-invalid-extends-references
+  (with-redefs [manifests/read-edn-file (fn [_]
+                                          {:templates {:base {:cmds ["base"]}
+                                                       :unused {:extends :missing-template
+                                                                :cmds ["unused"]}}
+                                           :cases [{:id "valid" :extends :base :cmds ["case"]}
+                                                   {:id "invalid" :extends :also-missing :cmds ["case"]}]})]
+    (let [error (try
+                  (manifests/load-cases :sync)
+                  nil
+                  (catch clojure.lang.ExceptionInfo error
+                    error))
+          issues (:issues (ex-data error))]
+      (is (some? error))
+      (is (re-find #"manifest lint failed" (.getMessage error)))
+      (is (= #{:also-missing :missing-template}
+             (set (map :target (filter #(= :invalid-extends (:type %)) issues))))))))
+
+(deftest load-cases-lint-detects-duplicate-case-ids
+  (with-redefs [manifests/read-edn-file (fn [_]
+                                          {:templates {:base {:cmds ["base"]}}
+                                           :cases [{:id "dup" :extends :base :cmds ["case-a"]}
+                                                   {:id "dup" :extends :base :cmds ["case-b"]}]})]
+    (let [error (try
+                  (manifests/load-cases :non-sync)
+                  nil
+                  (catch clojure.lang.ExceptionInfo error
+                    error))
+          duplicate-issues (filter #(= :duplicate-case-id (:type %))
+                                   (:issues (ex-data error)))]
+      (is (some? error))
+      (is (= [{:type :duplicate-case-id :id "dup" :count 2}]
+             (vec duplicate-issues))))))
+
+(deftest load-cases-lint-detects-unused-templates
+  (with-redefs [manifests/read-edn-file (fn [_]
+                                          {:templates {:base {:cmds ["base"]}
+                                                       :unused {:cmds ["unused"]}}
+                                           :cases [{:id "only" :extends :base :cmds ["case"]}]})]
+    (let [error (try
+                  (manifests/load-cases :sync)
+                  nil
+                  (catch clojure.lang.ExceptionInfo error
+                    error))
+          unused-issues (filter #(= :unused-template (:type %))
+                                (:issues (ex-data error)))]
+      (is (some? error))
+      (is (= [{:type :unused-template :template :unused}]
+             (vec unused-issues))))))
+
+(deftest sync-multi-batch-operations-uses-state-driven-waits-instead-of-fixed-sleeps
+  (let [cases (manifests/load-cases :sync)
+        multi-batch (some #(when (= "sync-multi-batch-operations" (:id %)) %) cases)
+        commands (:cmds multi-batch)
+        upload-commands (filter #(re-find #"sync upload --graph" %) commands)
+        wait-commands (filter #(re-find #"wait_sync_status\.py" %) commands)]
+    (is (some? multi-batch))
+    (is (not-any? #(= "sleep 1" %) commands))
+    (is (= 1 (count upload-commands)))
+    (is (= 5 (count wait-commands)))
+    (is (= 3 (count (filter #(re-find #"--root-dir '\{\{tmp-dir\}\}/graphs-b'.+--timeout-s 30 --interval-s 1" %) wait-commands))))))
+
+(deftest sync-manifest-includes-duplicate-upload-negative-case
+  (let [cases (manifests/load-cases :sync)
+        duplicate-upload (some #(when (= "sync-upload-rejects-duplicate-remote-graph" (:id %)) %) cases)
+        json-paths (get-in duplicate-upload [:expect :stdout-json-paths])
+        setup-commands (:setup duplicate-upload)
+        main-commands (:cmds duplicate-upload)]
+    (is (some? duplicate-upload))
+    (is (= 1 (get-in duplicate-upload [:expect :exit])))
+    (is (= "graph-already-exists"
+           (get-in duplicate-upload [:expect :stdout-json-paths [:error :code]])))
+    (is (= ["delete it before uploading again"]
+           (get-in duplicate-upload [:expect :stdout-contains])))
+    (is (= 1 (count (filter #(re-find #"sync upload --graph" %) setup-commands))))
+    (is (= 1 (count (filter #(re-find #"sync upload --graph" %) main-commands))))
+    (is (false? (contains? json-paths [:data :pending-local])))
+    (is (false? (contains? json-paths [:data :pending-asset])))
+    (is (false? (contains? json-paths [:data :pending-server])))
+    (is (false? (contains? json-paths [:data :last-error])))))
+
+(deftest sync-status-steady-state-does-not-repeat-identical-b-side-steady-state-waits
+  (let [cases (manifests/load-cases :sync)
+        steady-state (some #(when (= "sync-status-steady-state" (:id %)) %) cases)
+        steady-waits (filter #(re-find #"wait_sync_status\.py.+--root-dir '\{\{tmp-dir\}\}/graphs-b'.+--timeout-s 30 --interval-s 1" %) (:cmds steady-state))]
+    (is (some? steady-state))
+    (is (= 1 (count steady-waits)))
+    (is (= 1 (count (filter #(re-find #"sync status --graph" %) (:cmds steady-state)))))))
diff --git a/cli-e2e/test/logseq/cli/e2e/paths_test.clj b/cli-e2e/test/logseq/cli/e2e/paths_test.clj
new file mode 100644
index 0000000000..0e07287a74
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/paths_test.clj
@@ -0,0 +1,9 @@
+(ns logseq.cli.e2e.paths-test
+  (:require [clojure.test :refer [deftest is]]
+            [logseq.cli.e2e.paths :as paths]))
+
+(deftest repo-root-does-not-depend-on-runtime-file-binding
+  (let [expected (paths/repo-root)]
+    (binding [*file* nil]
+      (is (= expected
+             (paths/repo-root))))))
diff --git a/cli-e2e/test/logseq/cli/e2e/preflight_test.clj b/cli-e2e/test/logseq/cli/e2e/preflight_test.clj
new file mode 100644
index 0000000000..aa647b0d29
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/preflight_test.clj
@@ -0,0 +1,95 @@
+(ns logseq.cli.e2e.preflight-test
+  (:require [clojure.test :refer [deftest is testing]]
+            [logseq.cli.e2e.preflight :as preflight]))
+
+(def required-artifacts
+  ["/repo/static/logseq-cli.js"
+   "/repo/static/db-worker-node.js"
+   "/repo/dist/db-worker-node.js"
+   "/repo/dist/db-worker-node-assets.json"
+   "/repo/deps/db-sync/worker/dist/node-adapter.js"])
+
+(defn- with-required-artifacts
+  [f]
+  (with-redefs [logseq.cli.e2e.paths/repo-root (constantly "/repo")
+                logseq.cli.e2e.paths/required-artifacts (fn [] required-artifacts)]
+    (f)))
+
+(deftest build-plan-matches-required-commands
+  (is (= ["clojure -M:cljs compile logseq-cli"
+          "pnpm db-worker-node:compile:bundle"
+          "pnpm --dir deps/db-sync build:node-adapter"]
+         (mapv :cmd preflight/build-plan))))
+
+(deftest missing-artifacts-returns-unreadable-paths
+  (let [artifacts ["/repo/static/logseq-cli.js"
+                   "/repo/static/db-worker-node.js"
+                   "/repo/dist/db-worker-node.js"]
+        present? #{"/repo/static/logseq-cli.js"}]
+    (is (= ["/repo/static/db-worker-node.js"
+            "/repo/dist/db-worker-node.js"]
+           (preflight/missing-artifacts artifacts present?)))))
+
+(deftest skip-build-avoids-running-shell-commands
+  (let [called? (atom false)
+        result (preflight/run! {:skip-build true
+                                :run-command (fn [_]
+                                               (reset! called? true))
+                                :file-exists? (constantly false)})]
+    (is (= :skipped (:status result)))
+    (is (false? @called?))))
+
+(deftest build-runs-commands-even-when-artifacts-are-ready
+  (let [calls (atom [])]
+    (with-required-artifacts
+      #(let [result (preflight/run! {:run-command (fn [{:keys [cmd]}]
+                                                    (swap! calls conj cmd)
+                                                    {:cmd cmd
+                                                     :exit 0
+                                                     :out ""
+                                                     :err ""})
+                                     :file-exists? (set required-artifacts)})]
+         (is (= :ok (:status result)))
+         (is (= ["clojure -M:cljs compile logseq-cli"
+                 "pnpm db-worker-node:compile:bundle"
+                 "pnpm --dir deps/db-sync build:node-adapter"]
+                @calls))))))
+
+(deftest build-runs-commands-when-artifacts-are-partially-present
+  (let [calls (atom [])
+        existing (atom (disj (set required-artifacts)
+                             "/repo/dist/db-worker-node-assets.json"))]
+    (with-required-artifacts
+      #(let [result (preflight/run! {:run-command (fn [{:keys [cmd]}]
+                                                    (swap! calls conj cmd)
+                                                    (reset! existing (set required-artifacts))
+                                                    {:cmd cmd
+                                                     :exit 0
+                                                     :out ""
+                                                     :err ""})
+                                     :file-exists? (fn [path]
+                                                     (contains? @existing path))})]
+         (is (= :ok (:status result)))
+         (is (= ["clojure -M:cljs compile logseq-cli"
+                 "pnpm db-worker-node:compile:bundle"
+                 "pnpm --dir deps/db-sync build:node-adapter"]
+                @calls))))))
+
+(deftest build-runs-commands-when-artifacts-are-absent
+  (let [calls (atom [])
+        existing (atom #{})]
+    (with-required-artifacts
+      #(let [result (preflight/run! {:run-command (fn [{:keys [cmd]}]
+                                                    (swap! calls conj cmd)
+                                                    (reset! existing (set required-artifacts))
+                                                    {:cmd cmd
+                                                     :exit 0
+                                                     :out ""
+                                                     :err ""})
+                                     :file-exists? (fn [path]
+                                                     (contains? @existing path))})]
+         (is (= :ok (:status result)))
+         (is (= ["clojure -M:cljs compile logseq-cli"
+                 "pnpm db-worker-node:compile:bundle"
+                 "pnpm --dir deps/db-sync build:node-adapter"]
+                @calls))))))
diff --git a/cli-e2e/test/logseq/cli/e2e/random_bidirectional_block_ops_test.py b/cli-e2e/test/logseq/cli/e2e/random_bidirectional_block_ops_test.py
new file mode 100644
index 0000000000..ec457c6948
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/random_bidirectional_block_ops_test.py
@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+import sys
+
+
+MODULE_PATH = Path(__file__).resolve().parents[4] / "scripts" / "random_bidirectional_block_ops.py"
+spec = importlib.util.spec_from_file_location("random_bidirectional_block_ops", MODULE_PATH)
+random_bidirectional_block_ops = importlib.util.module_from_spec(spec)
+assert spec.loader is not None
+sys.modules[spec.name] = random_bidirectional_block_ops
+spec.loader.exec_module(random_bidirectional_block_ops)
+
+
+def test_default_profile_is_faster_than_high_stress(monkeypatch) -> None:
+    monkeypatch.setattr(
+        random_bidirectional_block_ops.sys,
+        "argv",
+        [
+            "random_bidirectional_block_ops.py",
+            "--cli",
+            "/tmp/logseq-cli.js",
+            "--graph",
+            "demo",
+            "--config-a",
+            "/tmp/a.edn",
+            "--root-dir-a",
+            "/tmp/a",
+            "--config-b",
+            "/tmp/b.edn",
+            "--root-dir-b",
+            "/tmp/b",
+            "--page",
+            "Home",
+        ],
+    )
+    default_args = random_bidirectional_block_ops.parse_args()
+
+    monkeypatch.setattr(
+        random_bidirectional_block_ops.sys,
+        "argv",
+        [
+            "random_bidirectional_block_ops.py",
+            "--cli",
+            "/tmp/logseq-cli.js",
+            "--graph",
+            "demo",
+            "--config-a",
+            "/tmp/a.edn",
+            "--root-dir-a",
+            "/tmp/a",
+            "--config-b",
+            "/tmp/b.edn",
+            "--root-dir-b",
+            "/tmp/b",
+            "--page",
+            "Home",
+            "--profile",
+            "high-stress",
+        ],
+    )
+    high_stress_args = random_bidirectional_block_ops.parse_args()
+
+    assert default_args.root_dir_a == "/tmp/a"
+    assert default_args.root_dir_b == "/tmp/b"
+    assert default_args.profile == "default"
+    assert high_stress_args.profile == "high-stress"
+    assert default_args.rounds_per_client < high_stress_args.rounds_per_client
+
+
+def test_explicit_rounds_override_profile_default(monkeypatch) -> None:
+    monkeypatch.setattr(
+        random_bidirectional_block_ops.sys,
+        "argv",
+        [
+            "random_bidirectional_block_ops.py",
+            "--cli",
+            "/tmp/logseq-cli.js",
+            "--graph",
+            "demo",
+            "--config-a",
+            "/tmp/a.edn",
+            "--root-dir-a",
+            "/tmp/a",
+            "--config-b",
+            "/tmp/b.edn",
+            "--root-dir-b",
+            "/tmp/b",
+            "--page",
+            "Home",
+            "--profile",
+            "high-stress",
+            "--rounds-per-client",
+            "12",
+        ],
+    )
+
+    args = random_bidirectional_block_ops.parse_args()
+
+    assert args.profile == "high-stress"
+    assert args.rounds_per_client == 12
diff --git a/cli-e2e/test/logseq/cli/e2e/runner_test.clj b/cli-e2e/test/logseq/cli/e2e/runner_test.clj
new file mode 100644
index 0000000000..a2a1ae1570
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/runner_test.clj
@@ -0,0 +1,152 @@
+(ns logseq.cli.e2e.runner-test
+  (:require [clojure.test :refer [deftest is]]
+            [logseq.cli.e2e.runner :as runner]))
+
+(deftest render-case-expands-template-values-recursively
+  (let [rendered (runner/render-case
+                  {:id "graph-create"
+                   :setup ["{{cli}} --graph {{graph-arg}}"]
+                   :cmds ["{{cli}} graph info --graph {{graph-arg}}"]
+                   :expect {:stdout-json-paths {[:data :graph] "{{graph}}"
+                                                [:status] "ok"}}}
+                  {:cli "node /tmp/logseq-cli.js"
+                   :graph "demo"
+                   :graph-arg "'demo'"})]
+    (is (= ["node /tmp/logseq-cli.js --graph 'demo'"] (:setup rendered)))
+    (is (= ["node /tmp/logseq-cli.js graph info --graph 'demo'"] (:cmds rendered)))
+    (is (= "demo" (get-in rendered [:expect :stdout-json-paths [:data :graph]])))))
+
+(deftest run-case-executes-setup-before-main-command
+  (let [calls (atom [])
+        result (runner/run-case!
+                {:id "graph-info"
+                 :setup ["setup one" "setup two"]
+                 :cmds ["main command one" "main command two"]
+                 :expect {:exit 0}}
+                {:context {}
+                 :run-command (fn [{:keys [cmd]}]
+                                (swap! calls conj cmd)
+                                {:cmd cmd
+                                 :exit 0
+                                 :out ""
+                                 :err ""})})]
+    (is (= ["setup one" "setup two" "main command one" "main command two"] @calls))
+    (is (= "graph-info" (:id result)))
+    (is (= "main command two" (get-in result [:result :cmd])))))
+
+(deftest run-case-includes-command-phase-metadata-when-detailed
+  (let [calls (atom [])]
+    (runner/run-case!
+     {:id "graph-info"
+      :setup ["setup one" "setup two"]
+      :cmds ["main command one" "main command two"]
+      :cleanup ["cleanup one"]
+      :expect {:exit 0}}
+     {:context {}
+      :detailed-log? true
+      :run-command (fn [{:keys [cmd phase step-index step-total case-id throw?] :as opts}]
+                     (swap! calls conj (select-keys opts [:cmd :phase :step-index :step-total :case-id :throw?]))
+                     {:cmd cmd
+                      :exit 0
+                      :out ""
+                      :err ""})})
+    (is (= [{:cmd "setup one" :phase :setup :step-index 1 :step-total 2 :case-id "graph-info" :throw? true}
+            {:cmd "setup two" :phase :setup :step-index 2 :step-total 2 :case-id "graph-info" :throw? true}
+            {:cmd "main command one" :phase :main :step-index 1 :step-total 2 :case-id "graph-info" :throw? true}
+            {:cmd "main command two" :phase :main :step-index 2 :step-total 2 :case-id "graph-info" :throw? false}
+            {:cmd "cleanup one" :phase :cleanup :step-index 1 :step-total 1 :case-id "graph-info" :throw? false}]
+           @calls))))
+
+(deftest run-case-collects-step-timings-when-enabled
+  (let [result (runner/run-case!
+                {:id "graph-info"
+                 :setup ["setup one"]
+                 :cmds ["main command"]
+                 :cleanup ["cleanup one"]
+                 :expect {:exit 0}}
+                {:context {}
+                 :timings? true
+                 :run-command (fn [{:keys [cmd]}]
+                                {:cmd cmd
+                                 :exit 0
+                                 :out ""
+                                 :err ""})})]
+    (is (= 3 (count (:timings result))))
+    (is (= [:setup :main :cleanup]
+           (mapv :phase (:timings result))))))
+
+(deftest run-case-attaches-timings-to-error-when-enabled
+  (let [error (try
+                (runner/run-case!
+                 {:id "graph-info"
+                  :setup ["setup one"]
+                  :cmds ["main command"]
+                  :cleanup ["cleanup one"]
+                  :expect {:exit 0}}
+                 {:context {}
+                  :timings? true
+                  :run-command (fn [{:keys [cmd]}]
+                                 (when (= cmd "main command")
+                                   (throw (ex-info "boom" {:cmd cmd})))
+                                 {:cmd cmd
+                                  :exit 0
+                                  :out ""
+                                  :err ""})})
+                nil
+                (catch clojure.lang.ExceptionInfo error
+                  error))
+        timings (:timings (ex-data error))]
+    (is (= "graph-info" (:case-id (ex-data error))))
+    (is (= [:setup :main :cleanup]
+           (mapv :phase timings)))
+    (is (= :failed (:status (second timings))))))
+
+(deftest run-case-validates-json-paths-and-nonzero-exit
+  (let [result (runner/run-case!
+                {:id "invalid-shell"
+                 :cmds ["node static/logseq-cli.js completion fish"]
+                 :expect {:exit 1
+                          :stdout-json-paths {[:status] "error"
+                                              [:error :code] "invalid-options"}}}
+                {:context {}
+                 :run-command (fn [{:keys [cmd]}]
+                                {:cmd cmd
+                                 :exit 1
+                                 :out "{\"status\":\"error\",\"error\":{\"code\":\"invalid-options\"}}"
+                                 :err ""})})]
+    (is (= 1 (get-in result [:result :exit])))))
+
+(deftest assert-result-validates-edn-paths
+  (is (nil? (runner/assert-result!
+             {:id "graph-list-edn"
+              :expect {:exit 0
+                       :stdout-edn-paths {[:status] :ok
+                                          [:data :graphs] ["demo"]}}}
+             {:cmd "node cli.js graph list"
+              :exit 0
+              :out "{:status :ok, :data {:graphs [\"demo\"]}}"
+              :err ""}))))
+
+(deftest assert-result-validates-stdout-not-contains
+  (is (thrown-with-msg?
+       clojure.lang.ExceptionInfo
+       #"stdout contained forbidden text"
+       (runner/assert-result!
+        {:id "remove-block"
+         :expect {:exit 0
+                  :stdout-not-contains ["Alpha block"]}}
+        {:cmd "node cli.js show --page Home"
+         :exit 0
+         :out "Home\n- Alpha block"
+         :err ""}))))
+
+(deftest assert-result-normalizes-json-escaped-windows-paths-for-contains
+  (is (nil? (runner/assert-result!
+             {:id "doctor-dev-script-json"
+              :expect {:exit 0
+                       :stdout-contains ["static/db-worker-node.js"
+                                         "C:\\Users\\demo\\tmp\\graph-export.edn"]}}
+             {:cmd "node cli.js doctor --dev-script"
+              :exit 0
+              :out "{\"status\":\"ok\",\"data\":{\"path\":\"C:\\\\Users\\\\demo\\\\tmp\\\\graph-export.edn\",\"message\":\"Found readable file: C:\\\\Users\\\\demo\\\\project\\\\static\\\\db-worker-node.js\"}}"
+              :err ""}))))
diff --git a/cli-e2e/test/logseq/cli/e2e/shell_test.clj b/cli-e2e/test/logseq/cli/e2e/shell_test.clj
new file mode 100644
index 0000000000..9d696d1dc6
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/shell_test.clj
@@ -0,0 +1,54 @@
+(ns logseq.cli.e2e.shell-test
+  (:require [babashka.process :as process]
+            [clojure.test :refer [deftest is testing]]
+            [logseq.cli.e2e.shell :as shell]))
+
+(deftest preserves-the-exact-command-string
+  (let [captured (atom nil)
+        command "node static/logseq-cli.js --graph 'Graph With Space' --help"
+        result (shell/run! {:cmd command
+                            :dir "/repo"
+                            :executor (fn [cmd opts]
+                                        (reset! captured {:cmd cmd
+                                                          :opts opts})
+                                        {:exit 0
+                                         :out "ok"
+                                         :err ""})})]
+    (is (= command (:cmd result)))
+    (is (= command (:cmd @captured)))
+    (is (= "/repo" (get-in @captured [:opts :dir])))))
+
+(deftest shell-failures-include-command-context
+  (let [command "node static/logseq-cli.js completion fish"]
+    (try
+      (shell/run! {:cmd command
+                   :executor (fn [_ _]
+                               {:exit 2
+                                :out ""
+                                :err "unsupported shell"})})
+      (is false "Expected shell/run! to throw")
+      (catch clojure.lang.ExceptionInfo ex
+        (is (= command (:cmd (ex-data ex))))
+        (is (= 2 (:exit (ex-data ex))))
+        (is (= "unsupported shell" (:err (ex-data ex))))))))
+
+(deftest allow-failure-returns-result-without-throwing
+  (let [command "node static/logseq-cli.js graph info --graph missing"
+        result (shell/run! {:cmd command
+                            :throw? false
+                            :executor (fn [_ _]
+                                        {:exit 1
+                                         :out "failed"
+                                         :err "missing"})})]
+    (is (= command (:cmd result)))
+    (is (= 1 (:exit result)))
+    (is (= "failed" (:out result)))
+    (is (= "missing" (:err result)))))
+
+(deftest default-executor-uses-resolvable-shell-command
+  (let [captured (atom nil)]
+    (with-redefs [process/process (fn [_opts & args]
+                                    (reset! captured args)
+                                    (future {:exit 0}))]
+      (shell/run! {:cmd "echo ok"}))
+    (is (= ["bash" "-c" "echo ok"] @captured))))
diff --git a/cli-e2e/test/logseq/cli/e2e/sync_fixture_test.clj b/cli-e2e/test/logseq/cli/e2e/sync_fixture_test.clj
new file mode 100644
index 0000000000..dd7a84ab6e
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/sync_fixture_test.clj
@@ -0,0 +1,114 @@
+(ns logseq.cli.e2e.sync-fixture-test
+  (:require [clojure.string :as string]
+            [clojure.test :refer [deftest is testing]]
+            [logseq.cli.e2e.sync-fixture :as sync-fixture]))
+
+(deftest prepare-case-injects-case-local-sync-resources
+  (let [suite-context {:sync-port "18080"
+                       :sync-http-base "http://127.0.0.1:18080"
+                       :sync-ws-url "ws://127.0.0.1:18080/sync/%s"}
+        input-case {:id "sync-case"
+                    :vars {:existing true}
+                    :setup ["mkdir -p '{{tmp-dir}}/graphs-b'"
+                            "mkdir -p '{{tmp-dir}}/home/logseq'"
+                            "cp ~/logseq/auth.json '{{tmp-dir}}/home/logseq/auth.json'"
+                            "python3 '{{repo-root}}/cli-e2e/scripts/prepare_sync_config.py' --output '{{config-path}}' --auth-path '{{tmp-dir}}/home/logseq/auth.json' --http-base '{{sync-http-base}}' --ws-url '{{sync-ws-url}}'"
+                            "python3 '{{repo-root}}/cli-e2e/scripts/prepare_sync_config.py' --output '{{tmp-dir}}/cli-b.edn' --auth-path '{{tmp-dir}}/home/logseq/auth.json' --http-base '{{sync-http-base}}' --ws-url '{{sync-ws-url}}'"
+                            "python3 '{{repo-root}}/cli-e2e/scripts/db_sync_server.py' start --port 18080"
+                            "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"]
+                    :cleanup ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{graph-arg}}"
+                              "python3 '{{repo-root}}/cli-e2e/scripts/db_sync_server.py' stop --pid-file '{{tmp-dir}}/db-sync-server.pid'"]}
+        prepared (sync-fixture/prepare-case input-case suite-context)]
+    (is (= "sync-case" (:id prepared)))
+    (is (= ["mkdir -p '{{tmp-dir}}/graphs-b'"
+            "mkdir -p '{{tmp-dir}}/home/logseq'"
+            "cp ~/logseq/auth.json '{{tmp-dir}}/home/logseq/auth.json'"
+            "python3 '{{repo-root}}/cli-e2e/scripts/prepare_sync_config.py' --output '{{config-path}}' --auth-path '{{tmp-dir}}/home/logseq/auth.json' --http-base '{{sync-http-base}}' --ws-url '{{sync-ws-url}}'"
+            "python3 '{{repo-root}}/cli-e2e/scripts/prepare_sync_config.py' --output '{{tmp-dir}}/cli-b.edn' --auth-path '{{tmp-dir}}/home/logseq/auth.json' --http-base '{{sync-http-base}}' --ws-url '{{sync-ws-url}}'"
+            "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"]
+           (:setup prepared)))
+    (is (= ["{{cli}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json server stop --graph {{graph-arg}}"]
+           (:cleanup prepared)))
+    (is (= "http://127.0.0.1:18080" (get-in prepared [:vars :sync-http-base])))
+    (is (= "ws://127.0.0.1:18080/sync/%s" (get-in prepared [:vars :sync-ws-url])))
+    (is (= "18080" (get-in prepared [:vars :sync-port])))
+    (is (= "11111" (get-in prepared [:vars :e2ee-password])))
+    (is (= "11111" (get-in prepared [:vars :e2ee-password-arg])))
+    (is (not (contains? (:vars prepared) :suite-auth-path)))
+    (is (not (contains? (:vars prepared) :suite-config-path)))
+    (is (not-any? #(string/includes? % "suite-auth-path") (:setup prepared)))
+    (is (not-any? #(string/includes? % "suite-config-path") (:setup prepared)))
+    (is (not-any? #(string/includes? % "db_sync_server.py' start") (:setup prepared)))
+    (is (not-any? #(string/includes? % "db_sync_server.py' stop") (:cleanup prepared)))))
+
+(deftest prepare-case-places-case-local-auth-before-cli-sync-commands
+  (let [suite-context {:suite-tmp-dir "/tmp/sync-suite"
+                       :sync-port "18080"
+                       :sync-http-base "http://127.0.0.1:18080"
+                       :sync-ws-url "ws://127.0.0.1:18080/sync/%s"}
+        prepared (sync-fixture/prepare-case
+                  {:id "sync-case"
+                   :setup ["mkdir -p '{{tmp-dir}}/graphs-b'"
+                           "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"
+                           "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync ensure-keys --graph {{graph-arg}} --e2ee-password {{e2ee-password-arg}}"]
+                   :cleanup []}
+                  suite-context)
+        setup (:setup prepared)
+        bootstrap-cmd (nth setup 5)]
+    (is (= "mkdir -p '{{tmp-dir}}/graphs-b'" (first setup)))
+    (is (= "mkdir -p '{{tmp-dir}}/home/logseq'" (second setup)))
+    (is (= "cp ~/logseq/auth.json '{{tmp-dir}}/home/logseq/auth.json'" (nth setup 2)))
+    (is (= "python3 '{{repo-root}}/cli-e2e/scripts/prepare_sync_config.py' --output '{{config-path}}' --auth-path '{{tmp-dir}}/home/logseq/auth.json' --http-base '{{sync-http-base}}' --ws-url '{{sync-ws-url}}'"
+           (nth setup 3)))
+    (is (= "python3 '{{repo-root}}/cli-e2e/scripts/prepare_sync_config.py' --output '{{tmp-dir}}/cli-b.edn' --auth-path '{{tmp-dir}}/home/logseq/auth.json' --http-base '{{sync-http-base}}' --ws-url '{{sync-ws-url}}'"
+           (nth setup 4)))
+    (is (string/includes? bootstrap-cmd "sync ensure-keys"))
+    (is (string/includes? bootstrap-cmd "--upload-keys"))
+    (is (string/includes? bootstrap-cmd "/tmp/sync-suite/user-rsa-keys.lock"))
+    (is (string/includes? bootstrap-cmd "/tmp/sync-suite/user-rsa-keys.ready"))
+    (is (= "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json graph create --graph {{graph-arg}} >/dev/null"
+           (nth setup 6)))
+    (is (= "{{cli-home}} --root-dir {{root-dir-arg}} --config {{config-path-arg}} --output json sync ensure-keys --graph {{graph-arg}} --e2ee-password {{e2ee-password-arg}}"
+           (nth setup 7)))
+    (is (not-any? #(and (string/includes? % "sync ensure-keys")
+                        (not= % bootstrap-cmd)
+                        (string/includes? % "--upload-keys"))
+                  setup))))
+
+(deftest prepare-case-accepts-custom-e2ee-password
+  (let [suite-context {:sync-port "18080"
+                       :sync-http-base "http://127.0.0.1:18080"
+                       :sync-ws-url "ws://127.0.0.1:18080/sync/%s"
+                       :e2ee-password "pass word"}
+        prepared (sync-fixture/prepare-case {:id "sync-case"
+                                             :setup []
+                                             :cleanup []}
+                                            suite-context)]
+    (is (= "pass word" (get-in prepared [:vars :e2ee-password])))
+    (is (= "'pass word'" (get-in prepared [:vars :e2ee-password-arg])))))
+
+(deftest before-and-after-suite-only-manage-shared-sync-server-lifecycle
+  (let [calls (atom [])
+        run-command (fn [opts]
+                      (swap! calls conj opts)
+                      {:exit 0
+                       :out ""
+                       :err ""})
+        suite-context (sync-fixture/before-suite! {:run-command run-command})]
+    (testing "before-suite only starts the shared server"
+      (is (= 1 (count @calls)))
+      (is (string/includes? (:cmd (first @calls)) "db_sync_server.py"))
+      (is (string/includes? (:cmd (first @calls)) " start "))
+      (is (string/includes? (:cmd (first @calls)) "--data-dir"))
+      (is (not (string/includes? (:cmd (first @calls)) "--root-dir")))
+      (is (string/includes? (:cmd (first @calls)) "--port 18080"))
+      (is (string/includes? (:cmd (first @calls)) "--startup-timeout-s 60"))
+      (is (not (string/includes? (:cmd (first @calls)) "prepare_sync_config.py")))
+      (is (not (contains? suite-context :suite-auth-path)))
+      (is (not (contains? suite-context :suite-config-path))))
+    (sync-fixture/after-suite! suite-context {:run-command run-command})
+    (testing "after-suite only stops the shared server once"
+      (is (= 2 (count @calls)))
+      (is (string/includes? (:cmd (last @calls)) "db_sync_server.py"))
+      (is (string/includes? (:cmd (last @calls)) " stop "))
+      (is (false? (:throw? (last @calls)))))))
diff --git a/cli-e2e/test/logseq/cli/e2e/wait_sync_status_test.py b/cli-e2e/test/logseq/cli/e2e/wait_sync_status_test.py
new file mode 100644
index 0000000000..ba9df4b78d
--- /dev/null
+++ b/cli-e2e/test/logseq/cli/e2e/wait_sync_status_test.py
@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import SimpleNamespace
+
+
+MODULE_PATH = Path(__file__).resolve().parents[4] / "scripts" / "wait_sync_status.py"
+spec = importlib.util.spec_from_file_location("wait_sync_status", MODULE_PATH)
+wait_sync_status = importlib.util.module_from_spec(spec)
+assert spec.loader is not None
+spec.loader.exec_module(wait_sync_status)
+
+
+def test_resolved_status_command_is_built_once_and_reused() -> None:
+    args = SimpleNamespace(
+        cli="~/repo/static/logseq-cli.js",
+        root_dir="~/tmp/root",
+        config="~/tmp/cli.edn",
+        graph="demo",
+    )
+
+    command = wait_sync_status.status_command(args)
+
+    assert command[0] == "node"
+    assert command[2] == "--root-dir"
+    assert command[-2:] == ["--graph", "demo"]
+    assert Path(command[1]).is_absolute()
+    assert Path(command[3]).is_absolute()
+    assert Path(command[5]).is_absolute()
+    assert wait_sync_status.status_command(args) is command
+
+
+def test_run_status_uses_precomputed_command() -> None:
+    command = ["node", "/abs/cli.js", "--graph", "demo"]
+    args = SimpleNamespace(status_command=command)
+    calls = []
+
+    def fake_run(cmd, capture_output, text):
+        calls.append(cmd)
+        return SimpleNamespace(
+            returncode=0,
+            stdout='{"status":"ok","data":{"pending-local":0,"pending-asset":0,"pending-server":0}}',
+            stderr="",
+        )
+
+    original_run = wait_sync_status.subprocess.run
+    wait_sync_status.subprocess.run = fake_run
+    try:
+        payload = wait_sync_status.run_status(args)
+    finally:
+        wait_sync_status.subprocess.run = original_run
+
+    assert payload["status"] == "ok"
+    assert calls == [command]
diff --git a/deps.edn b/deps.edn
index a75ca1655f..25544fddde 100644
--- a/deps.edn
+++ b/deps.edn
@@ -24,6 +24,8 @@
   cljs-http/cljs-http                   {:mvn/version "0.1.49"}
   org.babashka/sci                      {:mvn/version "0.12.51"}
   org.clj-commons/hickory               {:mvn/version "0.7.7"}
+  org.clj-commons/humanize              {:mvn/version "1.2"}
+  org.babashka/cli                      {:mvn/version "0.8.67"}
   hiccups/hiccups                       {:mvn/version "0.3.0"}
   tongue/tongue                         {:mvn/version "0.4.4"}
   org.clojure/core.async                {:mvn/version "1.8.741"}
diff --git a/deps/cli/src/logseq/cli.cljs b/deps/cli/src/logseq/cli.cljs
index cfcd4557fc..d53bc0bc0a 100644
--- a/deps/cli/src/logseq/cli.cljs
+++ b/deps/cli/src/logseq/cli.cljs
@@ -2,6 +2,7 @@
   "Main ns for Logseq CLI"
   (:require ["fs" :as fs]
             ["path" :as node-path]
+            ["child_process" :as child-process]
             [babashka.cli :as cli]
             [clojure.string :as string]
             [logseq.cli.common.graph :as cli-common-graph]
@@ -58,6 +59,29 @@
       (print-command-help "help" cmd-map)
       (println "Command" (pr-str command) "does not exist"))))
 
+(defn- extract-graph-names
+  "Extract graph names from parsed opts for unlock-graph."
+  [{:keys [graph graphs]}]
+  (cond-> []
+    (string? graph) (conj graph)
+    (sequential? graphs) (into graphs)))
+
+(defn- unlock-graphs!
+  "Stop the db-worker-node server(s) for graph-names so this CLI can open the
+  SQLite database directly"
+  [graph-names]
+  (doseq [graph graph-names]
+    (let [result (.spawnSync child-process
+                             "logseq"
+                             #js ["server" "stop" "-g" graph]
+                             #js {:timeout 5000
+                                  :stdio "pipe"})]
+      (if (= 0 (.-status result))
+        (println "Unlocked graph:" graph)
+        ;; Ignore server not started
+        (when-not (string/includes? (str (.-stdout result)) "server-not-found")
+          (println "Failed to unlock graph:" (pr-str result)))))))
+
 (defn- lazy-load-fn
   "Lazy load fn to speed up start time. After nbb requires ~30 namespaces, start time gets close to 1s.
    Also handles --help on all commands"
@@ -65,13 +89,17 @@
   (fn [& args]
     (if (get-in (first args) [:opts :help])
       (help-command {:opts {:command (-> args first :dispatch first)}})
-      (-> (p/let [_ (require (symbol (namespace fn-sym)))]
-            (apply (resolve fn-sym) args))
-          (p/catch (fn [err]
-                     (if (= :sci/error (:type (ex-data err)))
-                       (nbb.error/print-error-report err)
-                       (js/console.error "Error:" err))
-                     (js/process.exit 1)))))))
+      (do
+        (when (get-in (first args) [:opts :unlock-graph])
+          (let [graphs (extract-graph-names (get (first args) :opts))]
+            (unlock-graphs! graphs)))
+        (-> (p/let [_ (require (symbol (namespace fn-sym)))]
+              (apply (resolve fn-sym) args))
+            (p/catch (fn [err]
+                       (if (= :sci/error (:type (ex-data err)))
+                         (nbb.error/print-error-report err)
+                         (js/console.error "Error:" err))
+                       (js/process.exit 1))))))))
 
 (def ^:private table*
   [{:cmds ["list"] :desc "List local graphs"
@@ -122,10 +150,14 @@
     :spec default-spec
     :fn default-command}])
 
+
 ;; Spec shared with all commands
 (def ^:private shared-spec
   {:help {:alias :h
-          :desc "Print help"}})
+          :desc "Print help"}
+   :unlock-graph {:alias :u
+                  :coerce :boolean
+                  :desc "Unlock graph(s) before running command"}})
 
 (def ^:private table
   (mapv (fn [m] (update m :spec #(merge % shared-spec))) table*))
diff --git a/deps/cli/src/logseq/cli/commands/graph.cljs b/deps/cli/src/logseq/cli/commands/graph.cljs
index 73e5a0b00c..eb764d5525 100644
--- a/deps/cli/src/logseq/cli/commands/graph.cljs
+++ b/deps/cli/src/logseq/cli/commands/graph.cljs
@@ -38,6 +38,6 @@
 (defn list-graphs
   []
   (let [db-graphs (->> (cli-common-graph/get-db-based-graphs)
-                       (map #(string/replace-first % common-config/db-version-prefix ""))
+                       (map common-config/strip-leading-db-version-prefix)
                        sort)]
-    (println (string/join "\n" db-graphs))))
\ No newline at end of file
+    (println (string/join "\n" db-graphs))))
diff --git a/deps/cli/src/logseq/cli/common/graph.cljs b/deps/cli/src/logseq/cli/common/graph.cljs
index 87644110f2..d6c15ec8a2 100644
--- a/deps/cli/src/logseq/cli/common/graph.cljs
+++ b/deps/cli/src/logseq/cli/common/graph.cljs
@@ -1,23 +1,19 @@
 (ns ^:node-only logseq.cli.common.graph
   "Graph related fns shared between CLI and electron"
   (:require ["fs-extra" :as fs-extra]
-            ["os" :as os]
-            ["path" :as node-path]
             [clojure.string :as string]
             [logseq.common.config :as common-config]
-            [logseq.common.graph :as common-graph]))
+            [logseq.common.graph :as common-graph]
+            [logseq.common.graph-dir :as graph-dir]))
 
 (defn ^:api graph-name->path
   [graph-name]
-  (when graph-name
-    (-> graph-name
-        (string/replace "+3A+" ":")
-        (string/replace "++" "/"))))
+  (graph-dir/decode-graph-dir-name graph-name))
 
 (defn get-db-graphs-dir
   "Directory where DB graphs are stored"
   []
-  (node-path/join (os/homedir) "logseq" "graphs"))
+  (common-graph/expand-home (common-graph/get-default-graphs-dir)))
 
 (defn get-db-based-graphs
   []
@@ -27,5 +23,7 @@
          (remove (fn [s] (= s common-config/unlinked-graphs-dir)))
          (map graph-name->path)
          (keep (fn [s]
-                 (when-not (string/starts-with? s common-config/file-version-prefix)
-                   (str common-config/db-version-prefix s)))))))
+                 (when (and (string? s)
+                            (not (string/starts-with? s common-config/file-version-prefix)))
+                   (common-config/canonicalize-db-version-repo s))))
+         distinct)))
diff --git a/deps/cli/src/logseq/cli/common/mcp/tools.cljs b/deps/cli/src/logseq/cli/common/mcp/tools.cljs
index eba43a1da0..2856177335 100644
--- a/deps/cli/src/logseq/cli/common/mcp/tools.cljs
+++ b/deps/cli/src/logseq/cli/common/mcp/tools.cljs
@@ -26,7 +26,7 @@
               (if expand
                 (cond-> (into {} e)
                   true
-                  (dissoc e :block/tags :block/order :block/refs :block/name :db/index
+                  (dissoc :block/tags :block/order :block/refs :block/name :db/index
                           :logseq.property/default-value)
                   true
                   (update :block/uuid str)
@@ -46,7 +46,7 @@
               (if expand
                 (cond-> (into {} e)
                   true
-                  (dissoc e :block/tags :block/order :block/refs :block/name)
+                  (dissoc :block/tags :block/order :block/refs :block/name)
                   true
                   (update :block/uuid str)
                   (:logseq.property.class/extends e)
diff --git a/deps/cli/src/logseq/cli/util.cljs b/deps/cli/src/logseq/cli/util.cljs
index 42bc50fa19..9bd9e0fc90 100644
--- a/deps/cli/src/logseq/cli/util.cljs
+++ b/deps/cli/src/logseq/cli/util.cljs
@@ -4,7 +4,7 @@
             ["path" :as node-path]
             [clojure.string :as string]
             [logseq.cli.common.graph :as cli-common-graph]
-            [logseq.db.common.sqlite :as common-sqlite]
+            [logseq.common.graph-dir :as graph-dir]
             [nbb.error]
             [promesa.core :as p]))
 
@@ -17,7 +17,7 @@
     (string/includes? graph "/")
     ((juxt node-path/dirname node-path/basename) graph)
     :else
-    [(cli-common-graph/get-db-graphs-dir) (common-sqlite/sanitize-db-name graph)]))
+    [(cli-common-graph/get-db-graphs-dir) (graph-dir/repo->encoded-graph-dir-name graph)]))
 
 (defn get-graph-path
   "If graph is a file, return its path. Otherwise returns the graph's dir"
diff --git a/deps/common/.carve/config.edn b/deps/common/.carve/config.edn
index 954cbd2144..bdd5a7cab0 100644
--- a/deps/common/.carve/config.edn
+++ b/deps/common/.carve/config.edn
@@ -8,6 +8,8 @@
                   logseq.common.util.date-time
                   logseq.common.date
                   logseq.common.util.macro
+                  logseq.common.cognito-config
                   logseq.common.config
-                  logseq.common.defkeywords]
+                  logseq.common.defkeywords
+                  logseq.common.graph-dir]
  :report {:format :ignore}}
diff --git a/deps/common/.carve/ignore b/deps/common/.carve/ignore
index e70a067333..2d0fac603b 100644
--- a/deps/common/.carve/ignore
+++ b/deps/common/.carve/ignore
@@ -3,6 +3,10 @@ logseq.common.graph/get-files
 ;; API fn
 logseq.common.graph/read-directories
 ;; API fn
+logseq.common.graph/get-default-graphs-dir
+;; API fn
+logseq.common.graph/expand-home
+;; API fn
 logseq.common.authorization/verify-jwt
 
 ;; Profile utils
diff --git a/deps/common/src/logseq/common/cognito_config.cljs b/deps/common/src/logseq/common/cognito_config.cljs
new file mode 100644
index 0000000000..d4f7d19450
--- /dev/null
+++ b/deps/common/src/logseq/common/cognito_config.cljs
@@ -0,0 +1,13 @@
+(ns logseq.common.cognito-config
+  "Shared Cognito configuration for frontend and CLI-safe consumers.")
+
+(def COGNITO-CLIENT-ID
+  "69cs1lgme7p8kbgld8n5kseii6")
+
+(def CLI-COGNITO-CLIENT-ID
+  "69cs1lgme7p8kbgld8n5kseii6")
+
+(def OAUTH-DOMAIN
+  "logseq-prod.auth.us-east-1.amazoncognito.com")
+
+(def OAUTH-SCOPE "email openid phone")
diff --git a/deps/common/src/logseq/common/config.cljs b/deps/common/src/logseq/common/config.cljs
index 09e690b84c..9f8f238e66 100644
--- a/deps/common/src/logseq/common/config.cljs
+++ b/deps/common/src/logseq/common/config.cljs
@@ -33,6 +33,26 @@
 (defonce db-version-prefix "logseq_db_")
 (defonce file-version-prefix "logseq_local_")
 
+(defn strip-leading-db-version-prefix
+  "Strip exactly one leading db prefix for user-facing display values."
+  [s]
+  (if (and (string? s)
+           (string/starts-with? s db-version-prefix))
+    (subs s (count db-version-prefix))
+    s))
+
+(defn canonicalize-db-version-repo
+  "Normalize any repo/graph name to exactly one leading db prefix."
+  [s]
+  (when (seq s)
+    (let [s (str s)
+          stripped (loop [name' s]
+                     (if (string/starts-with? name' db-version-prefix)
+                       (recur (subs name' (count db-version-prefix)))
+                       name'))]
+      (str db-version-prefix stripped))))
+
+(defonce default-graphs-dir "~/logseq/graphs")
 (defonce local-assets-dir "assets")
 (defonce unlinked-graphs-dir "Unlinked graphs")
 
diff --git a/deps/common/src/logseq/common/graph.cljs b/deps/common/src/logseq/common/graph.cljs
index b255ac3b59..1cd38ae736 100644
--- a/deps/common/src/logseq/common/graph.cljs
+++ b/deps/common/src/logseq/common/graph.cljs
@@ -1,8 +1,10 @@
 (ns ^:node-only logseq.common.graph
   "This ns provides common fns for a graph directory and only runs in a node environment"
   (:require ["fs" :as fs]
+            ["os" :as os]
             ["path" :as node-path]
             [clojure.string :as string]
+            [logseq.common.config :as common-config]
             [logseq.common.path :as path]))
 
 (def ^:private win32?
@@ -97,3 +99,15 @@ Rules:
   (->> (readdir graph-dir)
        (remove (partial ignored-path? graph-dir))
        (filter #(contains? allowed-formats (get-ext %)))))
+
+(defn get-default-graphs-dir
+  "Get default dir for storing graphs by first looking in env var."
+  []
+  (or js/process.env.LOGSEQ_GRAPHS_DIR common-config/default-graphs-dir))
+
+(defn expand-home
+  "Expands path if it starts with '~'"
+  [path]
+  (if (and (seq path) (string/starts-with? path "~"))
+    (node-path/join (os/homedir) (subs path 1))
+    path))
diff --git a/deps/common/src/logseq/common/graph_dir.cljs b/deps/common/src/logseq/common/graph_dir.cljs
new file mode 100644
index 0000000000..d57b68f37f
--- /dev/null
+++ b/deps/common/src/logseq/common/graph_dir.cljs
@@ -0,0 +1,57 @@
+(ns logseq.common.graph-dir
+  "Platform-agnostic graph directory naming helpers."
+  (:require [clojure.string :as string]
+            [logseq.common.config :as common-config]))
+
+(defn encode-graph-dir-name
+  [graph-name]
+  (let [encoded (js/encodeURIComponent (or graph-name ""))]
+    (-> encoded
+        (string/replace "%20" " ")
+        (string/replace "~" "%7E")
+        (string/replace "%" "~"))))
+
+(defn decode-graph-dir-name
+  [dir-name]
+  (when-not (and (string? dir-name)
+                 (or (string/includes? dir-name "++")
+                     (string/includes? dir-name "+3A+")))
+    (when (some? dir-name)
+      (try
+        (js/decodeURIComponent (string/replace dir-name "~" "%"))
+        (catch :default _
+          nil)))))
+
+(def ^:private legacy-dir-pattern #"(?:\+\+|\+3A\+|%)")
+
+(defn decode-legacy-graph-dir-name
+  [dir-name]
+  (when (and (string? dir-name)
+             (re-find legacy-dir-pattern dir-name))
+    (let [compat-name (-> dir-name
+                          (string/replace "+3A+" ":")
+                          (string/replace "++" "/"))]
+      (try
+        (let [decoded (js/decodeURIComponent compat-name)]
+          (when (seq decoded)
+            decoded))
+        (catch :default _
+          nil)))))
+
+(defn repo->graph-dir-key
+  [repo]
+  (when (seq repo)
+    (if (string/starts-with? repo common-config/db-version-prefix)
+      (subs repo (count common-config/db-version-prefix))
+      repo)))
+
+(defn graph-dir-key->encoded-dir-name
+  [graph-dir-key]
+  (when (some? graph-dir-key)
+    (encode-graph-dir-name graph-dir-key)))
+
+(defn repo->encoded-graph-dir-name
+  [repo]
+  (some-> repo
+          repo->graph-dir-key
+          graph-dir-key->encoded-dir-name))
diff --git a/deps/db-sync/.carve/ignore b/deps/db-sync/.carve/ignore
index 7979afb245..f234f1b130 100644
--- a/deps/db-sync/.carve/ignore
+++ b/deps/db-sync/.carve/ignore
@@ -26,6 +26,8 @@ logseq.db-sync.worker/worker
 ;; debugging
 logseq.db-sync.worker.timing/summary
 ;; API
+logseq.db-sync.snapshot/finalize-datoms-jsonl-buffer
+;; API
 logseq.db-sync.checksum/recompute-checksum-diagnostics
 ;; API (test runner entrypoint)
 logseq.db-sync.test-runner/main
diff --git a/deps/db-sync/src/logseq/db_sync/malli_schema.cljs b/deps/db-sync/src/logseq/db_sync/malli_schema.cljs
index b3ed276242..d9140a94b6 100644
--- a/deps/db-sync/src/logseq/db_sync/malli_schema.cljs
+++ b/deps/db-sync/src/logseq/db_sync/malli_schema.cljs
@@ -148,7 +148,7 @@
 (def graphs-list-response-schema
   [:map
    [:graphs [:sequential graph-info-schema]]
-   [:user-rsa-keys-exists? :boolean]])
+   [:user-rsa-keys-exists? {:optional true} :boolean]])
 
 (def graph-create-request-schema
   [:map
diff --git a/deps/db-sync/src/logseq/db_sync/node/graph.cljs b/deps/db-sync/src/logseq/db_sync/node/graph.cljs
index 5e171b9d70..8cb7707ed5 100644
--- a/deps/db-sync/src/logseq/db_sync/node/graph.cljs
+++ b/deps/db-sync/src/logseq/db_sync/node/graph.cljs
@@ -8,14 +8,18 @@
          :removeWebSocket (fn [ws] (swap! sockets disj ws))}))
 
 (defn- env-object [cfg index-db assets-bucket]
-  (doto (js-obj)
-    (aset "DB" index-db)
-    (aset "LOGSEQ_SYNC_ASSETS" assets-bucket)
-    ;; Keep node-adapter snapshot stream uncompressed.
-    (aset "DB_SYNC_SNAPSHOT_STREAM_GZIP" "false")
-    (aset "COGNITO_ISSUER" (:cognito-issuer cfg))
-    (aset "COGNITO_CLIENT_ID" (:cognito-client-id cfg))
-    (aset "COGNITO_JWKS_URL" (:cognito-jwks-url cfg))))
+  (let [allow-unverified-jwt-claims (some-> js/process .-env (aget "DB_SYNC_ALLOW_UNVERIFIED_JWT_CLAIMS"))
+        env (doto (js-obj)
+              (aset "DB" index-db)
+              (aset "LOGSEQ_SYNC_ASSETS" assets-bucket)
+              ;; Keep node-adapter snapshot stream uncompressed.
+              (aset "DB_SYNC_SNAPSHOT_STREAM_GZIP" "false")
+              (aset "COGNITO_ISSUER" (:cognito-issuer cfg))
+              (aset "COGNITO_CLIENT_ID" (:cognito-client-id cfg))
+              (aset "COGNITO_JWKS_URL" (:cognito-jwks-url cfg)))]
+    (when (some? allow-unverified-jwt-claims)
+      (aset env "DB_SYNC_ALLOW_UNVERIFIED_JWT_CLAIMS" allow-unverified-jwt-claims))
+    env))
 
 (defn graph-context
   [{:keys [config index-db assets-bucket]} graph-id]
diff --git a/deps/db-sync/src/logseq/db_sync/node/server.cljs b/deps/db-sync/src/logseq/db_sync/node/server.cljs
index 887f222a88..46d6340ba0 100644
--- a/deps/db-sync/src/logseq/db_sync/node/server.cljs
+++ b/deps/db-sync/src/logseq/db_sync/node/server.cljs
@@ -24,15 +24,19 @@
 (logging/install!)
 
 (defn- make-env [cfg index-db assets-bucket]
-  (doto (js-obj)
-    (aset "DB" index-db)
-    (aset "LOGSEQ_SYNC_ASSETS" assets-bucket)
-    ;; Node adapter serves snapshot transit stream without gzip to avoid
-    ;; browser/adapter content-encoding mismatches during graph download.
-    (aset "DB_SYNC_SNAPSHOT_STREAM_GZIP" "false")
-    (aset "COGNITO_ISSUER" (:cognito-issuer cfg))
-    (aset "COGNITO_CLIENT_ID" (:cognito-client-id cfg))
-    (aset "COGNITO_JWKS_URL" (:cognito-jwks-url cfg))))
+  (let [allow-unverified-jwt-claims (some-> js/process .-env (aget "DB_SYNC_ALLOW_UNVERIFIED_JWT_CLAIMS"))
+        env (doto (js-obj)
+              (aset "DB" index-db)
+              (aset "LOGSEQ_SYNC_ASSETS" assets-bucket)
+              ;; Node adapter serves snapshot transit stream without gzip to avoid
+              ;; browser/adapter content-encoding mismatches during graph download.
+              (aset "DB_SYNC_SNAPSHOT_STREAM_GZIP" "false")
+              (aset "COGNITO_ISSUER" (:cognito-issuer cfg))
+              (aset "COGNITO_CLIENT_ID" (:cognito-client-id cfg))
+              (aset "COGNITO_JWKS_URL" (:cognito-jwks-url cfg)))]
+    (when (some? allow-unverified-jwt-claims)
+      (aset env "DB_SYNC_ALLOW_UNVERIFIED_JWT_CLAIMS" allow-unverified-jwt-claims))
+    env))
 
 (defn- access-allowed?
   [env graph-id request]
diff --git a/deps/db-sync/src/logseq/db_sync/worker/auth.cljs b/deps/db-sync/src/logseq/db_sync/worker/auth.cljs
index 66bff29f1c..f9f62aa950 100644
--- a/deps/db-sync/src/logseq/db_sync/worker/auth.cljs
+++ b/deps/db-sync/src/logseq/db_sync/worker/auth.cljs
@@ -34,12 +34,28 @@
 (def ^:private recoverable-auth-errors
   #{"invalid" "iss not found" "aud not found" "exp" "kid"})
 
+(def ^:private truthy-env-values
+  #{"1" "true" "yes" "on"})
+
 (defn- recoverable-auth-error?
   [error]
   (when error
     (let [message (or (ex-message error) (some-> error .-message))]
       (contains? recoverable-auth-errors message))))
 
+(defn- env-flag-enabled?
+  [env k]
+  (let [v (some-> env (aget k))]
+    (cond
+      (true? v) true
+      (false? v) false
+      (string? v) (contains? truthy-env-values (string/lower-case v))
+      :else false)))
+
+(defn- allow-unverified-jwt-claims?
+  [env]
+  (env-flag-enabled? env "DB_SYNC_ALLOW_UNVERIFIED_JWT_CLAIMS"))
+
 (defn- expired-token?
   [token]
   (when-let [claims (unsafe-jwt-claims token)]
@@ -55,7 +71,13 @@
         (p/resolved nil)
         (-> (authorization/verify-jwt token env)
             (p/catch (fn [error]
-                       (if (recoverable-auth-error? error)
+                       (cond
+                         (recoverable-auth-error? error)
                          nil
+
+                         (allow-unverified-jwt-claims? env)
+                         (unsafe-jwt-claims token)
+
+                         :else
                          (p/rejected error))))))
       (p/resolved nil))))
diff --git a/deps/db-sync/src/logseq/db_sync/worker/handler/sync.cljs b/deps/db-sync/src/logseq/db_sync/worker/handler/sync.cljs
index 6a17a1fd06..eacf6ad040 100644
--- a/deps/db-sync/src/logseq/db_sync/worker/handler/sync.cljs
+++ b/deps/db-sync/src/logseq/db_sync/worker/handler/sync.cljs
@@ -274,9 +274,9 @@
              (let [value (.-value chunk)
                    {:keys [rows buffer]} (snapshot/parse-framed-chunk buffer value)
                    rows-count (count rows)
-                   reset? (and @reset-pending? (seq rows))]
+                   reset? (boolean (and @reset-pending? (seq rows)))]
                (when (seq rows)
-                 (import-snapshot! self rows (true? reset?))
+                 (import-snapshot! self rows reset?)
                  (vreset! reset-pending? false))
                (vswap! total-count + rows-count)
                (p/recur buffer)))))
diff --git a/deps/db-sync/src/logseq/db_sync/worker/ws.cljs b/deps/db-sync/src/logseq/db_sync/worker/ws.cljs
index 5c4846530b..5eed65c3d1 100644
--- a/deps/db-sync/src/logseq/db_sync/worker/ws.cljs
+++ b/deps/db-sync/src/logseq/db_sync/worker/ws.cljs
@@ -28,7 +28,9 @@
         (.send ws (protocol/encode-message {:type "error" :message "server error"}))))))
 
 (defn broadcast! [^js self sender msg]
-  (let [clients (.getWebSockets (.-state self))]
-    (doseq [ws clients]
-      (when (and (not= ws sender) (ws-open? ws))
-        (send! ws msg)))))
+  (when-let [state (some-> self .-state)]
+    (when (fn? (.-getWebSockets state))
+      (let [clients (.getWebSockets state)]
+        (doseq [ws clients]
+          (when (and (not= ws sender) (ws-open? ws))
+            (send! ws msg)))))))
diff --git a/deps/db-sync/test/logseq/db_sync/worker_auth_test.cljs b/deps/db-sync/test/logseq/db_sync/worker_auth_test.cljs
index da187c325e..ba57d2b032 100644
--- a/deps/db-sync/test/logseq/db_sync/worker_auth_test.cljs
+++ b/deps/db-sync/test/logseq/db_sync/worker_auth_test.cljs
@@ -57,6 +57,22 @@
                           (is (= "jwks" (ex-message error)))
                           (done)))))))
 
+(deftest auth-claims-jwks-error-falls-back-to-unsafe-claims-when-enabled-test
+  (async done
+         (let [token "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1MSJ9.signature"
+               request (js/Request. "http://localhost/graphs"
+                                   #js {:headers #js {"authorization" (str "Bearer " token)}})
+               env #js {"DB_SYNC_ALLOW_UNVERIFIED_JWT_CLAIMS" "true"}]
+           (-> (p/with-redefs [authorization/verify-jwt
+                               (fn [_token _env]
+                                 (p/rejected (ex-info "jwks" {})))]
+                 (p/let [claims (auth/auth-claims request env)]
+                   (is (= "u1" (aget claims "sub")))))
+               (p/then (fn [] (done)))
+               (p/catch (fn [error]
+                          (is false (str error))
+                          (done)))))))
+
 (deftest auth-claims-expired-jwt-short-circuits-verification-test
   (async done
          (let [expired-token "eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjEsInN1YiI6InUxIn0.signature"
diff --git a/deps/db-sync/test/logseq/db_sync/worker_handler_sync_test.cljs b/deps/db-sync/test/logseq/db_sync/worker_handler_sync_test.cljs
index d867321bc6..f9e8667fcb 100644
--- a/deps/db-sync/test/logseq/db_sync/worker_handler_sync_test.cljs
+++ b/deps/db-sync/test/logseq/db_sync/worker_handler_sync_test.cljs
@@ -561,6 +561,56 @@
         (is (= "pull/ok" (:type pull-response)))
         (is (empty? (:txs pull-response)))))))
 
+(deftest tx-batch-keeps-created-by-ref-lookup-payload-test
+  (testing "created-by lookup payload is preserved for save-block tx"
+    (let [sql (test-sql/make-sql)
+          conn (storage/open-conn sql)
+          self #js {:sql sql
+                    :conn conn
+                    :schema-ready true}
+          page-uuid (random-uuid)
+          missing-user-uuid (random-uuid)
+          missing-user-ref [:block/uuid missing-user-uuid]
+          tx-entry {:tx (protocol/tx->transit [[:db/add -1 :block/uuid page-uuid]
+                                               [:db/add -1 :block/name "created-by-sanitize-page"]
+                                               [:db/add -1 :block/title "created-by-sanitize-page"]
+                                               [:db/add -1 :logseq.property/created-by-ref missing-user-ref]])
+                    :outliner-op :save-block}
+          response (with-redefs [ws/broadcast! (fn [& _] nil)]
+                     (sync-handler/handle-tx-batch! self nil [tx-entry] 0))
+          page (d/entity @conn [:block/uuid page-uuid])]
+      (is (= "tx/batch/ok" (:type response)))
+      (is (= 1 (:t response)))
+      (is (some? page))
+      (is (= "created-by-sanitize-page" (:block/title page)))
+      (is (= missing-user-ref (:logseq.property/created-by-ref page))))))
+
+(deftest tx-batch-rejects-missing-page-ref-lookups-test
+  (testing "missing page refs/tags lookup refs reject create-page tx"
+    (let [sql (test-sql/make-sql)
+          conn (storage/open-conn sql)
+          self #js {:sql sql
+                    :conn conn
+                    :schema-ready true}
+          page-uuid (random-uuid)
+          missing-ref-uuid (random-uuid)
+          missing-tag-uuid (random-uuid)
+          missing-user-uuid (random-uuid)
+          tx-entry {:tx (protocol/tx->transit [[:db/add -1 :block/uuid page-uuid]
+                                               [:db/add -1 :block/name "optional-ref-sanitize-page"]
+                                               [:db/add -1 :block/title "optional-ref-sanitize-page"]
+                                               [:db/add -1 :block/refs [:block/uuid missing-ref-uuid]]
+                                               [:db/add -1 :block/tags [:block/uuid missing-tag-uuid]]
+                                               [:db/add -1 :logseq.property/created-by-ref [:block/uuid missing-user-uuid]]])
+                    :outliner-op :create-page}
+          response (with-redefs [ws/broadcast! (fn [& _] nil)]
+                     (sync-handler/handle-tx-batch! self nil [tx-entry] 0))
+          page (d/entity @conn [:block/uuid page-uuid])]
+      (is (= "tx/reject" (:type response)))
+      (is (= "db transact failed" (:reason response)))
+      (is (= 0 (:t response)))
+      (is (nil? page)))))
+
 (deftest tx-batch-rejects-while-snapshot-upload-is-in-progress-test
   (let [sql (test-sql/make-sql)
         conn (d/create-conn db-schema/schema)
@@ -640,6 +690,33 @@
                           (is false (str error))
                           (done)))))))
 
+(deftest import-snapshot-stream-first-non-empty-chunk-applies-reset-test
+  (async done
+         (let [rows [[42 "payload" nil]]
+               frame (#'sync-handler/frame-bytes (snapshot/encode-rows rows))
+               stream (js/ReadableStream.
+                       #js {:start (fn [controller]
+                                     (.enqueue controller frame)
+                                     (.close controller))})
+               applied (atom [])
+               self #js {:sql (test-sql/make-sql)
+                         :conn (d/create-conn db-schema/schema)
+                         :schema-ready true}]
+           (-> (p/with-redefs [sync-handler/import-snapshot!
+                               (fn [_self rows* reset?]
+                                 (swap! applied conj {:rows rows*
+                                                      :reset? reset?}))]
+                 (p/let [count (#'sync-handler/import-snapshot-stream! self stream true)]
+                   (is (= 1 count))
+                   (is (= [{:rows rows
+                            :reset? true}]
+                          @applied))))
+               (p/then (fn []
+                         (done)))
+               (p/catch (fn [error]
+                          (is false (str error))
+                          (done)))))))
+
 (deftest tx-batch-rejects-when-a-tx-entry-fails-test
   (testing "db transact failure rejects the batch"
     (let [sql (test-sql/make-sql)
diff --git a/deps/db/.carve/config.edn b/deps/db/.carve/config.edn
index df4528d2d1..8068ab7858 100644
--- a/deps/db/.carve/config.edn
+++ b/deps/db/.carve/config.edn
@@ -9,6 +9,8 @@
                   logseq.db.sqlite.create-graph
                   logseq.db.frontend.malli-schema
                   logseq.db.frontend.asset
+                  ;; Used outside deps/db by frontend worker and electron modules.
+                  logseq.db.sqlite.backup
                   ;; Some fns are used by frontend but not worth moving over yet
                   logseq.db.frontend.schema
                   logseq.db.frontend.validate
diff --git a/deps/db/src/logseq/db/common/sqlite.cljs b/deps/db/src/logseq/db/common/sqlite.cljs
index 9bfae51898..3c658ce3a9 100644
--- a/deps/db/src/logseq/db/common/sqlite.cljs
+++ b/deps/db/src/logseq/db/common/sqlite.cljs
@@ -3,6 +3,8 @@
   (:require ["path" :as node-path]
             [clojure.string :as string]
             [datascript.core :as d]
+            [logseq.common.graph-dir :as graph-dir]
+            [logseq.common.path :as path]
             [logseq.db.sqlite.util :as sqlite-util]))
 
 (defn create-kvs-table!
@@ -26,11 +28,11 @@
 
 (defn get-db-full-path
   [graphs-dir db-name]
-  (let [db-name' (sanitize-db-name db-name)
-        graph-dir (node-path/join graphs-dir db-name')]
-    [db-name' (node-path/join graph-dir "db.sqlite")]))
+  (let [graph-dir-name (graph-dir/repo->encoded-graph-dir-name db-name)
+        graph-dir (node-path/join graphs-dir graph-dir-name)]
+    [graph-dir-name (path/path-join graph-dir "db.sqlite")]))
 
 (defn get-db-backups-path
   [graphs-dir db-name]
-  (let [db-name' (sanitize-db-name db-name)]
-    (node-path/join graphs-dir db-name' "backups")))
+  (let [graph-dir-name (graph-dir/repo->encoded-graph-dir-name db-name)]
+    (path/path-join graphs-dir graph-dir-name "backups")))
diff --git a/deps/db/src/logseq/db/common/sqlite_cli.cljs b/deps/db/src/logseq/db/common/sqlite_cli.cljs
index 778e6a970b..13cd4231bb 100644
--- a/deps/db/src/logseq/db/common/sqlite_cli.cljs
+++ b/deps/db/src/logseq/db/common/sqlite_cli.cljs
@@ -1,11 +1,11 @@
 (ns ^:node-only logseq.db.common.sqlite-cli
   "Primary ns to interact with DB files with node.js based CLIs"
   (:require ["better-sqlite3" :as sqlite3]
-            ["os" :as os]
             ["path" :as node-path]
             [cljs-bean.core :as bean]
             [clojure.string :as string]
             [datascript.storage :refer [IStorage]]
+            [logseq.common.graph :as common-graph]
             [logseq.db.common.sqlite :as common-sqlite]
             [logseq.db.frontend.schema :as db-schema]
             [logseq.db.sqlite.util :as sqlite-util]))
@@ -22,6 +22,7 @@
 (defn- upsert-addr-content!
   "Upsert addr+data-seq. Should be functionally equivalent to db-worker/upsert-addr-content!"
   [db data]
+  (assert db ::upsert-addr-content!)
   (let [insert (.prepare db "INSERT INTO kvs (addr, content, addresses) values ($addr, $content, $addresses) on conflict(addr) do update set content = $content, addresses = $addresses")
         insert-many (.transaction ^object db
                                   (fn [data]
@@ -99,5 +100,4 @@
                              ;; $ORIGINAL_PWD used by bb tasks to correct current dir
                                (node-path/join (or js/process.env.ORIGINAL_PWD ".") %))]
         ((juxt node-path/dirname node-path/basename) (resolve-path' graph-dir-or-path)))
-      ;; TODO: Reuse with get-db-graphs-dir when there is a db ns that is usable by electron i.e. no better-sqlite3
-      [(node-path/join (os/homedir) "logseq" "graphs") graph-dir-or-path])))
+      [(common-graph/expand-home (common-graph/get-default-graphs-dir)) graph-dir-or-path])))
diff --git a/deps/db/src/logseq/db/frontend/db.cljs b/deps/db/src/logseq/db/frontend/db.cljs
index 4f875b5e4f..b67461ea05 100644
--- a/deps/db/src/logseq/db/frontend/db.cljs
+++ b/deps/db/src/logseq/db/frontend/db.cljs
@@ -21,7 +21,7 @@
                   (:db/ident property-entity))))
 
 (defn private-built-in-page?
-  "Private built-in pages should not be navigable or searchable by users. Later it
+  "Private built-in pages should not be navigable, searchable or editable by users. Later it
    could be useful to use this for the All Pages view"
   [page]
   (cond (entity-util/property? page)
diff --git a/deps/db/src/logseq/db/frontend/db_ident.cljc b/deps/db/src/logseq/db/frontend/db_ident.cljc
index b681d15b2e..03e33e9a99 100644
--- a/deps/db/src/logseq/db/frontend/db_ident.cljc
+++ b/deps/db/src/logseq/db/frontend/db_ident.cljc
@@ -75,9 +75,9 @@
   (assert (not (re-find #"^(logseq|block)(\.|$)" (name user-namespace)))
           "New ident is not allowed to use an internal namespace")
   (if #?(:org.babashka/nbb true
-         :cljs             (exists? js/process)
+         ;; Use $LOGSEQ_STABLE_IDENTS when we want stable idents e.g. tests
+         :cljs             (and (exists? js/process) js/process.env.LOGSEQ_STABLE_IDENTS)
          :default          false)
-     ;; Used for contexts where we want repeatable idents e.g. tests and CLIs
     (keyword user-namespace (normalize-ident-name-part name-string))
     (let [plugin? (string/starts-with? user-namespace "plugin.class.")
           suffix (str "-"
diff --git a/deps/db/src/logseq/db/frontend/property.cljs b/deps/db/src/logseq/db/frontend/property.cljs
index fb349d263b..3d7eb3de8d 100644
--- a/deps/db/src/logseq/db/frontend/property.cljs
+++ b/deps/db/src/logseq/db/frontend/property.cljs
@@ -26,7 +26,7 @@
      * :cardinality - property cardinality. Default to one/single cardinality if not set
      * :hide? - Boolean which hides property when set on a block or exported e.g. slides
      * :public? - Boolean which allows property to be used by user: add and remove property to blocks/pages
-       and queryable via property and has-property rules
+       and queryable via property and has-property rules. When it's not set, it's the same as false
      * :view-context - Keyword to indicate which view contexts a property can be
        seen in when :public? is set. Valid values are :page, :block and :never. Property can
        be viewed in any context if not set
@@ -635,6 +635,11 @@
                                                         :public? false
                                                         :hide? true}})))
 
+(def public-built-in-properties
+  (->> built-in-properties
+       (keep (fn [[k v]] (when (get-in v [:schema :public?]) k)))
+       set))
+
 (def db-attribute-properties
   "Internal properties that are also db schema attributes"
   #{:block/alias :block/tags :block/parent
@@ -741,6 +746,11 @@
   ;; Disallow tags or page refs as they would create unreferenceable page names
   (not (re-find #"^(#|\[\[)" s)))
 
+(defn built-in-closed-values
+  "Gets :closed-values for given built-in property ident"
+  [ident]
+  (get-in built-in-properties [ident :closed-values]))
+
 (defn get-closed-property-values
   [db property-id]
   (when db
diff --git a/deps/db/src/logseq/db/frontend/property/type.cljs b/deps/db/src/logseq/db/frontend/property/type.cljs
index e04eb033d3..16c44eca4d 100644
--- a/deps/db/src/logseq/db/frontend/property/type.cljs
+++ b/deps/db/src/logseq/db/frontend/property/type.cljs
@@ -23,7 +23,7 @@
 (def user-allowed-internal-property-types
   "Internal property types that users are allowed to store. These aren't available in the UI
    so these would normally be created via EDN or the API."
-  #{:map})
+  #{:map :json :string})
 
 (assert (set/subset? user-allowed-internal-property-types internal-built-in-property-types))
 
diff --git a/deps/db/src/logseq/db/sqlite/backup.cljs b/deps/db/src/logseq/db/sqlite/backup.cljs
new file mode 100644
index 0000000000..1bcee037f9
--- /dev/null
+++ b/deps/db/src/logseq/db/sqlite/backup.cljs
@@ -0,0 +1,46 @@
+(ns logseq.db.sqlite.backup
+  "Shared SQLite backup utilities for Node runtimes."
+  (:require ["node:sqlite" :as node-sqlite]
+            [clojure.string :as string]
+            [goog.object :as gobj]
+            [promesa.core :as p]))
+
+(defn- resolve-database-sync-ctor
+  []
+  (or (gobj/get node-sqlite "DatabaseSync")
+      (some-> (gobj/get node-sqlite "default")
+              (gobj/get "DatabaseSync"))
+      (let [default-export (gobj/get node-sqlite "default")]
+        (when (fn? default-export)
+          default-export))
+      (throw (ex-info "node:sqlite DatabaseSync constructor missing"
+                      {:module-keys (js->clj (js/Object.keys node-sqlite))}))))
+
+(def ^:private DatabaseSync
+  (resolve-database-sync-ctor))
+
+(defn- resolve-sqlite-backup-fn
+  []
+  (or (gobj/get node-sqlite "backup")
+      (some-> (gobj/get node-sqlite "default")
+              (gobj/get "backup"))
+      (throw (ex-info "node:sqlite backup function missing"
+                      {:module-keys (js->clj (js/Object.keys node-sqlite))}))))
+
+(def ^:private sqlite-backup-fn
+  (resolve-sqlite-backup-fn))
+
+(defn backup-connection!
+  [^js db path]
+  (sqlite-backup-fn db path))
+
+(defn backup-db-file!
+  [src-path dst-path]
+  (let [db (new DatabaseSync src-path)]
+    (-> (backup-connection! db dst-path)
+        (p/finally (fn []
+                     (try
+                       (.close db)
+                       (catch :default error
+                         (when-not (string/includes? (str error) "database is not open")
+                           (throw error)))))))))
diff --git a/deps/graph-parser/README.md b/deps/graph-parser/README.md
index 7de5848680..f67565c795 100644
--- a/deps/graph-parser/README.md
+++ b/deps/graph-parser/README.md
@@ -36,10 +36,8 @@ This step is not needed if you're just running the frontend application.
 
 ### Testing
 
-Since this library is compatible with cljs and nbb-logseq, tests are run against both languages.
-
-Nbb tests use [nbb-test-runner](https://github.com/nextjournal/nbb-test-runner).
-Some basic usage:
+Testing is done with nbb-logseq and
+[nbb-test-runner](https://github.com/nextjournal/nbb-test-runner). Some basic usage:
 
 ```
 # Run all tests
@@ -50,13 +48,6 @@ $ pnpm test -H
 $ pnpm test -i focus
 ```
 
-ClojureScript tests use https://github.com/Olical/cljs-test-runner. To run tests:
-```
-clojure -M:test
-```
-
-To see available options that can run specific tests or namespaces: `clojure -M:test --help`
-
 ### Managing dependencies
 
 The package.json dependencies are just for testing and should be updated if there is
diff --git a/deps/outliner/src/logseq/outliner/core.cljs b/deps/outliner/src/logseq/outliner/core.cljs
index 5b84b3c118..3bd06b0d40 100644
--- a/deps/outliner/src/logseq/outliner/core.cljs
+++ b/deps/outliner/src/logseq/outliner/core.cljs
@@ -461,6 +461,11 @@
       (throw (ex-info "Block eid doesn't exist"
                       {:block block})))
     (when-let [entity (d/entity db eid)]
+      (when (outliner-validate/built-in-entity? entity)
+        (throw (ex-info "Built-in nodes can't be modified"
+                        {:type :notification
+                         :payload {:message "Built-in nodes can't be modified"
+                                   :type :error}})))
       (let [*txs-state (atom [])
             block' (if (de/entity? block)
                      block
@@ -838,15 +843,15 @@
   (let [top-level-blocks (filter-top-level-blocks db blocks)
         non-consecutive? (and (> (count top-level-blocks) 1) (seq (ldb/get-non-consecutive-blocks db top-level-blocks)))
         top-level-blocks* (get-top-level-blocks top-level-blocks non-consecutive?)
-        top-level-blocks (remove :logseq.property/built-in? top-level-blocks*)
+        top-level-blocks (remove outliner-validate/built-in-entity? top-level-blocks*)
         txs-state (ds/new-outliner-txs-state)
         block-ids (map (fn [b] [:block/uuid (:block/uuid b)]) top-level-blocks)
         start-block (first top-level-blocks)
         end-block (last top-level-blocks)
         delete-one-block? (or (= 1 (count top-level-blocks)) (= start-block end-block))]
 
-    ;; Validate before `when` since top-level-blocks will be empty when deleting one built-in block
-    (when (seq (filter :logseq.property/built-in? top-level-blocks*))
+    ;; Validate before `when` since top-level-blocks will be empty when deleting one built-in/internal block
+    (when (seq (filter outliner-validate/built-in-entity? top-level-blocks*))
       (throw (ex-info "Built-in nodes can't be deleted"
                       {:type :notification
                        :payload {:message "Built-in nodes can't be deleted."
@@ -934,6 +939,13 @@
                              :as opts}]
   {:pre [(seq blocks)]}
   (when (m/validate block-map-or-entity target-block)
+    (doseq [b blocks]
+      (let [entity (d/entity @conn (:db/id b))]
+        (when (outliner-validate/built-in-entity? entity)
+          (throw (ex-info "Built-in nodes can't be modified"
+                          {:type :notification
+                           :payload {:message "Built-in nodes can't be modified"
+                                     :type :error}})))))
     (let [db @conn
           top-level-blocks (filter-top-level-blocks db blocks)
           [target-block sibling?] (get-target-block db top-level-blocks target-block opts)
diff --git a/deps/outliner/src/logseq/outliner/page.cljs b/deps/outliner/src/logseq/outliner/page.cljs
index eb8f0fa169..0df4d7baae 100644
--- a/deps/outliner/src/logseq/outliner/page.cljs
+++ b/deps/outliner/src/logseq/outliner/page.cljs
@@ -195,11 +195,9 @@
 ;; TODO: Revisit title cleanup as this was copied from file implementation
 (defn ^:api sanitize-title
   [title]
-  (let [title      (-> (string/trim title)
-                       (text/page-ref-un-brackets!)
-                        ;; remove `#` from tags
-                       (string/replace #"^#+" ""))
-        title      (common-util/remove-boundary-slashes title)]
+  (let [title (-> (string/trim title)
+                  (text/page-ref-un-brackets!))
+        title (common-util/remove-boundary-slashes title)]
     title))
 
 (defn- get-page-by-parent-name
@@ -310,6 +308,7 @@
         class? (or class? (some (fn [t] (= :logseq.class/Tag (:db/ident t))) tags))
         class-ident-namespace? (and class? class-ident-namespace (string? class-ident-namespace))
         title (sanitize-title title*)
+        _ (outliner-validate/validate-page-title-no-hashtag title {:node {:block/title title}})
         types (cond class?
                     #{:logseq.class/Tag}
                     today-journal?
diff --git a/deps/outliner/src/logseq/outliner/property.cljs b/deps/outliner/src/logseq/outliner/property.cljs
index 767cc6fc4a..91098a4959 100644
--- a/deps/outliner/src/logseq/outliner/property.cljs
+++ b/deps/outliner/src/logseq/outliner/property.cljs
@@ -94,6 +94,7 @@
   [entities property-ident]
   (throw-error-if-deleting-protected-property (map :db/ident entities) property-ident)
   (when (= :block/tags property-ident) (throw-error-if-removing-private-tag entities))
+  (outliner-validate/disallow-editing-private-built-in-nodes entities)
   (throw-error-if-deleting-required-property property-ident))
 
 (defn- build-property-value-tx-data
@@ -184,14 +185,18 @@
       (and new-type old-ref-type? (not ref-type?))
       (conj [:db/retract (:db/id property) :db/valueType]))))
 
-(defn- update-property
-  [conn db-ident property schema {:keys [property-name properties]}]
+(defn- validate-property-name-update
+  [conn property property-name]
   (when (and (some? property-name) (not= property-name (:block/title property)))
     (outliner-validate/validate-page-title property-name {:node property})
     (outliner-validate/validate-page-title-characters property-name {:node property})
     (outliner-validate/validate-block-title @conn property-name property)
-    (outliner-validate/validate-property-title property-name))
+    (outliner-validate/validate-property-title property-name)))
 
+(defn- update-property
+  [conn db-ident property schema {:keys [property-name properties]}]
+  (validate-property-name-update conn property property-name)
+  (outliner-validate/validate-editing-built-in-property property schema)
   (let [changed-property-attrs
         ;; Only update property if something has changed as we are updating a timestamp
         (cond-> (->> (dissoc schema :db/cardinality)
@@ -219,13 +224,21 @@
                           (mapcat
                            (fn [[property-id v]]
                              (build-property-value-tx-data conn property property-id v)) properties)))
-        many->one? (and (db-property/many? property) (= :one (:db/cardinality schema)))]
+        many->one? (and (db-property/many? property)
+                        ;; For UI calls, :db/cardinality can have :one and :many values
+                        (contains? #{:one :db.cardinality/one} (:db/cardinality schema)))]
     (when (and many->one? (seq (d/datoms @conn :avet db-ident)))
       (throw (ex-info "Disallowed many to one conversion"
                       {:type :notification
                        :payload {:message "This property can't change from multiple values to one value because it has existing data."
                                  :i18n-key :property.validation/many-to-one
                                  :type :warning}})))
+    (when (and (contains? changed-property-attrs :logseq.property/type)
+               (seq (d/datoms @conn :avet db-ident)))
+      (throw (ex-info "Disallowed type change with existing data"
+                      {:type :notification
+                       :payload {:message "This property's type can't be changed because it has existing data."
+                                 :type :error}})))
     (when (seq tx-data)
       (ldb/transact! conn tx-data {:outliner-op :update-property
                                    :property-id (:db/id property)}))
@@ -407,14 +420,37 @@
                       v)]
         (find-or-create-property-value conn property-id v')))))
 
+(defn- convert-ref-property-values
+  [conn property-id value property-type {:keys [many?]}]
+  (if-not (and many? (or (sequential? value) (set? value)))
+    (convert-ref-property-value conn property-id value property-type)
+    (try
+      (mapv #(convert-ref-property-value conn property-id % property-type) value)
+      (catch :default e
+        (throw (ex-info "Failed to convert many property values"
+                        (merge
+                         {:property-id property-id
+                          :property-type property-type
+                          :value value
+                          :many? many?
+                          :value-shape (cond
+                                         (vector? value) :vector
+                                         (set? value) :set
+                                         (sequential? value) :seq
+                                         :else :single)}
+                         (ex-data e))
+                        e))))))
+
 (defn- throw-error-if-self-value
   [block value ref?]
-  (when (and ref? (= value (:db/id block)))
-    (throw (ex-info "Can't set this block itself as own property value"
-                    {:type :notification
-                     :payload {:message "Can't set this block itself as own property value."
-                               :i18n-key :property.validation/cant-set-self-value
-                               :type :error}}))))
+  (let [values (if (or (sequential? value) (set? value)) value [value])]
+    (when (and ref?
+               (some #(= % (:db/id block)) values))
+      (throw (ex-info "Can't set this block itself as own property value"
+                      {:type :notification
+                       :payload {:message "Can't set this block itself as own property value."
+                                 :i18n-key :property.validation/cant-set-self-value
+                                 :type :error}})))))
 
 (defn batch-remove-property!
   [conn block-ids property-id]
@@ -467,9 +503,21 @@
             (ldb/transact! conn txs
                            {:outliner-op :batch-remove-property})))))))
 
+(defn- validate-batch-set-property
+  [conn block-eids property-id v]
+  (outliner-validate/disallow-editing-private-built-in-nodes (mapv #(d/entity @conn %) block-eids))
+  (when (= property-id :block/tags)
+    (outliner-validate/validate-tags-property @conn block-eids v))
+  (when (= property-id :logseq.property.class/extends)
+    (outliner-validate/validate-extends-property
+     @conn
+     (if (number? v) (d/entity @conn v) v)
+     (map #(d/entity @conn %) block-eids))))
+
 (defn batch-set-property!
   "Sets properties for multiple blocks. Automatically handles property value refs.
-   Does no validation of property values."
+   Does no validation of property values. For :many properties, passing a collection
+   replaces existing values in one call, while passing a scalar preserves add-single-value behavior."
   ([conn block-ids property-id v]
    (batch-set-property! conn block-ids property-id v {}))
   ([conn block-ids property-id v options]
@@ -478,24 +526,18 @@
    (if (nil? v)
      (batch-remove-property! conn block-ids property-id)
      (let [block-eids (map ->eid block-ids)
-           _ (when (= property-id :block/tags)
-               (outliner-validate/validate-tags-property @conn block-eids v))
+           _ (validate-batch-set-property conn block-eids property-id v)
            property (d/entity @conn property-id)
-           blocks (keep #(d/entity @conn %) block-eids)
-           _ (when (= (:db/ident property) :logseq.property.class/extends)
-               (outliner-validate/validate-extends-property
-                @conn
-                (if (number? v) (d/entity @conn v) v)
-                blocks))
            _ (when (nil? property)
                (throw (ex-info (str "Property " property-id " doesn't exist yet") {:property-id property-id})))
            property-type (get property :logseq.property/type :default)
+           many? (= :db.cardinality/many (:db/cardinality property))
            entity-id? (and (:entity-id? options) (number? v))
            ref? (contains? db-property-type/all-ref-property-types property-type)
            default-url-not-closed? (and (contains? #{:default :url} property-type)
                                         (not (seq (entity-plus/lookup-kv-then-entity property :property/closed-values))))
            v' (if (and ref? (not entity-id?))
-                (convert-ref-property-value conn property-id v property-type)
+                (convert-ref-property-values conn property-id v property-type {:many? many?})
                 v)
            _ (when (nil? v')
                (throw (ex-info "Property value must be not nil" {:v v})))
@@ -505,11 +547,17 @@
                    (if-let [block (d/entity @conn eid)]
                      (let [v' (if (and default-url-not-closed?
                                        (not (and (keyword? v) entity-id?)))
-                                (do
-                                  (when (number? v')
-                                    (throw-error-if-invalid-property-value @conn property v'))
-                                  (let [v (if (number? v') (:block/title (d/entity @conn v')) v')]
-                                    (convert-ref-property-value conn property-id v property-type)))
+                                (let [normalize-default-url-value
+                                      (fn [value]
+                                        (if (number? value)
+                                          (do
+                                            (throw-error-if-invalid-property-value @conn property value)
+                                            (:block/title (d/entity @conn value)))
+                                          value))
+                                      value' (if (and many? (or (sequential? v') (set? v')))
+                                               (mapv normalize-default-url-value v')
+                                               (normalize-default-url-value v'))]
+                                  (convert-ref-property-values conn property-id value' property-type {:many? many?}))
                                 v')]
                        (throw-error-if-self-value block v' ref?)
                        (throw-error-if-invalid-property-value @conn property v')
@@ -665,6 +713,7 @@
                 (prn "property-id: " property-id ", property-name: " property-name))
         (outliner-validate/validate-page-title k-name {:node {:db/ident db-ident'}})
         (outliner-validate/validate-page-title-characters k-name {:node {:db/ident db-ident'}})
+        (outliner-validate/validate-property-title k-name {:node {:db/ident db-ident'}})
         (let [db-id (:db/id properties)
               opts' (cond-> {:title k-name
                              :properties properties}
@@ -672,6 +721,7 @@
                       (assoc :block-uuid (:block/uuid (d/entity db db-id))))
               tx-data (concat
                        [(sqlite-util/build-new-property db-ident' schema opts')]
+                       ;; Convert page to property
                        (when db-id
                          [[:db/retract db-id :block/tags :logseq.class/Page]]))]
           (ldb/transact! conn tx-data
diff --git a/deps/outliner/src/logseq/outliner/validate.cljs b/deps/outliner/src/logseq/outliner/validate.cljs
index b744ea1409..b537027d0a 100644
--- a/deps/outliner/src/logseq/outliner/validate.cljs
+++ b/deps/outliner/src/logseq/outliner/validate.cljs
@@ -9,10 +9,11 @@
             [logseq.db :as ldb]
             [logseq.db.frontend.class :as db-class]
             [logseq.db.frontend.entity-util :as entity-util]
+            [logseq.db.frontend.malli-schema :as db-malli-schema]
             [logseq.db.frontend.property :as db-property]))
 
-(defn ^:api validate-page-title-characters
-  "Validates characters that must not be in a page title"
+(defn ^:api validate-page-title-no-hashtag
+  "Validates a page title doesn't include hashtag character"
   [page-title meta-m]
   (when (string/includes? page-title "#")
     (throw (ex-info "Page name can't include \"#\"."
@@ -20,7 +21,12 @@
                            {:type :notification
                             :payload {:message "Page name can't include \"#\"."
                                       :i18n-key :page.validation/name-no-hash
-                                      :type :warning}}))))
+                                      :type :warning}})))))
+
+(defn ^:api validate-page-title-characters
+  "Validates characters that must not be in a page title"
+  [page-title meta-m]
+  (validate-page-title-no-hashtag page-title meta-m)
   (when (and (string/includes? page-title ns-util/parent-char)
              (not (common-date/normalize-date page-title nil)))
     (throw (ex-info "Page name can't include \"/\"."
@@ -154,6 +160,22 @@
                                        :i18n-key :property.validation/invalid-name
                                        :type :error}}))))))
 
+(defn validate-editing-built-in-property
+  "Validates if built-in property entity is editable for the given attributes to be updated"
+  [entity attribute-map-to-update]
+   ;; Update allowed as needed. Keep this as an allowed list to default to safe editing for built-in entities
+  (let [allowed-attributes #{:logseq.property/hide-empty-value :logseq.property/description}]
+    (when-let [disallowed (and (:logseq.property/built-in? entity)
+                               (not-empty (set/difference (set (keys attribute-map-to-update))
+                                                          allowed-attributes)))]
+      (throw (ex-info "Given built-in property's attributes are not editable"
+                      (merge
+                       {:type :notification
+                        :payload {:message "Can't change the given attributes for a built-in property"
+                                  :type :error}}
+                       {:property (:db/ident entity)
+                        :disallowed-attributes disallowed}))))))
+
 (defn- validate-extends-property-have-correct-type
   "Validates whether given parent and children are classes"
   [parent-ent child-ents]
@@ -231,9 +253,21 @@
                        :property-id :block/tags
                        :property-value v})))))
 
+(defn built-in-entity?
+  "Returns true when the entity is a built-in. Ideally checking
+  :logseq.property/built-in? would be enough but not all built-in nodes have
+  that property. Covers:
+  - entities marked with :logseq.property/built-in?  (built-in pages, classes, properties)
+  - file entities  (logseq/config.edn, custom.css, etc.)
+  - entities whose :db/ident belongs to an internal namespace  (KV entries, empty-placeholder)"
+  [ent]
+  (or (:logseq.property/built-in? ent)
+      (:file/path ent)
+      (some-> (:db/ident ent) db-malli-schema/internal-ident?)))
+
 (defn- disallow-tagging-a-built-in-entity
   [db block-eids & {:keys [delete?]}]
-  (when-let [built-in-ent (some #(when (:logseq.property/built-in? %) %)
+  (when-let [built-in-ent (some #(when (built-in-entity? %) %)
                                 (map #(d/entity db %) block-eids))]
     (throw (ex-info (str (if delete? "Can't remove tag" "Can't add tag")
                          " on built-in " (pr-str (:block/title built-in-ent)))
@@ -328,3 +362,17 @@
   (disallow-tagging-a-built-in-entity db block-eids {:delete? true})
   (disallow-node-cant-tag-with-private-tags db block-eids v {:delete? true})
   (disallow-removing-page-tag db block-eids v))
+
+(defn disallow-editing-private-built-in-nodes
+  "Disallow editing private :built-in nodes. This explicit validation is needed for contexts
+   like CLI and API which allow users to edit any built-in entity whereas the app guards this
+   by not allowing users to navigate to private built-in nodes"
+  [entities]
+  (doseq [entity entities]
+    (when (and (built-in-entity? entity)
+               ;; This also checks private status of non-page ents like ents with :kv/value
+               (ldb/private-built-in-page? entity))
+      (throw (ex-info "Built-in private nodes can't be modified"
+                      {:type :notification
+                       :payload {:message "Built-in private nodes can't be modified"
+                                 :type :error}})))))
diff --git a/deps/outliner/test/logseq/outliner/core_test.cljs b/deps/outliner/test/logseq/outliner/core_test.cljs
index 276f144829..30ed0fa6b6 100644
--- a/deps/outliner/test/logseq/outliner/core_test.cljs
+++ b/deps/outliner/test/logseq/outliner/core_test.cljs
@@ -3,7 +3,8 @@
             [datascript.core :as d]
             [logseq.db :as ldb]
             [logseq.db.test.helper :as db-test]
-            [logseq.outliner.core :as outliner-core]))
+            [logseq.outliner.core :as outliner-core]
+            [logseq.common.config :as common-config]))
 
 (deftest test-delete-block-with-default-property
   (testing "Delete block with default property hard retracts the block subtree"
@@ -50,3 +51,49 @@
           child' (db-test/find-block-by-content @conn "child")]
       (is (nil? parent'))
       (is (nil? child')))))
+
+(deftest delete-blocks-rejects-built-in-entities
+  (let [conn (db-test/create-conn)]
+    (testing "built-in page is rejected"
+      (let [recycle-page (ldb/get-page @conn common-config/recycle-page-name)]
+        (is (true? (:logseq.property/built-in? recycle-page)))
+        (is (thrown-with-msg? js/Error #"Built-in nodes can't be deleted"
+                              (db-test/silence-stderr (outliner-core/delete-blocks! conn [recycle-page] {}))))))
+
+    (testing "built-in idents that are not a class or property like empty-placeholder are rejected"
+      (let [placeholder (d/entity @conn :logseq.property/empty-placeholder)]
+        (is (some? (:block/uuid placeholder)))
+        (is (thrown-with-msg? js/Error #"Built-in nodes can't be deleted"
+                              (db-test/silence-stderr (outliner-core/delete-blocks! conn [placeholder] {}))))))
+
+    (testing "file entity is rejected"
+      (let [file (->> (d/datoms @conn :avet :file/path)
+                      first
+                      :e
+                      (d/entity @conn))]
+        (is (some? (:file/path file)))
+        (is (thrown-with-msg? js/Error #"Built-in nodes can't be deleted"
+                              (db-test/silence-stderr (outliner-core/delete-blocks! conn [file] {}))))))
+
+    (testing "KV entity is rejected"
+      (let [kv (d/entity @conn :logseq.kv/db-type)]
+        (is (some? (:db/id kv)))
+        (is (thrown-with-msg? js/Error #"Built-in nodes can't be deleted"
+                              (db-test/silence-stderr (outliner-core/delete-blocks! conn [kv] {}))))))))
+
+(deftest save-block-rejects-built-in-entity
+  (let [conn (db-test/create-conn)
+        placeholder (d/entity @conn :logseq.property/description)]
+    (is (thrown-with-msg? js/Error #"Built-in.*can't be modified"
+          (db-test/silence-stderr
+            (outliner-core/save-block! conn {:db/id (:db/id placeholder) :block/title "hacked"}))))))
+
+(deftest move-blocks-rejects-built-in-entity
+  (let [conn (db-test/create-conn-with-blocks
+              [{:page {:block/title "page1"}
+                :blocks [{:block/title "target"}]}])
+        placeholder (d/entity @conn :logseq.property/description)
+        target (db-test/find-block-by-content @conn "target")]
+    (is (thrown-with-msg? js/Error #"Built-in.*can't be modified"
+          (db-test/silence-stderr
+            (outliner-core/move-blocks! conn [placeholder] target {:sibling? true}))))))
\ No newline at end of file
diff --git a/deps/outliner/test/logseq/outliner/page_test.cljs b/deps/outliner/test/logseq/outliner/page_test.cljs
index 6b977d9413..d5f679dabf 100644
--- a/deps/outliner/test/logseq/outliner/page_test.cljs
+++ b/deps/outliner/test/logseq/outliner/page_test.cljs
@@ -97,7 +97,19 @@
          js/Error
          #"can't include \"/"
          (outliner-page/create! conn "foo/bar" {}))
-        "Page can't have '/'n title")))
+        "Page can't have '/'n title")
+
+    (is (thrown-with-msg?
+         js/Error
+         #"can't include \"#\""
+         (outliner-page/create! conn "foo#bar" {}))
+        "Page can't have '#' in title")
+
+    (is (thrown-with-msg?
+         js/Error
+         #"can't include \"#\""
+         (outliner-page/create! conn "#tagstyle" {}))
+        "Page can't have leading '#' in title")))
 
 (deftest delete-page
   (let [conn (db-test/create-conn-with-blocks
diff --git a/deps/outliner/test/logseq/outliner/property_test.cljs b/deps/outliner/test/logseq/outliner/property_test.cljs
index 336d682961..c0548df578 100644
--- a/deps/outliner/test/logseq/outliner/property_test.cljs
+++ b/deps/outliner/test/logseq/outliner/property_test.cljs
@@ -45,6 +45,20 @@
              (:block/title (d/entity @conn :user.property/p1-2)))
           "3rd property gets unique ident"))))
 
+(deftest upsert-property-rejects-type-change-with-existing-data
+  (testing "Changing type is rejected when property has values"
+    (let [conn (db-test/create-conn-with-blocks
+                [{:page {:block/title "page1"}
+                  :blocks [{:block/title "b1" :build/properties {:status "active"}}]}])]
+      (is (thrown-with-msg?
+           js/Error #"Disallowed type change with existing data"
+           (outliner-property/upsert-property! conn :user.property/status {:logseq.property/type :number} {})))))
+
+  (testing "Changing type is allowed when property has no values"
+    (let [conn (db-test/create-conn-with-blocks {:properties {:empty-prop {:logseq.property/type :default}}})]
+      (outliner-property/upsert-property! conn :user.property/empty-prop {:logseq.property/type :number} {})
+      (is (= :number (:logseq.property/type (d/entity @conn :user.property/empty-prop)))))))
+
 (deftest convert-property-input-string
   (testing "Convert property input string according to its schema type"
     (let [test-uuid (random-uuid)]
@@ -185,17 +199,68 @@
     (is (nil? (:user.property/default updated-block)) "Block property is deleted")))
 
 (deftest batch-set-property!
-  (let [conn (db-test/create-conn-with-blocks
-              [{:page {:block/title "page1"}
-                :blocks [{:block/title "item 1"}
-                         {:block/title "item 2"}]}])
-        block-ids (map #(-> (db-test/find-block-by-content @conn %) :block/uuid) ["item 1" "item 2"])
-        _ (outliner-property/batch-set-property! conn block-ids :logseq.property/order-list-type "number")
-        updated-blocks (map #(db-test/find-block-by-content @conn %) ["item 1" "item 2"])]
-    (is (= ["number" "number"]
-           (map #(db-property/property-value-content (:logseq.property/order-list-type %))
-                updated-blocks))
-        "Property values are batch set")))
+  (testing "Set built-in property values for multiple blocks"
+    (let [conn (db-test/create-conn-with-blocks
+                [{:page {:block/title "page1"}
+                  :blocks [{:block/title "item 1"}
+                           {:block/title "item 2"}]}])
+          block-ids (map #(-> (db-test/find-block-by-content @conn %) :block/uuid) ["item 1" "item 2"])
+          _ (outliner-property/batch-set-property! conn block-ids :logseq.property/order-list-type "number")
+          updated-blocks (map #(db-test/find-block-by-content @conn %) ["item 1" "item 2"])]
+      (is (= ["number" "number"]
+             (map #(db-property/property-value-content (:logseq.property/order-list-type %))
+                  updated-blocks))
+          "Property values are batch set")))
+
+  (testing "Set custom default-many property values from string vector"
+    (let [conn (db-test/create-conn-with-blocks
+                {:properties {:user.property/reproducible-steps {:logseq.property/type :default
+                                                                 :db/cardinality :db.cardinality/many
+                                                                 :logseq.property/public? true}}
+                 :pages-and-blocks [{:page {:block/title "page1"}
+                                     :blocks [{:block/title "target"}]}]})
+          block-id (:block/uuid (db-test/find-block-by-content @conn "target"))]
+      (outliner-property/batch-set-property! conn [block-id] :user.property/reproducible-steps ["Step 1" "Step 2" "Step 3"])
+      (is (= #{"Step 1" "Step 2" "Step 3"}
+             (->> (:user.property/reproducible-steps (d/entity @conn [:block/uuid block-id]))
+                  (map db-property/property-value-content)
+                  set))
+          "String vector values are persisted as many property values")))
+
+  (testing "Set custom default-many property values from id vector"
+    (let [conn (db-test/create-conn-with-blocks
+                {:properties {:user.property/reproducible-steps {:logseq.property/type :default
+                                                                 :db/cardinality :db.cardinality/many
+                                                                 :logseq.property/public? true}}
+                 :pages-and-blocks [{:page {:block/title "page1"}
+                                     :blocks [{:block/title "source"
+                                               :build/properties {:user.property/reproducible-steps #{"Step 1" "Step 2" "Step 3"}}}
+                                              {:block/title "target"}]}]})
+          source-values (->> (:user.property/reproducible-steps (db-test/find-block-by-content @conn "source"))
+                             (map :db/id)
+                             vec)
+          target-id (:block/uuid (db-test/find-block-by-content @conn "target"))]
+      (outliner-property/batch-set-property! conn [target-id] :user.property/reproducible-steps source-values)
+      (is (= #{"Step 1" "Step 2" "Step 3"}
+             (->> (:user.property/reproducible-steps (d/entity @conn [:block/uuid target-id]))
+                  (map db-property/property-value-content)
+                  set))
+          "Id vector values are persisted as many property values")))
+
+  (testing "Invalid many values throw and don't partially persist"
+    (let [conn (db-test/create-conn-with-blocks
+                {:properties {:user.property/reproducible-steps {:logseq.property/type :default
+                                                                 :db/cardinality :db.cardinality/many
+                                                                 :logseq.property/public? true}}
+                 :pages-and-blocks [{:page {:block/title "page1"}
+                                     :blocks [{:block/title "target"}]}]})
+          block-id (:block/uuid (db-test/find-block-by-content @conn "target"))]
+      (is (thrown-with-msg?
+           js/Error
+           #"Schema validation failed"
+           (outliner-property/batch-set-property! conn [block-id] :user.property/reproducible-steps [999999])))
+      (is (nil? (:user.property/reproducible-steps (d/entity @conn [:block/uuid block-id])))
+          "No partial values are persisted on failure"))))
 
 (deftest status-property-setting-classes
   (let [conn (db-test/create-conn-with-blocks
@@ -223,6 +288,14 @@
            (mapv :db/ident (:block/tags (d/entity @conn [:block/uuid project]))))
         "Doesn't add Task to block when it is already tagged")))
 
+(deftest batch-set-property-rejects-private-built-in-entity
+  (let [conn (db-test/create-conn)
+        placeholder (d/entity @conn :logseq.property/empty-placeholder)
+        prop (d/entity @conn :logseq.property/description)]
+    (is (thrown-with-msg? js/Error #"Built-in.*can't be modified"
+                          (db-test/silence-stderr
+                           (outliner-property/batch-set-property! conn [(:db/id placeholder)] (:db/ident prop) "hacked"))))))
+
 (deftest batch-remove-property!
   (let [conn (db-test/create-conn-with-blocks
               {:classes {:C1 {}}
@@ -247,6 +320,14 @@
          #"Can't remove required"
          (outliner-property/batch-remove-property! conn [(:db/id (d/entity @conn :user.class/C1))] :logseq.property.class/extends)))))
 
+(deftest batch-remove-property-rejects-private-built-in-entity
+  (let [conn (db-test/create-conn)
+        placeholder (d/entity @conn :logseq.property/empty-placeholder)
+        prop (d/entity @conn :logseq.property/description)]
+    (is (thrown-with-msg? js/Error #"Built-in.*can't be modified"
+                          (db-test/silence-stderr
+                           (outliner-property/batch-remove-property! conn [(:db/id placeholder)] (:db/ident prop)))))))
+
 (deftest add-existing-values-to-closed-values!
   (let [conn (db-test/create-conn-with-blocks
               [{:page {:block/title "page1"}
@@ -379,4 +460,4 @@
                                               (:db/id (d/entity @conn :user.class/C1)))
     (is (= [:logseq.class/Root]
            (:logseq.property.class/extends (db-test/readable-properties (d/entity @conn :user.class/C3))))
-        "Extends property is restored back to Root")))
+        "Extends property is restored back to Root")))
\ No newline at end of file
diff --git a/deps/outliner/test/logseq/outliner/validate_test.cljs b/deps/outliner/test/logseq/outliner/validate_test.cljs
index 1334c5799b..6d0590a41c 100644
--- a/deps/outliner/test/logseq/outliner/validate_test.cljs
+++ b/deps/outliner/test/logseq/outliner/validate_test.cljs
@@ -248,6 +248,27 @@
          (outliner-validate/validate-tags-property-deletion @conn [(:db/id page)] :logseq.class/Page))
         "Page without parent can't remove #Page")))
 
+(deftest validate-editing-built-in-property
+  (let [conn (db-test/create-conn-with-blocks
+              {:properties {:myprop {:logseq.property/type :default}}})
+        user-prop (d/entity @conn :user.property/myprop)
+        built-in-prop (d/entity @conn :block/tags)]
+
+    (testing "user property can edit any attribute"
+      (is (nil? (outliner-validate/validate-editing-built-in-property
+                 user-prop {:db/cardinality :db.cardinality/many}))))
+
+    (testing "built-in property cannot edit disallowed attribute"
+      (is (thrown-with-msg?
+           js/Error
+           #"not editable"
+           (outliner-validate/validate-editing-built-in-property
+            built-in-prop {:block/title "renamed"}))))
+
+    (testing "built-in property can edit allowed attribute"
+      (is (nil? (outliner-validate/validate-editing-built-in-property
+                 built-in-prop {:logseq.property/hide-empty-value true}))))))
+
 ;; Try as many of the validations against a new graph to confirm
 ;; that validations make sense and are valid for a new graph
 (deftest new-graph-should-be-valid
diff --git a/dist/logseq.js b/dist/logseq.js
new file mode 100755
index 0000000000..28b93e441c
--- /dev/null
+++ b/dist/logseq.js
@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+
+require(path.resolve(__dirname, "../static/logseq-cli.js"));
diff --git a/docs/agent-guide/001-logseq-cli.md b/docs/agent-guide/001-logseq-cli.md
new file mode 100644
index 0000000000..0be698f64c
--- /dev/null
+++ b/docs/agent-guide/001-logseq-cli.md
@@ -0,0 +1,166 @@
+# Logseq CLI Implementation Plan
+
+Goal: Build a new Logseq CLI in ClojureScript that runs on Node.js and connects to the db-worker-node server.
+
+Architecture: The CLI is a Node-targeted ClojureScript program built via shadow-cljs and packaged with a small JavaScript launcher.
+The CLI speaks a simple request and response protocol to the existing db-worker-node HTTP or WebSocket API and exposes high-level subcommands for users.
+
+Tech Stack: ClojureScript, shadow-cljs :node-script target, Node.js runtime, existing db-worker-node server.
+
+Related: Relates to docs/agent-guide/task--basic-logseq-cli.md and docs/agent-guide/task--db-worker-nodejs-compatible.md.
+
+## Problem statement
+
+We need a new Logseq CLI that is independent of any existing CLI code in the repo.
+The CLI must run in Node.js, be written in ClojureScript, and connect to the db-worker-node server started from dist/db-worker-node.js.
+The CLI should provide a stable interface for scripting and troubleshooting, and it should be easy to extend with new commands.
+
+## Testing Plan
+
+I will add an integration test that starts db-worker-node on a test port and verifies the CLI can connect and run a simple graph/content request.
+I will add unit tests for command parsing, configuration precedence, and error formatting.
+I will add unit tests for the client transport layer to ensure timeouts behave correctly.
+I will add unit tests for new graph/content commands (parsing, validation, and request mapping).
+I will add integration tests for graph lifecycle commands and content commands against a real db-worker-node.
+I will follow @test-driven-development for all behavior changes.
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Architecture sketch
+
+The CLI is a Node program that parses flags, loads config, and sends requests to db-worker-node.
+The db-worker-node server is already built from the :db-worker-node shadow-cljs target and listens on a random localhost TCP port recorded in the lock file.
+
+ASCII diagram:
+
++--------------+        HTTP or WS        +---------------------+
+| logseq-cli   | -----------------------> | db-worker-node       |
+| node script  | <----------------------- | server on random port |
++--------------+                          +---------------------+
+
+## Assumptions
+
+The db-worker-node server exposes a stable API for a small set of requests needed by the CLI.
+The CLI always uses localhost and discovers the server port from the lock file.
+The CLI will use JSON for request and response bodies for ease of scripting.
+
+## Implementation plan
+
+1. Use tool(update_plan) to track the full task list and include the @test-driven-development red-green-refactor steps.
+2. Read @test-driven-development guidelines and confirm the red phase will include all CLI tests first.
+3. Identify existing db-worker-node request handlers and document their request and response shapes.
+4. Define the initial CLI command surface as a table that includes command, input, output, and errors.
+5. Decide on transport protocol based on db-worker-node capabilities and document the selection.
+6. Add a new shadow-cljs build target named :logseq-cli with :target :node-script and a dedicated output file in static/.
+7. Create a new namespace for the CLI entrypoint in src/main/cli/main.cljs and wire it as the :main for the build.
+8. Create src/main/cli/config.cljs with config resolution order of CLI flags, env vars, then config file.
+9. Create src/main/cli/transport.cljs with a small client that can send requests and parse responses.
+10. Create src/main/cli/commands.cljs with pure functions that map parsed args to transport requests.
+11. Create src/main/cli/format.cljs that formats success and error output for human and machine usage.
+12. Add unit tests in src/test/logseq/cli for config precedence, command parsing, and error formatting behavior.
+13. Add integration tests in src/test/logseq/cli that start db-worker-node and invoke the CLI entrypoint.
+14. Run tests in red phase with bb dev:test -v and confirm failures are behavior-related.
+15. Implement the minimal code to make the tests pass and re-run in green phase.
+16. Refactor for naming and reuse while keeping tests green.
+17. Document how to build and run the CLI in a short section in README.md.
+
+## Current status (2026-01-14)
+
+Implemented:
+- CLI build target, entrypoint, config resolution, transport, formatting, and command wiring.
+- Graph commands: list/create/switch/remove/validate/info.
+- Content commands: add/remove/search/tree.
+- Unit tests for config/commands/format/transport and integration tests for graph/content commands.
+- CLI docs moved to `docs/cli/logseq-cli.md` and linked from README.
+
+Not fully aligned with plan:
+- Red-first TDD sequence was not strictly followed (some tests added after initial implementation).
+- README section was replaced by a link to the dedicated doc.
+- `search` currently queries `:block/title` only (no page name/content search).
+
+Open follow-ups (optional):
+- Expand `search` to include page name/content and update tests.
+- Add any additional graph metadata to `graph-info` beyond `:logseq.kv/graph-created-at` and `:logseq.kv/schema-version`.
+
+## Command surface definition
+
+| Command | Input | Output | Errors |
+| --- | --- | --- | --- |
+| graph-list | none | list of graphs | server unavailable, timeout |
+| graph-create | graph name | created graph + set current graph | invalid name, server unavailable |
+| graph-switch | graph name | switched graph + set current graph | missing graph, server unavailable |
+| graph-remove | graph name | removal confirmation | missing graph, server unavailable |
+| graph-validate | graph name or current graph | validation result | missing graph, server unavailable |
+| graph-info | graph name or current graph | graph metadata/info | missing graph, server unavailable |
+| add | block/page payload | created block IDs | invalid input, server unavailable |
+| remove | block/page id or name | removal confirmation | invalid input, server unavailable |
+| search | text query | matched blocks/pages | invalid input, server unavailable |
+| tree | block/page id or name | hierarchical tree output | invalid input, server unavailable |
+
+## Edge cases
+
+The db-worker-node server is not running or the lock file points to a stale server.
+The response payload is invalid JSON or missing fields.
+The request times out or the server closes the connection early.
+The user passes incompatible flags or unknown commands.
+The CLI is run on Windows where path and quoting rules differ.
+Graph commands are invoked without a current graph configured.
+Content commands are invoked without specifying a graph and no current graph is set.
+Content commands refer to missing pages/blocks.
+Graph removal is attempted while a graph is open.
+
+## Testing commands and expected output
+
+Run a single unit test in red phase.
+
+```bash
+bb dev:test -v 'logseq.cli.config-test/test-config-precedence'
+```
+
+Expected output includes a failing assertion and ends with a non-zero exit code.
+
+Run the full unit test suite in green phase.
+
+```bash
+bb dev:test -v 'logseq.cli.commands-test'
+```
+
+Expected output includes 0 failures and 0 errors.
+
+Run lint and unit tests when all work is complete.
+
+```bash
+bb dev:lint-and-test
+```
+
+Expected output includes successful linting and tests with exit code 0.
+
+## Testing Details
+
+I will add behavior-driven tests that verify the CLI connects to a real db-worker-node process and that each command returns the expected output for valid input.
+I will keep unit tests focused on pure functions like parsing, formatting, and config resolution, and avoid mocking internal implementation details.
+
+## Implementation Details
+
+- Add a new shadow-cljs build target for the CLI with a node-script output in static/.
+- Create a dedicated CLI entrypoint namespace that handles args, logging, and exit codes.
+- Implement config resolution for flags, env vars, and optional config file.
+- Implement a transport client with timeouts and explicit error mapping.
+- Define a small command map with functions that return request objects and output renderers.
+- Add structured JSON output mode for scripting alongside human-readable output.
+- Ensure the CLI exits with non-zero status codes on errors.
+- Document build and run steps, including starting db-worker-node first.
+- Add graph management commands that map to db-worker thread-apis.
+- Add graph content commands (add/remove/search/tree) with clear input formats and output.
+- Persist/resolve a “current graph” for commands that default to current context.
+
+## Question
+
+Which exact db-worker-node endpoints and request schemas should the CLI use for graph/content commands.
+- Answer: all thread-apis are available in http endpoint, check @src/main/frontend/worker/db_worker_node.cljs
+
+Do we want WebSocket or HTTP as the default transport for the CLI.
+- HTTP
+
+Can I consult the clojure-expert and research-agent agents for architecture and reference implementations as required by the planning guidelines.
+- yes
+---
diff --git a/docs/agent-guide/002-logseq-cli-subcommands.md b/docs/agent-guide/002-logseq-cli-subcommands.md
new file mode 100644
index 0000000000..8e14f38fd0
--- /dev/null
+++ b/docs/agent-guide/002-logseq-cli-subcommands.md
@@ -0,0 +1,165 @@
+# Logseq CLI Subcommands Implementation Plan
+
+Goal: Replace the CLI argument parser with babashka/cli and expose every command as a subcommand with consistent help and output formats.
+
+Architecture: The CLI remains a Node-targeted ClojureScript program built via shadow-cljs, but command parsing moves to babashka/cli with an explicit subcommand map. The CLI entrypoint will delegate to per-subcommand parsers and handlers that return a consistent result envelope that is rendered to human, JSON, or EDN output.
+
+Tech Stack: ClojureScript, babashka/cli, shadow-cljs, Node.js runtime, db-worker-node HTTP API.
+
+Related: Builds on docs/agent-guide/001-logseq-cli.md.
+
+## Problem statement
+
+The current CLI uses clojure.tools.cli with a flat flag set and manual command detection.
+This limits help text, makes subcommand-specific options awkward, and complicates output formatting consistency.
+We need to migrate to babashka/cli so that each command is a first-class subcommand with its own help, and so output formats are consistent across all commands.
+
+## Testing Plan
+
+I will add unit tests that validate babashka/cli subcommand parsing for every command and its flags.
+I will add unit tests that assert each subcommand renders help and that top-level help includes all subcommands.
+I will add unit tests that verify output formatting for human, JSON, and EDN across success and error paths for each subcommand.
+I will add integration tests that invoke the Node CLI with subcommands and verify consistent output formats for graph and content commands.
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Architecture sketch
+
++--------------+        HTTP        +---------------------+
+| logseq-cli   | -----------------> | db-worker-node        |
+| node script  | <----------------- | server on random port |
++--------------+                    +---------------------+
+
+## Command and output surface
+
+The CLI will expose these subcommands and shared output controls.
+
+| Subcommand | Purpose | Output formats | Notes |
+| --- | --- | --- | --- |
+| graph list | List graphs | human, json, edn | Replaces graph-list |
+| graph create | Create graph | human, json, edn | Replaces graph-create |
+| graph switch | Switch current graph | human, json, edn | Replaces graph-switch |
+| graph remove | Remove graph | human, json, edn | Replaces graph-remove |
+| graph validate | Validate graph | human, json, edn | Replaces graph-validate |
+| graph info | Graph metadata | human, json, edn | Replaces graph-info |
+| block add | Add blocks | human, json, edn | Replaces add |
+| block remove | Remove block or page | human, json, edn | Replaces remove |
+| search | Search graph | human, json, edn | Replaces search |
+| block tree | Show tree | human, json, edn | Replaces tree |
+
+The plan assumes a single global output flag that defaults to human, and each subcommand may also accept it.
+
+## Subcommand map design
+
+Global options apply to all subcommands and are parsed before subcommand options.
+
+| Option | Purpose | Notes |
+| --- | --- | --- |
+| --help | Show help | Available at top level and per subcommand. |
+| --version | Show version | Prints build time and revision. |
+| --config PATH | Config file path | Defaults to ~/logseq/cli.edn. |
+| --graph GRAPH | Graph name | Used as current graph. |
+| --timeout-ms MS | Request timeout | Integer milliseconds. |
+| --output FORMAT | Output format | One of human, json, edn. |
+
+Each subcommand uses a nested path and its own options.
+
+| Subcommand path | Required args | Options | Notes |
+| --- | --- | --- | --- |
+| graph list | none | --output | Lists all graphs. |
+| graph create | none | --graph GRAPH, --output | Creates and switches graph. |
+| graph switch | none | --graph GRAPH, --output | Switches current graph. |
+| graph remove | none | --graph GRAPH, --output | Removes graph. |
+| graph validate | none | --graph GRAPH, --output | Validates graph. |
+| graph info | none | --graph GRAPH, --output | Shows metadata, defaults to config repo if omitted. |
+| block add | none | --content TEXT, --blocks EDN, --blocks-file PATH, --page PAGE, --parent UUID, --output | Content source is required, with file and text variants. |
+| block remove | none | --block UUID, --page PAGE, --output | One of block or page is required. |
+| search | QUERY | --type page|block|tag|property|all, --tag NAME, --case-sensitive, --sort updated-at|created-at, --order asc|desc, --output | Search text is positional and required. Human output columns: ID (db/id), TITLE. Block reference UUIDs in text are resolved recursively up to 10 levels. |
+| block tree | none | --block UUID, --page PAGE, --format FORMAT, --output | One of block or page is required, and format controls tree rendering. |
+
+## Plan
+
+1. Consult the clojure-expert agent about babashka/cli idioms for nested subcommands and help generation.
+2. Consult the research-agent for a reference implementation of babashka/cli subcommand parsing in ClojureScript, including Node usage.
+3. Review current CLI documentation in docs/cli/logseq-cli.md and list all existing flags and examples that must be preserved.
+4. Review the current parser and action mapping in src/main/logseq/cli/commands.cljs and list which options are command-specific versus global.
+5. Create a babashka/cli command map design and capture it in this document as a table of subcommands, arguments, and defaults.
+6. Write new unit tests for top-level help output in src/test/logseq/cli/commands_test.cljs that assert subcommand listing and usage text.
+7. Write new unit tests for each subcommand parse path in src/test/logseq/cli/commands_test.cljs covering required args, missing args, and unknown flags.
+8. Write new unit tests in src/test/logseq/cli/format_test.cljs that assert human, json, and edn output for success and error results.
+9. Write new unit tests in src/test/logseq/cli/config_test.cljs for output format precedence between flags, env, and config file.
+10. Write new integration tests in src/test/logseq/cli/integration_test.cljs that invoke the built CLI with subcommands and verify outputs for at least one graph and one block command in each format.
+11. Run the new tests to confirm they fail for the current parser and output handling.
+12. Replace the parser in src/main/logseq/cli/commands.cljs with babashka/cli, using a subcommand map and per-command option specs.
+13. Update src/main/logseq/cli/main.cljs to route to babashka/cli and return subcommand-specific help when requested.
+14. Update src/main/logseq/cli/config.cljs to add a unified output format option and ensure json and edn are both supported.
+15. Update src/main/logseq/cli/format.cljs so that all commands emit consistent human, json, or edn output using a single option path.
+16. Update docs/cli/logseq-cli.md to document subcommands, shared output flags, and per-subcommand help examples.
+17. Run the unit test suite with bb dev:test -v 'logseq.cli.commands-test' and confirm 0 failures and 0 errors.
+18. Run lint and tests with bb dev:lint-and-test and confirm a zero exit code.
+19. Refactor for naming clarity, shared helpers, and reduced duplication while keeping tests green.
+
+## Status
+
+- Completed: Plan tasks 1-10, 12-19.
+- Skipped: Plan task 11 (red-phase confirmation no longer applicable after parser swap).
+
+## Edge cases
+
+Missing subcommand should show top-level help with a non-zero exit code.
+Unknown subcommands should show a helpful error that includes the available subcommands.
+Subcommand-specific help should not require a working db-worker-node server.
+Output format flags should be accepted both at the top level and at subcommand level without conflict.
+Existing config keys such as :output-format and the legacy --json flag should either be preserved or mapped with a clear deprecation path.
+Windows quoting should be covered for block add subcommand with multi-word content arguments.
+
+## Testing commands and expected output
+
+Run a single failing unit test in red phase.
+
+```bash
+bb dev:test -v 'logseq.cli.commands-test/test-help-output'
+```
+
+Expected output includes a failing assertion about subcommand help text and ends with a non-zero exit code.
+
+Run the full unit test suite in green phase.
+
+```bash
+bb dev:test -r logseq.cli.*
+```
+
+Expected output includes 0 failures and 0 errors.
+
+Run lint and unit tests when all work is complete.
+
+```bash
+bb dev:lint-and-test
+```
+
+Expected output includes successful linting and tests with exit code 0.
+
+## Testing Details
+
+The unit tests will exercise parsing and output formatting behavior without mocking internal parser details.
+The integration tests will start db-worker-node on a random port and invoke the CLI entrypoint with subcommands to verify end-to-end behavior.
+
+## Implementation Details
+
+- Replace clojure.tools.cli usage with babashka/cli and define a nested subcommand map for graph and block groups.
+- Keep global options for server connection and output format and merge them with per-subcommand options.
+- Normalize output format selection to :human, :json, or :edn and route it through a single formatting function.
+- Preserve config precedence across flags, env vars, and config file while adding the output format option.
+- Ensure each subcommand has a help string and usage text generated by babashka/cli.
+- Keep error envelopes consistent with current :status and :error keys to avoid breaking existing scripts.
+- Update CLI docs to show subcommand usage and output format examples.
+- Add a transition note for legacy command names if backward compatibility is required.
+
+## Question
+
+Should we keep backwards compatibility for legacy command names like graph-list and add, or require the new subcommand forms only.
+- Answer: No need to keep backwards compatibility
+Should we retain the --json flag as an alias for --output json or remove it after a deprecation period.
+- Answer: remove --json, only keep --output
+Do we want --output edn and --output json to be accepted at both the top level and per-subcommand level.
+- Answer: yes, accept at both levels
+---
diff --git a/docs/agent-guide/003-db-worker-node-cli-orchestration.md b/docs/agent-guide/003-db-worker-node-cli-orchestration.md
new file mode 100644
index 0000000000..53fe6268d9
--- /dev/null
+++ b/docs/agent-guide/003-db-worker-node-cli-orchestration.md
@@ -0,0 +1,115 @@
+# db-worker-node and logseq-cli Orchestration Plan
+
+Goal: Based on the current `logseq-cli` and `db-worker-node` implementations, refactor db-worker-node to be repo-bound with locking, make logseq-cli fully manage db-worker-node lifecycle, and add server subcommands for management.
+
+## Background and Current State (from existing code)
+
+- `db-worker-node` currently accepts `--repo` but it is optional; it can open/switch graphs via `thread-api/create-or-open-db` at runtime. Entrypoint: `src/main/frontend/worker/db_worker_node.cljs`.
+- `logseq-cli` connects to an existing db-worker-node on localhost using the port recorded in the lock file; it does not start/stop the server. Entrypoint: `src/main/logseq/cli/main.cljs`, `src/main/logseq/cli/commands.cljs`, `src/main/logseq/cli/transport.cljs`.
+- Tests explicitly start db-worker-node (`src/test/logseq/cli/integration_test.cljs`, `src/test/frontend/worker/db_worker_node_test.cljs`).
+
+## Requirements
+
+1. Refactor `db-worker-node`: startup must require `--repo`; on startup it must open or create that graph; it must not switch graphs at runtime; it must create a lock file so a graph can be served by only one db-worker-node instance; it only needs to bind to localhost.
+2. In `logseq-cli`, all commands requiring `--graph` or any graph operations must connect to or create the corresponding db-worker-node server.
+3. db-worker-node server must not be started manually; logseq-cli is fully responsible.
+4. Add `server` subcommand(s) to logseq-cli for managing db-worker-node servers.
+
+## Scope / Non-goals
+
+- In scope: db-worker-node startup and lifecycle, repo binding enforcement, lock files, CLI server orchestration, management commands, tests/docs.
+- Out of scope: changing db-worker core query/write protocol; changing db-worker-node HTTP API semantics beyond repo binding constraints.
+
+## Proposed Design
+
+- **Repo-bound server**: db-worker-node opens a single repo at startup and refuses repo changes for the lifetime of the process. It only listens on localhost.
+- **Lock file**: each repo directory has a lock file to ensure one server per graph. Lock contains metadata for status/cleanup; db-worker-node handles it by default, and logseq-cli handles cases db-worker-node cannot.
+- **CLI orchestration**: logseq-cli discovers/starts/reuses db-worker-node servers per repo. It is the only entrypoint for starting servers.
+- **Server subcommands**: add `server list|status|start|stop|restart` (or similar) to manage servers explicitly.
+
+## Detailed Design
+
+### 1) db-worker-node: required repo, repo binding, lock file
+
+Files:
+- `src/main/frontend/worker/db_worker_node.cljs`
+- `src/main/frontend/worker/platform/node.cljs` (for data-dir / repo dir resolution)
+- Optional new helper: `src/main/frontend/worker/db_worker_node_lock.cljs`
+
+Key changes:
+- **Argument parsing**: `--repo` becomes required. If missing, print help and exit non-zero. Host binding is restricted to localhost (e.g., `127.0.0.1`) regardless of input.
+- **Startup flow**: replace `<maybe-open-repo!` with a required `create-or-open-db` for the repo; store `bound-repo`.
+- **Reject switching**:
+  - In `/v1/invoke`, for repo-scoped thread APIs, validate `args[0]` matches `bound-repo`.
+  - Reject `thread-api/create-or-open-db`, `thread-api/unsafe-unlink-db`, etc. when repo differs.
+  - Return 409/400 with `:repo-mismatch` error shape.
+- **Lock file**:
+  - Location: inside repo dir (e.g. `~/logseq/cli-graphs/<graph>/db-worker.lock`).
+  - Content: JSON `{repo, pid, host, port, startedAt}`.
+  - Creation: exclusive create (`fs.open` with `wx`) or atomic temp + rename. If exists, fail with “graph already locked”.
+  - Cleanup: delete lock file on stop (`stop!`) and on SIGINT/SIGTERM.
+  - Stale lock: if lock exists but pid is dead, allow replacement (db-worker-node first; CLI can repair when server cannot).
+
+### 2) logseq-cli: auto start/reuse db-worker-node per repo
+
+Files:
+- `src/main/logseq/cli/commands.cljs`
+- `src/main/logseq/cli/main.cljs`
+- `src/main/logseq/cli/config.cljs`
+- New: `src/main/logseq/cli/server.cljs` (process management + lock handling)
+
+Key changes:
+- **Repo resolution**: for all graph/content commands, require `--graph` or resolved repo from config; otherwise error.
+- **Ensure server** (new helper `ensure-server!`):
+  1. Derive data-dir, repo dir, and lock file path from repo.
+  2. If lock file exists, read port/pid; probe `/healthz` + `/readyz`.
+  3. If healthy, reuse existing server; build the connection URL from localhost and the lock file port.
+  4. If unhealthy or stale, attempt to spawn a new server; if db-worker-node cannot handle the lock situation, CLI repairs the lock then retries.
+  5. Spawn via `child_process.spawn`: `./dist/db-worker-node.js --repo <repo> --data-dir <...>`.
+  6. Resolve actual port from the lock file written by db-worker-node.
+- **Connection URL**: derived from the repo lock file; host is always localhost and the port is always discovered from the lock file.
+
+### 3) CLI `server` subcommands
+
+Suggested command group:
+- `server list`: list servers from lock files (repo, pid, port, status).
+- `server start --graph <name>`: start server for repo.
+- `server stop --graph <name>`: stop server (SIGTERM or `/v1/shutdown`).
+- `server restart --graph <name>`: stop + start.
+
+Implementation notes:
+- `start|stop|restart` require `--graph`.
+- `list` scans data-dir for repo directories, reads lock files, and verifies status.
+- Consider adding `/v1/shutdown` in db-worker-node for graceful stop.
+
+## Compatibility / Migration
+
+- No need to preserve compatibility for existing env vars, config keys, or flags related to db-worker-node or CLI server connectivity; remove them if they are no longer needed.
+
+## Test Plan
+
+- **Unit tests**:
+  - CLI: repo resolution, server orchestration logic, lock parsing, error codes (`src/test/logseq/cli/*`).
+  - db-worker-node: repo required, repo mismatch rejection, lock file create/cleanup (`src/test/frontend/worker/db_worker_node_test.cljs`).
+- **Integration tests**:
+  - CLI runs graph/content commands without manual server startup (`src/test/logseq/cli/integration_test.cljs`).
+  - Concurrent startup of same repo must fail due to lock.
+
+## Milestones
+
+1. **db-worker-node binding & lock file**: repo required + repo enforcement + lock creation/cleanup.
+2. **CLI server module**: `ensure-server!` with lock/health checks and spawning.
+3. **CLI command updates**: graph/content commands require repo and auto-start server; add `server` subcommands.
+4. **Tests + docs**: update/extend tests and adjust CLI docs (`docs/cli/logseq-cli.md`).
+
+## Open Questions
+
+1. Should `graph list` require `--graph`? If not, define a “global” server or out-of-band access to data-dir.
+   - Answer: No --graph needed, using 'out-of-band access to data-dir' way
+2. Lock file format and location: confirm cross-platform expectations (Windows paths/permissions).
+   - lockfile name:`db-worker.lock`,
+   - Location: inside repo dir (e.g. `~/logseq/cli-graphs/<graph>/db-worker.lock`).
+   - only consider linux/macos for now
+3. Who owns lock cleanup and stale lock handling: primarily db-worker-node; CLI only steps in for cases db-worker-node cannot handle.
+4. Add `/v1/shutdown` for graceful stop vs. SIGTERM from CLI?
+5. db-worker-node servers should keep running unless `logseq-cli server stop` is invoked or the process exits unexpectedly; in the latter case, CLI should handle lockfile cleanup on restart.
diff --git a/docs/agent-guide/004-logseq-cli-verb-subcommands.md b/docs/agent-guide/004-logseq-cli-verb-subcommands.md
new file mode 100644
index 0000000000..44fad77d27
--- /dev/null
+++ b/docs/agent-guide/004-logseq-cli-verb-subcommands.md
@@ -0,0 +1,218 @@
+# Logseq CLI Verb-First Subcommands Implementation Plan
+
+Goal: Refactor logseq-cli to remove the block subcommand group and replace it with verb-first subcommands for list, add, remove, search, and show.
+
+Architecture: Keep the babashka/cli dispatch table but reorganize it into verb-first subcommands, and route each verb to typed actions for pages, blocks, tags, and properties through existing db-worker-node thread-apis.
+
+Tech Stack: ClojureScript, babashka/cli, db-worker-node thread-apis, Datascript queries.
+
+Related: Builds on docs/agent-guide/003-db-worker-node-cli-orchestration.md and docs/agent-guide/002-logseq-cli-subcommands.md.
+
+## Problem statement
+
+The current CLI uses a block subcommand group, which makes the interface noun-first and inconsistent with graph and server commands.
+
+We need to make the CLI verb-first, so that content operations are consistent with other tooling and easier to extend for new resource types.
+
+The refactor must preserve existing behaviors for add, remove, search, and tree while adding list commands for pages, tags, and properties, and renaming tree to show.
+
+## Testing Plan
+
+I will add unit tests that cover verb-first parsing, group help output, and option validation for list, add, remove, search, and tree.
+
+I will add unit tests that assert list option parsing for each list subtype and that invalid flag combinations are rejected.
+
+I will add integration tests that run list, add, remove, search, and tree against a real db-worker-node with a test graph and assert output shapes.
+
+I will follow @test-driven-development for all behavior changes.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Command surface
+
+The block subcommand group is removed and replaced with verb-first subcommands.
+
+Help output groups commands into two sections, with Graph Inspect and Edit first, and Graph Management last.
+
+Group names and order:
+
+| Group | Commands | Order |
+| --- | --- | --- |
+| Graph Inspect and Edit | list, add, remove, search, show | First |
+| Graph Management | graph, server | Last |
+
+| Command | Subcommand | Purpose |
+| --- | --- | --- |
+| list | page | List pages |
+| list | tag | List tags |
+| list | property | List properties |
+| add | block | Add blocks |
+| add | page | Create page |
+| remove | block | Remove block |
+| remove | page | Remove page |
+| search | none | Search across resources |
+| show | none | Show block tree |
+
+Global options remain unchanged and are shared across all commands.
+
+## List options detail
+
+The list command should expose a consistent shape across resource types.
+
+Common list options:
+
+| Option | Applies to | Purpose | Notes |
+| --- | --- | --- | --- |
+| --expand | page, tag, property | Include expanded metadata | Maps to existing api-list-* expand behavior. |
+| --limit N | page, tag, property | Limit results | Implemented in CLI after fetch unless server supports it. |
+| --offset N | page, tag, property | Offset results | Implemented in CLI after fetch unless server supports it. |
+| --sort FIELD | page, tag, property | Sort results | Field whitelist per type. |
+| --order asc|desc | page, tag, property | Sort direction | Defaults to desc. |
+| --output FORMAT | all | Output format | Existing output handling. |
+
+List page options:
+
+| Option | Purpose | Notes |
+| --- | --- | --- |
+| --include-journal | Include journal pages | Default is include all. |
+| --journal-only | Only journal pages | Requires journal detection in api-list-pages. |
+| --include-hidden | Include hidden pages | Requires a flag to bypass entity-util/hidden? filtering. |
+| --updated-after ISO8601 | Filter by updated-at | Compare to :block/updated-at. |
+| --created-after ISO8601 | Filter by created-at | Compare to :block/created-at. |
+| --fields FIELD,FIELD | Select output fields | |
+
+List tag options:
+
+| Option | Purpose | Notes |
+| --- | --- | --- |
+| --include-built-in | Include built-in classes | Built-in tags are currently included by default, clarify behavior. |
+| --with-properties | Include class properties | Uses :logseq.property.class/properties when expanded. |
+| --with-extends | Include class extends | Uses :logseq.property.class/extends when expanded. |
+| --fields FIELD,FIELD | Select output fields | |
+
+List property options:
+
+| Option | Purpose | Notes |
+| --- | --- | --- |
+| --include-built-in | Include built-in properties | Built-in properties are currently included by default, clarify behavior. |
+| --with-classes | Include property classes | Uses :logseq.property/classes when expanded. |
+| --with-type | Include property type | Uses :logseq.property/type. |
+| --fields FIELD,FIELD | Select output fields | |
+
+List block is removed to avoid overlap with search.
+
+## Search options detail
+
+Search has no subcommands and searches across pages, blocks, tags, and properties by default. Human output columns are `ID` (db/id) and `TITLE`.
+Search and show outputs resolve block reference UUIDs in text. Nested references are resolved recursively up to 10 levels (e.g., `[[<uuid1>]]` → `[[some text [[<uuid2>]]]]`, then `<uuid2>` is also replaced).
+
+| Option | Purpose | Notes |
+| --- | --- | --- |
+| QUERY | Search text | Required positional argument. |
+| --type page|block|tag|property|all | Restrict types | Default is all. |
+| --tag NAME | Restrict to a specific tag | Tag is a class page, e.g. Page, Asset, Task. |
+| --case-sensitive | Case sensitive search | Default is case-insensitive. |
+| --sort updated-at|created-at | Sort results | Default is relevance or stable order. |
+| --order asc|desc | Sort direction | Defaults to desc for time sorts. |
+
+## Tree options detail
+
+Show has no subcommands and returns the block tree for a page or block.
+
+| Option | Purpose | Notes |
+| --- | --- | --- |
+| --id ID | Tree root by :db/id | Mutually exclusive with other identifiers. |
+| --uuid UUID | Tree root by :block/uuid | Mutually exclusive with other identifiers. |
+| --page-name NAME | Tree root by :block/title for a #Page block | Must be a page. |
+| --level N | Limit tree depth | N >= 1, default 10. |
+| --format text|json|edn | Output format | Existing behavior. |
+
+## Plan
+
+1. Review current CLI command parsing and action routing in src/main/logseq/cli/commands.cljs to map block group behavior to verb-first commands.
+2. Add failing unit tests in src/test/logseq/cli/commands_test.cljs for verb-first help output and parse behavior for list, add, remove, search, and show.
+3. Add failing unit tests that assert list subtype option parsing and validation for list page, list tag, and list property.
+4. Add failing unit tests that assert search defaults to all types and respects --type and positional text.
+5. Add failing unit tests that assert show accepts --page-name, --uuid, or --id and rejects missing targets.
+6. Run bb dev:test -v 'logseq.cli.commands-test/test-parse-args' and confirm failures are about the new verbs and options.
+7. Update src/main/logseq/cli/commands.cljs to replace block subcommands with verb-first entries and to add list subcommand group.
+8. Update summary helpers in src/main/logseq/cli/commands.cljs to show group help for list, add, and remove instead of block, and to render help groups as Graph Inspect and Edit first, Graph Management last.
+9. Update src/main/logseq/cli/main.cljs usage string to reflect the verb-first command surface.
+10. Add list option specs in src/main/logseq/cli/commands.cljs and update validation to enforce required args and mutually exclusive flags.
+11. Implement list actions in src/main/logseq/cli/commands.cljs that call existing thread-apis for pages, tags, and properties.
+12. Implement add page using thread-api/apply-outliner-ops with :create-page in src/main/logseq/cli/commands.cljs.
+13. Update search logic in src/main/logseq/cli/commands.cljs to query all resource types and honor --type, --tag, --sort, and --order.
+14. Update show logic in src/main/logseq/cli/commands.cljs to support --id, --uuid, --page-name, and --level.
+15. Add failing integration tests in src/test/logseq/cli/integration_test.cljs for list page, list tag, list property, add page, remove page, search all, and show.
+16. Run bb dev:test -v 'logseq.cli.integration-test/test-cli-list-and-search' and confirm failures before implementation.
+17. Implement behavior for list, add, remove, search, and show until all tests pass.
+18. Update docs/cli/logseq-cli.md with new verb-first commands and examples.
+19. Run bb dev:test -r logseq.cli.* and confirm 0 failures and 0 errors.
+20. Run bb dev:lint-and-test and confirm a zero exit code.
+
+## Edge cases
+
+Missing subcommand should return group help for list, add, or remove, and still exit with a non-zero status.
+
+Unknown subcommands should return a helpful error message that lists the valid subcommands.
+
+Add block should still default to today’s journal page when no page is provided and no parent is provided.
+
+Search across all types should avoid duplicate hits when a tag or property is also a page with the same title.
+
+Show should return a deterministic order based on :block/order.
+
+## Testing commands and expected output
+
+Run a single unit test in red phase.
+
+```bash
+bb dev:test -v 'logseq.cli.commands-test/test-parse-args'
+```
+
+Expected output includes failing assertions about the new verb-first commands and ends with a non-zero exit code.
+
+Run the integration tests in red phase.
+
+```bash
+bb dev:test -v 'logseq.cli.integration-test/test-cli-list-add-search-show-remove'
+```
+
+Expected output includes failing assertions about list and search output and ends with a non-zero exit code.
+
+Run the full suite in green phase.
+
+```bash
+bb dev:test -r logseq.cli.*
+```
+
+Expected output includes 0 failures and 0 errors.
+
+Run lint and tests after all changes.
+
+```bash
+bb dev:lint-and-test
+```
+
+Expected output includes successful linting and tests with exit code 0.
+
+## Testing Details
+
+The unit tests will validate parsing, help output, and option validation for each new verb-first command.
+
+The integration tests will create a temporary graph, add pages, tags, and properties, and verify list, search, and tree output against db-worker-node behavior.
+
+## Implementation Details
+
+- Replace block group entries with list, add, remove, search, and show in src/main/logseq/cli/commands.cljs.
+- Add list subtype specs and validation, including common list options and per-type field filtering in src/main/logseq/cli/commands.cljs.
+- Extend search to combine page, block, tag, and property queries and to enforce --type and --tag behavior in src/main/logseq/cli/commands.cljs.
+- Preserve existing add block and remove block behavior while changing only the command paths and option names.
+- Rename tree to show and add id, uuid, page-name, and level parsing in src/main/logseq/cli/commands.cljs.
+- Update docs/cli/logseq-cli.md to show new usage and examples.
+
+## Question
+
+None.
+
+---
diff --git a/docs/agent-guide/005-logseq-cli-output-and-db-worker-node-log.md b/docs/agent-guide/005-logseq-cli-output-and-db-worker-node-log.md
new file mode 100644
index 0000000000..c0d041d37c
--- /dev/null
+++ b/docs/agent-guide/005-logseq-cli-output-and-db-worker-node-log.md
@@ -0,0 +1,160 @@
+# Logseq CLI Output and db-worker-node Log Implementation Plan
+
+Goal: Improve all logseq-cli human output for clarity and usability, and write db-worker-node logs to <data-dir>/<graph-dir>/db-worker-node-YYYYMMDD.log with retention of the most recent 7 logs.
+
+Architecture: Add a dedicated human output formatter with per-command renderers and consistent error messaging in the CLI formatting layer.
+Add a file-based glogi appender for db-worker-node that writes logs into the graph-specific data directory using dated filenames and retention while keeping console logging behavior explicit and configurable.
+
+Tech Stack: ClojureScript, babashka/cli, lambdaisland.glogi, Node.js fs/path.
+
+Related: Builds on docs/agent-guide/004-logseq-cli-verb-subcommands.md and docs/agent-guide/003-db-worker-node-cli-orchestration.md.
+
+## Human Output Specification
+
+Target: plain text, no ANSI colors. Each command has a stable layout and ordering.
+
+| Command | OK output (human) | Empty output | Notes |
+| --- | --- | --- | --- |
+| graph list | Table with header `GRAPH` and rows of graph names, followed by `Count: N` | Header + `Count: 0` | Data from `{:graphs [...]}` |
+| graph create | `Graph created: <graph>` | n/a | Use graph name from action/options |
+| graph switch | `Graph switched: <graph>` | n/a | Use graph name from action/options |
+| graph remove | `Graph removed: <graph>` | n/a | Use graph name from action/options |
+| graph validate | `Graph validated: <graph>` | n/a | Use graph name from action/options |
+| graph info | Lines: `Graph: <graph>`, `Created at: <relative time>`, `Schema version: <v>` | n/a | Use `:logseq.kv/*` data; show `-` if missing; `Created at` should use the same human-friendly relative format as list outputs |
+| server list | Table with header `REPO STATUS HOST PORT PID`, rows for servers, followed by `Count: N` | Header + `Count: 0` | Data from `{:servers [...]}` |
+| server status/start/stop/restart | `Server <status>: <repo>` + details line `Host: <host>  Port: <port>` when available | n/a | Use `:status` keyword where present |
+| list page/tag/property | Table with header (fields vary by command) and rows, followed by `Count: N` | Header + `Count: 0` | Defaults: page/tag/property `ID TITLE UPDATED-AT CREATED-AT` (ID uses `:db/id`); if `:db/ident` present, include `IDENT` column |
+| add block | `Added blocks: <count> (repo: <repo>)` | n/a | Count = number of blocks submitted |
+| add page | `Added page: <page> (repo: <repo>)` | n/a | |
+| remove block | `Removed block: <block-id> (repo: <repo>)` | n/a | Prefer UUID if available |
+| remove page | `Removed page: <page> (repo: <repo>)` | n/a | |
+| search | Table with header `TYPE TITLE/CONTENT UUID UPDATED-AT CREATED-AT`, rows in stable order, followed by `Count: N` | Header + `Count: 0` | For block rows use content snippet; for tag/property rows omit timestamps |
+| show (text) | Raw tree text with `:db/id` as first column, trimmed | n/a | Tree lines should be prefixed by `:db/id` followed by the tree glyphs. Example:<br/><br/>`id1 block1`<br/>`id2 ├── b2`<br/>`id3 │   └── b3`<br/>`id4 ├── b4`<br/>`id5 │   ├── b5`<br/>`id6 │   │   └── b6`<br/>`id7 │   └── b7`<br/>`id8 └── b8`<br/><br/>If a block title spans multiple lines, show the first line on the tree line and indent the remaining lines under the glyph column. Example:<br/><br/>`168 Jan 18th, 2026`<br/>`169 ├── b1`<br/>`173 ├── aaaxx`<br/>`174 ├── block-line1`<br/>`    │   block-line2`<br/>`175 └── cccc`<br/><br/>For `--format json|edn`, keep existing structured output |
+| errors | `Error (<code>): <message>` + optional `Hint: <hint>` line | n/a | Ensure error codes are stable and consistent |
+
+## Problem statement
+
+The current logseq-cli human output is mostly raw pr-str output, which is hard to read and inconsistent across commands.
+Users need clearer, command-specific summaries, stable table formats, and more helpful error messages for CLI usage.
+The db-worker-node process currently logs only to console, but operational debugging requires a per-graph log file stored under the data directory with simple retention.
+
+## Testing Plan
+
+I will add unit tests for human output formatting functions to ensure stable, readable rendering for each command result shape.
+I will add unit tests for error formatting to ensure consistent human output for common failure cases.
+I will add an integration test that starts db-worker-node and verifies that a log file is created at <data-dir>/<graph-dir>/db-worker-node-YYYYMMDD.log.
+I will add an integration test that exercises a log-producing db-worker-node action and asserts the log file contains the expected log entries.
+I will follow @test-driven-development for all behavior changes.
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Architecture sketch
+
+The CLI outputs structured results and the formatter converts them into human-friendly text based on the command and payload.
+The db-worker-node daemon configures glogi to append to a per-graph log file under the repo-specific data directory.
+
+ASCII diagram:
+
++-----------------+     format-result     +------------------------+
+| logseq-cli      | --------------------> | human output formatter  |
+| result payloads | <-------------------- | command renderers       |
++-----------------+                       +------------------------+
+
++------------------+   glogi appender   +-------------------------------------+
+| db-worker-node   | -----------------> | <data-dir>/<graph-dir>/db-worker-node-YYYYMMDD.log |
++------------------+                    +-------------------------------------+
+
+## Implementation plan
+
+1. Use tool(update_plan) to track the full task list and include the @test-driven-development red-green-refactor steps.
+2. Read @test-driven-development guidelines and confirm the red phase will include all CLI output and log file tests first.
+3. Review existing CLI output shapes in src/main/logseq/cli/commands.cljs to catalog the current :data payloads by command.
+4. Review current formatting in src/main/logseq/cli/format.cljs and identify all human output paths that need command-specific rendering.
+5. Define a human output specification table in docs/agent-guide/005-logseq-cli-output-and-db-worker-node-log.md that maps each command to its target human output layout.
+6. Add unit test scaffolding for CLI formatting in src/test/logseq/cli/format_test.cljs (or a new namespace) using representative :status/:data payloads.
+7. Write a failing unit test for list commands to ensure human output renders a table with a header and row count.
+8. Write a failing unit test for add/remove commands to ensure human output renders a succinct success line with key identifiers.
+9. Write a failing unit test for graph management commands to ensure human output includes graph name and status text.
+10. Write a failing unit test for server commands to ensure human output includes repo, status, host, and port when available.
+11. Write a failing unit test for search and show commands to ensure human output includes result counts and stable ordering.
+12. Write a failing unit test for error formatting to ensure error codes and helpful hints are included in human output.
+13. Add a failing integration test in src/test/frontend/worker/db_worker_node_test.cljs (or a new namespace) that starts db-worker-node and asserts the log file exists at <data-dir>/<graph-dir>/db-worker-node-YYYYMMDD.log.
+14. Add a failing integration test that performs a db-worker-node action and asserts at least one log line is appended to the log file.
+15. Implement a command-aware human formatter in src/main/logseq/cli/format.cljs, using a dispatch on command or data shape.
+16. Update src/main/logseq/cli/main.cljs to pass command context into the formatter so it can choose the correct renderer.
+17. Normalize CLI result payloads in src/main/logseq/cli/commands.cljs to include explicit command identifiers where needed for formatting.
+18. Ensure human output uses consistent spacing, headers, and ordering for list output, and avoids raw EDN dumps in normal cases.
+19. Add a utility for table rendering with fixed column widths and truncation behavior in src/main/logseq/cli/format.cljs or a new helper namespace.
+20. Implement db-worker-node log file setup in src/main/frontend/worker/db_worker_node.cljs using lambdaisland.glogi appenders.
+21. Compute the log path using frontend.worker.db-worker-node-lock/repo-dir and ensure the directory exists before writing.
+22. Configure glogi to append to <data-dir>/<graph-dir>/db-worker-node-YYYYMMDD.log and define whether console logging remains enabled.
+23. Update help text in src/main/frontend/worker/db_worker_node.cljs to document the log file location and log-level flag behavior.
+24. Update docs/cli/logseq-cli.md with the new human output expectations and any new formatting options.
+25. Run unit tests in the red phase to confirm failures, then implement minimal changes to make them pass.
+26. Run bb dev:test -v 'logseq.cli.commands-test' and bb dev:test -v 'frontend.worker.db-worker-node-test' in the green phase.
+27. Run bb dev:lint-and-test after all changes to validate lint and unit tests.
+
+## Edge cases
+
+The repo name contains characters that change the pool directory name, so the log file path must use worker-util/get-pool-name consistently.
+The data directory is on a filesystem without write permissions, which should surface a clear error message and non-zero exit code.
+Multiple db-worker-node instances for different repos should not overwrite each other’s log files.
+The log file should be created even if no requests are served yet and only startup logs are emitted.
+Human output should remain stable when list results are empty or fields are missing.
+The human formatter should avoid printing large nested maps by default for search or show results.
+
+## Testing commands and expected output
+
+Run a focused unit test during the red phase.
+
+```bash
+bb dev:test -v 'logseq.cli.format-test/test-human-output-list'
+```
+
+Expected output includes a failing assertion and exits with a non-zero status code.
+
+Run the db-worker-node log integration test in the green phase.
+
+```bash
+bb dev:test -v 'frontend.worker.db-worker-node-test/test-log-file-created'
+```
+
+Expected output includes 0 failures and 0 errors.
+
+Run the full lint and unit test suite when all changes are complete.
+
+```bash
+bb dev:lint-and-test
+```
+
+Expected output includes successful linting and tests with exit code 0.
+
+## Testing Details
+
+I will validate human output formatting by asserting on complete rendered strings for representative payloads instead of inspecting internal formatting helpers.
+I will validate db-worker-node logging by checking file existence, dated filename format, and that only the most recent 7 log files remain after multiple startups.
+I will assert that a known log event is present after a startup or invoke action.
+
+## Implementation Details
+
+- Add a command-aware human output renderer that produces tables, summaries, and success lines based on command and result payloads.
+- Standardize human error output to include error codes, messages, and actionable hints when possible.
+- Ensure human output defaults to stable ordering and includes a count line for list and search commands.
+- Add a table rendering helper with column width limits and truncation rules.
+- Pass command context through CLI result objects so the formatter can select the correct renderer.
+- Configure db-worker-node glogi to append logs to <data-dir>/<graph-dir>/db-worker-node-YYYYMMDD.log.
+- Enforce log retention by keeping only the most recent 7 dated log files per graph directory.
+- Ensure the log directory exists before log initialization and keep the log file path deterministic.
+- Document log file location and new human output behavior in CLI documentation.
+- Keep JSON and EDN outputs unchanged for scripting compatibility.
+- Preserve existing exit codes and error handling semantics in the CLI.
+
+## Question
+
+Should the human output include color or ANSI styling, or should it remain plain text for maximal portability.
+Answer: Remain plain text for maximal portability.
+Should db-worker-node log to both console and file, or file-only to avoid duplicate logs in CLI output.
+Answer: File-only to avoid duplicate logs in CLI output.
+Is log rotation or size management required for db-worker-node.log, or is simple append-only acceptable.
+Answer: Use dated log filenames and keep only the most recent 7 log files.
+
+---
diff --git a/docs/agent-guide/006-logseq-cli-import-export.md b/docs/agent-guide/006-logseq-cli-import-export.md
new file mode 100644
index 0000000000..461edee5aa
--- /dev/null
+++ b/docs/agent-guide/006-logseq-cli-import-export.md
@@ -0,0 +1,83 @@
+# Logseq CLI Import/Export Plan
+
+Goal: Add logseq-cli support for import/export with EDN and SQLite formats using the existing db-worker-node server.
+
+Architecture: Extend logseq-cli command parsing and execution to invoke db-worker-node thread APIs for export and import, with minimal new APIs to handle EDN import and SQLite binary payloads over HTTP.
+
+Tech Stack: ClojureScript, babashka/cli, db-worker-node HTTP /v1/invoke, datascript, sqlite-export helpers, Node fs/path.
+
+Related: Builds on docs/agent-guide/004-logseq-cli-verb-subcommands.md and docs/agent-guide/003-db-worker-node-cli-orchestration.md.
+
+## Requirements
+
+- Import types: edn, sqlite.
+- Export types: edn, sqlite.
+- CLI must work against db-worker-node with repo binding and lock file behavior.
+- Output files must be written to user-specified paths with clear success/error messages.
+
+## Proposed CLI UX
+
+Prefer graph-scoped subcommands to keep import/export with graph management:
+
+- `logseq graph export --type edn --file <path> [--graph <graph>]`
+- `logseq graph export --type sqlite --file <path> [--graph <graph>]`
+- `logseq graph import --type edn --input <path> --graph <graph>`
+- `logseq graph import --type sqlite --input <path> --graph <graph>`
+
+Notes:
+- `graph import` only supports importing into a new graph name; it must not overwrite an existing graph.
+- `--graph` is required for import, and required unless the current graph is set in config for export.
+
+## Current Capabilities (Baseline)
+
+- db-worker-node supports `:thread-api/export-edn`, `:thread-api/export-db`, and `:thread-api/import-db`.
+- logseq-cli can invoke db-worker-node via `src/main/logseq/cli/transport.cljs` and write files with `transport/write-output`.
+- EDN import exists in the app layer (`frontend.handler.db-based.import`) but not in db-worker-node.
+- SQLite import in db-worker-node writes the sqlite file, but CLI needs a full reload step to reflect new data.
+
+## Implementation Plan
+
+1. Review existing CLI command table and action pipeline in `src/main/logseq/cli/commands.cljs` and `src/main/logseq/cli/main.cljs` to locate insertion points for new graph import/export actions.
+2. Add new CLI specs for import/export flags (type, input, output, export-type, mode) in `src/main/logseq/cli/commands.cljs`.
+3. Extend the command table with `graph import` and `graph export` entries and ensure help output includes them.
+4. Add action builders for import/export that validate repo presence, file paths, and allowed types (edn, sqlite).
+5. Add CLI helpers for reading input files and writing output files in `src/main/logseq/cli/transport.cljs` (or a new helper namespace), keeping the existing `write-output` behavior for EDN and DB files.
+6. Implement export execution:
+   - EDN: call `thread-api/export-edn` (graph-only) and write EDN file.
+   - SQLite: call a new db-worker-node export API that returns a base64 string or transit-safe binary; decode to Buffer and write `.sqlite` file.
+7. Implement import execution:
+   - EDN: read EDN file, pass data to a new db-worker-node `thread-api/import-edn` (see below), and return a summary message.
+   - SQLite: read file as Buffer, pass to a new db-worker-node `thread-api/import-sqlite` (or reuse `import-db` with a wrapper that closes/reopens the repo).
+   - Always stop and restart the db-worker-node server from the CLI around import to ensure a clean reload.
+8. Add db-worker-node thread APIs in `src/main/frontend/worker/db_core.cljs`:
+   - `:thread-api/import-edn` to convert export EDN into tx data via `logseq.db.sqlite.export/build-import` and transact with `:tx-meta` including `::sqlite-export/imported-data? true` so the pipeline rebuilds refs.
+   - `:thread-api/export-db-base64` (or similar) to return a base64 string for SQLite export over HTTP.
+   - `:thread-api/import-db-base64` (or similar) to accept base64 input, close existing sqlite connections, import db data, and reopen the repo (or invoke `:thread-api/create-or-open-db` with `:import-type :sqlite-db`).
+9. Update db-worker-node server validation (repo binding) if the new thread APIs need special argument shapes.
+10. Update CLI output formatting in `src/main/logseq/cli/format.cljs` to print concise success lines like `Exported <type> to <path>` and `Imported <type> from <path>`.
+11. Update documentation in `docs/cli/logseq-cli.md` with new commands, examples, and file format notes.
+
+## Testing Plan
+
+- Add CLI parsing tests for `graph import` and `graph export` options in `src/test/logseq/cli/commands_test.cljs` (or a new namespace).
+- Add integration tests in `src/test/logseq/cli/integration_test.cljs` to:
+  - export EDN and SQLite from a test graph and assert output files exist and are non-empty.
+  - import EDN into a new graph and verify a known page/block exists via CLI `show` or `list`.
+  - import SQLite into a new graph and verify graph metadata or page count.
+- Add db-worker-node tests in `src/test/frontend/worker/db_worker_node_test.cljs` for the new import/export thread APIs (EDN build-import path and base64 DB export/import).
+- Follow @test-driven-development: write failing tests before implementation.
+
+## Edge Cases
+
+- Large SQLite exports may exceed JSON limits if not base64/transit encoded; ensure streaming-safe or chunked base64 handling.
+- Import should fail fast if the repo is missing and `--graph` is not provided, or if input file does not exist.
+- SQLite import while the repo is open must close/reopen connections to avoid stale datascript state.
+- EDN import should validate the export shape and surface readable errors when EDN is invalid or incompatible.
+- Overwrite behavior should be explicit for SQLite imports to prevent accidental data loss.
+
+## Decisions
+
+1. `graph import` only imports into a new graph; it must not overwrite an existing graph.
+2. No `--mode` flag; both EDN and SQLite imports are replace-style imports.
+3. CLI always stops and restarts db-worker-node around imports.
+4. `graph export --type edn` is graph-only for now (no page/view/blocks).
diff --git a/docs/agent-guide/007-logseq-cli-thread-api-and-command-split.md b/docs/agent-guide/007-logseq-cli-thread-api-and-command-split.md
new file mode 100644
index 0000000000..0b3a8d77db
--- /dev/null
+++ b/docs/agent-guide/007-logseq-cli-thread-api-and-command-split.md
@@ -0,0 +1,75 @@
+# Logseq CLI Thread API Keywords And Command Split Implementation Plan
+
+Goal: Replace thread-api string usage with keywords, standardize CLI repo/graph option to --graph, and split logseq.cli.commands into per-subcommand namespaces.
+
+Architecture: Update transport and db-worker-node boundaries to accept keyword methods while still serializing over HTTP. Refactor CLI command parsing into a shared dispatcher plus per-subcommand namespaces under a new command directory. Keep existing CLI behavior and output stable while updating option naming and error hints.
+
+Tech Stack: ClojureScript, babashka.cli, promesa, Logseq db-worker-node.
+
+Related: Builds on docs/agent-guide/004-logseq-cli-verb-subcommands.md, docs/agent-guide/005-logseq-cli-output-and-db-worker-node-log.md, docs/agent-guide/006-logseq-cli-import-export.md.
+
+## Problem statement
+
+The current CLI and db-worker-node codebase mixes thread-api method strings with keyword-based APIs, which makes it easy to introduce mismatches and reduces consistency with the thread-api macro design. The logseq.cli.commands namespace has grown large and mixes parsing, validation, and execution for multiple command groups, which makes maintenance and ownership difficult.
+
+## Testing Plan
+
+I will add unit tests to ensure all CLI thread-api method invocations use keywords and still serialize correctly through transport when invoking db-worker-node. I will add unit tests for command parsing and action building to cover the new per-subcommand namespaces and ensure summaries and help still match expected output. I will update db-worker-node tests to assert keyword method handling for repo validation and allowed non-repo methods. NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Plan
+
+1. Review @prompts/review.md to align plan with review expectations.
+
+2. Enumerate all thread-api string usages in CLI, db-worker-node, and tests using `rg -n -- "\"thread-api/" src/main src/test`.
+
+3. Enumerate all --graph references in CLI code and tests using `rg -n -- "--graph" src/main src/test` and confirm there are no docs references outside CLI.
+
+4. Define a small utility in `src/main/logseq/cli/transport.cljs` to normalize thread-api method arguments to keywords for callers while serializing over HTTP as string names.
+
+5. Add tests in `src/test/logseq/cli/transport_test.cljs` that pass a keyword method to transport invoke and assert the outgoing payload uses the string name and the response handling is unchanged.
+
+6. Update all CLI calls in `src/main/logseq/cli/commands.cljs` to pass keyword thread-api names to transport invoke and to any action maps that store method identifiers.
+
+7. Update CLI tests in `src/test/logseq/cli/commands_test.cljs` and `src/test/logseq/cli/integration_test.cljs` to expect keyword thread-api methods where they assert method calls.
+
+8. Update db-worker-node internal invocation and repo validation in `src/main/frontend/worker/db_worker_node.cljs` to coerce incoming method values to keywords for comparisons and logging, while still accepting string input from JSON payloads.
+
+9. Update any db-worker-node tests in `src/test/frontend/worker/db_worker_node_test.cljs` that assert method strings to use keyword expectations and verify non-repo method handling.
+
+10. ~~Replace any --graph option references in CLI formatting and tests by updating `src/main/logseq/cli/format.cljs` and `src/test/logseq/cli/format_test.cljs` to use --repo.~~
+
+11. Search for any `:graph` option wiring in `src/main/logseq/cli/commands.cljs` and remove CLI option parsing for --graph, including any help or usage text, while preserving graph-specific subcommands like `graph create`.
+
+12. Introduce a new directory `src/main/logseq/cli/command/` and split `logseq.cli.commands` into per-subcommand namespaces such as `logseq.cli.command.graph`, `logseq.cli.command.server`, `logseq.cli.command.list`, `logseq.cli.command.add`, `logseq.cli.command.remove`, `logseq.cli.command.search`, and `logseq.cli.command.show`.
+
+13. Create a small shared namespace like `src/main/logseq/cli/command/core.cljs` for global option spec, parsing helpers, summary formatting, and shared validation utilities, ensuring no behavior changes in parsing or summaries.
+
+14. Update `src/main/logseq/cli/commands.cljs` to become a thin facade that assembles tables from per-subcommand modules, delegates parse-args and build-action to those modules, and exposes execute dispatching without changing public API.
+
+15. Update `src/main/logseq/cli/main.cljs` requires to match any namespace changes and confirm the CLI usage summary still renders the same command list.
+
+16. Update tests in `src/test/logseq/cli/commands_test.cljs` to import any moved namespaces or use the facade namespace, and ensure all help summary snapshots still pass.
+
+17. Run unit tests for CLI and db-worker-node with `bb dev:test -v 'logseq.cli.commands-test'`, `bb dev:test -v 'logseq.cli.transport-test'`, and `bb dev:test -v 'frontend.worker.db-worker-node-test'` and fix failures.
+
+18. Run the full lint and unit test suite with `bb dev:lint-and-test` after all changes are complete.
+
+## Testing Details
+
+The tests will focus on behavior by asserting that CLI invocations still produce the same actions and outputs while enforcing keyword-based thread-api methods and updated --repo hints. The db-worker-node tests will assert that repo validation and non-repo method bypass logic behave correctly when methods are provided as keywords or strings. The command split will be validated by reusing existing parse-args and summary tests to ensure no behavioral regression in user-facing help or dispatch.
+
+## Implementation Details
+
+- Normalize thread-api method values at transport and db-worker-node boundaries to accept keywords and serialize as strings over HTTP.
+- Replace all explicit "thread-api/..." literals in CLI and db-worker-node call sites with :thread-api/... keywords.
+- Preserve graph subcommands and graph naming semantics while standardizing on :graph options.
+- Move per-subcommand parsing and execution helpers into `src/main/logseq/cli/command/` namespaces and keep `logseq.cli.commands` as a facade.
+- Keep action map shapes stable to avoid downstream changes in format or execution.
+- Update tests to match keyword method expectations and new module layout.
+- Ensure public CLI output and behavior remain unchanged
+
+## Question
+
+~~Resolved: Remove --graph entirely and fail fast on any --graph usage.~~
+
+---
diff --git a/docs/agent-guide/008-logseq-cli-move-command.md b/docs/agent-guide/008-logseq-cli-move-command.md
new file mode 100644
index 0000000000..281c613800
--- /dev/null
+++ b/docs/agent-guide/008-logseq-cli-move-command.md
@@ -0,0 +1,92 @@
+# Logseq CLI Move Command Implementation Plan
+
+Goal: Add a move subcommand to logseq-cli that moves a non-page block and its children under a target block or page with positional control.
+Architecture: Extend the existing CLI command table with a new move command that resolves source and target entities via db-worker-node and invokes :thread-api/apply-outliner-ops using :move-blocks.
+Architecture: Use existing outliner move semantics for ordering while validating CLI inputs and translating --pos into outliner options.
+Tech Stack: ClojureScript, babashka.cli, db-worker-node :thread-api/apply-outliner-ops, Logseq outliner ops.
+Related: Builds on docs/agent-guide/007-logseq-cli-thread-api-and-command-split.md.
+
+## Problem statement
+
+Users need a CLI way to move a block and its subtree to a new parent or sibling position in a graph without opening the UI.
+The current CLI supports add and remove but lacks a move operation even though db-worker-node and outliner already support :move-blocks.
+The move command must align with existing CLI patterns, validate non-page sources, and support positioning under a block or page target.
+
+## Testing Plan
+
+I will add unit tests for command parsing and validation of move options, including invalid combinations and default --pos behavior.
+I will add unit tests for human output formatting of move success messages.
+I will add an integration test that creates blocks, moves a block to a target page and block, and verifies the resulting tree via show.
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Command behavior and options
+
+The move command will be a new inspect and edit verb alongside add and remove.
+The command will accept exactly one source selector and exactly one target selector.
+The command will move a single block per invocation.
+The command will allow a page target via --page-name and a block target via a block selector.
+The move position will default to first-child unless --pos is provided.
+Source selectors will be --id or --uuid, and target selectors will be --target-id or --target-uuid.
+
+| Flag | Meaning | Required | Notes |
+| --- | --- | --- | --- |
+| --id | Source block db/id | Yes | Mutually exclusive with --uuid. |
+| --uuid | Source block UUID | Yes | Mutually exclusive with --id. |
+| --target-id | Target block db/id | Yes | Mutually exclusive with --target-uuid and --page-name. |
+| --target-uuid | Target block UUID | Yes | Mutually exclusive with --target-id and --page-name. |
+| --page-name | Target page name | Yes | Only valid when target is a page. |
+| --pos | Position relative to target | No | Allowed values: first-child, last-child, sibling. |
+
+## Implementation Plan
+
+1. Read @prompts/review.md and capture any relevant review checklist items for CLI commands and db-worker-node usage.
+2. Add a new command namespace at src/main/logseq/cli/command/move.cljs with a command entry, spec, and action builder.
+3. Add option validation in src/main/logseq/cli/command/move.cljs for allowed --pos values and mutually exclusive selectors.
+4. Add source resolution logic in src/main/logseq/cli/command/move.cljs that fetches the source block by id or uuid and rejects page entities.
+5. Add target resolution logic in src/main/logseq/cli/command/move.cljs that fetches the target block or page and returns a target db/id.
+6. Map --pos to outliner options for :move-blocks and document the mapping in comments for future maintenance.
+7. Implement execute-move in src/main/logseq/cli/command/move.cljs that calls :thread-api/apply-outliner-ops with :move-blocks.
+8. Wire the new command into src/main/logseq/cli/commands.cljs for parsing, validation, action building, and execution.
+9. Update src/main/logseq/cli/command/core.cljs to include move in the Graph Inspect and Edit group in top-level summaries.
+10. Update src/main/logseq/cli/main.cljs to include move in the usage command list string.
+11. Add human output formatting for move in src/main/logseq/cli/format.cljs and include the relevant context keys.
+12. Update src/test/logseq/cli/commands_test.cljs with parse and help coverage for move and validation error cases.
+13. Update src/test/logseq/cli/format_test.cljs with a move success formatting test.
+14. Update src/test/logseq/cli/integration_test.cljs with a move workflow that asserts the moved block appears under the new target.
+15. Update docs/cli/logseq-cli.md to document the new move command, its flags, and examples.
+16. Run bb dev:lint-and-test and fix any failures.
+
+## Edge cases to cover
+
+Moving a page block should fail with a clear error message and code.
+Providing --pos sibling should return a validation error when the target is a page.
+Moving a block to itself or into its descendants should be rejected by outliner and surfaced as an error.
+Supplying both id and uuid selectors should return a validation error.
+Supplying no target selector should return a validation error.
+
+## Notes on position mapping
+
+first-child will use :sibling? false and no :bottom? so that the moved block becomes the first child of the target.
+last-child will use :bottom? true so outliner places the block after the last child of the target.
+sibling will use :sibling? true so outliner places the block immediately after the target block.
+
+## Testing Details
+
+I will add command parsing tests that assert move is present in help output and that invalid flag combinations are rejected.
+I will add a format test that ensures the human output for move references the source block and target.
+I will add an integration test that creates a page, adds blocks, moves a block under a target, and verifies the show tree includes it in the expected position.
+
+## Implementation Details
+
+- Add a new command entry in src/main/logseq/cli/command/move.cljs with a spec that includes source and target selectors plus --pos.
+- Resolve source and target entities via :thread-api/pull and reject page sources by checking page attributes.
+- Translate --pos into outliner options for :move-blocks and pass them through :thread-api/apply-outliner-ops.
+- Extend command parsing and execution switches in src/main/logseq/cli/commands.cljs to include :move-block.
+- Extend human formatting in src/main/logseq/cli/format.cljs with a concise move success line.
+- Update docs/cli/logseq-cli.md to list the new move command in the inspect and edit section and help output.
+- Follow @skills/test-driven-development for all tests and implementation work.
+
+## Question
+
+
+---
diff --git a/docs/agent-guide/009-cli-add-pos-show-tree-align.md b/docs/agent-guide/009-cli-add-pos-show-tree-align.md
new file mode 100644
index 0000000000..e822d4b36d
--- /dev/null
+++ b/docs/agent-guide/009-cli-add-pos-show-tree-align.md
@@ -0,0 +1,110 @@
+# CLI Add Pos And Show Tree Alignment Implementation Plan
+
+Goal: Add --pos support to logseq-cli add block, rename move --page-name to --target-page-name, and fix show tree alignment when db/id widths differ.
+
+Architecture: Extend the logseq-cli command layer to parse and validate add block target options and --pos, map it to outliner insert options sent over db-worker-node, and update tree rendering to use a fixed-width id column computed from the tree.
+
+Tech Stack: ClojureScript, babashka.cli, promesa, db-worker-node thread-api.
+
+Related: Builds on docs/agent-guide/008-logseq-cli-move-command.md.
+
+## Problem statement
+
+The logseq-cli add block command always inserts at the bottom, and it cannot express first-child or sibling insertion positions, and it relies on --page/--parent targets instead of explicit target ids.
+
+The move command uses --page-name for page targets, which is inconsistent with the target naming used by other move flags.
+
+The show command renders a text tree with id prefixes, but the glyph column shifts when db/id digit widths differ, making the tree hard to read.
+
+We need to add a --pos option to add block that mirrors existing move semantics and fix show tree alignment for variable id widths.
+
+## Testing Plan
+
+I will add a unit test that parses add block with --target-id/--target-uuid/--target-page-name and --pos and validates invalid pos values, ensuring it is rejected with a clear error.
+
+I will add a unit test that parses move with --target-page-name and rejects --page-name as an unknown option.
+
+I will add a unit test for show tree rendering that uses mixed-width db/id values and verifies glyph alignment is consistent.
+
+I will add an integration test that inserts two blocks with different --pos values using the new target flags and verifies the resulting order via show output or a query in db-worker-node.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Implementation Plan
+
+1. Read the existing add block command spec and execution path in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs.
+
+2. Read the existing move --pos implementation in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/move.cljs to mirror the allowed values and option mapping, and to scope the rename from --page-name to --target-page-name.
+
+3. Write a failing unit test that parses add block with --target-id/--target-uuid/--target-page-name and --pos in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs.
+
+4. Write a failing unit test for show tree alignment with mixed-width ids in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs.
+
+5. Run the CLI unit tests to confirm both tests fail for the correct reasons.
+
+6. Replace add block target options in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs with --target-id, --target-uuid, --target-page-name, and add :pos to the spec so help text includes the option.
+
+7. Add an invalid-options? helper in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs to validate allowed positions and to reject sibling positioning when the target is a page or when no target is supplied.
+
+8. Wire add-block invalid option checks into command validation in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs.
+
+9. Update build-add-block-action in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs to normalize :pos, resolve --target-* options into a single target selector, and include it in the action payload while keeping the default behavior as last-child.
+
+10. Update execute-add-block in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs to resolve the target selector and translate :pos into insert-blocks options, using the same mapping as move and keeping compatibility with db-worker-node.
+
+11. Rename move --page-name to --target-page-name in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/move.cljs and update parsing in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs.
+
+12. Update any move-related tests in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs to use --target-page-name and to assert --page-name is rejected.
+
+13. Update tree->text in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs to compute a fixed id column width from all nodes in the tree and pad id cells consistently for all rows and multiline continuations.
+
+14. Update the show tree unit test expectations in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs to reflect the new alignment behavior.
+
+15. Write a failing integration test in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs that uses db-worker-node to insert blocks with different --pos values and checks the resulting order.
+
+16. Run the specific unit tests and the new integration test to verify they pass.
+
+17. Run the full CLI test suite with bb dev:lint-and-test to ensure no regressions.
+
+## Edge cases
+
+Add --pos sibling with --target-page-name should be rejected because a page target has no sibling context.
+
+Add --pos values should be case-insensitive and trimmed, matching move semantics.
+
+Show tree rendering should keep alignment for nodes that have no db/id or use a placeholder.
+
+Multiline block titles should continue to render under the glyph column even with mixed-width ids.
+
+## Testing Details
+
+Unit tests cover add --pos parsing and show tree alignment with mixed-width ids and multiline titles to validate visible behavior rather than internal helpers.
+
+Integration tests cover db-worker-node insert ordering by creating a page and inserting blocks with first-child and last-child positions using the new target flags, then asserting order via show output or a query.
+
+Move command tests cover renaming --page-name to --target-page-name and ensure the legacy flag is rejected.
+
+## Implementation Details
+
+- Replace add block target flags with --target-id, --target-uuid, --target-page-name and add :pos to the spec in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs.
+- Mirror move position values and mapping to {:sibling? false} and {:sibling? false :bottom? true} and {:sibling? true}.
+- Keep default add behavior as last-child when --pos is omitted for backward compatibility.
+- Reject --pos sibling when the target is a page or when no target is provided.
+- Normalize and validate :pos and target selector in add command parsing to avoid leaking invalid values to db-worker-node.
+- Rename move --page-name to --target-page-name in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/move.cljs and update parsing and help output accordingly.
+- Compute max id width in tree->text by traversing root and descendants before rendering lines.
+- Build id padding from the max width and use it for both first rows and multiline continuation rows.
+- Update tests in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs to assert alignment with mixed-width ids.
+- Ensure db-worker-node invocations remain unchanged aside from the extra insert options map.
+
+## Question
+
+Should --pos default to last-child to match current add behavior, or should it default to first-child for consistency with move.
+
+Answer: Default to last-child to preserve current add behavior.
+
+Should the old --page and --parent flags be removed immediately or supported as deprecated aliases for one release.
+
+Answer: Remove immediately.
+
+---
diff --git a/docs/agent-guide/010-logseq-cli-show-linked-references.md b/docs/agent-guide/010-logseq-cli-show-linked-references.md
new file mode 100644
index 0000000000..931563c135
--- /dev/null
+++ b/docs/agent-guide/010-logseq-cli-show-linked-references.md
@@ -0,0 +1,82 @@
+# Logseq CLI Show Linked References Implementation Plan
+
+Goal: Add task status prefixes and block tag rendering to show output, replace inline `[[<uuid>]]` references with `[[<referenced block content>]]`, and include linked references for the shown block or page.
+
+Architecture: The CLI show command will fetch status data via `:logseq.property/status` with the tree and will build a display label that prefixes the status before the block content, replaces inline `[[<uuid>]]` with `[[<referenced block content>]]`, and then appends inline block tags (e.g. `#RTC #Task`) to the content display.
+Architecture: The CLI show command will also call db-worker-node thread-api/get-block-refs to fetch linked references and append them to text output in a tree form (db/id in the first column), while returning structured data in JSON and EDN output.
+Architecture: Data flow will remain CLI -> db-worker-node -> db-core with no new worker endpoints, reusing existing thread-api functions.
+
+Tech Stack: ClojureScript, promesa, logseq-cli transport, db-worker-node thread-api, Datascript.
+
+Related: Builds on docs/agent-guide/009-cli-add-pos-show-tree-align.md.
+
+## Testing Plan
+
+I will follow @test-driven-development and write failing tests before any production changes.
+I will add a unit test in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs that asserts tree->text prefixes :logseq.property/status before the block title for TODO and CANCELED blocks.
+I will add a unit test in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs that asserts tree->text appends :block/tags in `#Tag` format to the rendered block content.
+I will add a unit test in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs that asserts tree->text keeps multiline alignment when the status prefix is present.
+I will add an integration test in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs that creates a page and a referencing block, runs show with --format json, and asserts that linked references are present and include the referencing block uuid and page title.
+I will run the new unit tests with bb dev:test -v 'logseq.cli.commands-test' and the new integration test namespace with bb dev:test -v 'logseq.cli.integration-test' to confirm failures, then again to confirm passing.
+I will run bb dev:lint-and-test after implementation to ensure no regressions.
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Problem statement
+
+The current show command prints only the block title or page name without the task status, which hides task status context in CLI usage.
+The show command also does not include linked references for the shown block or page, forcing users to query references separately.
+We need to enhance the show output to include task status prefixes and linked references while keeping existing formats and db-worker-node integration stable.
+
+## Implementation Plan
+
+1. Read /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs to identify the tree-block selector, label construction, and output formatting paths.
+2. Read /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs to confirm the behavior and return shape of :thread-api/get-block-refs.
+3. Read the existing show tree tests in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs to align new expectations with current formatting rules.
+4. Add a failing unit test in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs that builds a tree with :logseq.property/status values and asserts the status prefix appears before the block title in tree->text output.
+5. Add a failing unit test in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs that covers multiline block titles with statuses and asserts continuation lines still align under the glyph column.
+6. Add a failing integration test in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs that creates a page, adds a block referencing that page, runs show for the page in JSON, and asserts the response contains linked references with block uuid and page title.
+7. Run the two new unit tests and the integration test to confirm failures for the expected reasons.
+8. Update the tree-block selector in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs to pull :logseq.property/status alongside :block/title and :block/name.
+9. Add a small helper in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs that builds the display label by prefixing :logseq.property/status followed by a space when a status is present, while falling back to :block/name or :block/uuid when :block/title is missing, and appending `#Tag` strings for :block/tags.
+10. Update tree->text in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs to use the new label helper for both root and child nodes so that status prefixes appear in all output lines.
+11. Add a linked references fetch step in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs that calls transport/invoke with :thread-api/get-block-refs using the root db/id.
+12. Normalize linked references by pulling a minimal selector for each ref block, including :db/id, :block/uuid, :block/title, :logseq.property/status, and {:block/page [:db/id :block/name :block/title :block/uuid]}, so CLI output is predictable and lightweight.
+13. Extend the show tree data structure to include :linked-references with a list of normalized blocks and a :count, and ensure this structure is returned for JSON and EDN output paths.
+14. For text output, append a Linked References section after the tree that renders each referencing block in tree form with db/id in the first column (aligned to the glyph column), include the status-prefixed label, and show a count line when references exist.
+15. Update the unit test expectations in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs to match the status-prefixed text output.
+16. Update the new integration test assertions to match the final JSON structure for linked references.
+17. Run the targeted tests again, then bb dev:lint-and-test, to verify all changes pass.
+
+## Edge cases
+
+Blocks without :logseq.property/status should render exactly as before with no extra spacing.
+Blocks with :block/tags should render tag names as `#Tag` appended after the content.
+Blocks containing inline `[[<uuid>]]` references should render those tokens replaced with `[[<referenced block content>]]`.
+Blocks with :block/title nil should still render using :block/name or :block/uuid with the status prefix applied only when a title exists.
+Linked references can be empty, in which case the Linked References section should be omitted from text output and :linked-references should contain a zero count in JSON and EDN.
+Linked reference blocks that are missing a page or title should still render using their uuid fallback.
+Linked references should render using the same tree layout rules as the main show tree, including db/id in the first column.
+Show by block id and show by page name should both resolve linked references using the root db/id.
+
+## Testing Details
+
+The unit tests exercise tree->text output formatting to ensure status prefixes appear on the first line and multiline alignment is preserved, which validates CLI-visible behavior.
+The integration test uses db-worker-node to create actual referencing blocks and verifies that show output includes linked references in the JSON response without inspecting internal worker details.
+
+## Implementation Details
+
+- Pull :logseq.property/status in the tree selector so task status is available for label rendering.
+- Build a label helper that prefixes status values without changing existing fallback logic for titles and names, replaces inline `[[<uuid>]]` tokens with `[[<referenced block content>]]`, and appends block tags (e.g. `#RTC #Task`) after the content.
+- Append a Linked References section in text output with a header, count, and tree-formatted block labels (db/id in the first column).
+- Use :thread-api/get-block-refs for reference discovery and re-pull a minimal selector for stable CLI output.
+- Return linked references in JSON and EDN outputs as {:linked-references {:count n :blocks [...]}}.
+- Keep all changes inside the CLI show command and avoid new db-worker-node endpoints.
+
+## Question
+
+Should the status prefix use the stored uppercase value (for example CANCELED) or should it be title-cased to match the example with Canceled.
+Answer: Use the stored uppercase status value (for example CANCELED).
+Should linked references be grouped by page in text output, or listed as a flat list with page labels.
+Answer: Group linked references by page in text output.
+
+---
diff --git a/docs/agent-guide/011-logseq-cli-search-optimization.md b/docs/agent-guide/011-logseq-cli-search-optimization.md
new file mode 100644
index 0000000000..81b44f36d4
--- /dev/null
+++ b/docs/agent-guide/011-logseq-cli-search-optimization.md
@@ -0,0 +1,111 @@
+# Logseq CLI Search Optimization Implementation Plan
+
+Goal: Simplify the search command arguments and ensure search covers blocks, pages, tags, and properties by default.
+
+Architecture: The CLI parses args with babashka.cli, builds a search action, and queries db-worker-node through thread-api endpoints for pages, blocks, tags, and properties.
+Architecture: The change stays in the CLI layer and relies on existing thread-api methods in db-worker-node for data access.
+
+Tech Stack: ClojureScript, babashka.cli, Datascript queries, db-worker-node thread-api.
+
+Related: Relates to docs/agent-guide/007-logseq-cli-thread-api-and-command-split.md.
+
+## Problem statement
+
+The current search command requires the --text option or positional args and joins all positional args into the search string.
+
+The current search documentation and tests are still written around the --text flag and do not describe default type behavior.
+
+We need to remove the --text option, use the first positional string as the search text, and ensure searches cover block titles, page names, tag names, and property names with --type defaulting to all.
+
+We also need to remove the --include-content option and any :block/content usage from CLI search because :block/content is no longer present in db-graph.
+
+We also need to remove the --limit option because it currently only trims output and does not reduce query work.
+
+## Testing Plan
+
+I will add unit tests for CLI parsing that assert the search text is taken from the first positional argument and that --type defaults to all when omitted.
+
+I will add integration tests for the CLI search command that use the positional search text and verify results include at least one matching item from each type when the graph contains data.
+
+I will add a formatting test that validates the missing search text hint no longer references --text.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Scope
+
+This plan updates CLI search option parsing and action building for search types.
+
+This plan removes --include-content from CLI search options and eliminates :block/content usage from CLI search code and tests.
+
+This plan updates user-facing docs that describe the search command usage.
+
+## Non-goals
+
+This plan does not change db-worker-node thread-api method signatures or introduce new server endpoints.
+
+This plan does not alter vector search or inference-worker behavior.
+
+## Expected CLI behavior
+
+| Scenario | Input | Behavior |
+| --- | --- | --- |
+| Basic search | logseq-cli search "hello" | Uses "hello" as search text and searches pages, blocks, tags, and properties. |
+| Type filter | logseq-cli search "hello" --type page | Searches only pages. |
+| Missing text | logseq-cli search | Returns missing-search-text with a hint that positional text is required. |
+| Block titles | logseq-cli search "todo" | Matches block titles only, not :block/content. |
+
+## Implementation Plan
+
+1. Read @test-driven-development and follow TDD for every behavior change in this plan.
+2. Update CLI parsing tests in `src/test/logseq/cli/commands_test.cljs` to use positional search text and verify default types are all when --type is omitted.
+3. Run `bb dev:test -v 'logseq.cli.commands-test'` and confirm the new tests fail for the expected reasons.
+4. Update integration tests in `src/test/logseq/cli/integration_test.cljs` to call search without --text and to assert results still return ok with data.
+5. Run `bb dev:test -v 'logseq.cli.integration-test'` and confirm the new tests fail for the expected reasons.
+6. Update formatting expectations in `src/test/logseq/cli/format_test.cljs` if missing-search-text hints change.
+7. Run `bb dev:test -v 'logseq.cli.format-test'` and confirm the new tests fail for the expected reasons.
+8. Remove the :text, :include-content, and :limit options from search spec in `src/main/logseq/cli/command/search.cljs` and update help text accordingly.
+9. Update `src/main/logseq/cli/commands.cljs` to require positional search text and to stop referencing :text in missing-search-text logic.
+10. Update `src/main/logseq/cli/command/search.cljs` build-action to use the first positional argument as text and ignore any additional positional args for search text.
+11. Remove :block/content references from `src/main/logseq/cli/command/search.cljs` so block searches use block title fields only.
+12. Update `src/main/logseq/cli/format.cljs` to remove the hint that references --text.
+13. Update docs in `docs/cli/logseq-cli.md`, `docs/agent-guide/004-logseq-cli-verb-subcommands.md`, and `docs/agent-guide/002-logseq-cli-subcommands.md` to remove --text, --include-content, and --limit and document the new positional argument behavior and default --type behavior.
+14. Update CLI tests in `src/test/logseq/cli/commands_test.cljs`, `src/test/logseq/cli/integration_test.cljs`, and `src/test/logseq/cli/format_test.cljs` to remove --include-content, --limit, and any :block/content expectations.
+15. Run `bb dev:lint-and-test` and confirm all linters and unit tests pass.
+
+## Edge cases and validation
+
+Multiple positional arguments should not be concatenated into a single search string unless explicitly required by design.
+
+Search text containing spaces should still work when the shell passes it as a single quoted argument.
+
+When --type is provided, only the requested type set should be searched and defaults should not override the filter.
+
+Search with --tag should continue to filter block searches and should not filter page, tag, or property results unless explicitly required.
+
+The CLI must not attempt to query :block/content because the attribute is absent in db-graph.
+
+## Testing Details
+
+The CLI command tests will assert that a positional search term maps to the action :text and that missing text errors are raised when no positional arguments exist.
+
+The integration tests will execute the CLI against a sample graph, verify the command exits with ok, and confirm search results are a vector for each type requested.
+
+The formatting tests will assert the error hint no longer suggests the deprecated --text option.
+
+The CLI tests will assert that no --include-content or --limit option exists and that searches do not rely on :block/content.
+
+## Implementation Details
+
+- Remove :text, :include-content, and :limit from the search option spec and adjust help text generation to avoid advertising those options.
+- Update missing-search-text validation to rely only on positional args.
+- Use only the first positional argument as the search text to match the new spec.
+- Confirm default search types flow through normalize-search-types when --type is absent.
+- Remove :block/content usage from query-blocks and any related logic.
+- Update docs and examples to show quoted positional search text.
+- Ensure error hints reference positional text rather than options.
+
+## Question
+
+No open questions.
+
+---
diff --git a/docs/agent-guide/012-logseq-cli-graph-storage.md b/docs/agent-guide/012-logseq-cli-graph-storage.md
new file mode 100644
index 0000000000..c044f8bc84
--- /dev/null
+++ b/docs/agent-guide/012-logseq-cli-graph-storage.md
@@ -0,0 +1,77 @@
+# Logseq CLI Graph Storage Plan
+
+## Context
+logseq-cli and db-worker-node currently store CLI-managed graphs under `~/.logseq/db-worker/` and use per-graph directories named like `.logseq-pool-<graph-name>/` (with partial encoding). This plan captures the non-functional updates requested:
+
+1) Rename `~/.logseq/db-worker/` to `~/logseq/cli-graphs/` for CLI-managed graphs.
+2) Rename per-graph directory format from `.logseq-pool-<graph-name>/` to `<graph-name>/`.
+3) Ensure graph names that are not valid directory names are encoded, and decoding is symmetric when reading/listing.
+
+## Goals
+- Move CLI graph storage to `~/logseq/cli-graphs` by default.
+- Use a clean per-graph directory name equal to the (encoded) graph name, without `.` prefix or `logseq-pool-` prefix.
+- Provide a reversible encode/decode for graph names so list/read operations reconstruct the original graph name.
+- CLI commands and outputs should hide the internal `logseq_db_` prefix; user-facing graph names strip that db prefix.
+- Maintain db-worker-node functionality (locks/logs/kv-store) with the new paths.
+
+## Non-goals
+- Changing Electron or browser-based db graph storage (`~/logseq/graphs`) or OPFS behavior.
+- Changing db schema or sqlite storage format.
+- Changing db-worker-node API semantics.
+
+## Current Behavior (Key References)
+- CLI default data dir is `~/.logseq/db-worker`: `src/main/logseq/cli/config.cljs`.
+- db-worker-node default data dir is `~/.logseq/db-worker`: `src/main/frontend/worker/db_worker_node.cljs`, `src/main/frontend/worker/db_worker_node_lock.cljs`, `src/main/frontend/worker/platform/node.cljs`.
+- Per-graph directory currently `.logseq-pool-<sanitized>`:
+  - `frontend.worker-common.util/get-pool-name` returns `logseq-pool-<sanitized>`: `src/main/frontend/worker_common/util.cljc`.
+  - `repo-dir` uses `"." + pool-name` in CLI server, db-worker-node lock, and node platform: `src/main/logseq/cli/server.cljs`, `src/main/frontend/worker/db_worker_node_lock.cljs`, `src/main/frontend/worker/platform/node.cljs`.
+- Current graph decoding in list operations reverses only `+3A+` and `++` (file-based graphs); other characters are not reversible: `src/main/logseq/cli/server.cljs`, `src/main/frontend/worker/platform/node.cljs`.
+
+## Proposed Approach
+### 1) New default data dir
+- Change default data dir for CLI and db-worker-node from `~/.logseq/db-worker` to `~/logseq/cli-graphs`.
+- Update help text and any user-facing docs mentioning the old default.
+
+### 2) New per-graph directory naming
+- Replace `.logseq-pool-<graph-name>/` with `<encoded-graph-name>/`.
+- Remove the leading dot and `logseq-pool-` prefix entirely for CLI-managed graphs.
+
+### 3) Reversible graph name encoding
+- Introduce a shared encode/decode pair for graph directory names that is bijective for all graph names.
+- The encoding must avoid path separators and other invalid characters (esp. `/`, `\`, `:` on Windows).
+- Suggested approach (reversible and simple):
+  - Encode: apply `encodeURIComponent` to the graph name, then replace `%` with a safe delimiter (e.g. `~`) to keep filenames readable and avoid `%` edge cases.
+  - Decode: reverse the delimiter replacement, then `decodeURIComponent`.
+- Provide helper functions in a shared place (e.g. `frontend.worker-common.util` or a new shared CLI/worker helper) so CLI server, db-worker-node lock, and node platform list all use the same encode/decode logic.
+
+## Implementation Steps
+1) Add encode/decode helpers
+   - Add new helpers for reversible graph name <-> directory name.
+   - Update `get-pool-name` or replace its usage for CLI/db-worker-node paths.
+   - Files: `src/main/frontend/worker_common/util.cljc`, potentially `deps/cli/src/logseq/cli/common/graph.cljs`.
+
+2) Update data dir defaults
+   - Change defaults to `~/logseq/cli-graphs` in:
+     - `src/main/logseq/cli/config.cljs`
+     - `src/main/logseq/cli/server.cljs`
+     - `src/main/frontend/worker/db_worker_node_lock.cljs`
+     - `src/main/frontend/worker/db_worker_node.cljs` (help text)
+     - `src/main/frontend/worker/platform/node.cljs`
+   - Update any CLI docs/tests that reference `db-worker` as default.
+
+3) Update repo-dir/path derivation
+   - Replace `"." + pool-name` usage with new `<encoded-graph-name>` directory naming.
+   - Update list-graphs and list-servers to decode from new directory names.
+   - Files: `src/main/logseq/cli/server.cljs`, `src/main/frontend/worker/db_worker_node_lock.cljs`, `src/main/frontend/worker/platform/node.cljs`.
+
+4) Tests & verification
+   - Update CLI integration tests that construct temp dirs named `db-worker*` to match new defaults or explicitly pass `--data-dir`.
+   - Update db-worker-node tests to use new naming and to validate encode/decode.
+   - Ensure `bb dev:lint-and-test` passes.
+
+## Open Questions
+- The new encoding is CLI and db-worker-node only (no Electron changes).
+
+## Rollout Notes
+- This is a filesystem layout change. Include release notes and ensure users can override via `--data-dir`.
+- Provide a one-time warning if old layout is detected and not migrated.
diff --git a/docs/agent-guide/013-logseq-cli-datascript-query.md b/docs/agent-guide/013-logseq-cli-datascript-query.md
new file mode 100644
index 0000000000..9fb2903dc3
--- /dev/null
+++ b/docs/agent-guide/013-logseq-cli-datascript-query.md
@@ -0,0 +1,157 @@
+# Logseq CLI Datascript Query Implementation Plan
+
+Goal: Add a logseq-cli query subcommand that runs a Datascript query via db-worker-node and returns the raw datascript-query result shape.
+Architecture: The CLI will parse a query form from arguments, call db-worker-node using the existing /v1/invoke transport with :thread-api/q, and return whatever datascript-query returns without normalization.
+Architecture: No new db-worker-node HTTP endpoints are required because :thread-api/q already exists in the worker thread API.
+Tech Stack: ClojureScript, babashka.cli, Datascript, db-worker-node HTTP transport.
+Related: Relates to docs/agent-guide/012-logseq-cli-graph-storage.md.
+
+## Problem statement
+
+The current logseq-cli does not expose a query subcommand for running Datascript queries against a graph.
+Users need a CLI command that executes a Datascript query and returns the same result shape as datascript-query for scripting and downstream tooling.
+The solution should follow the existing logseq-cli and db-worker-node invocation patterns so it works with the current daemon and transport.
+
+## Testing Plan
+
+I will add an integration test that creates a graph, inserts blocks, runs the new query subcommand, and asserts that the returned IDs match the expected block IDs.
+I will add a unit test that validates query argument parsing, including invalid EDN, missing query text, and optional inputs parsing.
+I will add a unit test that verifies the query command returns the same shape as datascript-query without transformation.
+I will follow @test-driven-development and write the failing tests before implementing behavior.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Plan
+
+Create a new command module at src/main/logseq/cli/command/query.cljs that defines the query command spec and action builder.
+Use --query for the Datascript query form and --inputs for the optional EDN inputs vector, and parse them with cljs.reader/read-string or logseq.common.util/safe-read-string with error handling.
+Return a structured action map that includes :type :query, :repo, :query, and :inputs to keep execution isolated from parsing.
+Register the new command in src/main/logseq/cli/commands.cljs and include it in the command table so help output includes query.
+Update src/main/logseq/cli/main.cljs usage text to include query in the command list.
+Implement execution in src/main/logseq/cli/command/query.cljs using logseq.cli.transport/invoke with :thread-api/q and args [repo [query & inputs]].
+Return the raw Datascript result as-is, matching datascript-query output across human, json, and edn formats.
+Add formatting in src/main/logseq/cli/format.cljs for :query to render the raw result in human output and pass-through for json or edn output.
+Add command-level validation in src/main/logseq/cli/commands.cljs to return a missing-query error when no query is supplied.
+Update src/test/logseq/cli/commands_test.cljs to expect query in help output and to validate parse errors for missing query or invalid input.
+Add a CLI integration test in src/test/logseq/cli/integration_test.cljs that uses run-cli to execute query and verifies IDs in JSON output.
+Confirm that no db-worker-node changes are required by verifying that :thread-api/q continues to accept the same argument shape in src/main/frontend/worker/db_core.cljs.
+
+## Edge cases
+
+A query string that cannot be read as EDN should return a clear invalid-options error and a non-zero exit code.
+A query that returns no results should return an empty result with a successful status.
+Queries with :in parameters should work when --inputs supplies the matching values in order.
+
+## Testing Details
+
+The integration test will create a graph, add known blocks, run a query that finds those blocks, and verify that the output matches the datascript-query result shape.
+The unit tests will assert that parsing rejects invalid EDN for --inputs, that a missing query produces a :missing-query error, and that query execution returns raw results unchanged.
+
+## Implementation Details
+
+- Add a new command module at src/main/logseq/cli/command/query.cljs.
+- Add command entries in src/main/logseq/cli/commands.cljs.
+- Add output formatting in src/main/logseq/cli/format.cljs.
+- Update usage text in src/main/logseq/cli/main.cljs.
+- Use transport/invoke with :thread-api/q and [repo [query & inputs]].
+- Return datascript-query results without transformation.
+- Keep all argument parsing and validation inside query command module using --query and --inputs.
+- Keep db-worker-node changes to zero unless a new worker API is required.
+- Add `custom-queries` to cli.edn for storing pre-defined Datascript queries that the CLI can list and run by name.
+- Add built-in queries that appear in the query list alongside custom queries.
+- Optional inputs should support default values in cli.edn, and built-in queries should ship with reasonable defaults for their optional inputs (required inputs can omit defaults).
+  - `block-search` (search-title)
+    ```
+    [:find [?e ...]
+           :in $ ?search-title
+           :where
+           [?e :block/title ?title]
+           [(clojure.string/lower-case ?title) ?title-lower-case]
+           [(clojure.string/include? ?title-lower-case ?search-title)]]
+    ```
+  - `task-search` (search-status, ?search-title, ?recent-days)
+    ```
+    ;; Modify this query so search-title and recent-days are optional parameters.
+    ;; ?now-ms is injected by the CLI so users don't need to pass it (and should be hidden in query list output).
+    ;; Example: logseq query --name task-search --inputs '["doing"]'
+    [:find [?e ...]
+           :in $ ?search-status ?search-title ?recent-days ?now-ms
+           :where
+           [?e :block/title ?title]
+           [?e :logseq.property/status ?s]
+           [?s :db/ident ?status-ident]
+           [(= ?status-ident ?search-status)]
+           [(clojure.string/lower-case ?title) ?title-lower-case]
+           (or-join [?search-title ?title-lower-case]
+                    [(nil? ?search-title)]
+                    [(clojure.string/blank? ?search-title)]
+                    (and [(clojure.string/lower-case ?search-title) ?search-title-lower-case]
+                         [(clojure.string/include? ?title-lower-case ?search-title-lower-case)]))
+           [(get-else $ ?e :block/updated-at 0) ?updated-at]
+           (or
+            [(nil? ?recent-days)]
+            (and [(number? ?recent-days)]
+                 [(<= ?recent-days 0)])
+            (and [(number? ?recent-days)]
+                 [(>= ?updated-at (- ?now-ms (* ?recent-days 86400000)))]) )]
+    ```
+
+## cli.edn query shape
+
+Represent queries as a map keyed by query name. Keep the query form as EDN data (not a string) so it can be read directly. Optional fields like `:doc` and `:inputs` are included to help with listing and UX. `:inputs` should allow optional inputs to declare default values that are used when the CLI caller omits them. Internal inputs like `?now-ms` should be hidden from `query list` output.
+
+Suggested `:inputs` shapes:
+- `["search-status" "?search-title" "?recent-days"]` (legacy string-only form)
+- `[{:name "search-status"} {:name "?search-title" :default nil} {:name "?recent-days" :default nil}]` (explicit defaults)
+
+Example:
+```
+{:custom-queries
+ {"block-search"
+  {:doc "Find blocks by title substring (case-insensitive)."
+   :inputs ["search-title"]
+   :query [:find [?e ...]
+           :in $ ?search-title
+           :where
+           [?e :block/title ?title]
+           [(clojure.string/lower-case ?title) ?title-lower-case]
+           [(clojure.string/include? ?title-lower-case ?search-title)]]}
+
+  "task-search"
+  {:doc "Find tasks by status, optional title substring, optional recent-days."
+   :inputs [{:name "search-status"}
+            {:name "?search-title" :default nil}
+            {:name "?recent-days" :default nil}
+            ;; ?now-ms is internal; CLI fills it with current ms and query list should hide it.
+            {:name "?now-ms" :default :now-ms}]
+   :query [:find [?e ...]
+           :in $ ?search-status ?search-title ?recent-days ?now-ms
+           :where
+           [?e :block/title ?title]
+           [?e :logseq.property/status ?s]
+           [?s :db/ident ?status-ident]
+           [(= ?status-ident ?search-status)]
+           [(clojure.string/lower-case ?title) ?title-lower-case]
+           (or-join [?search-title ?title-lower-case]
+                    [(nil? ?search-title)]
+                    [(clojure.string/blank? ?search-title)]
+                    (and [(clojure.string/lower-case ?search-title) ?search-title-lower-case]
+                         [(clojure.string/include? ?title-lower-case ?search-title-lower-case)]))
+           [(get-else $ ?e :block/updated-at 0) ?updated-at]
+           (or
+            [(nil? ?recent-days)]
+            (and [(number? ?recent-days)]
+                 [(<= ?recent-days 0)])
+            (and [(number? ?recent-days)]
+                 [(>= ?updated-at (- ?now-ms (* ?recent-days 86400000)))]) )]}}}
+```
+
+Notes:
+- Built-in queries live in code but should be merged into the same map shape when listing or resolving by name.
+- `:inputs` is optional metadata for CLI help. It does not affect execution.
+## Question
+
+Use --query and --inputs options for the query subcommand.
+Output should mirror datascript-query for scripting stability.
+
+---
diff --git a/docs/agent-guide/014-logseq-cli-show-multi-id.md b/docs/agent-guide/014-logseq-cli-show-multi-id.md
new file mode 100644
index 0000000000..7b0587a855
--- /dev/null
+++ b/docs/agent-guide/014-logseq-cli-show-multi-id.md
@@ -0,0 +1,71 @@
+# Logseq CLI Show Multi-ID Implementation Plan
+
+Goal: Extend the logseq-cli show command so `--id` accepts one or more block ids, and when passed as `[<id1> <id2> ...]`, it displays all blocks separated by a clear delimiter.
+Architecture: Keep existing CLI parsing and db-worker-node transport, but allow `--id` to accept an EDN vector of ids; execute one fetch per id or a single multi-id fetch if supported by the worker thread API.
+Tech Stack: ClojureScript, babashka.cli, db-worker-node HTTP transport, Logseq block formatting.
+Related: Builds on existing show command behavior and db-worker-node thread API usage.
+
+## Problem statement
+
+The current `logseq show --id <id>` only supports a single block id, which makes it cumbersome to inspect multiple blocks from scripts.
+We need `--id` to accept `[<id1> <id2> ...]` and print each corresponding block, separated by a reasonable visual delimiter.
+This should align with existing logseq-cli and db-worker-node patterns and preserve existing single-id behavior.
+This also enables a pipeline workflow such as: `logseq query --name task-search --inputs '["todo"]' | xargs logseq show -id`.
+
+## Note on removing `search`
+
+Remove the `search` subcommand. No migration or compatibility work is required.
+
+## Note on `logseq query` output
+
+`logseq query` output handling:
+1. Validate it is valid EDN.
+2. Replace all spaces with commas.
+
+## Note on `logseq query task-search` inputs
+
+The first `task-search` input `status` should be a string like `"todo"` or `"doing"`, not `:logseq.property/status.todo`.
+
+## Testing Plan
+
+I will add unit tests for show argument parsing to accept a vector of ids and to reject invalid EDN in `--id`.
+I will add an integration test that runs `logseq show --id '["id1" "id2"]'` and asserts that both blocks are present in output with the delimiter between them.
+I will keep existing single-id tests intact and ensure no regressions in JSON/EDN output modes.
+I will follow @test-driven-development and write the failing tests before implementing behavior.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Plan
+
+Locate the show command definition and parsing in `src/main/logseq/cli/command/show.cljs` (or equivalent) and identify current `--id` parsing behavior.
+Update argument parsing so `--id` accepts either a single id (string) or an EDN vector of ids; parse via `cljs.reader/read-string` or `logseq.common.util/safe-read-string` with clear errors on invalid EDN.
+Normalize the parsed value into a vector of ids, preserving the current single-id behavior by wrapping the string in a vector.
+Update the show execution path to iterate through ids and fetch each block via existing db-worker-node transport; if a batch API exists, prefer it but keep compatibility with current API.
+Add output formatting logic to insert a delimiter between each block in human output (for example `\n-----\n` or `\n====\n`), and keep JSON/EDN output structured as a vector of blocks instead of concatenated text.
+Update command help/usage in `src/main/logseq/cli/main.cljs` and `src/main/logseq/cli/commands.cljs` to document vector form, including an example.
+Add unit tests in `src/test/logseq/cli/commands_test.cljs` or a show-specific test file to validate parsing and error cases.
+Add an integration test in `src/test/logseq/cli/integration_test.cljs` to verify multi-id output with delimiter and correct block ordering.
+Confirm db-worker-node thread API endpoints used by show (likely in `src/main/frontend/worker/`) do not need changes; if they do, add a minimal batch fetch method and corresponding tests.
+
+## Edge cases
+
+`--id` contains invalid EDN (e.g., `[` without closing bracket) should return a clear invalid-options error and non-zero exit.
+Mixed types in the id vector (e.g., numbers, maps) should either coerce to strings or be rejected with a clear error; prefer rejection to avoid surprising behavior.
+Missing blocks (id not found) should return a clear message per block while still printing other valid blocks.
+Output delimiter should not appear before the first block or after the last block.
+
+## Testing Details
+
+Unit tests should cover parsing of a single id, a vector of ids, and invalid EDN.
+Integration tests should create two blocks, fetch them by ids, and verify both are present in order with the delimiter separating them in human output.
+JSON/EDN outputs should be a vector of block structures matching current single-id output shape.
+
+## Implementation Details
+
+- Update `--id` parsing to accept EDN vectors of ids while preserving single-id strings.
+- Normalize `id` input to `ids` vector for downstream handling.
+- Loop fetches through existing db-worker-node transport, or add a batch fetch endpoint only if necessary.
+- Insert a delimiter between blocks in human output; keep machine-readable outputs as structured vectors.
+- Update help text and tests accordingly.
+
+---
diff --git a/docs/agent-guide/015-logseq-cli-db-worker-node-housekeeping.md b/docs/agent-guide/015-logseq-cli-db-worker-node-housekeeping.md
new file mode 100644
index 0000000000..8efa52b043
--- /dev/null
+++ b/docs/agent-guide/015-logseq-cli-db-worker-node-housekeeping.md
@@ -0,0 +1,64 @@
+# Logseq CLI and db-worker-node Housekeeping Implementation Plan
+
+Goal: Remove the --retries and --auth-token options from logseq-cli and db-worker-node, and add a --version option that prints build time and commit.
+
+Architecture: Keep option parsing centralized in logseq.cli.command.core and frontend.worker.db-worker-node, and move build metadata into a dedicated ClojureScript namespace injected via shadow-cljs closure defines.
+Architecture: Ensure logseq-cli prints version info without needing a running db-worker-node, and db-worker-node no longer gates endpoints on auth tokens.
+
+Tech Stack: ClojureScript, babashka.cli, shadow-cljs, Node.js.
+
+Related: Relates to docs/agent-guide/001-logseq-cli.md.
+Related: Relates to docs/agent-guide/002-logseq-cli-subcommands.md.
+Related: Relates to docs/agent-guide/003-db-worker-node-cli-orchestration.md.
+
+## Problem statement
+
+The current logseq-cli and db-worker-node expose --retries and --auth-token options that are no longer desired, and the CLI lacks a version command that prints build time and commit.
+The cleanup should remove these options without compatibility shims and introduce a clear version output backed by build metadata.
+
+## Testing Plan
+
+I will add a unit test for logseq-cli parsing that asserts --version short-circuits command execution and prints build metadata fields.
+I will update the config and transport tests to remove retries and auth token expectations while still validating timeout behavior.
+I will add a db-worker-node CLI test that verifies the help output no longer mentions --auth-token and that args parsing ignores the removed flag.
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Plan
+
+1. Review current option definitions and call sites for retries and auth-token in src/main/logseq/cli/command/core.cljs, src/main/logseq/cli/config.cljs, src/main/logseq/cli/transport.cljs, and src/main/frontend/worker/db_worker_node.cljs.
+2. Update src/main/logseq/cli/command/core.cljs to remove :auth-token and :retries from the global spec and option summary output.
+3. Update src/main/logseq/cli/config.cljs to remove env parsing and defaults for auth-token and retries, and to stop persisting those keys in config files.
+4. Update src/main/logseq/cli/transport.cljs to drop auth header handling and retry loops, and adjust invoke to pass only method, url, body, and timeout values.
+5. Update any logseq-cli action builders or server helpers that still read :auth-token or :retries from config, and delete those plumbing paths if present.
+6. Update src/main/frontend/worker/db_worker_node.cljs to remove --auth-token parsing, remove authorization checks on endpoints, and delete auth-token from daemon options and help output.
+7. Add a new namespace such as src/main/logseq/cli/version.cljs that defines BUILD_TIME and REVISION via goog-define with safe defaults, and exposes a formatter for the CLI.
+8. Add a global --version flag in logseq-cli by extending the global spec and by adding a short-circuit path in src/main/logseq/cli/main.cljs or src/main/logseq/cli/commands.cljs that prints build time and commit without requiring a command.
+9. Add closure defines for the CLI build in shadow-cljs.edn under :logseq-cli and for the node test build under :test so tests can assert deterministic build metadata values.
+10. Update build entry points that compile logseq-cli, such as package.json scripts or any CI workflow that calls clojure -M:cljs compile logseq-cli, to export LOGSEQ_BUILD_TIME and LOGSEQ_REVISION for the defines.
+11. Update docs/cli/logseq-cli.md to remove auth-token and retries from the configuration list and to document --version output format with build time and commit.
+12. Scan for remaining user-facing mentions of --auth-token or --retries in docs and README files, and update or remove them where appropriate.
+13. Run unit tests for CLI and db-worker-node using bb dev:test for the modified namespaces, and run bb dev:lint-and-test if time allows.
+14. Follow @prompts/review.md and @skills/test-driven-development throughout implementation and verification.
+
+## Testing Details
+
+The CLI tests will assert that --version returns a non-empty output containing build time and commit keys and that it exits successfully without requiring a subcommand.
+The transport tests will still cover timeout behavior but will no longer assert retries behavior or auth header inclusion.
+The db-worker-node tests will validate updated help output and ensure that argument parsing still recognizes required flags after removing --auth-token.
+
+## Implementation Details
+
+- Remove :auth-token and :retries from global CLI option specs and summaries in src/main/logseq/cli/command/core.cljs.
+- Remove env parsing and defaults for auth-token and retries in src/main/logseq/cli/config.cljs.
+- Simplify HTTP request and invoke logic in src/main/logseq/cli/transport.cljs to remove retries and auth headers.
+- Remove auth-token CLI parsing and authorization gating in src/main/frontend/worker/db_worker_node.cljs.
+- Add build metadata defines in a new CLI version namespace and wire --version output through logseq-cli entrypoints.
+- Add closure defines for LOGSEQ_BUILD_TIME and LOGSEQ_REVISION in shadow-cljs.edn for :logseq-cli and :test builds.
+- Update scripts or CI to populate LOGSEQ_BUILD_TIME and LOGSEQ_REVISION at compile time.
+- Update docs/cli/logseq-cli.md and any other user-facing documentation to reflect the new option set.
+
+## Question
+
+Answer: remove all auth support entirely, including env vars and header checks.
+
+---
diff --git a/docs/agent-guide/016-recent-updated-query.md b/docs/agent-guide/016-recent-updated-query.md
new file mode 100644
index 0000000000..427625ae51
--- /dev/null
+++ b/docs/agent-guide/016-recent-updated-query.md
@@ -0,0 +1,89 @@
+# Recent Updated Query Implementation Plan
+
+Goal: Add a built-in CLI query named recent-updated that filters entities updated within a configurable recent-days window.
+
+Architecture: The logseq CLI will expose a new built-in query spec in the query command module and pass inputs to db-worker-node via thread-api/q with no db-worker-node changes.
+The query will rely on :block/updated-at and a now-ms input to compute a rolling cutoff in milliseconds.
+
+Tech Stack: ClojureScript, Datascript queries, logseq CLI, db-worker-node thread-api.
+
+Related: Builds on 015-logseq-cli-db-worker-node-housekeeping.md.
+
+## Problem statement
+
+Users need a built-in CLI query to list recently updated content without crafting ad hoc datalog each time.
+The new recent-updated query should accept a recent-days parameter and integrate with existing logseq CLI query listing and execution paths.
+The implementation must align with db-worker-node query execution and hide internal inputs from query list output.
+
+## Testing Plan
+
+I will add an integration test that creates a temporary graph, adds blocks, and runs the recent-updated query with a small recent-days window, asserting only recently updated entities are returned.
+I will add a second integration test case in the same test to cover recent-days values of nil and non-positive numbers, confirming the CLI returns a clear invalid input error.
+I will add a CLI query list assertion that recent-updated appears with the correct input spec and defaults, excluding the internal now-ms input from list output.
+I will add a CLI show -id test to ensure duplicate trees are filtered when ids include parent/child relationships.
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Implementation Plan
+
+1. Write the failing integration test for recent-updated in `src/test/logseq/cli/integration_test.cljs` that uses `run-cli` to create a graph, insert blocks, and query by name, asserting the result is a vector of db/id values.
+2. Write the failing assertion that `query list` returns a recent-updated entry with an inputs vector that only shows recent-days.
+3. Run the single integration test to confirm failures are due to missing built-in query behavior.
+4. Add a new built-in query spec entry in `src/main/logseq/cli/command/query.cljs` with name "recent-updated" and inputs [{:name "?recent-days" :default 0} {:name "?now-ms" :default :now-ms}].
+5. Define the query to find entities that have :block/updated-at and apply an or-join to bypass filtering when recent-days is nil or <= 0.
+6. Ensure the query result shape matches other built-ins and returns a vector of entity ids.
+7. Run the integration test again and confirm it now passes.
+8. Refactor the built-in query spec and test setup for clarity if necessary while keeping behavior unchanged.
+9. Run the CLI integration test suite or the focused test case to ensure no regressions.
+10. Update the show -id output path to drop contained trees when multiple ids overlap.
+
+## Edge Cases and Considerations
+
+- recent-days must be greater than 0, and nil or non-positive values should be rejected with a clear CLI error.
+- Blocks without :block/updated-at should be excluded consistently and not cause query errors.
+- The query should return both pages and blocks.
+- The query should exclude built-in entities by default.
+
+## Testing Details
+
+The tests will exercise the CLI path end to end by invoking db-worker-node and asserting the query results contain only the expected entities based on updated-at timestamps.
+The tests will validate both the query list metadata and the data returned from the query invocation.
+
+## Implementation Details
+
+- Add a new entry to built-in-query-specs in `src/main/logseq/cli/command/query.cljs`.
+- Use :block/updated-at and a computed cutoff (now-ms minus recent-days in milliseconds) inside the datalog query, and enforce recent-days > 0 in CLI input validation.
+- Keep the inputs list consistent with existing built-in queries and rely on hide-internal-inputs to remove ?now-ms from list output.
+- Reuse the same optional input handling logic as task-search for recent-days defaults.
+- Ensure the query name is normalized and discoverable via `logseq query list`.
+- Return a vector of db/id values with no ordering guarantees, matching task-search behavior.
+- Keep db-worker-node unchanged since it already supports arbitrary datascript queries via thread-api/q.
+
+## Question
+
+recent-updated must return both pages and blocks, and exclude built-in entities by default.
+recent-days must be greater than 0, and nil or non-positive values should be treated as invalid input.
+Results must be returned as an unordered vector of db/id values, and users should use logseq show to view content and apply sorting.
+
+## Show -id duplicate filtering note
+
+When `logseq show -id` is given multiple ids, the output can include duplicate trees if some ids are children of others.
+Filter out smaller (contained) trees from the result, so only the largest parent tree is kept.
+
+Example:
+
+```text
+logseq show -id [7830,7831,7832,7833]
+7830 Jan 23rd, 2026 #Journal
+7831 ├── asdfasdfasdf
+7832 │   └── yyyy
+7833 └── [[xxxx]] yyy
+================================================================
+7831 asdfasdfasdf
+7832 └── yyyy
+================================================================
+7832 yyyy
+================================================================
+7833 [[xxxx]] yyy
+```
+
+---
diff --git a/docs/agent-guide/017-logseq-cli-db-worker-node-housekeeping-2.md b/docs/agent-guide/017-logseq-cli-db-worker-node-housekeeping-2.md
new file mode 100644
index 0000000000..0763fe5b8b
--- /dev/null
+++ b/docs/agent-guide/017-logseq-cli-db-worker-node-housekeeping-2.md
@@ -0,0 +1,97 @@
+# Logseq CLI Housekeeping 2 Implementation Plan
+
+Goal: Simplify CLI options for show, move, and remove while keeping db-worker-node behavior unchanged.
+
+Architecture: The changes are limited to CLI option parsing, action building, and output formatting in the CLI layer.
+The db-worker-node API calls remain the same, but we will verify expected input shapes for delete and move operations.
+We will centralize shared id parsing so show and remove stay consistent.
+
+Tech Stack: ClojureScript, babashka.cli, promesa, Logseq CLI, db-worker-node thread-api.
+
+Related: Builds on docs/agent-guide/015-logseq-cli-db-worker-node-housekeeping.md and relates to docs/agent-guide/014-logseq-cli-show-multi-id.md.
+
+## Testing Plan
+
+I will follow @test-driven-development by writing failing tests for each new CLI behavior before changing implementation.
+I will add unit tests in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs for parsing and validation of the new remove options and renamed flags.
+I will add unit tests for show option parsing to accept --page and reject --page-name and --format, while preserving global --output handling.
+I will add unit tests for move option parsing to accept --target-page and reject --target-page-name.
+I will add unit tests for remove parsing to accept --id, --uuid, and --page, and to reject multiple selectors or missing target.
+I will add unit tests for remove parsing to accept multi-id vectors and to reject invalid or empty vectors.
+I will run the CLI test namespace and confirm the new tests fail before any implementation changes.
+I will rerun the CLI tests after each behavioral change to confirm they pass.
+
+Command to run tests is shown below.
+
+```bash
+bb dev:test -v 'logseq.cli.commands-test'
+```
+
+Expected test output is described below.
+
+The output should include zero failures and zero errors for logseq.cli.commands-test.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Problem statement
+
+The CLI currently exposes overlapping option names and per-command format flags that conflict with the global output option.
+The remove command is split into remove block and remove page, which makes scripting awkward and inconsistent with show and move selectors.
+The move and show commands use page-name flags that should be renamed for clarity and consistency across commands.
+We need a small, coordinated change that updates CLI parsing, action building, and documentation without changing db-worker-node APIs.
+
+## Plan
+
+1. Review current CLI option specs and validation in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs, /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/remove.cljs, and /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/move.cljs to confirm existing behavior and data shapes.
+2. Review db-worker-node call sites for delete and move operations by searching for :delete-blocks and :delete-page usages to confirm expected argument shapes in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/remove.cljs and related call sites.
+3. Add failing parsing and validation tests for the unified remove command and renamed flags in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs.
+4. Add failing tests that assert legacy flags and subcommands are rejected in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs.
+5. Run the CLI test namespace and record the failing cases using the test command in the testing plan.
+6. Extract the show id parsing logic into a shared helper in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/id.cljs or a similar shared namespace, and update /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs to use it.
+7. Update /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/remove.cljs to define a single remove spec with --id, --uuid, and --page, and to build actions based on which selector is present.
+8. Update remove execution to support single and multiple id deletion while preserving page deletion behavior, and ensure returned data matches existing format expectations.
+9. Update /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs to rename --page-name to --page and remove the --format option and related validation.
+10. Update show execution to use the resolved output format from config instead of a command-specific flag, while preserving human-readable output for the default format.
+11. Update /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/move.cljs to rename --target-page-name to --target-page and adjust validation and target resolution accordingly.
+12. Update /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs to reflect the new remove command, show selector, and move target flag in validation, action building, and help routing.
+13. Update /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs if the new remove action type changes the command name used for human formatting.
+14. Update CLI usage text in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs to remove the remove block and remove page references.
+15. Update CLI documentation and examples in /Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md to use --page, --target-page, and the unified remove command without --format.
+16. Rerun the CLI test namespace and confirm all tests pass.
+17. Run bb dev:lint-and-test if time permits and confirm there are no regressions in other CLI tests.
+18. Review the changes against @prompts/review.md and ensure the updated flags are reflected everywhere in docs and tests.
+
+## Edge cases
+
+Removing blocks with a vector of ids that contains non-integers should produce a clear invalid options error.
+Removing blocks with an empty id vector should produce a clear invalid options error.
+Removing with both --id and --uuid should fail validation with a single-selector error.
+Removing with both --page and a block selector should fail validation with a single-selector error.
+Showing with --page should still reject invalid level values and missing targets.
+Showing with --output json or edn should return structured data rather than human text for both single and multi-id cases.
+Moving with --target-page should still reject --pos sibling.
+Legacy flags like --page-name, --target-page-name, and show --format should be rejected by the parser with invalid-options errors.
+
+## Testing Details
+
+I will focus tests on CLI behavior by asserting parse-args results, invalid option errors, and build-action normalization for ids and selectors.
+I will avoid mock-only tests and instead assert actual validation behavior and action shapes that drive CLI execution.
+
+## Implementation Details
+
+- Consolidate remove command parsing around a single spec and selector validation.
+- Share id parsing between show and remove to keep behavior identical.
+- Keep db-worker-node API calls unchanged and only adjust CLI argument shapes.
+- Use config output-format in show execution to decide between human text and structured data.
+- Remove show-specific format validation and option from the CLI help output.
+- Rename show and move page flags and update all associated validation logic.
+- Update CLI documentation and examples to match the new flags and remove subcommands.
+- Update CLI help routing so logseq remove behaves like a command, not a group.
+
+## Decisions
+
+- Remove `--page-name` and `--target-page-name` entirely (no aliases or warnings).
+- For remove with multiple ids, continue with best-effort deletion (do not fail on the first missing id).
+- For remove ids, allow only the show-style vector and single value formats (no repeated `--id` flags).
+
+---
diff --git a/docs/agent-guide/018-logseq-cli-add-tags-builtin-properties.md b/docs/agent-guide/018-logseq-cli-add-tags-builtin-properties.md
new file mode 100644
index 0000000000..f9158c0b4b
--- /dev/null
+++ b/docs/agent-guide/018-logseq-cli-add-tags-builtin-properties.md
@@ -0,0 +1,199 @@
+# Logseq CLI Add Tag And Built-in Property Support Implementation Plan
+
+Goal: Extend logseq-cli add block and add page to accept tags and built-in properties with correct type handling.
+
+Architecture: Parse tag and property options in the CLI, resolve them via db-worker-node, and apply them using existing outliner ops.
+Architecture: Use built-in property definitions and property type rules to coerce values before invoking :batch-set-property or :create-page.
+
+Tech Stack: ClojureScript, babashka.cli, Datascript, db-worker-node, outliner ops.
+
+Related: Relates to docs/agent-guide/015-logseq-cli-db-worker-node-housekeeping.md.
+
+## Problem statement
+
+Logseq CLI currently supports add block and add page with content and basic status support.
+Users need to set tags and built-in properties at creation time from CLI, but built-in properties have multiple value types and validation rules.
+The implementation must align with the built-in property definitions and property type system so that values are stored and validated correctly in db-worker-node.
+
+## Testing Plan
+
+I will add unit tests that parse new CLI options for tags and properties and validate error cases for invalid property names and invalid type values.
+I will add integration tests that run add block and add page with tags and built-in properties and assert the resulting data in the graph.
+I will add tests that cover ref-type properties like :logseq.property/deadline and :block/tags to ensure resolution behavior is correct.
+I will add tests that cover scalar properties like :logseq.property/publishing-public? and :logseq.property/heading with proper type coercion.
+I will verify that invalid types cause CLI errors before any outliner ops are sent.
+I will add tests that missing tags in --add-tag fail with a clear error and do not create tags.
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current behavior summary
+
+Add block and add page live in src/main/logseq/cli/command/add.cljs.
+Add block supports content, blocks, blocks-file, target selection, position, and status, and it sets status via :batch-set-property.
+Add page uses :create-page with an empty options map and does not apply tags or properties.
+Built-in properties and their schema are defined in deps/db/src/logseq/db/frontend/property.cljs and type rules in deps/db/src/logseq/db/frontend/property/type.cljs.
+
+## Requirements
+
+Add block supports setting tags on all inserted blocks.
+Add page supports setting tags on the created page.
+Add block supports setting built-in properties with correct type coercion.
+Add page supports setting built-in properties with correct type coercion.
+Add block and add page accept tag and property references by id, :block/title, or :db/ident for --tags and --properties.
+CLI rejects non built-in properties for these new options.
+CLI rejects built-in properties that are not public and provides a clear error message.
+CLI rejects adding non public tags to blocks.
+CLI rejects combining --blocks or --blocks-file with --add-property, --remove-property, --add-tag, or --remove-tag.
+
+## Non goals
+
+Do not change db-worker-node HTTP APIs or add new endpoints.
+Do not change outliner property validation logic.
+Do not add support for user properties in this change.
+
+## Built-in property type considerations
+
+Built-in property configuration lives in deps/db/src/logseq/db/frontend/property.cljs.
+Built-in property types and validation live in deps/db/src/logseq/db/frontend/property/type.cljs.
+Property types include user types (:default, :number, :date, :datetime, :checkbox, :url, :node) and internal types (:string, :keyword, :map, :coll, :any, :entity, :class, :page, :property, :raw-number).
+Some built-in properties are not public and must not be user-settable via CLI.
+
+### Value coercion table
+
+| Property type | Expected CLI input | Resolution behavior |
+| --- | --- | --- |
+| :checkbox | boolean or "true"/"false" | Coerce to boolean and send directly. |
+| :number | number or numeric string | Coerce to number and send directly. |
+| :raw-number | number | Send directly and reject non numeric. |
+| :datetime | ISO string | Convert to epoch ms number before sending. |
+| :date | date string or journal page name | Resolve to journal page entity id. |
+| :default | string or EDN | If string, pass as text value and let outliner create property value block. |
+| :url | string | Validate with db-property-type/url? or allow macro urls and send as string. |
+| :string | string | Send directly. |
+| :keyword | keyword or string | Coerce string to keyword if safe. |
+| :map | EDN map | Send directly. |
+| :coll | EDN vector or list | Send directly. |
+| :entity | block uuid or db/id | Resolve to entity id with :thread-api/pull or reject. |
+| :page | page name or uuid | Resolve to page entity id, create page if missing. |
+| :class | tag name or uuid | Resolve to class entity id and fail if missing. |
+| :property | property name or keyword | Resolve to property entity id using built-in properties map. |
+| :node | block uuid or page name | Resolve to entity id or allow node text block if required. |
+| :any | EDN value | Send directly. |
+
+## Data flow overview
+
+CLI input is parsed by babashka.cli and normalized in src/main/logseq/cli/command/add.cljs.
+CLI resolves tags and property values via db-worker-node using :thread-api/pull and existing outliner ops.
+CLI applies properties using :batch-set-property for blocks and :create-page options for pages.
+
+ASCII architecture sketch.
+
+CLI add command
+  -> parse options
+  -> resolve tags and properties
+  -> db-worker-node :thread-api/apply-outliner-ops
+  -> outliner ops set properties and tags
+
+## Design decisions
+
+Tags are applied through :block/tags because it is the built-in tags property and is validated by outliner validation.
+Page creation uses :create-page with :tags and :properties options to avoid separate post-create transactions.
+Block creation uses existing insert blocks then batch-set-property for tags and each built-in property to keep behavior consistent with status handling.
+Tags are always written to :block/tags and never to :logseq.property/page-tags.
+Add block rejects any combination of --blocks or --blocks-file with --add-property, --remove-property, --add-tag, or --remove-tag.
+Properties provided via CLI apply to all inserted blocks unless the input blocks already include explicit values in their block maps.
+Properties provided via CLI override existing values on the newly created blocks to avoid ambiguity.
+
+## Implementation plan
+
+### 1. CLI option design and parsing
+
+Add new options to content-add-spec in src/main/logseq/cli/command/add.cljs for tags and properties.
+Add new options to add-page-spec in src/main/logseq/cli/command/add.cljs for tags and properties.
+Use a single EDN map option like --properties for multiple properties and a repeated option like --property for key value pairs if needed.
+Use a single EDN vector option like --tags and a repeated option like --tag for convenience.
+For --tags, allow each entry to be either a tag id, :db/ident, or the tag page's :block/title.
+For --properties, allow each property key to be a property id, :db/ident, or the property's :block/title.
+Update command summary and help output in src/main/logseq/cli/command/core.cljs if needed to reflect new options.
+
+### 2. Tag resolution helpers
+
+Add a helper in src/main/logseq/cli/command/add.cljs to normalize tag inputs into a vector of tag names or uuids.
+Add a helper that validates each tag exists and fails fast when a tag is missing.
+Use :thread-api/pull with lookup refs to resolve existing tag pages by name or uuid.
+Return a vector of tag entity ids or uuids suitable for outliner ops.
+
+### 3. Built-in property resolution helpers
+
+Add a helper in src/main/logseq/cli/command/add.cljs to parse --properties EDN and validate keys against logseq.db.frontend.property/built-in-properties.
+Reject keys not present in built-in-properties or not public based on :schema :public?.
+Add a helper to get property type from built-in-properties and then coerce values using rules in deps/db/src/logseq/db/frontend/property/type.cljs.
+Add a helper to resolve ref values into entity ids via :thread-api/pull for :page, :class, :property, :entity, and :node.
+Add a helper to resolve :date to a journal page, creating it when missing if that is consistent with UI behavior.
+Do not create tags implicitly when missing for --add-tag.
+
+### 4. Add page execution changes
+
+Extend build-add-page-action to carry tags and properties in the action context.
+Modify execute-add-page in src/main/logseq/cli/command/add.cljs to pass :tags and :properties into the :create-page op options map.
+Ensure property values are coerced before being sent so outliner validation passes.
+
+### 5. Add block execution changes
+
+Extend build-add-block-action to carry tags and properties in the action context.
+After insert blocks and status application, apply tags via :batch-set-property with :block/tags and the resolved tag ids.
+Apply each built-in property via :batch-set-property for the newly created block uuids.
+Keep :keep-uuid? behavior for status so tags and properties can reference inserted block ids.
+
+### 6. CLI formatting and errors
+
+Update error messages in src/main/logseq/cli/commands.cljs to include new invalid option errors.
+Add error formatting in src/main/logseq/cli/format.cljs if needed to show applied tags or properties in human output.
+Ensure JSON output includes any new context if the CLI returns it.
+
+### 7. Tests and fixtures
+
+Add unit tests in src/test/logseq/cli/commands_test.cljs for option parsing and error handling.
+Add integration tests in src/test/logseq/cli/integration_test.cljs that create blocks and pages with tags and built-in properties.
+Add tests for at least one ref property (e.g. :logseq.property/deadline) and one scalar property (e.g. :logseq.property/publishing-public?).
+Add tests for tag creation when tag pages do not exist.
+
+## Edge cases
+
+Tags that collide with private or built-in non-tag classes should be rejected by validation and surfaced to the CLI user.
+Missing tags in --add-tag should produce a clear missing tag error without creating new tag pages.
+Properties with closed values like :logseq.property/status should accept keyword idents as well as string labels where supported.
+Date properties must resolve to journal pages or fail with a clear error if parsing is invalid.
+Properties with cardinality many should accept vectors and sets and maintain ordering when required.
+Inline tags or page namespaces should not be created implicitly without validation of allowed characters.
+
+## Resolved decisions
+
+CLI must not allow setting non public built-in properties, even with a force option.
+Tags are applied via :block/tags and not :logseq.property/page-tags.
+Add block must reject --blocks or --blocks-file when combined with --add-property, --remove-property, --add-tag, or --remove-tag.
+Datetime values are provided as ISO strings.
+
+## Testing Details
+
+I will add CLI tests that run add page and add block end to end and assert the actual persisted properties and tags using list or show commands.
+I will add tests that confirm invalid inputs fail fast and do not produce partial writes.
+I will add tests that assert correct ref resolution for tag pages and journal pages.
+I will ensure tests cover behavior rather than internal data structures and follow @test-driven-development.
+
+## Implementation Details
+
+- Update src/main/logseq/cli/command/add.cljs with new option parsing and action fields.
+- Add tag and property normalization helpers in src/main/logseq/cli/command/add.cljs.
+- Use deps/db/src/logseq/db/frontend/property.cljs to validate built-in property keys.
+- Use deps/db/src/logseq/db/frontend/property/type.cljs to coerce values by type.
+- Use :thread-api/pull in src/main/logseq/cli/command/add.cljs to resolve pages, tags, properties, and blocks.
+- Pass tags and properties into :create-page ops in src/main/logseq/cli/command/add.cljs.
+- Apply :batch-set-property for :block/tags and built-in properties in src/main/logseq/cli/command/add.cljs.
+- Update src/test/logseq/cli/commands_test.cljs with parsing validation tests.
+- Update src/test/logseq/cli/integration_test.cljs with behavior tests for tags and built-in properties.
+
+## Question
+
+No open questions.
+
+---
diff --git a/docs/agent-guide/019-logseq-cli-data-dir-permissions.md b/docs/agent-guide/019-logseq-cli-data-dir-permissions.md
new file mode 100644
index 0000000000..9819e53edf
--- /dev/null
+++ b/docs/agent-guide/019-logseq-cli-data-dir-permissions.md
@@ -0,0 +1,82 @@
+# Logseq CLI Data-dir Permission Checks Plan
+
+Goal: Make logseq-cli validate read/write access for `data-dir` before it tries to start or communicate with db-worker-node, and surface a clear error when permissions are missing.
+
+Architecture: The CLI resolves `data-dir` in `logseq.cli.config` and uses it via `logseq.cli.server` to spawn and manage `db-worker-node`. `db-worker-node` also depends on `data-dir` for logs, locks, and SQLite storage via `frontend.worker.platform.node`.
+
+Tech Stack: ClojureScript, Node.js fs APIs, promesa, logseq-cli, db-worker-node.
+
+## Problem statement
+
+`data-dir` is used for locks, logs, and the local SQLite DB. Today, permission issues show up as late runtime exceptions (e.g., during lock creation or log file writes) with unclear error output. The CLI should proactively check that `data-dir` is readable and writable and return a clear error before attempting db-worker-node actions.
+
+## Current behavior summary
+
+- `logseq.cli.config/resolve-config` defaults `:data-dir` to `~/logseq/cli-graphs`.
+- `logseq.cli.server` resolves and uses `data-dir` for locks and server discovery.
+- `frontend.worker.db-worker-node` writes logs and lock files under `data-dir` and delegates storage to `frontend.worker.platform.node`, which creates directories as needed.
+- No explicit read/write permission checks exist; errors bubble up from fs operations.
+
+## Requirements
+
+- CLI validates that `data-dir` is a directory with read and write permission.
+- If `data-dir` does not exist, CLI attempts to create it (recursive). If creation or access fails, CLI returns an error.
+- CLI surfaces a clear error code and message that includes the failing path.
+- The check must run before any db-worker-node lifecycle or graph access that relies on `data-dir`.
+
+## Non-goals
+
+- Do not change db-worker-node storage layout or lock format.
+- Do not add new CLI options for data-dir.
+- Do not change API server behavior.
+
+## Design decisions
+
+- Treat `data-dir` as required to be read/write for all local-graph CLI commands.
+- Convert permission failures into a consistent CLI error code (e.g., `:data-dir-permission`) and message.
+- Reuse the same permission check in db-worker-node entrypoint to guard direct invocation.
+
+## Implementation plan
+
+### 1) Add a data-dir permission helper
+
+- Create a helper namespace (e.g., `src/main/logseq/cli/data_dir.cljs`) that:
+  - Expands `~` and normalizes the path.
+  - If missing, attempts `fs.mkdirSync` with `{:recursive true}`.
+  - Verifies the path is a directory (`fs.statSync`).
+  - Verifies read/write access with `fs.accessSync` (R_OK | W_OK).
+  - Throws `ex-info` with `{:code :data-dir-permission :path <path> :cause <node-code>}` on failure.
+
+### 2) Wire the check into CLI flow
+
+- In `src/main/logseq/cli/main.cljs`, after `config/resolve-config`, call the permission helper before `commands/build-action`/`commands/execute`.
+- If the CLI supports API-token-only commands that do not touch local graphs, gate the check to only run for actions that require local graph access or server management.
+- Map thrown permission errors into CLI error output with a clear message (e.g., "data-dir is not readable/writable: <path>").
+
+### 3) Add a safety check in db-worker-node
+
+- In `src/main/frontend/worker/db_worker_node.cljs`, run the same permission helper (or a small local equivalent) before `install-file-logger!` and before `platform-node/node-platform`.
+- When this check fails, print a concise error to stderr and exit with code 1 to avoid partial startup.
+
+### 4) Update CLI error formatting
+
+- In `src/main/logseq/cli/format.cljs`, add an error hint for `:data-dir-permission` (e.g., "Check filesystem permissions or set LOGSEQ_CLI_DATA_DIR").
+- Ensure error output contains the path and permission type (read/write).
+
+### 5) Tests
+
+- Add unit tests in `src/test/logseq/cli` for the permission helper:
+  - Non-existent path that can be created succeeds.
+  - Path that is a file (not directory) fails.
+  - Read-only directory fails (use chmod to remove write permission in tmp dir).
+- Add an integration test that runs CLI with `--data-dir` pointing to a non-writable directory and asserts the CLI returns error code `:data-dir-permission`.
+- Add a graph-create case where `graph-dir` cannot be created (no mkdir permission) and assert a clear error is returned.
+- Add a db-worker-node test (if there is a suitable harness) or extend existing CLI integration tests to assert db-worker-node start fails fast with the new error.
+
+## Open questions
+
+Resolved:
+- Always check `data-dir` permissions, even when an API-server token is provided.
+- Only create `data-dir` when a command needs it (local graph or server operations), not eagerly for all commands.
+
+---
diff --git a/docs/agent-guide/020-logseq-cli-default-paths-move.md b/docs/agent-guide/020-logseq-cli-default-paths-move.md
new file mode 100644
index 0000000000..fea9f1bcad
--- /dev/null
+++ b/docs/agent-guide/020-logseq-cli-default-paths-move.md
@@ -0,0 +1,77 @@
+# Logseq CLI Default Paths Move Plan
+
+Goal: Move the default `--data-dir` location to `~/logseq/cli-graphs` and the default `cli.edn` location to `~/logseq/cli.edn`, keeping logseq-cli and db-worker-node consistent.
+
+Architecture: logseq-cli resolves defaults in `logseq.cli.config` and `logseq.cli.data-dir`, then hands `data-dir` into `logseq.cli.server` which spawns and manages db-worker-node. db-worker-node itself also resolves `data-dir` for logs, locks, and SQLite storage via `frontend.worker.platform.node` and `frontend.worker.db-worker-node-lock`.
+
+Tech Stack: ClojureScript, Node.js fs/path, logseq-cli, db-worker-node.
+
+## Problem statement
+
+Defaults currently live under `~/.logseq/`, but CLI data is not the same as desktop app data and should live under `~/logseq/` for better discoverability and separation. We need to update the defaults in both logseq-cli and db-worker-node, and update docs/help text to match.
+
+## Current behavior summary
+
+- logseq-cli uses `~/logseq/cli-graphs` as the default data dir.
+- db-worker-node help text and internal resolution also default to `~/logseq/cli-graphs`.
+- logseq-cli defaults config path to `~/logseq/cli.edn`.
+- Docs reference `~/logseq/cli.edn` and `~/logseq/cli-graphs`.
+
+## Requirements
+
+- Default `data-dir` becomes `~/logseq/cli-graphs` everywhere it is derived.
+- Default config path becomes `~/logseq/cli.edn`.
+- `--data-dir` and `--config` flags continue to override defaults.
+- `LOGSEQ_CLI_DATA_DIR` and `LOGSEQ_CLI_CONFIG` (if present) continue to override defaults.
+- Help text and docs must match the new defaults.
+
+## Non-goals
+
+- Do not migrate existing data automatically.
+- Do not change CLI flags, env var names, or db-worker-node storage layout.
+- Do not change runtime behavior beyond the default locations.
+
+## Design decisions
+
+- Keep default paths defined in a single place per subsystem (CLI vs db-worker-node), but ensure they resolve to the same new location.
+- Do not auto-detect the old location as a fallback to avoid surprises; users can pass `--data-dir` / `--config` explicitly if needed.
+- Document the change and provide a brief migration note in CLI docs.
+
+## Implementation plan
+
+### 1) Update default `data-dir` constants and resolution
+
+- `src/main/logseq/cli/data_dir.cljs`
+  - Change `default-data-dir` from `~/logseq/cli-graphs` to `~/logseq/cli-graphs`.
+- `src/main/logseq/cli/server.cljs`
+  - Update `resolve-data-dir` default to `~/logseq/cli-graphs` (keeps server defaults aligned when config is absent).
+- `src/main/frontend/worker/db_worker_node_lock.cljs`
+  - Update `resolve-data-dir` default to `~/logseq/cli-graphs`.
+- `src/main/frontend/worker/platform/node.cljs`
+  - Update `node-platform` default for `data-dir` to `~/logseq/cli-graphs`.
+- `src/main/frontend/worker/db_worker_node.cljs`
+  - Update the `--data-dir` help text default to `~/logseq/cli-graphs`.
+
+### 2) Update default config path for CLI
+
+- `src/main/logseq/cli/config.cljs`
+  - Change `config-path` default from `~/logseq/cli.edn` to `~/logseq/cli.edn`.
+  - Update any inline default map (`resolve-config` default options) to match if present.
+
+### 3) Update docs and internal references
+
+- `docs/cli/logseq-cli.md`
+  - Replace references to `~/logseq/cli.edn` and `~/logseq/cli-graphs` with the new paths.
+  - Add a short migration note: existing data/config can be used by passing `--data-dir` / `--config`.
+- `docs/agent-guide/*.md`
+  - Update any references to the old defaults (notably `docs/agent-guide/002-logseq-cli-subcommands.md`, `docs/agent-guide/003-db-worker-node-cli-orchestration.md`, `docs/agent-guide/012-logseq-cli-graph-storage.md`, `docs/agent-guide/019-logseq-cli-data-dir-permissions.md`, and `docs/agent-guide/task--db-worker-nodejs-compatible.md`).
+
+### 4) Tests
+
+- Unit tests likely unaffected, but adjust any tests or snapshots that assert default path strings (search for `~/logseq/cli-graphs` or `~/logseq/cli.edn` in tests).
+- If tests assert CLI help output or default config path, update expected strings accordingly.
+
+## Notes
+
+- Do not add a one-time warning for the old `~/logseq/cli-graphs` location. If a config is needed, prefer `cli.edn` under the selected `data-dir`.
+- Do not add any fallback or compatibility for `~/logseq/cli.edn`. The old location is ignored.
diff --git a/docs/agent-guide/021-logseq-cli-reference-uuid-rewrite.md b/docs/agent-guide/021-logseq-cli-reference-uuid-rewrite.md
new file mode 100644
index 0000000000..e5c723a4bc
--- /dev/null
+++ b/docs/agent-guide/021-logseq-cli-reference-uuid-rewrite.md
@@ -0,0 +1,87 @@
+# Logseq CLI Add Reference UUID Rewrite Plan
+
+Goal: For logseq-cli add block/page content, replace every `[[<reference-name>]]` with `[[block-uuid]]` before calling db-worker-node thread-api, creating missing pages when needed.
+
+Architecture: logseq-cli (`src/main/logseq/cli/command/add.cljs`) sends `:thread-api/apply-outliner-ops` calls through `logseq.cli.transport`. db-worker-node executes `outliner-op/apply-ops!` without normalizing refs. Frontend already normalizes refs using `logseq.db.frontend.content/title-ref->id-ref`, but CLI does not.
+
+Tech Stack: ClojureScript, logseq-cli, db-worker-node, Datascript.
+
+## Problem statement
+
+Today logseq-cli passes block content to db-worker-node as-is. If content includes `[[Page Name]]`, db-worker-node does not automatically resolve or create that page for outliner ops. We need to normalize content refs to uuid references up front so db-worker-node receives canonical refs and missing pages are created deterministically.
+
+## Current behavior summary
+
+- `logseq-cli add block` builds blocks and calls `:thread-api/apply-outliner-ops` with `:insert-blocks`.
+- `logseq-cli add page` calls `:thread-api/apply-outliner-ops` with `:create-page` only (no content normalization).
+- db-worker-node `:thread-api/apply-outliner-ops` applies ops verbatim and does not resolve page refs in block content.
+- Frontend editor normalizes refs using `logseq.db.frontend.content/title-ref->id-ref`, but CLI paths do not use it.
+
+## Requirements
+
+- For add block and add page content, replace every `[[<reference-name>]]` with `[[block-uuid]]` before invoking db-worker-node thread-api.
+- Page reference:
+  - If `<reference-name>` is not a UUID, treat it as a page title.
+  - If the page does not exist, create it first.
+  - Replace `[[Page Title]]` with `[[page-uuid]]` (case-insensitive).
+- Block reference:
+  - If `<reference-name>` is a UUID, treat it as a block ref.
+  - The block must exist; otherwise return a CLI error.
+- Do not change other syntax (e.g. `((uuid))` block refs, tags, or macros) unless they are inside `[[...]]`.
+
+## Non-goals
+
+- Do not alter how `((uuid))` block refs are parsed or stored.
+- Do not introduce automatic block creation for missing block UUIDs.
+- Do not change CLI command flags or output format.
+
+## Design decisions
+
+- Reuse `logseq.db.frontend.content/title-ref->id-ref` so CLI behavior matches frontend normalization rules.
+- Extract `[[...]]` refs using the existing page-ref regex from `logseq.common.util.page-ref` to avoid implementing a new parser.
+- Resolve refs once per CLI action, cache page-name -> uuid, and then update all affected blocks before the first `:thread-api/apply-outliner-ops` call.
+- Handle page creation with the existing `ensure-page!` helper in `src/main/logseq/cli/command/add.cljs` for consistent behavior.
+
+## Implementation plan
+
+### 1) Add reference extraction and resolution helpers
+
+- `src/main/logseq/cli/command/add.cljs`
+  - Add a helper to extract `[[...]]` tokens from a block title using `logseq.common.util.page-ref/page-ref-re`.
+  - Add a helper that partitions refs into:
+    - `uuid-refs`: `[[<uuid>]]` values
+    - `page-refs`: `[[<page-title>]]` values
+  - Add a resolver that:
+    - For `page-refs`, calls `ensure-page!` (once per unique title) and returns `{:block/uuid uuid :block/title title}`.
+    - For `uuid-refs`, pulls the entity by `[:block/uuid uuid]` and errors if missing.
+
+### 2) Normalize add block content before outliner ops
+
+- `src/main/logseq/cli/command/add.cljs`
+  - In `execute-add-block`, before building ops:
+    - Walk the `:blocks` tree (top-level and any nested `:block/children`) and collect all `[[...]]` refs.
+    - Resolve refs once per action using the resolver from step 1.
+    - For each block with `:block/title`, rewrite it with `db-content/title-ref->id-ref` using the resolved refs and `{:replace-tag? false}`.
+  - Use the rewritten blocks in the `:insert-blocks` op.
+
+### 3) Normalize add page content (when present)
+
+- `src/main/logseq/cli/command/add.cljs`
+  - If add page grows to accept initial blocks/content (or if `:create-page` options start supporting content), reuse the same ref normalization flow from step 2 before invoking `:create-page` or `:insert-blocks`.
+  - If no content is provided, no change is needed in the current implementation.
+
+### 4) Tests
+
+- `test/logseq/cli/integration_test.cljs`
+  - Add an integration test for `add block` with content `"See [[New Page]]"`:
+    - Assert the page is created.
+    - Pull the inserted block and verify its title contains `[[<page-uuid>]]` instead of `[[New Page]]`.
+  - Add an integration test for `add block` with content `"See [[<existing-block-uuid>]]"`:
+    - Assert the UUID is preserved and no new page is created.
+  - Add an integration test for `add block` with content `"See [[<missing-block-uuid>]]"`:
+    - Assert CLI returns an error with a clear message.
+
+## Notes
+
+- If we later decide to normalize tags (`#tag`) or macro-based refs, we can extend the resolver to call `db-content/title-ref->id-ref` with `:replace-tag? true` and add tests accordingly.
+- Keep all normalization in CLI to avoid changing db-worker-node semantics for other callers.
diff --git a/docs/agent-guide/022-logseq-cli-help-show-output.md b/docs/agent-guide/022-logseq-cli-help-show-output.md
new file mode 100644
index 0000000000..00d72911bb
--- /dev/null
+++ b/docs/agent-guide/022-logseq-cli-help-show-output.md
@@ -0,0 +1,122 @@
+# Logseq CLI Help and Show Output Cleanup Implementation Plan
+
+Goal: Improve logseq-cli help readability and ensure show JSON and EDN outputs use :db/id without :block/uuid.
+
+Architecture: The CLI help text is assembled in logseq.cli.command.core and babashka.cli spec descriptions, while show output is built in logseq.cli.command.show and formatted in logseq.cli.format before returning JSON or EDN.
+
+Tech Stack: ClojureScript, logseq-cli, babashka.cli, db-worker-node.
+
+Related: Relates to 018-logseq-cli-add-tags-builtin-properties.md.
+
+## Problem statement
+
+The current help output lists [options] for nearly every command, which clutters the help display and reduces readability.
+
+The tags and properties option help text does not clearly state that identifiers can be id, :db/ident, or :block/title across all relevant help contexts.
+
+The show command includes :block/uuid in JSON and EDN output, even though :db/id is already present and preferred for programmatic consumers.
+
+```
+logseq-cli
+  |  help text built from babashka.cli specs
+  v
+logseq.cli.command.core
+  |  parse args and build command payloads
+  v
+logseq.cli.command.show
+  |  fetch tree data from db-worker-node
+  v
+logseq.cli.format
+  |  render human, json, edn output
+  v
+stdout
+```
+
+## Testing Plan
+
+I will add or update unit tests that assert help summaries do not include repeated [options] in the command list, and that tags and properties descriptions include the identifier guidance.
+
+I will add or update unit tests that verify show JSON and EDN outputs do not include :block/uuid and still include :db/id for root and child nodes.
+
+I will add or update integration tests for show JSON output to assert :db/id is present and :block/uuid is absent in root, tags, and linked references where applicable.
+
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Requirements
+
+The top level help output and group summaries must avoid repeating [options] for each command listing while still documenting that options exist in the usage line.
+
+The help description for --tags and --properties must explicitly state that identifiers can be id, :db/ident, or :block/title.
+
+The show command must omit :block/uuid from JSON and EDN outputs while preserving :db/id for the same entities.
+
+The show command human output must be unchanged.
+
+## Non-goals
+
+Do not change CLI command behavior or supported flags beyond help text updates.
+
+Do not change db-worker-node behavior or its API surface.
+
+Do not change the structure of human output for show, list, add, or query commands.
+
+## Design decisions
+
+Limit the help output adjustment to formatting in logseq.cli.command.core so command behavior and parsing remain unchanged.
+
+Apply the identifier clarification to all --tags and --properties options in logseq.cli.command.add and any other specs that expose those flags.
+
+Strip :block/uuid only for show outputs in JSON and EDN formats by post-processing tree data just before returning payloads.
+
+## Implementation plan
+
+1. Follow @test-driven-development for every change in this plan.
+
+2. Add a unit test in src/test/logseq/cli/commands_test.cljs that asserts command list rows in top level and group help do not contain [options] after the command name.
+
+3. Add a unit test in src/test/logseq/cli/commands_test.cljs that asserts the --tags and --properties option descriptions include the text supporting id, :db/ident, and :block/title identifiers.
+
+4. Add a unit test in src/test/logseq/cli/format_test.cljs or src/test/logseq/cli/commands_test.cljs that asserts show JSON and EDN outputs strip :block/uuid while retaining :db/id in root and child nodes.
+
+5. Update integration tests in src/test/logseq/cli/integration_test.cljs that currently assert :uuid or :block/uuid in show JSON output to instead assert :db/id and absence of :block/uuid.
+
+6. Adjust logseq.cli.command.core command listing formatting so only the usage line includes [options], and the command listing uses the bare command path without the suffix.
+
+7. Update the --tags and --properties option descriptions in src/main/logseq/cli/command/add.cljs to include the identifier guidance sentence in a consistent phrasing.
+
+8. Add a helper in src/main/logseq/cli/command/show.cljs or src/main/logseq/cli/format.cljs that removes :block/uuid keys from show JSON and EDN payloads, and apply it in execute-show when output-format is :json or :edn.
+
+9. Run the updated unit tests and integration tests from the Testing Plan and confirm all pass.
+
+## Edge cases
+
+Command help should still show [options] in the usage line for commands that accept options, but not in the command list table.
+
+Multi-id show results should strip :block/uuid from each tree entry without changing the error map shape.
+
+Linked references and tag entities should keep :db/id in the output even when :block/uuid is removed.
+
+## Testing Details
+
+I will add tests that verify help summaries and option descriptions at the command summary level and not by matching the raw babashka.cli output.
+
+I will add tests that parse show JSON and EDN output and assert :block/uuid is missing while :db/id remains on block nodes.
+
+I will update integration tests that read show JSON output to match the new key expectations without changing the test setup logic.
+
+## Implementation Details
+
+- Update logseq.cli.command.core formatting to render command rows without [options].
+- Keep usage lines intact so users still see options availability in usage sections.
+- Align help text for --tags and --properties to a single wording that mentions id, :db/ident, and :block/title.
+- Add a show-specific sanitization step for json and edn output only.
+- Keep the show tree data used for human output unchanged to avoid regressions.
+- Ensure strip logic is recursive so :block/uuid is removed from nested children and linked references.
+- Prefer clojure.walk/postwalk for key removal to minimize custom traversal code.
+- Document the new behavior in tests rather than adding new user-facing docs.
+
+## Question
+
+This is resolved. Only add supports --tags and --properties today, so we will update help text there only.
+
+---
diff --git a/docs/agent-guide/023-logseq-cli-help-show-styling.md b/docs/agent-guide/023-logseq-cli-help-show-styling.md
new file mode 100644
index 0000000000..c0c25da8e3
--- /dev/null
+++ b/docs/agent-guide/023-logseq-cli-help-show-styling.md
@@ -0,0 +1,108 @@
+# Logseq CLI Help And Show Styling Implementation Plan
+
+Goal: Add picocolors-based styling for help output and show human output in logseq-cli and db-worker-node.
+
+Architecture: Introduce a small shared styling helper that wraps picocolors and is used by CLI help renderers and show tree formatting.
+Help output headings and error strings will apply bold to keywords while show output will color status labels and bold tag suffixes without changing data payloads.
+
+Tech Stack: ClojureScript, Node.js, picocolors, babashka.cli.
+
+Related: Relates to docs/agent-guide/022-logseq-cli-help-show-output.md.
+
+## Problem statement
+
+The current help output in logseq-cli and db-worker-node is plain text and does not emphasize command names or option names, which makes scanning harder.
+The show command human output also does not visually differentiate status values or tags, which makes scanning large trees harder.
+The tree glyphs in show output currently have the same visual weight as content, which makes the structure harder to scan.
+
+## Testing Plan
+
+I will add unit tests for help summary formatting that assert bold styling is applied to command names, option names, and error messages for missing options.
+I will add unit tests for show tree text rendering that verify status labels are colorized and tag suffixes are bolded while preserving the existing tree glyph alignment when ANSI codes are stripped.
+I will add a unit test that verifies tree glyphs are rendered in a lighter style without altering alignment when ANSI is stripped.
+I will add a unit test for db-worker-node help output that asserts bold styling on command names and option names and that the help text still omits auth-token.
+I will add unit tests for the styling helper to ensure it can be disabled for tests by stripping ANSI when comparing output.
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Scope and constraints
+
+This plan targets logseq-cli in src/main/logseq/cli and db-worker-node help output in src/main/frontend/worker/db_worker_node.cljs.
+This plan must use picocolors for color and bold styling and should not change JSON or EDN output formats.
+This plan should not introduce new CLI options unless required to gate coloring for tests.
+Styling must only be applied when color is supported, and dumb terminals must receive plaintext output.
+The `logseq -h` help output should omit the commands list section.
+
+## Files and ownership
+
+| Area | Path | Notes |
+| --- | --- | --- |
+| npm dependency | package.json | Add picocolors dependency used by ClojureScript Node targets. |
+| npm lockfile | pnpm-lock.yaml | Update to include picocolors. |
+| CLI help summary | src/main/logseq/cli/command/core.cljs | Apply bold styling to command names and option names in help summaries and error text. |
+| CLI show output | src/main/logseq/cli/command/show.cljs | Apply status color and tag bold styling in tree labels. |
+| CLI show output | src/main/logseq/cli/command/show.cljs | Apply lighter styling to tree glyphs in human output. |
+| CLI formatting helpers | src/main/logseq/cli/format.cljs | Avoid impacting non-human output, and ensure show uses styled message for human output only. |
+| CLI legacy help | deps/cli/src/logseq/cli.cljs | Apply bold styling to command names and option names in help output for legacy cli entrypoint. |
+| db-worker-node help | src/main/frontend/worker/db_worker_node.cljs | Apply bold styling to command names and option names in help output lines. |
+| CLI tests | src/test/logseq/cli/commands_test.cljs | Update help summary and show tree tests to tolerate ANSI and assert styling intent. |
+| CLI format tests | src/test/logseq/cli/format_test.cljs | Add or update tests to ensure human show output includes styled text but JSON and EDN do not. |
+| db-worker-node tests | src/test/frontend/worker/db_worker_node_test.cljs | Extend help output test to validate bold styling. |
+
+## Implementation plan
+
+1. Add picocolors to package.json dependencies and update pnpm-lock.yaml with the new dependency using pnpm.
+2. Create a small styling helper in a new namespace such as src/main/logseq/cli/style.cljs that wraps picocolors functions for bold and color and exposes a no-color flag for tests.
+3. Add a companion helper in a shared location for db-worker-node, or reuse the same namespace if it is available in that build target, to avoid duplicated color logic.
+4. In src/main/logseq/cli/style.cljs, add a color support check that disables styling when color is not supported or TERM is dumb.
+5. In src/main/logseq/cli/command/core.cljs, wrap help summary command names and option names with the new bold helper.
+6. In src/main/logseq/cli/command/core.cljs, update the invalid options error formatting so missing required option names are bolded in the error message.
+7. In deps/cli/src/logseq/cli.cljs, apply the same bold styling to command names and option names in the help output for the legacy cli entrypoint.
+8. In src/main/frontend/worker/db_worker_node.cljs, update show-help! output to bold command names and option names in the help text.
+9. In src/main/logseq/cli/command/show.cljs, add a status style function that maps known status labels to distinct colors, and bolds the status text, using picocolors.
+10. In src/main/logseq/cli/command/show.cljs, update the tag suffix rendering to wrap each #tag with bold styling and ensure tags remain separated by spaces.
+11. In src/main/logseq/cli/command/show.cljs, style the tree glyphs with a dim or gray color using picocolors while leaving ids and labels unstyled.
+12. In src/main/logseq/cli/command/show.cljs, ensure status formatting and glyph styling are only applied to the human output path and do not alter the underlying data used for JSON or EDN outputs.
+13. Update src/test/logseq/cli/commands_test.cljs to compare help summaries using an ANSI-stripping helper so assertions remain stable, and to assert bold styling for command and option names.
+14. Update src/test/logseq/cli/commands_test.cljs show tree text tests to assert that the status prefix and tag suffix are styled when ANSI is preserved, and to verify tree alignment and glyph lightening using stripped output.
+15. Add or update tests in src/test/logseq/cli/format_test.cljs to verify that human show output includes styled prefixes while JSON and EDN outputs remain unchanged.
+16. Update src/test/frontend/worker/db_worker_node_test.cljs to assert that the help output bolds command and option names and still omits auth-token.
+17. Run bb dev:lint-and-test to ensure all lint and unit tests pass.
+
+## Edge cases
+
+The status value may be a keyword with namespaces such as :logseq.property.status/todo and should still map to the same color for TODO.
+The status label may be missing or blank, and the show output should remain unchanged in that case.
+Tag labels may include uppercase or punctuation and should still render as bolded tags without losing the leading #.
+Help output should still be readable when ANSI colors are not supported, and tests should be resilient by stripping ANSI sequences.
+Tree glyph styling should not break alignment when ANSI codes are stripped.
+Styling should be fully disabled when color is not supported or TERM is dumb.
+
+## Open questions
+
+Should picocolors styling be applied only when stdout is a TTY, or should it always render for human output regardless of terminal support.
+Which specific status to color mapping is preferred for the full set of Logseq statuses such as NOW, LATER, WAITING, CANCELLED, and TODO variants.
+
+## Testing Details
+
+The tests will verify visible behavior by asserting that help output includes bolded command names and option names and that show output includes styled status and tags when rendered to human text.
+The tests will also assert that JSON and EDN outputs remain unchanged and that ANSI codes do not break alignment by validating stripped output.
+The tests will continue to avoid asserting internal data structures and instead focus on rendered output behavior.
+
+## Implementation Details
+
+- Use a small helper that can apply bold and color via picocolors and also expose a strip-ansi helper for tests.
+- Keep styling limited to human output paths and avoid touching transport or data payloads.
+- Centralize the status to color mapping in one function to keep future changes easy.
+- Apply bold to command names and option names in help output and error strings.
+- Preserve existing spacing and alignment by applying styling after label construction rather than before width calculations.
+- Apply a lighter style to tree glyphs only, not to ids or labels.
+- Gate styling behind color support checks so dumb terminals get plaintext output.
+- Ensure any new helper is available to both the CLI and db-worker-node build targets.
+- Update tests to use ANSI stripping for alignment assertions and explicit style presence for keyword checks.
+- Avoid adding new configuration flags unless tests cannot reliably assert output without them.
+
+## Question
+
+Styling is limited to help info and show human output for now.
+
+---
diff --git a/docs/agent-guide/024-logseq-cli-show-updates.md b/docs/agent-guide/024-logseq-cli-show-updates.md
new file mode 100644
index 0000000000..4bc6d1d19e
--- /dev/null
+++ b/docs/agent-guide/024-logseq-cli-show-updates.md
@@ -0,0 +1,99 @@
+# Logseq CLI Show Output & Linked References Options Plan
+
+Goal: Update the `logseq show` command to (1) render the ID column in human output with lighter styling (matching tree glyphs), (2) include `:db/ident` on block entities in JSON/EDN output when present, and (3) add an option to toggle Linked References (default enabled).
+Architecture: Keep the existing logseq-cli → db-worker-node HTTP transport and thread-api calls; adjust show command selectors and output formatting only.
+Tech Stack: ClojureScript, babashka.cli, db-worker-node transport, Logseq pull selectors, CLI styling helpers.
+Related: Builds on `logseq.cli.command.show` tree rendering and linked references fetch; see `docs/agent-guide/010-logseq-cli-show-linked-references.md` and `docs/agent-guide/023-logseq-cli-help-show-styling.md`.
+
+## Problem Statement
+
+The `show` command currently renders the ID column with the same styling as regular text, does not expose `:db/ident` in JSON/EDN output for blocks, and always fetches/prints Linked References. We need to make the ID column visually lighter, surface `:db/ident` when it exists, and add a switch to disable linked references (defaulting to true).
+
+## Non-Goals
+
+- Changing db-worker-node APIs or transport protocols.
+- Altering the show command’s existing tree structure or block ordering.
+- Changing JSON/EDN output structure beyond adding `:db/ident` when present.
+
+## Current Behavior (Key Points)
+
+- Human output is rendered by `tree->text` in `src/main/logseq/cli/command/show.cljs`, with tree glyphs styled via `style/dim` but IDs unstyled.
+- JSON/EDN output pulls specific selectors via `tree-block-selector` / `linked-ref-selector` and strips only `:block/uuid`.
+- Linked References are always fetched and rendered via `fetch-linked-references` + `tree->text-with-linked-refs`.
+
+## Proposed Changes
+
+1) **Lighter ID column in human output**
+   - Style the padded ID column with the same dim styling used for tree glyphs.
+   - Apply the change in `tree->text` so both root and child rows render IDs dimmed.
+
+2) **Include `:db/ident` in JSON/EDN for blocks (when present)**
+   - Add `:db/ident` to block pull selectors:
+     - `tree-block-selector` (children)
+     - `linked-ref-selector` (linked references)
+     - root entity pulls in `fetch-tree` for `:id`, `:uuid`, and `:page`
+   - No post-processing is required because absent attributes will not appear in the pulled maps.
+
+3) **Optional Linked References (default true)**
+   - Add a boolean option `--linked-references` to `show-spec`, defaulting to true.
+   - Pass the option through `build-action` and into `build-tree-data`.
+   - When disabled:
+     - Skip `fetch-linked-references` entirely.
+     - Omit the `Linked References` section from human output.
+     - Omit `:linked-references` from JSON/EDN output.
+
+## Implementation Plan
+
+1) **Add show option wiring**
+   - Update `show-spec` in `src/main/logseq/cli/command/show.cljs` with a new boolean option (choose name + description, note default true).
+   - Extend `build-action` to include the option in `:action` (e.g., `:linked-references?`).
+   - Update `invalid-options?` if needed for any new validation.
+
+2) **Gate linked references fetching/rendering**
+   - Update `build-tree-data` to honor the new option:
+     - If enabled, keep current logic.
+     - If disabled, skip `fetch-linked-references`, avoid UUID label resolution based on linked refs, and avoid `tree->text-with-linked-refs`.
+   - Update `execute-show` to select `tree->text` vs `tree->text-with-linked-refs` based on the option.
+   - Ensure JSON/EDN output omits `:linked-references` when disabled.
+
+3) **Add `:db/ident` to selectors**
+   - Update `tree-block-selector`, `linked-ref-selector`, and root entity pull vectors in `fetch-tree` to include `:db/ident`.
+   - Ensure this does not add nil values (pull should omit missing attributes).
+
+4) **Dim ID column in human output**
+   - In `tree->text`, apply `style/dim` to the padded ID string (e.g., `pad-id` output) for both root and child rows.
+   - Keep existing branch/prefix dim styling unchanged.
+
+5) **Help output updates**
+   - Ensure `logseq show --help` lists the new linked references option (covered automatically by `show-spec`).
+
+## Testing Plan
+
+- Update or add unit tests in:
+  - `src/test/logseq/cli/format_test.cljs` to verify:
+    - ANSI dim styling is applied to the ID column in human output when color is enabled.
+    - No regressions in strip-ansi output.
+  - `src/test/logseq/cli/commands_test.cljs` to verify:
+    - `logseq show --help` includes the new linked references option.
+- Add show-specific tests for JSON/EDN output:
+  - Ensure `:db/ident` appears when present (use a stubbed tree map or test fixtures if available).
+  - Ensure `:linked-references` is omitted when the option disables them.
+
+## Edge Cases
+
+- Blocks with no `:db/ident` should not gain a nil or empty key in output.
+- When linked refs are disabled, UUID label resolution should not depend on linked refs (ensure `collect-uuid-refs` handles empty refs).
+- Multi-id output should still honor the linked references option per target and not render linked refs when disabled.
+
+## Files to Touch
+
+- `src/main/logseq/cli/command/show.cljs` (options, selectors, tree output, linked refs gating)
+- `src/test/logseq/cli/format_test.cljs` (ID dim styling test)
+- `src/test/logseq/cli/commands_test.cljs` (help output)
+- Possibly `src/test/logseq/cli/command_show_test.cljs` or similar if a dedicated show test file exists
+
+## Open Questions
+
+- None.
+
+---
diff --git a/docs/agent-guide/025-logseq-cli-builtin-status-priority-queries.md b/docs/agent-guide/025-logseq-cli-builtin-status-priority-queries.md
new file mode 100644
index 0000000000..b185015d8b
--- /dev/null
+++ b/docs/agent-guide/025-logseq-cli-builtin-status-priority-queries.md
@@ -0,0 +1,94 @@
+# Logseq CLI Built-in Status/Priority Queries Plan
+
+Goal: Add built-in `query` names `list-status` and `list-priority` that return the available Status/Priority options from a graph.
+Architecture: Keep the existing logseq-cli → db-worker-node transport and thread-api usage; implement `list-status`/`list-priority` via `:thread-api/q` rather than adding a dedicated thread-api.
+Tech Stack: ClojureScript, logseq-cli, db-worker-node, Datascript, logseq.db.frontend.property.
+Related: `src/main/logseq/cli/command/query.cljs`, `src/main/frontend/worker/db_core.cljs`, `deps/db/src/logseq/db/frontend/property.cljs`.
+
+## Problem Statement
+
+Logseq CLI’s `query` built-ins are limited to Datascript queries. Users cannot easily discover valid Status or Priority options for a graph (e.g., TODO/DOING/DONE, Urgent/High/Low) without knowing the property internals or running custom queries. We need simple built-ins that list the closed values configured for Status and Priority.
+
+## Non-Goals
+
+- Changing property schemas or defaults.
+- Replacing the existing Datascript query flow.
+- Adding new UI commands outside `query` or changing CLI output formats.
+
+## Current Behavior (Key Points)
+
+- Built-in queries are defined in `built-in-query-specs` in `src/main/logseq/cli/command/query.cljs` and executed via `:thread-api/q`.
+- Status and Priority options are stored as closed values on `:logseq.property/status` and `:logseq.property/priority` (see `logseq.db.frontend.property/get-closed-property-values`).
+- There is no CLI helper to list those closed values.
+
+## Proposed Changes
+
+1) **Use `:thread-api/q` for closed values**
+   - Implement `list-status`/`list-priority` by issuing a Datascript query via `:thread-api/q`.
+   - Return a vector of maps with `:db/ident` and `:db/id`.
+   - Use `:find` with an ellipsis form to return a vector, e.g. `:find [(pull ?e [:db/ident :db/id]) ...]` (instead of `:find (pull ?e [:db/ident :db/id])`).
+
+2) **Add built-in query names `list-status` and `list-priority`**
+   - Add entries to `built-in-query-specs` that specify a non-Datascript execution path (e.g., `:method`/`:handler` metadata).
+   - Wire `build-action` to create a dedicated action type when these names are used.
+   - Update `execute-query` to call the new thread API and return results as `{:result ["TODO" ...]}` so existing output formatting works unchanged.
+
+3) **Expose built-ins in `query list`**
+   - Ensure `query list` includes the new entries (with `doc` and `inputs: []`).
+   - Keep existing “custom overrides built-in” semantics.
+
+## Implementation Plan
+
+1) **db-worker-node API**
+   - No new thread-api should be added; use `:thread-api/q` only.
+
+2) **CLI built-in wiring**
+   - Extend `built-in-query-specs` in `src/main/logseq/cli/command/query.cljs`:
+     - `list-status` → `:property-ident :logseq.property/status`
+     - `list-priority` → `:property-ident :logseq.property/priority`
+     - Include `:doc` and `:inputs []`.
+   - Update `normalize-query-entry` / `find-query` handling to preserve the extra metadata.
+   - Update `build-action`:
+     - When the built-in includes a `:property-ident` (or `:method`), create an action like
+       `{:type :query-closed-values :repo ... :property-ident ...}`.
+   - Update `execute-query`:
+   - Branch on the new action type to call `transport/invoke` with `:thread-api/q` and return `{:result values}` (vector of maps with `:db/ident` and `:db/id`).
+
+3) **Output and docs**
+   - No change to formatters; `format-query-results` already prints vectors.
+   - Update CLI docs if needed (e.g., `docs/cli/logseq-cli.md`) to mention the two built-ins.
+
+## Testing Plan
+
+- **Unit tests** (`src/test/logseq/cli/command/query_test.cljs`):
+  - `list-queries` includes `list-status` and `list-priority` with empty inputs.
+  - `build-action` for `--name list-status` returns `:query-closed-values` action with property ident.
+  - Custom query overrides built-in name still works.
+
+- **db-worker-node tests**: no new thread-api, so no additional db-worker-node test needed.
+
+- **Integration** (`src/test/logseq/cli/integration_test.cljs`):
+  - Start a graph, run `logseq query --name list-status` / `list-priority`, assert status `ok` and a non-empty vector.
+  - If stable defaults are known, assert a known value is present; otherwise, seed closed values in the test graph.
+
+## Edge Cases
+
+- Property has no closed values → return an empty vector (not an error).
+- Closed values may be stored in either `:block/title` or `:logseq.property/value`; if `:db/ident` is absent, the map should still include the key with a nil value.
+- Ensure ordering follows `:block/order` from `get-closed-property-values`.
+
+## Files to Touch
+
+- `src/main/frontend/worker/db_core.cljs` (no new thread-api)
+- `src/main/logseq/cli/command/query.cljs` (built-in specs, build-action branching, execute-query)
+- `src/test/logseq/cli/command/query_test.cljs` (unit coverage)
+- `src/test/frontend/worker/db_worker_node_test.cljs` or a db-core test (not required for new thread-api)
+- `src/test/logseq/cli/integration_test.cljs` (CLI end-to-end)
+- `docs/cli/logseq-cli.md` (optional docs update)
+
+## Open Questions
+
+- Use `:thread-api/q` to return structured values: `{:db/ident .., :db/id ..}`.
+- Expose `list-status`/`list-priority` via `query --name` only (no dedicated subcommands).
+
+---
diff --git a/docs/agent-guide/026-logseq-cli-query-output.md b/docs/agent-guide/026-logseq-cli-query-output.md
new file mode 100644
index 0000000000..7c36123334
--- /dev/null
+++ b/docs/agent-guide/026-logseq-cli-query-output.md
@@ -0,0 +1,70 @@
+# Logseq CLI Query Output Piping Implementation Plan
+
+Goal: Remove the space-to-comma transformation in CLI query human output while preserving EDN output and ensuring `logseq show --id` accepts ids both via argument and stdin pipelines.
+
+Architecture: Keep human formatting for query results as EDN output (no line-oriented transformation) and update tests to validate pipeline usage with intact EDN.
+Architecture: Extend logseq show --id to read ids from stdin when present, whether or not an id argument is provided, and update integration tests to validate both xargs and direct stdin pipelines.
+
+Tech Stack: ClojureScript, Logseq CLI, db-worker-node, Node-based integration tests.
+
+Related: Relates to docs/agent-guide/025-logseq-cli-builtin-status-priority-queries.md.
+
+## Testing Plan
+
+I will add an integration test that ensures a human-output query can be piped into xargs and then into logseq show --id for multiple ids, with the query output preserved as EDN.
+I will add an integration test that ensures a human-output query can be piped directly into logseq show --id via stdin, with or without an explicit id argument.
+I will update the existing integration test that currently pipes human query output directly into logseq show so it asserts EDN preservation and stdin ingestion.
+I will add a focused unit test for format-query-results that covers EDN output for scalar collections, non-scalar collections, and nil results.
+I will add a unit test for show id parsing that covers stdin provided, stdin blank, and explicit id values.
+
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Problem statement
+
+The CLI currently replaces spaces with commas in format-query-results, which is a lossy transformation that makes output less readable.
+We need to remove the space-to-comma logic while preserving EDN output (including spaces) for query results.
+Pipelines should remain usable by allowing logseq show --id to accept ids from stdin and from explicit arguments interchangeably.
+
+## Plan
+
+1. Read the existing formatting logic in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs and document current behavior in a quick note.
+2. Read the show command option parsing in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs and /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/id.cljs to understand current id validation.
+3. Locate the current integration test that verifies human query output piping in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs and map the required changes.
+4. Define the new output rule for format-query-results as a comment in the plan: always return EDN output unchanged (including spaces), and remove space-to-comma logic.
+5. Define the new show --id stdin rule as a comment in the plan: when stdin is non-empty, parse it as the id or id vector string and use it regardless of whether an id argument is provided.
+6. Write the failing unit tests for format-query-results in a new test namespace under /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs that covers nil, scalar-id sequences, and nested maps, all preserved as EDN strings.
+7. Write failing unit tests for show id parsing in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/show_test.cljs that cover stdin provided (overriding or complementing args), stdin blank, and explicit id values.
+8. Run the unit tests to confirm the failure before implementation using bb dev:test with the new namespaces.
+9. Write a failing integration test that uses the exact pipeline command from the request by invoking a shell command from the test harness in /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs for xargs usage.
+10. Write a failing integration test that uses the exact pipeline command from the request for direct stdin piping into logseq show --id with or without an argument.
+11. Run the integration tests to confirm the failure before implementation using bb dev:test with the specific test names.
+12. Implement the new format-query-results behavior in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs by removing the space-to-comma logic and preserving EDN output.
+13. Implement stdin ingestion for show --id in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs, using a helper to read from stdin when non-empty regardless of whether an id argument is provided.
+14. Update the existing human-output pipeline integration test to align with the EDN-preserving output and assert both xargs and direct stdin usage.
+16. Re-run the unit tests and the integration tests to validate the new behavior.
+17. Update deps/cli/README.md examples if they reference comma-transformed output, and add a short note describing the new xargs-friendly and stdin-friendly behavior for id lists.
+
+## Testing Details
+
+The unit tests will exercise behavior by calling format-query-results with representative results and asserting the exact emitted EDN string for id lists and non-id data.
+The integration tests will execute logseq query with a task-search or custom datalog query, pipe the EDN output through xargs into logseq show --id, and pipe directly into logseq show --id via stdin.
+The show stdin behavior test will assert that missing --id input without stdin returns a clear error and that stdin is parsed the same as an explicit id argument.
+
+## Implementation Details
+
+- Preserve the existing safe-read-string validation to avoid changing behavior for invalid EDN strings.
+- Keep non-scalar results as their original EDN string output.
+- Maintain nil handling so that "nil" still prints as "nil".
+- Remove the space-to-comma transformation while keeping EDN output intact, including spaces.
+- Add stdin reading to show --id when stdin is non-empty, even if an id argument is provided.
+- Parse stdin through the same id parsing function used for explicit --id values.
+- Keep existing errors when --id is missing and stdin is empty or whitespace.
+- Update integration tests to use the exact pipeline command from the requirement.
+- Use @test-driven-development for all implementation steps.
+
+## Question
+
+Query results remain in EDN form (e.g., `[1 2 3]`) with no line-oriented transformation.
+Logseq show --id accepts ids via explicit argument and via stdin pipelines (stdin takes precedence when provided).
+
+---
diff --git a/docs/agent-guide/027-logseq-cli-update-command.md b/docs/agent-guide/027-logseq-cli-update-command.md
new file mode 100644
index 0000000000..1911937726
--- /dev/null
+++ b/docs/agent-guide/027-logseq-cli-update-command.md
@@ -0,0 +1,133 @@
+# Logseq CLI Update Command (Move Refactor)
+
+## Summary
+Introduce a new `update` CLI command that subsumes the current `move` command and adds tag/property updates. The new command keeps all existing move capabilities/options, makes move targets optional (no target means no move), and adds update/remove semantics for tags and properties. The plan is grounded in current `logseq-cli` parsing/execution and db-worker-node outliner ops.
+
+## Goals
+- Replace `move` command behavior with `update` while keeping all current move options and semantics.
+- Allow `update` to move blocks *and/or* update tags/properties in one command.
+- Support new options:
+  - `--update-tags`, `--update-properties`
+  - `--remove-tags`, `--remove-properties`
+- Reuse tag/property parsing and resolution rules from `add block`:
+  - Identifiers accept `db/id`, `db/ident`, `block/title`.
+  - `--update-tags` and `--update-properties` accept the same EDN format as `add block` `--tags`/`--properties`.
+  - `--remove-tags` and `--remove-properties` accept EDN vectors of tag/property identifiers.
+
+## Non-goals
+- Changing db-worker-node APIs or introducing new outliner ops.
+- Expanding `update` beyond blocks (no page-level update scope in this iteration).
+- Changing move semantics or target resolution.
+
+## Background: Current Move Command
+- CLI move implementation lives in `src/main/logseq/cli/command/move.cljs`.
+- It requires a source (`--id` or `--uuid`) and a target (`--target-id`, `--target-uuid`, or `--target-page`).
+- Execution uses `:thread-api/apply-outliner-ops` with `[:move-blocks ...]`.
+- Move output formatting in `src/main/logseq/cli/format.cljs` uses `format-move-block`.
+
+## Proposed Behavior (Update Command)
+### Required/Optional Inputs
+- **Source is required**: one of `--id` or `--uuid`.
+- **Move targets are optional**:
+  - `--target-page`, `--target-uuid`, `--target-id`, `--pos` are optional.
+  - If no target is provided, no move occurs and the command only updates tags/properties.
+  - If a target is provided, move executes with the same semantics as today.
+- **Update/remove options are optional**:
+  - `--update-tags` (EDN vector, same as `add block --tags`)
+  - `--update-properties` (EDN map, same as `add block --properties`)
+  - `--remove-tags` (EDN vector of tag identifiers)
+  - `--remove-properties` (EDN vector of property identifiers)
+
+### Validation Rules
+- Only one source selector is allowed: `--id` or `--uuid`.
+- Only one target selector is allowed: `--target-id`, `--target-uuid`, or `--target-page`.
+- `--pos sibling` is only valid when the target is a block (not a page), same as `move`.
+- At least one of the following must be provided: target (move) or update/remove options.
+- `--update-tags` and `--update-properties` accept the same EDN grammar and validations as in `add`.
+- `--remove-tags` and `--remove-properties` must be non-empty vectors (EDN), with identifiers validated similarly to add.
+
+### Execution Semantics
+- Resolve source block to `db/id` using existing move helpers.
+- If move target provided, resolve target entity using existing move helpers and compute `pos` opts.
+- Tag/property updates use current outliner ops (no new db-worker changes):
+  - **Add/update tags**: `[:batch-set-property [block-ids :block/tags tag-id {}]]` for each tag.
+  - **Add/update properties**: `[:batch-set-property [block-ids property-id value {}]]`.
+  - **Remove tags**: `[:batch-delete-property-value [block-ids :block/tags tag-id]]`.
+  - **Remove properties**: `[:batch-remove-property [block-ids property-id]]`, with property resolution aligned to `add` (built-in/public property rules).
+- Combine operations into a single `apply-outliner-ops` call when possible to keep updates atomic and reduce roundtrips.
+
+## Design and Implementation Plan
+### 1) Create `update` command module
+- New file: `src/main/logseq/cli/command/update.cljs`.
+- Start from `move.cljs` and expand the spec to include update/remove tag/property options.
+- Extract shared helpers from `move.cljs` (e.g., `resolve-source`, `resolve-target`, `pos->opts`, `invalid-options?`) into a small shared namespace or move into `update.cljs`.
+
+### 2) Reuse tag/property parsing and resolution from `add`
+- Refactor `src/main/logseq/cli/command/add.cljs` to expose reusable helpers for:
+  - `parse-tags-option`, `parse-properties-option` (for update)
+  - `resolve-tags`, `resolve-properties` (for update)
+  - Tag/property identifier normalization functions if needed for remove vectors
+- Keep the parsing behavior exactly consistent with `add block`.
+- Add new helper in `add` (or a shared namespace) to parse **remove vectors**:
+  - `parse-tags-vector-option` (vector of tag identifiers)
+  - `parse-properties-vector-option` (vector of property identifiers)
+
+### 3) Update top-level command registry
+- Add `update` to `src/main/logseq/cli/commands.cljs` table and summary groups.
+- Remove `move` from the command registry and help output (no alias/compat).
+
+### 4) Update parse/validation logic
+- In `finalize-command` (`src/main/logseq/cli/commands.cljs`):
+  - Add `update`-specific validation for sources, targets, and update/remove options.
+  - Reuse `update-command/invalid-options?`.
+  - Allow missing target when update/remove options are present.
+  - Keep error messaging aligned with existing CLI patterns.
+
+### 5) Implement update action building
+- `build-action` returns a combined action with:
+  - `:type :update-block`
+  - `:id`/`:uuid` for source, optional target selectors, `:pos` default `first-child` when move is requested
+  - `:update-tags`, `:update-properties`, `:remove-tags`, `:remove-properties`
+- `execute-update`:
+  - Resolve source; resolve target only when move is requested.
+  - Build a vector of outliner ops, in order: move (if present), then remove tags/properties, then update/add tags/properties (order can be adjusted if needed for predictable results).
+  - Use `:thread-api/apply-outliner-ops` once with all ops.
+
+### 6) Update output formatting
+- `src/main/logseq/cli/format.cljs`:
+  - Add `format-update-block` to describe move + updates in a concise line.
+  - Update dispatcher to handle `:update-block`.
+
+### 7) Tests
+- Unit tests in `src/test/logseq/cli/commands_test.cljs`:
+  - Parsing: `update` accepts `--id/--uuid`, optional target, and new options.
+  - Validation: missing source, invalid target selector combinations, invalid pos, invalid EDN options.
+  - Ensure that `update` without target but with update/remove options is accepted.
+- Format tests in `src/test/logseq/cli/format_test.cljs` for `:update-block`.
+- Integration tests in `src/test/logseq/cli/integration_test.cljs`:
+  - Move-only update should behave the same as current `move`.
+  - Update tags/properties on an existing block.
+  - Remove tags/properties and validate via `show` or query.
+
+## Open Questions
+- If only `--pos` is provided without any target selector, return the error: `--pos is only valid when a target is provided`.
+
+## Risks / Edge Cases
+- If tag/property parsing rules diverge from `add`, user experience becomes inconsistent. Refactor shared parsing to avoid drift.
+- Combining move and property updates in one `apply-outliner-ops` call needs to preserve correct operation order; keep move first unless property updates depend on position.
+- Ensure non-page validation for source and block target remains intact when refactoring.
+
+## Implementation Checklist (Concrete File Touches)
+- Add: `src/main/logseq/cli/command/update.cljs`.
+- Update: `src/main/logseq/cli/commands.cljs` (table, validation, action dispatch).
+- Update: `src/main/logseq/cli/command/core.cljs` (top-level summary group list to include update).
+- Update: `src/main/logseq/cli/format.cljs` (formatting for update).
+- Update: `src/test/logseq/cli/commands_test.cljs`.
+- Update: `src/test/logseq/cli/format_test.cljs`.
+- Update: `src/test/logseq/cli/integration_test.cljs`.
+
+## Verification
+- Run unit tests: `bb dev:test -v logseq.cli.commands-test`.
+- Run format tests: `bb dev:test -v logseq.cli.format-test`.
+- Run CLI integration tests (move/update subset): `bb dev:test -v logseq.cli.integration-test`.
+- Optional full suite: `bb dev:lint-and-test`.
diff --git a/docs/agent-guide/028-logseq-cli-verbose-debug.md b/docs/agent-guide/028-logseq-cli-verbose-debug.md
new file mode 100644
index 0000000000..ff4b1b867f
--- /dev/null
+++ b/docs/agent-guide/028-logseq-cli-verbose-debug.md
@@ -0,0 +1,74 @@
+# Logseq CLI Verbose Debug Logging Implementation Plan
+
+Goal: Add a global --verbose flag that enables structured debug logging for CLI options and all db-worker-node API calls without polluting normal command output.
+
+Architecture: The CLI will install a stderr log handler and enable debug level logging when --verbose is set.
+Architecture: The CLI transport and db-worker-node lifecycle utilities will emit structured debug logs for each request and response, using a shared truncation helper to cap large payloads.
+Architecture: The db-worker-node process log level remains unchanged, and --verbose only controls logseq-cli logging.
+
+Tech Stack: ClojureScript, lambdaisland.glogi, Node.js, db-worker-node HTTP API.
+
+Related: Relates to docs/agent-guide/005-logseq-cli-output-and-db-worker-node-log.md.
+
+## Problem statement
+
+The CLI currently has no verbose debug mode for troubleshooting, so engineers cannot easily see which options were parsed or what db-worker-node API calls were made.
+This makes it hard to diagnose failures, especially when db-worker-node responses are large and need safe, truncated logging.
+The goal is to add a global --verbose option that emits debug logs for command options and db-worker-node API calls without breaking existing output contracts.
+
+## Testing Plan
+
+I will add a unit test that verifies the log truncation helper returns a preview with a stable maximum length and a flag indicating truncation.
+I will add a unit test that verifies the log truncation helper handles strings, collections, and nil without throwing.
+I will add a unit test that verifies the CLI debug logger emits records only when verbose is enabled by capturing glogi records via a temporary handler.
+I will add an integration test that runs the CLI with --verbose and asserts that stderr contains a db-worker-node invoke debug line while stdout remains valid JSON for a simple command.
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Logging coverage
+
+| Area | File path | Log events | Notes |
+| --- | --- | --- | --- |
+| CLI option intake | src/main/logseq/cli/main.cljs | Parsed options and resolved config values | Use truncation for long option values like content or blocks. |
+| db-worker-node invoke | src/main/logseq/cli/transport.cljs | Request and response debug logs with timing | Truncate response preview and include size metadata. |
+| db-worker-node health checks | src/main/logseq/cli/server.cljs | /healthz, /readyz, /v1/shutdown debug logs | Keep quiet unless verbose is true. |
+| db-worker-node server logs | src/main/frontend/worker/db_worker_node.cljs | Keep existing logging behavior unchanged. | --verbose does not affect db-worker-node. |
+
+## Implementation Plan
+
+1. Read @prompts/review.md and note any CLI and db-worker-node review checklist items that affect logging or output stability.
+2. Add :verbose to the CLI global option spec in src/main/logseq/cli/command/core.cljs with a description and boolean coercion so it appears in help output.
+3. Add a new logging helper namespace in src/main/logseq/cli/log.cljs that sets a stderr handler, toggles log levels, and exposes a truncate-preview helper that caps output length and records the original size.
+4. Add unit tests for the new logging helper in src/test/logseq/cli/log_test.cljs to cover truncation behavior and the verbose gating behavior using a temporary glogi handler.
+5. Initialize CLI logging in src/main/logseq/cli/main.cljs after resolving config so --verbose turns on debug level and installs the handler once per run.
+6. Emit a debug log in src/main/logseq/cli/main.cljs that includes the command, args, and full options map from the parsed command, using the truncation helper for large values.
+7. Add request and response debug logs in src/main/logseq/cli/transport.cljs around invoke, including method, directPass, args preview, response preview, response size, and elapsed time.
+8. Add request and response debug logs in src/main/logseq/cli/server.cljs for db-worker-node HTTP calls, and ensure logs are emitted only when --verbose is set.
+9. Confirm no changes are made to src/main/frontend/worker/db_worker_node.cljs behavior or log levels for this feature.
+10. Add an integration test in src/test/logseq/cli/integration_test.cljs to ensure stdout remains valid JSON when verbose logs are emitted to stderr.
+11. Update docs/cli/logseq-cli.md to document the new --verbose flag, that it only affects logseq-cli, and that debug logs go to stderr with large payloads truncated.
+
+## Edge Cases
+
+Large query or export results can exceed the preview limit, so logs must include a length field and a truncated preview instead of full payloads.
+CLI commands that output JSON or EDN must keep stdout clean, so debug logs must go to stderr only.
+Options that contain large text content or EDN blocks must be truncated in logs to avoid massive log lines.
+db-worker-node can be started independently, so its debug logs should still be gated by its log-level flag even when the CLI is not involved.
+
+## Testing Details
+
+Tests will validate that debug logging is gated by --verbose, that truncation is applied consistently, and that stdout output remains parseable while stderr contains debug logs for a simple db-worker-node invocation.
+
+## Implementation Details
+
+- Use lambdaisland.glogi for CLI logging so log-level control is consistent with db-worker-node.
+- Install a stderr log handler in the CLI to avoid polluting stdout output formats.
+- Truncate previews by character count and include metadata such as original length and truncation flag.
+- Log db-worker-node invoke timings so slow calls are visible in verbose mode.
+- Keep db-worker-node API behavior and log levels unchanged.
+- Ensure all verbose logs are emitted by logseq-cli only.
+
+## Question
+
+None.
+
+---
diff --git a/docs/agent-guide/029-logseq-cli-show-properties.md b/docs/agent-guide/029-logseq-cli-show-properties.md
new file mode 100644
index 0000000000..d4da572d5b
--- /dev/null
+++ b/docs/agent-guide/029-logseq-cli-show-properties.md
@@ -0,0 +1,150 @@
+# Logseq CLI Show Properties Implementation Plan
+
+Goal: Display block properties in the human-readable output of the logseq-cli show command.
+
+Architecture: Extend the show command pull selectors to include property data from db-worker-node, then enrich tree->text to append formatted property lines per block.
+Architecture: Keep JSON and EDN outputs structurally the same, while only altering the human text renderer to include properties beneath each block label.
+
+Tech Stack: ClojureScript, Datascript pull selectors, logseq-cli, db-worker-node thread-api.
+
+Related: Builds on 028-logseq-cli-verbose-debug.md.
+
+## Problem statement
+
+The logseq-cli show command currently renders block trees without any property visibility.
+Users need to see each block's properties directly under the block content in the human output so that show reflects the same metadata they rely on in the UI.
+Property lines belong to the same block tree element, so they must render with the same tree glyphs and indentation rules used for multiline block content (no blank space-only prefix).
+The display must show "<property-name>: <property-value>" and must handle single-value properties as a single line and multi-value properties as an indented list as shown in the example.
+
+## Testing Plan
+
+I will add a unit test that asserts tree->text renders single-value properties in one line after the block content.
+I will add a unit test that asserts tree->text renders multi-value properties as a dash list aligned under the property name.
+I will add a unit test that asserts user property order follows a stable key order.
+I will add a unit test that asserts properties do not break multiline block alignment for both root and child blocks.
+I will add a unit test that asserts property values only appear in property-kvs and never in block/children.
+I will update selector coverage tests to assert property selectors are included in show pulls.
+I will add an integration test that asserts show output includes property lines.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Context and integration points
+
+The show command data path is: CLI action -> transport/invoke -> db-worker-node -> pull/query -> tree data -> tree->text human rendering.
+The pull selectors in logseq.cli.command.show define what properties are available to tree->text.
+User properties are stored directly on block entities with keys in the :user.property/* namespace.
+
+ASCII diagram of the flow:
+
+CLI show
+  |
+  |  transport/invoke :thread-api/pull / :thread-api/q
+  v
+DB worker node
+  |
+  |  returns tree data with block maps
+  v
+logseq.cli.command.show/tree->text
+  |
+  |  renders block label + property lines
+  v
+stdout
+
+## Files to touch
+
+| File path | Purpose |
+| --- | --- |
+| src/main/logseq/cli/command/show.cljs | Add property selectors, build property lines, and render properties in tree->text. |
+| src/test/logseq/cli/commands_test.cljs | Add tree->text unit tests for property rendering and selector coverage. |
+| src/test/logseq/cli/integration_test.cljs | Add integration coverage for show property rendering output. |
+
+## Implementation plan (TDD-ordered)
+
+1. Read @prompts/review.md to align with review expectations.
+2. Add failing unit tests for tree->text:
+   - single-value property rendering
+   - multi-value property rendering with dash list formatting + alignment
+   - user property ordering
+   - multiline alignment with properties
+3. Add failing selector coverage test asserting show pull patterns include property selectors.
+4. Add failing integration test asserting show output includes property lines.
+5. Run each new test and confirm failures reference missing property behavior (not test errors).
+6. Update show pull selectors in src/main/logseq/cli/command/show.cljs to include :user.property/* attributes so db-worker-node returns needed data.
+7. Add helpers in src/main/logseq/cli/command/show.cljs to:
+   - collect and sort user property keys
+   - normalize user property values into a vector of display strings
+   - format property lines for single vs multi values
+8. Extend tree->text in src/main/logseq/cli/command/show.cljs to append property lines after block label lines, preserving indentation rules and no tree glyphs.
+9. Re-run unit tests and selector test; confirm they pass.
+10. Re-run integration test; confirm it passes.
+11. Run `bb dev:lint-and-test` and confirm all linters and tests pass.
+
+## Edge cases to handle
+
+User properties with empty values should be skipped to avoid blank lines in the output.
+User properties with values that are sets, vectors, or lists should render each item as a separate dash line.
+User properties with values that are entities or maps should render as :block/title, :block/name, or :logseq.property/value when present.
+User properties must be detected only via the :user.property/* namespace and no other property sources should be displayed.
+Blocks without properties should render exactly as they do today.
+Linked references output should include properties for each block without breaking the existing tree formatting.
+Property lines should include the same tree glyphs/branch markers used for multiline block content so they align with block text.
+
+## Implementation details for formatting
+
+Use a stable sort order for :user.property/* keys, such as ascending by keyword name.
+Do not use :block/properties-text-values for db-graph output.
+Format user property values from :user.property/* attributes and coerce values into strings using :block/title, :block/name, or :logseq.property/value.
+Render single values as "Property: value" and multi values as "Property: - v1" with subsequent lines aligned under the dash list.
+Align property lines with the block content column and reuse the same tree glyph indentation rules used for multiline block content.
+
+## Questions
+
+Properties should display using their :block/title for the property name, derived from the property entity when available, and never fall back to :db/ident.
+Hidden or internal properties must be filtered out to avoid noise in CLI output.
+Tags must render as #tags only and must not be listed as properties.
+:block/properties-text-values is file-graph only and should be ignored for db-graph output.
+
+## Testing Details
+
+The new tests will directly exercise tree->text with synthetic tree data that includes :user.property/* attributes to ensure the human output matches the requested format.
+The new tests will assert property values are only present in property-kvs and do not appear in block/children output.
+The selector test will validate that the show pull patterns include property attributes so db-worker-node can provide the necessary data.
+These tests verify output behavior, ordering, and indentation rather than internal helper logic.
+The integration test will validate that show output includes property lines end-to-end.
+
+## Implementation Details
+
+- Update tree-block-selector and linked-ref-selector to pull :user.property/* attributes.
+- Update the id and uuid fetch pull patterns to include the same property fields.
+- Add a property normalization helper that returns ordered [key values] pairs.
+- Add a value formatting helper that converts each property value into displayable strings.
+- Extend tree->text to append property lines after block content lines for both root and child nodes.
+- Keep JSON and EDN outputs intact aside from the additional property keys pulled from the db.
+- Property values should only appear in property-kvs; do not surface property values in block/children.
+- Add new unit tests for single-value, multi-value, ordering, and multiline alignment cases.
+- Add a selector test that asserts property selectors are included.
+
+## Example output
+
+Current:
+```
+5137 Done Add git sha when graph is created for improved debugging #Issue
+5138 ├── Motivated by wanting to ensure missing addresses bug isn't happening in new graphs - https://logseq.slack.com/archives/C04ENNDPDFB/p1748290483138269
+5139 ├── When a DB graph is created in app, store git SHA used to create it in entity :logseq.kv/graph-git-sha
+5140 └── When a DB graph is created with a script, store git SHA used to create it in entity :logseq.kv/graph-git-sha
+```
+
+Target:
+```
+5137 Done Add git sha when graph is created for improved debugging #Issue
+     │   Background: Motivated by wanting to ensure missing addresses bug isn't happening in new graphs - https://logseq.slack.com/archives/C04ENNDPDFB/p1748290483138269
+     │   Acceptance Criteria:
+     │     - When a DB graph is created in app, store git SHA used to create it in entity :logseq.kv/graph-git-sha
+     │     - When a DB graph is created with a script, store git SHA used to create it in entity :logseq.kv/graph-git-sha
+```
+
+## Question
+
+JSON and EDN outputs must include property values alongside the existing data.
+
+---
diff --git a/docs/agent-guide/030-logseq-cli-db-graph-default-dir-locking.md b/docs/agent-guide/030-logseq-cli-db-graph-default-dir-locking.md
new file mode 100644
index 0000000000..1384d26901
--- /dev/null
+++ b/docs/agent-guide/030-logseq-cli-db-graph-default-dir-locking.md
@@ -0,0 +1,191 @@
+# Logseq CLI DB Graph Default Dir And Write Exclusion Implementation Plan
+
+Goal: Move the default CLI data directory to `~/logseq/graphs`, store graph directories without requiring the `logseq_db_` prefix, and enforce single-writer behavior for graph files while one db-worker-node instance owns a graph.
+
+Architecture: Keep `logseq_db_` as the internal repo identifier used by thread-api calls, but introduce a canonical graph directory key that strips the db prefix for filesystem paths.
+Architecture: Centralize graph directory resolution and lock ownership checks so `logseq.cli.server`, `frontend.worker.db-worker-node-lock`, and `frontend.worker.platform.node` enforce the same rules.
+
+Tech Stack: ClojureScript, Node.js `fs` and `path`, promesa, logseq-cli command pipeline, db-worker-node daemon, existing lock file protocol.
+
+Related: Builds on `docs/agent-guide/019-logseq-cli-data-dir-permissions.md`.
+Related: Supersedes `docs/agent-guide/020-logseq-cli-default-paths-move.md`.
+Related: Relates to `docs/agent-guide/012-logseq-cli-graph-storage.md`.
+
+## Problem statement
+
+The current CLI default data directory is `~/logseq/cli-graphs`, while this change requires `~/logseq/graphs`.
+
+The current filesystem directory naming for a graph is based on repo identifiers that frequently include `logseq_db_`, so users still observe prefixed names in the data directory.
+
+The current lock model prevents launching a second db-worker-node for one repo, but it does not define an explicit write-lease boundary that all graph file mutations must validate before writing.
+
+We need one coherent model where graph directories are user-facing names, internal repo identifiers stay db-prefixed for thread-api compatibility, and graph writes are denied for non-owners while a server is running.
+
+This plan does not include compatibility logic, migration, or special handling for old on-disk graph directories that start with `logseq_db_`.
+
+This plan treats old on-disk `logseq_db_` prefixed graph directories as ignored entries.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and add all failing tests before implementation edits.
+
+I will add unit tests for default path resolution and help text defaults in CLI and db-worker-node code paths.
+
+I will add unit tests for graph directory canonicalization that prove `logseq_db_demo` resolves to the same on-disk directory as `demo` in the default data directory.
+
+I will not add migration tests for old prefixed directories because compatibility and migration are out of scope for this change.
+
+I will add db-worker-node tests that validate write-lease ownership checks fail for non-owner lock metadata and pass for the active owner.
+
+I will run targeted test namespaces first for fast red and green loops, then run the full lint and test suite.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current behavior map
+
+| Area | Current implementation | Required change |
+|---|---|---|
+| Default data dir | `~/logseq/cli-graphs` in CLI and db-worker-node defaults. | `~/logseq/graphs` in all default derivation and help output locations. |
+| Graph dir naming | Graph directory derivation commonly receives repo values that include `logseq_db_`. | Graph directory derivation must use canonical graph names without requiring `logseq_db_`. |
+| Graph type assumption | DB graph identity is inferred from repo prefix in several paths. | In default data dir, treat every graph directory as a db graph and map to internal repo with prefix only at invocation boundaries. |
+| Write exclusivity | `db-worker.lock` blocks duplicate daemon start, but write ownership is not verified by all mutation paths. | Introduce write-lease ownership checks for all graph file mutation operations executed by db-worker-node. |
+
+## Integration sketch
+
+```text
+CLI --graph demo
+  -> command-core resolves internal repo: logseq_db_demo
+  -> graph-dir resolver maps repo to graph key: demo
+  -> fs paths use ~/logseq/graphs/demo
+  -> thread-api calls still use logseq_db_demo
+
+db-worker-node owner lease
+  -> creates db-worker.lock with pid + lock-id
+  -> mutation path checks lock-id + pid ownership
+  -> non-owner mutation attempt returns :repo-locked
+```
+
+## Implementation plan
+
+### Phase 1: Add failing tests for path defaults and naming.
+
+1. Add a failing assertion in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/config_test.cljs` that `resolve-config` defaults `:data-dir` to `~/logseq/graphs`.
+2. Add a failing assertion in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/data_dir_test.cljs` that `normalize-data-dir` resolves to `$HOME/logseq/graphs`.
+3. Add a failing assertion in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that `show-help!` prints `default ~/logseq/graphs` for `--data-dir`.
+4. Add a failing assertion in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that global help includes `Path to db-worker data dir (default ~/logseq/graphs)`.
+5. Run `bb dev:test -v 'logseq.cli.config-test'` and confirm the new default path assertion fails.
+6. Run `bb dev:test -v 'logseq.cli.data-dir-test'` and confirm the new default path assertion fails.
+
+### Phase 2: Add failing tests for prefix-free graph directory semantics.
+
+7. Add a new test namespace `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_lock_test.cljs` that asserts repo `logseq_db_demo` resolves to graph directory key `demo` under default data dir.
+8. Add a second test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_lock_test.cljs` that repo `demo` also resolves to graph directory key `demo`.
+9. Add a test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_lock_test.cljs` that verifies no migration helper is invoked for legacy prefixed on-disk graph directories.
+10. Add a test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_lock_test.cljs` that canonical directory resolution only targets `<graph>` naming in the default data dir.
+11. Add a failing CLI server test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` that `lock-path` for repo `logseq_db_demo` points to `<data-dir>/demo/db-worker.lock`.
+12. Run `bb dev:test -v 'frontend.worker.db-worker-node-lock-test'` and confirm failures for unimplemented canonicalization and non-migration logic.
+13. Run `bb dev:test -v 'logseq.cli.server-test'` and confirm lock-path behavior fails before implementation.
+
+### Phase 3: Add failing tests for write-lease ownership.
+
+14. Add a test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that simulates lock metadata mismatch and expects write mutation to fail with `:repo-locked`.
+15. Add a test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that verifies owner write mutation succeeds when lock metadata matches current owner.
+16. Add a test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that stale lock ownership is rejected after lock replacement.
+17. Run `bb dev:test -v 'frontend.worker.db-worker-node-test'` and confirm the write-lease tests fail before implementation.
+
+### Phase 4: Implement default directory switch to `~/logseq/graphs`.
+
+18. Update default path constants in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/data_dir.cljs` from `~/logseq/cli-graphs` to `~/logseq/graphs`.
+19. Update CLI config defaults in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/config.cljs` so `:data-dir` defaults to `~/logseq/graphs`.
+20. Update server fallback in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` so `resolve-data-dir` defaults to `~/logseq/graphs`.
+21. Update db-worker-node default path in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node_lock.cljs` so `resolve-data-dir` defaults to `~/logseq/graphs`.
+22. Update node platform fallback in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs` so `node-platform` defaults to `~/logseq/graphs`.
+23. Update CLI help text in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` to show `~/logseq/graphs`.
+24. Re-run `bb dev:test -v 'logseq.cli.config-test'` and `bb dev:test -v 'logseq.cli.data-dir-test'` and confirm green results.
+
+### Phase 5: Implement canonical graph directory resolution without required `logseq_db_` prefix.
+
+25. Add shared graph directory canonicalization helpers in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node_lock.cljs` to map internal repo names to canonical graph directory keys.
+26. Ensure canonicalization strips `logseq_db_` only when the repo is a db repo and preserves encoded filename safety through existing `encode-graph-dir-name` helpers.
+27. Explicitly avoid adding legacy directory migration logic from `logseq_db_<graph>` to `<graph>` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node_lock.cljs`.
+28. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` to use canonical graph directory resolution for `repo-dir`, `lock-path`, and graph enumeration.
+29. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs` to use canonical graph directory keys in `storage-pool-name` and `db-exists?` path resolution for node runtime.
+30. Re-run `bb dev:test -v 'frontend.worker.db-worker-node-lock-test'` and `bb dev:test -v 'logseq.cli.server-test'` and confirm canonical naming tests pass without migration behavior.
+
+### Phase 6: Implement write-lease ownership checks for graph file mutations.
+
+32. Extend lock payload in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node_lock.cljs` with a generated `lock-id` and keep ownership fields immutable after acquisition.
+33. Add `assert-lock-owner!` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node_lock.cljs` that validates lock existence, pid ownership, and `lock-id` match before mutation.
+34. Pass a write-guard callback from `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` into `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs`.
+35. Invoke the write-guard callback before every graph file mutation path in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs`, including sqlite import, text writes, and recursive delete paths.
+36. Return consistent `:repo-locked` errors from ownership failures and ensure CLI formatting remains readable through `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`.
+37. Re-run `bb dev:test -v 'frontend.worker.db-worker-node-test'` and confirm ownership tests pass.
+
+### Phase 7: Update docs and run full verification.
+
+38. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` for the new default data dir and for prefix-free on-disk graph directory naming.
+39. Add a breaking-change note in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` stating old on-disk prefixed graph directories are not automatically migrated.
+40. Re-run `bb dev:test -v 'logseq.cli.commands-test'` and `bb dev:test -v 'logseq.cli.main-test'` to verify help text and command behavior coverage.
+41. Run `bb dev:lint-and-test` and confirm the suite passes with no regressions.
+42. Review changed code against `@prompts/review.md` to catch Clojure and ClojureScript correctness pitfalls before merge.
+
+## Edge cases to cover
+
+| Scenario | Expected behavior |
+|---|---|
+| Graph name contains `/`, `:`, `%`, or unicode. | Directory naming remains reversible through encode and decode helpers. |
+| Legacy on-disk directory `logseq_db_demo` exists. | No compatibility or migration is performed by this change, and discovery commands ignore this directory. |
+| Lock file is stale with dead pid. | Startup removes stale lock and acquires a fresh lease. |
+| Lock file exists with alive non-owner pid. | Startup and direct mutation fail fast with `:repo-locked`. |
+| Default data dir has non-graph directories. | Enumeration ignores directories that are not valid graph directories after canonicalization checks. |
+
+## Verification commands and expected outputs
+
+```bash
+bb dev:test -v 'logseq.cli.config-test'
+bb dev:test -v 'logseq.cli.data-dir-test'
+bb dev:test -v 'logseq.cli.server-test'
+bb dev:test -v 'frontend.worker.db-worker-node-lock-test'
+bb dev:test -v 'frontend.worker.db-worker-node-test'
+bb dev:test -v 'logseq.cli.commands-test'
+bb dev:lint-and-test
+```
+
+Each command should finish with zero failures and zero errors.
+
+If a red phase command is run before implementation, it should fail specifically on the newly added assertions in that phase.
+
+## Testing Details
+
+The tests validate behavior through public CLI and daemon entrypoints instead of validating only implementation internals.
+
+The naming tests prove that internal db repo prefixes remain stable while on-disk names are canonicalized for user-facing graph directories.
+
+The ownership tests verify that only the active lock owner can execute graph file mutation paths in db-worker-node.
+
+The tests intentionally avoid migration coverage because compatibility with old prefixed on-disk graph directories is out of scope.
+
+## Implementation Details
+
+- Keep internal repo values db-prefixed for thread-api compatibility and db metadata reads.
+- Use canonical graph directory keys for all on-disk path construction in node runtime.
+- Do not add compatibility branches or migration logic for old `logseq_db_` prefixed on-disk graph directories.
+- Ignore old `logseq_db_` prefixed on-disk graph directories during graph discovery and server listing.
+- Add lock ownership token fields and verify ownership before each graph mutation path.
+- Enforce ownership checks for all files under a graph directory, including sqlite files, search and client-op files, debug logs, backups, and text files.
+- Keep error code semantics stable by reusing `:repo-locked` for ownership and lock conflicts.
+- Keep lock-conflict error semantics unified across CLI and db-worker-node as `:repo-locked`.
+- Update all default data-dir strings and help text to `~/logseq/graphs`.
+- Keep CLI output graph names user-facing and prefix-free.
+- Update docs with a breaking-change note for old prefixed on-disk graph directories.
+- Follow `@test-driven-development` and `@prompts/review.md` through implementation and verification.
+
+## Question
+
+Resolved decisions:
+
+1. Ignore old on-disk `logseq_db_` prefixed graph directories.
+2. Requirement three covers all files under the graph directory.
+3. Lock conflicts and ownership failures use unified error code `:repo-locked`.
+
+---
diff --git a/docs/agent-guide/031-logseq-cli-doctor-command.md b/docs/agent-guide/031-logseq-cli-doctor-command.md
new file mode 100644
index 0000000000..4a2872cd3b
--- /dev/null
+++ b/docs/agent-guide/031-logseq-cli-doctor-command.md
@@ -0,0 +1,183 @@
+# Logseq CLI Doctor Command Implementation Plan
+
+Goal: Add a `doctor` command that verifies logseq-cli runtime availability before normal command execution, including `db-worker-node.js` existence and `data-dir` read and write readiness.
+
+Architecture: Add a dedicated `logseq.cli.command.doctor` namespace and wire it into the existing `parse-args` -> `build-action` -> `execute` pipeline in `logseq.cli.commands`.
+Architecture: Reuse existing helpers in `logseq.cli.data-dir` and `logseq.cli.server` for permission checks and daemon liveness probes, then return one structured diagnostics report.
+
+Tech Stack: ClojureScript, babashka.cli command table, Node.js `fs` and `path`, Promesa, existing CLI formatter and test harness.
+
+Related: Builds on `docs/agent-guide/019-logseq-cli-data-dir-permissions.md`.
+Related: Relates to `docs/agent-guide/015-logseq-cli-db-worker-node-housekeeping.md`.
+Related: Relates to `docs/agent-guide/017-logseq-cli-db-worker-node-housekeeping-2.md`.
+Related: Relates to `docs/agent-guide/030-logseq-cli-db-graph-default-dir-locking.md`.
+
+## Problem statement
+
+The current CLI fails only when a concrete command touches startup paths, so users discover environment problems late.
+
+We need a fast explicit health command that confirms whether logseq-cli can run reliably in the current machine context.
+
+The minimum required checks are the presence of `db-worker-node.js` and read and write access for `data-dir`.
+
+Note: `dist/db-worker-node.js` is a thin entry wrapper that loads `static/db-worker-node.js`. Doctor should validate the actual runtime target in `static/` rather than only the `dist/` wrapper.
+
+We should also surface practical runtime risks already modeled by current code, especially stale or unready db-worker instances discovered from lock files and health endpoints.
+
+This plan keeps scope to diagnostics and does not change daemon lifecycle semantics, lock protocol, or graph migration behavior.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and write all failing tests before adding implementation behavior.
+
+I will add parser and action-dispatch tests for `doctor` in `commands_test` so command discovery and help output are guarded.
+
+I will add dedicated `doctor` command tests that cover success, missing script file, and `data-dir` permission failure behavior.
+
+I will add `format` tests to ensure human and machine-readable output for `doctor` are stable and useful.
+
+I will run focused test namespaces first to validate RED and GREEN transitions, then run the full lint and test suite.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current behavior map
+
+| Area | Current implementation | Required change |
+|---|---|---|
+| Runtime script path | `spawn-server!` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` starts `../dist/db-worker-node.js`, which delegates to `../static/db-worker-node.js`, but no explicit diagnostic command validates that runtime target path readiness. | Add `doctor` check that validates the effective script file existence and readability before startup commands fail. |
+| Data-dir readiness | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/data_dir.cljs` enforces directory creation and read or write access in `ensure-data-dir!`. | Reuse `ensure-data-dir!` inside `doctor` and report a dedicated failing check item. |
+| Daemon liveness visibility | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` has `list-servers`, `server-status`, `ready?`, and `healthy?`, but no consolidated health summary command. | Add optional runtime checks in `doctor` that flag non-ready running servers discovered from lock files. |
+| CLI discoverability | Top-level help and command table in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` do not include diagnostics entrypoint. | Add `doctor` to command entries and help summaries. |
+
+## Proposed doctor checks
+
+| Check id | Behavior | Existing helper to reuse | Failure signal |
+|---|---|---|---|
+| `db-worker-script` | Verify `../static/db-worker-node.js` exists and is readable as a file (and optionally verify `../dist/db-worker-node.js` wrapper exists). | New shared path helper in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` plus Node `fs` checks in doctor command. | `:doctor-script-missing` or `:doctor-script-unreadable`. |
+| `data-dir` | Verify configured or default data dir can be created and is read and write accessible. | `logseq.cli.data-dir/ensure-data-dir!` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/data_dir.cljs`. | Existing `:data-dir-permission` surfaced as doctor failure detail. |
+| `running-servers` | Verify currently locked db-worker instances are reachable on readiness endpoint. | `logseq.cli.server/list-servers` status derivation in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs`. | `:doctor-server-not-ready` for any server reported as `:starting`. |
+
+## Integration sketch
+
+```text
+logseq doctor
+  -> parse-args (commands table)
+  -> build-action {:type :doctor}
+  -> execute-doctor
+       1) check effective db-worker-node.js runtime path (`static/db-worker-node.js`).
+       2) check data-dir accessibility.
+       3) inspect running server readiness.
+  -> format result for human/json/edn.
+```
+
+## Implementation plan
+
+### Phase 1: RED for command plumbing.
+
+1. Add failing assertions in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that top-level help includes `doctor` and bold-styled `doctor` command text.
+2. Add a failing parse test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `commands/parse-args ["doctor"]` returning `:ok? true` with command `:doctor`.
+3. Add a failing build-action test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `{:command :doctor}` producing action type `:doctor`.
+4. Run `bb dev:test -v 'logseq.cli.commands-test'` and confirm failures are specifically on new doctor assertions.
+
+### Phase 2: RED for doctor behavior.
+
+5. Create `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/doctor_test.cljs` with namespace and fixtures consistent with existing command tests.
+6. Add a failing test that marks script check as failed when `static/db-worker-node.js` path does not exist.
+7. Add a failing test that marks data-dir check as failed when `ensure-data-dir!` throws `:data-dir-permission`.
+8. Add a failing test that returns all checks passed when script and data-dir are both valid and no running server is unready.
+9. Add a failing test that reports runtime warning or failure when `list-servers` includes entries with status `:starting`.
+10. Run `bb dev:test -v 'logseq.cli.command.doctor-test'` and confirm all new tests fail for expected reasons.
+
+### Phase 3: GREEN for command integration.
+
+11. Add `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/doctor.cljs` with `entries`, `build-action`, and `execute-doctor` returning structured check results.
+12. Wire doctor namespace into `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` requires and append `doctor-command/entries` into `table`.
+13. Add `:doctor` branch in `build-action` inside `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+14. Add `:doctor` branch in `execute` inside `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+15. Update top-level command grouping in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` to show `doctor` in help output.
+16. Run `bb dev:test -v 'logseq.cli.commands-test'` and confirm doctor parse and help tests are green.
+
+### Phase 4: GREEN for doctor checks.
+
+17. Extract or add a shared db-worker script path helper in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` so spawn and doctor share one source of truth.
+18. Implement script existence and readability check in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/doctor.cljs` using Node `fs` metadata checks.
+19. Implement data-dir check in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/doctor.cljs` by invoking `logseq.cli.data-dir/ensure-data-dir!`.
+20. Implement running-server readiness check in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/doctor.cljs` using `logseq.cli.server/list-servers`.
+21. Return deterministic check ordering and include actionable message per check in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/doctor.cljs`.
+22. Re-run `bb dev:test -v 'logseq.cli.command.doctor-test'` and confirm all doctor behavior tests are green.
+
+### Phase 5: RED and GREEN for formatting and docs.
+
+23. Add failing output tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for human summary rendering of doctor checks.
+24. Add failing output tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for json and edn output preserving structured check payload.
+25. Implement doctor-specific human formatter in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`.
+26. Ensure `doctor` output includes overall status and per-check status in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`.
+27. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` with `doctor` command description, examples, and expected failure hints.
+28. Run `bb dev:test -v 'logseq.cli.format-test'` and confirm new doctor formatting tests are green.
+
+### Phase 6: Verify RED to GREEN cycle completion, refactor, and full validation.
+
+29. Run `bb dev:test -v 'logseq.cli.commands-test'` and ensure no regressions in help parsing and action dispatch.
+30. Run `bb dev:test -v 'logseq.cli.command.doctor-test'` and ensure all doctor checks are behavior-driven and stable.
+31. Run `bb dev:test -v 'logseq.cli.main-test'` to confirm entrypoint behavior remains compatible.
+32. Run `bb dev:test -v 'logseq.cli.server-test'` to verify shared script path changes do not break server startup assumptions.
+33. Run `bb dev:test -v 'logseq.cli.format-test'` to validate output contracts.
+34. Run `bb dev:lint-and-test` and confirm zero failures and zero errors.
+35. Review changed code against `@prompts/review.md` before merge.
+
+## Edge cases to cover
+
+| Scenario | Expected behavior |
+|---|---|
+| `static/db-worker-node.js` path exists but points to a directory. | `doctor` reports script check failure with explicit path and reason. |
+| `data-dir` path points to a file. | `doctor` fails with `:data-dir-permission` detail and does not continue to misleading pass status. |
+| `data-dir` is readable but not writable. | `doctor` fails data-dir check and returns actionable permission hint. |
+| Running server lock exists but `/readyz` is not healthy. | `doctor` reports runtime check as failed for that repo. |
+| No running server exists. | Runtime server check passes with empty server list and does not force daemon startup. |
+| `--output json` is used. | Doctor returns stable machine-readable check list for scripts and automation. |
+
+## Verification commands and expected outputs
+
+```bash
+bb dev:test -v 'logseq.cli.commands-test'
+bb dev:test -v 'logseq.cli.command.doctor-test'
+bb dev:test -v 'logseq.cli.server-test'
+bb dev:test -v 'logseq.cli.format-test'
+bb dev:test -v 'logseq.cli.main-test'
+bb dev:lint-and-test
+```
+
+Each command should finish with zero failures and zero errors in GREEN phase.
+
+Each RED phase run should fail on newly added doctor assertions and not on unrelated setup errors.
+
+## Testing Details
+
+The tests focus on command behavior and diagnostics outcomes through public parser and executor boundaries.
+
+The tests avoid implementation-detail assertions and instead validate user-observable results for success and failure cases.
+
+The formatter tests ensure the same doctor payload is usable for both human troubleshooting and automation output modes.
+
+## Implementation Details
+
+- Keep `doctor` as a first-class command in the existing CLI command table.
+- Reuse `ensure-data-dir!` instead of reimplementing permission checks.
+- Reuse server health status discovery through existing `list-servers` behavior.
+- Keep check execution deterministic and output stable for CI parsing.
+- Keep command scope read-only for diagnostics and avoid auto-remediation side effects.
+- Return explicit error codes for script and runtime health failures.
+- Preserve current graph and repo naming semantics and lock protocol behavior.
+- Add targeted formatter support so human output is concise and actionable.
+- Verify all changes via focused tests before full lint and test pass.
+- Follow `@test-driven-development` and `@prompts/review.md` throughout implementation.
+
+## Question
+
+Resolved: `doctor` will fail fast on the first failed check.
+
+Resolved: `doctor` will treat `:starting` servers as warnings when script and data-dir checks pass.
+
+Resolved: `doctor` will support a future `--graph` scoped deep check that verifies per-graph lock path and repo directory access without starting the daemon.
+
+---
diff --git a/docs/agent-guide/032-logseq-cli-show-property-key-bold.md b/docs/agent-guide/032-logseq-cli-show-property-key-bold.md
new file mode 100644
index 0000000000..703f9a84d5
--- /dev/null
+++ b/docs/agent-guide/032-logseq-cli-show-property-key-bold.md
@@ -0,0 +1,119 @@
+# Logseq CLI Show Property Key Bold Implementation Plan
+
+Goal: Make `<property-key>` render in bold in `show` human output while keeping the existing `property-kvs` layout and values unchanged.
+
+Architecture: Keep db-worker-node data fetching and property title resolution unchanged, and only add styling at the final text rendering layer in `logseq.cli.command.show`.
+
+Tech Stack: ClojureScript, logseq-cli show renderer, db-worker-node transport/thread-api, cljs.test.
+
+Related: Relates to `docs/agent-guide/029-logseq-cli-show-properties.md` and `docs/agent-guide/023-logseq-cli-help-show-styling.md`.
+
+## Problem statement
+
+The current `show` human output prints property lines as plain text in the form `<property-key>: <property-value>`.
+
+`property-kvs` are already rendered in the correct position and indentation under each block, but `<property-key>` does not have visual emphasis.
+
+The requested behavior is to bold only `<property-key>` while preserving `:`, value text, multiline/list formatting, and tree alignment.
+
+Because logseq-cli `show` depends on db-worker-node data, this change must not alter db-worker-node API contracts, pull results, or non-human output formats.
+
+## Testing Plan
+
+I will add a unit test that verifies a single-value property line styles only the property key with ANSI bold when color is enabled.
+
+I will add a unit test that verifies multi-value property blocks style the property key heading in bold while list item rows remain non-bold.
+
+I will update existing property rendering tests to keep `strip-ansi` expectations unchanged so layout behavior is locked.
+
+I will add a format-level test to ensure human `show` output preserves the new bold key styling through `format/format-result`.
+
+I will run one integration test for show properties to confirm db-worker-node end-to-end behavior remains unchanged after ANSI stripping.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Scope and non-goals
+
+In scope is styling `<property-key>` in human output generated by `show`.
+
+Out of scope is changing property query logic, property sorting rules, property value normalization, and db-worker-node request/response schemas.
+
+Out of scope is any change to JSON or EDN output.
+
+## Files to touch
+
+| File path | Purpose |
+| --- | --- |
+| `src/main/logseq/cli/command/show.cljs` | Apply bold style to `<property-key>` in property line formatter only. |
+| `src/test/logseq/cli/commands_test.cljs` | Add renderer-focused tests for ANSI bold presence and unchanged stripped layout. |
+| `src/test/logseq/cli/format_test.cljs` | Verify formatted human output keeps bold property-key styling. |
+| `src/test/logseq/cli/integration_test.cljs` | Confirm end-to-end show property output remains stable after strip-ansi. |
+
+## Implementation plan
+
+1. Follow `@test-driven-development` and `@prompts/review.md` before code edits.
+2. Add failing renderer unit tests in `src/test/logseq/cli/commands_test.cljs` for bold `<property-key>` in single and multi-value property output.
+3. Run targeted tests and confirm they fail for missing styling behavior and not for test setup errors.
+4. Update `format-property-lines` in `src/main/logseq/cli/command/show.cljs` to wrap only the property title segment with `style/bold`.
+5. Keep `indent`, colon placement, and value rendering unchanged so current tree alignment remains intact.
+6. Add or update `src/test/logseq/cli/format_test.cljs` to ensure `format/format-result` does not strip the new bold style in human output.
+7. Run targeted unit tests again and confirm all new assertions pass.
+8. Run the existing integration test that covers show properties and confirm stripped output still matches the same textual content.
+9. Run full lint and unit test suite for regression coverage.
+
+## Verification commands
+
+```bash
+bb dev:test -v 'logseq.cli.commands-test/test-tree->text-renders-properties-single-value'
+bb dev:test -v 'logseq.cli.commands-test/test-tree->text-renders-properties-multi-value'
+bb dev:test -v 'logseq.cli.format-test/test-human-output-show'
+bb dev:test -v 'logseq.cli.integration-test/test-cli-show-properties-human-output'
+bb dev:lint-and-test
+```
+
+Expected outcome is that new property-key bold tests pass, pre-existing strip-ansi assertions remain unchanged, integration behavior remains stable, and the full lint/test command exits successfully.
+
+## Edge cases
+
+When color is disabled, output should remain plain text and still include `<property-key>: <property-value>` with no ANSI codes.
+
+For multiline block titles, property-key bold styling must not shift spacing or tree glyph alignment.
+
+For multi-value properties, only the heading key line should be bold and bullet item values should remain unchanged.
+
+If a property title is missing or blank, existing skip behavior should remain unchanged.
+
+## Rollout and risk
+
+Risk is low because the change is limited to a string formatting helper used only by human output.
+
+The main regression risk is accidental styling leakage into values or alignment shifts caused by ANSI code placement.
+
+This risk is controlled by preserving existing strip-ansi golden assertions and adding explicit ANSI presence tests.
+
+## Testing Details
+
+The tests verify behavior at three levels, which are renderer output, formatter passthrough, and db-worker-node integration stability.
+
+Renderer tests assert exact ANSI bold placement around property keys and unchanged plain text after stripping ANSI.
+
+Formatter tests confirm human output still carries ANSI styling while JSON and EDN behavior is unchanged.
+
+Integration coverage confirms end-to-end property visibility still works with the same stripped output content.
+
+## Implementation Details
+- Reuse `logseq.cli.style/bold` instead of introducing a new styling helper.
+- Change only `format-property-lines` and avoid modifying property discovery helpers.
+- Keep sorted property order logic exactly as-is.
+- Keep `property-value->string` and `normalize-property-values` untouched.
+- Preserve the existing list format for multi-value properties.
+- Preserve root and child indentation prefixes from `tree->text`.
+- Avoid any db-worker-node API or transport changes.
+- Ensure ANSI checks in tests use existing helpers like `style/strip-ansi` or regex.
+- Keep all JSON and EDN output paths unchanged.
+
+## Question
+
+Only the heading key should be considered the full `<property-key>` target, so `Criteria` should be bold while `- One` and `- Two` should remain non-bold.
+
+---
diff --git a/docs/agent-guide/033-desktop-db-worker-node-backend.md b/docs/agent-guide/033-desktop-db-worker-node-backend.md
new file mode 100644
index 0000000000..592d4ed0ab
--- /dev/null
+++ b/docs/agent-guide/033-desktop-db-worker-node-backend.md
@@ -0,0 +1,224 @@
+# Desktop Db Worker Node Backend Implementation Plan
+
+Goal: Switch the Electron desktop app graph database backend from OPFS plus periodic disk export to db-worker-node with direct disk SQLite access, so desktop app and logseq-cli can safely use the same data-dir at the same time.
+
+Architecture: Reuse existing `logseq.cli.server` daemon orchestration and lock semantics, and add an Electron main process graph-scoped daemon manager.
+
+Architecture: Replace the Electron renderer `PersistentDB` implementation from `frontend.persist-db.browser` to an HTTP plus SSE remote client that talks to `/v1/invoke` and `/v1/events` on db-worker-node.
+
+Tech Stack: ClojureScript, Electron main plus renderer, Node child_process, db-worker-node HTTP plus SSE API, Electron IPC with transit-json payloads, SQLite files under data-dir, lock files.
+
+Related: Builds on `docs/agent-guide/003-db-worker-node-cli-orchestration.md`.
+
+Related: Relates to `docs/agent-guide/012-logseq-cli-graph-storage.md`.
+
+Related: Relates to `docs/agent-guide/030-logseq-cli-db-graph-default-dir-locking.md`.
+
+Related: Owner-aware lifecycle follow-up is documented in `docs/agent-guide/034-db-worker-node-owner-process-management.md`.
+
+## Problem statement
+
+The current desktop app uses an OPFS-backed SQLite worker in the renderer and periodically exports to disk through `persist-db/run-export-periodically!`.
+
+The current logseq-cli starts and connects to db-worker-node, and directly reads and writes SQLite files in data-dir.
+
+This split creates two write paths with eventual synchronization, and desktop plus CLI concurrent usage depends on export timing instead of one shared lock-governed write path.
+
+The goal is to make desktop and CLI share db-worker-node semantics and lock behavior so disk SQLite becomes the single source of truth.
+
+The desktop default DB graphs directory is `~/logseq/graphs`, defined in `deps/cli/src/logseq/cli/common/graph.cljs`, and used by Electron DB file operations in `src/electron/electron/db.cljs`.
+
+This plan focuses on backend access flow and lifecycle management, and does not change business-level thread-api semantics or SQLite schema.
+
+## Testing Plan
+
+I will follow `@test-driven-development` for every phase and write failing tests before implementation changes.
+
+I will prioritize pure-function and dependency-injected tests so core behavior can be validated without launching a full Electron GUI.
+
+I will add Electron main db-worker manager lifecycle tests for first graph open, multi-window reuse, last-window close, and app shutdown cleanup.
+
+I will add remote client transport tests for invoke success, invoke failure propagation, SSE disconnect and reconnect, and missing auth token handling.
+
+I will extend db-worker-node tests with desktop plus CLI coexistence cases, including lock contention and stale lock recovery.
+
+I will run targeted tests first and then run `bb dev:lint-and-test`, and I will apply the review checklist in `@prompts/review.md`.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current behavior map
+
+| Area | Current implementation | Target implementation |
+|---|---|---|
+| Desktop graph DB runtime | Renderer uses `frontend.persist-db.browser` and an OPFS worker. | Renderer uses a remote `PersistentDB` client against db-worker-node. |
+| Desktop persistence model | OPFS acts as source of truth and is periodically exported to disk through Electron IPC. | Disk SQLite in data-dir is the source of truth with no OPFS periodic export flow. |
+| CLI persistence model | CLI starts db-worker-node and calls `/v1/invoke`. | Keep unchanged and align desktop with the same daemon semantics. |
+| Lock and ownership | Desktop OPFS path bypasses db-worker-node lock semantics during in-memory writes. | Desktop and CLI both go through db-worker-node lock and single-writer enforcement. |
+| Process lifecycle | Desktop has no graph-scoped daemon manager in main process. | Electron main manages per-graph daemon start, reuse, health checks, and stop. |
+
+## Integration sketch
+
+```text
+Desktop Renderer
+  -> requests graph runtime from Electron Main via `electron.ipc/ipc` (transit-json)
+  -> receives {base-url, auth-token, repo} for db-worker-node
+  -> calls /v1/invoke and listens /v1/events through remote PersistentDB client
+
+Electron Main
+  -> on graph open: ensure db-worker-node started for graph in data-dir
+  -> on graph close or app quit: stop graph daemon when the last window exits
+  -> maintains graph -> daemon state cache
+
+Logseq CLI
+  -> uses existing logseq.cli.server ensure/start/stop
+  -> talks to the same graph data-dir and lock protocol
+
+db-worker-node
+  -> provides the single write path to disk SQLite files
+  -> enforces lock ownership and readiness checks
+```
+
+## Scope and non-goals
+
+In scope are Electron main daemon lifecycle management, renderer persistence client switch, OPFS export-path removal, and required tests plus docs.
+
+Out of scope are thread-api business behavior changes, SQLite schema changes, mobile behavior changes, and broad sync-system redesign.
+
+## Implementation plan
+
+### Phase 1: Add failing tests for the new desktop backend contract.
+
+1. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` that verifies stable lock-conflict error reporting from daemon orchestration.
+2. Add `/Users/rcmerci/gh-repos/logseq/src/test/electron/db_worker_manager_test.cljs` and write a failing test for `ensure-started!` idempotency.
+3. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/electron/db_worker_manager_test.cljs` that verifies one daemon is reused across multiple windows for the same graph.
+4. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/electron/db_worker_manager_test.cljs` that verifies stop on last-window close.
+5. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/electron/db_worker_manager_test.cljs` that verifies stop-all behavior on app quit.
+6. Add `/Users/rcmerci/gh-repos/logseq/src/test/frontend/persist_db/remote_test.cljs` and write failing tests for invoke success and invoke error propagation.
+7. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/persist_db/remote_test.cljs` for SSE parsing and reconnect behavior.
+8. Run `bb dev:test -v 'electron.db-worker-manager-test'` and confirm new assertions fail first.
+9. Run `bb dev:test -v 'frontend.persist-db.remote-test'` and confirm new assertions fail first.
+
+### Phase 2: Extract shared daemon orchestration for CLI and Electron.
+
+10. Extract CLI-output-independent daemon orchestration logic from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs`.
+11. Add `/Users/rcmerci/gh-repos/logseq/src/main/logseq/db_worker/daemon.cljs` and move `spawn`, `wait-ready`, `read-lock`, and `cleanup-stale-lock` core functions into it.
+12. Keep command-facing API shape in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` stable and delegate internally to the new helper.
+13. Extend `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` with regression tests for unchanged CLI behavior.
+14. Run `bb dev:test -v 'logseq.cli.server-test'` and confirm green.
+
+### Phase 3: Implement Electron main db-worker manager.
+
+15. Add `/Users/rcmerci/gh-repos/logseq/src/electron/electron/db_worker.cljs` with graph-to-daemon state cache and reference counting.
+16. Implement `ensure-started!` in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/db_worker.cljs` using the shared daemon helper and return `base-url` plus `auth-token`.
+17. Implement `ensure-stopped!` and `stop-all!` in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/db_worker.cljs`.
+18. Add `electron.ipc/ipc` handlers in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/handler.cljs` for renderer requests of graph runtime configuration, encoded with transit-json.
+19. Hook `stop-all!` into app lifecycle in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/core.cljs` at `before-quit` and `window-all-closed`.
+20. Hook graph last-window stop logic into close flow in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/core.cljs`.
+21. Run `bb dev:test -v 'electron.db-worker-manager-test'` and confirm lifecycle tests pass.
+
+### Phase 4: Add Electron renderer remote PersistentDB client.
+
+22. Add `/Users/rcmerci/gh-repos/logseq/src/main/frontend/persist_db/remote.cljs` implementing `protocol/PersistentDB` with HTTP plus SSE transport.
+23. Implement browser-safe invoke transport in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/persist_db/remote.cljs` and avoid Node-only `http` dependency in the renderer.
+24. Implement event subscription and reconnect policy in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/persist_db/remote.cljs` compatible with current event handler signatures.
+25. Extend runtime implementation selection in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/persist_db.cljs` to explicitly use remote client for Electron.
+26. Add initialization flow in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/persist_db.cljs` that fetches runtime config from `electron.ipc/ipc` via transit-json before creating the remote client.
+27. Update `/Users/rcmerci/gh-repos/logseq/src/test/frontend/persist_db/remote_test.cljs` to green after implementation.
+28. Run `bb dev:test -v 'frontend.persist-db.remote-test'` and confirm green.
+
+### Phase 5: Replace OPFS startup path and remove periodic export workflow.
+
+29. Remove Electron-path dependency on `frontend.persist-db.browser/start-db-worker!` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler.cljs`.
+30. Start remote `PersistentDB` initialization flow in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler.cljs`.
+31. Remove Electron-path invocation of `persist-db/run-export-periodically!` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler.cljs`.
+32. Adjust `:graph/save-db-to-disk` behavior in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/events.cljs` to a no-op or user guidance path.
+33. Adjust shortcut behavior for `:graph/db-save` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/modules/shortcut/config.cljs` so it no longer triggers legacy export flow.
+34. Mark `:db-get` and `:db-export` `electron.ipc/ipc` endpoints in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/handler.cljs` as compatibility-only or remove unused entry points.
+35. Clean up OPFS-export-only logic in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/db.cljs` while preserving needed utility paths.
+36. Run `bb dev:test -v 'frontend.handler.route-test'` and `bb dev:test -v 'frontend.handler.common.config-edn-test'` for regression coverage.
+
+### Phase 6: Add desktop and CLI coexistence verification.
+
+37. Add concurrency tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` covering desktop plus CLI access to the same graph.
+38. Add stale-lock recovery tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs`.
+39. Add tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` for CLI reuse or conflict reporting when desktop already started the graph daemon.
+40. Run `bb dev:test -v 'frontend.worker.db-worker-node-test'` and confirm green for coexistence tests.
+41. Run `bb dev:test -v 'logseq.cli.server-test'` and confirm green for coexistence tests.
+
+### Phase 7: Docs and rollout safety.
+
+42. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to document shared db-worker-node semantics between desktop and CLI.
+43. Add `/Users/rcmerci/gh-repos/logseq/docs/developers/desktop-db-worker-node.md` describing Electron main lifecycle and renderer remote-client init ordering.
+44. Add release notes describing that Electron no longer uses OPFS as the primary database storage path.
+45. Add rollback notes for a temporary fallback switch if emergency recovery is required.
+46. Run `bb dev:lint-and-test` and confirm zero failures and zero errors.
+47. Run a final review against `@prompts/review.md` and fix findings before merge.
+
+## Edge cases
+
+| Scenario | Expected behavior |
+|---|---|
+| Desktop opens a graph before daemon readiness completes. | Renderer waits for main-process ready runtime or receives a retryable error, and does not silently fall back to OPFS. |
+| Desktop and CLI both attempt first start for the same graph daemon. | Exactly one owner acquires lock and the other path reuses the existing daemon or retries after a `:repo-locked` status check. |
+| Graph name contains special characters. | Existing graph-dir encoding resolves to the same on-disk directory for desktop and CLI. |
+| SSE connection drops. | Remote client reconnects and keeps event handling consistent, while invoke calls remain independent. |
+| App exits abnormally and leaves a stale lock. | Next startup cleans stale lock via existing lock housekeeping logic without manual lock deletion. |
+| Version switch from OPFS-backed desktop behavior. | No one-time migration is required because desktop already writes to disk data-dir, and startup verification should check disk DB readability before enabling the new backend. |
+
+## Verification commands and expected outputs
+
+```bash
+bb dev:test -v 'electron.db-worker-manager-test'
+bb dev:test -v 'frontend.persist-db.remote-test'
+bb dev:test -v 'logseq.cli.server-test'
+bb dev:test -v 'frontend.worker.db-worker-node-test'
+clojure -M:cljs compile db-worker-node
+bb dev:lint-and-test
+```
+
+Each test command should finish with `0 failures, 0 errors`.
+
+`clojure -M:cljs compile db-worker-node` should produce a runnable `static/db-worker-node.js`.
+
+In manual smoke tests, desktop and CLI reads and writes for the same graph should be immediately visible to each other without periodic export dependency.
+
+## Rollout strategy
+
+Phase one ships behind a feature flag and enables by default in development builds for coexistence and recovery telemetry.
+
+Phase two enables by default in stable builds and keeps a short-lived rollback switch.
+
+Phase three removes legacy OPFS export-path code and removes the rollback switch.
+
+## Clarity required before implementation
+
+Confirm product-level messaging for desktop and CLI lock-contention conflicts on the same graph.
+
+Confirm whether `:graph/db-save` is removed or redefined as a checkpoint action in the new model.
+
+Confirm rollback-switch lifecycle and target removal release.
+
+## Testing Details
+
+Tests focus on behavior, not implementation details, by validating daemon lifecycle, invoke responses, and event-stream consistency.
+
+Core coexistence tests validate lock ownership, recovery, and cross-client visibility for the same graph instead of mock call counts.
+
+Regression tests ensure existing CLI behavior stays stable and Electron startup plus shutdown does not leave zombie processes or lock files.
+
+## Implementation Details
+
+- Reuse and extract daemon orchestration from `logseq.cli.server` to avoid duplicate process-management logic.
+- Add a dedicated Electron main db-worker manager with graph-scoped daemon state cache.
+- Use a renderer remote `PersistentDB` client against db-worker-node HTTP plus SSE endpoints.
+- Use transit-json for frontend and Electron communication through `electron.ipc/ipc` (see also `ldb/write-transit-str`).
+- Remove periodic OPFS export workflow in Electron so disk SQLite is the only source of truth.
+- Keep thread-api and database schema unchanged to limit application-level regressions.
+- Keep lock-file and `:repo-locked` semantics identical for desktop and CLI.
+- Add reconnect and stale-lock recovery tests to cover availability risks.
+- Roll out with feature-flag phases and a short rollback window.
+- Follow `@test-driven-development` and `@prompts/review.md` through implementation and verification.
+
+## Question
+
+---
diff --git a/docs/agent-guide/034-db-worker-node-owner-process-management.md b/docs/agent-guide/034-db-worker-node-owner-process-management.md
new file mode 100644
index 0000000000..6d9148b9f8
--- /dev/null
+++ b/docs/agent-guide/034-db-worker-node-owner-process-management.md
@@ -0,0 +1,205 @@
+# DB Worker Node Owner-Aware Process Management Implementation Plan
+
+Goal: Add owner-aware lock metadata and orphan-process recovery so CLI and Electron can safely share one graph daemon without cross-managing each other.
+
+Architecture: Keep one `db-worker.lock` per graph directory, but extend lock schema with `owner-source` so lifecycle actions can enforce owner boundaries.
+Architecture: Keep read and write traffic reusable across clients, while restricting `stop` and `restart` to the side that originally started the daemon.
+Architecture: Add orphan-process detection for lock-missing cases so `logseq server restart` does not hang on timeout when a legacy process is still alive.
+
+Tech Stack: ClojureScript, Node.js child process APIs, `promesa`, `logseq.cli.server`, `logseq.db-worker.daemon`, Electron main-process daemon manager, db-worker-node lock helpers.
+
+Related: Builds on `docs/agent-guide/033-desktop-db-worker-node-backend.md`.
+Related: Relates to `docs/agent-guide/030-logseq-cli-db-graph-default-dir-locking.md`.
+Related: Relates to `docs/agent-guide/003-db-worker-node-cli-orchestration.md`.
+
+## Problem statement
+
+Current lock payload only records repo, pid, host, and port, so ownership is implicit and lifecycle commands cannot distinguish CLI-started and Electron-started daemons.
+
+`stop-server!` and `restart-server!` can currently terminate any alive daemon if the lock exists, which violates the requirement that each client should manage only its own process.
+
+If a db-worker-node process remains alive but lock file is missing, `server restart` can wait until timeout because startup relies on lock appearance and has no orphan recovery path.
+
+When CLI starts a daemon first, Electron may treat the runtime as managed-by-self and attempt stop or restart logic, which can break graph open flow and produce user-facing errors.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and add failing tests before each implementation change.
+
+I will add lock schema and owner compatibility tests in `src/test/frontend/worker/db_worker_node_lock_test.cljs`.
+
+I will add daemon-owner lifecycle and orphan-recovery tests in `src/test/logseq/cli/server_test.cljs` and `src/test/logseq/db_worker/daemon_test.cljs`.
+
+I will add Electron manager tests for external-runtime attachment and no-cross-stop behavior in `src/test/electron/db_worker_manager_test.cljs`.
+
+I will add db-worker-node argument and lock-write tests in `src/test/frontend/worker/db_worker_node_test.cljs`.
+
+I will run focused red-green loops first, then run `bb dev:lint-and-test`, and finish with a review pass against `@prompts/review.md`.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current behavior map
+
+| Area | Current behavior | Target behavior |
+|---|---|---|
+| Lock metadata | No owner field in `db-worker.lock`. | Lock includes `owner-source` as `cli` or `electron`, plus versioned metadata. |
+| Lifecycle authority | Any caller can stop or restart lock-owned daemon. | `stop` and `restart` are allowed only for matching owner-source. |
+| Runtime reuse | Reuse happens, but manager cannot tell owned vs external runtime. | Reuse still happens, and runtime state tracks `owned?` to prevent cross-stop. |
+| Lock missing + orphan process | Startup can timeout with no clear recovery path. | Orphan detection and cleanup path runs before or after failed startup wait. |
+| Compatibility | Legacy lock without owner is ambiguous. | Legacy lock is treated as `owner-source: unknown` with explicit policy. |
+
+## Integration sketch
+
+```text
+CLI or Electron request ensure-server(repo, requester-owner)
+  -> read lock
+  -> if lock exists and healthy:
+       return runtime + ownership(owned/external)
+  -> if lock missing:
+       scan orphan db-worker-node process for same repo/data-dir
+       if orphan found:
+         terminate orphan
+       spawn new daemon with --owner-source <cli|electron>
+  -> db-worker-node writes lock {repo,pid,host,port,owner-source,lock-id,...}
+
+stop/restart(requester-owner)
+  -> read lock owner-source
+  -> if owner-source matches requester-owner: allow
+  -> else: deny with :server-owned-by-other
+```
+
+## Implementation plan
+
+### Phase 1: Add failing tests for owner-aware lock schema and policies.
+
+1. Add a failing test in `src/test/frontend/worker/db_worker_node_lock_test.cljs` that lock serialization includes `owner-source`.
+2. Add a failing test in `src/test/frontend/worker/db_worker_node_lock_test.cljs` that missing owner metadata is normalized to `:unknown`.
+3. Add a failing test in `src/test/frontend/worker/db_worker_node_test.cljs` that `--owner-source cli` is written into the lock.
+4. Add a failing test in `src/test/frontend/worker/db_worker_node_test.cljs` that `--owner-source electron` is written into the lock.
+5. Add a failing test in `src/test/logseq/cli/server_test.cljs` that `stop-server!` returns `:server-owned-by-other` on owner mismatch.
+6. Add a failing test in `src/test/logseq/cli/server_test.cljs` that `restart-server!` does not SIGTERM external-owner daemon.
+7. Add a failing test in `src/test/electron/db_worker_manager_test.cljs` that external runtime release does not call `stop-daemon!`.
+8. Run `bb dev:test -v 'frontend.worker.db-worker-node-lock-test'` and confirm failures match new assertions.
+9. Run `bb dev:test -v 'logseq.cli.server-test'` and confirm failures match new assertions.
+
+### Phase 2: Extend lock schema and daemon startup arguments.
+
+10. Update argument parsing in `src/main/frontend/worker/db_worker_node.cljs` to accept `--owner-source`.
+11. Add owner-source validation in `src/main/frontend/worker/db_worker_node.cljs` with allowed values `cli`, `electron`, and fallback `unknown`.
+12. Thread owner-source through `start-daemon!` in `src/main/frontend/worker/db_worker_node.cljs` into lock creation.
+13. Update `create-lock!` in `src/main/frontend/worker/db_worker_node_lock.cljs` to persist `owner-source`.
+14. Update `read-lock` normalization path in `src/main/frontend/worker/db_worker_node_lock.cljs` to inject `:owner-source :unknown` for legacy files.
+15. Keep `update-lock!` in `src/main/frontend/worker/db_worker_node_lock.cljs` from mutating existing owner-source during port updates.
+16. Add targeted tests for lock read-write roundtrip in `src/test/frontend/worker/db_worker_node_lock_test.cljs`.
+17. Run `bb dev:test -v 'frontend.worker.db-worker-node-test'` and make sure lock owner assertions pass.
+
+### Phase 3: Make CLI server orchestration owner-aware.
+
+18. Add requester owner config to `ensure-server!` in `src/main/logseq/cli/server.cljs`.
+19. Pass owner-source to daemon spawn args from `spawn-server!` in `src/main/logseq/db_worker/daemon.cljs`.
+20. Update `ensure-server-started!` in `src/main/logseq/cli/server.cljs` to return ownership metadata for caller state tracking.
+21. Update `stop-server!` in `src/main/logseq/cli/server.cljs` to deny stop when lock owner-source differs from requester owner.
+22. Update `restart-server!` in `src/main/logseq/cli/server.cljs` to preserve the same owner check semantics as `stop-server!`.
+23. Update `server-status` and `list-servers` in `src/main/logseq/cli/server.cljs` to include owner-source in output payload.
+24. Update server command response formatting so `logseq server list` human output includes an `OWNER` column mapped from `owner-source` (and preserves owner metadata in structured output).
+25. Add regression tests in `src/test/logseq/cli/server_test.cljs` for owner-aware start, stop, and restart.
+26. Run `bb dev:test -v 'logseq.cli.server-test'` and verify no timeout-based flaky failure remains.
+
+### Phase 4: Add orphan-process detection and recovery for lock-missing start.
+
+27. Add process listing helper in `src/main/logseq/db_worker/daemon.cljs` that discovers db-worker-node processes by repo and data-dir arguments.
+28. Add parser helpers in `src/main/logseq/db_worker/daemon.cljs` to read `repo`, `data-dir`, and `owner-source` from command args.
+29. Add `cleanup-orphan-process!` in `src/main/logseq/db_worker/daemon.cljs` to SIGTERM matched orphan pids before new spawn.
+30. Call orphan cleanup path in `ensure-server-started!` in `src/main/logseq/cli/server.cljs` when lock is missing before spawn.
+31. Add timeout fallback in `ensure-server-started!` in `src/main/logseq/cli/server.cljs` to emit `:server-start-timeout-orphan` with discovered pids.
+32. Add unit tests in `src/test/logseq/db_worker/daemon_test.cljs` for process-arg parsing and orphan match logic.
+33. Add CLI regression test in `src/test/logseq/cli/server_test.cljs` for lock-missing orphan scenario to avoid raw timeout.
+34. Run `bb dev:test -v 'logseq.db-worker.daemon-test'` and `bb dev:test -v 'logseq.cli.server-test'`.
+
+### Phase 5: Make Electron manager attach external daemon without cross-management.
+
+35. Pass requester owner as `electron` from `start-managed-daemon!` in `src/electron/electron/db_worker.cljs`.
+36. Save ownership flag in manager runtime state in `src/electron/electron/db_worker.cljs`.
+37. Update stop flow in `src/electron/electron/db_worker.cljs` so `stop-daemon!` runs only when `owned?` is true.
+38. Update unhealthy-runtime branch in `src/electron/electron/db_worker.cljs` to avoid stopping external owner daemon and re-resolve runtime instead.
+39. Add tests in `src/test/electron/db_worker_manager_test.cljs` for external runtime reuse plus no-stop-on-release.
+40. Run `bb dev:test -v 'electron.db-worker-manager-test'` and confirm lifecycle behavior.
+
+### Phase 6: Update docs and error surfaces.
+
+41. Update CLI docs in `docs/cli/logseq-cli.md` to document owner-aware `server stop` and `server restart` behavior.
+42. Update desktop lifecycle docs in `docs/developers/desktop-db-worker-node.md` to explain external runtime attachment semantics.
+43. Add explicit error messages for `:server-owned-by-other` and `:server-start-timeout-orphan` in `src/main/logseq/cli/format.cljs`.
+44. Add one integration note in `docs/agent-guide/033-desktop-db-worker-node-backend.md` linking to owner-aware behavior.
+
+### Phase 7: Full verification and review gate.
+
+45. Run `bb dev:test -v 'frontend.worker.db-worker-node-test'`.
+46. Run `bb dev:test -v 'frontend.worker.db-worker-node-lock-test'`.
+47. Run `bb dev:test -v 'logseq.db-worker.daemon-test'`.
+48. Run `bb dev:test -v 'logseq.cli.server-test'`.
+49. Run `bb dev:test -v 'electron.db-worker-manager-test'`.
+50. Run `bb dev:lint-and-test` and confirm zero failures and zero errors.
+51. Perform final review checklist pass against `@prompts/review.md`.
+
+## Edge cases
+
+| Scenario | Expected behavior |
+|---|---|
+| Lock file missing but old CLI daemon still alive. | CLI restart detects orphan by repo and data-dir, cleans it, then starts cleanly. |
+| Lock owner is `cli` and Electron calls ensure runtime. | Electron reuses runtime with `owned? false` and never stops it on window close. |
+| Lock owner is `electron` and CLI calls `server stop`. | CLI returns `:server-owned-by-other` with owner metadata and no process kill. |
+| Legacy lock file has no owner-source field. | System treats owner as `unknown` and allows CLI takeover with owner metadata rewrite. |
+| Two owners race to start same graph. | First lock wins and second caller reuses healthy daemon without extra spawn. |
+| Owner process crashes and lock remains stale. | Stale lock cleanup still works, and next owner can start daemon normally. |
+
+## Verification commands and expected outputs
+
+```bash
+bb dev:test -v 'frontend.worker.db-worker-node-lock-test'
+bb dev:test -v 'frontend.worker.db-worker-node-test'
+bb dev:test -v 'logseq.db-worker.daemon-test'
+bb dev:test -v 'logseq.cli.server-test'
+bb dev:test -v 'electron.db-worker-manager-test'
+bb dev:lint-and-test
+```
+
+Each command should finish with `0 failures, 0 errors`.
+
+The owner-mismatch tests should return `:server-owned-by-other` instead of timeout or forced stop behavior.
+
+`logseq server list` human output should include an `OWNER` column.
+
+The orphan-recovery tests should return deterministic cleanup behavior instead of waiting until generic timeout.
+
+## Testing Details
+
+The tests validate behavior by asserting lifecycle authority boundaries, successful runtime reuse across clients, and orphan recovery outcomes.
+
+The tests avoid mock-only success criteria by asserting returned error codes and process-management side effects observable from public APIs.
+
+The critical regressions are lock-missing orphan restart and CLI-first then Electron-open graph flow, and both are explicitly covered.
+
+## Implementation Details
+
+- Extend lock payload with `owner-source` and preserve it across lock updates.
+- Pass `--owner-source` when spawning db-worker-node from both CLI and Electron pathways.
+- Return ownership metadata from server orchestration so callers can track `owned?` state.
+- Enforce owner check for stop and restart while keeping read and write invoke reuse unchanged.
+- Add orphan process discovery by command args for lock-missing recovery.
+- Scope orphan process discovery in v1 to macOS and Linux, and use a Windows-safe no-op fallback.
+- Keep stale-lock cleanup logic and layer orphan recovery without changing healthy lock reuse flow.
+- Add explicit CLI error codes for owner mismatch and orphan timeout contexts.
+- Prevent Electron manager from stopping external-owner runtime on release or health fallback.
+- Document operator-visible behavior changes in CLI and desktop developer docs.
+- Execute full suite and `@prompts/review.md` checks before merge.
+
+## Question
+
+Decision: CLI is allowed to take over `owner-source: unknown` and rewrite ownership metadata in v1.
+
+Decision: when lock file is missing, orphan cleanup terminates all matching repo and data-dir processes.
+
+Decision: v1 scopes orphan process-scan support to macOS and Linux only, with a Windows-safe no-op fallback.
+
+---
diff --git a/docs/agent-guide/035-logseq-cli-db-worker-deps-cli-decoupling.md b/docs/agent-guide/035-logseq-cli-db-worker-deps-cli-decoupling.md
new file mode 100644
index 0000000000..0ad05a9d67
--- /dev/null
+++ b/docs/agent-guide/035-logseq-cli-db-worker-deps-cli-decoupling.md
@@ -0,0 +1,167 @@
+# Logseq CLI and db-worker-node deps/cli Decoupling Implementation Plan
+
+Goal: Make `logseq-cli` behavior independent from old `deps/cli` regressions while restoring list behavior that regressed after commit `0de3c337e` on February 12, 2026.
+
+Architecture: Apply a CLI-scoped decoupling only for the runtime path used by `logseq-cli` (`src/main/logseq/cli/*` plus db-worker API path it invokes), and defer non-CLI namespace migration to follow-up work.
+
+Tech Stack: ClojureScript, Datascript, `shadow-cljs` node-script builds (`:logseq-cli` and `:db-worker-node`), babashka test workflow.
+
+Related: Builds on `docs/agent-guide/003-db-worker-node-cli-orchestration.md`, `docs/agent-guide/007-logseq-cli-thread-api-and-command-split.md`, and `docs/agent-guide/034-db-worker-node-owner-process-management.md`.
+
+Developer note (CLI-scoped): The implementation for this plan only migrates the `logseq-cli -> db-worker-node -> thread-api` runtime path by adding `src/main/logseq/cli/common/mcp/tools.cljs`. It does not migrate or alter export/Electron/non-CLI namespaces still resolving from `deps/cli`.
+
+## Problem statement
+
+`deps/cli` is the old CLI codebase, but current runtime paths under `src/` still require namespaces from `deps/cli`, so old CLI commits can silently change new CLI behavior.
+
+Commit `0de3c337e` changed `deps/cli/src/logseq/cli/common/mcp/tools.cljs` and removed fields and filters that new CLI still depends on through db-worker thread-api calls.
+
+Current regressions are reproducible with existing tests.
+
+`bb dev:test -v 'logseq.cli.integration-test/test-cli-list-outputs-include-id'` currently fails because list items no longer include numeric `:id`.
+
+`bb dev:test -v 'logseq.cli.integration-test/test-cli-add-tags-and-properties-by-id'` currently fails because default tag/property lists no longer include built-in entities needed for ID-based add flows.
+
+The dependency path that causes this is shown below.
+
+```text
+logseq-cli (src/main/logseq/cli/*)
+  -> HTTP invoke to db-worker-node
+    -> thread-api methods in frontend.worker.db-core
+      -> implementation helper logseq.cli.common.mcp.tools  (currently loaded from deps/cli)
+```
+
+## Current dependency inventory
+
+| Namespace currently resolved from `deps/cli` | `src/` consumers | Build impact | Status in this plan |
+| --- | --- | --- | --- |
+| `logseq.cli.common.mcp.tools` | `src/main/frontend/worker/db_core.cljs`, `src/main/logseq/api/db_based/cli.cljs`, `src/main/logseq/sdk/utils.cljs` | `:db-worker-node`, app API, SDK | In scope now |
+| `logseq.cli.common.file` | `src/main/frontend/worker/export.cljs` | `:db-worker-node` export path | Out of scope now |
+| `logseq.cli.common.util` | `src/main/frontend/extensions/zip.cljs`, export handlers | app export and zip features | Out of scope now |
+| `logseq.cli.common.export.common` | `src/main/frontend/handler/export/common.cljs`, `src/main/frontend/handler/export/html.cljs`, `src/main/frontend/handler/export/opml.cljs`, `src/main/frontend/handler/export/text.cljs` | app export features | Out of scope now |
+| `logseq.cli.common.export.text` | `src/main/frontend/handler/export/text.cljs` | app markdown export | Out of scope now |
+| `logseq.cli.common.graph` | `src/electron/electron/utils.cljs`, `src/electron/electron/db.cljs`, `src/electron/electron/handler.cljs` | Electron graph directory behavior | Out of scope now |
+| `logseq.cli.common.mcp.server` | `src/electron/electron/server.cljs` | Electron MCP HTTP endpoint | Out of scope now |
+| `logseq.cli.text-util` | `src/main/frontend/util/text.cljs` | frontend text helpers | Out of scope now |
+
+## Scope
+
+This plan only changes logseq-cli related runtime behavior.
+
+This plan migrates the `logseq-cli -> db-worker-node -> thread-api` path where the implementation currently resolves to `deps/cli`.
+
+In this PR, that means migrating `logseq.cli.common.mcp.tools` out of `deps/cli` because it is the thread-api-side implementation used by logseq-cli list/add flows.
+
+This plan does not modify any code under `deps/cli`.
+
+This plan does not migrate frontend export namespaces, Electron namespaces, or unrelated old CLI modules in `deps/cli`.
+
+This plan does not redesign CLI command UX or old CLI feature parity, and old CLI under `deps/cli` remains frozen unless a compatibility fix is required for release safety.
+
+Implementation must follow @test-driven-development, and any unexpected test failure while migrating must follow @clojure-debug before changing behavior.
+
+## Testing Plan
+
+I will first lock the current regressions by running the two failing integration tests as baseline checks and recording failure reasons in the PR notes.
+
+I will add focused tests for list data contract behavior so `:id`, built-in inclusion defaults, and page filtering options are guaranteed independent of old CLI code.
+
+I will run compile checks for both node builds to ensure the CLI path behaves correctly after the targeted namespace move.
+
+I will not include export/Electron migration tests in this PR because those modules are explicitly out of scope.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Implementation plan
+
+1. Add a migration checklist section in the PR description that references this document and lists the two known failing integration tests.
+
+2. Run `bb dev:test -v 'logseq.cli.integration-test/test-cli-list-outputs-include-id'` and confirm it fails before code changes.
+
+3. Run `bb dev:test -v 'logseq.cli.integration-test/test-cli-add-tags-and-properties-by-id'` and confirm it fails before code changes.
+
+4. Add a focused test file at `src/test/logseq/cli/mcp_tools_contract_test.cljs` for `list-pages`, `list-tags`, and `list-properties` contract behavior used by new CLI.
+
+5. In that test file, add a case asserting non-expanded list output includes `:db/id`, `:block/title`, `:block/created-at`, and `:block/updated-at`.
+
+6. In that test file, add a case asserting `include-built-in` defaults to true and explicitly false excludes built-in tags and properties.
+
+7. In that test file, add a case asserting page list filtering honors `include-hidden`, `include-journal`, `journal-only`, `created-after`, and `updated-after`.
+
+8. Add `src/main/logseq/cli/common/mcp/tools.cljs` by porting the pre-`0de3c337e` behavior as baseline thread-api implementation and keeping API signatures used by `db-core` and SDK.
+
+9. Update `src/` callsites to resolve the new `src/main` implementation and keep `deps/cli` source files untouched.
+
+10. Re-run `bb dev:test -v 'logseq.cli.mcp-tools-contract-test'` and make it pass with no test skips.
+
+11. Re-run the two integration regressions and make both pass.
+
+12. Keep all files under `deps/cli` unchanged in this PR.
+
+13. Do not remove `logseq/cli` from `deps.edn` in this PR because unrelated frontend and Electron runtime modules still depend on it.
+
+14. Run `clojure -M:cljs compile logseq-cli` and verify compile success.
+
+15. Run `clojure -M:cljs compile db-worker-node` and verify compile success.
+
+16. Run `bb dev:test -v 'logseq.cli.commands-test/test-list-subcommand-parse'` to verify list option parsing remains stable.
+
+17. Run `bb dev:test -v 'logseq.cli.integration-test/test-cli-list-outputs-include-id'` to verify ID contract restoration end-to-end.
+
+18. Run `bb dev:test -v 'logseq.cli.integration-test/test-cli-add-tags-and-properties-by-id'` to verify built-in tag/property ID flows end-to-end.
+
+19. Run `bb dev:test -v 'logseq.cli.integration-test/test-cli-list-add-show-remove'` as a smoke test for normal create/list/show/remove flow.
+
+20. Run `bb dev:test -v 'logseq.cli.integration-test/test-cli-query-recent-updated'` as a smoke test for list timestamps and query interplay.
+
+21. Run `bb dev:lint-and-test` before merge to satisfy repository review checklist.
+
+## Edge cases to validate during implementation
+
+If `created-after` or `updated-after` is an invalid date string, filtering should not crash and should behave as no time filter.
+
+When `include-journal` is omitted, journals should remain included by default to preserve existing CLI expectations.
+
+When `include-built-in` is omitted, built-in tags and properties must remain included so ID resolution in add/update flows still works.
+
+Non-expanded list output must contain stable numeric IDs even if UUID and title are present.
+
+Expanded list output must keep UUID string conversion and keep relationship fields (`classes`, `extends`, `properties`) in expected shapes.
+
+Non-CLI frontend export and Electron behavior must remain untouched in this PR.
+
+## Open questions requiring clarity
+
+Should we do a second PR for non-CLI namespace migration (`export`, `electron`, `text-util`) immediately after this thread-api decoupling PR, or wait until after release.
+
+## Testing Details
+
+The key behavior tests are integration-first and validate user-observable outcomes, not internal helper implementation.
+
+`test-cli-list-outputs-include-id` verifies that real CLI JSON output includes usable IDs for list operations.
+
+`test-cli-add-tags-and-properties-by-id` verifies that list output can feed directly into add operations using IDs and complete a write/read roundtrip.
+
+`mcp-tools-contract-test` verifies option semantics and filtering behavior at the db-worker API boundary to prevent future regressions from unrelated old CLI edits.
+
+## Implementation Details
+
+- Keep migration atomic by changing only logseq-cli related runtime pieces in this PR.
+- Preserve public function names and argument shapes to minimize callsite churn.
+- Restore pre-`0de3c337e` list semantics for IDs and built-in filtering.
+- Do not edit any file under `deps/cli`; all migration changes must happen in `src/` and `src/test/`.
+- Do not change command parsing behavior in `src/main/logseq/cli/command/list.cljs` unless tests show incompatibility.
+- Keep Electron/export/frontend non-CLI require lines unchanged in this PR.
+- Treat `deps/cli` as frozen legacy code for non-CLI modules in this PR.
+- Add a short developer note in `README.md` or `docs` explaining this PR is CLI-scoped only.
+- Use smallest possible commits per namespace group to simplify rollback.
+- Ensure all touched files remain ASCII and follow existing formatting conventions.
+- Finish with `bb dev:lint-and-test` and include command outputs in the PR summary.
+
+## Decision
+
+This migration will keep `logseq.cli.common.*` namespace names stable and only move CLI-path runtime implementation needed for `logseq-cli`.
+
+Namespace renaming will be done in a follow-up PR after decoupling and regression fixes are complete.
+
+---
diff --git a/docs/agent-guide/036-db-worker-node-ncc-bundling.md b/docs/agent-guide/036-db-worker-node-ncc-bundling.md
new file mode 100644
index 0000000000..dccc7f4929
--- /dev/null
+++ b/docs/agent-guide/036-db-worker-node-ncc-bundling.md
@@ -0,0 +1,199 @@
+# db-worker-node ncc Standalone Bundle Implementation Plan
+
+Goal: Build `db-worker-node.js` with `@vercel/ncc` so the runtime can run without `node_modules` present next to the executable.
+
+Architecture: Keep `shadow-cljs` as the source compiler for `:db-worker-node`, then run `ncc` on the generated entry and publish a single runtime artifact in `dist/` that is used by CLI daemon orchestration.
+Architecture: Preserve local development ergonomics by keeping `static/db-worker-node.js` for fast dev loops, while production and package paths resolve to the ncc artifact first.
+
+Tech Stack: ClojureScript, `shadow-cljs` `:node-script`, `@vercel/ncc`, Node.js 22, `pnpm` scripts in `package.json`, existing CLI daemon and doctor checks.
+
+Related: Builds on `docs/agent-guide/031-logseq-cli-doctor-command.md`.
+Related: Relates to `docs/agent-guide/033-desktop-db-worker-node-backend.md`.
+Related: Relates to `docs/agent-guide/035-logseq-cli-db-worker-deps-cli-decoupling.md`.
+
+## Problem statement
+
+`/Users/rcmerci/gh-repos/logseq/static/db-worker-node.js` is currently generated by `shadow-cljs`, and runtime behavior assumes dependencies are available from `node_modules`.
+
+The CLI server startup path in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` points to `../dist/db-worker-node.js`, which is currently a thin wrapper that forwards to `../static/db-worker-node.js`.
+
+This wrapper model keeps runtime coupled to workspace layout and to `node_modules`, so the daemon script is not independently portable.
+
+We need a deterministic packaging path that produces one runnable artifact plus copied native assets, and we need to verify that artifact works when `node_modules` is absent.
+
+Electron release packaging also needs to include the db-worker standalone bundle step, so `pnpm release-electron` always ships the same packaged runtime artifact.
+
+The solution must keep existing CLI and Electron daemon orchestration behavior unchanged, including lock-file semantics, owner-source semantics, and health endpoint behavior.
+
+## Current packaging map
+
+| Area | Current behavior | Limitation |
+| --- | --- | --- |
+| Build output | `pnpm db-worker-node:compile` writes `/Users/rcmerci/gh-repos/logseq/static/db-worker-node.js`. | Output is not a standalone distribution artifact. |
+| Dist entry | `/Users/rcmerci/gh-repos/logseq/dist/db-worker-node.js` only `require`s `../static/db-worker-node.js`. | Runtime still depends on static output and installed dependencies. |
+| Daemon spawn | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` spawns `../dist/db-worker-node.js`. | Spawn path is stable, but executable is not standalone. |
+| Doctor check | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/doctor.cljs` checks `../static/db-worker-node.js` by default. | Diagnostic target does not match the intended distributable runtime. |
+| Package manifest | `/Users/rcmerci/gh-repos/logseq/package.json` includes `static/db-worker-node.js` in `files`. | Published package does not guarantee standalone daemon artifact contract. |
+| Electron release | `pnpm release-electron` does not guarantee db-worker bundle refresh before packaging. | Desktop release artifact can drift from standalone db-worker bundle contract. |
+
+## Target packaging map
+
+| Area | Target behavior | Verification signal |
+| --- | --- | --- |
+| Bundle output | `ncc` emits a standalone `db-worker-node` runtime in `/Users/rcmerci/gh-repos/logseq/dist/` with required runtime assets copied adjacent to entrypoint. | Daemon starts and serves `/healthz` and `/readyz` without `node_modules`. |
+| Spawn path | CLI server keeps spawning `/Users/rcmerci/gh-repos/logseq/dist/db-worker-node.js` as canonical runtime. | Existing `logseq.cli.server-test` assertions remain green with updated contract. |
+| Doctor check | Doctor defaults to the same packaged runtime path used for spawn, and does not auto-fallback to static runtime. | Doctor check path matches runtime path in tests and manual runs. |
+| Dev flow | Fast local dev command remains available using `static/db-worker-node.js` for watch and debug workflows. | `pnpm db-worker-node:compile` and `node ./static/db-worker-node.js` still work during development. |
+| Publish flow | Package `files` include standalone runtime assets required by ncc output. | Installed package can execute daemon without extra dependency install. |
+| Electron release | `pnpm release-electron` runs db-worker bundle build before Electron packaging steps. | Electron release artifact includes the same standalone db-worker runtime contract. |
+
+## Integration sketch
+
+```text
+shadow-cljs (:db-worker-node)
+  -> /static/db-worker-node.js
+  -> ncc build step
+      -> /dist/db-worker-node.js
+      -> /dist/<ncc runtime assets, including native binaries if emitted>
+
+logseq-cli runtime
+  -> logseq.cli.server/spawn-server!
+  -> /dist/db-worker-node.js
+  -> db-worker daemon HTTP + SSE API
+```
+
+## Testing Plan
+
+I will follow `@test-driven-development` and add failing tests before implementation changes in each phase.
+
+I will add behavior tests for runtime path resolution so spawn and doctor point to the same canonical bundle target.
+
+I will add a standalone smoke test that launches the bundled daemon from a temporary directory without `node_modules` and verifies `/healthz`, `/readyz`, and shutdown behavior.
+
+I will keep existing daemon lifecycle tests green to ensure no regression in lock cleanup, owner checks, and timeout error semantics.
+
+I will run focused tests first, then full validation with `pnpm cljs:lint && pnpm test`, and if any unexpected failures appear I will use `@clojure-debug` before changing behavior.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Implementation plan
+
+### Phase 1: RED for runtime artifact contract.
+
+1. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` asserting canonical db-worker runtime path resolves to `dist/db-worker-node.js` as the production target.
+2. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/doctor_test.cljs` asserting default doctor script check points to the same canonical runtime target as server spawn.
+3. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/doctor_test.cljs` asserting optional dev-mode check can still validate `static/db-worker-node.js` when explicitly requested.
+4. Add a new failing bundle smoke test file at `/Users/rcmerci/gh-repos/logseq/src/test/logseq/db_worker/ncc_bundle_test.cljs` that expects daemon startup success from a bundle-only temp directory.
+5. Run `pnpm cljs:test && pnpm cljs:run-test -v 'logseq.cli.server-test'` and confirm failures occur on the new path-contract assertions.
+6. Run `pnpm cljs:test && pnpm cljs:run-test -v 'logseq.cli.command.doctor-test'` and confirm failures occur on the new default-path expectations.
+7. Run `pnpm cljs:test && pnpm cljs:run-test -v 'logseq.db-worker.ncc-bundle-test'` and confirm standalone smoke test fails before implementation.
+
+### Phase 2: Add ncc build pipeline.
+
+8. Add `@vercel/ncc` to `/Users/rcmerci/gh-repos/logseq/package.json` as a dev dependency.
+9. Add a dedicated script in `/Users/rcmerci/gh-repos/logseq/package.json` to build `:db-worker-node` in release mode before bundling.
+10. Add a dedicated script in `/Users/rcmerci/gh-repos/logseq/package.json` to run `ncc` against `/Users/rcmerci/gh-repos/logseq/static/db-worker-node.js`.
+11. Add a dedicated script in `/Users/rcmerci/gh-repos/logseq/package.json` to normalize ncc output into `/Users/rcmerci/gh-repos/logseq/dist/db-worker-node.js` with adjacent assets preserved.
+12. If script complexity is non-trivial, add `/Users/rcmerci/gh-repos/logseq/scripts/build-db-worker-node-bundle.mjs` to encapsulate output normalization and deterministic cleanup.
+13. Add or update `pnpm` scripts in `/Users/rcmerci/gh-repos/logseq/package.json` for one-command bundle build and optional local run of the bundled artifact.
+14. Update `pnpm release-electron` in `/Users/rcmerci/gh-repos/logseq/package.json` so it includes `db-worker-node:release:bundle` before Electron packaging.
+15. Run `pnpm db-worker-node:release:bundle` and verify `dist/db-worker-node.js` is regenerated with executable permissions preserved.
+
+### Phase 3: Align runtime path and diagnostics.
+
+15. Refactor runtime path helpers in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` so there is one canonical function for packaged runtime and one explicit dev fallback function.
+16. Keep `spawn-server!` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` bound to the packaged runtime path to avoid ambiguity.
+17. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/doctor.cljs` to default-check the same packaged runtime path used by spawn.
+18. Add an explicit action option in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/doctor.cljs` for fallback static-path diagnostics used only for development troubleshooting.
+19. Ensure doctor failure codes remain stable as `:doctor-script-missing` and `:doctor-script-unreadable`.
+21. Re-run `pnpm cljs:test && pnpm cljs:run-test -v 'logseq.cli.server-test'` and `pnpm cljs:test && pnpm cljs:run-test -v 'logseq.cli.command.doctor-test'` to make the new path contract green.
+
+### Phase 4: Package manifest and docs alignment.
+
+22. Update `files` in `/Users/rcmerci/gh-repos/logseq/package.json` so packaged runtime includes `dist/db-worker-node.js` and ncc-emitted adjacent assets.
+23. Keep `static/db-worker-node.js` inclusion only if required for development workflows, and document that distinction explicitly.
+24. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` build instructions to include the ncc bundle command and standalone runtime expectations.
+25. Update daemon runtime notes in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` so `doctor` references packaged runtime as primary target.
+26. Add troubleshooting notes for native module asset copy behavior from ncc output.
+
+### Phase 5: Standalone runtime behavior verification.
+
+27. Implement bundle smoke test setup in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/db_worker/ncc_bundle_test.cljs` to copy only bundle artifacts into a temp directory with no `node_modules`.
+28. In that test, spawn `node ./db-worker-node.js --repo <repo> --data-dir <tmp>` from the bundle-only directory.
+29. In that test, poll `/healthz` and `/readyz` and assert both return HTTP 200 after startup.
+30. In that test, invoke `/v1/shutdown` and assert process exits and lock file is cleaned or becomes stale-removable.
+31. In that test, assert failure output is actionable if native binary asset is missing, to guard accidental packaging regressions.
+32. Run `pnpm cljs:test && pnpm cljs:run-test -v 'logseq.db-worker.ncc-bundle-test'` and make it green.
+
+### Phase 6: Final validation and review checklist.
+
+33. Run `pnpm cljs:test && pnpm cljs:run-test -v 'logseq.cli.server-test'` and confirm zero failures and zero errors.
+34. Run `pnpm cljs:test && pnpm cljs:run-test -v 'logseq.cli.command.doctor-test'` and confirm zero failures and zero errors.
+35. Run `pnpm cljs:test && pnpm cljs:run-test -v 'logseq.db-worker.ncc-bundle-test'` and confirm zero failures and zero errors.
+36. Run `pnpm db-worker-node:compile` and verify `static/db-worker-node.js` remains valid for local dev flow.
+37. Run `pnpm db-worker-node:release:bundle` and verify `dist/db-worker-node.js` starts successfully with `node dist/db-worker-node.js --help`.
+38. Run `pnpm release-electron` and verify the script execution includes `db-worker-node:release:bundle` before Electron packaging steps.
+39. Run `pnpm cljs:lint && pnpm test` and confirm repository review checklist passes.
+40. Validate changed code against `@prompts/review.md` before merge.
+
+## Edge cases to validate during implementation
+
+| Scenario | Expected behavior |
+| --- | --- |
+| `ncc` emits native `.node` assets for `better-sqlite3`. | Bundle output keeps those assets adjacent to entrypoint and runtime loads without `node_modules`. |
+| Bundle is copied to another directory without static files. | Daemon still starts because packaged runtime no longer `require`s `../static/db-worker-node.js`. |
+| Developer runs doctor in source workspace before bundle build. | Doctor reports missing packaged artifact by default, and only checks static runtime when explicitly requested. |
+| `dist/db-worker-node.js` exists but is not readable or is a directory. | Doctor returns `:doctor-script-unreadable` with path detail. |
+| Bundle build is run twice. | Build output remains deterministic and stale ncc artifacts are cleaned safely. |
+| `pnpm release-electron` is run directly. | Release flow still builds db-worker standalone bundle before Electron packaging artifacts are produced. |
+| CLI and Electron share lock for same repo under bundled runtime. | Existing ownership and lock semantics remain unchanged from current behavior. |
+
+## Verification commands and expected outputs
+
+```bash
+pnpm cljs:test && pnpm cljs:run-test -v 'logseq.cli.server-test'
+pnpm cljs:test && pnpm cljs:run-test -v 'logseq.cli.command.doctor-test'
+pnpm cljs:test && pnpm cljs:run-test -v 'logseq.db-worker.ncc-bundle-test'
+pnpm db-worker-node:compile
+pnpm db-worker-node:release:bundle
+pnpm release-electron
+node dist/db-worker-node.js --help
+pnpm cljs:lint && pnpm test
+```
+
+All test commands should finish with `0 failures, 0 errors`.
+
+The bundle command should finish without `MODULE_NOT_FOUND` for runtime dependencies.
+
+`node dist/db-worker-node.js --help` should print daemon help text and exit with code `0`.
+
+## Testing Details
+
+Behavior-focused tests will validate that runtime path resolution, doctor diagnostics, and daemon startup behavior match user-visible expectations.
+
+The standalone smoke test will verify real process startup and HTTP readiness in a bundle-only filesystem layout, rather than asserting internal helper calls.
+
+Regression safety is provided by existing CLI server and doctor tests to ensure lock lifecycle and error-code contracts remain stable.
+
+## Implementation Details
+
+- Keep packaged runtime path as one canonical helper shared by spawn and doctor.
+- Keep dev runtime path explicit and opt-in for local diagnostics only.
+- Introduce ncc build scripts with deterministic output normalization into `dist/`.
+- Preserve local `shadow-cljs` development flow and avoid slowing watch mode.
+- Add a dedicated standalone bundle smoke test namespace for runtime validation.
+- Keep error code contracts stable for doctor and server command callers.
+- Ensure package `files` include all ncc runtime assets required at execution time.
+- Document build and troubleshooting steps in CLI docs for contributors and release workflows.
+- Use `@test-driven-development` for every behavior change and follow `@clojure-debug` for unexpected failures.
+- Finish with full lint and test validation and checklist review from `@prompts/review.md`.
+
+## Question
+
+Resolved: choose option 1.
+
+`doctor` defaults to strict packaged-runtime validation only.
+
+`doctor` does not auto-fallback to static runtime without an explicit flag.
+
+---
diff --git a/docs/agent-guide/037-db-worker-node-node-sqlite.md b/docs/agent-guide/037-db-worker-node-node-sqlite.md
new file mode 100644
index 0000000000..2701ba92b6
--- /dev/null
+++ b/docs/agent-guide/037-db-worker-node-node-sqlite.md
@@ -0,0 +1,166 @@
+# db-worker-node Node Built-in SQLite Migration Implementation Plan
+
+Goal: Replace `better-sqlite3` in `db-worker-node` with Node.js built-in `node:sqlite` while keeping `logseq-cli` behavior and db-worker thread-api contracts unchanged.
+
+Architecture: Keep the existing platform adapter boundary in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs` and swap only the Node SQLite backend implementation to a compatibility wrapper around `DatabaseSync` and `StatementSync`.
+Architecture: Preserve daemon lifecycle and lock ownership semantics, then update bundle/test/doc assumptions that currently depend on native `.node` assets from `better-sqlite3`.
+
+Tech Stack: ClojureScript, `shadow-cljs` `:node-script`, Node.js `>=22.20.0`, `node:sqlite`, `@vercel/ncc`, `logseq-cli` HTTP transport.
+
+Related: Builds on `docs/agent-guide/033-desktop-db-worker-node-backend.md` and `docs/agent-guide/036-db-worker-node-ncc-bundling.md`.
+Related: Relates to `docs/agent-guide/task--db-worker-nodejs-compatible.md` and `docs/cli/logseq-cli.md`.
+
+## Problem statement
+
+`db-worker-node` currently requires `better-sqlite3` from `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs`.
+
+`logseq-cli` and Electron desktop both depend on this daemon runtime through `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs`, so backend driver replacement must not change daemon API behavior.
+
+The current ncc bundle plan and tests assume native `.node` assets are emitted and copied next to `dist/db-worker-node.js`, which is specific to `better-sqlite3` and must be revised after migration.
+
+Node.js in this repository is already pinned to `>=22.20.0` in `/Users/rcmerci/gh-repos/logseq/package.json`, so `node:sqlite` is available, but it is still experimental and emits runtime warnings that we need to account for.
+
+## Current implementation map
+
+| Area | Current implementation | Migration impact |
+| --- | --- | --- |
+| Node sqlite adapter | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs` wraps `better-sqlite3` with custom `exec` and `transaction` behavior. | Replace constructor and statement execution with `node:sqlite` API while preserving wrapper contract. |
+| Daemon runtime contract | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` exposes `/healthz`, `/readyz`, `/v1/invoke`, `/v1/events`. | No protocol change allowed. |
+| CLI runtime spawn | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` spawns `dist/db-worker-node.js`. | Behavior must remain unchanged. |
+| Bundle smoke tests | `/Users/rcmerci/gh-repos/logseq/src/test/logseq/db_worker/ncc_bundle_test.cljs` expects a missing native `.node` asset failure mode. | Replace asset assertions to match built-in sqlite runtime with zero native assets. |
+| Dependency declaration | `/Users/rcmerci/gh-repos/logseq/package.json` includes `better-sqlite3`. | Remove dependency and refresh lockfile. |
+| CLI documentation | `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` references `dist/build/Release/better_sqlite3.node`. | Update build output description and troubleshooting text. |
+
+## Target architecture
+
+```text
+logseq-cli / electron
+  -> db-worker-node HTTP API
+    -> frontend.worker.db-core
+      -> frontend.worker.platform.node sqlite wrapper
+        -> node:sqlite DatabaseSync
+          -> graph-dir/*.sqlite files
+```
+
+The wrapper contract consumed by db-core remains `open-db`, `exec`, `transaction`, and `close`.
+
+The wrapper implementation changes from `better-sqlite3` to `node:sqlite` internals only.
+
+## Testing Plan
+
+I will use `@test-driven-development` and add failing tests first for adapter behavior and bundle assumptions before modifying runtime code.
+
+I will add focused Node adapter tests for parameter binding, array-row reads, commit behavior, and rollback behavior so the compatibility wrapper is behavior-locked.
+
+I will keep existing daemon smoke tests and CLI sqlite import/export integration tests as end-to-end regression guards.
+
+I will update ncc bundle tests so they validate standalone runtime startup without relying on native `.node` artifacts.
+
+I will run `bb dev:test` for focused namespaces first, then run `bb dev:lint-and-test` for the repository checklist.
+
+I will use `@clojure-debug` if any ClojureScript test fails unexpectedly while porting the adapter.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Implementation plan
+
+### Phase 1: Lock behavior with failing tests.
+
+1. Add a new test namespace at `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/platform_node_test.cljs` to cover Node sqlite wrapper behavior in isolation.
+2. Add a failing test that `exec` with SQL string creates schema and writes data through the wrapper.
+3. Add a failing test that `exec` with `{:sql ... :bind ... :rowMode "array"}` returns array rows in the same shape used by `restore-data-from-addr`.
+4. Add a failing test that named bindings with `$name` and `:name` styles are both accepted by the wrapper.
+5. Add a failing test that wrapper `transaction` commits writes on success.
+6. Add a failing test that wrapper `transaction` rolls back writes when callback throws.
+7. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/db_worker/ncc_bundle_test.cljs` asserting bundled runtime can start even when bundle manifest has zero assets.
+8. Replace the current missing-native-asset expectation test with a failing test that checks bundle manifest format and actionable errors for missing manifest or missing entry script instead.
+9. Run `bb dev:test -v 'frontend.worker.platform-node-test'` and confirm failures before implementation.
+10. Run `bb dev:test -v 'logseq.db-worker.ncc-bundle-test'` and confirm failures before implementation.
+
+### Phase 2: Port Node sqlite adapter to node:sqlite.
+
+11. Edit `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs` to replace `"better-sqlite3"` require with `"node:sqlite"`.
+12. Build a `DatabaseSync` constructor resolver compatible with Shadow-CLJS interop and avoid default-export assumptions.
+13. Keep `open-sqlite-db` async shape unchanged and create `DatabaseSync` after ensuring parent directory exists.
+14. Re-implement statement execution so `:rowMode "array"` maps to `StatementSync#setReturnArrays(true)`.
+15. Re-implement positional and named parameter passing for array and object binds without changing db-core callsites.
+16. Preserve existing bind key normalization behavior for `$name` and `:name` forms to avoid hidden regressions.
+17. Re-implement wrapper `transaction` semantics using explicit SQL transaction control with rollback on exceptions.
+18. Add nested-transaction safety via savepoint naming or equivalent deterministic strategy to avoid partial writes from nested calls.
+19. Keep wrapper `close` idempotent and compatible with existing shutdown paths in `db-core` and daemon stop.
+20. Keep all public platform map keys unchanged in `node-platform`.
+
+### Phase 3: Update dependency and bundle assumptions.
+
+21. Remove `better-sqlite3` from `/Users/rcmerci/gh-repos/logseq/package.json` dependencies.
+22. Run `pnpm install` to refresh `/Users/rcmerci/gh-repos/logseq/pnpm-lock.yaml` and verify `better-sqlite3` is removed from runtime dependency graph.
+23. Verify no remaining runtime require for `better-sqlite3` via `rg -n "better-sqlite3" /Users/rcmerci/gh-repos/logseq/src /Users/rcmerci/gh-repos/logseq/package.json /Users/rcmerci/gh-repos/logseq/pnpm-lock.yaml`.
+24. Keep `/Users/rcmerci/gh-repos/logseq/scripts/package.json` unchanged in this task because scope is limited to `logseq-cli` and `db-worker-node` runtime paths.
+25. Update `/Users/rcmerci/gh-repos/logseq/scripts/build-db-worker-node-bundle.mjs` only if manifest handling needs explicit support for empty asset arrays.
+
+### Phase 4: Refresh tests and docs around runtime packaging.
+
+26. Update `/Users/rcmerci/gh-repos/logseq/src/test/logseq/db_worker/ncc_bundle_test.cljs` to stop asserting a required `.node` asset exists.
+27. Keep startup smoke test that runs copied `db-worker-node.js` from a temporary runtime directory with no `node_modules`.
+28. Add assertions that `/healthz`, `/readyz`, and `/v1/shutdown` still work under bundled runtime.
+29. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` build section to remove `better_sqlite3.node` runtime-asset example.
+30. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` troubleshooting text to describe expected bundle output when native assets are absent.
+31. Update references in `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/task--db-worker-nodejs-compatible.md` to reflect that Node runtime now uses built-in sqlite.
+
+### Phase 5: Run regression and verification commands.
+
+32. Run `bb dev:test -v 'frontend.worker.platform-node-test'` and expect `0 failures, 0 errors`.
+33. Run `bb dev:test -v 'frontend.worker.db-worker-node-test/db-worker-node-daemon-smoke-test'` and expect daemon startup and query path to pass.
+34. Run `bb dev:test -v 'frontend.worker.db-worker-node-test/db-worker-node-import-db-base64'` and expect sqlite export/import behavior to pass.
+35. Run `bb dev:test -v 'logseq.db-worker.ncc-bundle-test'` and expect standalone bundle smoke tests to pass.
+36. Run `bb dev:test -v 'logseq.cli.integration-test/test-cli-graph-export-import-sqlite'` and expect end-to-end CLI sqlite flow to pass.
+37. Run `clojure -M:cljs compile db-worker-node logseq-cli` and expect successful node-script builds.
+38. Run `pnpm db-worker-node:release:bundle` and verify `dist/db-worker-node.js` still starts with `node ./dist/db-worker-node.js --help`.
+39. Run `bb dev:lint-and-test` and expect full lint and test checks to pass.
+40. Review changed files against `/Users/rcmerci/gh-repos/logseq/prompts/review.md` checklist before merge.
+
+## Edge cases to validate during implementation
+
+| Scenario | Expected behavior |
+| --- | --- |
+| Named parameter binding uses `$name` keys from current callsites. | Statement executes without bind-key mismatch errors. |
+| Named parameter binding uses `:name` keys from normalized callsites. | Statement executes and returns same data as before. |
+| `rowMode` is `"array"` for kv restore reads. | First row remains index-addressable for existing `first` and destructuring logic. |
+| Transaction callback throws mid-write. | All writes in that transaction scope are rolled back. |
+| Nested transaction callback occurs inside outer transaction. | Inner failure does not commit partial data and outer behavior is deterministic. |
+| ncc bundle emits zero extra assets. | Bundle tests and CLI docs still treat runtime as valid standalone output. |
+| Daemon starts under Node 22 and emits experimental sqlite warning. | Warning does not break health/readiness checks or CLI invoke flow. |
+| Graph sqlite import/export uses large payloads. | Base64 transport and file writes still preserve binary integrity. |
+
+## Decisions confirmed
+
+1. Keep Node experimental `node:sqlite` warning output as-is for this migration phase; warning suppression and logging policy changes are out of scope.
+2. Scope is limited to `logseq-cli` and `db-worker-node`; do not modify `/Users/rcmerci/gh-repos/logseq/scripts/package.json` in this task.
+3. No temporary fallback flag to `better-sqlite3`; enforce one-way migration to built-in `node:sqlite`.
+4. Treat Node.js `>=22.20.0` as a hard prerequisite for local and CI runtime to ensure `node:sqlite` availability.
+
+## Testing Details
+
+The adapter unit tests will validate observable behavior for SQL execution, parameter binding, row shape, and transaction semantics instead of testing internal helper structure.
+
+The daemon smoke tests will validate real process startup and thread-api calls so platform wiring and lock behavior stay stable.
+
+The CLI integration sqlite export/import test will verify user-visible behavior from command surface to db-worker storage backend.
+
+The bundle tests will validate standalone runtime packaging assumptions that changed because native `.node` assets are no longer required.
+
+## Implementation Details
+
+- Keep `db-worker-node` HTTP and SSE API contracts unchanged.
+- Keep platform adapter keys unchanged to avoid db-core callsite churn.
+- Implement a compatibility wrapper over `DatabaseSync` instead of refactoring db-core.
+- Preserve bind normalization semantics for backward compatibility.
+- Implement explicit rollback-safe transaction handling with nested safety.
+- Remove `better-sqlite3` only from main runtime dependency declarations.
+- Update bundle tests to assert behavior, not driver-specific artifact names.
+- Update CLI docs and historical planning notes that mention native sqlite assets.
+- Require Node.js `>=22.20.0` in local and CI verification environments.
+- Run focused tests first, then repository-wide lint and tests.
+- Follow `@test-driven-development` and `@clojure-debug` for implementation and debugging workflow.
+
+---
diff --git a/docs/agent-guide/038-electron-db-worker-switch-graph.md b/docs/agent-guide/038-electron-db-worker-switch-graph.md
new file mode 100644
index 0000000000..eed3e7acb3
--- /dev/null
+++ b/docs/agent-guide/038-electron-db-worker-switch-graph.md
@@ -0,0 +1,187 @@
+# Electron Db Worker Switch Graph Implementation Plan
+
+Goal: Fix Electron graph switching with db-worker-node so switching to a new graph never leaves the renderer bound to a stopped runtime.
+
+Architecture: Keep db-worker runtime lifecycle in the `db-worker-runtime` path and window close path, and treat `setCurrentGraph` as window graph metadata synchronization only.
+
+Architecture: Remove or guard the duplicate release path in `setCurrentGraph` that can stop the newly started runtime after `persist-db/<fetch-init-data` already switched the window to the new repo.
+
+Architecture: Add regression tests for the switch order and run manual Electron smoke checks that validate runtime continuity and no stale runtime ownership after repeated switches.
+
+Tech Stack: ClojureScript, Electron main process IPC, Promesa, db-worker-node, babashka tests.
+
+Related: Builds on `docs/agent-guide/033-desktop-db-worker-node-backend.md`.
+
+Related: Relates to `docs/agent-guide/034-db-worker-node-owner-process-management.md`.
+
+## Problem statement
+
+Current graph switching in the renderer calls `persist-db/<fetch-init-data` before `state/set-current-repo!`.
+
+In Electron mode, `persist-db/<fetch-init-data` calls `ipc/ipc "db-worker-runtime"` and binds the window to the new repo runtime via `/Users/rcmerci/gh-repos/logseq/src/electron/electron/db_worker.cljs`.
+
+After the runtime is already switched, `state/set-current-repo!` calls `ipc/ipc "setCurrentGraph"` from `/Users/rcmerci/gh-repos/logseq/src/main/frontend/state.cljs`.
+
+`handle :setCurrentGraph` in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/handler.cljs` currently calls `db-worker/release-window!` whenever graph path changes.
+
+That second release runs after the window has already been rebound to the new repo, so it can stop the new runtime and make switch graph fail with downstream invoke errors.
+
+The issue is reproducible when switching between two db graphs in one window with db-worker-node backend enabled.
+
+The expected behavior is that switching from graph A to graph B stops graph A when needed and keeps graph B alive for immediate reads and writes.
+
+## Current and target event sequence
+
+```text
+Current sequence.
+Renderer restore graph B.
+  -> persist-db/<fetch-init-data B.
+  -> ipc "db-worker-runtime" B.
+  -> main db-worker manager switches A -> B.
+  -> state/set-current-repo! B.
+  -> ipc "setCurrentGraph" B.
+  -> handler calls release-window! again.
+  -> B runtime may be stopped unexpectedly.
+
+Target sequence.
+Renderer restore graph B.
+  -> persist-db/<fetch-init-data B.
+  -> ipc "db-worker-runtime" B.
+  -> main db-worker manager switches A -> B.
+  -> state/set-current-repo! B.
+  -> ipc "setCurrentGraph" B.
+  -> handler only updates window graph path.
+  -> B runtime stays available.
+```
+
+## Testing Plan
+
+I will follow `@test-driven-development` and add failing tests before each behavior change.
+
+I will add a failing regression test in `/Users/rcmerci/gh-repos/logseq/src/test/electron/db_worker_manager_test.cljs` that encodes the expected post-switch invariant that the new runtime remains active until explicit release on window close.
+
+I will add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/persist_db_test.cljs` for the graph switch flow to assert runtime rebinding happens once per target repo and is not reinitialized by graph metadata sync.
+
+I will add a focused unit test file `/Users/rcmerci/gh-repos/logseq/src/test/electron/graph_switch_flow_test.cljs` for extracted pure graph-switch decision logic so the release/no-release condition is testable without Electron GUI dependencies.
+
+I will run focused tests after each phase and finish with `bb dev:lint-and-test`.
+
+I will perform manual Electron smoke checks that open graph A, switch to graph B, execute thread-api reads and writes, and then switch back to graph A.
+
+I will review changes against `@prompts/review.md` before merge.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Implementation plan
+
+### Phase 1: Add failing tests that reproduce the switch-order regression.
+
+1. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/electron/db_worker_manager_test.cljs` that simulates A -> B switch and asserts no stop is triggered for B before explicit release.
+2. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/persist_db_test.cljs` for the sequence `<fetch-init-data B` followed by `set-current-repo! B`.
+3. Add `/Users/rcmerci/gh-repos/logseq/src/test/electron/graph_switch_flow_test.cljs` with a failing case that `setCurrentGraph` graph-path synchronization does not request runtime release on normal switch.
+4. Run `bb dev:test -v 'electron.db-worker-manager-test'` and confirm failures match the new assertions.
+5. Run `bb dev:test -v 'frontend.persist-db-test'` and confirm failures match the new assertions.
+
+### Phase 2: Extract graph switch release decision into a pure helper.
+
+6. Add `/Users/rcmerci/gh-repos/logseq/src/electron/electron/graph_switch_flow.cljs` with a pure function that decides when runtime release is allowed during `setCurrentGraph`.
+7. Keep the helper contract explicit with inputs for previous graph identity and next graph identity so race-prone implicit state is avoided.
+8. Make `/Users/rcmerci/gh-repos/logseq/src/test/electron/graph_switch_flow_test.cljs` pass with minimal logic.
+9. Run `bb dev:test -v 'electron.graph-switch-flow-test'` and confirm green.
+
+### Phase 3: Update Electron `setCurrentGraph` handler to avoid stopping the new runtime.
+
+10. Update `handle :setCurrentGraph` in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/handler.cljs` to use the new pure decision helper.
+11. Remove direct unconditional `db-worker/release-window!` on graph-path change from `/Users/rcmerci/gh-repos/logseq/src/electron/electron/handler.cljs`.
+12. Keep window graph-path state updates in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/handler.cljs` unchanged so existing window routing semantics remain stable.
+13. Preserve runtime cleanup responsibility in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/db_worker.cljs` and `/Users/rcmerci/gh-repos/logseq/src/electron/electron/window.cljs`.
+14. Run `bb dev:test -v 'electron.graph-switch-flow-test'` and confirm green.
+
+### Phase 4: Harden manager behavior for repeated switch calls.
+
+15. Add a guard in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/db_worker.cljs` that keeps switch idempotency for repeated `ensure-started!` calls to the same repo and window.
+16. Ensure stale release operations cannot remove a window mapping for a newer repo assignment in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/db_worker.cljs`.
+17. Update `/Users/rcmerci/gh-repos/logseq/src/test/electron/db_worker_manager_test.cljs` assertions to cover stale-release no-op behavior.
+18. Run `bb dev:test -v 'electron.db-worker-manager-test'` and confirm green.
+
+### Phase 5: Verify renderer remote runtime rebinding contract.
+
+19. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/persist_db.cljs` only if needed to keep `<ensure-remote!` single-responsibility for runtime rebinding.
+20. Ensure `/Users/rcmerci/gh-repos/logseq/src/main/frontend/db/restore.cljs` keeps order `<fetch-init-data` before `set-current-repo!` unchanged unless tests prove a safer order is required.
+21. Extend `/Users/rcmerci/gh-repos/logseq/src/test/frontend/persist_db_test.cljs` to assert no duplicate remote stop/start on metadata-only sync.
+22. Run `bb dev:test -v 'frontend.persist-db-test'` and confirm green.
+
+### Phase 6: Add targeted diagnostics and manual smoke script.
+
+23. Add temporary structured logs with `lambdaisland.glogi` in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/db_worker.cljs` around repo switch and release decisions.
+24. Add temporary structured logs in `/Users/rcmerci/gh-repos/logseq/src/electron/electron/handler.cljs` around `setCurrentGraph` branch selection.
+25. Execute manual smoke flow in Electron dev mode by switching A -> B -> A and invoking read and write actions after each switch.
+26. Validate no immediate invoke failures after switch and confirm runtime stays available for the active graph.
+27. Remove temporary logs that are not needed for long-term maintainability.
+
+### Phase 7: Final verification and review gate.
+
+28. Run `bb dev:test -v 'electron.graph-switch-flow-test'`.
+29. Run `bb dev:test -v 'electron.db-worker-manager-test'`.
+30. Run `bb dev:test -v 'frontend.persist-db-test'`.
+31. Run `bb dev:lint-and-test`.
+32. Confirm each command reports `0 failures, 0 errors`.
+33. Run final review checklist pass against `@prompts/review.md`.
+
+## Edge cases
+
+| Scenario | Expected behavior |
+|---|---|
+| Switch A -> B in one window where both graphs are local db graphs. | Runtime for B remains active and calls succeed immediately after switch. |
+| Switch A -> B -> A quickly before all async handlers settle. | Late `setCurrentGraph` sync does not stop the currently active runtime. |
+| Two windows share graph A and one window switches to graph B. | Graph A runtime remains alive for the other window and graph B runtime starts for the switching window. |
+| Re-select current graph B from UI without actual graph change. | No runtime restart and no runtime release occurs. |
+| Window closes right after switch to B. | Runtime release happens exactly once via close flow and does not leave stale window mapping. |
+| Runtime ownership is external (`:owned? false`). | Graph switch does not attempt to stop external runtime unexpectedly. |
+| Restore fails after runtime bind but before UI route redirect. | Failure handling does not silently stop the newly bound runtime unless explicit cleanup path runs. |
+
+## Verification commands and expected outputs
+
+```bash
+bb dev:test -v 'electron.graph-switch-flow-test'
+bb dev:test -v 'electron.db-worker-manager-test'
+bb dev:test -v 'frontend.persist-db-test'
+bb dev:lint-and-test
+```
+
+Each command should finish with `0 failures, 0 errors`.
+
+Manual Electron switch checks should show successful read and write operations immediately after each switch.
+
+No `db-worker invoke failed` errors should appear during normal A -> B -> A switching.
+
+## Testing Details
+
+The new tests verify behavior around event ordering and runtime lifecycle boundaries instead of implementation details.
+
+The manager tests validate that stale or duplicate release operations cannot terminate the active repo runtime.
+
+The frontend tests validate that runtime rebinding is driven by repo changes and not by metadata synchronization calls.
+
+Manual smoke checks validate real Electron runtime behavior that unit tests cannot fully represent.
+
+## Implementation Details
+
+- Keep `setCurrentGraph` focused on graph-path synchronization and remove lifecycle side effects from that path.
+- Keep runtime start and stop orchestration centralized in `electron.db-worker` manager APIs.
+- Use a small pure helper for release decision logic so regression tests do not depend on Electron runtime modules.
+- Preserve existing `db-worker-runtime` IPC contract from renderer to main process.
+- Keep old graph cleanup tied to explicit switch lifecycle and window close lifecycle only.
+- Validate switch behavior with both single-window and multi-window tests.
+- Use `@test-driven-development` for red-green implementation order.
+- Follow `@prompts/review.md` checks before merging.
+
+## Question
+
+Decision: On failed graph restore, keep the newly bound runtime alive for fast retry in the same window.
+
+Decision: Do not add a short-lived debug flag for switch sequencing logs in development builds.
+
+Decision: Add an E2E scenario in `/Users/rcmerci/gh-repos/logseq/clj-e2e` for switch graph with db-worker-node and treat it as a release gate.
+
+---
diff --git a/docs/agent-guide/039-worker-platform-abstraction-cleanup.md b/docs/agent-guide/039-worker-platform-abstraction-cleanup.md
new file mode 100644
index 0000000000..2bc4e3762c
--- /dev/null
+++ b/docs/agent-guide/039-worker-platform-abstraction-cleanup.md
@@ -0,0 +1,213 @@
+# Worker Platform Abstraction Cleanup Implementation Plan
+
+Goal: Route shared db-worker sync code through `frontend.worker.platform` wrappers so browser and node runtimes both work without runtime-specific branches in shared modules.
+
+Architecture: Keep runtime-specific APIs inside `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/browser.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs`.
+Call platform capabilities from shared modules via `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform.cljs` using `platform/current` at the call site.
+Preserve existing key names and payload shapes to avoid data migration.
+
+Tech Stack: ClojureScript, promesa, cljs.test, clojure-lsp diagnostics, db-worker platform adapters.
+
+Related: Relates to `docs/agent-guide/038-electron-db-worker-switch-graph.md` and `docs/agent-guide/db-sync/db-sync-guide.md`.
+
+## Problem statement
+
+`frontend.worker.platform` currently exposes public wrappers that clojure-lsp reports as unused.
+
+The reported vars are `kv-get`, `kv-set!`, `read-text!`, `write-text!`, and `websocket-connect`.
+
+Shared worker modules still contain runtime-specific calls that bypass those wrappers.
+
+The bypasses are concentrated in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs`.
+
+This creates duplicated runtime assumptions and weakens node and browser parity.
+
+| Symptom | Current location | Impact |
+|---|---|---|
+| `clojure-lsp/unused-public-var` on `platform/kv-get` and `platform/kv-set!` | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform.cljs` | Signals shared code is not using the adapter path for kv persistence. |
+| `clojure-lsp/unused-public-var` on `platform/read-text!` and `platform/write-text!` | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform.cljs` | Signals text file I/O in shared code can still hardcode a backend. |
+| `clojure-lsp/unused-public-var` on `platform/websocket-connect` | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform.cljs` | Signals websocket creation in shared sync code may bypass node adapter (`ws`). |
+| Direct `js/WebSocket.` in shared sync module | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` | Couples shared sync lifecycle to browser global API. |
+| Direct `opfs/<read-text!` and `opfs/<write-text!` in shared crypt module | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` | Couples password persistence fallback to OPFS path. |
+| Direct idb key-value calls in shared crypt module | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` | Bypasses node kv adapter path and keeps duplicate kv plumbing. |
+
+```text
+Current shared path.
+db_core -> sync.cljs -> js/WebSocket.
+db_core -> sync/crypt.cljs -> opfs/idb-keyval.
+
+Target shared path.
+db_core -> sync.cljs -> platform/websocket-connect.
+db_core -> sync/crypt.cljs -> platform/read-text!/write-text!/kv-get/kv-set!.
+
+Runtime adapter ownership.
+browser adapter -> OPFS + IndexedDB + browser WebSocket.
+node adapter -> fs + JSON kv file + ws package.
+```
+
+## Testing Plan
+
+I will add a unit test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` that asserts `#'db-sync/connect!` creates sockets through `platform/websocket-connect` and not direct globals.
+
+I will write the test by stubbing `platform/current`, `platform/websocket-connect`, and `#'db-sync/attach-ws-handlers!` to verify the adapter call receives the tokenized URL.
+
+I will add unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/sync/crypt_test.cljs` that assert non-native password read and write paths call `platform/read-text!` and `platform/write-text!`.
+
+I will add a unit test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/sync/crypt_test.cljs` that asserts native write fallback uses `platform/write-text!` when main-thread persistence fails.
+
+I will add unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/sync/crypt_test.cljs` that assert encrypted AES key cache I/O flows through `platform/kv-get`, `platform/kv-set!`, and `platform/current`.
+
+I will run each new test case first and confirm failure before implementation changes using `@test-driven-development`.
+
+I will then run targeted suites and expect all tests to pass.
+
+I will run `bb dev:test -v frontend.worker.db-sync-test` and expect `0 failures, 0 errors`.
+
+I will run `bb dev:test -v frontend.worker.sync.crypt-test` and expect `0 failures, 0 errors` for the selected non-`:fix-me` cases.
+
+I will run `bb dev:lint-and-test` and expect lint plus unit test completion without new warnings in touched namespaces.
+
+I will verify clojure-lsp diagnostics no longer report `clojure-lsp/unused-public-var` for the five wrapper vars in `frontend.worker.platform`.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Scope and non-goals
+
+This plan changes shared worker modules that should remain runtime-agnostic.
+
+This plan does not change browser or node adapter implementations except where signature alignment is required.
+
+This plan does not redesign db-sync protocol or e2ee crypto flow.
+
+This plan does not migrate persisted data keys.
+
+This plan is intentionally limited to the exact five wrapper warnings first.
+
+This plan includes migrating encrypted AES key cache access in `sync/crypt.cljs` to `platform/kv-get` and `platform/kv-set!` because it is in scope of those warnings.
+
+This plan does not include unrelated broader idb migration outside these touched shared worker paths.
+
+## Implementation steps
+
+1. Add a failing websocket adapter test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` for `#'db-sync/connect!`.
+
+2. Run `bb dev:test -v frontend.worker.db-sync-test` and confirm the new test fails because the code still uses direct `js/WebSocket.`.
+
+3. Add `frontend.worker.platform` require alias in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs`.
+
+4. Replace the socket constructor in `connect!` with `(platform/websocket-connect (platform/current) ...)`.
+
+5. Run `bb dev:test -v frontend.worker.db-sync-test` and confirm the websocket adapter test passes.
+
+6. Add a failing non-native read and write adapter test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/sync/crypt_test.cljs`.
+
+7. Add a failing native fallback test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/sync/crypt_test.cljs` that forces native save failure and expects `platform/write-text!`.
+
+8. Add a failing kv adapter test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/sync/crypt_test.cljs` for AES key cache persistence path.
+
+9. Run `bb dev:test -v frontend.worker.sync.crypt-test` and confirm new tests fail before implementation.
+
+10. Add `frontend.worker.platform` require alias in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs`.
+
+11. Replace direct password file I/O calls with `platform/read-text!` and `platform/write-text!` against `(platform/current)`.
+
+12. Replace direct encrypted AES cache idb calls with `platform/kv-get` and `platform/kv-set!` against `(platform/current)`.
+
+13. Keep key format exactly as `rtc-encrypted-aes-key###<graph-id>` to preserve existing browser data compatibility.
+
+14. Remove now-unused direct OPFS and idb-keyval requirements from `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` if no longer referenced.
+
+15. Re-run `bb dev:test -v frontend.worker.sync.crypt-test` and confirm all new tests pass.
+
+16. Re-run `bb dev:test -v frontend.worker.db-sync-test` and confirm no regressions from sync namespace changes.
+
+17. Run `bb dev:lint-and-test` and confirm there are no new lint or test regressions.
+
+18. Verify editor or CI diagnostics no longer show the five `frontend.worker.platform` unused-public-var warnings.
+
+19. If any wrapper remains unused, decide whether to add a real call site or convert that wrapper to private in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform.cljs`.
+
+20. Document verification evidence and remaining caveats in the PR description.
+
+## Edge cases and risk controls
+
+Native worker password flow must keep current behavior that first attempts main-thread persistence and falls back on local storage write.
+
+Node runtime may not expose browser globals, so all shared websocket construction must pass through the adapter.
+
+Key-value persistence must keep existing key naming to avoid cache misses for already stored encrypted graph AES keys.
+
+The adapter functions may return promises, so call sites must preserve existing `p/let` sequencing and error paths.
+
+If `platform/current` is unset in tests, failures should be explicit and tests should set a minimal platform map.
+
+## Clarified decisions before coding
+
+Encrypted AES key cache in `sync/crypt.cljs` will migrate from direct idb store to platform kv now.
+
+Removal of the five `unused-public-var` warnings is mandatory acceptance criteria.
+
+Tests remain colocated in `db_sync_test.cljs` and `sync/crypt_test.cljs` instead of adding a dedicated platform test namespace.
+
+## Verification commands
+
+```bash
+bb dev:test -v frontend.worker.db-sync-test
+```
+
+Expected output contains the new websocket adapter test name and ends with zero failures.
+
+```bash
+bb dev:test -v frontend.worker.sync.crypt-test
+```
+
+Expected output contains new adapter usage tests and ends with zero failures for executed tests.
+
+```bash
+bb dev:lint-and-test
+```
+
+Expected output finishes lint plus test pipeline without new errors in touched files.
+
+## Skills to apply during implementation
+
+Use `@test-driven-development` for all behavior changes.
+
+Use `@clojure-debug` immediately when any new test fails unexpectedly.
+
+Use `@clojure-paren-repair` if Clojure delimiter errors occur while editing touched namespaces.
+
+## Testing Details
+
+Tests focus on externally visible behavior of shared worker modules choosing runtime behavior through adapter calls.
+
+The websocket test validates the constructor path and tokenized URL input instead of testing internal locals.
+
+The crypt tests validate fallback and persistence behavior through adapter interaction and returned outcomes.
+
+The kv cache tests validate read and write behavior by key and value flow rather than implementation-specific helpers.
+
+## Implementation Details
+
+- Touch `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` to route socket creation through `platform/websocket-connect`.
+- Touch `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` to route text and kv persistence through platform wrappers.
+- Touch `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` to add websocket adapter behavior tests.
+- Touch `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/sync/crypt_test.cljs` to add adapter-backed storage and kv behavior tests.
+- Preserve existing e2ee key naming and payload shapes.
+- Keep adapter interface unchanged unless tests prove a missing capability.
+- Prefer removing obsolete direct dependencies once wrappers are adopted.
+- Keep all new logic promise-safe with existing `promesa` flow.
+- Validate clojure-lsp warning cleanup for all five wrapper vars.
+- Keep PR scoped to abstraction usage cleanup and tests only.
+
+## Question
+
+Confirmed scope: limit this effort to the exact five wrapper warnings first.
+
+Confirmed decision: migrate encrypted AES key cache usage in `sync/crypt.cljs` to platform kv in this pass.
+
+Confirmed quality gate: the five `unused-public-var` warnings must be cleared.
+
+Confirmed test placement: keep new tests in existing `db_sync_test.cljs` and `sync/crypt_test.cljs`.
+
+---
diff --git a/docs/agent-guide/040-hide-db-prefix-in-user-visible-graph-names.md b/docs/agent-guide/040-hide-db-prefix-in-user-visible-graph-names.md
new file mode 100644
index 0000000000..e26f5a5c23
--- /dev/null
+++ b/docs/agent-guide/040-hide-db-prefix-in-user-visible-graph-names.md
@@ -0,0 +1,204 @@
+# Hide Db Prefix In User Visible Graph Names Implementation Plan
+
+Goal: Ensure user-visible graph names strip exactly one leading `logseq_db_` prefix while preventing new multi-prefix repos from being created.
+
+Architecture: Keep display normalization as single-pass prefix stripping for web, Electron, and CLI user-facing fields.
+
+Architecture: Add shared canonicalization at ingestion and graph-discovery boundaries so internal repo identifiers are normalized to exactly one leading prefix before persistence and routing.
+
+Architecture: Follow `@test-driven-development` with failing tests first across frontend, Electron boundary code, RTC ingestion, and CLI paths.
+
+Tech Stack: ClojureScript, Rum, Electron IPC, db-worker-node runtime, Logseq CLI formatting pipeline, Babashka tests.
+
+Related: Relates to `docs/agent-guide/033-desktop-db-worker-node-backend.md`.
+
+Related: Builds on `docs/agent-guide/038-electron-db-worker-switch-graph.md`.
+
+## Problem statement
+
+Graph names shown in the web graph list can expose `logseq_db_` when the stored repo value has multiple leading prefixes.
+
+Current rendering logic intentionally strips only one leading prefix, so malformed values like `logseq_db_logseq_db_demo` still render as `logseq_db_demo`.
+
+The product decision is to keep one-layer stripping behavior and fix the upstream causes that create multi-prefix repo identifiers.
+
+Multi-prefix data can enter through legacy disk graph discovery, Electron graph mapping, RTC remote metadata ingestion, and CLI graph-name conversion paths.
+
+The required outcome is stable single-prefix internal repo identifiers plus single-pass display normalization, so normal graphs render as `demo` and malformed legacy doubles render as `logseq_db_demo`.
+
+## Current and target normalization path
+
+```text
+Current path with multi-prefix source data.
+input repo: logseq_db_logseq_db_demo
+  -> display helper strips once
+  -> output: logseq_db_demo
+  -> user-visible prefix leak occurs.
+
+Target path with source canonicalization + single-pass display stripping.
+ingress repo: logseq_db_logseq_db_demo
+  -> canonicalize to one internal prefix: logseq_db_demo
+  -> display helper strips once
+  -> output: demo
+
+Legacy persisted double-prefix fallback path (no migration).
+input repo from old state: logseq_db_logseq_db_demo
+  -> display helper strips once
+  -> output: logseq_db_demo
+```
+
+## Testing Plan
+
+I will follow `@test-driven-development` and write all failing tests before implementation.
+
+I will add frontend unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/util/text_test.cljs` to assert single-pass prefix stripping behavior.
+
+I will add frontend persist tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/db/persist_test.cljs` to assert merged graph sources are canonicalized to one internal prefix before UI state usage.
+
+I will add RTC tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/handler/db_based/rtc_test.cljs` to assert remote graph payload ingestion cannot create local double-prefix repos.
+
+I will extend CLI formatter tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` to assert user-facing fields strip exactly one prefix and never introduce additional prefixes.
+
+I will extend CLI command tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `graph list` and server output paths with unprefixed and prefix-like graph names, and assert prefix-like `--graph` values are treated as graph-name content instead of invalid input.
+
+I will add legacy graph discovery tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/common/graph_test.cljs` to verify old directory names do not produce multi-prefix repo ids.
+
+I will run focused tests after RED and GREEN phases, then run `bb dev:lint-and-test` before completion.
+
+I will review changes against `@prompts/review.md` before merge.
+
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Implementation plan
+
+### Phase 1: Add failing tests for one-layer display stripping and multi-prefix prevention.
+
+1. Add failing unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/util/text_test.cljs` for `logseq_db_demo -> demo`, `logseq_db_logseq_db_demo -> logseq_db_demo`, and middle-substring preservation.
+2. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/db/persist_test.cljs` to verify worker and Electron graph sources are canonicalized to one internal prefix.
+3. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/handler/db_based/rtc_test.cljs` for remote graph mapping and download paths with prefixed and double-prefixed payload names.
+4. Extend `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` with failing cases where `:repo` or `:graph` includes one or two prefixes and output uses one-layer stripping only.
+5. Extend `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` with failing cases for graph list and server output using unprefixed and prefix-like `--graph` values, and assert prefix-like values are not rejected by argument validation.
+6. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/common/graph_test.cljs` for legacy directory names that already contain `logseq_db_`.
+7. Run focused tests and confirm failures reflect behavior gaps rather than setup errors.
+
+### Phase 2: Implement shared helpers for display normalization and repo canonicalization.
+
+8. Add shared helpers in `/Users/rcmerci/gh-repos/logseq/deps/common/src/logseq/common/config.cljs` for single-pass display stripping and exact-one-prefix canonicalization.
+9. Keep display helper semantics strict to remove only one leading prefix and preserve all middle substrings.
+10. Keep canonicalization helper semantics strict to collapse any number of leading prefixes to exactly one.
+11. Use function names that clearly separate display behavior from internal repo id normalization.
+12. Keep helpers pure and dependency-light so they can be reused in frontend, Electron, and CLI namespaces.
+
+### Phase 3: Apply web app fixes with one-layer display semantics.
+
+13. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/util/text.cljs` so `get-graph-name-from-path` calls the shared single-pass display helper.
+14. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/config.cljs` so `db-graph-name` remains one-layer stripping and does not over-strip.
+15. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/db/conn.cljs` so `get-short-repo-name` uses shared one-layer display normalization.
+16. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/components/repo.cljs` rendering paths only if needed to ensure all user-visible labels share one-layer stripping behavior.
+17. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/db/persist.cljs` so merged graph sources are canonicalized to one internal prefix before entering repo state.
+18. Keep `data-testid` and internal routing keys unchanged unless canonicalization is required to prevent multi-prefix key creation.
+
+### Phase 4: Fix Electron and graph discovery paths that can create multi-prefix repos.
+
+19. Update `/Users/rcmerci/gh-repos/logseq/deps/cli/src/logseq/cli/common/graph.cljs` so `get-db-based-graphs` canonicalizes discovered graph repo names to one prefix.
+20. Update `/Users/rcmerci/gh-repos/logseq/src/electron/electron/handler.cljs` and `/Users/rcmerci/gh-repos/logseq/src/electron/electron/utils.cljs` to canonicalize repo identifiers at IPC mapping boundaries.
+21. Verify Electron IPC `getGraphs` keeps stable internal repo identifiers and no path emits new double-prefixed repos.
+
+### Phase 5: Fix RTC ingestion paths that can reintroduce multi-prefix repos.
+
+22. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/db_based/rtc.cljs` so remote graph payload mapping canonicalizes incoming graph names before repo/url construction.
+23. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/rtc/full_upload_download_graph.cljs` so download naming canonicalizes to one internal prefix before local repo creation.
+24. Ensure existing graphs with prefixed remote names remain accessible after normalization.
+25. Ensure new uploads and downloads cannot create `logseq_db_logseq_db_*` local repo ids.
+
+### Phase 6: Apply CLI fixes for one-layer display and one-prefix internal ids.
+
+26. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` so `repo->graph` strips exactly one leading prefix for user-visible output.
+27. Verify `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` uses one-layer display normalization consistently for human, JSON, and EDN user-facing graph fields.
+28. Update `/Users/rcmerci/gh-repos/logseq/deps/cli/src/logseq/cli/commands/graph.cljs` to canonicalize internal repo identifiers before list rendering and server-target resolution.
+29. Ensure CLI parsing and command execution treat `--graph` as a graph-name string, so leading `logseq_db_` is interpreted as part of graph name when present and is not rejected by input validation.
+
+### Phase 7: Verification and release gate.
+
+30. Run `bb dev:test -v 'frontend.util.text-test'` and confirm one-layer strip behavior and canonicalization tests pass.
+31. Run `bb dev:test -v 'frontend.db.persist-test'` and confirm merged-source canonicalization behavior is stable.
+32. Run `bb dev:test -v 'frontend.handler.db-based.rtc-test'` and confirm remote ingestion cannot produce multi-prefix repos.
+33. Run `bb dev:test -v 'logseq.cli.format-test'` and confirm CLI display fields apply one-layer strip behavior.
+34. Run `bb dev:test -v 'logseq.cli.commands-test'` and confirm graph command behavior remains stable with unprefixed and prefix-like `--graph` input.
+35. Run `bb dev:test -v 'logseq.cli.common.graph-test'` and confirm legacy graph discovery does not emit double-prefixed repo names.
+36. Run `bb dev:lint-and-test` and confirm `0 failures, 0 errors`.
+37. Perform a manual graph-list smoke check on web and Electron to confirm normal graphs display without prefix and legacy doubles display with one remaining prefix.
+38. Perform a manual CLI smoke check with `logseq graph list`, `logseq server status --graph demo`, and `logseq server status --graph logseq_db_demo` to confirm both inputs are accepted as graph names.
+
+## Edge cases
+
+| Scenario | Expected behavior |
+|---|---|
+| Internal repo is `logseq_db_demo`. | User-visible name is `demo`. |
+| Internal repo is `logseq_db_logseq_db_demo`. | User-visible name is `logseq_db_demo`. |
+| Graph name contains middle substring like `my_logseq_db_notes`. | Middle substring is preserved and only one leading prefix is removed when present. |
+| Legacy disk directory is named `logseq_db_demo`. | Discovery canonicalization keeps exactly one prefix and does not create `logseq_db_logseq_db_demo`. |
+| Legacy disk directory is named `logseq_db_logseq_db_demo`. | Discovery canonicalization collapses to internal repo `logseq_db_demo`. |
+| Remote graph payload returns `graph-name` as `logseq_db_demo`. | RTC mapping keeps internal repo `logseq_db_demo` and user-visible name `demo`. |
+| Remote graph payload returns `graph-name` as `logseq_db_logseq_db_demo`. | RTC mapping canonicalizes to internal repo `logseq_db_demo`, and user-visible name is `demo` after one-layer display strip. |
+| CLI receives `--graph demo`. | Command works and output graph name is `demo`. |
+| CLI receives `--graph logseq_db_demo`. | Command treats `logseq_db_` as part of graph name and does not fail argument validation. |
+| CLI receives `--graph logseq_db_logseq_db_demo`. | Command treats the full value as graph name content and does not fail argument validation. |
+| Non-user-visible fields like `data-testid` include repo id. | Existing selectors remain unchanged unless canonicalization is required to prevent duplicate graph entries. |
+
+## Verification commands and expected outputs
+
+```bash
+bb dev:test -v 'frontend.util.text-test'
+bb dev:test -v 'frontend.db.persist-test'
+bb dev:test -v 'frontend.handler.db-based.rtc-test'
+bb dev:test -v 'logseq.cli.format-test'
+bb dev:test -v 'logseq.cli.commands-test'
+bb dev:test -v 'logseq.cli.common.graph-test'
+bb dev:lint-and-test
+```
+
+Each command should finish with `0 failures, 0 errors`.
+
+Web and Electron manual checks should show no new multi-prefix repo entries.
+
+Web and Electron display should strip one prefix only at render time.
+
+CLI human output should match one-layer strip semantics, and CLI `--graph` should treat prefix-like values as normal graph names.
+
+## Testing Details
+
+The tests verify user-visible behavior and repo-id canonicalization at ingress and discovery boundaries.
+
+Frontend tests assert display output and merged-state behavior rather than helper internals alone.
+
+RTC and Electron tests assert that incoming prefixed names cannot generate additional prefixes in local repo ids.
+
+CLI tests assert command behavior and output formatting remain stable for unprefixed and prefix-like graph-name input.
+
+## Implementation Details
+
+- Keep display normalization as single-pass prefix stripping.
+- Add one shared helper for exact-one-prefix repo canonicalization.
+- Canonicalize ingress and discovery data before it reaches persistent repo state.
+- Reuse shared helpers across frontend, Electron, and CLI.
+- Preserve `data-testid` compatibility unless canonicalization makes key updates unavoidable.
+- Avoid one-time metadata migration for existing persisted graphs.
+- Treat CLI `--graph` input as raw graph name where `logseq_db_` may be part of the name.
+- Keep internal thread-api contracts based on prefixed repo ids.
+- Follow `@test-driven-development` for RED, GREEN, and REFACTOR order.
+- Validate final patch with `@prompts/review.md` checklist.
+
+## Question
+
+Decision: Display normalization removes only one leading prefix, so `logseq_db_logseq_db_xxxx` displays as `logseq_db_xxxx` in app surfaces that read legacy uncanonicalized values.
+
+Decision: The implementation focus is to identify and fix all paths that can create multi-prefix repo identifiers, so newly produced data stays canonical.
+
+Decision: This change does not include a one-time metadata migration for existing persisted legacy values.
+
+Decision: CLI `--graph` option treats leading `logseq_db_` as graph-name content, not as forbidden prefix.
+
+Decision: Treat `data-testid` stability as a strict compatibility requirement for `clj-e2e`.
+
+---
diff --git a/docs/agent-guide/041-logseq-cli-add-block-json-identifiers.md b/docs/agent-guide/041-logseq-cli-add-block-json-identifiers.md
new file mode 100644
index 0000000000..c3b0e28b86
--- /dev/null
+++ b/docs/agent-guide/041-logseq-cli-add-block-json-identifiers.md
@@ -0,0 +1,171 @@
+# Logseq CLI Add Command Entity Id Output Implementation Plan
+
+Goal: Make `add page` and `add block` return newly created entity `db/id` in `--output human`, `--output json`, and `--output edn`.
+
+Architecture: Keep existing add command write paths and add a post-write identifier resolution step in the CLI command layer.
+Architecture: Return a unified structured payload for both add commands where `:result` is a vector of created entity `db/id`.
+Architecture: Update human formatter for add commands to include created entity ids while preserving existing success semantics.
+
+Tech Stack: ClojureScript, Logseq CLI command layer, db-worker-node thread API, Logseq CLI formatter.
+
+Related: Builds on docs/agent-guide/027-logseq-cli-update-command.md and docs/agent-guide/005-logseq-cli-output-and-db-worker-node-log.md.
+
+Document naming follows @planning-documents using the next available sequence number `041`.
+
+## Problem statement
+
+Current behavior for `add block --output json` is `{"status":"ok","data":{"result":null}}` because `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` sets `:result nil` in `execute-add-block`.
+
+Current add command outputs are not consistent for machine and human flows when users need the new entity id immediately.
+
+Users now require `db/id` in all output formats for both `add page` and `add block`.
+
+Without this output, automation must run extra commands to locate newly created entities before `update` or `remove`.
+
+## Testing Plan
+
+I will follow @test-driven-development and complete all RED tests before implementation.
+
+I will add integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `add page --output json` and `add block --output json` asserting returned `db/id`.
+
+I will add integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `add page --output edn` and `add block --output edn` asserting returned `:db/id`.
+
+I will add formatter tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` asserting human output lines for add page and add block include new ids.
+
+I will add one integration chain test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that uses returned add ids directly in `update` and `remove` commands.
+
+I will add a focused unit test namespace at `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/add_test.cljs` for helper logic that builds the created-entity result payload.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Architecture sketch
+
+```
+add page/add block
+  -> /src/main/logseq/cli/command/add.cljs execute-add-*
+  -> thread-api write call
+  -> resolve created entity ids in CLI command layer
+  -> result payload {:result [id1 id2 ...]}
+  -> /src/main/logseq/cli/format.cljs human renderer includes id information
+```
+
+## Output contract
+
+JSON output for add page returns created page id vector in `data.result`.
+
+JSON output for add block returns created block ids in `data.result`.
+
+EDN output mirrors the same data shape using keyword keys.
+
+Human output includes created ids for both commands.
+
+Example human output for add page is:
+
+```text
+Added page:
+[123]
+```
+
+Example human output for add block is:
+
+```text
+Added blocks:
+[101 102]
+```
+
+## Plan
+
+1. Read `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` and confirm current add page and add block result payload shapes.
+2. Read `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` and confirm current human formatter paths for add commands.
+3. Write RED integration test A in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for add page JSON result containing created page `db/id`.
+4. Write RED integration test B in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for add block JSON result containing created block `db/id` list.
+5. Write RED integration test C in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for add page and add block EDN output containing `:db/id`.
+6. Write RED formatter tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` asserting human add output includes ids.
+7. Write RED unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/add_test.cljs` for id vector normalization and deterministic ordering.
+8. Run focused tests and verify failures are caused by missing behavior and not incorrect test setup.
+9. Implement add block result enrichment in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` so it returns all created block ids including nested children.
+10. Implement add page result enrichment in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` so it returns created page id as a one-element vector.
+11. Keep result field naming stable with a shape `:data {:result [101 102]}`.
+12. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` add page and add block human renderers to include id data from command result.
+13. Ensure JSON and EDN formatter paths continue to serialize the enriched result without special-case regressions.
+14. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` with add page and add block structured output examples that include `db/id`.
+15. Run focused tests again and verify GREEN behavior for all newly added tests.
+16. Refactor helper naming and duplicate mapping code in add command execution if needed without behavior change.
+17. Re-run focused tests after refactor to verify tests stay green.
+18. Run `bb dev:lint-and-test` for regression verification.
+
+## Edge cases
+
+Add block from `--content` must still return generated block id when UUID was not supplied in input.
+
+Add block from `--blocks` with multiple nested blocks must return all created ids and use deterministic ordering in returned payload.
+
+Add page should return the created page id even when tags and properties are added in the same command.
+
+Add block human output should remain readable when returning many ids including nested children.
+
+When id resolution fails unexpectedly after a successful write, command should return an error rather than a misleading success payload without ids.
+
+Error output format and exit codes must remain unchanged for invalid input and missing target cases.
+
+## Testing commands and expected output
+
+Run focused RED tests.
+
+```bash
+bb dev:test -v 'logseq.cli.integration-test/test-cli-add-page-json-output-returns-id'
+bb dev:test -v 'logseq.cli.integration-test/test-cli-add-block-json-output-returns-ids'
+bb dev:test -v 'logseq.cli.integration-test/test-cli-add-page-block-edn-output-returns-id'
+bb dev:test -v 'logseq.cli.format-test/test-human-output-add-remove'
+```
+
+Expected RED output includes assertion failures indicating missing id fields in add outputs.
+
+Run focused GREEN tests after implementation.
+
+```bash
+bb dev:test -v 'logseq.cli.integration-test/test-cli-add-page-json-output-returns-id'
+bb dev:test -v 'logseq.cli.integration-test/test-cli-add-block-json-output-returns-ids'
+bb dev:test -v 'logseq.cli.integration-test/test-cli-add-page-block-edn-output-returns-id'
+bb dev:test -v 'logseq.cli.integration-test/test-cli-add-identifiers-chain-update-remove'
+bb dev:test -v 'logseq.cli.command.add-test'
+bb dev:test -v 'logseq.cli.format-test/test-human-output-add-remove'
+```
+
+Expected GREEN output includes zero failures and zero errors for the focused namespaces.
+
+Run full verification.
+
+```bash
+bb dev:lint-and-test
+```
+
+Expected output includes successful lint and tests with exit code `0`.
+
+## Testing Details
+
+Integration tests will assert actual CLI command output payloads and real persisted graph behavior for add page and add block.
+
+Formatter tests will assert exact human output strings for add page and add block including id fragments.
+
+Unit tests will validate helper behavior for id list assembly and ordering.
+
+## Implementation Details
+
+- Enrich `execute-add-block` result so `:result` is a vector of all created block ids including nested children.
+- Enrich `execute-add-page` result so `:result` is a one-element vector containing created page id.
+- Keep result payload stable across JSON and EDN output paths by using Clojure maps with keyword keys.
+- Update human formatters for add page and add block to include id information:
+  - add page rendered as `Added page:` on one line and `[123]` on the next line.
+  - add block rendered as `Added blocks:` on one line and `[101 102]` on the next line.
+- Preserve existing command success and error semantics besides the new id output fields.
+- Add integration coverage for add outputs plus id-based `update` and `remove` chaining.
+- Update CLI docs to show the new add page and add block result examples with ids.
+
+## Decisions
+
+Human output for add block must display all created ids including nested children.
+
+For add block and add page, `:result` must be an id vector such as `[101 102]`.
+
+---
diff --git a/docs/agent-guide/042-logseq-cli-add-tag-command.md b/docs/agent-guide/042-logseq-cli-add-tag-command.md
new file mode 100644
index 0000000000..f5d3656573
--- /dev/null
+++ b/docs/agent-guide/042-logseq-cli-add-tag-command.md
@@ -0,0 +1,138 @@
+# Logseq CLI Add Tag Subcommand Implementation Plan
+
+Goal: Add `logseq add tag` so CLI users can create a tag entity before using that tag in `add block`, `add page`, and `update`.
+
+Architecture: Reuse the existing CLI to db-worker-node write path by sending `:create-page` with `{:class? true}` through `:thread-api/apply-outliner-ops`.
+Architecture: Keep db-worker-node protocol and HTTP endpoints unchanged because the feature composes existing worker operations.
+Architecture: Validate the result after write by pulling the page entity and asserting the page has `:logseq.class/Tag` semantics.
+
+Tech Stack: ClojureScript, babashka.cli, Promesa, Datascript, db-worker-node, outliner ops.
+
+Related: Builds on docs/agent-guide/018-logseq-cli-add-tags-builtin-properties.md and docs/agent-guide/041-logseq-cli-add-block-json-identifiers.md.
+
+## Problem statement
+
+Current CLI behavior can attach only existing tags because `resolve-tag-entity` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` fails with `:tag-not-found` when a tag is missing.
+
+Current CLI behavior has no `add tag` command entry in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs`, so users cannot create custom tags from CLI.
+
+Current db-worker-node flow already supports page and class creation through `:thread-api/apply-outliner-ops` and `:create-page`, so the missing capability is command orchestration in CLI instead of worker transport.
+
+`list tag` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/mcp/tools.cljs` returns entities tagged with `:logseq.class/Tag`, so `add tag` must create that exact class shape instead of a plain page.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and write parsing tests before changing command implementation code.
+
+I will add failing action-building tests that verify required options, normalized action payload, and explicit errors for invalid input.
+
+I will add failing execution tests that stub transport calls and verify emitted outliner ops include `:create-page` with `{:class? true}`.
+
+I will add failing format tests for human output so `:add-tag` has a stable success message contract.
+
+I will add one integration test that creates a new tag and then uses that tag in `add block` to prove end to end behavior through db-worker-node.
+
+I will add one integration test that confirms failure when the same title already exists as a non-tag page, so the command does not report false success.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Scope and non-goals
+
+This plan adds only `add tag` under the existing `add` command group.
+
+This plan does not add new db-worker-node endpoints or thread-api methods.
+
+This plan does not add editing features such as setting class extends, class properties, or tag description during creation.
+
+This plan does not change existing `add block`, `add page`, or `update` option syntax.
+
+`add tag` accepts `--name` only, and does not support `--tag` alias.
+
+## Integration overview
+
+```
+logseq add tag --name "Quote"
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs
+  -> db-worker-node /v1/invoke
+  -> :thread-api/apply-outliner-ops
+  -> :create-page [title {:class? true}]
+  -> Datascript entity tagged as :logseq.class/Tag
+```
+
+## Detailed implementation plan
+
+1. Add a failing parser help test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that expects `add` group help to include `add tag`.
+2. Add a failing parser test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `["add" "tag" "--name" "Quote"]` to produce `:add-tag`.
+3. Add a failing parser validation test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that missing `--name` returns `:missing-tag-name`.
+4. Add a failing build-action test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that ensures `:add-tag` action contains `:type`, `:repo`, `:graph`, and normalized `:name`.
+5. Add a failing execute test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that stubs transport and verifies `:create-page` options include `:class? true`.
+6. Add a failing execute test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that simulates existing non-tag page conflict and expects a deterministic CLI error code.
+7. Add a failing format test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for `:add-tag` human output.
+8. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that runs `add tag`, validates `list tag` contains the new tag, and confirms `add block --tags` with that tag succeeds.
+9. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for duplicate title where a normal page exists and command must fail with clear error.
+10. Run focused tests and confirm all new tests fail for behavior reasons, and use `@clojure-debug` only if failures are caused by test setup mistakes.
+11. Extend `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` with a new `add-tag` command spec, entry, action builder, and executor.
+12. In `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs`, implement execution via `:thread-api/apply-outliner-ops` and `[:create-page [name {:class? true}]]`.
+13. In `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs`, add a post-create pull check that verifies the resulting entity is class-tagged and raise an explicit error if not.
+14. Extend `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` parse validation with `:missing-tag-name` handling for `:add-tag`.
+15. Extend `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` action dispatch and execute dispatch for `:add-tag`.
+16. Extend `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` context propagation to include the new tag field used by formatter output.
+17. Extend `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` with `format-add-tag` and command routing for `:add-tag`.
+18. Run focused unit and integration tests and confirm they pass without changing unrelated command behavior.
+19. Run `bb dev:lint-and-test` and confirm the repository remains green after the feature.
+20. Refactor only local helper naming and shared logic inside `add.cljs` while preserving behavior and keeping tests green.
+
+## Edge cases to cover
+
+Tag names with leading `#` should be normalized consistently, or rejected consistently, with one documented behavior.
+
+Tag names containing namespace separators like `A/B` should produce deterministic behavior aligned with existing page creation rules.
+
+Duplicate tag creation should be idempotent when the existing entity is already a tag class.
+
+If a page with the same name exists but is not a tag class, `add tag` should fail with a dedicated error instead of silently succeeding.
+
+Built-in tag names should remain valid and should return existing ids without creating duplicate entities.
+
+The command should reject blank names after trim.
+
+## Verification commands
+
+| Command | Expected result |
+| --- | --- |
+| `bb dev:test -v logseq.cli.commands-test/test-parse-args-help` | New `add tag` appears in add group help assertions. |
+| `bb dev:test -v logseq.cli.commands-test/test-verb-subcommand-parse-add` | New parse and validation tests for `add tag` pass. |
+| `bb dev:test -v logseq.cli.commands-test/test-build-action-inspect-edit` | Build action includes `:add-tag` cases and passes. |
+| `bb dev:test -v logseq.cli.commands-test/test-execute-add-tag-builds-create-page-op` | Outliner op assertions pass with `{:class? true}`. |
+| `bb dev:test -v logseq.cli.format-test/test-human-output-add-remove` | Human output for `:add-tag` matches expected string. |
+| `bb dev:test -v logseq.cli.integration-test/test-cli-add-tag-create-and-use` | End to end creation and usage of a new tag passes. |
+| `bb dev:test -v logseq.cli.integration-test/test-cli-add-tag-rejects-existing-non-tag-page` | Conflict behavior test passes with explicit error. |
+| `bb dev:lint-and-test` | Full lint and unit suite pass. |
+
+## Testing Details
+
+The tests validate user-visible behavior at parser, action, executor, formatter, and integration boundaries.
+
+The tests assert command success and failure contracts, and they verify persisted graph behavior with CLI reads such as `list tag` and `show`.
+
+The tests avoid asserting implementation details that are not externally observable.
+
+## Implementation Details
+
+- Add `add tag` spec and entry in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs`.
+- Add `build-add-tag-action` and `execute-add-tag` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs`.
+- Use existing server bootstrap and transport invoke path from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs`.
+- Create tag through `:create-page` with `{:class? true}` and verify resulting entity semantics.
+- Add parse validation and missing error mapping in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+- Add build and execute routing for `:add-tag` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+- Add human formatter branch for `:add-tag` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`.
+- Add parser and executor unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+- Add formatter test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`.
+- Add integration coverage in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`.
+
+## Question
+
+No open questions.
+
+---
diff --git a/docs/agent-guide/043-logseq-cli-tag-property-management.md b/docs/agent-guide/043-logseq-cli-tag-property-management.md
new file mode 100644
index 0000000000..906a892bcb
--- /dev/null
+++ b/docs/agent-guide/043-logseq-cli-tag-property-management.md
@@ -0,0 +1,182 @@
+# Logseq CLI Tag and Property Management Implementation Plan
+
+Goal: Add first class CLI support for `upsert tag`, `upsert property`, `remove tag`, and `remove property`, and restructure existing remove behavior into `remove block` and `remove page`.
+
+Architecture: Replace current `add tag` command entry with `upsert tag` so tag creation and idempotent update semantics are unified under one verb.
+Architecture: Expand `remove` into typed subcommands (`block`, `page`, `tag`, `property`) to make deletion intent explicit and prevent mixed selector ambiguity.
+Architecture: Reuse `:thread-api/apply-outliner-ops` in db-worker-node so no new HTTP route or transport protocol is introduced.
+
+Tech Stack: ClojureScript, babashka.cli, Promesa, Datascript, db-worker-node, outliner ops.
+
+Related: Builds on docs/agent-guide/042-logseq-cli-add-tag-command.md and docs/agent-guide/029-logseq-cli-show-properties.md.
+
+## Problem statement
+
+Current CLI supports tag creation through `add tag` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs`, but does not expose an `upsert` verb for tags and properties.
+
+Current `update` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/update.cljs` updates tag and property values on blocks, but does not upsert or remove tag/property entities.
+
+Current `remove` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/remove.cljs` mixes block and page deletion under one command, and has no explicit tag/property deletion path.
+
+db-worker-node already supports required mutation primitives through `:thread-api/apply-outliner-ops` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` and outliner ops in `/Users/rcmerci/gh-repos/logseq/deps/outliner/src/logseq/outliner/op.cljs`.
+
+The implementation gap is CLI command surface design, parser wiring, validation, and output contract coverage.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and write failing parser, action, executor, formatter, and integration tests before adding behavior.
+
+I will add parser tests for the new `upsert` verb and the new typed `remove` subcommands.
+
+I will add action builder tests that verify repo propagation, normalized names, schema coercion, and typed action payloads for each new command.
+
+I will add executor tests that stub transport and assert exact outliner ops emitted for each command path.
+
+I will add formatter tests for human and json output so command responses are stable for scripts.
+
+I will add integration tests against db-worker-node that verify graph state changes through `list`, `show`, and entity queries.
+
+I will use `@clojure-debug` only when failures are caused by test setup rather than behavior.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Command contract
+
+The final command surface is top level verbs without a `manage` group.
+
+| Command | Required options | Optional options | Behavior |
+| --- | --- | --- | --- |
+| `logseq upsert tag` | `--name` | none in v1 | Creates tag when missing, returns existing tag when already present, and errors if same title exists as non-tag page. |
+| `logseq upsert property` | `--name` | `--type`, `--cardinality`, `--hide`, `--public` | Creates property when missing, updates schema for existing property, and validates type or cardinality compatibility. |
+| `logseq remove tag` | one of `--name`, `--id` | none | Deletes a tag entity after validating target type and removability, and fails with a candidate list when `--name` matches multiple tags. |
+| `logseq remove property` | one of `--name`, `--id` | none | Deletes a property entity after validating target type and removability, and fails with a candidate list when `--name` matches multiple properties. |
+| `logseq remove block` | one of `--id`, `--uuid` | none | Deletes one or more blocks with existing block remove behavior. |
+| `logseq remove page` | `--name` | none | Deletes a page with existing page remove behavior. |
+
+`add tag` will be removed from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` and replaced by `upsert tag`.
+
+Bare `remove` without a subcommand will be rejected with a clear parse error.
+
+No compatibility aliases or deprecation shims will be kept for removed commands.
+
+## Integration overview
+
+```text
+logseq upsert property --name "owner" --type node --cardinality many
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs (/v1/invoke)
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs (:thread-api/apply-outliner-ops)
+  -> /Users/rcmerci/gh-repos/logseq/deps/outliner/src/logseq/outliner/op.cljs (:upsert-property)
+```
+
+```text
+logseq remove tag --name "Quote"
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/remove.cljs
+  -> remove tag resolver validates :logseq.class/Tag
+  -> :thread-api/apply-outliner-ops with [:delete-page [tag-uuid]]
+  -> outliner page delete flow applies class cleanup and persistence
+```
+
+## Detailed implementation plan
+
+1. Add failing parse help tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that expect top level `upsert` and `remove` subcommands (`block`, `page`, `tag`, `property`).
+2. Add failing parse tests for `['upsert' 'tag' '--name' 'Quote']` and `['upsert' 'property' '--name' 'owner' '--type' 'node' '--cardinality' 'many']` in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+3. Add failing parse tests for `['remove' 'tag' '--name' 'Quote']` and `['remove' 'property' '--id' '123']` in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+4. Add failing parse tests for `['remove' 'block' '--id' '1']` and `['remove' 'page' '--name' 'Home']` to preserve old delete behavior in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+5. Add failing parse validation tests that reject bare `remove` and old `add tag` command usage in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+6. Add failing parse validation tests for invalid property type and cardinality values in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+7. Add failing build action tests for `upsert tag` name normalization and `#` prefix stripping in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+8. Add failing build action tests for `upsert property` schema coercion to `:logseq.property/type` and `:db/cardinality` in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+9. Add failing executor tests that `upsert tag` emits `[:create-page [name {:class? true}]]` only when the tag is missing in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+10. Add failing executor tests that `upsert tag` is idempotent for existing tag entities and rejects non-tag title conflicts in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+11. Add failing executor tests that `upsert property` emits `[:upsert-property [property-id schema opts]]` and passes `{:property-name name}` when creating a new property in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+12. Add failing executor tests that `remove tag` and `remove property` resolve entities by `--name` or `--id` and emit `[:delete-page [uuid]]` in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+13. Add failing executor tests that `remove tag --name` and `remove property --name` fail on multiple matches, return all matched candidates in output, and require rerun with `--id` in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+14. Add failing executor tests that built in or hidden tag or property targets are rejected with explicit error codes in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+15. Add failing formatter tests for `upsert tag`, `upsert property`, `remove tag`, and `remove property` outputs in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`.
+16. Add failing formatter tests that `remove block` and `remove page` outputs remain backward compatible in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`.
+17. Add failing integration tests for `upsert tag` create and idempotent behavior in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`.
+18. Add failing integration tests for `upsert property` create and schema update behavior in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`.
+19. Add failing integration tests for `remove tag` and `remove property` ensuring entities disappear from `list tag` and `list property` in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`.
+20. Add failing integration tests for `remove tag --name` and `remove property --name` ambiguous matches to assert candidate list output and `--id` guidance in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`.
+21. Add failing integration tests for `remove block` and `remove page` command migration behavior in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`.
+22. Run focused tests and confirm all new tests fail for behavior reasons before implementation.
+23. Create `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` with command specs, entries, validation helpers, action builders, and executors for tag and property upsert.
+24. Refactor shared tag resolver helpers from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` into `upsert.cljs` or a shared helper namespace to avoid duplication.
+25. Remove `add tag` command entry and related build or execute dispatch from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+26. Extend `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/remove.cljs` to register `remove block`, `remove page`, `remove tag`, and `remove property` entries.
+27. Keep existing block and page delete execution logic and map it behind `remove block` and `remove page` subcommands.
+28. Implement new remove tag and remove property resolver and execution paths in `remove.cljs` using `:delete-page` outliner op after entity type validation and ambiguity failure behavior for `--name`.
+29. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` table, parse validation, action builder, context propagation, and execute dispatch for new upsert and remove contracts.
+30. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` to format results for `upsert tag`, `upsert property`, `remove tag`, and `remove property`, including ambiguous candidate lists.
+31. Run focused unit and integration tests, then run `bb dev:lint-and-test`, and keep only behavior preserving refactors.
+32. Update CLI help text snapshots and any docs references to remove `add tag` and bare `remove` usage.
+
+## Edge cases to cover
+
+Tag names with leading `#` should normalize consistently in `upsert tag`.
+
+Tag and property names that collide by title or case must fail resolution for `--name`, list all candidate matches, and require explicit `--id`.
+
+Remove selectors must reject ambiguous name matches with a clear error, include all candidate ids and names in output, and require `--id`.
+
+Built in tags and built in properties must not be removable.
+
+Property type and cardinality updates must reject invalid transitions already enforced by outliner validation.
+
+`remove block` multi id behavior must stay unchanged from current implementation.
+
+`remove page` must preserve current not found and built in page deletion behavior.
+
+Commands must reject blank names after trim.
+
+## Verification commands
+
+| Command | Expected result |
+| --- | --- |
+| `bb dev:test -v logseq.cli.commands-test/test-parse-args-help` | Help output includes `upsert` and typed `remove` subcommands. |
+| `bb dev:test -v logseq.cli.commands-test/test-verb-subcommand-parse-upsert-remove` | Parse and validation tests for new command contracts pass. |
+| `bb dev:test -v logseq.cli.commands-test/test-build-action-upsert-remove` | Action payload tests pass for all new paths. |
+| `bb dev:test -v logseq.cli.commands-test/test-execute-upsert-remove-tag-property` | Outliner op emission tests pass for upsert and entity removal flows. |
+| `bb dev:test -v logseq.cli.format-test/test-human-output-upsert-remove` | Human output formatting for new commands is stable. |
+| `bb dev:test -v logseq.cli.integration-test/test-cli-upsert-and-remove-tag-property` | End to end behavior through db-worker-node passes for all four new commands. |
+| `bb dev:test -v logseq.cli.integration-test/test-cli-remove-block-page-subcommands` | Block and page deletion still work through new remove subcommands. |
+| `bb dev:lint-and-test` | Full lint and unit suite pass. |
+
+## Migration and compatibility
+
+No db-worker-node route migration is required because this feature reuses `/v1/invoke` and existing thread-api methods.
+
+No schema migration is required because tag and property entities are created and deleted through existing outliner operations.
+
+This is a CLI breaking change because `add tag` is removed and bare `remove` is replaced by typed `remove block` and `remove page` commands.
+
+This breaking change will be applied directly with no compatibility alias period.
+
+## Testing Details
+
+Tests validate parser, action, execution, formatter, and integration behavior for `upsert tag`, `upsert property`, `remove tag`, and `remove property`.
+
+Tests also validate migration behavior for `remove block` and `remove page` so previous block and page deletion semantics are preserved.
+
+Tests focus on command contracts and graph outcomes instead of helper internals.
+
+## Implementation Details
+
+- Add new upsert command module at `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`.
+- Register upsert entries and dispatch hooks in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+- Remove `add tag` command entry and related dispatch from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+- Refactor remove command entries in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/remove.cljs` to `remove block`, `remove page`, `remove tag`, and `remove property`.
+- Reuse `:thread-api/apply-outliner-ops` with `:create-page`, `:upsert-property`, and `:delete-page` for all entity mutations.
+- Add formatter branches in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` for new commands.
+- Add parser and executor unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+- Add formatter tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`.
+- Add end to end coverage in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`.
+- Use `@clojure-debug` only when failures indicate fixture or async wiring issues.
+
+## Question
+
+No open questions.
+
+---
diff --git a/docs/agent-guide/044-logseq-cli-upsert-block-page.md b/docs/agent-guide/044-logseq-cli-upsert-block-page.md
new file mode 100644
index 0000000000..43bf316684
--- /dev/null
+++ b/docs/agent-guide/044-logseq-cli-upsert-block-page.md
@@ -0,0 +1,191 @@
+# Logseq CLI Upsert Block and Upsert Page Implementation Plan
+
+Goal: Consolidate block and page write commands by replacing `add block`, `add page`, and `update` with `upsert block` and `upsert page` while preserving current db-worker-node write behavior.
+
+Architecture: Keep db-worker-node RPC and outliner operation contracts unchanged, and implement command consolidation in CLI parsing, action building, execution, and formatting layers.
+Architecture: Reuse existing helper logic from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/update.cljs` first, then fold shared behavior into `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`.
+Architecture: Route all mutations through existing `:thread-api/apply-outliner-ops` and `:thread-api/pull` calls so `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` require no new thread APIs.
+
+Tech Stack: ClojureScript, babashka.cli, Promesa, Logseq CLI transport, db-worker-node, and outliner ops.
+
+Related: Relates to `docs/agent-guide/027-logseq-cli-update-command.md` and builds on `docs/agent-guide/041-logseq-cli-add-block-json-identifiers.md`.
+Document naming follows @planning-documents with sequence `044`.
+
+## Problem statement
+
+The current CLI splits block mutations across `add block` and `update`, while page writes are exposed as `add page`.
+This creates an inconsistent user model and duplicates validation and formatting paths in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`.
+The current block update property options only support built-in properties, which prevents consistent upsert behavior for custom properties.
+The current `add page` flow applies tags after create, but page property behavior for existing pages is not fully upsert-like because `create-page` may no-op when the page exists.
+The db-worker-node layer already exposes stable generic APIs, so this feature should be implemented as a CLI surface refactor without protocol changes.
+
+## Testing Plan
+
+I will use @test-driven-development for all implementation batches.
+I will write all RED tests for parser, action builder, formatter, and integration flows before changing implementation behavior.
+I will add parser and builder tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `upsert block` and `upsert page` command forms and for hard-removal behavior of `add` and `update`.
+I will add formatter tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for human output of `:upsert-block` and `:upsert-page`.
+I will add integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that verify block creation, block update, block move, page creation, and page update through only `upsert` commands.
+I will add one integration test that verifies `upsert page` updates properties on an existing page, which closes the current `add page` gap.
+I will verify RED failures come from missing behavior and not from broken test setup.
+I will run focused GREEN tests after minimal implementation, then refactor, then rerun focused tests and full lint-test.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current implementation baseline
+
+| Area | Current implementation | Change target |
+| --- | --- | --- |
+| Command entries | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` defines `["add" "block"]` and `["add" "page"]`, and `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/update.cljs` defines `["update"]`. | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` defines `["upsert" "block"]` and `["upsert" "page"]` together with existing upsert subcommands. |
+| Validation and dispatch | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` validates and dispatches `:add-block`, `:add-page`, and `:update-block` separately. | Replace with `:upsert-block` and `:upsert-page` parse and dispatch paths. |
+| Help and group summaries | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` top-level summary and group handling still expose `add` and `update`. | Expose only `upsert` for these write cases. |
+| Formatter | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` has `format-add-block`, `format-add-page`, and `format-update-block`. | Replace with upsert-focused formatter routes while preserving existing output contract style. |
+| Worker APIs | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` already provide `:thread-api/apply-outliner-ops`. | No new worker endpoint or transport shape. |
+| Page create behavior | `/Users/rcmerci/gh-repos/logseq/deps/outliner/src/logseq/outliner/page.cljs` `create!` can return existing page with no transaction. | `upsert page` applies properties and tags explicitly on existing page to ensure real upsert behavior. |
+
+## Interface contract proposal
+
+`upsert block` supports two modes with deterministic priority.
+If `--id` or `--uuid` is provided, `upsert block` always runs update mode.
+If neither `--id` nor `--uuid` is provided, `upsert block` runs create mode.
+For `upsert block` update mode, add, update, and remove property options must support all existing properties, not only built-in properties.
+`upsert page` requires `--page` and always resolves an existing or newly created page, then applies add, update, and remove semantics for tags and properties.
+For `upsert page`, all add, update, and remove tag or property operations require the target tag and property to already exist, otherwise the command returns an error.
+
+| Command | Input signal | Behavior | Existing code path to reuse |
+| --- | --- | --- | --- |
+| `upsert block` create mode | `--id` and `--uuid` are absent and a content source is present. | Insert blocks under target with existing add semantics and support add, update, and remove tag or property options in post-insert ops. | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` add helpers plus update option helpers. |
+| `upsert block` update mode | `--id` or `--uuid` is present. | Move and or add, update, and remove tags or properties with existing update semantics, and support both built-in and custom properties in property options. | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/update.cljs` update helpers. |
+| `upsert page` | `--page` is present. | Create page if missing, then apply add, update, and remove tags and properties for both new and existing pages, with strict existing-tag and existing-property validation. | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` plus explicit remove op wiring. |
+
+## Architecture sketch
+
+```text
+CLI args
+  -> parse-args in commands.cljs
+  -> build-action returns :upsert-block or :upsert-page
+  -> execute routes to upsert command executor
+  -> transport/invoke :thread-api/apply-outliner-ops and :thread-api/pull
+  -> db-worker-node /v1/invoke passthrough
+  -> db_core thread-api handlers and outliner-op/apply-ops!
+```
+
+## Plan
+
+1. Add RED parser tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `upsert block` create mode with `--content` and for update mode with `--id` plus `--update-tags`.
+2. Add RED parser tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that confirm `--id` or `--uuid` forces update mode even when create inputs are also present.
+3. Add RED parser tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `upsert page --page <name>` with tags and properties.
+4. Add RED parser tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` to define expected unknown-command behavior for legacy `add block`, `add page`, and `update`.
+5. Add RED builder tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `:upsert-block` action shape in create mode.
+6. Add RED builder tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `:upsert-block` action shape in update mode, including custom property option inputs.
+7. Add RED builder tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `:upsert-page` action shape including resolved options.
+8. Add RED execute tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` to verify `:upsert-block` delegates to insert-style ops for create mode.
+9. Add RED execute tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` to verify `:upsert-block` delegates to move and property ops for update mode across built-in and custom properties.
+10. Add RED execute tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` to verify `:upsert-page` applies add, update, and remove property or tag ops on an already existing page.
+11. Add RED execute tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` to verify `:upsert-page` returns errors when any referenced tag or property does not exist.
+12. Add RED formatter tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for human output text of `:upsert-block` and `:upsert-page`.
+13. Add RED integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `upsert block` create mode id outputs.
+14. Add RED integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `upsert block` update mode move behavior and custom property updates.
+15. Add RED integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `upsert page` create and update-existing behaviors.
+16. Add RED integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `upsert page` erroring when referenced tags or properties do not exist.
+17. Run focused RED commands and confirm failures are expectation failures rather than transport or fixture errors.
+18. Extend `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` spec to include block and page options while keeping existing tag and property specs.
+19. Implement `build-block-action` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` to classify create mode versus update mode with `--id` or `--uuid` priority, and normalize property options for all property identifiers.
+20. Implement `build-page-action` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` for `upsert page`.
+21. Extract or reuse add helper functions from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` for reading blocks, parsing tags, parsing properties, and resolving ids.
+22. Extract or reuse update helper functions from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/update.cljs` for source and target resolution and move option mapping.
+23. Implement `execute-upsert-block` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` that branches by mode and calls reused logic without behavior drift, including custom property update support.
+24. Implement `execute-upsert-page` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` so add, update, and remove property or tag ops are applied after resolving the page entity in both create and existing-page paths.
+25. Enforce strict `upsert page` validation and execution behavior where missing tags or properties fail fast instead of creating missing entities.
+26. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` table entries and finalize-command validation for `:upsert-block` and `:upsert-page`.
+27. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` build and execute case dispatch to remove `:add-block`, `:add-page`, and `:update-block` routing.
+28. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` top-level summary and group-help triggers to reflect the new command family.
+29. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` with `format-upsert-block` and `format-upsert-page` and command dispatch keys.
+30. Keep `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` unchanged unless test evidence proves a missing worker behavior.
+31. Update CLI documentation in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to replace add and update examples with upsert equivalents.
+32. Run focused GREEN tests and confirm parser, builder, formatter, and integration cases pass.
+33. Refactor duplicated helper wiring between add, update, and upsert modules while preserving test behavior.
+34. Rerun focused test set after refactor to confirm no regressions.
+35. Run `bb dev:lint-and-test` as final regression verification.
+
+## Edge cases
+
+`upsert block` with `--id` or `--uuid` plus create inputs must deterministically run update mode because source selectors have priority.
+`upsert block` update mode must keep current `--pos` validation where `sibling` is invalid for page targets and `--pos` requires a target.
+`upsert block` update mode property options must support all existing properties, including non built-in properties.
+`upsert block` create mode must preserve current default target fallback to today journal when no target selector is provided.
+`upsert block` create mode with `--blocks` or `--blocks-file` must keep the existing restriction that tags and properties cannot be combined if that restriction is still required by current insert behavior.
+`upsert block` and `upsert page` must support remove options for tags and properties in addition to add and update options.
+`upsert page` must return stable `data.result` id vectors for JSON, EDN, and human output just like current add command id outputs.
+`upsert page` on an existing page must apply property updates and removals explicitly so upsert semantics are true for both create and existing states.
+`upsert page` must error when any tag or property referenced by add, update, or remove options does not already exist.
+Legacy command behavior must be hard removal with standard `unknown-command` errors for `add block`, `add page`, and `update`.
+Help output must not regress command grouping or ANSI formatting alignment in `commands_test`.
+
+## Verification commands and expected output
+
+Run parser and builder tests during RED.
+
+```bash
+bb dev:test -v logseq.cli.commands-test
+```
+
+Expected RED behavior is failing assertions for missing `upsert block` and `upsert page` paths before implementation.
+
+Run formatter tests during RED.
+
+```bash
+bb dev:test -v logseq.cli.format-test
+```
+
+Expected RED behavior is failing assertions for unknown command formatter branches for upsert block and upsert page.
+
+Run focused integration tests after implementation.
+
+```bash
+bb dev:test -v logseq.cli.integration-test/test-cli-upsert-block-create-json-output-returns-ids
+bb dev:test -v logseq.cli.integration-test/test-cli-upsert-block-update-move
+bb dev:test -v logseq.cli.integration-test/test-cli-upsert-page-create-and-update-existing
+```
+
+Expected GREEN behavior is zero failures and zero errors for these tests.
+
+Run full verification.
+
+```bash
+bb dev:lint-and-test
+```
+
+Expected GREEN behavior is full suite pass with exit code `0`.
+
+## Testing Details
+
+Behavior tests will assert command-level outcomes through real CLI execution and Datascript queries instead of only checking mock invocation counts.
+Unit-level command tests will assert parse, validation, and action-shape behavior at module boundaries.
+Integration tests will verify persisted graph state changes for both create and update paths of upsert block and upsert page.
+
+## Implementation Details
+
+- Keep db-worker-node API contracts unchanged and implement all command-surface changes in CLI modules only.
+- Add `upsert block` and `upsert page` entries to `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`.
+- Reuse add and update helper functions to minimize behavior drift and reduce migration risk.
+- Ensure `upsert block` and `upsert page` support add, update, and remove options for tags and properties.
+- Ensure `upsert block` property update options accept all existing properties, including custom properties, not only built-in properties.
+- Ensure `upsert page` applies tags and properties after resolving page entity so existing pages are updated too.
+- Ensure `upsert page` fails fast when referenced tags or properties do not exist, and never auto-creates them through upsert-page mutation options.
+- Remove old command routes in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` for `add block`, `add page`, and `update`, returning standard `unknown-command`.
+- Update formatter dispatch in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` for new command ids.
+- Update command summaries in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` to keep help output accurate.
+- Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` examples and command reference text.
+- Keep implementation batches aligned to @test-driven-development RED, GREEN, and refactor phases.
+
+## Question
+
+No open questions.
+Decided: remove `add block`, `add page`, and `update` immediately.
+Decided: in `upsert block`, `--id` or `--uuid` means update mode and absence of both means create mode.
+Decided: support add, update, and remove semantics for tags and properties.
+Decided: in `upsert block` update mode, property mutation options support all existing properties, including custom properties.
+Decided: for `upsert page`, add, update, and remove tag or property options require existing tags and properties, otherwise return error.
+
+---
diff --git a/docs/agent-guide/045-logseq-cli-property-type-and-upsert-option-unification.md b/docs/agent-guide/045-logseq-cli-property-type-and-upsert-option-unification.md
new file mode 100644
index 0000000000..ce6d2caa8d
--- /dev/null
+++ b/docs/agent-guide/045-logseq-cli-property-type-and-upsert-option-unification.md
@@ -0,0 +1,180 @@
+# Logseq CLI Property Type and Upsert Option Unification Implementation Plan
+
+Goal: Add a property type column to `list property`, add `--id` update-mode semantics to `upsert block/page/tag/property`, and remove duplicated `--tags` or `--properties` options from `upsert block/page` in favor of `--update-tags` or `--update-properties`.
+
+Architecture: Keep the existing `logseq-cli -> transport/invoke -> db-worker-node :thread-api/*` contract unchanged and implement behavior changes in CLI parsing, action building, execution, and formatting.
+Architecture: Extend property list payload shaping so non-expanded property items include `:logseq.property/type`, then render a dedicated property table in human output with a `TYPE` column.
+Architecture: Treat `--id` as an explicit update signal for all upsert entity commands, and keep create paths only when `--id` is absent.
+
+Tech Stack: ClojureScript, babashka.cli, Promesa, Datascript, logseq-cli command modules, db-worker-node thread APIs.
+
+Related: Builds on `docs/agent-guide/044-logseq-cli-upsert-block-page.md` and relates to `docs/agent-guide/043-logseq-cli-tag-property-management.md`.
+
+## Problem statement
+
+Current `list property` human output in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` uses the same formatter as `list tag`, so no property-type column is rendered.
+
+Current non-expanded property list items from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/mcp/tools.cljs` are built by `minimal-list-item`, which does not include `:logseq.property/type`.
+
+Current `upsert block` already supports `--id` and treats it as update mode via `update-mode?` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`, but `upsert page`, `upsert tag`, and `upsert property` do not accept `--id`.
+
+Current `upsert block/page` specs include both `--tags` or `--properties` and `--update-tags` or `--update-properties` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`, which duplicates semantics and increases parser and action complexity.
+
+Current parser validation in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` requires `--page` for `upsert page` and requires `--name` for `upsert property`, so there is no update-by-id mode for those commands.
+
+## Testing Plan
+
+I will use `@test-driven-development` for all implementation batches.
+
+I will add parser and action RED tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for new `--id` contracts on `upsert page`, `upsert tag`, and `upsert property`.
+
+I will add formatter RED tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for the `list property` `TYPE` column and its value normalization.
+
+I will add contract RED tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/mcp_tools_contract_test.cljs` to ensure non-expanded property list items carry `:logseq.property/type`.
+
+I will add integration RED tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for update-by-id flows and for rejecting removed `--tags` or `--properties` flags on `upsert block/page`.
+
+I will use `@clojure-debug` only when failures indicate fixture or async harness issues rather than missing behavior.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current implementation baseline
+
+| Requirement | Current behavior | Gap |
+| --- | --- | --- |
+| `list property` shows type column. | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` renders tag and property with the same columns (`ID`, `TITLE`, optional `IDENT`, timestamps). | No `TYPE` column in human output, and non-expanded payload currently omits type. |
+| `upsert block/page/tag/property` supports `--id` and `--id` forces update mode. | `upsert block` supports this already, but `upsert page/tag/property` specs do not expose `--id` and still depend on page/name creation-first contracts. | Missing update-by-id mode for three upsert commands. |
+| `upsert block/page` removes `--tags` or `--properties` and uses `--update-tags` or `--update-properties` only. | Both old and new options are accepted and merged in action building and execution. | Duplicate option surface and duplicate parsing paths remain. |
+
+## Target contract
+
+`upsert block` keeps current `--id` update-mode behavior and remove legacy create-only `--tags` or `--properties` options.
+
+`upsert page` accepts `--id` as update mode, and accepts `--page` only for create mode.
+
+`upsert tag` accepts `--id` as update mode, and keeps `--name` for create mode.
+
+`upsert property` accepts `--id` as update mode, and keeps `--name` for create mode.
+
+`upsert tag --id <id>` with no additional mutation options is a successful no-op after id lookup and tag-class validation.
+
+`upsert page --id <id> --page <name>` is invalid and must fail as conflicting selectors.
+
+When `--id` is provided for any upsert command, create-specific resolution paths must be skipped and the command must fail if the target id does not exist or has the wrong entity class.
+
+`upsert block/page` should reject `--tags` and `--properties` as unknown options after spec cleanup, with guidance to use `--update-tags` and `--update-properties`.
+
+Update-by-id failures should use new id-mode specific error codes so scripts can distinguish id lookup and id class mismatch from create-mode validation failures.
+
+## Architecture sketch
+
+```text
+list property
+  -> /src/main/logseq/cli/command/list.cljs execute-list-property
+  -> /src/main/frontend/worker/db_core.cljs :thread-api/cli-list-properties
+  -> /src/main/logseq/cli/common/mcp/tools.cljs list-properties
+  -> /src/main/logseq/cli/format.cljs format-list-property (new dedicated formatter)
+```
+
+```text
+upsert page/tag/property --id <id>
+  -> /src/main/logseq/cli/commands.cljs parse + finalize-command
+  -> /src/main/logseq/cli/command/upsert.cljs update-mode detection and action build
+  -> transport/invoke :thread-api/pull for id/entity validation
+  -> transport/invoke :thread-api/apply-outliner-ops for update ops only
+```
+
+## Detailed implementation plan
+
+1. Add RED parser tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting `upsert page --id 10 --update-properties ...` parses as `:upsert-page` and no longer requires `--page`.
+2. Add RED parser tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting `upsert tag --id 10` parses and `upsert property --id 10 --type node` parses.
+3. Add RED parser tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting `upsert block --tags ...` and `upsert page --properties ...` fail with `:invalid-options` due to removed flags.
+4. Add RED parser tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting `upsert page --id <id> --page <name>` fails with a selector conflict error.
+5. Add RED build-action tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `upsert page/tag/property` actions that include `:mode :update` when `--id` is present.
+6. Add RED execute tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` verifying `upsert tag --id <id>` with no update fields returns `:ok` and no mutation ops.
+7. Add RED execute tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` verifying update-by-id rejects missing ids and wrong entity classes with new id-mode specific error codes.
+8. Add RED formatter tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` asserting `list property` human output includes `TYPE` header and per-row values.
+9. Add RED contract tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/mcp_tools_contract_test.cljs` asserting non-expanded `list-properties` items include `:logseq.property/type`.
+10. Add RED integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `upsert page --id`, `upsert tag --id`, and `upsert property --id` update mode behavior, including tag no-op behavior.
+11. Add RED integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` verifying `upsert page --id --page` fails with selector conflict and `upsert block/page` reject removed `--tags` and `--properties` options.
+12. Run focused RED commands and verify failures are behavior assertions, not fixture failures.
+13. Update specs in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` to remove `:tags` and `:properties` from block/page specs and add `:id` to page/tag/property specs.
+14. Update option validation in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` so `upsert page` and `upsert property` required-field checks are mode-aware instead of unconditional, and add explicit selector-conflict validation for `upsert page --id --page`.
+15. Refactor `build-page-action` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` to support create mode by `--page` and update mode by `--id`.
+16. Refactor `build-tag-action` and `build-property-action` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` to support update mode by `--id` with mode-specific required options.
+17. Add shared helper(s) in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` to pull entities by id and validate class/type constraints before updates.
+18. Update `execute-upsert-page`, `execute-upsert-tag`, and `execute-upsert-property` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` so update mode uses id lookup, skips creation paths, and applies only update semantics, with `upsert tag --id` no-op when no mutation fields are provided.
+19. Introduce explicit id-mode error codes in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` for id-not-found and id-type-mismatch failures.
+20. Remove all `:tags` and `:properties` action wiring from page/block upsert flows in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`, and keep only `:update-tags` and `:update-properties`.
+21. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/mcp/tools.cljs` to include `:logseq.property/type` in non-expanded property list items.
+22. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` to split property formatting from tag formatting and render a dedicated `TYPE` column for `:list-property`.
+23. Update docs in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to remove `--tags` or `--properties` from `upsert block/page` docs, document update-by-id behavior across all upsert commands, and document selector conflict behavior.
+24. Run focused GREEN tests for commands, format, and integration, then run `bb dev:lint-and-test`.
+25. Refactor only after GREEN to reduce duplication in upsert mode branching, then rerun focused tests and full suite.
+
+## Edge cases
+
+`upsert page --id <id>` must fail when id points to a block that is not a page entity.
+
+`upsert tag --id <id>` must fail when id points to a page not tagged with `:logseq.class/Tag`.
+
+`upsert property --id <id>` must fail when id points to an entity without `:logseq.property/type`.
+
+`upsert tag --id <id>` with no mutation options must return success without issuing mutation ops.
+
+`upsert page --id <id> --page <name>` must fail with a dedicated selector conflict error.
+
+Update-by-id missing target and class mismatch failures must return new id-mode specific error codes.
+
+`upsert block` create mode with `--blocks` or `--blocks-file` must preserve existing validation behavior after removing `--tags` and `--properties` options.
+
+Property type display should remain stable for built-in and custom properties, and missing type values should render as `-` instead of throwing.
+
+JSON and EDN list outputs should remain backward compatible except for the additive `type` field on property items.
+
+## Verification commands and expected output
+
+| Command | Expected output |
+| --- | --- |
+| `bb dev:test -v logseq.cli.commands-test` | Parser, action, and execute tests for mode switching and option removal pass. |
+| `bb dev:test -v logseq.cli.format-test` | Human formatter tests pass with `TYPE` column coverage for `list property`. |
+| `bb dev:test -v logseq.cli.mcp-tools-contract-test` | Contract tests pass with `:logseq.property/type` present in non-expanded property items. |
+| `bb dev:test -v logseq.cli.integration-test/test-cli-upsert-page-create-and-update-existing` | Existing page upsert flow still passes after mode refactor. |
+| `bb dev:test -v logseq.cli.integration-test` | New `--id` update-mode and removed-option behavior pass end to end. |
+| `bb dev:lint-and-test` | Full suite passes with exit code `0`. |
+
+## Testing Details
+
+Tests cover CLI behavior at parser, action, executor, formatter, and end-to-end levels, and they assert entity outcomes instead of internal helper wiring.
+
+Tests verify that update-by-id mode never creates entities and that legacy duplicated options are no longer accepted for block/page upsert.
+
+Tests verify that `list property` human and structured output both include property-type information in their respective contracts.
+
+## Implementation Details
+
+- Keep db-worker-node thread API names unchanged and avoid adding new transport methods.
+- Add `--id` to `upsert page/tag/property` specs in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`.
+- Remove `--tags` and `--properties` from `upsert block/page` specs in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`.
+- Make finalize validation in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` mode-aware for page/property required options.
+- Rework `build-page-action`, `build-tag-action`, and `build-property-action` to branch on create vs update mode.
+- Add id-based entity validation helpers in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`.
+- Make `upsert tag --id` with no mutation fields a successful no-op after id and class validation.
+- Reject `upsert page --id --page` as explicit selector conflict.
+- Add new id-mode specific error codes for id-not-found and id-type-mismatch paths.
+- Include `:logseq.property/type` in non-expanded property list payload from `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/mcp/tools.cljs`.
+- Split property-specific table rendering in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` to add `TYPE` column.
+- Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` command reference and examples.
+- Keep implementation and debugging workflow aligned with `@test-driven-development` and `@clojure-debug`.
+
+## Question
+
+No open questions.
+
+Decided: `upsert tag --id <id>` with no additional mutation options is a successful no-op.
+
+Decided: `upsert page --id <id> --page <name>` is rejected as conflicting selectors.
+
+Decided: update-by-id failures use new id-mode specific error codes.
+
+---
diff --git a/docs/agent-guide/046-logseq-cli-upsert-tag-rename-by-id.md b/docs/agent-guide/046-logseq-cli-upsert-tag-rename-by-id.md
new file mode 100644
index 0000000000..3c8824ad74
--- /dev/null
+++ b/docs/agent-guide/046-logseq-cli-upsert-tag-rename-by-id.md
@@ -0,0 +1,147 @@
+# Logseq CLI Upsert Tag Rename by ID Implementation Plan
+
+Goal: Allow `logseq upsert tag --id <id> --name <new-name>` to rename an existing tag while preserving the current create-by-name and validate-by-id behavior.
+
+Architecture: Keep the current `logseq-cli -> transport/invoke -> :thread-api/apply-outliner-ops` integration and implement rename-by-id entirely in the CLI command layer.
+Architecture: Reuse the existing db-worker-node `:rename-page` outliner op instead of introducing a new thread API.
+Architecture: Keep `upsert tag --id <id>` with no `--name` as an id-validation no-op for backward compatibility.
+
+Tech Stack: ClojureScript, babashka.cli, Promesa, Datascript pull queries, db-worker-node outliner ops.
+
+Related: Builds on `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/042-logseq-cli-add-tag-command.md`, `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/043-logseq-cli-tag-property-management.md`, and `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/045-logseq-cli-property-type-and-upsert-option-unification.md`.
+
+## Problem statement
+
+Current `upsert tag` validation in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` rejects `--id` and `--name` together with the error `only one of --id or --name is allowed`.
+
+Current update mode in `execute-upsert-tag` only calls `ensure-tag-by-id!` and returns success without mutation when `:mode` is `:update`.
+
+Current db-worker-node path already supports page rename through `:thread-api/apply-outliner-ops` with `[:rename-page [page-uuid new-title]]` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`, so rename behavior can be reused without adding new APIs.
+
+The user-visible gap is that a command like `logseq upsert tag --graph <GRAPH> --id 180 --name "Project Renamed"` should rename tag `180`, but currently fails at option validation.
+
+## Testing Plan
+
+I will use `@test-driven-development` for all implementation.
+
+I will write all RED tests first in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` and `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` before any production edits.
+
+I will verify RED failures are behavior failures by asserting error codes or missing mutation ops rather than fixture or async setup problems.
+
+I will use `@clojure-debug` only if async transport stubs or db-worker test harness behavior is unclear.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current implementation baseline
+
+| Requirement | Current behavior | Gap |
+| --- | --- | --- |
+| `upsert tag --id <id> --name <name>` renames an existing tag. | `invalid-options?` for `:upsert-tag` rejects mixed selectors in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`. | Rename-by-id cannot be triggered. |
+| `upsert tag --id <id>` stays supported. | `execute-upsert-tag` update mode validates id and returns `[id]` without mutation. | Must remain unchanged for compatibility. |
+| Rename execution uses existing db-worker-node contracts. | db-worker-node already handles `:rename-page` via `:thread-api/apply-outliner-ops` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`. | CLI does not currently call rename op in tag update path. |
+
+## Target contract
+
+`upsert tag --name <name>` keeps create or idempotent-create semantics.
+
+`upsert tag --id <id>` keeps id-validation no-op semantics and returns the same id.
+
+`upsert tag --id <id> --name <new-name>` renames the target tag to `<new-name>` using the existing outliner rename op.
+
+`upsert tag --id <id> --name <new-name>` must fail with `:upsert-id-not-found` or `:upsert-id-type-mismatch` when id is invalid or not a tag.
+
+`upsert tag --id <id> --name <new-name>` must no-op when `<new-name>` normalizes to the same `:block/name` as the target.
+
+`upsert tag --id <id> --name <new-name>` must fail if `<new-name>` belongs to another non-tag page with `:tag-name-conflict`.
+
+`upsert tag --id <id> --name <new-name>` must fail if `<new-name>` belongs to another existing tag to avoid ambiguous cross-tag merges.
+
+## Architecture sketch
+
+```text
+CLI
+  logseq upsert tag --id 180 --name "Project Renamed"
+    -> /src/main/logseq/cli/commands.cljs finalize-command
+    -> /src/main/logseq/cli/command/upsert.cljs build-tag-action
+    -> /src/main/logseq/cli/command/upsert.cljs execute-upsert-tag
+         1) ensure-tag-by-id!
+         2) conflict lookup by target name
+         3) transport/invoke :thread-api/apply-outliner-ops
+            [repo [[:rename-page [tag-uuid new-name]]] {}]
+         4) pull by id and return same id
+DB Worker
+  /src/main/frontend/worker/db_core.cljs
+    :rename-page handler -> outliner-core/save-block! with new title
+```
+
+## Detailed implementation plan
+
+1. Add a RED parse/build test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting `upsert tag --id 180 --name "Project Renamed"` is accepted and routed to `:upsert-tag`.
+2. Add a RED action test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting update-mode tag action keeps `:id` and includes normalized `:name`.
+3. Add a RED execute test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting update-mode with both id and name emits exactly one `:rename-page` op through `:thread-api/apply-outliner-ops`.
+4. Add a RED execute test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting update-mode with id-only remains no-op and does not call `:thread-api/apply-outliner-ops`.
+5. Add a RED execute test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting rename target conflict with non-tag page returns `:tag-name-conflict`.
+6. Add a RED execute test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` asserting rename target conflict with another tag returns a dedicated conflict error code.
+7. Add a RED integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that creates a tag, fetches its id, runs `upsert tag --id <id> --name <new-name>`, and verifies the new title appears in `list tag`.
+8. Add a RED integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` asserting the old name no longer appears in `list tag` after rename.
+9. Run focused RED commands and confirm failures are expected contract failures.
+10. Update `invalid-options?` for `:upsert-tag` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` to permit `--id` plus `--name` and keep invalid checks for empty or malformed names.
+11. Update `build-tag-action` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` so update mode accepts optional `:name` and keeps create mode semantics unchanged.
+12. Add helper logic in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` to detect whether normalized rename target equals current tag name and skip mutation in that case.
+13. Add helper logic in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` to pull by target name and detect conflicts with other entities before rename.
+14. Update `execute-upsert-tag` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` update branch to call `:rename-page` when id and name are both provided.
+15. Keep error handling in `execute-upsert-tag` aligned with existing `:upsert-id-not-found` and `:upsert-id-type-mismatch` contracts, and add one dedicated rename-conflict code for tag-to-tag collisions.
+16. Update CLI reference docs in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to document `upsert tag --id <id> --name <name>` rename semantics and conflict behavior.
+17. Run focused GREEN tests for `commands_test` and targeted integration tests.
+18. Run `bb dev:test -v logseq.cli.commands-test` and `bb dev:test -v logseq.cli.integration-test` to confirm no regressions.
+19. Run `bb dev:lint-and-test` as final verification.
+20. Refactor duplicated tag-name normalization or conflict checks only after GREEN, then rerun focused tests.
+
+## Edge cases
+
+- `--name` with leading `#` in update mode should normalize exactly like create mode.
+- `--name` that trims to blank should return `:invalid-options` and not hit db-worker.
+- Rename to current name with different casing should follow normalized-name no-op behavior.
+- Rename target that already exists as another tag should fail deterministically and not mutate either tag.
+- Rename target that exists as a non-tag page should fail with `:tag-name-conflict`.
+- Rename by id must preserve the original `:db/id` in command output.
+- Id-mode not-found and type-mismatch errors must remain stable for scripts.
+
+## Verification commands and expected output
+
+| Command | Expected output |
+| --- | --- |
+| `bb dev:test -v logseq.cli.commands-test` | Upsert tag parse, build, and execute tests pass including rename-by-id and no-op id-only paths. |
+| `bb dev:test -v logseq.cli.integration-test/test-cli-upsert-tag-id-rename` | End-to-end rename-by-id test passes with renamed tag visible in list output. |
+| `bb dev:test -v logseq.cli.integration-test/test-cli-upsert-tag-id-rename-conflict` | Conflict behavior test passes and returns expected error code/message. |
+| `bb dev:lint-and-test` | Full suite passes with exit code `0`. |
+
+## Testing Details
+
+The new tests verify user-observable behavior at parser, action, executor, and CLI integration levels.
+
+The tests assert command outputs, mutation calls, and list/query observable state instead of helper internals.
+
+The tests keep existing id-only no-op behavior covered so rename support does not regress current automation scripts.
+
+## Implementation Details
+
+- Modify tag option validation only in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`.
+- Keep db-worker-node thread API signatures unchanged in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`.
+- Reuse existing `:rename-page` outliner op instead of introducing a new op.
+- Preserve create-by-name idempotency path for `upsert tag --name`.
+- Preserve id-only validate path for `upsert tag --id`.
+- Add deterministic rename conflict handling before invoking rename op.
+- Keep error code stability for existing id lookup and type mismatch failures.
+- Update CLI docs to reflect rename-by-id and no-op-by-id contracts.
+- Follow `@test-driven-development` sequence strictly and use `@clojure-debug` only for harness issues.
+
+## Question
+
+Resolved: choose option 1.
+
+Rename-to-existing-tag returns a dedicated conflict error and must not be treated as success by returning the existing tag id.
+
+This prevents implicit merges and accidental retargeting.
+
+---
diff --git a/docs/agent-guide/047-logseq-cli-sync-command.md b/docs/agent-guide/047-logseq-cli-sync-command.md
new file mode 100644
index 0000000000..945d496e5e
--- /dev/null
+++ b/docs/agent-guide/047-logseq-cli-sync-command.md
@@ -0,0 +1,225 @@
+# Logseq CLI Sync Command Implementation Plan
+
+Goal: Add `logseq sync` subcommands to inspect and operate db-sync through existing db-worker-node APIs.
+
+Architecture: The CLI parser and executor will gain a dedicated sync command module that maps subcommands to `:thread-api/db-sync-*` calls via `/v1/invoke`.
+Architecture: A small worker API addition will expose runtime sync status, and sync config commands will support headless token setup through CLI-managed config values.
+Architecture: The design will reuse existing graph lock and repo binding behavior in `logseq.cli.server/ensure-server!` and `frontend.worker.db-worker-node/repo-error`.
+
+Tech Stack: ClojureScript, babashka.cli, promesa, db-worker-node HTTP API, frontend.worker.sync.
+
+Related: Builds on `docs/agent-guide/031-logseq-cli-doctor-command.md`, `docs/agent-guide/033-desktop-db-worker-node-backend.md`, and `docs/agent-guide/034-db-worker-node-owner-process-management.md`.
+
+## Problem statement
+
+The current CLI exposes graph, server, doctor, list, upsert, remove, query, and show commands, but it does not expose db-sync control or observability.
+
+`frontend.worker.db-core` already exposes operational db-sync thread APIs such as `:thread-api/db-sync-start`, `:thread-api/db-sync-stop`, `:thread-api/db-sync-upload-graph`, and `:thread-api/db-sync-grant-graph-access`.
+
+`frontend.worker.db-worker-node` already routes these methods over `/v1/invoke` with repo-lock safety checks, so the missing piece is a CLI command surface and one read API for status inspection.
+
+This plan keeps scope tight by reusing current transport and server lifecycle code, and only adds new worker behavior where inspection data is currently unavailable.
+
+I will use @planning-documents for naming, @writing-plans for task granularity, @logseq-cli for CLI integration expectations, and @test-driven-development for implementation sequence.
+
+## Testing Plan
+
+I will add parser and action unit tests that fail first for new `sync` command help, option validation, and action shaping.
+
+I will add command execution tests that fail first and verify `logseq.cli.transport/invoke` receives the exact method names and argument shapes for each sync subcommand.
+
+I will add format tests that fail first and verify human output for `sync status` and action commands, while keeping JSON and EDN behavior unchanged.
+
+I will add worker API tests that fail first for the new sync inspection API exposed through `/v1/invoke`.
+
+I will add one CLI integration test that fails first and verifies an end-to-end `sync status` flow on a temp graph and a started db-worker-node process.
+
+I will run targeted tests after each behavior slice and then run `bb dev:lint-and-test` before final review.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Scope and CLI surface
+
+| CLI command | Purpose | Worker method | Repo required |
+|---|---|---|---|
+| `sync status [--graph <name>]` | View current db-sync runtime state and counters. | `:thread-api/db-sync-status` (new). | Yes. |
+| `sync start [--graph <name>]` | Start db-sync websocket client for the graph. | `:thread-api/db-sync-start`. | Yes. |
+| `sync stop [--graph <name>]` | Stop db-sync client for the running daemon. | `:thread-api/db-sync-stop`. | Yes, to target a graph daemon deterministically. |
+| `sync upload [--graph <name>]` | Upload current graph snapshot and mark graph remote metadata. | `:thread-api/db-sync-upload-graph`. | Yes. |
+| `sync download [--graph <name>]` | Download remote graph data and apply it to local graph storage. | `:thread-api/db-sync-download-graph` (new). | Yes. |
+| `sync remote-graphs` | List remote graphs visible to current auth context. | `:thread-api/db-sync-list-remote-graphs` (new). | No. |
+| `sync ensure-keys` | Ensure user RSA keys required by e2ee are present. | `:thread-api/db-sync-ensure-user-rsa-keys`. | No. |
+| `sync grant-access --graph-id <uuid> --email <email> [--graph <name>]` | Grant encrypted graph key access to a target user email. | `:thread-api/db-sync-grant-graph-access`. | Yes. |
+| `sync config set <name> <value>` | Set one config value by key. | `:thread-api/set-db-sync-config`. | No. |
+| `sync config get <name>` | Read one config value by key. | `:thread-api/get-db-sync-config` (new). | No. |
+| `sync config unset <name>` | Remove one config value by key. | `:thread-api/set-db-sync-config`. | No. |
+
+The first release intentionally excludes asset download and raw kv import commands because they need more user-facing safety rails and payload tooling.
+
+`sync config set` supports `ws-url`, `http-base`, and `auth-token`, and `config set auth-token <token-value>` is the headless authentication entrypoint.
+
+`sync config get` and `sync config unset` reject unknown config keys.
+
+`sync status` will return normalized fields even when sync is not configured, so scripts can branch deterministically.
+
+`sync remote-graphs` and `sync download` require auth-token to be configured in headless mode.
+
+## Architecture and integration points
+
+```text
+logseq sync <subcommand>
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs (parse/build/execute)
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs (new)
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs (ensure graph daemon)
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs (POST /v1/invoke)
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs (repo checks + invoke)
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs thread APIs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs and sync/crypt.cljs
+```
+
+Worker additions will be minimal, with no protocol changes to cloud endpoints.
+
+CLI additions will follow existing `graph` and `server` command module patterns for spec, `entries`, `build-action`, and `execute-*` helpers.
+
+## Implementation plan
+
+### Phase 1. Add failing parser and help tests.
+
+1. Add a failing assertion in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that top-level help includes `sync` and `sync status`.
+2. Add a failing assertion in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that `logseq sync` shows subgroup help like `server` and `graph`.
+3. Add a failing assertion in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that `sync config set|get|unset` and `sync grant-access` show in sync group help.
+4. Run `bb dev:test -v logseq.cli.commands-test/test-help-output` and confirm failure references missing `sync` command rows.
+
+### Phase 2. Add failing action and execution tests for sync command module.
+
+5. Create `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` with failing tests for `build-action` graph requirement on `sync status`.
+6. Add a failing test for `build-action` rejection when `sync config set` is missing name or value.
+7. Add a failing test for `build-action` rejection when `sync grant-access` misses `--graph-id` or `--email`.
+8. Add a failing test for `build-action` graph requirement on `sync download`.
+9. Add a failing execution test that stubs `logseq.cli.server/ensure-server!` and `logseq.cli.transport/invoke` and expects `:thread-api/db-sync-start` with `[repo]`.
+10. Add a failing execution test that expects `:thread-api/db-sync-stop` with `[]` and still routes through `ensure-server!` using selected repo.
+11. Add a failing execution test that expects `:thread-api/db-sync-upload-graph` with `[repo]`.
+12. Add a failing execution test that expects `:thread-api/db-sync-download-graph` with `[repo]`.
+13. Add a failing execution test that expects `:thread-api/db-sync-list-remote-graphs` for `sync remote-graphs`.
+14. Add a failing execution test that expects `:thread-api/db-sync-ensure-user-rsa-keys` without repo.
+15. Add a failing execution test that expects `:thread-api/db-sync-grant-graph-access` with `[repo graph-id email]`.
+16. Add a failing execution test that expects `:thread-api/get-db-sync-config` for `sync config get <name>`.
+17. Add a failing execution test that expects `:thread-api/set-db-sync-config` for `sync config set <name> <value>` and payload merge behavior.
+18. Add a failing execution test that expects `:thread-api/set-db-sync-config` for `sync config unset <name>` and key removal behavior.
+19. Add a failing execution test that verifies `sync config set auth-token <token-value>` updates worker-consumable token config for headless mode.
+20. Run `bb dev:test -v logseq.cli.command.sync-test` and confirm failures are only from missing sync implementation.
+
+### Phase 3. Implement CLI sync command wiring.
+
+21. Add `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` with sync option specs, `entries`, `build-action`, and `execute-*` functions.
+22. Register `sync-command/entries` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` command table.
+23. Extend `finalize-command` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` with sync-specific required-option checks.
+24. Extend single-token group help routing in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` to include `sync`.
+25. Extend `build-action` dispatch in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` to call `sync-command/build-action`.
+26. Extend `execute` dispatch in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` to route sync action types.
+27. Add `sync` to top-level command grouping in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs`.
+28. Run `bb dev:test -v logseq.cli.commands-test/test-parse-args-help` and `bb dev:test -v logseq.cli.command.sync-test` until green.
+
+### Phase 4. Add read-only worker APIs for sync inspection.
+
+29. Add a failing worker test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that `/v1/invoke` accepts `thread-api/get-db-sync-config` without repo.
+30. Add a failing worker test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that `/v1/invoke` for `thread-api/db-sync-status` enforces repo and returns structured status.
+31. Add `:thread-api/get-db-sync-config` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` returning current config map.
+32. Add `:thread-api/db-sync-status` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` returning ws state, graph id, and sync counters for a repo.
+33. Add or expose a small helper in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` to compute status without requiring websocket side effects.
+34. Add `:thread-api/db-sync-list-remote-graphs` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` and implement cloud graph listing through worker sync HTTP helpers.
+35. Add `:thread-api/db-sync-download-graph` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` and implement remote snapshot download plus local import flow.
+36. Update worker sync auth token resolution so `sync config set auth-token <token-value>` is used in headless mode when state token is missing.
+37. Register `:thread-api/get-db-sync-config` and `:thread-api/db-sync-list-remote-graphs` in `non-repo-methods` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs`.
+38. Run `bb dev:test -v frontend.worker.db-worker-node-test` and fix only sync-related regressions.
+
+### Phase 5. Add output formatting tests and implementation.
+
+39. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for human output of `sync status`.
+40. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for human output of `sync remote-graphs`.
+41. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for human output of sync action commands such as start, upload, and download.
+42. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` verifying token redaction for `sync config get auth-token` in human output.
+43. Implement sync human formatters in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` with stable keys and token redaction.
+44. Confirm JSON and EDN output behavior by running `bb dev:test -v logseq.cli.format-test`.
+
+### Phase 6. Add integration coverage and CLI docs.
+
+45. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that creates a graph and runs `sync status` with `--output json`.
+46. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `sync config set auth-token` then `sync config get auth-token` behavior.
+47. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `sync config unset auth-token`.
+48. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `sync remote-graphs --output json`.
+49. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` for `sync download --graph <name>` flow with mocked remote snapshot response.
+50. Implement any missing glue for integration stability in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs`.
+51. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` command docs with sync command examples and error behaviors.
+52. Run `bb dev:test -v logseq.cli.integration-test` to verify end-to-end behavior.
+
+### Phase 7. Final verification and cleanup.
+
+53. Run `bb dev:lint-and-test` from `/Users/rcmerci/gh-repos/logseq` and confirm exit code `0`.
+54. Run manual smoke commands with a temp graph and confirm both `--output human` and `--output json` are stable.
+55. Review help text alignment and command ordering to match existing CLI aesthetics.
+
+## Edge cases and error handling
+
+`sync status` must return a valid map even when `:ws-url` is missing, with an explicit inactive state rather than throwing.
+
+`sync start` must keep current behavior where missing `ws-url` or missing graph uuid results in no crash and a deterministic status response.
+
+`sync grant-access` must surface cloud errors with existing `http-error` path and preserve status code and body context.
+
+`sync config get auth-token` must redact token values in human output while keeping full value available in JSON and EDN output for scripting.
+
+`sync config set auth-token <token-value>` must write to the config file selected by `--config` (default `~/logseq/cli.edn`) so headless auth survives daemon restarts.
+
+`sync remote-graphs` must return a deterministic empty list when user has no remote graphs instead of returning nil.
+
+`sync download` must fail fast when the target local graph is missing required auth or remote graph metadata, and must report a clear sync-specific error code.
+
+Repo mismatch and lock ownership behavior must remain enforced by db-worker-node and must not be bypassed in CLI command code.
+
+All new options must keep kebab-case keyword naming and avoid introducing `_` forms.
+
+## Verification commands
+
+| Command | Expected outcome |
+|---|---|
+| `bb dev:test -v logseq.cli.command.sync-test` | Sync command unit tests pass with no failures. |
+| `bb dev:test -v logseq.cli.commands-test/test-help-output` | Help output includes `sync` group and subcommands. |
+| `bb dev:test -v frontend.worker.db-worker-node-test` | Worker invoke tests pass including new sync read APIs. |
+| `bb dev:test -v logseq.cli.format-test` | Human and structured output tests pass including sync formatters. |
+| `bb dev:test -v logseq.cli.integration-test` | CLI integration tests pass for sync status and config flow. |
+| `bb dev:lint-and-test` | Full lint and unit suite passes with exit code `0`. |
+| `node ./dist/logseq.js sync status --graph demo --output json` | Returns `{"status":"ok","data":...}` with sync status fields. |
+| `node ./dist/logseq.js sync remote-graphs --output json` | Returns remote graph list in structured output. |
+| `node ./dist/logseq.js sync download --graph demo` | Downloads remote graph snapshot and imports it into local graph data. |
+| `node ./dist/logseq.js sync config set auth-token <token-value>` | Sets headless auth token for db-sync API calls. |
+| `node ./dist/logseq.js sync config get auth-token --output json` | Returns configured token value in structured output. |
+| `node ./dist/logseq.js sync config unset auth-token` | Removes configured token and returns success message. |
+
+## Testing Details
+
+The new tests verify behavior at parser level, action-building level, transport payload level, worker invoke contract level, output formatting level, and end-to-end CLI invocation level.
+
+The tests assert external behavior such as command availability, returned status payloads, and worker method invocations, instead of asserting internal helper implementation details.
+
+## Implementation Details
+
+- Add new file `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` for sync command ownership.
+- Keep `sync` command wiring inside existing dispatch points in `commands.cljs` and do not introduce a second dispatcher.
+- Add core worker sync inspection APIs, `get-db-sync-config` and `db-sync-status`, and reuse existing `set-db-sync-config` for config writes.
+- Add worker sync APIs for remote graph listing and graph download to support `sync remote-graphs` and `sync download`.
+- Reuse `transport/invoke` with existing `direct-pass?` handling and default to transit mode.
+- Keep `sync status` output fields stable for scripting, including `repo`, `graph-id`, `ws-state`, and pending counters.
+- Keep human output terse and redact auth-token values.
+- Update `command.core/top-level-summary` and group-help routing so `sync` behaves like existing command groups.
+- Keep all new keyword names kebab-case and avoid shadowed local names such as `bytes`.
+- Update `docs/cli/logseq-cli.md` with command list, examples, and expected error hints.
+- Run full lint and tests after targeted green passes.
+
+## Question
+
+No open question.
+
+This plan adopts option A and includes `sync config set|get|unset` with `config set auth-token <token-value>` as the token setup path.
+
+---
diff --git a/docs/agent-guide/048-sync-download-start-reliability.md b/docs/agent-guide/048-sync-download-start-reliability.md
new file mode 100644
index 0000000000..311fe77e04
--- /dev/null
+++ b/docs/agent-guide/048-sync-download-start-reliability.md
@@ -0,0 +1,179 @@
+# Sync Download And Sync Start Reliability Implementation Plan
+
+Goal: Validate and fix `logseq sync download` plus `logseq sync start` so download data is complete and start reaches a working sync session.
+
+Architecture: I will harden behavior with failing tests first at CLI, db-worker-node invoke boundary, and worker sync core, then apply minimal fixes in `logseq.cli.command.sync`, `frontend.worker.db_core`, and `frontend.worker.sync`.
+Architecture: The start path will stop reporting false success by checking runtime status after start, and the download path will fail fast on incomplete or inconsistent snapshot import conditions.
+Architecture: Manual verification will use a local untracked `cli.edn` built from the exact config block provided in this task.
+
+Tech Stack: ClojureScript, babashka test runner, db-worker-node daemon, frontend worker thread APIs, websocket plus HTTP sync APIs.
+
+Related: Builds on `docs/agent-guide/047-logseq-cli-sync-command.md`, and relates to `docs/agent-guide/033-desktop-db-worker-node-backend.md` and `docs/agent-guide/034-db-worker-node-owner-process-management.md`.
+
+## Problem statement
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` currently reports `sync start` success after invoking `:thread-api/db-sync-start`, but it does not verify the websocket state becomes `:open`.
+
+`/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` skips start when config or graph-id is missing, and the CLI currently does not distinguish this from a successful start.
+
+`/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` enforces frame integrity in `finalize-framed-buffer`, but the current tests do not cover incomplete snapshot frame failure through the full download flow.
+
+`/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` imports downloaded rows and returns a summary map, but there is no end-to-end CLI integration test that confirms downloaded graph data is usable and consistent after import.
+
+This plan uses @planning-documents for naming, @writing-plans for granularity, @test-driven-development for sequence, and @clojure-debug when failures are not immediately obvious.
+
+## Testing Plan
+
+I will add CLI command tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` for start readiness polling, start timeout behavior, and download error propagation.
+
+I will add worker sync tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` for incomplete framed snapshot behavior and download completeness invariants.
+
+I will add worker daemon invoke tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` to verify start and status interactions remain stable through `/v1/invoke`.
+
+I will add CLI integration tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` to verify `sync download` yields queryable graph data and `sync start` reaches `:open` within timeout in a deterministic mocked sync environment.
+
+I will run targeted tests after each behavior slice and then run `bb dev:lint-and-test` for regression safety.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current integration map
+
+```text
+logseq sync download/start
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs
+  -> remote sync HTTP + websocket endpoints
+```
+
+## Manual test configuration
+
+Create `/tmp/logseq-sync-cli.edn` with the exact EDN block provided in this task request.
+
+Keep this file local and untracked, and never commit the auth token to the repository.
+
+Use `--config /tmp/logseq-sync-cli.edn` for every manual `logseq sync` command in this plan.
+
+## Implementation plan
+
+### Phase 0. Baseline and reproducibility.
+
+1. Create `/tmp/logseq-sync-cli.edn` from the provided config block.
+2. Run `bb dev:test -v logseq.cli.command.sync-test` to capture current CLI sync baseline.
+3. Run `bb dev:test -v frontend.worker.db-sync-test` to capture current worker sync baseline.
+4. Run `bb dev:test -v frontend.worker.db-worker-node-test` to capture current daemon invoke baseline.
+5. Run `node ./dist/logseq.js sync remote-graphs --config /tmp/logseq-sync-cli.edn --output json` and record the graph-id and graph-name used for manual verification.
+
+### Phase 1. RED tests for sync start readiness semantics.
+
+6. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` that `sync start` polls `:thread-api/db-sync-status` and returns success only after `:ws-state` becomes `:open`.
+7. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` that `sync start` returns `:error` with diagnostic status when `:ws-state` never reaches `:open` before timeout.
+8. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` that start skipped conditions like missing `:ws-url` are surfaced as actionable CLI errors instead of success.
+9. Run `bb dev:test -v logseq.cli.command.sync-test/test-execute-sync-start` and verify RED failures are behavior failures.
+
+### Phase 2. RED tests for download completeness and failure propagation.
+
+10. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` that incomplete snapshot frames trigger `:db-sync/incomplete-snapshot-frame` behavior through download framing helpers.
+11. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` that a valid download payload produces stable row batches that can be imported without truncation.
+12. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` that `sync download` returns `:error` and preserves error code when `:thread-api/db-sync-download-graph-by-id` fails.
+13. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that downloaded data is queryable after import and includes expected graph metadata.
+14. Run `bb dev:test -v frontend.worker.db-sync-test` and `bb dev:test -v logseq.cli.integration-test` and verify RED failures are behavior failures.
+
+### Phase 3. GREEN implementation for sync start observability.
+
+15. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` to add a bounded wait helper that polls `:thread-api/db-sync-status` after `:thread-api/db-sync-start`.
+16. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` so `:sync-start` returns `{:status :ok}` only when status shows `:ws-state :open`.
+17. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` so timeout or skipped start returns `{:status :error}` with `:repo`, current `:ws-state`, and remediation hint.
+18. If needed, update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` status payload to include one extra diagnostic field for recent start failures.
+19. Re-run `bb dev:test -v logseq.cli.command.sync-test` until all start-related tests pass.
+
+### Phase 4. GREEN implementation for download completeness guarantees.
+
+20. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` to keep strict framed payload validation and expose structured failure details used by CLI.
+21. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` download/import path to assert required result fields before import and fail fast on invalid payload.
+22. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` download branch to preserve worker error code and context in CLI output.
+23. Re-run `bb dev:test -v frontend.worker.db-sync-test` and `bb dev:test -v logseq.cli.command.sync-test` until download-related tests pass.
+
+### Phase 5. REFACTOR and regression safety.
+
+24. Refactor only duplicated sync command helper code in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` without changing behavior.
+25. Re-run `bb dev:test -v logseq.cli.command.sync-test` after refactor.
+26. Re-run `bb dev:test -v frontend.worker.db-sync-test` after refactor.
+27. Re-run `bb dev:test -v frontend.worker.db-worker-node-test` after refactor.
+
+### Phase 6. Manual end-to-end verification with provided cli.edn.
+
+28. Run `node ./dist/logseq.js sync download --graph <graph-name> --config /tmp/logseq-sync-cli.edn --output json` and record `graph-id`, `remote-tx`, and `row-count`.
+29. Run `node ./dist/logseq.js q --graph <graph-name> --config /tmp/logseq-sync-cli.edn --output json '[:find (count ?e) :where [?e :block/uuid]]'` and confirm graph has non-zero entities.
+30. Run `node ./dist/logseq.js sync status --graph <graph-name> --config /tmp/logseq-sync-cli.edn --output json` and capture pre-start `ws-state`.
+31. Run `node ./dist/logseq.js sync start --graph <graph-name> --config /tmp/logseq-sync-cli.edn --output json` and verify command succeeds only when status reaches `:open`.
+32. Run `node ./dist/logseq.js upsert block --graph <graph-name> --title "sync smoke $(date +%s)" --config /tmp/logseq-sync-cli.edn --output json` to create a local change.
+33. Run `node ./dist/logseq.js sync status --graph <graph-name> --config /tmp/logseq-sync-cli.edn --output json` repeatedly until `pending-local` trends back to `0`.
+34. If step 31 or step 33 fails, inspect db-worker-node log file under the graph repo directory and capture exact error code plus timestamp.
+
+### Phase 7. Final verification.
+
+35. Run `bb dev:lint-and-test` from `/Users/rcmerci/gh-repos/logseq` and ensure full suite is green.
+36. Re-run manual step 31 one more time to verify no flakiness after full test run.
+37. Document final behavior and known limitations in the PR summary.
+
+## Edge cases to cover explicitly
+
+`sync start` must return an actionable error when `:ws-url` is missing or empty.
+
+`sync start` must avoid false success when token exists but handshake never reaches `:open`.
+
+Repeated `sync start` calls must be idempotent and not create duplicate clients.
+
+`sync download` must fail clearly when remote graph is not found and must include graph-name in the error.
+
+`sync download` must fail clearly on incomplete framed snapshot payload.
+
+`sync download` must not leave a half-imported local graph when import throws mid-batch.
+
+`sync download` must preserve and report `graph-e2ee?` and remote graph-id in result payload.
+
+## Verification command matrix
+
+| Command | Expected outcome |
+|---|---|
+| `bb dev:test -v logseq.cli.command.sync-test` | Sync CLI tests pass, including start readiness and download error propagation. |
+| `bb dev:test -v frontend.worker.db-sync-test` | Worker sync framing and download completeness tests pass. |
+| `bb dev:test -v frontend.worker.db-worker-node-test` | Daemon invoke and status behavior remains green. |
+| `bb dev:test -v logseq.cli.integration-test` | CLI integration verifies queryable data after download and start readiness path. |
+| `node ./dist/logseq.js sync download --graph <graph-name> --config /tmp/logseq-sync-cli.edn --output json` | Returns `status: ok` with stable `graph-id`, `remote-tx`, and non-negative `row-count`. |
+| `node ./dist/logseq.js sync start --graph <graph-name> --config /tmp/logseq-sync-cli.edn --output json` | Returns `status: ok` only when worker status reaches `ws-state: open`. |
+| `node ./dist/logseq.js sync status --graph <graph-name> --config /tmp/logseq-sync-cli.edn --output json` | Shows non-negative queue counters and stable repo graph identifiers. |
+| `bb dev:lint-and-test` | Full lint and unit suite passes with exit code `0`. |
+
+## Testing Details
+
+The test suite additions validate behavior from user-visible CLI result down to worker framed snapshot handling and daemon invoke boundary.
+
+The tests verify externally observable behavior such as command status, error code, websocket state progression, and queryable post-download graph data.
+
+The tests avoid checking private implementation details and focus on functional outcomes.
+
+## Implementation Details
+
+- Keep `sync` command API surface unchanged and improve readiness validation inside existing `:sync-start` execution path.
+- Keep download protocol unchanged and improve payload validation plus error propagation semantics.
+- Reuse `:thread-api/db-sync-status` as the source of readiness truth for CLI start.
+- Keep all keyword names kebab-case and avoid introducing underscore keys.
+- Ensure any new helper names avoid shadowed locals like `bytes`.
+- Keep auth token handling in local config and never persist token values into repository files.
+- 在 db-worker-node 中，如果是 desktop app 场景启动，token 读写保持原有代码路径。
+- 在 db-worker-node 中，如果是 cli 场景启动，读取 token 一律从 `cli.edn`（sync config）中获取。
+- 在 db-worker-node 中，如果是 cli 场景启动，写入 token 也走 `cli.edn`（sync config）路径。
+- Preserve existing db-worker-node repo lock and method access rules.
+- Keep manual verification commands deterministic by pinning `--config /tmp/logseq-sync-cli.edn`.
+- Use a fixed `sync start` wait timeout of `10000` ms with no CLI override option.
+
+## Question
+
+No open question.
+
+---
diff --git a/docs/agent-guide/049-logseq-cli-graph-info-kv-display.md b/docs/agent-guide/049-logseq-cli-graph-info-kv-display.md
new file mode 100644
index 0000000000..940048ed24
--- /dev/null
+++ b/docs/agent-guide/049-logseq-cli-graph-info-kv-display.md
@@ -0,0 +1,193 @@
+# Graph Info Kv Display Implementation Plan
+
+Goal: Make `logseq graph info` display all persisted `:logseq.kv/<...>` values in a readable and script-friendly way without introducing new db-worker-node protocol endpoints.
+
+Architecture: Reuse existing `logseq-cli -> transport -> db-worker-node -> :thread-api/q` flow to query kv entities by `:db/ident` namespace `logseq.kv`.
+
+Architecture: Keep backward compatibility by preserving current summary fields while adding a structured ident-keyed kv map for JSON and EDN output plus a dedicated kv section in human output.
+
+Architecture: Follow `@test-driven-development` with failing tests first in command, formatter, and integration layers.
+
+Tech Stack: ClojureScript, Datascript query via existing `:thread-api/q`, db-worker-node HTTP transit transport, Logseq CLI formatter pipeline, Babashka test runner.
+
+Related: Builds on `docs/agent-guide/001-logseq-cli.md`.
+
+Related: Builds on `docs/agent-guide/007-logseq-cli-thread-api-and-command-split.md`.
+
+Related: Relates to `docs/agent-guide/033-desktop-db-worker-node-backend.md`.
+
+## Problem statement
+
+Current `execute-graph-info` only fetches `:logseq.kv/graph-created-at` and `:logseq.kv/schema-version` via two `:thread-api/pull` calls.
+
+Current human output shows only three lines, which is too limited for diagnosing graph state during CLI usage.
+
+Current JSON and EDN outputs also omit other kv entries such as `:logseq.kv/db-type`, `:logseq.kv/graph-initial-schema-version`, and runtime metadata keys.
+
+The requested behavior is to show all `:logseq.kv/<...>` kv pairs in a way that is readable for humans and stable for machine consumers.
+
+The implementation should stay within the current db-worker-node design and avoid adding new RPC methods unless absolutely necessary.
+
+## Current and target data flow
+
+```text
+Current.
+logseq graph info
+  -> execute-graph-info
+  -> thread-api/pull (:graph-created-at)
+  -> thread-api/pull (:schema-version)
+  -> formatter renders 3 lines.
+
+Target.
+logseq graph info
+  -> execute-graph-info
+  -> thread-api/q (query all :db/ident in namespace "logseq.kv" with :kv/value)
+  -> normalize + sort kv rows
+  -> data payload keeps summary fields + ident-keyed kv map
+  -> formatter renders summary + kv section (human) or structured kv payload (json/edn).
+```
+
+## Target behavior
+
+`graph info` keeps existing top summary lines so users still see graph name, created-at, and schema version immediately.
+
+`graph info` adds a complete kv section in human output, sorted by ident for deterministic reading.
+
+`graph info` adds a structured ident-keyed kv map field in result data for JSON and EDN output so scripts can parse all kv values directly.
+
+The kv field contains only persisted kv rows, which means keys without `:kv/value` in the DB are not synthesized.
+
+All output formats redact kv keys matching sensitive patterns like `token`, `secret`, or `password`.
+
+Human output truncates very long string values with explicit marker text.
+
+The implementation uses only existing `:thread-api/q` and transport invocation paths.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and write all failing tests before implementation.
+
+I will add command-level tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/graph_test.cljs` to validate `execute-graph-info` builds kv payload from query rows and preserves existing summary fields.
+
+I will extend formatting tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` to verify human output includes a deterministic kv section and still keeps the existing summary lines.
+
+I will add JSON and EDN formatting assertions in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for the new structured kv field shape.
+
+I will add formatter tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for sensitive key redaction across human, JSON, and EDN outputs plus long string truncation in human output.
+
+I will add integration coverage in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that creates a graph and asserts `graph info` returns non-empty `logseq.kv` data end-to-end through db-worker-node.
+
+I will run focused tests first and use `@clojure-debug` if any failure is non-obvious before changing implementation.
+
+I will run `bb dev:lint-and-test` as final gate.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Implementation plan
+
+### Phase 1: Add failing tests for command payload shape.
+
+1. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/graph_test.cljs` that stubs `cli-server/ensure-server!` and `transport/invoke` and asserts `execute-graph-info` issues one `:thread-api/q` request for `logseq.kv` rows.
+2. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/graph_test.cljs` that asserts result data still includes `:graph`, `:logseq.kv/graph-created-at`, and `:logseq.kv/schema-version`.
+3. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/graph_test.cljs` that asserts kv rows are normalized into an ident-keyed map for machine output and deterministic sorted entries for human rendering.
+
+### Phase 2: Add failing tests for human output.
+
+4. Extend `test-human-output-graph-info` in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` to expect the existing summary lines plus a kv section.
+5. Add a failing formatter test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` that verifies kv rows are ordered lexicographically by ident.
+6. Add a failing formatter test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` that verifies sensitive kv keys are redacted in human output.
+7. Add a failing formatter test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` that verifies long string kv values are truncated in human output.
+
+### Phase 3: Add failing tests for machine outputs and integration.
+
+8. Add a failing JSON output test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` asserting new kv map field is present and parseable.
+9. Add a failing EDN output test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` asserting kv map preserves keyword idents and applies sensitive key redaction.
+10. Add a failing JSON output test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` asserting sensitive keys are redacted in machine output.
+11. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that runs `graph create` then `graph info` and asserts returned data includes multiple `:logseq.kv/...` keys.
+12. Run focused tests and confirm failures are behavior gaps rather than fixture or server boot issues.
+
+### Phase 4: Implement command-side kv collection with existing db-worker-node API.
+
+13. Add a private datalog query constant in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/graph.cljs` that finds `?ident` and `?value` where ident namespace is `"logseq.kv"` and entity has `:kv/value`.
+14. Update `execute-graph-info` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/graph.cljs` to call `transport/invoke` once with `:thread-api/q` and query inputs.
+15. Normalize query tuples into an ident-keyed kv map for machine output and keep a sorted kv entry list for deterministic human formatting.
+16. Derive `:logseq.kv/graph-created-at` and `:logseq.kv/schema-version` from the kv map to keep backward compatibility in `:data`.
+17. Add the new structured kv map field to the response payload while keeping existing keys unchanged.
+
+### Phase 5: Implement formatter changes for reasonable display.
+
+18. Add a helper in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` to format graph kv rows for human output with a clear header and deterministic ordering.
+19. Update `format-graph-info` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` to render summary lines first and kv section second.
+20. Add centralized masking for kv keys matching sensitive patterns like `token`, `secret`, or `password` so human, JSON, and EDN output share the same redaction behavior.
+21. Add human output truncation for very long string values with an explicit marker.
+22. Ensure human output remains readable when kv list is empty by showing an explicit empty state line.
+
+### Phase 6: Verify behavior and compatibility.
+
+23. Run `bb dev:test -v 'logseq.cli.command.graph-test'` and verify new command tests pass.
+24. Run `bb dev:test -v 'logseq.cli.format-test'` and verify human, JSON, and EDN formatting tests pass.
+25. Run `bb dev:test -v 'logseq.cli.integration-test'` and verify graph-info integration behavior across db-worker-node is green.
+26. Run `bb dev:lint-and-test` and verify `0 failures, 0 errors`.
+27. Review against `/Users/rcmerci/gh-repos/logseq/prompts/review.md` checklist before final submission.
+
+## Edge cases
+
+| Scenario | Expected behavior |
+|---|---|
+| Graph has only default kv rows. | Human output shows summary lines plus kv section with default keys. |
+| Graph has additional future `:logseq.kv/*` keys. | All persisted keys are included automatically without code changes. |
+| Graph has composite kv values such as map or vector. | Human output renders values safely as printable EDN strings. |
+| Graph has boolean and UUID kv values. | JSON output serializes them in existing normalize-json behavior without crashes. |
+| Kv key includes `token`, `secret`, or `password`. | Human, JSON, and EDN outputs all show redacted value. |
+| Kv value is a very long string. | Human output shows truncated text with explicit marker. |
+| Query returns no kv rows due to corrupted graph state. | Command still succeeds with summary placeholders and an explicit empty kv section. |
+| Existing script parses `graph-created-at` and `schema-version` fields. | Backward compatible fields remain present in response data. |
+| Human output consumers expect old first three lines. | Existing first three lines remain unchanged in order and meaning. |
+
+## Verification commands and expected outputs
+
+```bash
+bb dev:test -v 'logseq.cli.command.graph-test'
+bb dev:test -v 'logseq.cli.format-test'
+bb dev:test -v 'logseq.cli.integration-test'
+bb dev:lint-and-test
+```
+
+Each command should complete with `0 failures, 0 errors`.
+
+Integration output should include a non-empty kv field in `graph info` JSON payload.
+
+Human output should include `Graph`, `Created at`, and `Schema version` before the kv section.
+
+## Testing Details
+
+The tests verify behavior at command assembly, output formatting, and end-to-end runtime boundaries.
+
+The command tests validate query usage and payload compatibility instead of checking internal helper implementation details only.
+
+The format tests verify visible behavior for human readability and machine parseability for JSON and EDN outputs.
+
+The integration test verifies real db-worker-node invocation and confirms that kv data is actually surfaced through CLI transport.
+
+## Implementation Details
+
+- Reuse `:thread-api/q` and avoid introducing a new db-worker-node endpoint.
+- Keep `execute-graph-info` backward compatible for existing top-level summary fields.
+- Add one new ident-keyed kv map field for scripts instead of spreading arbitrary keys at top level.
+- Keep kv ordering deterministic in CLI code to stabilize human snapshots and tests.
+- Render complex values safely in human output with printable EDN formatting.
+- Redact sensitive keys in human, JSON, and EDN output for `token`, `secret`, and `password` patterns.
+- Truncate very long string values in human output only.
+- Preserve existing output pipeline behavior for `:json`, `:edn`, and `:human`.
+- Keep command parser and `graph info` CLI flags unchanged for this iteration.
+- Follow `@test-driven-development` strictly and use `@clojure-debug` on unexpected failures.
+
+## Question
+
+Decision: The new structured kv field is a single ident-keyed map for machine output.
+
+Decision: Human, JSON, and EDN outputs must redact kv keys matching sensitive patterns like `token`, `secret`, or `password`.
+
+Decision: Human output must truncate very long string values with an explicit marker.
+
+---
diff --git a/docs/agent-guide/050-sync-download-create-empty-db.md b/docs/agent-guide/050-sync-download-create-empty-db.md
new file mode 100644
index 0000000000..bcd6faf57f
--- /dev/null
+++ b/docs/agent-guide/050-sync-download-create-empty-db.md
@@ -0,0 +1,188 @@
+# Sync Download Create Empty Db Implementation Plan
+
+Goal: Ensure `sync download` never writes `db-initial-data` before snapshot import by starting `db-worker-node` with an explicit empty-db mode.
+
+Architecture: Add a new db-worker startup flag `--create-empty-db` and plumb it through CLI server orchestration only for the `sync download` path.
+
+Architecture: When the flag is enabled, `db-worker-node` will call `:thread-api/create-or-open-db` with `{:datoms []}` during daemon startup so `frontend.worker.db-core/<create-or-open-db!` skips `build-db-initial-data` writes.
+
+Tech Stack: ClojureScript, Node child process args, db-worker daemon lock lifecycle, thread-api invoke path, babashka test runner.
+
+Related: Relates to `docs/agent-guide/047-logseq-cli-sync-command.md`.
+
+Related: Builds on `docs/agent-guide/048-sync-download-start-reliability.md`.
+
+Related: Relates to `docs/agent-guide/033-desktop-db-worker-node-backend.md` and `docs/agent-guide/034-db-worker-node-owner-process-management.md`.
+
+## Problem statement
+
+`sync download` currently reaches remote graph listing by ensuring a db-worker runtime for the target repo before the snapshot is imported.
+
+The startup call in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` always invokes `:thread-api/create-or-open-db` with empty opts `{}`.
+
+`/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` interprets `datoms=nil` as a signal to write `db-initial-data` when initial data does not already exist.
+
+For download-first graph bootstrap, this creates local initialization writes before remote snapshot import, which is unnecessary and can introduce non-snapshot state.
+
+The desired behavior is to create an empty DB for download bootstrap and let sync snapshot import be the only writer of initial graph content.
+
+`sync download` must also verify the target graph DB is empty before importing snapshot data.
+
+If the DB is not empty, `sync download` must fail fast with a clear error instead of continuing import.
+
+This plan follows `@planning-documents`, `@writing-plans`, and executes implementation with `@test-driven-development` plus `@clojure-debug` on failures.
+
+## Testing Plan
+
+I will add daemon argument plumbing tests that fail first when `--create-empty-db` is missing from spawn and parse layers.
+
+I will add sync command execution tests that fail first unless `sync download` asks server orchestration to enable create-empty mode.
+
+I will add db-worker-node startup behavior tests that fail first unless startup uses `{:datoms []}` when create-empty mode is enabled.
+
+I will add sync download safety tests that fail first unless the command rejects non-empty graph DB state.
+
+I will run focused test namespaces after each phase and then run the full `bb dev:lint-and-test` regression suite.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Current integration map
+
+```text
+sync download
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/db_worker/daemon.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs
+  -> :thread-api/db-sync-download-graph-by-id import path
+```
+
+## Scope and non-goals
+
+In scope are CLI-to-daemon argument plumbing, db-worker startup behavior change behind a new flag, tests, and docs updates.
+
+Out of scope are sync protocol changes, snapshot payload format changes, and non-download command behavior changes.
+
+## Implementation plan
+
+### Phase 0. Baseline and failure capture.
+
+1. Run `bb dev:test -v logseq.db-worker.daemon-test` and record baseline.
+2. Run `bb dev:test -v frontend.worker.db-worker-node-test` and record baseline.
+3. Run `bb dev:test -v logseq.cli.server-test` and record baseline.
+4. Run `bb dev:test -v logseq.cli.command.sync-test` and record baseline.
+
+### Phase 1. RED tests for daemon flag plumbing.
+
+5. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/db_worker/daemon_test.cljs` that `spawn-server!` appends `--create-empty-db` when `:create-empty-db? true` is passed.
+6. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/db_worker/daemon_test.cljs` that `spawn-server!` keeps default args unchanged when `:create-empty-db?` is absent or false.
+7. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that `parse-args` recognizes `--create-empty-db` and maps it to `:create-empty-db? true`.
+8. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that help output documents `--create-empty-db` as a startup option.
+9. Run `bb dev:test -v logseq.db-worker.daemon-test` and `bb dev:test -v frontend.worker.db-worker-node-test` and confirm RED.
+
+### Phase 2. GREEN implementation for daemon flag plumbing.
+
+10. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/db_worker/daemon.cljs` so `spawn-server!` accepts `:create-empty-db?` and conditionally appends `--create-empty-db`.
+11. Keep process scanning in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/db_worker/daemon.cljs` compatible by ignoring unknown flags as today.
+12. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` `parse-args` to set `:create-empty-db? true` when `--create-empty-db` is present.
+13. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` `show-help!` to include one line for `--create-empty-db`.
+14. Re-run `bb dev:test -v logseq.db-worker.daemon-test` and `bb dev:test -v frontend.worker.db-worker-node-test` and confirm green.
+
+### Phase 3. RED tests for sync download orchestration.
+
+15. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` that `:sync-download` calls `cli-server/ensure-server!` with `:create-empty-db? true`.
+16. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` that `spawn-server!` forwards `:create-empty-db?` from `ensure-server-started!` config when spawning a new daemon.
+17. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that `sync download` path keeps existing `graph-exists` guard unchanged while still enabling create-empty mode on success paths.
+18. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` that `sync download` fails fast with a dedicated error when the graph DB is not empty.
+19. Run `bb dev:test -v logseq.cli.command.sync-test` and `bb dev:test -v logseq.cli.server-test` and confirm RED.
+
+### Phase 4. GREEN implementation for sync download orchestration.
+
+20. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` so the `:sync-download` execution path enriches config with `:create-empty-db? true` before `invoke-global` and `invoke-with-repo`.
+21. Add a DB emptiness guard in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` or worker thread-api path that explicitly validates target graph DB is empty before calling `:thread-api/db-sync-download-graph-by-id`.
+22. Keep non-download sync actions in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` unchanged so default startup remains backward compatible.
+23. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` and its internal `spawn-server!` wrapper to pass through `:create-empty-db?` to daemon spawn.
+24. Re-run `bb dev:test -v logseq.cli.command.sync-test` and `bb dev:test -v logseq.cli.server-test` and confirm green.
+
+### Phase 5. RED tests for startup create-or-open behavior.
+
+25. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that startup invokes `thread-api/create-or-open-db` with `[repo {:datoms []}]` when `:create-empty-db? true`.
+26. Add a failing test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that default startup still invokes `[repo {}]` when flag is not set.
+27. Add a failing behavior test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` or `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` validating download bootstrap path does not depend on locally generated initial data.
+28. Add a failing behavior test validating non-empty graph DB state is rejected before import starts.
+29. Run targeted tests and confirm RED failures are behavior-based.
+
+### Phase 6. GREEN implementation for empty-db startup.
+
+30. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` `start-daemon!` to pass startup opts `{:datoms []}` to `:thread-api/create-or-open-db` only when `:create-empty-db? true`.
+31. Keep lock lifecycle and health endpoints unchanged in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs`.
+32. Add a tiny helper in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` if needed to keep startup opts construction testable.
+33. Implement or expose a reusable DB emptiness check in worker/CLI path and return a stable error code for non-empty DB.
+34. Re-run `bb dev:test -v frontend.worker.db-worker-node-test` and the selected download behavior test namespace until green.
+
+### Phase 7. Docs and regression.
+
+35. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to document that `sync download` starts db-worker in create-empty mode and rejects non-empty DB state.
+36. Update `/Users/rcmerci/gh-repos/logseq/docs/developers/desktop-db-worker-node.md` with a note that create-empty mode is CLI download bootstrap behavior and does not change desktop default startup.
+37. Run `bb dev:lint-and-test` from `/Users/rcmerci/gh-repos/logseq` and ensure full suite passes.
+38. Run final review checklist in `/Users/rcmerci/gh-repos/logseq/prompts/review.md` before merge.
+
+## Edge cases to cover explicitly
+
+| Scenario | Expected behavior |
+|---|---|
+| `sync download` for a brand-new graph. | Daemon starts with `--create-empty-db` and startup `create-or-open-db` uses `{:datoms []}`. |
+| `sync start`, `sync upload`, and graph CRUD commands. | No `--create-empty-db` flag is used, and existing startup behavior stays unchanged. |
+| Existing local graph (`graph-exists`). | Command fails before daemon startup as it does today. |
+| Existing ready daemon lock for the same repo. | Command must validate DB emptiness before download and fail fast when DB is not empty. |
+| Missing remote graph. | `remote-graph-not-found` response remains unchanged, and no behavior regression in error shape occurs. |
+| Flag typo or absent flag. | Startup remains backward compatible with default `create-or-open-db` opts `{}`. |
+
+## Verification command matrix
+
+| Command | Expected outcome |
+|---|---|
+| `bb dev:test -v logseq.db-worker.daemon-test` | Spawn arg and parser tests for `--create-empty-db` pass. |
+| `bb dev:test -v frontend.worker.db-worker-node-test` | Startup invoke args and help text tests pass. |
+| `bb dev:test -v logseq.cli.server-test` | CLI server pass-through tests for `:create-empty-db?` pass. |
+| `bb dev:test -v logseq.cli.command.sync-test` | `sync download` ensures server with create-empty mode. |
+| `bb dev:test -v logseq.cli.commands-test` | Existing `graph-exists` guard and command dispatch remain stable. |
+| `bb dev:test -v logseq.cli.integration-test/test-cli-sync-download-and-start-readiness-with-mocked-sync` | Integration path remains green with download plus start readiness behavior. |
+| `bb dev:lint-and-test` | Full lint and unit test suite exits with code `0`. |
+
+## Rollout notes
+
+This change is intentionally scoped to startup behavior for `sync download` and does not alter runtime sync protocol.
+
+If regressions appear, rollback is to remove `:create-empty-db?` wiring in sync command and keep daemon/parser support dormant until retried.
+
+## Testing Details
+
+Tests focus on externally visible behavior, namely which startup args are passed and whether startup create-or-open uses empty datoms in download bootstrap mode.
+
+Tests also verify `sync download` rejects non-empty graph DB state before any import side effect.
+
+Tests avoid asserting private implementation internals except where argument boundaries are the behavior contract.
+
+Integration coverage confirms existing sync download and sync start semantics remain stable after plumbing changes.
+
+## Implementation Details
+
+- Add `:create-empty-db?` option plumbing from sync command to CLI server spawn path.
+- Add `--create-empty-db` process arg emission in daemon spawn helper.
+- Parse `--create-empty-db` in db-worker-node entrypoint args.
+- When create-empty is enabled, startup invoke payload uses `[repo {:datoms []}]`.
+- Add a strict pre-download emptiness check and fail with a stable error code when DB is not empty.
+- Keep default startup invoke payload `[repo {}]` for all other flows.
+- Keep lock ownership and stale-lock cleanup behavior unchanged.
+- Keep command-level `graph-exists` and `remote-graph-not-found` behaviors unchanged.
+- Update CLI and developer docs with exact scope of the new flag.
+- Run targeted tests first, then full `bb dev:lint-and-test`.
+- Use `@test-driven-development` workflow and `@clojure-debug` when failures are non-obvious.
+
+## Question
+
+No open question.
+
+---
diff --git a/docs/agent-guide/051-logseq-cli-sync-upload-fix.md b/docs/agent-guide/051-logseq-cli-sync-upload-fix.md
new file mode 100644
index 0000000000..e4c3c241ee
--- /dev/null
+++ b/docs/agent-guide/051-logseq-cli-sync-upload-fix.md
@@ -0,0 +1,347 @@
+# Logseq CLI Sync Upload Fix Plan
+
+Goal: Fix `logseq sync upload` so a CLI-managed local graph can be uploaded successfully with the current `logseq-cli` + `db-worker-node` architecture, including the first upload of a graph that does not yet have a local `graph-id`.
+
+Architecture: Keep the CLI surface small and move the real fix into the worker-side sync layer so `:thread-api/db-sync-upload-graph` becomes self-sufficient: it should resolve or create the remote graph when needed, persist the resulting graph metadata locally, and then perform snapshot upload.
+
+Architecture: Remove the current error-swallowing behavior in worker upload so failures propagate back through `db-worker-node` and the CLI can report an actual error instead of a false success.
+
+Tech Stack: ClojureScript, `logseq-cli`, `db-worker-node`, `frontend.worker.sync`, db-sync HTTP endpoints, promesa, babashka test runner.
+
+Related: Builds on `docs/agent-guide/047-logseq-cli-sync-command.md`.
+
+Related: Relates to `docs/cli/logseq-cli.md` and `docs/developers/desktop-db-worker-node.md`.
+
+## Problem statement
+
+With the current implementation, `logseq sync upload --graph <name>` is wired only as:
+
+- CLI `sync upload`
+- `logseq.cli.command.sync/execute`
+- `:thread-api/db-sync-upload-graph`
+- `frontend.worker.sync/upload-graph!`
+
+That path assumes the local graph already has a usable remote `graph-id`.
+
+However, `frontend.worker.sync/upload-graph!` currently fails when either `http-base` or `graph-id` is missing:
+
+- `http-base` comes from CLI sync config and is present in the provided `cli.edn`.
+- `graph-id` is read from local graph metadata via `get-graph-id`.
+- For a fresh local graph that has never been uploaded or downloaded before, `graph-id` is typically missing.
+
+The desktop/UI flow does not have this problem because `frontend.handler.db_based.sync/<rtc-upload-graph!` first calls `<rtc-create-graph!`, persists the returned graph id locally, and only then invokes `:thread-api/db-sync-upload-graph`.
+
+The CLI flow does not perform that preflight step, so first-time upload cannot work reliably.
+
+There is a second bug that makes the failure harder to see: `frontend.worker.sync/upload-graph!` currently catches errors and only logs them with `js/console.error`, which can turn a failed upload into a misleading success result from the CLI perspective.
+
+In practice, with a `cli.edn` that already provides `ws-url`, `http-base`, `auth-token`, and `e2ee-password`, upload can still fail because the missing piece is remote graph bootstrap and proper error propagation, not just config.
+
+## Current implementation findings
+
+### 1. CLI upload path is too thin for first-time upload
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs`
+
+`execute` for `:sync-upload` currently does only one repo-scoped invoke:
+
+- `:thread-api/set-db-sync-config`
+- `:thread-api/db-sync-upload-graph`
+
+There is no CLI-side or worker-side step that ensures the remote graph exists before upload starts.
+
+### 2. Worker upload requires an existing local graph id
+
+`/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs`
+
+`upload-graph!` currently derives:
+
+- `base` from `http-base-url`
+- `graph-id` from `get-graph-id`
+
+If either value is missing, it rejects with `ex-info "db-sync missing upload info"`.
+
+This is correct as a low-level invariant, but it means the higher-level upload orchestration is incomplete.
+
+### 3. Desktop flow already has the missing bootstrap logic
+
+`/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/db_based/sync.cljs`
+
+`<rtc-upload-graph!` does:
+
+1. `<rtc-create-graph!`
+2. persist returned graph metadata locally
+3. call `:thread-api/db-sync-upload-graph`
+4. refresh remote graphs / start sync
+
+So the product already has a working conceptual flow, but the CLI path bypasses the graph-creation step.
+
+### 4. Upload errors are swallowed
+
+`/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs`
+
+`upload-graph!` ends with a broad `p/catch` that only does `js/console.error`.
+
+That means transport and CLI layers cannot reliably distinguish success from failure.
+
+### 5. Test coverage misses the real failing case
+
+Current CLI tests mostly verify transport wiring, for example that `sync upload` invokes `:thread-api/db-sync-upload-graph`.
+
+What is missing is an end-to-end behavior test for:
+
+- local graph without graph id
+- configured `http-base` + `auth-token`
+- worker creating or resolving a remote graph
+- successful upload
+- failure surfacing when remote bootstrap or snapshot upload fails
+
+## Root cause summary
+
+The broken behavior is not primarily a config parsing problem.
+
+The actual root causes are:
+
+1. `sync upload` assumes local sync metadata already exists, but first-time CLI upload has no step to create or resolve a remote graph.
+2. Worker upload swallows errors, so CLI output can be misleading.
+3. Desktop and CLI implement different upload orchestration paths, which caused the CLI path to miss required bootstrap logic.
+4. There is no regression test covering first-time upload from a local-only graph.
+
+## Desired behavior
+
+Given a CLI config containing valid sync credentials and endpoints, `logseq sync upload --graph <name>` should:
+
+1. start or reuse the graph's `db-worker-node`
+2. apply sync config to the worker
+3. detect whether the local graph already has a remote `graph-id`
+4. if missing, resolve or create the remote graph
+5. persist the resolved/created graph id and sync metadata locally
+6. upload the graph snapshot
+7. return a real success result only when upload actually succeeds
+8. return a real error with context when any step fails
+
+This should work both for:
+
+- an already-linked graph that has a local `graph-id`
+- a fresh local graph being uploaded for the first time
+
+## Recommended design
+
+### Option A: Fix inside worker upload orchestration
+
+Preferred approach: make `frontend.worker.sync/upload-graph!` capable of ensuring remote graph identity before snapshot upload.
+
+This keeps the CLI simple and makes `:thread-api/db-sync-upload-graph` a complete unit of behavior.
+
+Suggested worker-side flow:
+
+1. Read local `graph-id`.
+2. If present, continue with existing upload logic.
+3. If absent, list remote graphs visible to the current auth context.
+4. Match by canonical graph name.
+5. If a matching remote graph exists, bind local graph to that `graph-id`.
+6. If no matching remote graph exists, create one with the current graph name and schema version.
+7. Persist returned graph metadata locally.
+8. Continue snapshot upload using the resolved `graph-id`.
+
+This mirrors the desktop behavior conceptually while avoiding duplicated orchestration in CLI code.
+
+### Option B: Add CLI-specific preflight before invoking upload
+
+Alternative approach: keep worker upload low-level and add a new CLI-side preflight that creates or resolves the remote graph before invoking `:thread-api/db-sync-upload-graph`.
+
+I do not recommend this because it duplicates sync orchestration across CLI and desktop-adjacent code and makes the worker thread API less useful as a stable contract.
+
+## Scope
+
+### In scope
+
+- Fix first-time `sync upload` for CLI-managed graphs.
+- Make worker upload propagate failures.
+- Reuse existing remote graph APIs (`GET /graphs`, `POST /graphs`) instead of inventing a new cloud protocol.
+- Add tests for first-time upload, already-linked upload, and failure propagation.
+- Update CLI docs so `sync upload` behavior is explicit.
+
+### Out of scope
+
+- Changing the cloud snapshot upload protocol.
+- Adding a new top-level CLI command for graph creation.
+- Reworking websocket sync start/stop behavior.
+- Large refactors unrelated to upload bootstrap.
+
+## Implementation plan
+
+### Phase 1. Add failing tests for the broken behavior
+
+1. Add a worker sync test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` for first-time upload when local graph has no graph id.
+2. Stub remote graph listing to return no match, stub graph creation to return a new id, and assert upload continues with that id.
+3. Add a companion test where remote graph listing already contains the same graph name and assert upload reuses the existing graph id instead of creating a duplicate graph.
+4. Add a failure test that simulates graph creation failure and asserts the promise rejects rather than resolving silently.
+5. Add a failure test that simulates snapshot upload failure and asserts the CLI-visible result is an error, not success.
+6. Add a CLI command execution/integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` or CLI integration tests that covers the real first-upload path, not just method wiring.
+
+### Phase 2. Move remote graph bootstrap into worker sync code
+
+7. Add a worker helper in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` to ensure a usable remote graph id before snapshot upload.
+8. That helper should read the local graph name from repo name using the same canonicalization rules already used by CLI and desktop sync.
+9. If local graph id exists, return it immediately.
+10. If local graph id is missing, call existing remote graph list API.
+11. If a graph with the same canonical name exists, reuse its `graph-id` and persist it locally.
+12. If no match exists, call the existing graph creation API and persist the new `graph-id` locally.
+13. Keep local metadata writes inside worker code so later sync commands (`sync start`, asset upload, etc.) see a consistent graph identity.
+
+### Phase 3. Reuse or extract desktop graph-creation logic
+
+14. Avoid leaving two divergent graph-creation implementations.
+15. Extract the parts of `frontend.handler.db_based.sync/<rtc-create-graph!` that are transport/persistence logic into worker-shared code, or reimplement them once in `frontend.worker.sync` and have desktop code reuse that worker-oriented path where practical.
+16. Keep UI-only behaviors such as notifications and state refresh in the frontend handler layer.
+17. Ensure the shared implementation supports `graph-e2ee?` and schema version consistently.
+
+### Phase 4. Fix error propagation
+
+18. Remove the broad catch-and-only-log behavior at the end of `frontend.worker.sync/upload-graph!`.
+19. If local logging is still desired, log and rethrow, or convert to a structured `ex-info` with context.
+20. Ensure `db-worker-node` HTTP invoke returns a failure status when upload bootstrap or upload body transfer fails.
+21. Verify CLI output paths show the actual error code/message.
+
+### Phase 5. Clarify E2EE behavior for first-time upload
+
+22. Decide what `graph-e2ee?` should be when a local graph has no sync metadata yet.
+23. Prefer to match the current desktop default for fresh cloud graph creation, which treats missing value as encrypted unless explicitly false.
+24. Make that default explicit in code and tests instead of relying on incidental `nil` handling.
+25. Ensure the provided `e2ee-password` config is actually used when a new encrypted remote graph is created.
+26. Add at least one test covering fresh upload with encrypted-graph setup.
+
+### Phase 6. Update docs and command expectations
+
+27. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` so `sync upload` explicitly documents first-time upload behavior.
+28. Document that upload will resolve an existing same-name remote graph or create a new remote graph when no graph id is present locally.
+29. Document the failure modes clearly: auth failure, graph creation failure, snapshot upload failure, and local DB missing.
+30. Do not include real tokens or passwords in docs or tests.
+
+## Detailed design notes
+
+### Remote graph resolution rules
+
+For first-time upload, use the local graph name after stripping the internal db prefix in the same way current sync code already does for remote graph matching.
+
+Recommended resolution order:
+
+1. local `graph-id`
+2. exact remote graph name match
+3. create remote graph
+
+If graph name matching can return more than one candidate, fail with a deterministic conflict error instead of guessing.
+
+### Metadata persistence
+
+After graph resolution/creation succeeds, persist at least:
+
+- `:logseq.kv/graph-uuid`
+- `:logseq.kv/graph-remote?`
+- `:logseq.kv/graph-rtc-e2ee?`
+
+This ensures later commands such as `sync start`, asset operations, and subsequent uploads operate on the same graph identity.
+
+### Error model
+
+Do not return success when worker upload has failed.
+
+Prefer structured `ex-info` errors with enough context for CLI formatting, such as:
+
+- `:repo`
+- `:graph-id`
+- `:graph-name`
+- `:status`
+- `:url`
+- remote response body when safe
+
+### Why the fix belongs in worker sync
+
+`db-sync-upload-graph` is already the contract used by CLI.
+
+If the worker API stays incomplete and CLI grows its own upload bootstrap logic, we will keep drifting away from the desktop path and make sync semantics harder to maintain.
+
+Putting graph bootstrap in worker sync makes the behavior available to every caller and keeps the CLI transport layer thin.
+
+## Verification plan
+
+### Targeted automated verification
+
+- `bb dev:test -v frontend.worker.db-sync-test`
+- `bb dev:test -v logseq.cli.command.sync-test`
+- `bb dev:test -v logseq.cli.integration-test`
+
+### Manual verification with CLI config
+
+Use a `cli.edn` with these keys configured:
+
+- `:ws-url`
+- `:http-base`
+- `:auth-token`
+- `:e2ee-password`
+
+Do not commit real token values.
+
+Manual checks:
+
+1. Create a brand-new local graph with no stored `graph-id`.
+2. Run `logseq sync upload --graph <name>`.
+3. Confirm the command returns success only after remote graph bootstrap + snapshot upload finish.
+4. Run `logseq sync status --graph <name>` and confirm the graph now has stable remote metadata.
+5. Re-run `logseq sync upload --graph <name>` and confirm it reuses the existing graph id.
+6. Force a failing auth token and confirm the CLI returns an error instead of false success.
+7. Force a server-side snapshot upload failure and confirm the CLI returns an error with useful context.
+
+## Acceptance criteria
+
+The fix is complete when all of the following are true:
+
+- `logseq sync upload --graph <name>` works for a fresh local graph with no prior `graph-id`.
+- The command reuses an existing same-name remote graph when appropriate.
+- Worker upload failures propagate to CLI callers and no longer appear as success.
+- Desktop and CLI upload bootstrap logic no longer diverge in a risky way.
+- Test coverage includes first-time upload and failure propagation.
+- CLI docs describe first-time upload behavior and required config without exposing secrets.
+
+## Risks and mitigations
+
+### Risk: duplicate remote graphs
+
+If upload always creates a graph when local `graph-id` is missing, we may create duplicates.
+
+Mitigation: list remote graphs first and only create when there is no exact name match.
+
+### Risk: inconsistent E2EE defaults
+
+Fresh graph creation from CLI may accidentally create an unencrypted graph while desktop defaults to encrypted.
+
+Mitigation: make fresh-upload `graph-e2ee?` behavior explicit and test it.
+
+### Risk: hidden regressions in desktop flow
+
+If desktop and worker share more code, UI expectations could shift.
+
+Mitigation: keep only transport/bootstrap logic shared; keep UI state refresh and notifications in frontend handler code.
+
+## Suggested file touch list
+
+Primary implementation files:
+
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/db_based/sync.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs`
+
+Primary test files:
+
+- `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`
+
+Primary docs:
+
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+
+## Question
+
+No open question. The current implementation gap is clear enough to proceed with a worker-centered fix.
diff --git a/docs/agent-guide/052-logseq-cli-sync-upload-graph-uuid-alignment.md b/docs/agent-guide/052-logseq-cli-sync-upload-graph-uuid-alignment.md
new file mode 100644
index 0000000000..288acc2032
--- /dev/null
+++ b/docs/agent-guide/052-logseq-cli-sync-upload-graph-uuid-alignment.md
@@ -0,0 +1,172 @@
+# CLI Sync Upload Graph UUID Alignment Implementation Plan
+
+Goal: Make `logseq sync upload` persist local graph UUID metadata so CLI and web app upload flows leave the graph in the same sync-ready state.
+
+Architecture: Keep `:thread-api/db-sync-upload-graph` as the single upload contract used by both CLI and web app.
+Architecture: Align identity persistence inside `frontend.worker.sync` so every resolved graph id is written to both client-op storage and graph KV metadata.
+Architecture: Use web app graph identity persistence semantics from `frontend.handler.db_based.sync/<rtc-create-graph!` as the source of truth for what local metadata must exist after upload bootstrap.
+
+Tech Stack: ClojureScript, Promesa, Datascript, db-worker-node HTTP invoke API, logseq-cli sync command stack.
+
+Related: Builds on `docs/agent-guide/051-logseq-cli-sync-upload-fix.md`.
+Related: Relates to `docs/agent-guide/047-logseq-cli-sync-command.md`.
+
+## Problem statement
+
+`logseq sync upload` currently reaches `frontend.worker.sync/upload-graph!` through `db-worker-node` and can complete snapshot upload while local graph KV metadata still does not contain `:logseq.kv/graph-uuid`.
+
+The current worker persistence path writes graph id to `frontend.worker.sync.client-op` but does not write `:logseq.kv/graph-uuid` into the graph database.
+
+The web app has an established graph identity persistence pattern in `frontend.handler.db_based.sync/<rtc-create-graph!`, where graph creation persists `:logseq.kv/graph-uuid` and related sync metadata into graph KV.
+
+This mismatch causes CLI-uploaded graphs to remain partially initialized from the local metadata perspective even though remote upload succeeded.
+
+The practical symptom is that features reading graph UUID from `logseq.db/get-graph-rtc-uuid` still see nil after upload.
+
+I will use @test-driven-development for every implementation step and keep CLI behavior aligned with @logseq-cli command contracts.
+
+## Current flow comparison
+
+| Dimension | CLI upload flow today | Web app reference behavior | Gap to close |
+|---|---|---|---|
+| Entry point | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` via `execute-sync-upload`. | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/db_based/sync.cljs` via `<rtc-upload-graph!` and `<rtc-create-graph!`. | None on entry API shape. |
+| Worker API | Calls `:thread-api/db-sync-upload-graph` through `/v1/invoke`. | Calls the same `:thread-api/db-sync-upload-graph` for upload. | None on worker method selection. |
+| Graph id resolution | `frontend.worker.sync/<ensure-upload-graph-identity!` resolves from DB KV, client-op, remote list, or remote create. | Same worker resolution path during upload bootstrap. | None on resolution source order. |
+| Graph id persistence | `frontend.worker.sync/persist-upload-graph-identity!` writes client-op graph UUID and sync flags but not `:logseq.kv/graph-uuid`. | Web app graph create flow writes `:logseq.kv/graph-uuid` into graph KV. | Missing graph UUID write in worker upload persistence path. |
+| Post-upload local state | Graph may still miss `:logseq.kv/graph-uuid`. | Expected local graph identity metadata is complete after remote bootstrap. | CLI path is not fully sync-ready for UUID readers. |
+
+## Target aligned behavior
+
+After `logseq sync upload --graph <name>` succeeds, local graph metadata must contain a stable `:logseq.kv/graph-uuid` value in graph KV and the same graph id in client-op storage.
+
+The persistence rule must be enforced by worker sync code so both CLI and web app callers inherit identical behavior.
+
+When upload finds graph id from client-op fallback, worker must backfill missing graph KV UUID before returning success.
+
+Repeated uploads must be idempotent and must not create a new graph id or rewrite to a different value unexpectedly.
+
+## Architecture and integration points
+
+```text
+CLI path
+  logseq.cli.command.sync/execute-sync-upload
+    -> logseq.cli.transport/invoke POST /v1/invoke
+    -> frontend.worker.db_worker_node /v1/invoke
+    -> :thread-api/db-sync-upload-graph in frontend.worker.db_core
+    -> frontend.worker.sync/<ensure-upload-graph-identity!
+    -> frontend.worker.sync/upload-graph!
+
+Web app path
+  frontend.handler.db_based.sync/<rtc-upload-graph!
+    -> state/<invoke-db-worker :thread-api/db-sync-upload-graph
+    -> frontend.worker.sync/<ensure-upload-graph-identity!
+    -> frontend.worker.sync/upload-graph!
+
+Web app source-of-truth identity persistence reference
+  frontend.handler.db_based.sync/<rtc-create-graph!
+    -> ldb/transact! with :logseq.kv/graph-uuid
+```
+
+## Testing Plan
+
+I will add worker unit tests that fail first when upload identity resolution does not persist `:logseq.kv/graph-uuid` into the graph database.
+
+I will add worker unit tests that fail first for the three identity branches, which are graph id from remote create, graph id from remote name match, and graph id from client-op fallback.
+
+I will add regression assertions that verify the persisted graph UUID is readable through `logseq.db/get-graph-rtc-uuid` and matches `client-op/get-graph-uuid`.
+
+I will add a CLI-facing regression check that validates upload success is followed by graph info data containing `logseq.kv/graph-uuid` in real or staged integration coverage.
+
+I will run targeted tests after each micro-change, then run broad lint and test commands before final review.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Implementation plan
+
+### Phase 1. Add failing worker tests for UUID persistence parity.
+
+1. Add a failing assertion in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` for remote-create upload bootstrap to assert `ldb/get-graph-rtc-uuid` is set after `<ensure-upload-graph-identity!`.
+2. Add a failing assertion in the same file for remote-name-match bootstrap to assert graph KV UUID is also set.
+3. Add a failing test for the client-op-fallback branch where graph id exists only in client-op and graph KV UUID is missing before upload identity resolution.
+4. Add a failing idempotency assertion that repeated identity ensure calls keep the same graph UUID value.
+5. Run `bb dev:test -v frontend.worker.db-sync-test` and confirm the new assertions fail before implementation.
+
+### Phase 2. Implement shared worker identity persistence aligned with web app semantics.
+
+6. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` to persist graph UUID into graph KV when graph id is resolved.
+7. Reuse the same UUID coercion semantics as web app reference code by converting graph-id string to UUID before writing `:logseq.kv/graph-uuid`.
+8. Extend `set-graph-sync-metadata!` or a new helper to write `:logseq.kv/graph-uuid`, `:logseq.kv/graph-remote?`, and `:logseq.kv/graph-rtc-e2ee?` in one place.
+9. Keep `client-op/update-graph-uuid` writes unchanged so existing fallback behavior remains compatible.
+10. Ensure `<ensure-upload-graph-identity!` calls the persistence helper even when graph id is resolved from local fallback, so backfill works for previously uploaded graphs.
+11. Preserve return payload shape from upload identity functions to avoid CLI output contract changes.
+12. Run `bb dev:test -v frontend.worker.db-sync-test` until all new and existing sync tests pass.
+
+### Phase 3. Guard CLI and web caller alignment.
+
+13. Add or extend tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` to assert CLI upload still delegates to `:thread-api/db-sync-upload-graph` without introducing a divergent bootstrap branch.
+14. Add or extend tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/handler/db_based/sync_test.cljs` to assert web app upload path continues to defer bootstrap to worker.
+15. Add a regression check in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that verifies graph metadata reported after upload includes a graph UUID field when the worker upload path succeeds.
+16. Run `bb dev:test -v logseq.cli.command.sync-test` and `bb dev:test -v frontend.handler.db-based.sync-test`.
+17. Run `bb dev:test -v logseq.cli.integration-test` and confirm sync upload behavior remains green.
+
+### Phase 4. Document and verify user-visible behavior.
+
+18. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to state that successful `sync upload` persists local graph UUID metadata.
+19. Add a short troubleshooting note that graph UUID should be visible in graph info output after upload.
+20. Run `bb dev:lint-and-test` from `/Users/rcmerci/gh-repos/logseq` and confirm exit code `0`.
+
+## Edge cases to cover
+
+| Edge case | Expected behavior |
+|---|---|
+| Graph id resolved from client-op only. | Worker backfills `:logseq.kv/graph-uuid` in graph KV during upload identity ensure. |
+| Graph datascript conn is unavailable. | Worker still keeps client-op graph UUID and returns a structured error or deferred persistence path without false success. |
+| Graph id string is malformed. | Worker fails fast with a sync-specific error code instead of writing invalid KV data. |
+| Repeated upload on same graph. | Graph UUID stays stable and no duplicate graph identity writes change semantic value. |
+| Remote graph list returns multiple same-name matches. | Existing ambiguous-match error remains and CLI surfaces deterministic failure. |
+
+## Clarifications needed before coding
+
+Should the fix include automatic backfill on `sync start` and `sync status` in addition to `sync upload`, or is upload-only backfill sufficient for now.
+
+Should malformed graph-id values be rejected hard or stored as raw strings if UUID coercion fails.
+
+For this iteration, rely on upload-triggered backfill on the next upload; do not add a one-time migration or dedicated backfill command.
+
+## Verification commands
+
+| Command | Expected outcome |
+|---|---|
+| `bb dev:test -v frontend.worker.db-sync-test` | New UUID persistence tests fail first, then pass after implementation. |
+| `bb dev:test -v logseq.cli.command.sync-test` | CLI upload delegation contract stays unchanged. |
+| `bb dev:test -v frontend.handler.db-based.sync-test` | Web app upload path remains worker-centered. |
+| `bb dev:test -v logseq.cli.integration-test` | Sync upload integration remains green with graph UUID metadata visible post-upload. |
+| `bb dev:lint-and-test` | Full lint and test suite passes. |
+| `node ./dist/logseq.js --graph demo sync upload --output json` | Returns `status=ok` with graph id on success. |
+| `node ./dist/logseq.js --graph demo graph info --output json` | Output includes `logseq.kv/graph-uuid` for the uploaded graph. |
+
+## Testing Details
+
+The primary behavior test is that graph identity is fully persisted locally after upload, not just remotely acknowledged.
+
+Tests will verify externally observable behavior through `ldb/get-graph-rtc-uuid`, `client-op/get-graph-uuid`, and CLI graph info output.
+
+Tests will avoid asserting private implementation internals and will focus on identity outcomes across the three upload identity branches.
+
+## Implementation Details
+
+- Keep all orchestration inside `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` so CLI and web callers stay aligned.
+- Preserve `:thread-api/db-sync-upload-graph` as the single cross-surface upload API in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`.
+- Reuse existing metadata transaction style from `frontend.handler.db_based.sync/<rtc-create-graph!` for graph UUID persistence semantics.
+- Ensure UUID persistence helper is idempotent and safe to call multiple times.
+- Keep client-op UUID persistence as a compatibility fallback.
+- Do not introduce new cloud API endpoints or protocol changes.
+- Keep CLI upload call sequence unchanged in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs`.
+- Add regression tests before implementation and run them incrementally with @test-driven-development.
+- Update CLI docs to reflect guaranteed local graph UUID persistence after successful upload.
+
+## Decision
+
+For this iteration, upload-triggered backfill is sufficient. Do not add a dedicated backfill command for previously uploaded graphs missing `:logseq.kv/graph-uuid` yet.
+
+---
diff --git a/docs/agent-guide/053-logseq-cli-async-test-isolation.md b/docs/agent-guide/053-logseq-cli-async-test-isolation.md
new file mode 100644
index 0000000000..2f5dcb2ccd
--- /dev/null
+++ b/docs/agent-guide/053-logseq-cli-async-test-isolation.md
@@ -0,0 +1,288 @@
+# Logseq CLI and db-worker-node Async Test Isolation Plan
+
+Goal: Audit all CLI-related async test cases and ensure every mocked function, overridden global binding, and shared test state is reset after each test case so no test leaks state into later tests.
+
+Architecture: Prefer per-test scoped mocking (`with-redefs` / `p/with-redefs`) and explicit `:each` fixtures for mutable globals, while keeping real process/server lifecycle cleanup in `p/finally` so async resources are always released.
+
+Tech Stack: ClojureScript, `cljs.test`, `promesa`, Node.js-based test runtime.
+
+Related: Builds on `docs/agent-guide/001-logseq-cli.md`, `docs/agent-guide/003-db-worker-node-cli-orchestration.md`, `docs/agent-guide/015-logseq-cli-db-worker-node-housekeeping.md`, and `docs/agent-guide/035-logseq-cli-db-worker-deps-cli-decoupling.md`.
+
+## Problem statement
+
+Current CLI-related async tests rely heavily on mutating namespace vars and process globals with `set!`, then restoring them manually in `p/finally` blocks.
+
+That pattern works only if every async branch reaches cleanup. It is easy to miss one restore path, and a failed or aborted test can leave mutated globals behind for later tests.
+
+The most leak-prone coverage today is concentrated in these files:
+
+- `src/test/logseq/cli/command/sync_test.cljs` — many async tests mutate `cli-server/ensure-server!`, `transport/invoke`, and `cli-config/update-config!` with `set!`.
+- `src/test/logseq/cli/commands_test.cljs` — many async command execution tests mutate `cli-server/*`, `transport/invoke`, and add-command resolver vars.
+- `src/test/logseq/cli/server_test.cljs` — async tests mutate daemon fns plus process globals like `js/process.kill` and `child_process.spawn`.
+- `src/test/logseq/cli/command/doctor_test.cljs` and `src/test/logseq/cli/command/graph_test.cljs` — smaller but repeated manual global override patterns.
+- `src/test/logseq/cli/integration_test.cljs` — a mix of safe `p/with-redefs` usage and unsafe direct `set!` of `cli-server/ensure-server!`, `transport/invoke`, and `process.stderr.write` interception.
+- `src/test/logseq/cli/transport_test.cljs` — mutates `url.parse` and depends on manual restoration around async flows.
+- `src/test/frontend/worker/db_worker_node_test.cljs` — async tests mutate platform/db-core/db-lock vars and also interact with module-level `defonce` atoms such as `*sse-clients`, `*ready?`, `*lock-info`, and `*file-handler` in `src/main/frontend/worker/db_worker_node.cljs`.
+
+The risk is not theoretical: these tests are asynchronous, share a single Node process, and run against real namespace vars or process objects. Any missing reset can change behavior of unrelated tests that run later in the same suite.
+
+## Current leak vectors
+
+### 1. Manual `set!` / restore in async tests
+
+The dominant pattern is:
+
+1. capture original var value,
+2. `set!` the var to a mock,
+3. run async code,
+4. restore in `p/finally`.
+
+This appears throughout `sync_test.cljs`, `commands_test.cljs`, `server_test.cljs`, `doctor_test.cljs`, `graph_test.cljs`, and parts of `integration_test.cljs`.
+
+This pattern is brittle because cleanup is duplicated in every test and can drift over time.
+
+### 2. Process-global overrides
+
+Some tests override Node globals directly, for example:
+
+- `child_process.spawn` in `src/test/logseq/cli/server_test.cljs`
+- `js/process.kill` in `src/test/logseq/cli/server_test.cljs`
+- `js/process.stderr.write` via `capture-stderr!` in `src/test/logseq/cli/integration_test.cljs`
+- `url.parse` in `src/test/logseq/cli/transport_test.cljs`
+
+These are more dangerous than namespace-local mocks because they affect any code running in the same process while the override is active.
+
+### 3. Module-level mutable atoms in db-worker-node
+
+`src/main/frontend/worker/db_worker_node.cljs` keeps daemon state in `defonce` atoms:
+
+- `*ready?`
+- `*sse-clients`
+- `*lock-info`
+- `*file-handler`
+
+`db_worker_node_test.cljs` already has one `:each` fixture for print suppression, but the file still contains tests that interact with or depend on mutable daemon state. Some tests locally save and restore `*sse-clients`; others rely on daemon stop paths to reset internals.
+
+This should be normalized into a single fixture-backed reset strategy so every test starts from a known baseline even if a previous test fails unexpectedly.
+
+### 4. Mixed mocking styles across files
+
+Some tests already use safer scoped mocking:
+
+- `p/with-redefs` in `src/test/logseq/cli/integration_test.cljs`
+- `with-redefs` in targeted synchronous tests
+
+But many nearby tests still use raw `set!`. The inconsistency makes future maintenance error-prone and makes it harder to know which tests are safely isolated.
+
+## Scope
+
+This plan covers async tests for current `logseq-cli` and `db-worker-node` behavior.
+
+In scope:
+
+- `src/test/logseq/cli/*.cljs`
+- `src/test/logseq/cli/command/*.cljs`
+- `src/test/frontend/worker/db_worker_node_test.cljs`
+- `src/test/frontend/worker/db_worker_node_lock_test.cljs` if follow-up cleanup is needed for consistency
+
+Out of scope:
+
+- Non-CLI frontend async tests unless a reusable helper extracted here is intentionally shared
+- Refactoring production runtime logic unless needed only to expose test-reset hooks for daemon state
+- Rewriting all sync tests that already use safe scoped mocks
+
+## Desired end state
+
+After this work:
+
+- every async test that mocks a namespace var uses scoped mocking or a standardized helper that guarantees restoration;
+- every process-global override has one canonical helper with guaranteed teardown;
+- every db-worker-node mutable singleton used by tests is reset in an `:each` fixture;
+- no CLI-related async test relies on state left behind by a previous test;
+- the suite can run target namespaces together, repeatedly, and in different orders without order-dependent failures.
+
+## Testing Plan
+
+I will first lock in the current risk surface by inventorying every CLI-related async test that uses `set!`, process-global mutation, or mutable singleton state.
+
+I will convert one representative file in each category to a safer reset pattern before touching the rest, so the approach is proven incrementally.
+
+I will run targeted test namespaces repeatedly and in grouped combinations to detect order-dependent leakage.
+
+NOTE: I will write or adjust tests/helpers before broad refactors where possible, and any unexpected async failure will be debugged before continuing wide mechanical conversion.
+
+## Implementation plan
+
+1. Create an audit checklist of all CLI-related async tests that currently use `set!`, process-global mutation, manual restore logic, or mutable singleton state.
+
+2. Group those findings by leak type:
+   - namespace-var overrides,
+   - Node process/global overrides,
+   - db-worker-node singleton atoms,
+   - real server/daemon lifecycle cleanup.
+
+3. Add a small shared test helper namespace for CLI async isolation, e.g. `src/test/logseq/cli/test_helper.cljs`, to centralize patterns that should no longer be repeated inline.
+
+4. In that helper, add wrappers/macros/functions for scoped async mocking around Promesa flows so tests can replace repeated `orig-*` / `set!` / `p/finally restore` boilerplate.
+
+5. Prefer `p/with-redefs` for namespace vars that are only needed during the async body, especially in:
+   - `src/test/logseq/cli/command/sync_test.cljs`
+   - `src/test/logseq/cli/commands_test.cljs`
+   - `src/test/logseq/cli/command/doctor_test.cljs`
+   - `src/test/logseq/cli/command/graph_test.cljs`
+   - targeted sections of `src/test/logseq/cli/integration_test.cljs`
+
+6. Convert low-risk files first (`graph_test.cljs`, `doctor_test.cljs`, `main_test.cljs` if needed) to establish the preferred style with minimal surface area.
+
+7. Convert `src/test/logseq/cli/command/sync_test.cljs` from repeated manual `set!` restoration to scoped mocks. This file should become the reference pattern for async command tests.
+
+8. Convert `src/test/logseq/cli/commands_test.cljs` in batches, prioritizing the async sections that currently mutate `cli-server/list-graphs`, `cli-server/ensure-server!`, `transport/invoke`, and add-command resolution vars.
+
+9. For `src/test/logseq/cli/server_test.cljs`, separate two concerns:
+   - keep real filesystem/server cleanup in `p/finally`,
+   - move mock restoration for functions/globals into scoped helper wrappers wherever possible.
+
+10. For process-global overrides that cannot use ordinary `with-redefs` (for example `child_process.spawn`, `js/process.kill`, `process.stderr.write`, `url.parse`), add dedicated helper functions that use `try`/`finally` or Promesa-aware wrappers so restoration is guaranteed from one place.
+
+11. Refactor `src/test/logseq/cli/integration_test.cljs` to replace the remaining direct `set!` mocks with `p/with-redefs` where possible, since that file already demonstrates the safer pattern in other tests.
+
+12. Add or reuse an `:each` fixture in `src/test/frontend/worker/db_worker_node_test.cljs` to reset db-worker-node mutable singleton atoms before and after every test:
+    - `*ready?`
+    - `*sse-clients`
+    - `*lock-info`
+    - `*file-handler`
+
+13. Keep the existing quiet-print fixture in `db_worker_node_test.cljs`, but merge or compose it with the new daemon-state reset fixture so both print behavior and daemon singletons are normalized per test.
+
+14. Review tests in `db_worker_node_test.cljs` that directly save/restore individual atoms (for example `*sse-clients`) and simplify them once the shared fixture guarantees a clean baseline.
+
+15. If a daemon stop path is currently relied on for cleanup, keep asserting `stop!` behavior but do not rely on it as the only test isolation mechanism.
+
+16. Add comments in the helper or fixture code documenting the rule: mock restoration belongs in scoped helpers/fixtures, while resource cleanup (servers, files, daemons) belongs in `p/finally`.
+
+17. Update any contributor-facing guidance near the modified tests if a recurring pattern should be preserved, especially when replacing repetitive manual restore code with helper abstractions.
+
+18. Run targeted namespaces individually after each batch of refactors:
+    - `logseq.cli.command.graph-test`
+    - `logseq.cli.command.doctor-test`
+    - `logseq.cli.command.sync-test`
+    - `logseq.cli.server-test`
+    - `logseq.cli.transport-test`
+    - `logseq.cli.commands-test`
+    - `logseq.cli.integration-test`
+    - `frontend.worker.db-worker-node-test`
+
+19. Run grouped combinations of the above namespaces multiple times in the same process to catch order-dependent leaks.
+
+20. Finish with `bb dev:lint-and-test` if the changed surface is stable enough and runtime permits.
+
+## Verification strategy
+
+Use three levels of verification.
+
+### A. Static inventory verification
+
+Re-scan CLI-related test files and confirm that leak-prone raw patterns are either gone or intentionally wrapped:
+
+- direct `set!` to namespace vars in async tests should be eliminated or heavily reduced;
+- any remaining direct process-global mutation must be routed through a dedicated helper with centralized restore logic;
+- db-worker-node singleton atoms should be covered by fixtures rather than ad hoc local resets.
+
+### B. Repetition and order verification
+
+Run the target namespaces repeatedly and in different orders.
+
+At minimum:
+
+- run each namespace alone;
+- run `sync-test`, `commands-test`, and `integration-test` together;
+- run `server-test`, `transport-test`, and `db_worker_node_test` together;
+- re-run the same grouped command at least twice to catch leaked state from the previous run.
+
+### C. Behavioral smoke verification
+
+Confirm that tests still validate real async behavior rather than only helper abstractions:
+
+- server startup/shutdown tests still exercise real server lifecycle paths;
+- integration tests still verify CLI flow outputs;
+- db-worker-node tests still verify daemon and HTTP behavior;
+- helper conversion does not weaken assertions or skip cleanup-sensitive paths.
+
+## Proposed helper patterns
+
+### Pattern 1: Scoped Promesa var redefs
+
+For ordinary vars such as `cli-server/ensure-server!`, `transport/invoke`, `cli-config/update-config!`, and `db-lock/update-lock!`, prefer `p/with-redefs` around the async body.
+
+This should replace bespoke `orig-*` capture and restoration in most test files.
+
+### Pattern 2: Process-global guard helpers
+
+For globals like `process.stderr.write`, `process.kill`, or JS module properties such as `child_process.spawn` and `url.parse`, create helper wrappers such as:
+
+- `with-stderr-write-capture`
+- `with-process-kill-mock`
+- `with-child-process-spawn-mock`
+- `with-js-property-override`
+
+These helpers should always restore the original value in a single `finally` path.
+
+### Pattern 3: db-worker-node state reset fixture
+
+Create a fixture that snapshots and resets db-worker-node singleton atoms around each test. The fixture should not depend on individual tests remembering which atoms they touched.
+
+If some atoms contain resources such as handlers or open references, the fixture should also null them out after test completion.
+
+## Edge cases to validate during implementation
+
+If an async test fails before reaching the happy path, mock restoration must still happen.
+
+If a mocked function is rebound inside nested async calls, the outer helper should still restore the original after the Promise chain settles.
+
+If real daemon startup fails, fixture teardown must not throw while resetting singleton atoms.
+
+If `capture-stderr!` or similar helpers are used concurrently in the future, helper APIs should make nesting/ownership behavior explicit.
+
+If a test still needs local save/restore of atom contents for assertion purposes, that local logic should compose safely with the global fixture baseline.
+
+## Expected file touch points
+
+Primary expected edits:
+
+- `src/test/logseq/cli/command/graph_test.cljs`
+- `src/test/logseq/cli/command/doctor_test.cljs`
+- `src/test/logseq/cli/command/sync_test.cljs`
+- `src/test/logseq/cli/commands_test.cljs`
+- `src/test/logseq/cli/server_test.cljs`
+- `src/test/logseq/cli/transport_test.cljs`
+- `src/test/logseq/cli/integration_test.cljs`
+- `src/test/frontend/worker/db_worker_node_test.cljs`
+- `src/test/logseq/cli/test_helper.cljs` or similar new helper namespace
+
+Possible follow-up edits:
+
+- `src/test/frontend/worker/db_worker_node_lock_test.cljs` if helper reuse or fixture alignment is beneficial
+- any nearby docs/comments that explain the approved async mocking pattern
+
+## Non-goals
+
+This plan does not require rewriting working synchronous tests just to match style.
+
+This plan does not require changing production APIs unless a tiny testability hook is necessary for deterministic reset behavior.
+
+This plan does not require introducing a new test framework; it should stay within current `cljs.test` and `promesa` patterns.
+
+## Decision
+
+Do not add a new lint rule or automated check for this work.
+
+Enforce the no-leaky-mocks rule by convention, shared helpers, and fixtures only.
+
+Adopt a two-layer strategy:
+
+1. use scoped redefs/helpers for mocked functions and process globals;
+2. use `:each` fixtures for mutable singleton state owned by `db-worker-node`.
+
+This keeps the rollout focused on improving test isolation directly, avoids adding maintenance burden for a custom check, and still addresses both function mocking leaks and shared-state leaks.
+
+---
diff --git a/docs/agent-guide/054-db-sync-test-isolation.md b/docs/agent-guide/054-db-sync-test-isolation.md
new file mode 100644
index 0000000000..b54c5f0b9c
--- /dev/null
+++ b/docs/agent-guide/054-db-sync-test-isolation.md
@@ -0,0 +1,166 @@
+# 054-db-sync-test-isolation
+
+## Summary
+
+`bb dev:lint-and-test` would currently fail in CLJS runtime tests, while lint and test compilation would still pass. The observed failures would point to test isolation problems inside `frontend.worker.db-sync-test`, not to a stable regression in db-sync production logic.
+
+## Background
+
+The failing command would be:
+
+- `bb dev:lint-and-test`
+
+Its execution flow would be:
+
+1. lint tasks
+2. CLJS test compilation
+3. CLJS runtime test execution
+
+Observed behavior from the captured run:
+
+- lint would pass
+- test compilation would pass
+- runtime tests would fail with 3 failures
+
+The failing tests would include:
+
+- `frontend.worker.db-sync-test/ensure-upload-graph-identity-defaults-e2ee-enabled-test`
+- `frontend.worker.db-sync-test/download-graph-by-id-fails-on-incomplete-snapshot-frame-test`
+
+A follow-up run of the full namespace would fail on a different test:
+
+- `frontend.worker.db-sync-test/pull-ok-out-of-order-stale-response-is-ignored-test`
+
+This changing failure surface would strongly suggest flaky shared state rather than a deterministic implementation bug.
+
+## Evidence
+
+### 1. Failing tests would pass in isolation
+
+Running these tests individually would pass:
+
+- `frontend.worker.db-sync-test/ensure-upload-graph-identity-defaults-e2ee-enabled-test`
+- `frontend.worker.db-sync-test/download-graph-by-id-fails-on-incomplete-snapshot-frame-test`
+
+This would indicate that the underlying code paths can behave correctly when the test environment is clean.
+
+### 2. Full-namespace execution would produce a different failure
+
+Running the whole namespace would fail in `pull-ok-out-of-order-stale-response-is-ignored-test` instead of the two failures seen in the full suite.
+
+This would indicate order dependence or leaked global state between tests in the same namespace.
+
+### 3. Failure payloads would match leaked state
+
+`ensure-upload-graph-identity-defaults-e2ee-enabled-test` would unexpectedly receive an existing graph identity with:
+
+- `:graph-id "c52bf9d4-3a95-4f17-9c8c-7f86eef5f75d"`
+- `:graph-e2ee? false`
+
+That graph id would match a value used by another test in the same file. This would suggest that the later test is reusing state left behind by an earlier test instead of executing its own intended bootstrap path.
+
+`download-graph-by-id-fails-on-incomplete-snapshot-frame-test` would expect `incomplete-snapshot-frame` but would sometimes receive an unrelated assertion failure:
+
+- `Assert failed: test-db-sync-repo (some? conn)`
+
+This would suggest that another asynchronous code path is still interacting with shared worker state while the test is running.
+
+## Root Cause
+
+The most likely root cause would be incomplete per-test cleanup of shared global state in:
+
+- `frontend.worker.state`
+- `frontend.worker.sync`
+
+The highest-risk shared atoms would include:
+
+- `worker-state/*datascript-conns`
+- `worker-state/*client-ops-conns`
+- `worker-state/*db-sync-client`
+- `worker-state/*db-sync-config`
+- `db-sync/*repo->latest-remote-tx`
+- `db-sync/*start-inflight-target`
+
+The test file would also rely heavily on:
+
+- `async done`
+- nested `promesa` chains
+- cleanup inside `p/finally`
+
+That structure would make it possible for a test to signal completion before all outer cleanup has fully restored shared state, especially when asynchronous callbacks or listeners are still active.
+
+## Proposed Changes
+
+### 1. Add a per-test fixture for global state reset
+
+A `:each` fixture in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs` would reset the shared worker and db-sync atoms before and after every test.
+
+The fixture would reset at least:
+
+- `worker-state/*datascript-conns`
+- `worker-state/*client-ops-conns`
+- `worker-state/*db-sync-client`
+- `worker-state/*db-sync-config`
+- `db-sync/*repo->latest-remote-tx`
+- `db-sync/*start-inflight-target`
+
+### 2. Review high-risk async tests
+
+If fixture-based isolation is not sufficient, the next step would be to tighten async structure in the tests most likely to leak state.
+
+Priority candidates would include:
+
+- upload identity tests
+- snapshot download tests
+- pull/ok ordering tests
+
+The goal would be to ensure that:
+
+- cleanup happens after the actual promise chain settles
+- `done` is called only after cleanup boundaries are satisfied
+- any listener or temporary override is fully restored before the next test starts
+
+## Why Production Code Is Less Likely To Be At Fault
+
+The current evidence would not strongly support a production db-sync bug because:
+
+1. the affected tests would pass when run alone
+2. the failing test would change depending on suite shape
+3. the observed incorrect values would match data seeded by neighboring tests
+4. the expected production code path for incomplete snapshot handling already appears to raise the correct error in isolated execution
+
+Because of that, modifying production sync logic first would risk masking a test harness problem instead of fixing the actual instability.
+
+## Verification Plan
+
+After applying the test isolation changes, verification would include:
+
+1. `bb dev:test -v frontend.worker.db-sync-test`
+2. `bb dev:lint-and-test`
+
+Success criteria would be:
+
+- individual failing tests still pass
+- the full `frontend.worker.db-sync-test` namespace passes reliably
+- the full `bb dev:lint-and-test` command no longer fails on these db-sync tests
+
+## Risks And Follow-ups
+
+If failures remain after the fixture reset, the next investigation would focus on:
+
+- leaked `d/listen!` listeners
+- background tasks still running across tests
+- `js/fetch` restoration timing
+- promise chains whose cleanup is attached at the wrong level
+- other shared atoms not yet covered by the fixture
+
+## Files
+
+Would modify:
+
+- `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_sync_test.cljs`
+
+Would not modify initially:
+
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/client_op.cljs`
diff --git a/docs/agent-guide/055-logseq-cli-login-logout.md b/docs/agent-guide/055-logseq-cli-login-logout.md
new file mode 100644
index 0000000000..978976febe
--- /dev/null
+++ b/docs/agent-guide/055-logseq-cli-login-logout.md
@@ -0,0 +1,317 @@
+# Logseq CLI Login and Logout Implementation Plan
+
+Goal: Add `logseq login` and `logseq logout`, persist Cognito auth in `/Users/rcmerci/logseq/auth.json`, and remove `:auth-token` persistence from `/Users/rcmerci/logseq/cli.edn`.
+
+Architecture: The CLI will get a dedicated auth module that owns loopback OAuth login, token persistence, token refresh, and logout file cleanup.
+Architecture: Sync commands will continue to pass `:auth-token` to db-sync at runtime, but that token will be resolved from `auth.json` instead of being edited through `sync config set|get|unset`.
+Architecture: The flow will reuse existing Cognito constants and token refresh semantics from the frontend user code, while following the ECA browser plus localhost callback pattern for headless login.
+
+Tech Stack: ClojureScript, babashka.cli, Node.js HTTP server APIs, Cognito Hosted UI OAuth, Promesa, JSON file persistence.
+
+Related: Builds on `docs/agent-guide/047-logseq-cli-sync-command.md`, `docs/agent-guide/048-sync-download-start-reliability.md`, `docs/agent-guide/051-logseq-cli-sync-upload-fix.md`, and `docs/agent-guide/033-desktop-db-worker-node-backend.md`.
+
+## Problem statement
+
+The current CLI expects headless sync authentication to be provided as `:auth-token` inside `/Users/rcmerci/logseq/cli.edn`.
+
+That approach is awkward for users, leaks auth concerns into general CLI config, and does not provide a first-class login or logout flow.
+
+The current sync code path in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` still reads `:auth-token` directly from resolved config and writes it through `sync config set|get|unset`.
+
+The db-sync worker then consumes that runtime token through `worker-state/*db-sync-config` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs`.
+
+Logseq user management already uses AWS Cognito in the frontend app, with Cognito constants in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/config.cljs` and refresh-token logic in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/user.cljs`.
+
+The ECA repository shows the closest CLI-friendly reference implementation for this feature, because it opens a browser, listens on localhost for the callback, exchanges the authorization code for tokens, and persists auth state locally.
+
+This plan keeps the existing db-sync runtime contract stable by continuing to inject `:auth-token` into the worker config map, while changing only how the CLI obtains and persists that token.
+
+I will use @planning-documents for naming, @writing-plans for task granularity, @test-driven-development for implementation order, and the current `logseq-cli` plus `db-worker-node` implementation as the baseline architecture.
+
+## Testing Plan
+
+I will add unit tests for auth file path resolution, JSON persistence, token refresh, and auth file deletion before adding implementation behavior.
+
+I will add command parser tests for the new `login` and `logout` commands before wiring them into the CLI.
+
+I will add execution tests for `login` and `logout` that verify browser launch, callback handling, Cognito token exchange, auth file writes, and logout cleanup.
+
+I will add sync command regression tests that fail first and verify `sync config set|get|unset` no longer accept `auth-token`.
+
+I will add config resolution tests that fail first and verify `resolve-config` no longer loads or persists `:auth-token` from `cli.edn`, while a new auth resolver loads the effective token from `auth.json`.
+
+I will add worker-facing tests that fail first and verify CLI sync runtime still injects an `:auth-token` into `worker-state/*db-sync-config` when `auth.json` exists.
+
+I will add integration tests that fail first and cover `login`, `logout`, and one authenticated sync command using a stubbed Cognito token exchange.
+
+I will run targeted tests after each slice, and I will finish with `bb dev:lint-and-test`.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Proposed CLI surface
+
+| Command | Purpose | Persistence effect | Notes |
+|---|---|---|---|
+| `logseq login` | Authenticate the current machine against Logseq cloud. | Creates or updates `/Users/rcmerci/logseq/auth.json`. | Opens browser and completes a localhost callback flow. |
+| `logseq logout` | Remove locally persisted cloud auth for the CLI. | Deletes or clears `/Users/rcmerci/logseq/auth.json`. | Idempotent when the file does not exist. |
+| `logseq sync config set ws-url|http-base|e2ee-password <value>` | Persist non-auth sync config. | Updates `/Users/rcmerci/logseq/cli.edn`. | `auth-token` is removed from this command. |
+| `logseq sync config get ws-url|http-base|e2ee-password` | Read non-auth sync config. | Reads `/Users/rcmerci/logseq/cli.edn`. | `auth-token` is removed from this command. |
+| `logseq sync config unset ws-url|http-base|e2ee-password` | Remove non-auth sync config. | Updates `/Users/rcmerci/logseq/cli.edn`. | `auth-token` is removed from this command. |
+
+The runtime db-sync config map will still contain `:auth-token` when the CLI invokes worker methods.
+
+Only the persistence source changes from `cli.edn` to `auth.json`.
+
+## Auth file design
+
+The new auth file will live at `/Users/rcmerci/logseq/auth.json` by default.
+
+The implementation should expose an internal override path for tests, but it should not add a new public CLI flag unless later required.
+
+The file format should be JSON rather than EDN so it is easy to inspect and delete manually.
+
+The file should contain enough information to refresh expired tokens without asking the user to log in again.
+
+A good starting shape is the following.
+
+```json
+{
+  "provider": "cognito",
+  "id-token": "<jwt>",
+  "access-token": "<jwt>",
+  "refresh-token": "<opaque>",
+  "expires-at": 1735689600000,
+  "sub": "<user-uuid>",
+  "email": "<user-email>",
+  "updated-at": 1735686000000
+}
+```
+
+`id-token` should remain the value injected into db-sync as runtime `:auth-token`, because current CLI and worker behavior already assumes the sync token is the same value as `state/get-auth-id-token` on desktop.
+
+`refresh-token` is required so the CLI can refresh auth non-interactively before sync commands.
+
+`access-token` can be stored for parity with the existing frontend token model, even if the first CLI release does not consume it directly.
+
+The file should be written with restrictive permissions on Unix when feasible, and tests should verify the implementation does not fail on platforms where chmod semantics differ.
+
+## OAuth flow design
+
+The login flow should follow the ECA pattern more than the current browser app pattern.
+
+The CLI should start a temporary localhost callback server, generate a PKCE verifier and challenge, build a Cognito Hosted UI authorization URL, and then open the browser.
+
+The callback should validate `state`, read the authorization `code`, exchange it against Cognito `/oauth2/token`, persist the resulting tokens, and print a concise success result.
+
+A suggested flow is shown below.
+
+```text
+logseq login
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/auth.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/auth.cljs
+  -> start localhost callback server on an ephemeral port
+  -> build Cognito authorize URL with PKCE and redirect_uri http://127.0.0.1:<port>/auth/callback
+  -> open browser with system launcher, or print URL fallback
+  -> receive code on callback server
+  -> POST code exchange to https://<oauth-domain>/oauth2/token
+  -> persist /Users/rcmerci/logseq/auth.json
+  -> future sync commands refresh token if needed and inject runtime :auth-token
+```
+
+The callback server should prefer an ephemeral port rather than a fixed port, because that avoids collisions during local development and test runs.
+
+The login result should include non-sensitive metadata such as email, subject, auth file path, and whether the token was freshly created or refreshed.
+
+The CLI should not print raw tokens in human output.
+
+## Refresh and runtime token resolution
+
+The current worker code does not refresh tokens in CLI-owned node mode.
+
+`frontend.worker.sync/<resolve-ws-token` explicitly skips refresh when `:owner-source` is `:cli`.
+
+That means the new CLI auth module must resolve a fresh usable token before invoking sync commands.
+
+The auth module should expose one helper that loads `auth.json`, checks `id-token` expiry, refreshes via the Cognito refresh-token grant when needed, persists the updated file, and returns the effective runtime `id-token`.
+
+The refresh HTTP request should mirror the existing app logic in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/user.cljs`, which already posts to `https://<oauth-domain>/oauth2/token` using `grant_type=refresh_token` and `client_id`.
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` should stop reading `:auth-token` from resolved config and instead call the new auth helper when building the sync runtime config sent through `:thread-api/set-db-sync-config`.
+
+If no valid auth file exists, authenticated sync commands should return a dedicated error with a hint such as `Run logseq login first.`.
+
+## Implementation plan
+
+### Phase 1. Add failing tests for auth file helpers.
+
+1. Create `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/auth_test.cljs`.
+2. Add a failing test that the default auth path resolves to `/Users/rcmerci/logseq/auth.json`.
+3. Add a failing test that writing auth data creates the parent directory when missing.
+4. Add a failing test that reading a missing auth file returns `nil` instead of throwing.
+5. Add a failing test that deleting auth data is idempotent when the file does not exist.
+6. Add a failing test that expired `id-token` plus valid `refresh-token` triggers refresh and persists updated JSON.
+7. Add a failing test that malformed JSON returns a stable `invalid-auth-file` error code.
+8. Run `bb dev:test -v logseq.cli.auth-test` and confirm only auth helper tests fail.
+
+### Phase 2. Add failing parser and help tests for `login` and `logout`.
+
+9. Update `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` with a failing assertion that top-level help lists `login` and `logout`.
+10. Add a failing assertion that `logseq login --help` and `logseq logout --help` produce command-specific help.
+11. Add a failing assertion that `sync config set|get|unset` help no longer mentions `auth-token`.
+12. Run `bb dev:test -v logseq.cli.commands-test` and confirm the failures reflect missing auth command wiring and old sync config text.
+
+### Phase 3. Add failing command execution tests for auth commands.
+
+13. Create `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/auth_test.cljs`.
+14. Add a failing test that `login` starts a callback server and opens the browser with a Cognito authorize URL.
+15. Add a failing test that `login` validates `state` before exchanging the authorization code.
+16. Add a failing test that a successful code exchange writes `/Users/rcmerci/logseq/auth.json` through the auth persistence helper.
+17. Add a failing test that `logout` removes the auth file and returns success when the file existed.
+18. Add a failing test that `logout` still succeeds when the auth file was already absent.
+19. Add a failing test that `login` returns a timeout error when no browser callback arrives.
+20. Run `bb dev:test -v logseq.cli.command.auth-test` and confirm the tests fail for missing implementation only.
+
+### Phase 4. Implement auth helpers and OAuth plumbing.
+
+21. Add `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/auth.cljs` for auth path resolution, JSON read and write helpers, token expiry checks, refresh logic, and auth file deletion.
+22. Add `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/auth.cljs` for command entries, action builders, and command execution.
+23. Implement PKCE helpers and loopback callback server support inside `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/auth.cljs`, unless the file becomes too large, in which case split transport helpers into `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/auth_oauth.cljs`.
+24. Build the Cognito authorize URL using constants from `/Users/rcmerci/gh-repos/logseq/src/main/frontend/config.cljs` so the CLI and app share the same cloud environment.
+25. Implement the token exchange POST against `https://<oauth-domain>/oauth2/token` and map the response into the `auth.json` shape.
+26. Implement refresh-token exchange using the same Cognito domain and client id.
+27. Add best-effort browser launching for macOS and Linux, and always print the URL so the flow remains usable when auto-open fails.
+28. Run `bb dev:test -v logseq.cli.auth-test` and `bb dev:test -v logseq.cli.command.auth-test` until green.
+
+### Phase 5. Wire `login` and `logout` into the CLI parser and help output.
+
+29. Register `auth-command/entries` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+30. Extend `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` so top-level summaries include `login` and `logout` in a dedicated auth section or the existing management section.
+31. Extend action building and execute dispatch in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` to route `:login` and `:logout`.
+32. Re-run `bb dev:test -v logseq.cli.commands-test` until the new parser and help output tests pass.
+
+### Phase 6. Remove `:auth-token` persistence from `cli.edn`.
+
+33. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/config_test.cljs` that `resolve-config` no longer returns `:auth-token` from file config.
+34. Add a failing test that `update-config!` strips `:auth-token` from updates instead of persisting it.
+35. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/config.cljs` so file-backed config excludes `:auth-token` while still preserving `ws-url`, `http-base`, `e2ee-password`, graph selection, and output settings.
+36. Update any config-related tests that currently expect `:auth-token` round-tripping through `cli.edn`.
+37. Run `bb dev:test -v logseq.cli.config-test` until green.
+
+### Phase 7. Update sync commands to resolve auth from `auth.json`.
+
+38. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs` that `sync config set|get|unset auth-token` is rejected as an unknown key.
+39. Add a failing test that sync execution uses the auth helper to resolve a runtime `:auth-token` before invoking `:thread-api/set-db-sync-config`.
+40. Add a failing test that missing auth file returns a `missing-auth` style error for authenticated sync operations such as `sync remote-graphs`.
+41. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` so `config-key-map` removes `auth-token`.
+42. Update sync execution to call the auth helper and merge the effective runtime token into the in-memory sync config map.
+43. Update human-readable hints that currently say `Set sync config keys (ws-url/http-base/auth-token)` so they instead mention login plus the remaining sync config keys.
+44. Run `bb dev:test -v logseq.cli.command.sync-test` until green.
+
+### Phase 8. Keep worker behavior stable while clarifying CLI ownership of auth.
+
+45. Add a failing regression test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/sync/crypt_test.cljs` that CLI node mode still prefers the runtime `:auth-token` provided by sync config over renderer state.
+46. Decide whether an additional worker test is needed to prove no worker-side changes are required beyond existing runtime behavior.
+47. Make only the smallest worker change necessary, and prefer no production worker changes if CLI runtime injection remains sufficient.
+48. Run `bb dev:test -v frontend.worker.sync.crypt-test` and any related worker namespace tests.
+
+### Phase 9. Update output formatting and docs.
+
+49. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for human output of `login` and `logout`.
+50. Remove or rewrite any format tests that currently mention `sync config get auth-token` redaction.
+51. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` so auth command output reports file path, email, and status without printing tokens.
+52. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to document `login`, `logout`, `auth.json`, and the reduced `sync config` key set.
+53. Add one short troubleshooting section telling users to delete `/Users/rcmerci/logseq/auth.json` or run `logseq logout` when local auth becomes invalid.
+54. Run `bb dev:test -v logseq.cli.format-test` after formatter updates.
+
+### Phase 10. Add integration coverage and perform final verification.
+
+55. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that simulates a successful `login` callback and verifies `auth.json` contents.
+56. Add a failing integration test that `logout` removes the auth file.
+57. Add a failing integration test that an authenticated sync command reads `auth.json`, refreshes if needed, and sends runtime `:auth-token` to the worker.
+58. Stub browser opening and Cognito HTTP responses so the integration tests remain deterministic and offline.
+59. Run `bb dev:test -v logseq.cli.integration-test` until the new coverage is green.
+60. Run `bb dev:lint-and-test` from `/Users/rcmerci/gh-repos/logseq` and confirm exit code `0`.
+
+## File map
+
+| Area | Files to update or add | Reason |
+|---|---|---|
+| Auth persistence and OAuth flow | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/auth.cljs`, optionally `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/auth_oauth.cljs` | Own `auth.json`, login callback server, PKCE, refresh, and logout deletion. |
+| CLI command wiring | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`, `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs`, `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/auth.cljs` | Expose `login` and `logout` and update help text. |
+| Sync runtime auth | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` | Replace file-backed `:auth-token` lookup with auth helper resolution. |
+| Config cleanup | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/config.cljs` | Stop round-tripping `:auth-token` in `cli.edn`. |
+| Cloud constants reuse | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/config.cljs`, `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/user.cljs` | Reference existing Cognito endpoints and refresh semantics. |
+| Tests | `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/auth_test.cljs`, `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/auth_test.cljs`, `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/config_test.cljs`, `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/sync_test.cljs`, `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`, `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`, `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`, and possibly `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/sync/crypt_test.cljs` | Cover behavior before implementation. |
+| User-facing docs | `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | Explain the new auth workflow and removal of `auth-token` from sync config commands. |
+
+## Edge cases and failure handling
+
+`logseq login` must fail cleanly when the localhost callback port cannot be opened.
+
+`logseq login` must reject callbacks with mismatched `state` or missing `code`.
+
+`logseq login` must surface Cognito code-exchange failures without writing a partial auth file.
+
+`logseq logout` must succeed even when `/Users/rcmerci/logseq/auth.json` is already missing.
+
+Malformed or partially written `auth.json` must produce a deterministic error code and an actionable hint rather than a generic JSON parse exception.
+
+Expired `id-token` with a valid `refresh-token` should auto-refresh before sync commands instead of forcing an immediate re-login.
+
+Expired `id-token` with an invalid or missing `refresh-token` should fail with a hint to run `logseq login`.
+
+`sync start`, `sync remote-graphs`, `sync upload`, `sync download`, `sync ensure-keys`, and `sync grant-access` should all use the same auth resolution path so behavior is consistent.
+
+The CLI must not print raw JWTs or refresh tokens in human output, logs, or test snapshots.
+
+The implementation should preserve the current worker contract by continuing to pass `:auth-token` in runtime sync config, because changing the worker key name would expand scope without user benefit.
+
+## Verification commands
+
+| Command | Expected outcome |
+|---|---|
+| `bb dev:test -v logseq.cli.auth-test` | Auth helper tests pass. |
+| `bb dev:test -v logseq.cli.command.auth-test` | Login and logout command tests pass. |
+| `bb dev:test -v logseq.cli.commands-test` | Help output includes `login` and `logout`, and sync config no longer mentions `auth-token`. |
+| `bb dev:test -v logseq.cli.config-test` | `cli.edn` no longer persists `:auth-token`. |
+| `bb dev:test -v logseq.cli.command.sync-test` | Sync command tests pass with auth resolved from `auth.json`. |
+| `bb dev:test -v logseq.cli.integration-test` | End-to-end auth flow tests pass with stubs. |
+| `bb dev:lint-and-test` | Full repo lint and test suite passes with exit code `0`. |
+| `node ./dist/logseq.js login` | Opens browser or prints login URL, then writes `/Users/rcmerci/logseq/auth.json` after callback. |
+| `node ./dist/logseq.js logout` | Removes local auth state and reports success. |
+| `node ./dist/logseq.js sync remote-graphs --output json` | Reads auth from `auth.json` and returns remote graphs without requiring `sync config set auth-token`. |
+
+## Testing Details
+
+The tests focus on externally observable behavior, including CLI help text, browser launch requests, callback validation, auth file contents, refresh-on-expiry behavior, sync runtime payloads, and user-facing error hints.
+
+The tests should not assert private helper structure unless that structure is itself the behavior contract, such as the persisted JSON keys or the generated Cognito callback URL.
+
+## Implementation Details
+
+- Keep `auth-token` as an in-memory db-sync runtime key, but remove it from persistent `cli.edn` config and from `sync config` command parsing.
+- Add a dedicated CLI auth module instead of scattering login and refresh logic across `sync.cljs` and `config.cljs`.
+- Reuse Cognito constants from `frontend.config` so the CLI always targets the same environment as the app.
+- Reuse the refresh grant semantics from `frontend.handler.user.cljs` instead of inventing a second refresh protocol.
+- Prefer an ephemeral localhost callback port and PKCE-based authorization code flow.
+- Always print a copyable login URL even when automatic browser opening succeeds.
+- Make `logout` local and idempotent first, and treat remote Cognito session invalidation as optional future scope.
+- Keep the worker contract stable and prefer solving expiration entirely in the CLI auth module.
+- Add an internal test-only auth path override rather than a new public CLI flag.
+- Update user-facing docs and error hints so `Run logseq login first.` becomes the primary recovery path.
+
+## Decision
+
+The implementation will use a loopback redirect URI such as `http://127.0.0.1:<port>/auth/callback`.
+
+If the current Cognito app client does not yet allow that redirect URI pattern, updating the Cognito app-client configuration is part of the implementation prerequisite rather than a reason to change the CLI design.
+
+`logout` will only clear `/Users/rcmerci/logseq/auth.json` in the first release.
+
+Best-effort browser sign-out against the Cognito Hosted UI logout endpoint is explicitly out of scope for this iteration.
+
+`auth.json` will persist `id-token`, `access-token`, and `refresh-token`, plus non-sensitive metadata such as `expires-at`, `sub`, `email`, and `updated-at`.
+
+This keeps the first CLI implementation aligned with the existing frontend token model while still using `id-token` as the runtime `:auth-token` injected into db-sync.
+
+---
diff --git a/docs/agent-guide/056-graph-name-dir-encoding-alignment.md b/docs/agent-guide/056-graph-name-dir-encoding-alignment.md
new file mode 100644
index 0000000000..b31aac8254
--- /dev/null
+++ b/docs/agent-guide/056-graph-name-dir-encoding-alignment.md
@@ -0,0 +1,377 @@
+# Align graph dir encoding between logseq-cli and desktop app
+
+## Summary
+
+Align `logseq-cli`, `db-worker-node`, and desktop app handling of `graph dir` / `graph-name` so special characters are encoded and decoded with one shared, reversible contract.
+
+The authoritative contract would be the existing `encode-graph-dir-name` / `decode-graph-dir-name` pair in `src/main/frontend/worker_common/util.cljc`, which is already used by `db-worker-node` and `logseq-cli` server-side graph directory resolution.
+
+This plan keeps user-facing graph names unchanged and only aligns their on-disk directory representation.
+
+## Background
+
+Current code paths do not agree on how a graph name maps to a graph directory on disk:
+
+- `db-worker-node` and `logseq-cli` server/runtime paths use a reversible graph-dir encoding.
+- desktop app contains paths that join the raw graph name directly into a filesystem path.
+- some Electron and CLI-adjacent helpers still use lossy `sanitize-db-name` behavior.
+- shared graph discovery still contains legacy decoding logic for older naming conventions, but not the current reversible encoding.
+
+This mismatch becomes visible when graph names contain special characters such as `/`, `:`, `%`, `~`, or spaces.
+
+## Goals
+
+- Use one shared graph-dir encoding/decoding contract across CLI and desktop app.
+- Preserve current user-facing graph-name semantics.
+- Keep `logseq_db_` prefix canonicalization separate from graph-dir encoding.
+- Define compatibility behavior for legacy graph directory names.
+- Add tests that cover special-character graph names across all affected entry points.
+
+## Non-goals
+
+- Redesign the user-visible graph naming model.
+- Change the existing `logseq_db_` display normalization rules.
+- Remove all legacy compatibility in one step without an explicit migration strategy.
+
+## Current behavior
+
+### Shared reversible encoding already exists
+
+Authoritative implementation today:
+
+- `src/main/frontend/worker_common/util.cljc`
+  - `encode-graph-dir-name`
+  - `decode-graph-dir-name`
+
+Current behavior:
+
+1. `encodeURIComponent` is applied.
+2. literal `~` is rewritten to `%7E`.
+3. `%` is rewritten to `~`.
+4. decoding reverses `~ -> %` and then applies `decodeURIComponent`.
+
+This gives a reversible filesystem-safe directory key without `/` or `\\` path separators.
+
+### db-worker-node follows the shared contract
+
+Relevant files:
+
+- `src/main/frontend/worker/db_worker_node_lock.cljs`
+- `src/main/frontend/worker/platform/node.cljs`
+- `src/main/frontend/worker/db_worker_node.cljs`
+- `src/main/frontend/worker/graph_dir.cljs`
+
+Current behavior:
+
+- repo identity strips one leading `logseq_db_` to produce a graph-dir key.
+- graph-dir key is encoded with `encode-graph-dir-name`.
+- list-graphs decodes on-disk directory names back to graph-dir keys.
+- worker log paths and lock paths are stored under the encoded graph directory.
+
+### CLI is partially aligned
+
+Relevant files:
+
+- `src/main/logseq/cli/server.cljs`
+- `src/main/logseq/cli/command/core.cljs`
+- `src/main/logseq/cli/command/graph.cljs`
+- `src/main/logseq/cli/common.cljs`
+- `deps/cli/src/logseq/cli/common/graph.cljs`
+- `deps/cli/src/logseq/cli/util.cljs`
+
+Current behavior:
+
+- `cli.server` already uses the same canonical graph-dir path contract as `db-worker-node`.
+- graph display/input normalization strips or restores one `logseq_db_` prefix as needed.
+- `unlink-graph!` still derives directory names with `sanitize-db-name`, which is lossy.
+- shared discovery in `deps/cli` still decodes only older directory naming patterns such as `++` and `+3A+`.
+
+### Desktop app is not aligned
+
+Relevant files:
+
+- `src/electron/electron/utils.cljs`
+- `src/electron/electron/db.cljs`
+- `src/electron/electron/handler.cljs`
+- `src/electron/electron/url.cljs`
+- `src/main/frontend/config.cljs`
+
+Current behavior:
+
+- `electron.utils/get-graph-dir` joins the raw graph name into the graph path after db-prefix stripping.
+- if the graph name contains `/`, the resulting path becomes nested directories.
+- `electron.db` still uses `sanitize-db-name` in some db path creation logic.
+- frontend local-dir helpers also treat graph name as a raw path segment.
+
+## Problem statement
+
+The same logical graph name can map to different on-disk paths depending on which subsystem touches it:
+
+- reversible encoded path in `db-worker-node`
+- raw path join in Electron/frontend
+- lossy underscore replacement in sanitize-based helpers
+- legacy decode-only behavior in shared graph discovery
+
+As a result:
+
+- a graph may be listable but not removable
+- a graph may be resolvable in CLI but not in desktop app
+- a graph name containing `/` may accidentally create path nesting in one flow but not another
+- existing tests do not enforce cross-subsystem parity
+
+## Proposed contract
+
+### 1. Separate graph identity from graph directory representation
+
+The plan would explicitly distinguish:
+
+- **graph-name / repo**: user-facing identifier, subject to existing `logseq_db_` canonicalization rules
+- **graph-dir key**: graph-name with exactly one leading db prefix stripped
+- **encoded graph-dir**: on-disk directory name produced only by `encode-graph-dir-name`
+
+This separation would make it clear that special-character handling belongs to the graph-dir layer, not the user-facing name layer.
+
+### 2. Make the db-worker-node contract authoritative
+
+The repository would standardize on:
+
+- `repo -> graph-dir key`: strip one leading `logseq_db_`
+- `graph-dir key -> encoded graph-dir`: `encode-graph-dir-name`
+- `encoded graph-dir -> graph-dir key`: `decode-graph-dir-name`
+
+Any code path that needs an on-disk db graph directory would route through this contract rather than reimplementing path logic.
+
+### 3. Keep user-visible graph names unchanged
+
+The plan would preserve current user-visible behavior:
+
+- CLI graph names remain prefix-free for display and config storage where already intended.
+- desktop app continues to display logical graph names, not encoded directory names.
+- URL-level graph identification continues to resolve to logical graph names, not on-disk encoded names.
+
+## Proposed code changes
+
+### A. Consolidate path-authoritative helpers
+
+Add or reuse one shared helper layer for:
+
+- converting repo to graph-dir key
+- converting graph-dir key to encoded graph directory
+- converting repo directly to on-disk graph directory path
+
+Target files likely involved:
+
+- `src/main/frontend/worker/graph_dir.cljs`
+- `src/main/frontend/worker/db_worker_node_lock.cljs`
+- `src/electron/electron/utils.cljs`
+- `src/main/frontend/config.cljs`
+- `deps/cli/src/logseq/cli/util.cljs`
+
+Expected outcome:
+
+- no raw path join for logical graph names in path-authoritative code
+- no duplicate graph-dir encoding implementations
+
+### B. Align Electron graph-dir resolution
+
+Replace raw graph path derivation in Electron with the shared encoded graph-dir contract.
+
+Target files:
+
+- `src/electron/electron/utils.cljs`
+- `src/electron/electron/handler.cljs`
+- `src/electron/electron/db.cljs`
+
+Expected outcome:
+
+- desktop app resolves the same on-disk graph dir as `db-worker-node`
+- graph names containing `/`, `:`, `%`, `~`, or spaces behave predictably
+- `sanitize-db-name` is no longer used for authoritative db graph-dir mapping
+
+### C. Align CLI remove/unlink behavior
+
+Update CLI removal/unlink flows to resolve graph directories via the same encoded contract used by list/start/lock behavior.
+
+Target file:
+
+- `src/main/logseq/cli/common.cljs`
+
+Expected outcome:
+
+- a graph that can be listed or switched to can also be removed through the same path mapping
+
+### D. Align shared graph discovery
+
+Update shared discovery helpers so current encoded graph dirs are decoded correctly, while preserving deliberate support for legacy names where needed.
+
+Target file:
+
+- `deps/cli/src/logseq/cli/common/graph.cljs`
+
+Expected outcome:
+
+- desktop/CLI discovery would recognize encoded graph dirs produced by current db-worker-node logic
+- legacy decode branches would be explicitly documented as compatibility behavior
+
+### E. Audit frontend local-dir helpers
+
+Review helpers that expose graph-related directories to ensure they are either:
+
+- display-only helpers, or
+- path-authoritative helpers using the shared encoded contract
+
+Target file:
+
+- `src/main/frontend/config.cljs`
+
+Expected outcome:
+
+- no ambiguous helper remains that appears safe for filesystem use while still using raw graph names
+
+## Compatibility and migration
+
+This plan should explicitly decide how to handle already-existing graph directories created by older logic.
+
+### Option 1: Read legacy names, write canonical encoded names
+
+Behavior:
+
+- discovery accepts legacy directory names and current encoded names
+- all newly created or rewritten paths use the canonical encoded form
+- optional one-time migration may rename legacy directories
+
+Pros:
+
+- safer rollout
+- less risk of immediately losing access to existing graphs
+
+Cons:
+
+- mixed formats may coexist temporarily
+
+### Option 2: Auto-migrate on access
+
+Behavior:
+
+- when a legacy graph directory is detected, code renames it to the canonical encoded path before continuing
+
+Pros:
+
+- converges quickly to one format
+
+Cons:
+
+- higher operational risk
+- rename behavior must be designed carefully for active workers and lock files
+
+### Option 3: Strict cutover
+
+Behavior:
+
+- only encoded graph dirs are supported after the change
+
+Pros:
+
+- simplest long-term contract
+
+Cons:
+
+- too risky without explicit migration tooling
+
+### Recommended direction
+
+Prefer **Option 1** for the first rollout:
+
+- read compatibility for legacy directory names
+- canonical writes to encoded graph dirs
+- add explicit migration follow-up only after parity tests pass
+
+## Test plan
+
+### Unit tests
+
+Extend or add tests for:
+
+- `src/test/frontend/worker/worker_common_util_test.cljs`
+- `src/test/frontend/worker/db_worker_node_lock_test.cljs`
+- `src/test/logseq/cli/server_test.cljs`
+- `src/test/logseq/cli/common/graph_test.cljs`
+- Electron-specific tests if available for graph-dir resolution
+
+### Special-character test matrix
+
+All subsystems should use the same examples:
+
+- `foo/bar`
+- `a:b`
+- `space name`
+- `100% legit`
+- `til~de`
+- `mix/of:many %chars~here`
+
+### Behavior to verify
+
+1. encode/decode roundtrip is lossless
+2. CLI list-graphs returns the same logical graph name that was encoded on disk
+3. CLI switch/remove resolve the same graph directory
+4. desktop app resolves the same graph directory as CLI/db-worker-node
+5. graph names remain user-visible without encoded substitutions
+6. legacy discovery behavior remains intentional and documented
+
+### Missing coverage today
+
+The repository currently appears to lack end-to-end parity tests for:
+
+- CLI create/switch/remove with special-character graph names
+- Electron graph-name -> graph-dir resolution with special characters
+- desktop and CLI agreement on one on-disk graph directory for the same logical graph
+
+## Rollout sequence
+
+1. Make the shared graph-dir contract explicit in code and docs.
+2. Update Electron path-authoritative helpers to use encoded graph dirs.
+3. Update CLI unlink/remove behavior to use the same mapping.
+4. Update shared graph discovery for encoded graph dirs and legacy compatibility.
+5. Add parity tests across worker, CLI, and desktop-related helpers.
+6. Evaluate whether legacy directory migration should be a separate follow-up.
+
+## Risks
+
+- Existing graphs may already exist under lossy or raw directory naming rules.
+- Desktop-specific compatibility code may rely on current path layout assumptions.
+- URL/deeplink flows may resolve graph identifiers separately from filesystem mapping and should not accidentally expose encoded names to users.
+- Removing `sanitize-db-name` from authoritative paths may surface hidden assumptions in older db bootstrap code.
+
+## Open questions
+
+1. Should legacy raw/sanitized graph directories remain writable, or only readable?
+2. Should migration happen automatically, manually, or in a later dedicated change?
+3. Which helper should become the single exported entry point for graph-name -> on-disk graph-dir path resolution?
+4. Should `docs/cli/logseq-cli.md` be updated in the same change to clarify that on-disk graph directories are encoded, not always literal graph names?
+
+## Expected files to change in implementation
+
+Likely implementation targets:
+
+- `src/main/frontend/worker_common/util.cljc`
+- `src/main/frontend/worker/graph_dir.cljs`
+- `src/main/frontend/worker/db_worker_node_lock.cljs`
+- `src/main/logseq/cli/server.cljs`
+- `src/main/logseq/cli/common.cljs`
+- `deps/cli/src/logseq/cli/common/graph.cljs`
+- `deps/cli/src/logseq/cli/util.cljs`
+- `src/electron/electron/utils.cljs`
+- `src/electron/electron/db.cljs`
+- `src/electron/electron/handler.cljs`
+- `src/main/frontend/config.cljs`
+- related tests under `src/test/`
+
+## Acceptance criteria
+
+This plan would be complete when:
+
+- one shared graph-dir encoding contract is identified as authoritative
+- all affected subsystems and files are enumerated
+- compatibility strategy for legacy graph directories is documented
+- a concrete test matrix for special-character graph names is defined
+- the plan preserves current user-facing graph-name semantics while aligning on-disk graph-dir behavior
diff --git a/docs/agent-guide/057-cli-sync-download-realtime-progress.md b/docs/agent-guide/057-cli-sync-download-realtime-progress.md
new file mode 100644
index 0000000000..83ad162da3
--- /dev/null
+++ b/docs/agent-guide/057-cli-sync-download-realtime-progress.md
@@ -0,0 +1,436 @@
+# 057: Make `logseq-cli sync download` stream realtime progress and support long-running downloads
+
+## Summary
+
+This document defines an execution-ready implementation plan for improving `logseq-cli sync download` for large graphs.
+
+Today, the CLI waits for a single `/v1/invoke` response and uses a short default timeout. This creates two bad outcomes for large graph downloads:
+
+1. the terminal is silent while the snapshot is downloading and importing, and
+2. healthy long-running work may appear to fail because the CLI request timeout is too short.
+
+The implementation should reuse the existing sync log/event infrastructure already used by the app, instead of creating a separate CLI-only progress system.
+
+## Decision records (confirmed)
+
+The following decisions are fixed for implementation:
+
+1. `sync download` timeout strategy uses a command-level long-running policy (not a global timeout increase).
+2. Progress logs are printed to `stdout`.
+3. Add `--progress` option for `sync download`.
+4. `--progress` defaults to `true` for human output.
+5. For structured output modes (for example `json` / `edn`), progress is automatically disabled unless the user explicitly passes `--progress true`.
+6. Download progress log emission should be unified into shared worker/sync code (no duplicate app-only emission path for the same milestones).
+
+## Problem statement
+
+`logseq-cli sync download` already uses the same db-worker-node and worker sync stack that powers app sync behavior, but it does not currently reuse the realtime event stream.
+
+Relevant current-state facts:
+
+- CLI sends a request to db-worker-node over `/v1/invoke` and waits for one final response.
+- db-worker-node already exposes `/v1/events` as an SSE event stream.
+- worker/app sync logic already emits `:rtc-log` events.
+- app/desktop already displays those logs.
+- CLI transport defaults to a `10000` ms timeout, which is not appropriate for a full graph snapshot download/import.
+
+The implementation goal is therefore not to invent progress tracking from scratch. The goal is to make CLI consume and display the same progress events, and to change timeout behavior so long-running downloads can complete.
+
+## Goals
+
+- Show realtime progress during `logseq-cli sync download`.
+- Reuse the existing `:rtc-log` event model and db-worker-node SSE stream.
+- Unify download progress log emission into shared worker/sync code for the full download flow.
+- Add `--progress` to `sync download` with default behavior enabled for human output.
+- Print progress to `stdout`.
+- Automatically disable progress for structured output modes unless `--progress true` is explicitly set.
+- Prevent large graph downloads from failing under the generic short CLI timeout path.
+- Preserve the final command result semantics and existing validation behavior.
+
+## Non-goals
+
+- Redesign the sync protocol.
+- Replace the app RTC log UI.
+- Introduce a polling-based progress API.
+- Change the existing success/failure meaning of `sync download`.
+- Add a CLI-only event schema that diverges from app behavior.
+
+## Current implementation map
+
+### CLI entrypoints
+
+- `src/main/logseq/cli/command/sync.cljs`
+  - defines `sync download`
+  - resolves auth, starts db-worker-node, validates empty DB, invokes `:thread-api/db-sync-download-graph-by-id`
+- `src/main/logseq/cli/transport.cljs`
+  - sends HTTP requests to db-worker-node `/v1/invoke`
+  - currently applies default timeout behavior
+- `src/main/logseq/cli/format.cljs`
+  - formats final CLI output
+- `src/main/logseq/cli/config.cljs`
+  - defines CLI defaults, including timeout
+- `src/main/logseq/cli/command/core.cljs`
+  - defines global CLI options including `--timeout-ms`
+
+### db-worker-node / worker entrypoints
+
+- `src/main/frontend/worker/db_worker_node.cljs`
+  - serves `/v1/invoke`
+  - serves `/v1/events` as SSE
+- `src/main/frontend/worker/db_core.cljs`
+  - handles `:thread-api/db-sync-download-graph-by-id`
+  - already emits import/decrypt/save-stage logs
+- `src/main/frontend/worker/sync.cljs`
+  - performs remote snapshot download and sync data fetch
+- `src/main/frontend/worker/sync/log_and_state.cljs`
+  - publishes `:rtc-log` events to connected clients
+
+### App-side log consumers and app-specific log emission
+
+- `src/main/frontend/handler/db_based/sync.cljs`
+  - currently emits useful early download messages such as:
+    - `Preparing graph snapshot download`
+    - `Start downloading graph snapshot, file size: ...`
+    - `Graph snapshot downloaded`
+- `src/main/frontend/handler/worker.cljs`
+- `src/main/frontend/handler/events.cljs`
+- `src/main/frontend/handler/db_based/rtc_flows.cljs`
+- `src/main/frontend/components/rtc/indicator.cljs`
+
+These app-side files are useful references because they show the desired end-user progress semantics. However, the actual shared event source should live in worker/shared sync code, not in app-only UI handlers.
+
+## Design constraints
+
+1. **One shared progress model**
+   - CLI and app should consume the same logical progress events.
+   - Avoid a separate CLI-only progress protocol.
+
+2. **Invoke result remains authoritative**
+   - Realtime logs improve visibility but must not replace final command success/failure semantics.
+
+3. **Long-running timeout behavior must be command-aware**
+   - `sync download` should not rely on the same timeout assumptions as short metadata requests.
+
+4. **Output compatibility matters**
+   - Streaming progress should not break final human or machine-readable command results.
+
+## Proposed implementation
+
+The implementation should be delivered in four phases.
+
+---
+
+## Phase 1: Make timeout handling explicit for long-running `sync download`
+
+### Objective
+
+Remove the dependency on the generic short CLI request timeout for the long-running download/import invoke path.
+
+### Files
+
+- `src/main/logseq/cli/command/sync.cljs`
+- `src/main/logseq/cli/transport.cljs`
+- `src/main/logseq/cli/config.cljs`
+- `src/main/logseq/cli/command/core.cljs`
+
+### Tasks
+
+1. Trace exactly how `:timeout-ms` flows from CLI options/config into `transport/invoke` for `sync download`.
+2. Introduce command-specific timeout behavior for `sync download`.
+3. Keep the timeout policy explicit in code, rather than relying on an accidental global default.
+4. Preserve existing timeout behavior for short non-download CLI commands unless intentionally changed.
+
+### Recommended implementation direction
+
+Prefer a command-specific long-task timeout path over raising the global default for all CLI traffic.
+
+Good options include:
+
+- passing a much larger timeout only for the final `db-sync-download-graph-by-id` invoke, or
+- introducing a dedicated long-running request helper for commands that are expected to take a long time.
+
+Do **not** solve this by silently changing all CLI requests to use a large default timeout.
+
+### Acceptance criteria
+
+- `sync download` no longer depends on the generic `10000` ms timeout for the full download/import request.
+- Other CLI requests keep their current short-request behavior unless explicitly updated.
+- The effective timeout policy is easy to understand from the command implementation.
+
+### Verification
+
+- Unit test or integration test proving that `sync download` can run longer than the old short timeout path.
+- Regression test showing short requests are unchanged.
+
+---
+
+## Phase 2: Unify all download-progress logs into shared worker/sync code
+
+### Objective
+
+Ensure the full download flow emits shared progress events from the same worker/sync path used by both app and CLI.
+
+### Files
+
+- `src/main/frontend/worker/sync.cljs`
+- `src/main/frontend/worker/db_core.cljs`
+- `src/main/frontend/worker/sync/log_and_state.cljs`
+- `src/main/frontend/handler/db_based/sync.cljs`
+
+### Tasks
+
+1. Inventory all download-progress log emissions related to `sync download` across app handlers and worker code.
+2. Move or extract all shared milestones into worker/shared sync code where the remote snapshot and import/decrypt flow actually executes.
+3. Reuse the existing `:rtc.log/download` event family and existing `sub-type` semantics wherever possible.
+4. Remove duplicate app-only emission for shared milestones, and keep app handlers as consumers of shared events.
+5. Keep milestone wording stable enough to avoid unnecessary UI regression in existing app consumers.
+
+### Required shared milestones
+
+The worker/shared path should emit at least these human-meaningful milestones:
+
+- preparing snapshot download,
+- snapshot download started, including file size when available,
+- snapshot download completed,
+- saving/import/decrypt progress,
+- graph ready / download complete.
+
+The final wording may differ, but the milestones must cover both:
+
+- network download progress stages, and
+- local import/decrypt stages.
+
+### Acceptance criteria
+
+- Shared download milestones are emitted from worker/sync code across the full flow (download + import/decrypt).
+- There is no competing app-only emission path for the same shared milestones.
+- CLI-triggered `db-sync-download-graph-by-id` produces the same family of download progress events as app-triggered flows.
+- Existing app consumers can still display download progress using the shared event source.
+
+### Verification
+
+- Worker-level or sync-level tests for emitted `:rtc-log` events.
+- Manual verification in app that download progress still appears after the refactor.
+
+---
+
+## Phase 3: Add CLI support for db-worker-node SSE event consumption
+
+### Objective
+
+Allow the CLI to subscribe to `/v1/events` while a long-running invoke is in progress.
+
+### Files
+
+- `src/main/logseq/cli/transport.cljs`
+- `src/main/logseq/cli/command/sync.cljs`
+- optionally a new helper namespace under `src/main/logseq/cli/` if event-stream logic should be isolated
+- reference implementation:
+  - `src/main/frontend/persist_db/remote.cljs`
+  - `src/main/frontend/persist_db/node.cljs`
+
+### Tasks
+
+1. Add a lightweight CLI-side SSE client for db-worker-node `/v1/events`.
+2. Decode incoming event payloads into the same shape consumed elsewhere in the codebase.
+3. Support subscription lifecycle management:
+   - connect before starting the long-running invoke,
+   - receive events during the invoke,
+   - close cleanly on success, error, timeout, or interruption.
+4. Keep the event client generic enough that future CLI commands could reuse it if needed.
+
+### Important behavior
+
+- The SSE stream is for observability, not command truth.
+- If SSE disconnects, the invoke result still determines command success/failure.
+- If the invoke finishes successfully, the CLI must stop listening and finalize normally.
+
+### Acceptance criteria
+
+- CLI can consume db-worker-node `/v1/events` while a command is in flight.
+- Incoming `:rtc-log` events are decoded correctly.
+- Subscription cleanup is reliable across success and failure paths.
+
+### Verification
+
+- Tests for event decode behavior.
+- Tests or integration coverage for stream setup/cleanup.
+- Manual verification against a running db-worker-node.
+
+---
+
+## Phase 4: Render download progress in `sync download` without breaking final output
+
+### Objective
+
+Display realtime download/import progress in the terminal while preserving final result compatibility.
+
+### Files
+
+- `src/main/logseq/cli/command/sync.cljs`
+- `src/main/logseq/cli/format.cljs`
+- any new CLI event/render helper added in Phase 3
+- `docs/cli/logseq-cli.md`
+
+### Tasks
+
+1. Add `--progress` option to `sync download` command handling.
+2. Define default behavior: progress enabled for human-oriented output mode.
+3. Define structured-output behavior: progress automatically disabled for structured modes unless explicitly overridden by `--progress true`.
+4. Subscribe to the worker event stream before invoking `db-sync-download-graph-by-id` when progress is enabled.
+5. Filter only the relevant download log events for the active graph.
+6. Render progress messages in chronological order to `stdout`.
+7. Preserve the final success/failure output contract.
+8. Document the new behavior in CLI docs, including mode-dependent defaults and override rules.
+
+### Output policy
+
+The implementation must make a clear separation between:
+
+- streaming progress lines, and
+- the final command result.
+
+Confirmed direction:
+
+- stream progress to `stdout` when progress is enabled,
+- add `--progress` option for `sync download`,
+- default `--progress` to `true` for human-oriented output,
+- automatically disable progress for structured output modes unless the user explicitly passes `--progress true`,
+- keep the final result formatter responsible for terminal success/failure summary semantics.
+
+### Filtering policy
+
+The command should filter progress events using enough context to avoid printing unrelated logs.
+
+At minimum, filtering should consider the active graph identity. If a more precise operation-level filter is available without major complexity, prefer it.
+
+### Acceptance criteria
+
+- Running `logseq-cli sync download` with human-oriented output prints realtime progress lines to `stdout` during download/import.
+- `--progress false` suppresses progress streaming.
+- Structured output modes auto-disable progress unless `--progress true` is explicitly provided.
+- Final command output still reflects the authoritative invoke result.
+- Structured output parsing is not broken under the default mode-dependent progress behavior.
+
+### Verification
+
+- Integration test or high-confidence manual test showing visible staged output.
+- Verification that final success output still matches expected formatter behavior.
+- Verification that failure cases still return the correct final error.
+
+---
+
+## Concrete execution order
+
+Implement in this order:
+
+1. **Phase 1 first** so large downloads no longer die under the short timeout path.
+2. **Phase 2 second** so the CLI has a complete shared event source to consume.
+3. **Phase 3 third** to add CLI event subscription infrastructure.
+4. **Phase 4 last** to wire the streaming logs into `sync download` and finalize output behavior.
+
+Do not start Phase 4 before Phase 2 is complete, or the CLI will only show partial progress from the existing worker import stage.
+
+## Testing plan
+
+### Unit / focused tests
+
+Add or update tests in the most appropriate existing test namespaces for:
+
+- CLI timeout behavior for `sync download`
+- event decoding / event subscription lifecycle
+- worker/shared sync download log emission
+- filtering and rendering of relevant `:rtc-log` events
+
+Likely test locations:
+
+- `src/test/logseq/cli/command/sync_test.cljs`
+- `src/test/logseq/cli/integration_test.cljs`
+- `src/test/frontend/worker/db_worker_node_test.cljs`
+- `src/test/frontend/worker/db_sync_test.cljs`
+- `src/test/frontend/handler/db_based/sync_test.cljs`
+
+The exact namespace choices may differ depending on existing test structure, but the coverage categories above are required.
+
+### Manual verification checklist
+
+1. Start a `sync download` against a graph large enough to produce visible staged progress.
+2. Confirm the terminal shows early snapshot-download messages.
+3. Confirm the terminal shows import/decrypt/save progress.
+4. Confirm progress lines are emitted to `stdout` in human-oriented mode.
+5. Confirm `--progress false` suppresses streaming progress output.
+6. Confirm structured output mode auto-disables progress by default.
+7. Confirm structured output mode prints progress only when explicitly using `--progress true`.
+8. Confirm successful completion still depends on the invoke result.
+9. Confirm a slow download no longer fails under the old short timeout path.
+10. Confirm existing app download progress still works after shared-log refactoring.
+11. Confirm non-empty DB validation and other preflight failures remain unchanged.
+
+## Risks and open questions
+
+### Risk 1: app and CLI may need slightly different rendering
+
+The event source should be shared, but rendering may differ by client.
+
+Mitigation:
+
+- share event emission, not presentation details.
+- keep worker messages human-readable enough for both app and CLI.
+
+### Risk 2: progress events may not uniquely identify one operation
+
+If multiple operations or graphs are active, CLI could print unrelated logs.
+
+Mitigation:
+
+- filter by graph identity at minimum,
+- add more precise filtering only if needed and justified by actual ambiguity.
+
+### Risk 3: output-mode compatibility
+
+Streaming logs can interfere with structured output modes.
+
+Mitigation:
+
+- enforce mode-dependent default behavior (`progress` auto-off for structured output unless explicitly enabled),
+- verify human and machine-readable modes explicitly.
+
+### Resolved decision: timeout strategy
+
+`sync download` uses command-level long-running timeout handling instead of a global timeout increase.
+
+### Open question 1
+
+Should the CLI event-stream helper remain local to `sync download`, or be introduced as a reusable CLI transport helper?
+
+Recommendation:
+
+- prefer a small reusable helper if the abstraction stays simple.
+
+## Out-of-scope follow-ups
+
+The following can be considered later and are **not required** for this plan:
+
+- byte-level progress bars,
+- richer TUI formatting,
+- resumable download semantics,
+- generalized event streaming for all CLI commands.
+
+## Definition of done
+
+This work is complete when all of the following are true:
+
+- `logseq-cli sync download` displays realtime progress while a large graph is downloading/importing.
+- The progress messages come from the shared worker/app event model, not a CLI-only ad hoc implementation.
+- Download-progress milestones are unified in shared worker/sync code across the full flow.
+- `sync download` supports `--progress`, with mode-dependent default behavior as documented.
+- In structured output modes, progress is auto-disabled unless explicitly enabled.
+- Large downloads are no longer constrained by the old generic short timeout path.
+- Final command success/failure semantics remain intact.
+- Relevant automated tests and CLI docs are updated.
+
+## Recommendation
+
+Execute this as a shared-event refactor plus a command-specific long-request timeout change.
+
+The key architecture decision is to make worker/shared sync code the source of truth for download progress, then let the CLI subscribe to db-worker-node events just like the app already does. This maximizes reuse, keeps progress semantics aligned across clients, and solves the two real UX issues together: silent long-running work and premature short-timeout failures.
\ No newline at end of file
diff --git a/docs/agent-guide/058-db-worker-node-revision-and-cli-server-list.md b/docs/agent-guide/058-db-worker-node-revision-and-cli-server-list.md
new file mode 100644
index 0000000000..1ab5ad6f47
--- /dev/null
+++ b/docs/agent-guide/058-db-worker-node-revision-and-cli-server-list.md
@@ -0,0 +1,226 @@
+# 058 — db-worker-node revision and CLI server list compatibility
+
+## Summary
+
+This plan proposes three related improvements to align `db-worker-node` runtime metadata with `logseq-cli` versioning:
+
+1. Add `--version` support to `db-worker-node`.
+2. Persist `revision` in `db-worker.lock`.
+3. Extend `logseq-cli server list` with a `REVISION` column and a compatibility warning when server revision differs from local CLI revision.
+
+The goal is to make version drift observable and debuggable in multi-process and multi-version environments.
+
+---
+
+## Product decisions (locked)
+
+1. **Mismatch rule**: if revision/commit strings are not exactly equal, it is a mismatch.
+   - No normalization.
+   - No short-hash expansion.
+   - No suffix stripping.
+
+2. **Warning scope**: mismatch warning is shown **only in human output**.
+   - JSON output must not include human warning text.
+
+---
+
+## Background
+
+Current behavior:
+
+- `logseq-cli --version` already prints build metadata including `Revision`.
+- `db-worker-node` accepts operational flags (`--repo`, `--data-dir`, etc.) but does not expose `--version`.
+- `db-worker.lock` does not include revision metadata.
+- `logseq-cli server list` shows process/state fields (`GRAPH`, `STATUS`, `HOST`, `PORT`, `PID`, `OWNER`) but not revision.
+
+As a result, users cannot quickly determine whether a running DB worker matches the CLI binary currently used to manage it.
+
+---
+
+## Goals
+
+- Expose `db-worker-node` revision consistently with CLI version semantics.
+- Persist server revision in lock metadata for later discovery.
+- Surface revision in `server list` output.
+- Warn users when a listed server revision does not match local CLI revision (human output only).
+
+## Non-goals
+
+- No protocol change for worker RPC endpoints.
+- No forced auto-restart or auto-migration for mismatched servers.
+- No hard failure on mismatch (warning only).
+
+---
+
+## Design
+
+### 1) Add `--version` to db-worker-node
+
+#### Behavior
+
+- `db-worker-node --version` prints version metadata and exits with code `0`.
+- It must not require `--repo`.
+- Output must include at least `Revision: <value>`.
+- Formatting should follow `logseq-cli --version` style for consistency.
+
+#### Implementation shape
+
+- Extend argument parsing in `db_worker_node.cljs` to recognize `--version`.
+- Add an early return branch in `main` before repo validation.
+- Introduce a worker-side version namespace using `goog-define` values injected at build time.
+
+### 2) Add `revision` to lock file
+
+#### Behavior
+
+- Lock creation writes `:revision`.
+- Lock update preserves existing revision and remains backward compatible with old lock files.
+- Reading old lock files without revision continues to work.
+
+#### Implementation shape
+
+- Add revision retrieval at lock write point.
+- Extend `create-lock!` payload in `db_worker_node_lock.cljs`.
+- Adjust `update-lock!` merge/preserve behavior.
+
+### 3) Show revision in `server list` and warn on mismatch
+
+#### Behavior
+
+- Add `REVISION` column to human table output.
+- `--format json` includes per-server `revision` field.
+- Mismatch warning text appears only in human output.
+- Missing revision should render as `-` and should not crash formatting.
+
+#### Mismatch rule (exact string)
+
+Given:
+
+- local CLI revision = `cli-rev`
+- server lock revision = `server-rev`
+
+Then:
+
+- mismatch if `cli-rev != server-rev` (exact string compare)
+- no normalization at either side
+
+#### Implementation shape
+
+- Extend server discovery result in `logseq.cli.server/list-servers` to include `:revision`.
+- Compute mismatch server set in command/data path (`server list` execute path), then pass structured mismatch info to formatter.
+- Render warning block only in human formatter path.
+
+---
+
+## Build metadata strategy
+
+Use the same metadata source philosophy as `logseq-cli`:
+
+- Revision source priority:
+  1. `LOGSEQ_REVISION` env
+  2. git describe output
+  3. fallback `"dev"`
+
+- Build-time source priority:
+  1. `LOGSEQ_BUILD_TIME` env
+  2. current UTC timestamp
+
+For `db-worker-node`, inject closure defines through its shadow build target, analogous to existing CLI metadata injection.
+
+---
+
+## Implementation plan (task list)
+
+1. Add worker version namespace and shadow metadata wiring.
+2. Add `--version` parse + main dispatch branch in `db_worker_node.cljs`.
+3. Add `:revision` field in `db-worker.lock` create/update path.
+4. Extend `server list` data model with revision.
+5. Extend table formatter with `REVISION` column.
+6. Add mismatch detection (exact string compare) and pass structured mismatch data.
+7. Render mismatch warning in human output only.
+8. Add/update tests for all paths.
+9. Update CLI documentation.
+
+---
+
+## Testing plan
+
+### Unit tests
+
+- `db_worker_node_test.cljs`
+  - Add case: `--version` recognized and exits early without repo.
+  - Validate output includes `Revision`.
+
+- `db_worker_node_lock_test.cljs`
+  - Create lock includes `:revision`.
+  - Update lock preserves existing revision.
+  - Legacy lock without revision remains supported.
+
+- `format_test.cljs`
+  - Human `server list` table includes `REVISION` column.
+  - Missing revision renders `-`.
+  - Mismatch warning block appears in human output for exact-string mismatch.
+  - No warning block when revisions are equal.
+
+- `server_test.cljs` (or equivalent)
+  - Discovery output includes revision extracted from lock.
+  - Mismatch set computed with exact string comparison.
+
+- JSON output tests
+  - `server list --format json` contains per-server `revision`.
+  - JSON output does not contain human warning text.
+
+### Regression checks
+
+- Existing `logseq-cli --version` tests remain green.
+- Existing server list owner/status formatting remains unchanged aside from the added `REVISION` column and optional warning block in human mode.
+
+---
+
+## Rollout and compatibility
+
+- Backward compatible with existing lock files.
+- New clients can read old locks (revision absent).
+- Old clients can ignore new lock key (`revision`) if parser is permissive map decode.
+
+---
+
+## Risks and mitigations
+
+- **Risk:** db-worker build target missing metadata hook.
+  - **Mitigation:** add explicit hook wiring and test fallback value (`dev`) in test target.
+
+- **Risk:** warning noise in mixed environments.
+  - **Mitigation:** warning remains informational and human-only.
+
+- **Risk:** flaky tests due to dynamic metadata.
+  - **Mitigation:** use deterministic test defines in shadow test config.
+
+---
+
+## Acceptance criteria
+
+- `db-worker-node --version` prints revision and exits `0` without requiring repo args.
+- `db-worker.lock` written by worker includes `revision`.
+- `logseq-cli server list` (human) shows `REVISION` column.
+- `logseq-cli server list` (human) prints mismatch warning when local CLI revision string is not exactly equal to server revision string.
+- `logseq-cli server list --format json` includes server revision data and does not include human warning text.
+- Added/updated tests cover happy path and backward-compatibility path.
+
+---
+
+## File scope (expected)
+
+- `src/dev-cljs/shadow/hooks.clj`
+- `shadow-cljs.edn`
+- `src/main/frontend/worker/db_worker_node.cljs`
+- `src/main/frontend/worker/db_worker_node_lock.cljs`
+- `src/main/frontend/worker/version.cljs` (new)
+- `src/main/logseq/cli/server.cljs`
+- `src/main/logseq/cli/command/server.cljs`
+- `src/main/logseq/cli/format.cljs`
+- `src/test/frontend/worker/db_worker_node_test.cljs`
+- `src/test/frontend/worker/db_worker_node_lock_test.cljs`
+- `src/test/logseq/cli/format_test.cljs`
+- `src/test/logseq/cli/server_test.cljs`
+- `docs/cli/logseq-cli.md`
diff --git a/docs/agent-guide/059-cli-doctor-server-revision-mismatch-warning.md b/docs/agent-guide/059-cli-doctor-server-revision-mismatch-warning.md
new file mode 100644
index 0000000000..3afa5cf0c9
--- /dev/null
+++ b/docs/agent-guide/059-cli-doctor-server-revision-mismatch-warning.md
@@ -0,0 +1,237 @@
+# 059 — Add doctor warning for server and CLI revision mismatch
+
+## Summary
+
+This plan adds a new `doctor` warning when a discovered db-worker server revision does not match the local `logseq-cli` revision.
+
+The warning must be actionable: for each mismatched server, `doctor` should tell the user to run:
+
+- `logseq server restart --graph <name>`
+
+This closes the current observability gap where `server list` already exposes revision mismatch, but `doctor` does not.
+
+---
+
+## Product decisions (locked)
+
+1. **Mismatch rule is exact string compare**.
+   - `cli-revision != server-revision` means mismatch.
+   - No normalization, no hash shortening, no suffix stripping.
+
+2. **Severity is warning, not error**.
+   - Revision drift is diagnosable and recoverable.
+   - `doctor` should still return `:status :ok` at top-level transport with `:data {:status :warning ...}` behavior, consistent with existing warning checks.
+
+3. **`doctor` remains fail-fast for hard preconditions**.
+   - If script check fails, stop immediately (current behavior).
+   - If data-dir check fails, stop immediately (current behavior).
+   - Revision mismatch check runs only when server checks are reached.
+
+4. **Restart guidance is per affected graph/server**.
+   - The warning includes one restart command per mismatched graph.
+   - Command form is `logseq server restart --graph <name>`.
+
+5. **Structured output must remain machine-friendly**.
+   - JSON/EDN outputs include structured mismatch check data.
+   - Human output includes readable warning text and restart guidance.
+
+---
+
+## Background
+
+Current implementation already has the needed revision primitives:
+
+- CLI revision source: `logseq.cli.version/revision`.
+- Server revision source: `db-worker.lock` revision surfaced by `logseq.cli.server/list-servers`.
+- `server list` already computes and warns on mismatch in human output.
+
+Current `doctor` checks:
+
+1. `db-worker-script`
+2. `data-dir`
+3. `running-servers` readiness
+
+`doctor` does **not** currently compare server revision against CLI revision.
+
+---
+
+## Goals
+
+- Add revision mismatch detection to `doctor` using existing revision sources.
+- Provide actionable restart guidance for each mismatched graph.
+- Keep mismatch semantics identical to existing `server list` behavior.
+- Preserve existing `doctor` fail-fast behavior for script/data-dir errors.
+
+## Non-goals
+
+- No automatic server restart.
+- No change to daemon ownership/permission rules.
+- No new db-worker RPC endpoint for version info.
+- No hard failure on mismatch.
+
+---
+
+## User-facing behavior
+
+### Human output
+
+When mismatches exist, `doctor` includes a warning check (example shape):
+
+- `[warning] server-revision-mismatch - 2 servers use a different revision than this CLI`
+- Followed by actionable per-graph commands, e.g.:
+  - `Run: logseq server restart --graph graph-a`
+  - `Run: logseq server restart --graph graph-b`
+
+If graph names include spaces, command examples should quote names in guidance output.
+
+### JSON and EDN output
+
+`doctor --output json|edn` keeps structured check payload, including mismatch details.
+
+Suggested check payload shape:
+
+- `:id :server-revision-mismatch`
+- `:status :warning | :ok`
+- `:code :doctor-server-revision-mismatch` (when warning)
+- `:cli-revision <string>`
+- `:servers [{:repo <repo> :revision <server-revision> :graph <graph-name>}]`
+- `:message <human summary>`
+
+---
+
+## Design
+
+### 1) Reuse one mismatch computation path
+
+Today, mismatch computation is a private helper in `logseq.cli.command.server`.
+
+Plan:
+
+- Move or extract mismatch computation into a shared helper (recommended in `logseq.cli.server`), so both `server list` and `doctor` use exactly the same comparison logic.
+- Keep return shape stable enough to support both command paths.
+
+This prevents semantic drift between `server list` and `doctor`.
+
+### 2) Add a dedicated doctor check
+
+Add a new check in `logseq.cli.command.doctor`:
+
+- `check-server-revision-mismatch`
+
+Input:
+
+- local CLI revision (`logseq.cli.version/revision`)
+- discovered servers from `list-servers`
+
+Behavior:
+
+- No mismatches -> check status `:ok`
+- Any mismatch -> check status `:warning`, include mismatch metadata and restart guidance
+
+### 3) Execution flow in doctor
+
+Keep current order and fail-fast semantics for hard errors:
+
+1. `check-db-worker-script` (error stops execution)
+2. `check-data-dir` (error stops execution)
+3. `check-running-servers`
+4. `check-server-revision-mismatch` (new)
+
+Final `doctor` status is:
+
+- `:ok` when all checks are `:ok`
+- `:warning` when any warning check exists (`running-servers` and/or `server-revision-mismatch`)
+- `:error` only for hard failures as today
+
+### 4) Restart guidance formatting strategy
+
+Two viable options:
+
+- **Option A (minimal formatter change):** put guidance directly into mismatch check `:message`.
+- **Option B (cleaner long-term):** add a small `format-doctor` branch for `:server-revision-mismatch` to render command lines from structured fields.
+
+Recommended: **Option B** if it stays small, because it preserves clean machine payload while improving human readability and escaping/quoting behavior.
+
+### 5) Graph naming for restart commands
+
+Restart command uses `--graph`, not repo id.
+
+Plan:
+
+- Derive graph name via existing repo/graph conversion helper before rendering command guidance.
+- Ensure guidance is aligned with user-facing graph names shown in CLI output.
+
+---
+
+## Implementation plan (task list)
+
+1. Extract revision mismatch helper from `command/server.cljs` into shared location.
+2. Update `server list` command to call the shared helper (behavior unchanged).
+3. Add `check-server-revision-mismatch` to `command/doctor.cljs`.
+4. Extend `execute-doctor` to append the new check and compute combined warning status.
+5. Add per-graph restart guidance to human doctor output.
+6. Keep JSON/EDN payload structured and stable.
+7. Update CLI docs for `doctor` warning behavior and remediation command.
+
+---
+
+## Testing plan
+
+### Unit tests
+
+- `src/test/logseq/cli/command/doctor_test.cljs`
+  - Adds warning check when one or more servers have mismatched revisions.
+  - Includes restart command guidance for each mismatched graph.
+  - Treats missing server revision as mismatch (exact compare behavior).
+  - Keeps existing fail-fast behavior for script/data-dir errors.
+
+- `src/test/logseq/cli/command/server_test.cljs`
+  - Verifies `server list` still uses exact-string mismatch semantics after helper extraction.
+  - Confirms human mismatch metadata remains attached when expected.
+
+- `src/test/logseq/cli/format_test.cljs`
+  - Human `doctor` output includes mismatch warning and restart guidance.
+  - JSON/EDN doctor outputs include structured mismatch fields.
+
+### Regression checks
+
+- Existing `running-servers` warning behavior is preserved.
+- Existing `server list` mismatch warning behavior is preserved.
+- `doctor` top-level status semantics remain unchanged (`ok|warning|error` through current response model).
+
+---
+
+## Risks and mitigations
+
+- **Risk:** Duplicate warning noise (`running-servers` + mismatch) in one doctor run.
+  - **Mitigation:** Keep distinct check IDs/messages so users can tell readiness vs revision drift.
+
+- **Risk:** Restart command may fail with owner restrictions.
+  - **Mitigation:** Keep guidance explicit but non-blocking; existing error hint `server-owned-by-other` remains the fallback behavior.
+
+- **Risk:** Missing revision in legacy lock files increases warning count.
+  - **Mitigation:** Treat as mismatch by design; message should clearly indicate missing server revision value.
+
+---
+
+## Acceptance criteria
+
+- `logseq doctor` emits a warning check when any discovered server revision differs from local CLI revision.
+- Warning includes actionable restart guidance: `logseq server restart --graph <name>` for each mismatched graph.
+- No mismatch warning when all discovered server revisions exactly equal CLI revision.
+- `server list` mismatch behavior remains consistent with `doctor` (shared comparison semantics).
+- `doctor --output json|edn` includes structured mismatch check data.
+
+---
+
+## File scope (expected)
+
+- `src/main/logseq/cli/command/doctor.cljs`
+- `src/main/logseq/cli/command/server.cljs`
+- `src/main/logseq/cli/server.cljs`
+- `src/main/logseq/cli/format.cljs` (if dedicated doctor warning rendering is added)
+- `src/test/logseq/cli/command/doctor_test.cljs`
+- `src/test/logseq/cli/command/server_test.cljs`
+- `src/test/logseq/cli/format_test.cljs`
+- `docs/cli/logseq-cli.md`
+- `docs/agent-guide/059-cli-doctor-server-revision-mismatch-warning.md`
diff --git a/docs/agent-guide/060-cli-graph-list-legacy-graph-dir-rename-command.md b/docs/agent-guide/060-cli-graph-list-legacy-graph-dir-rename-command.md
new file mode 100644
index 0000000000..35f753f8b9
--- /dev/null
+++ b/docs/agent-guide/060-cli-graph-list-legacy-graph-dir-rename-command.md
@@ -0,0 +1,197 @@
+# 060 — CLI graph list: mark legacy graph-dir and provide rename command
+
+## Summary
+
+`logseq-cli graph list` currently filters out graph directories that cannot be decoded by the current canonical graph-dir encoding. This behavior makes legacy graph directories invisible to users.
+
+This plan proposes to:
+
+1. Detect non-canonical (legacy) graph directories during graph listing.
+2. Mark them as `legacy` in `graph list` output.
+3. Show a warning when legacy entries exist.
+4. Print a suggested shell rename command from legacy dir name to current canonical encoded dir name (only when graph-name can be derived reliably).
+
+## Product decisions (locked)
+
+1. Scope is `graph list` only.
+2. Human output must show:
+   - regular graph items (existing behavior),
+   - legacy marker per legacy item,
+   - a warning section when at least one legacy graph is found,
+   - one rename command suggestion per legacy graph when derivation is reliable.
+3. Structured outputs (`json` / `edn`) must include legacy metadata (not human-only text).
+4. Suggested command target is POSIX shell (`mv`) with safe quoting.
+5. If target encoded dir already exists, output should include conflict guidance instead of a blind rename suggestion.
+6. If a legacy dir cannot be decoded to a reliable graph-name, show `legacy` marker and warning only; do not output a rename command.
+
+## Goals
+
+- Make legacy graph dirs visible in `logseq-cli graph list`.
+- Provide actionable migration guidance with minimal user effort.
+- Keep current canonical graph listing behavior unchanged for non-legacy entries.
+
+## Non-goals
+
+- Automatic rename/migration execution.
+- Reworking graph storage layout.
+- Adding new CLI subcommands in this iteration.
+
+## Current behavior (based on code)
+
+- `src/main/logseq/cli/server.cljs` `list-graphs` scans graph data dirs and decodes names via canonical decode.
+- Entries that fail canonical decode are dropped.
+- `src/main/logseq/cli/command/graph.cljs` `execute-graph-list` passes graph names to formatter.
+- `src/main/logseq/cli/format.cljs` `format-graph-list` renders graph names but has no legacy path.
+
+Related encoding utilities:
+
+- Canonical encode/decode logic:
+  - `deps/common/src/logseq/common/graph_dir.cljs`
+  - `src/main/frontend/worker/db_worker_node_lock.cljs`
+- Legacy token hints still exist in browser-side logic (`+3A+`, `++`) and can be used to define migration decoding behavior.
+
+## Design
+
+### 1) Data model for graph list results
+
+Introduce a richer graph-list item shape from CLI server layer:
+
+- Canonical item:
+  - `{:kind :canonical :graph-name <decoded-graph-name> :graph-dir <encoded-dir-name>}`
+- Legacy item:
+  - `{:kind :legacy :legacy-dir <raw-dir-name> :legacy-graph-name <decoded-or-derived-name> :target-graph-dir <canonical-encoded-dir-name> :conflict? <bool>}`
+- Undecodable non-canonical item:
+  - `{:kind :legacy-undecodable :legacy-dir <raw-dir-name> :reason <keyword-or-string>}`
+
+Notes:
+
+- `legacy-graph-name` should be derived using a dedicated legacy decode path (fallbacks allowed).
+- `target-graph-dir` should always be computed from `legacy-graph-name` through current canonical encoding.
+- `:legacy-undecodable` entries must never produce rename commands.
+
+### 2) Legacy detection and derivation
+
+At graph discovery stage (`src/main/logseq/cli/server.cljs`):
+
+1. Keep current canonical decode attempt.
+2. If canonical decode succeeds -> canonical item.
+3. If canonical decode fails -> try legacy derivation:
+   - legacy token replacement decode path (e.g. `+3A+ -> :`, `++ -> /`) as compatibility rule,
+   - URI decode fallback if applicable.
+4. If derivation yields a reliable name, classify as `:legacy`.
+5. If no reliable derivation is possible, classify as `:legacy-undecodable` and include warning-only entry (no rename command).
+
+### 3) Command layer contract
+
+In `src/main/logseq/cli/command/graph.cljs`:
+
+- `execute-graph-list` should return:
+  - `:data` containing canonical + legacy + undecodable legacy metadata,
+  - `:human` warning payload when any legacy entries exist.
+
+This keeps formatter logic deterministic while preserving structured output for `json` and `edn`.
+
+### 4) Human formatter behavior
+
+In `src/main/logseq/cli/format.cljs`:
+
+- Extend graph list rendering to show legacy marker, for example:
+  - `- my/old/graph [legacy]`
+  - `- unknown-legacy-dir [legacy]`
+- Add warning block when legacy entries are present.
+- For each renameable legacy item, print a shell suggestion:
+  - `mv '<data-dir>/<legacy-dir>' '<data-dir>/<target-graph-dir>'`
+- For conflict entries (`target already exists`), print explicit conflict note and no direct `mv` command.
+- For undecodable legacy entries, print explicit warning and no `mv` command.
+
+### 5) Shell quoting
+
+Current CLI arg quoting helper is not sufficient for robust shell copy/paste.
+
+Plan:
+
+- Add a dedicated POSIX single-quote escaping helper for rendered shell suggestions.
+- Use it only in human formatting layer.
+
+## Output examples (human)
+
+Example list section:
+
+- `my/new/graph`
+- `my/old/graph [legacy]`
+- `strange-dir-name [legacy]`
+
+Warning section example:
+
+- `Warning: 2 legacy graph directories detected.`
+- `Rename suggestion:`
+- `mv '/path/to/data/my++old++graph' '/path/to/data/my~2Fold~2Fgraph'`
+- `Warning: cannot derive graph name for legacy dir 'strange-dir-name'; rename command is not available.`
+
+Conflict example:
+
+- `Warning: target directory already exists for legacy graph 'my/old/graph'.`
+- `Please rename manually after resolving the conflict.`
+
+## Test plan
+
+### Unit tests
+
+1. `src/test/logseq/cli/commands_test.cljs`
+   - verify `graph list` command data includes legacy and undecodable legacy entries.
+2. `src/test/logseq/cli/format_test.cljs`
+   - verify human output marker `[legacy]`.
+   - verify warning block appears only when legacy exists.
+   - verify rename command rendering and shell quoting.
+   - verify undecodable legacy outputs warning only and no rename command.
+3. `src/test/frontend/worker/graph_dir_test.cljs`
+   - extend coverage for canonical encode/decode + legacy derivation helper behavior.
+
+### Integration tests
+
+1. `src/test/logseq/cli/integration_test.cljs`
+   - seed canonical + legacy dirs in test data dir.
+   - assert `graph list` behavior for human/json/edn outputs.
+   - assert conflict message when target encoded dir already exists.
+   - assert undecodable legacy case emits warning without rename command.
+
+## Edge cases
+
+- Legacy dir cannot be decoded to a graph name.
+- Canonical target dir already exists.
+- Graph names containing shell-sensitive characters.
+- Mixed directories that are not graph dirs (must avoid false positives).
+
+## Implementation plan
+
+1. Add legacy classification utilities and detailed graph list payload in CLI server layer.
+2. Adapt `graph list` command contract to pass structured legacy information to formatter and machine outputs.
+3. Extend human formatter with legacy marker, warning block, and safe rename suggestions.
+4. Add/adjust tests for unit + integration coverage.
+5. Validate no regression for all existing `graph list` output formats.
+
+## Acceptance criteria
+
+- `graph list` shows legacy entries instead of silently hiding them.
+- Human output includes explicit legacy marker and warning.
+- Human output includes safe rename command for renameable entries.
+- Undecodable legacy entries are clearly reported with warning only (no rename command).
+- Conflict scenarios are surfaced without unsafe rename suggestions.
+- JSON/EDN outputs expose legacy metadata for automation.
+- Existing canonical-only behavior remains stable when no legacy entries exist.
+
+## Affected files (planned)
+
+Would modify:
+
+- `src/main/logseq/cli/server.cljs`
+- `src/main/logseq/cli/command/graph.cljs`
+- `src/main/logseq/cli/format.cljs`
+- `src/test/logseq/cli/commands_test.cljs`
+- `src/test/logseq/cli/format_test.cljs`
+- `src/test/logseq/cli/integration_test.cljs`
+- `src/test/frontend/worker/graph_dir_test.cljs`
+
+Would create:
+
+- `docs/agent-guide/060-cli-graph-list-legacy-graph-dir-rename-command.md`
diff --git a/docs/agent-guide/061-graph-dir-space-preserve-canonical.md b/docs/agent-guide/061-graph-dir-space-preserve-canonical.md
new file mode 100644
index 0000000000..ed774cd0bc
--- /dev/null
+++ b/docs/agent-guide/061-graph-dir-space-preserve-canonical.md
@@ -0,0 +1,202 @@
+# 061 — Preserve spaces in canonical graph directory names
+
+## Summary
+
+Change canonical graph directory encoding so spaces are preserved as literal spaces.
+
+- Before: graph-name `GRAPH one` -> graph dir `GRAPH~20one`
+- After: graph-name `GRAPH one` -> graph dir `GRAPH one`
+
+All other special-character encode/decode behavior remains unchanged.
+
+This plan is based on the current `logseq-cli` and `db-worker-node` implementation, both of which already rely on shared graph-dir encoding utilities.
+
+## Product decision (locked)
+
+1. Canonical graph dir must preserve spaces (no `~20` for spaces).
+2. Existing encoding/decoding rules for non-space special characters remain unchanged.
+3. Existing directories using old space encodings (for example `~20` or `%20`) are treated as legacy-compatible inputs, not the canonical write format.
+4. New writes/path derivations must use the new canonical format with literal spaces.
+
+## Goals
+
+- Align `logseq-cli` and `db-worker-node` on a canonical graph-dir format that keeps spaces as spaces.
+- Keep current behavior for all non-space special characters.
+- Preserve compatibility for existing legacy directory names during discovery/listing.
+- Keep user-facing graph-name semantics unchanged.
+
+## Non-goals
+
+- Redesign graph naming.
+- Change `logseq_db_` prefix handling rules.
+- Introduce automatic on-disk migration in this iteration.
+- Change unrelated path or lock semantics.
+
+## Current behavior (relevant paths)
+
+### Shared encoding contract
+
+Authoritative helpers:
+
+- `deps/common/src/logseq/common/graph_dir.cljs`
+  - `encode-graph-dir-name`
+  - `decode-graph-dir-name`
+  - `decode-legacy-graph-dir-name`
+  - `repo->graph-dir-key`
+  - `graph-dir-key->encoded-dir-name`
+
+Current behavior for space:
+
+1. `encodeURIComponent("GRAPH one")` -> `GRAPH%20one`
+2. `%` is rewritten to `~`
+3. output becomes `GRAPH~20one`
+
+### CLI usage
+
+- `src/main/logseq/cli/server.cljs`
+  - canonical/legacy classification for graph dirs (`classify-graph-dir`, `canonical-dir-name?`)
+- `src/main/logseq/cli/command/graph.cljs`
+  - `graph list` payload construction
+- `src/main/logseq/cli/format.cljs`
+  - legacy warning/rename suggestion rendering
+
+### db-worker-node usage
+
+- `src/main/frontend/worker/db_worker_node_lock.cljs`
+  - `repo-dir`, `lock-path`, `repo->graph-dir-key`
+- `src/main/frontend/worker/platform/node.cljs`
+  - list/db path installation flows that resolve graph dir via shared helpers
+- `src/main/frontend/worker/db_core.cljs`
+  - storage pool naming path uses graph-dir key/encoded dir conventions
+
+## Proposed behavior
+
+### Canonical encode/decode contract
+
+For graph-dir encoding:
+
+- Preserve literal spaces in output.
+- Keep current reversible encode/decode behavior for all other special characters.
+- Keep `~`/`%` safety rules unchanged.
+
+Examples:
+
+- `GRAPH one` -> `GRAPH one` (changed)
+- `a/b` -> `a~2Fb` (unchanged)
+- `x:y` -> `x~3Ay` (unchanged)
+- `100% real` -> `100~25 real` (unchanged except space stays literal)
+
+Decoding expectations:
+
+- `GRAPH one` -> `GRAPH one`
+- `GRAPH~20one` -> `GRAPH one` (legacy-compatible decode still works)
+
+### Canonical vs legacy classification in CLI
+
+`graph list` canonical check should reflect the new canonical encoding:
+
+- Directory `GRAPH one` is canonical.
+- Directory `GRAPH~20one` is non-canonical (legacy) and should be surfaced as legacy with rename guidance targeting `GRAPH one`.
+- Existing `%20` legacy directories remain legacy.
+
+## Design details
+
+### 1) Shared encoder update
+
+Update `encode-graph-dir-name` in `deps/common/src/logseq/common/graph_dir.cljs` so space is not rewritten into `~20`.
+
+Implementation constraint:
+
+- Do not alter non-space transformation behavior.
+- Keep encode/decode reversibility for previously supported special characters.
+
+### 2) Keep decode compatibility
+
+`decode-graph-dir-name` remains compatibility-friendly so both old and new directory spellings decode to the same graph-name.
+
+No behavioral contraction should be introduced in decoding.
+
+### 3) CLI classification and guidance alignment
+
+Because canonical encoding changes, `src/main/logseq/cli/server.cljs` classification will naturally reclassify old `~20` dirs as legacy.
+
+Ensure `target-graph-dir` generation and formatter output use the new canonical output containing spaces.
+
+### 4) db-worker-node path outputs
+
+No separate encoding logic should be added.
+
+All db-worker-node path generation must continue to route through shared helpers so new canonical behavior applies consistently to:
+
+- graph repo dir
+- lock path
+- db path
+- log path
+
+## Test plan
+
+### Update existing tests
+
+1. `src/test/frontend/worker/worker_common_util_test.cljs`
+   - Update roundtrip expectations for space-containing names to canonical literal-space output.
+2. `src/test/logseq/cli/common/graph_test.cljs`
+   - Update graph-dir decode/list expectations from `space~20name` canonical assumptions to literal-space canonical behavior.
+3. `src/test/logseq/cli/server_test.cljs`
+   - Update canonical vs legacy expectations:
+     - space directory canonical
+     - `~20`/`%20` variants legacy where applicable
+4. `src/test/logseq/cli/integration_test.cljs`
+   - Update integration assertions for `graph list` legacy markers and rename targets.
+5. `src/test/logseq/db/common_sqlite_test.cljs`
+   - Update encoded-dir path assertions for graphs with spaces.
+6. `src/test/logseq/cli/common_test.cljs`
+   - Update unlink/move expectations when graph names contain spaces.
+7. `src/test/logseq/cli/format_test.cljs`
+   - Ensure rename suggestion target renders literal-space canonical dir.
+
+### Add targeted coverage (if missing)
+
+- Roundtrip examples that mix spaces with other special characters (for example `A B/C:D%~E`) to prove only space behavior changed.
+- Explicit assertion that non-space character transformations are unchanged.
+
+## Rollout and compatibility
+
+- No immediate forced migration.
+- Legacy directories remain discoverable/readable via existing decode + CLI legacy classification.
+- New writes and canonical suggestions converge toward literal-space directories.
+
+## Risks
+
+1. Hidden assumptions in tests that treat `~20` as canonical for spaces.
+2. Any code path bypassing shared graph-dir helpers could diverge (must be checked during implementation).
+3. Rename suggestion shell formatting with spaces must remain safely quoted.
+
+## Acceptance criteria
+
+1. For graph-name `GRAPH one`, canonical graph dir is exactly `GRAPH one`.
+2. Non-space special-character encoding behavior is unchanged from current behavior.
+3. CLI graph listing marks old space-encoded dirs (`~20`/`%20`) as legacy where relevant.
+4. db-worker-node path derivation uses the new canonical space-preserving output via shared helpers.
+5. Updated tests pass and demonstrate:
+   - new canonical space behavior,
+   - unchanged non-space behavior,
+   - legacy compatibility visibility.
+
+## Affected files (planned)
+
+Would modify:
+
+- `deps/common/src/logseq/common/graph_dir.cljs`
+- `src/main/logseq/cli/server.cljs` (if classification adjustments are required)
+- `src/main/logseq/cli/format.cljs` (if rename guidance formatting expectations need updates)
+- `src/test/frontend/worker/worker_common_util_test.cljs`
+- `src/test/logseq/cli/common/graph_test.cljs`
+- `src/test/logseq/cli/server_test.cljs`
+- `src/test/logseq/cli/integration_test.cljs`
+- `src/test/logseq/db/common_sqlite_test.cljs`
+- `src/test/logseq/cli/common_test.cljs`
+- `src/test/logseq/cli/format_test.cljs`
+
+Would create:
+
+- `docs/agent-guide/061-graph-dir-space-preserve-canonical.md`
diff --git a/docs/agent-guide/062-cli-list-default-sort-updated-at.md b/docs/agent-guide/062-cli-list-default-sort-updated-at.md
new file mode 100644
index 0000000000..279190c799
--- /dev/null
+++ b/docs/agent-guide/062-cli-list-default-sort-updated-at.md
@@ -0,0 +1,164 @@
+# Logseq CLI List Default Updated-at Sort Implementation Plan
+
+Goal: Make `list page`, `list tag`, and `list property` behave as if `--sort updated-at` is provided when users do not pass `--sort`.
+
+Architecture: Keep the change in the CLI command layer so the existing db-worker-node API surface remains stable.
+Architecture: Reuse current CLI-side sorting flow in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs` where sorting already runs before offset and limit.
+Architecture: Keep db-worker-node list providers in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/mcp/tools.cljs` unchanged for this scope, and document that decision explicitly.
+
+Tech Stack: ClojureScript, babashka.cli option specs, Promesa, Datascript-backed db-worker-node thread-api, existing CLI integration test harness.
+
+Related: Builds on `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/004-logseq-cli-verb-subcommands.md` and `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/043-logseq-cli-tag-property-management.md`.
+
+## Problem statement
+
+Current list commands support `--sort` and `--order`, but default behavior is unsorted because no sort field is applied unless users pass `--sort`.
+
+In current implementation, `list` execution fetches items from db-worker-node and runs `apply-sort` only when `:sort` is present in options.
+
+This means default output order depends on entity scan order from db-worker-node list functions, which is not aligned with the desired product behavior.
+
+The requested behavior is a consistent default sort key of `updated-at` for page, tag, and property list subcommands.
+
+## Current behavior snapshot
+
+| Layer | File | Current behavior |
+| --- | --- | --- |
+| CLI command parsing and execution | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs` | `:sort` is optional and defaults to nil, so `apply-sort` is skipped when `--sort` is absent. |
+| db-worker-node list thread-api bridge | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` | `:thread-api/cli-list-pages`, `:thread-api/cli-list-tags`, and `:thread-api/cli-list-properties` return unsorted collections from shared list helpers. |
+| Shared list helpers | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/mcp/tools.cljs` | List helpers filter and shape items but do not apply sort by `updated-at`. |
+| User docs | `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | List command syntax documents `--sort` as optional but does not state default sort behavior. |
+
+## Scope and non-goals
+
+This plan changes default sort behavior for CLI commands `list page`, `list tag`, and `list property`.
+
+This plan does not add new db-worker-node thread-api methods.
+
+This plan does not push pagination or sorting into db-worker-node.
+
+This plan does not change field names or output schemas.
+
+## Proposed behavior
+
+When users run `logseq list page`, `logseq list tag`, or `logseq list property` without `--sort`, CLI should sort by `updated-at` using the existing list sorting pipeline.
+
+When users pass `--sort`, the explicit value must override the default.
+
+`--order` should continue to default to `asc` unless explicitly set to `desc`.
+
+When multiple entities have the same primary sort value, CLI should apply `:db/id` as the deterministic secondary sort key.
+
+`offset` and `limit` must still be applied after sorting.
+
+The behavior should be equivalent to explicitly passing `--sort updated-at` today, with deterministic tie-breaking by `:db/id`.
+
+## Integration overview
+
+```text
+logseq list page
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs
+     - determine effective sort field (default updated-at)
+     - apply CLI-side sort/order
+     - apply offset/limit/fields
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/mcp/tools.cljs
+```
+
+## Testing Plan
+
+I will follow `@test-driven-development` and add tests before implementation changes.
+
+I will add unit tests for CLI list execution paths that verify default sorting is applied when `:sort` is missing.
+
+I will add unit tests that verify explicit `--sort` still overrides the new default.
+
+I will add integration tests that verify default output order matches explicit `--sort updated-at` output for page, tag, and property list commands.
+
+I will update docs assertions or command help expectations if any existing tests encode old behavior.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Detailed implementation plan
+
+1. Add a failing unit test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for list-page execution where input items are intentionally out of updated-at order and no `:sort` is provided.
+2. Assert in that test that returned item ids are ordered exactly as if `:sort` were `"updated-at"` with default `:order`.
+3. Add a failing unit test for list-tag execution with no `:sort` and confirm default updated-at ordering is applied after tag item preparation.
+4. Add a failing unit test for list-property execution with no `:sort` and confirm default updated-at ordering is applied after property item preparation.
+5. Add a failing unit test that passes explicit `:sort "title"` and confirms explicit sort overrides default updated-at behavior.
+6. Add a failing unit test that passes explicit `:order "desc"` without `:sort` and confirms order is applied to default updated-at sort key.
+7. Add a failing integration test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` that compares `list page` results against `list page --sort updated-at` for the same graph and asserts identical id sequences.
+8. Add a failing integration test that compares `list tag` against `list tag --sort updated-at` and asserts identical id sequences.
+9. Add a failing integration test that compares `list property` against `list property --sort updated-at` and asserts identical id sequences.
+10. Run focused tests to verify they fail for the new default-sort behavior and not for unrelated setup issues.
+11. Implement an `effective-sort` decision in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs` so list commands use `"updated-at"` when `:sort` is absent.
+12. Reuse the effective sort key for all three executors: `execute-list-page`, `execute-list-tag`, and `execute-list-property`.
+13. Keep existing explicit sort validation and allowed sort fields unchanged.
+14. Add deterministic tie-breaking by `:db/id` in CLI list sorting when primary sort values are equal.
+15. Keep existing order default (`asc`) unchanged.
+16. Update option descriptions in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs` to clarify default sort behavior for users.
+17. Update docs in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to state that list subcommands default to sorting by `updated-at`.
+18. Run focused unit and integration tests again and confirm green.
+19. Run `bb dev:test -v logseq.cli.commands-test` to confirm command-level regressions are not introduced.
+20. Run `bb dev:test -v logseq.cli.integration-test` for list command scenarios impacted by ordering.
+21. Run `bb dev:lint-and-test` for final confidence.
+
+## Edge cases to cover
+
+Entities with missing `:block/updated-at` should still be sortable without runtime errors.
+
+Multiple entities with equal `updated-at` values should be secondarily sorted by `:db/id` for deterministic output across repeated runs.
+
+`--fields` filtering should not remove `updated-at` before sorting is executed.
+
+`--offset` and `--limit` should continue to apply after sorting, not before sorting.
+
+`--sort` with any allowed non-time field should keep existing behavior and take precedence over the new default.
+
+`--order desc` without explicit `--sort` should now reverse default updated-at order.
+
+## Verification commands
+
+| Command | Expected result |
+| --- | --- |
+| `bb dev:test -v logseq.cli.commands-test/test-list-subcommand-parse` | Existing parse behavior remains valid and list options remain accepted. |
+| `bb dev:test -v logseq.cli.commands-test` | New default-sort unit tests pass and no command-level regressions are introduced. |
+| `bb dev:test -v logseq.cli.integration-test` | Integration checks for list default ordering pass against a real db-worker-node flow. |
+| `bb dev:lint-and-test` | Full lint and unit suite pass with zero errors. |
+
+## Rollout and compatibility
+
+This is a behavior change in default ordering for three CLI list commands.
+
+Scripts that depended on previous implicit scan order may observe changed item order.
+
+Scripts that already pass explicit `--sort` remain unaffected.
+
+No db-worker-node API contract change is introduced in this scope.
+
+## Testing Details
+
+Tests verify user-visible command behavior by comparing result ordering between default list calls and explicit `--sort updated-at` calls.
+
+Tests validate override behavior so explicit sort fields still control final ordering.
+
+Tests validate order plus pagination interaction to ensure behavior consistency.
+
+## Implementation Details
+
+- Update default sort selection in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs` for page, tag, and property list executors.
+- Keep existing `apply-sort`, `apply-offset-limit`, and `apply-fields` sequencing unchanged.
+- Extend CLI sort implementation to apply `:db/id` as secondary key when primary sort values are equal.
+- Reuse existing `list-*-field-map` entries for `updated-at` so no new field mapping is introduced.
+- Keep db-worker-node list handlers in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` unchanged in this scope.
+- Keep shared list helper behavior in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/mcp/tools.cljs` unchanged in this scope.
+- Add command-level unit coverage in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+- Add end-to-end list ordering coverage in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`.
+- Update user-facing list docs in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`.
+
+## Question
+
+No open questions.
+
+---
diff --git a/docs/agent-guide/063-logseq-cli-upsert-block-custom-many-property.md b/docs/agent-guide/063-logseq-cli-upsert-block-custom-many-property.md
new file mode 100644
index 0000000000..585741ee09
--- /dev/null
+++ b/docs/agent-guide/063-logseq-cli-upsert-block-custom-many-property.md
@@ -0,0 +1,164 @@
+# Logseq CLI Upsert Block Custom Many Property Reliability Plan
+
+Goal: Fix `logseq upsert block --update-properties` so custom public properties with `type=default` and `cardinality=many` can reliably persist multiple values on blocks.
+
+Architecture: Keep CLI command shape stable and preserve `upsert property` / `upsert block` UX.
+Architecture: Apply the core behavior fix in outliner property write logic (`:batch-set-property`) because db-worker-node forwards ops without property-value normalization.
+Architecture: Add end-to-end regression coverage in CLI integration tests and low-level behavioral coverage in outliner property tests.
+
+Tech Stack: ClojureScript, Datascript, Promesa, Logseq CLI command layer, db-worker-node thread-api, outliner ops (`deps/outliner`), existing CLI integration test harness.
+
+Related:
+- `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/044-logseq-cli-upsert-block-page.md`
+- `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/045-logseq-cli-property-type-and-upsert-option-unification.md`
+- `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/043-logseq-cli-tag-property-management.md`
+
+## Problem statement
+
+A reproducible CLI flow currently fails or behaves inconsistently when assigning multiple values to a custom property on a block:
+
+1. `graph create`
+2. `upsert property --name "Reproducible steps" --type default --cardinality many --public true`
+3. `upsert block --update-properties '{"Reproducible steps" ["Step 1" "Step 2" "Step 3"]}'`
+
+Observed behavior:
+- String-vector payload can fail with a generic CLI `http request failed` during `:batch-set-property`.
+- A numeric-id vector payload may report `ok` but still not materialize expected property datoms on the target block.
+
+Expected behavior:
+- The target block should persist exactly three values for that custom property.
+- CLI should provide deterministic success/failure semantics for both title-based values and id-based values.
+
+## Current implementation snapshot
+
+| Layer | File | Current behavior |
+| --- | --- | --- |
+| CLI upsert command wiring | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs` | `upsert block` (create/update paths) resolves properties and emits `[:batch-set-property [block-ids k v {}]]`. |
+| CLI property parse/resolve | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` | `allow-non-built-in? true` path supports custom properties and many values. |
+| db-worker-node bridge | `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` | `:thread-api/apply-outliner-ops` forwards ops to outliner; no property-value normalization. |
+| Outliner op execution | `/Users/rcmerci/gh-repos/logseq/deps/outliner/src/logseq/outliner/op.cljs` | `:batch-set-property` delegates to `outliner-property/batch-set-property!`. |
+| Property value conversion | `/Users/rcmerci/gh-repos/logseq/deps/outliner/src/logseq/outliner/property.cljs` | `convert-ref-property-value` is scalar-centric and has incomplete/implicit handling for custom ref-many collection values. |
+
+## Scope and non-goals
+
+This plan fixes custom property many-value persistence for block updates through CLI upsert/update flows.
+
+This plan includes both string-input and id-input value shapes for custom `default` + `many` properties.
+
+This plan does not redesign property schema semantics.
+
+This plan does not change CLI command flags or argument names.
+
+This plan does not add new thread-api methods.
+
+## Proposed behavior
+
+For custom public properties (`:user.property/*`) with `:db.cardinality/many` and ref-capable types (including `:default`):
+
+- `--update-properties '{"Name" ["Step 1" "Step 2" "Step 3"]}'` should persist three values on the block.
+- `--update-properties '{"Name" [180 181 182]}'` should persist three values on the block when ids are valid entities.
+- `--update-properties '{"Name" []}'` should clear the property from the target block.
+- Duplicate input values should be preserved at input semantics level (CLI/outliner must not proactively dedupe user input before write).
+- Result must be observable via Datascript query as expected datoms for that block/property.
+
+Failure cases should return explicit error payloads (invalid values, invalid ids, schema mismatch), not silent no-op behavior.
+
+## Root-cause hypothesis
+
+Primary hypothesis:
+- `batch-set-property!` in outliner currently applies ref conversion in a way that is optimized for scalar values and does not consistently normalize collection values for custom ref-many properties.
+- `convert-ref-property-value` treats collection values as a special case only when all elements are integers; string collection conversion is not explicit/element-wise for many mode.
+- This causes unstable behavior in CLI flows that legitimately pass many values.
+
+Secondary hypothesis:
+- Success responses can occur even when final value conversion does not produce a valid persisted property value set for the target block.
+
+## Testing plan (TDD first)
+
+I will follow `@test-driven-development` and add/adjust tests before implementation changes.
+
+### Outliner-level tests (RED first)
+
+Add tests in:
+`/Users/rcmerci/gh-repos/logseq/deps/outliner/test/logseq/outliner/property_test.cljs`
+
+1. Add failing test: custom property (`:user.property/reproducible-steps`) with `:default + many`, call `batch-set-property!` with string vector values, assert three persisted values.
+2. Add failing test: same property, call `batch-set-property!` with numeric id vector, assert three persisted values.
+3. Add failing test: mixed/invalid value set returns explicit error and does not partially persist.
+4. Add regression assertion that built-in many properties (for example tags/page-tags-like behavior) remain unchanged.
+
+### CLI integration tests (RED first)
+
+Add tests in:
+`/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs`
+
+5. Add failing end-to-end test:
+   - create graph
+   - upsert custom property (`default + many + public`)
+   - upsert block with string-vector update-properties
+   - query and assert exactly three values on target block.
+6. Add failing end-to-end test for id-vector values.
+7. Ensure assertion helper is many-aware (do not rely on scalar-only query helpers).
+
+### Optional command-level guard tests
+
+8. If needed, add command-level tests in:
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
+   to verify many-value payload survives parse/build-action shape without lossy normalization.
+
+## Detailed implementation plan
+
+1. In `/Users/rcmerci/gh-repos/logseq/deps/outliner/src/logseq/outliner/property.cljs`, introduce explicit many-aware ref conversion helper (for example, scalar conversion + collection mapping wrapper).
+2. Keep existing scalar conversion semantics as baseline for non-many properties.
+3. In `batch-set-property!`, compute cardinality from property entity and branch conversion flow:
+   - one: current scalar conversion path
+   - many: normalize to collection and convert each element deterministically.
+4. Ensure string inputs for custom default properties create/reuse property value entities element-by-element.
+5. Ensure integer/ref inputs for many mode are validated and preserved element-by-element.
+6. Preserve validation (`throw-error-if-invalid-property-value`) after conversion and before tx construction.
+7. Ensure self-reference protection for ref values also works in many mode (check each resolved element against block id when applicable).
+8. Keep transaction generation centralized via `build-property-value-tx-data` and avoid introducing duplicate write paths.
+9. Add explicit error context when conversion fails in many mode (property id, incoming value shape) to reduce generic `http request failed` surface area.
+10. Re-run newly added outliner tests and iterate until green.
+11. Re-run CLI integration tests and confirm end-to-end pass for both string-vector and id-vector payloads.
+12. Confirm existing upsert flows for built-in properties still pass.
+
+## Edge cases to cover
+
+- Empty vector value for many property should clear the property on the target block.
+- Duplicate values in input vector should be preserved at input semantics level (no proactive dedupe in CLI/outliner conversion path).
+- Mixed-type vectors (`["Step 1" 181]`) for default many property.
+- Invalid entity ids in id-vector input.
+- Non-public property update attempts.
+- Property just upserted in same flow followed immediately by block update.
+
+## Verification commands
+
+| Command | Expected result |
+| --- | --- |
+| `bb dev:test -v logseq.outliner.property-test` | New many-value conversion tests pass and no outliner regressions. |
+| `bb dev:test -v logseq.cli.integration-test` | New CLI e2e tests for custom many property pass. |
+| `bb dev:test -v logseq.cli.commands-test` | Command parse/build behavior remains stable. |
+| `bb dev:lint-and-test` | Full lint/test suite remains green. |
+
+## Acceptance criteria
+
+1. CLI flow for custom `default + many + public` property with string values persists all values on target block.
+2. CLI flow with id values persists all values on target block.
+3. Empty vector updates (`[]`) clear the target property from the block.
+4. Duplicate input values are preserved at input semantics level (conversion path does not proactively dedupe).
+5. Datascript query confirms expected count and value set semantics for the target block property.
+6. No regression for built-in property update flows.
+7. Failures return actionable error details instead of generic silent/no-op outcomes.
+
+## Rollout and compatibility
+
+This is a behavior correctness fix, not a CLI API change.
+
+Existing scripts using current flags remain valid.
+
+Behavioral change is limited to making many-value persistence for custom properties deterministic and correct.
+
+## Question
+
+No open design question for this phase.
diff --git a/docs/agent-guide/064-logseq-cli-integration-test-shell-refactor.md b/docs/agent-guide/064-logseq-cli-integration-test-shell-refactor.md
new file mode 100644
index 0000000000..556b85cf47
--- /dev/null
+++ b/docs/agent-guide/064-logseq-cli-integration-test-shell-refactor.md
@@ -0,0 +1,175 @@
+# Logseq CLI Integration Test Shell Refactor Implementation Plan
+
+Goal: Build a new `cli-e2e` test suite that refactors `logseq.cli.integration-test` into babashka-driven shell e2e tests for compiled `logseq-cli` and `db-worker-node`, excluding `sync`, `login`, and `logout`, with full in-scope subcommand coverage and key-option coverage.
+
+Architecture: Use a declarative command case manifest in `cli-e2e/` and execute every case via explicit shell command strings so test execution is transparent and copy-pasteable.
+Architecture: Run a build preflight that compiles `logseq-cli` and `db-worker-node` artifacts before every e2e run, then run cases against those compiled artifacts only.
+Architecture: Enforce completeness with a coverage checker that fails when any in-scope subcommand or any declared key option is not covered by at least one case.
+
+Tech Stack: Babashka, babashka.cli, babashka.process, EDN manifests, Node.js, shadow-cljs build targets `logseq-cli` and `db-worker-node`, existing Logseq CLI and db-worker-node runtime.
+
+Related: Relates to `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/053-logseq-cli-async-test-isolation.md`.
+Related: Relates to `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/058-db-worker-node-revision-and-cli-server-list.md`.
+Related: Relates to `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/060-cli-graph-list-legacy-graph-dir-rename-command.md`.
+
+## Problem statement
+
+The current `src/test/logseq/cli/integration_test.cljs` suite mostly calls `logseq.cli.main/run!` directly instead of executing `logseq-cli` as a shell command.
+This makes command-line behavior, quoting, piping, process lifecycle, and compiled artifact boundaries under-tested.
+The current suite also relies heavily on `with-redefs` for `sync` and auth flows, which hides process-level integration issues.
+The suite location and runtime are tied to `shadow-cljs :test`, while the new requirement is an independent `cli-e2e/` babashka flow that tests compiled binaries.
+The new requirement also asks for in-scope subcommand completeness with key option coverage enforcement, which is not explicitly guaranteed today.
+
+## Current implementation snapshot
+
+| Area | Current file | Current behavior | Gap against requirement |
+| --- | --- | --- | --- |
+| CLI integration tests | `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` | Runs in cljs test bundle and invokes `run!` directly for most tests. | Not fully shell-first and not isolated under `cli-e2e/`. |
+| CLI compiled artifact | `/Users/rcmerci/gh-repos/logseq/static/logseq-cli.js` | Generated by `shadow-cljs` target `logseq-cli`. | Not currently enforced as precondition in integration test flow. |
+| db-worker runtime used by CLI server lifecycle | `/Users/rcmerci/gh-repos/logseq/dist/db-worker-node.js` | Spawned by `logseq.cli.server/db-worker-script-path`. | Must be rebuilt before e2e to ensure latest runtime. |
+| Existing integration runner entrypoint | `/Users/rcmerci/gh-repos/logseq/package.json` (`cljs:run-integration-test`) | Runs `node static/tests.js -r '^(logseq.cli.integration-test).*'`. | Keeps tests inside cljs test harness instead of babashka shell runner. |
+
+## In-scope command and key option inventory
+
+The e2e suite target excludes every `sync *` command and excludes `login` and `logout`.
+The suite treats global options and command options as separate coverage buckets.
+The option inventory below is the key-option scope for this phase.
+
+| Scope | Commands | Options to cover |
+| --- | --- | --- |
+| Global | Any in-scope command invocation | `--help`, `--version`, `--config`, `--graph`, `--data-dir`, `--output`, `--verbose`. |
+| graph | `graph list`, `graph create`, `graph switch`, `graph remove`, `graph validate`, `graph info`, `graph export`, `graph import` | `--fix`, `--type`, `--file`, `--input`. |
+| list | `list page`, `list tag`, `list property` | `--expand`, `--fields`, `--limit`, `--offset`, `--sort`, `--order`, `--journal-only`, `--with-properties`, `--with-extends`, `--with-classes`, `--with-type`. |
+| upsert | `upsert block`, `upsert page`, `upsert tag`, `upsert property` | `--id`, `--uuid`, `--target-id`, `--target-uuid`, `--target-page`, `--pos`, `--content`, `--blocks-file`, `--status`, `--update-tags`, `--update-properties`, `--remove-tags`, `--remove-properties`, `--page`, `--name`, `--type`, `--cardinality`, `--hide`, `--public`. |
+| remove | `remove block`, `remove page`, `remove tag`, `remove property` | `--id`, `--uuid`, `--name`. |
+| query | `query`, `query list` | `--query`, `--name`, `--inputs`. |
+| show | `show` | `--id`, `--uuid`, `--page`, `--linked-references`, `--level`, stdin `--id` input path. |
+| server | `server list`, `server status`, `server start`, `server stop`, `server restart` | Command-specific graph use through `--graph`. |
+| doctor | `doctor` | `--dev-script`. |
+| completion | `completion` | Positional `zsh` or `bash`, and `--shell`. |
+
+## Testing Plan
+
+I will follow `@test-driven-development` for this refactor and write failing tests first in the new `cli-e2e` harness before implementation logic.
+I will keep the tests behavior-first by asserting process exit code, stdout or stderr payload, file-system side effects, and db state changes after shell commands.
+
+I will add a failing manifest coverage test that enumerates all in-scope subcommands and key options and fails when any item is missing from executed cases.
+I will add failing runner tests that assert commands are executed as explicit shell strings and that each case logs the exact command line.
+I will add failing preflight tests that assert build preflight runs before cases and that required compiled artifacts exist.
+I will add failing e2e cases for each in-scope command and each key option from the inventory table, using positive and validation-error scenarios.
+I will add regression tests for piping and stdin (`query | show --id`) to preserve shell-native workflows.
+I will add tests that verify db-worker-node lifecycle commands (`server start/status/restart/stop`) operate against compiled runtime.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Target layout and integration points
+
+The new harness will live under `/Users/rcmerci/gh-repos/logseq/cli-e2e/`.
+The existing `src/test/logseq/cli/integration_test.cljs` namespace will be reduced or split so in-scope command responsibilities move to the new harness.
+
+```text
++----------------------+        shell exec        +------------------------------+
+| cli-e2e bb runner    | -----------------------> | node static/logseq-cli.js    |
+| (bb + EDN manifests) |                          +--------------+---------------+
++----------+-----------+                                         |
+           |                                                     | spawns
+           | preflight build                                    v
+           |                                         +------------------------------+
+           +---------------------------------------> | dist/db-worker-node.js       |
+                                                     | via logseq.cli.server         |
+                                                     +------------------------------+
+```
+
+## Detailed implementation plan
+
+1. Create `/Users/rcmerci/gh-repos/logseq/cli-e2e/` with `bb.edn`, `README.md`, and minimal source directories.
+2. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn` tasks `build`, `test`, and `list-cases`.
+3. Use `@clojure-babashka-cli` patterns in `bb.edn` to parse `--case`, `--include`, `--skip-build`, and `--verbose`.
+4. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/paths.clj` to resolve absolute repo-root aware paths.
+5. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/shell.clj` with a single shell execution utility that records exact command strings.
+6. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/preflight.clj` to run build preflight commands.
+7. Implement preflight commands as `clojure -M:cljs compile logseq-cli db-worker-node` followed by `pnpm db-worker-node:compile:bundle`.
+8. Add preflight artifact existence checks for `/Users/rcmerci/gh-repos/logseq/static/logseq-cli.js`, `/Users/rcmerci/gh-repos/logseq/static/db-worker-node.js`, `/Users/rcmerci/gh-repos/logseq/dist/db-worker-node.js`, and `/Users/rcmerci/gh-repos/logseq/dist/db-worker-node-assets.json`.
+9. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` to declare required command and key-option coverage excluding sync, login, and logout.
+10. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` to declare all shell cases with `:cmd`, `:expect`, and `:covers`.
+11. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/coverage.clj` that computes missing command and key-option coverage from manifests.
+12. Write a failing test that coverage checker reports missing entries before cases are added.
+13. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/fixtures.clj` for temp data-dir, temp config, and graph seed helpers.
+14. Implement graph seed helper using explicit shell commands only, not direct namespace calls.
+15. Add base cases for global key-option coverage in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`.
+16. Add base cases for every `graph` subcommand and its options, including negative validation paths.
+17. Add base cases for every `list` subcommand and key list options with deterministic assertions.
+18. Add base cases for every `upsert` subcommand and key options, including selector conflict errors and file-based block insertion.
+19. Add base cases for every `remove` subcommand and key options, including uuid and name resolution behavior.
+20. Add base cases for `query` and `query list`, including `--query`, `--name`, and `--inputs` paths.
+21. Add base cases for `show` including `--id`, `--uuid`, `--page`, `--linked-references`, `--level`, and stdin id input.
+22. Add base cases for `server` commands and assert lifecycle transitions through `server status`.
+23. Add base cases for `doctor --dev-script` and assert readable script check behavior.
+24. Add base cases for `completion` positional and `--shell` usage and assert shell snippet markers.
+25. Add case-runner assertions for stdout parsing in `json`, `edn`, and `human` output modes.
+26. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/report.clj` to print pass or fail summary with missing coverage details.
+27. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/README.md` with setup, run commands, and expected artifacts.
+28. Add root task wiring in `/Users/rcmerci/gh-repos/logseq/bb.edn` for `dev:cli-e2e` delegating to `cli-e2e/bb.edn`.
+29. Add package script wiring in `/Users/rcmerci/gh-repos/logseq/package.json` for `cli:e2e` and `cli:e2e:skip-build`.
+30. Move or slim in-scope tests out of `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` and keep only compatibility coverage that still belongs in cljs unit scope.
+31. Add a deprecation note in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` pointing engineers to `cli-e2e/`.
+32. Run the full new `cli-e2e` suite with build preflight enabled and confirm zero missing coverage.
+33. Run a focused subset using `--case` to validate developer ergonomics and rerun speed.
+34. Run `bb dev:lint-and-test` to confirm the migration does not break existing unit test workflows.
+
+## Verification commands and expected outcomes
+
+| Command | Expected outcome |
+| --- | --- |
+| `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn build` | Compiles CLI and db-worker artifacts and passes artifact existence checks. |
+| `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn test` | Runs all in-scope cases and prints zero missing command or key-option coverage. |
+| `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn test --case show-stdin-id` | Runs one targeted case with exact shell command output shown. |
+| `bb dev:cli-e2e` | Delegates to `cli-e2e` full run from repository root. |
+| `bb dev:lint-and-test` | Existing lint and unit suites remain green after migration. |
+
+## Edge cases to include in case manifests
+
+1. Graph names and data-dir paths that include spaces and legacy-encoded names.
+2. `show --id` stdin behavior with empty stdin and invalid EDN input.
+3. Boolean option coercion for `--with-type`, `--linked-references`, `--hide`, and `--public`.
+4. Mutually exclusive selectors such as `upsert page --id` with `--page` and `remove block --id` with `--uuid`.
+5. Output format assertions for `--output human`, `--output json`, and `--output edn`.
+6. `query` argument validation for `--query` and `--name` conflict and invalid `--inputs` EDN.
+7. `completion` unsupported shell error path.
+8. `server` command behavior when the target graph server is missing or already running.
+9. `doctor --dev-script` when static script exists and when path is unreadable in a controlled failure case.
+10. Ensure excluded commands (`sync`, `login`, `logout`) are rejected by coverage checker if accidentally added to in-scope inventory.
+
+## Clarifications and assumptions captured in implementation
+
+1. Key option coverage means each in-scope key option must appear in at least one behaviorally asserted case and not merely in help text.
+2. Combinatorial explosion is controlled by one-option-at-least-once coverage plus targeted interaction cases for known conflicts.
+3. Sync commands plus `login` and `logout` are explicitly excluded from this plan and remain covered by other test scopes.
+4. The canonical runtime under test for CLI-managed server lifecycle is `dist/db-worker-node.js`, so bundle build is part of preflight.
+5. The new suite is the source of truth for shell e2e behavior, while cljs namespace tests remain unit and component level.
+
+## Testing Details
+
+The new tests validate real behavior at process boundaries by invoking compiled binaries through shell commands and asserting outputs, files, and db effects.
+Coverage checks verify every declared in-scope subcommand and key option has at least one asserted case.
+Failure output will include missing coverage entries and the exact failing shell command for fast diagnosis.
+
+## Implementation Details
+
+- Use `cli-e2e/spec/non_sync_inventory.edn` as the single source of required in-scope command and key-option coverage.
+- Use `cli-e2e/spec/non_sync_cases.edn` as declarative executable test cases with explicit `:covers`.
+- Use one shared shell executor to keep command logging and error reporting consistent.
+- Build preflight must run by default and may be skipped only with explicit `--skip-build`.
+- Keep all test setup through shell commands to satisfy shell-first requirement.
+- Use temp dirs per case to avoid cross-test contamination.
+- Keep `login` and `logout` out of this suite by explicit inventory exclusions and checker guards.
+- Preserve at least one pipeline test that uses stdout to stdin command chaining.
+- Keep root task wiring minimal and avoid coupling `cli-e2e` to existing cljs test runner.
+- Document command examples and troubleshooting in `cli-e2e/README.md`.
+
+## Question
+
+Do you want `login` and `logout` to stay permanently out of `cli-e2e`, or should we plan a separate optional suite for them under a dedicated `:manual` or `:network` tag?
+
+
+---
diff --git a/docs/agent-guide/065-logseq-cli-show-ref-id-footer.md b/docs/agent-guide/065-logseq-cli-show-ref-id-footer.md
new file mode 100644
index 0000000000..97d1448de6
--- /dev/null
+++ b/docs/agent-guide/065-logseq-cli-show-ref-id-footer.md
@@ -0,0 +1,166 @@
+# Logseq CLI Show Referenced Entity IDs in Footer Plan
+
+Goal: Add a footer section to `logseq show` human output that lists referenced entities and their IDs when block content contains `[[<ref>]]`.
+
+Architecture: Keep the existing tree rendering unchanged and append a post-tree summary section (`Referenced Entities`) generated from refs discovered in the shown tree (and linked references when enabled).
+
+Tech Stack: ClojureScript, `logseq.cli.command.show`, db-worker-node thread-api pull/query via existing transport.
+
+Related:
+- `docs/agent-guide/021-logseq-cli-reference-uuid-rewrite.md`
+- `docs/agent-guide/024-logseq-cli-show-updates.md`
+- `docs/agent-guide/010-logseq-cli-show-linked-references.md`
+
+## Problem Statement
+
+Current `show` output rewrites `[[<uuid>]]` to readable labels, but users cannot see the stable entity ID for each reference in human output.
+
+When reviewing large trees or debugging graph links, users need a deterministic ID mapping without polluting every inline block line.
+
+The selected UX is a dedicated footer section (not inline expansion) so the tree remains readable.
+
+## Proposed UX
+
+### Human output (new footer section)
+
+Keep current tree output exactly as-is, then append:
+
+```text
+Referenced Entities (2)
+181 -> First child line A\nline B for wrapping
+179 -> Root task for show command
+```
+
+Behavior:
+- Section appears only when at least one reference is present.
+- Order is by first appearance in rendered traversal order.
+- ID should be `:db/id` (human-facing stable numeric id in CLI context).
+- Label should prefer `:block/title`, then `:block/name`, then UUID string fallback.
+
+### Option behavior
+
+Provide an explicit option so users can disable the footer when needed:
+- `--ref-id-footer` (boolean, default `true`)
+
+When `true` (default), append the footer section.
+When `false`, do not render the footer section.
+
+Because this changes default human output, update related snapshots/tests accordingly and document the behavior in release notes.
+
+## Scope
+
+In scope:
+- Human output for `show` command only.
+- Single target and multi-id target modes.
+- Respect existing `--linked-references` behavior for reference discovery source.
+
+Out of scope:
+- JSON/EDN schema changes.
+- Inline replacement format changes.
+- New reference graph traversal semantics.
+
+## Design Details
+
+### Reference discovery source
+
+Build the footer map from already available tree data:
+1. Traverse `:root` tree nodes and gather references from text fields (`:block/title`, `:block/name`, `:block/content`).
+2. If linked references are enabled, include linked reference block texts too.
+3. Reuse existing UUID extraction and label fetch behavior where possible.
+
+### UUID to entity resolution
+
+Current logic already fetches labels for UUID refs. Extend resolution to also fetch `:db/id` for each referenced UUID:
+- Pull selector should include `:db/id`, `:block/uuid`, `:block/title`, `:block/name`.
+- Build map: `uuid-lowercase -> {:id <db-id> :label <label>}`.
+
+### Footer rendering
+
+Add formatter helper in `show.cljs`:
+- Input: ordered vector of referenced UUIDs + resolution map
+- Output:
+  - Header: `Referenced Entities (N)`
+  - Rows: `<id> -> <label>`
+
+Fallbacks:
+- Missing id: `- -> <label>`
+- Missing label: `<id> -> <uuid>`
+
+### Multi-id output
+
+For multi-id human output (joined by delimiter), each successful tree result should include its own footer section when enabled.
+
+Failed targets keep current error text behavior unchanged.
+
+## Implementation Plan (TDD Order)
+
+1. Add failing tests for footer rendering helper (no refs, one ref, multiple refs, missing label/id fallbacks).
+2. Add failing tests for `show` human output with `--ref-id-footer true`:
+   - Single target output includes `Referenced Entities` section.
+   - `--ref-id-footer false` has no section.
+3. Add failing tests for multi-id output ensuring each successful segment can include its own footer.
+4. Extend `show-spec` with `--ref-id-footer` boolean option.
+5. Thread option through `build-action` into action map.
+6. Extend reference metadata fetch to include `:db/id` and produce `uuid -> {:id :label}` map.
+7. Add footer rendering and append step to human rendering path only.
+8. Ensure existing JSON/EDN output remains unchanged.
+9. Update help/commands tests that validate `show --help` options.
+10. Run targeted and full CLI tests.
+
+## Files to Touch
+
+- `src/main/logseq/cli/command/show.cljs`
+  - Option spec (`show-spec`)
+  - Action wiring (`build-action`)
+  - UUID metadata fetch (id + label)
+  - Footer rendering helpers
+  - Human rendering composition
+
+- `src/test/logseq/cli/command/show_test.cljs`
+  - Unit tests for new helper behavior
+
+- `src/test/logseq/cli/format_test.cljs`
+  - Human formatting assertions for `show` payload passthrough
+
+- `src/test/logseq/cli/commands_test.cljs`
+  - Help output option coverage if command options are asserted there
+
+## Testing Plan
+
+Targeted tests:
+- `bb dev:test -v logseq.cli.command.show-test`
+- `bb dev:test -v logseq.cli.format-test/test-human-output-show`
+- `bb dev:test -v logseq.cli.commands-test`
+
+Regression:
+- `bb dev:lint-and-test`
+
+Acceptance criteria:
+- With default options, show human output appends `Referenced Entities (N)` with `<id> -> <label>` rows when references exist.
+- With `--ref-id-footer false`, footer section is not rendered.
+- Multi-id output preserves delimiter/error behavior and only enhances successful segments.
+- JSON/EDN outputs do not add/remove fields due to this feature.
+
+## Edge Cases
+
+- Duplicate references in multiple blocks should appear once in footer (first-seen order).
+- Broken references (entity missing) should still print UUID fallback row.
+- References discovered only inside linked references should be included only when linked references are enabled.
+- Very large reference sets should remain deterministic; consider future pagination if needed.
+
+## Rollout and Risk
+
+Risk: medium.
+- Medium for human-output compatibility because default behavior changes.
+- Medium for output snapshot tests and formatting expectations.
+
+Mitigation:
+- Provide `--ref-id-footer false` opt-out.
+- Add precise tests for ordering and fallback behavior.
+- Document the default change in release notes.
+
+## Future Extensions
+
+- Allow `--ref-id-footer db-id|uuid|both` display mode.
+- Add `--ref-id-footer-limit` for huge outputs.
+- Add grouped footer by page for better navigation.
diff --git a/docs/agent-guide/066-logseq-cli-list-property-cardinality-column.md b/docs/agent-guide/066-logseq-cli-list-property-cardinality-column.md
new file mode 100644
index 0000000000..05c673f7af
--- /dev/null
+++ b/docs/agent-guide/066-logseq-cli-list-property-cardinality-column.md
@@ -0,0 +1,182 @@
+# Logseq CLI List Property Cardinality Column Plan
+
+Goal: Add a `CARDINALITY` column to `logseq list property` output, aligned with the existing `TYPE` column behavior and powered by current `logseq-cli -> db-worker-node` thread-api flow.
+
+Architecture: Keep the transport contract unchanged (`:thread-api/cli-list-properties`) and extend the property list payload shape plus human formatter columns.
+
+Tech Stack: ClojureScript, Datascript, Promesa, `logseq.cli.command.list`, `logseq.cli.common.db-worker`, `frontend.worker.db-core`, `logseq.cli.format`.
+
+Related:
+- `docs/agent-guide/045-logseq-cli-property-type-and-upsert-option-unification.md`
+- `docs/agent-guide/064-logseq-cli-integration-test-shell-refactor.md`
+- `docs/cli/logseq-cli.md`
+
+## Problem Statement
+
+`list property` currently includes `TYPE` in default output, but it does not show property cardinality in human tables.
+
+In current implementation:
+- CLI list execution (`src/main/logseq/cli/command/list.cljs`) already supports property-specific fields and formatting hooks.
+- db-worker thread API (`src/main/frontend/worker/db_core.cljs`) already routes `:thread-api/cli-list-properties` to `logseq.cli.common.db-worker/list-properties`.
+- Property list payload currently includes `:logseq.property/type` in non-expanded mode, but does not guarantee cardinality is present for all properties.
+- Human formatter (`src/main/logseq/cli/format.cljs`) has no `CARDINALITY` column for `:list-property`.
+
+Users cannot quickly inspect whether a property is `one` or `many` from the list table.
+
+## Current Data Flow (Baseline)
+
+```text
+logseq list property
+  -> src/main/logseq/cli/command/list.cljs execute-list-property
+  -> transport/invoke :thread-api/cli-list-properties
+  -> db-worker-node /v1/invoke forwarding
+  -> src/main/frontend/worker/db_core.cljs :thread-api/cli-list-properties
+  -> src/main/logseq/cli/common/db_worker.cljs list-properties
+  -> back to CLI formatter src/main/logseq/cli/format.cljs
+```
+
+This flow is already correct and should be preserved. The change is additive in payload fields and table rendering.
+
+## Target Contract
+
+1. Human output for `list property` includes a `CARDINALITY` column by default.
+2. Cardinality values render as `one` or `many` (not raw Datascript keywords).
+3. If a property has no explicit `:db/cardinality`, treat it as `one` (Datascript default semantics).
+4. For `--output json`, property items expose cardinality via `cardinality` (string `"one"` or `"many"`).
+5. For `--output edn`, property items expose cardinality via `:db/cardinality`.
+6. `--fields` and `--sort` for `list property` can reference `cardinality`.
+7. Existing thread-api method names and db-worker-node invoke protocol remain unchanged.
+
+## Design Decisions
+
+### 1) Cardinality source of truth
+
+Use `:db/cardinality` from property entity returned by Datascript.
+
+Normalization rule:
+- `:db.cardinality/many` => `many`
+- `:db.cardinality/one` or missing value => `one`
+
+### 2) Payload layer behavior
+
+In `src/main/logseq/cli/common/db_worker.cljs` `list-properties`:
+- Ensure non-expanded list items always include `:db/cardinality`.
+- For entities missing explicit cardinality, populate `:db/cardinality :db.cardinality/one`.
+- Keep existing behavior for `:logseq.property/type`, classes, description, and built-in filtering.
+
+### 3) CLI list command behavior
+
+In `src/main/logseq/cli/command/list.cljs`:
+- Extend `list-property-field-map` with `"cardinality" -> :db/cardinality`.
+- Keep existing default option behavior (`--with-type` remains unchanged).
+- Reuse existing `apply-sort` / `apply-fields` pipeline so cardinality works with no new execution path.
+
+### 4) Human formatter behavior
+
+In `src/main/logseq/cli/format.cljs`:
+- Add a cardinality normalization helper (similar style to `normalize-property-type`).
+- Add `CARDINALITY` to `list-property-columns` near `TYPE`.
+- Render `one` / `many`, and fallback to `-` only for truly unknown values.
+
+### 5) Structured output key behavior
+
+- Keep payload source key as `:db/cardinality` in command/data layer.
+- In JSON formatting path, map property-list item key `db/cardinality` to `cardinality`.
+- EDN output keeps `:db/cardinality` unchanged.
+
+## Implementation Plan (TDD Order)
+
+1. Add failing formatter tests in `src/test/logseq/cli/format_test.cljs`:
+   - `list property` table includes `CARDINALITY` header.
+   - `:db.cardinality/many` renders `many`.
+   - missing/`one` cardinality renders `one`.
+
+2. Add failing db-worker payload tests in `src/test/logseq/cli/common/db_worker_test.cljs`:
+   - non-expanded `list-properties` includes `:db/cardinality` key.
+   - custom property created without explicit cardinality still yields `:db.cardinality/one`.
+
+3. Add failing output-format tests in `src/test/logseq/cli/format_test.cljs`:
+   - JSON output for `list property` uses `cardinality` key.
+   - EDN output for `list property` keeps `:db/cardinality`.
+
+4. Add failing command parsing/execution tests in `src/test/logseq/cli/commands_test.cljs`:
+   - `list property --fields name,type,cardinality` parses successfully.
+   - `list property --sort cardinality` is accepted and sorted through existing pipeline.
+
+5. Implement payload update in `src/main/logseq/cli/common/db_worker.cljs`.
+
+6. Implement field-map update in `src/main/logseq/cli/command/list.cljs`.
+
+7. Implement formatter updates in `src/main/logseq/cli/format.cljs`:
+   - human `CARDINALITY` column + value normalization.
+   - JSON key remap `db/cardinality` -> `cardinality` for `:list-property`.
+
+8. Update CLI docs in `docs/cli/logseq-cli.md`:
+   - document `CARDINALITY` as default `list property` column.
+   - document JSON key `cardinality` and EDN key `:db/cardinality`.
+   - mention default semantics (`one` when omitted in schema).
+
+9. Update shell e2e spec in `cli-e2e/spec/non_sync_cases.edn`:
+   - extend `property-upsert-and-list-json` expectation to include `cardinality` field/value.
+
+10. Run focused tests, then broader regression suite.
+
+## Files to Touch
+
+- `src/main/logseq/cli/common/db_worker.cljs`
+  - include normalized cardinality in property list payload.
+
+- `src/main/logseq/cli/command/list.cljs`
+  - add `cardinality` field mapping for sort/fields.
+
+- `src/main/logseq/cli/format.cljs`
+  - add `CARDINALITY` column and render normalization.
+
+- `src/test/logseq/cli/common/db_worker_test.cljs`
+  - contract tests for property list payload cardinality.
+
+- `src/test/logseq/cli/commands_test.cljs`
+  - parser/sort/fields coverage for new property field.
+
+- `src/test/logseq/cli/format_test.cljs`
+  - human table assertions with cardinality column.
+
+- `cli-e2e/spec/non_sync_cases.edn`
+  - structured output expectation coverage.
+
+- `docs/cli/logseq-cli.md`
+  - user-facing command/output reference update.
+
+## Verification Commands
+
+| Command | Expected |
+| --- | --- |
+| `bb dev:test -v logseq.cli.format-test/test-human-output-list-tag-property` | Property table assertions pass with `CARDINALITY`. |
+| `bb dev:test -v logseq.cli.common.db-worker-test` | Non-expanded property payload includes cardinality contract. |
+| `bb dev:test -v logseq.cli.commands-test/test-list-subcommand-parse` | `cardinality` fields/sort parsing passes. |
+| `bb -f cli-e2e/bb.edn test --skip-build` | Non-sync CLI e2e list/property cases pass. |
+| `bb dev:lint-and-test` | Full lint/test suite remains green. |
+
+## Risks and Mitigation
+
+- Risk: Some properties may not explicitly store `:db/cardinality`, causing missing-column behavior.
+  - Mitigation: Normalize missing to `:db.cardinality/one` in payload layer.
+
+- Risk: Human output snapshot expectations may break due to added column width/layout.
+  - Mitigation: Update formatter tests with explicit expected tables.
+
+- Risk: Structured output consumers may rely on previous key set.
+  - Mitigation: This is additive only; do not remove or rename existing fields.
+
+## Out of Scope
+
+- Adding a new CLI option such as `--with-cardinality`.
+- Changing thread-api names or db-worker-node HTTP protocol.
+- Changing `upsert property` cardinality semantics.
+
+## Decision
+
+- JSON output uses `cardinality`.
+- EDN output uses `:db/cardinality`.
+
+Implementation note: keep command/data layer on `:db/cardinality`, and apply JSON-only key remapping in formatting path for `:list-property`.
diff --git a/docs/agent-guide/067-logseq-cli-json-namespaced-keys.md b/docs/agent-guide/067-logseq-cli-json-namespaced-keys.md
new file mode 100644
index 0000000000..b5f01f25fe
--- /dev/null
+++ b/docs/agent-guide/067-logseq-cli-json-namespaced-keys.md
@@ -0,0 +1,256 @@
+# Logseq CLI JSON Namespaced Keys Implementation Plan
+
+Goal: Make `--output json` preserve namespaced keys so agents can reliably parse Logseq graph semantics without lossy key flattening.
+
+Architecture: Keep the existing `logseq-cli -> db-worker-node` transit transport contract unchanged for `directPass=false` calls.
+Architecture: Move semantic-preserving JSON conversion into the CLI formatting boundary so all command outputs can keep canonical namespaced keys in machine output.
+Architecture: Update tests, shell completion, and user docs to consume namespaced JSON keys as the canonical contract.
+
+Tech Stack: ClojureScript, `logseq.cli.format`, `logseq.cli.transport`, `frontend.worker.db-worker-node`, `cli-e2e`, JSON parsing with keywordized paths.
+
+Related: Builds on `docs/agent-guide/035-logseq-cli-db-worker-deps-cli-decoupling.md`, `docs/agent-guide/066-logseq-cli-list-property-cardinality-column.md`, and `docs/agent-guide/task--db-worker-nodejs-compatible.md`.
+
+## Problem statement
+
+Current JSON output is not semantically faithful for keyword keys and ident-heavy graph data.
+
+The core `db-worker-node` invoke contract already preserves Clojure semantics in transit for `directPass=false` via `resultTransit`.
+
+The semantic loss happens at the final CLI JSON formatting stage in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` when `clj->js` is used on keyword-keyed maps.
+
+When keyword namespaces are dropped in JSON keys, `:block/title` and `:logseq.property/title` can collapse into an ambiguous flat key, which breaks stable agent parsing.
+
+This is especially harmful for Logseq because identity and schema semantics depend on namespace, ident, and cardinality.
+
+If JSON output strips namespace semantics, CLI machine output no longer reflects the graph-native model accurately.
+
+## Current implementation baseline
+
+The current non-direct-pass runtime path is:
+
+```text
+CLI command execution
+  -> /src/main/logseq/cli/transport.cljs transport/invoke
+  -> POST /v1/invoke on db-worker-node
+  -> db-worker-node returns {:ok true :resultTransit "..."}
+  -> CLI decodes transit into Clojure data
+  -> /src/main/logseq/cli/format.cljs format-result ->json
+  -> JSON stringify for stdout
+```
+
+`/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` keeps `resultTransit` for `directPass=false`, which is good and should remain unchanged.
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` currently serializes machine output with `clj->js`, which is the lossy boundary we need to replace.
+
+`list property` currently has a JSON-only key remap (`db/cardinality` to `cardinality`) that also weakens namespace semantics.
+
+Shell completion generation in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/completion_generator.cljs` currently reads flat keys like `title` from JSON output.
+
+`cli-e2e` non-sync specs currently assert many flat JSON paths such as `[:data :items 0 :title]`.
+
+## Target JSON contract
+
+JSON output must preserve canonical key namespaces whenever the source map key is a namespaced keyword.
+
+The canonical key form is string `namespace/name` in JSON object keys.
+
+Unqualified keyword keys remain plain strings like `status`, `data`, and `message`.
+
+String keys already present in data must remain unchanged.
+
+Keyword values that represent idents must preserve namespace text in machine output.
+
+The output contract should prioritize semantic correctness over legacy flat-key convenience.
+
+### Contract examples
+
+| Source key or value | Current JSON behavior | Target JSON behavior |
+| --- | --- | --- |
+| `:block/title` key | `"title"` | `"block/title"` |
+| `:logseq.property/title` key | `"title"` | `"logseq.property/title"` |
+| `:db/id` key | `"id"` | `"db/id"` |
+| `:db/cardinality` key | `"cardinality"` in list-property path | `"db/cardinality"` |
+| ident value like `:logseq.class/Tag` | lossy/ambiguous stringification in machine output | namespace-preserving machine string |
+
+## Scope and non-goals
+
+In scope is `--output json` machine output behavior for CLI command results.
+
+In scope is preserving namespaced semantics for nested maps, vectors, and mixed payloads.
+
+In scope is keeping `--output edn` unchanged as already semantically rich.
+
+In scope is preserving current `db-worker-node` transit invoke protocol for non-direct-pass methods.
+
+Out of scope is redesigning command-specific domain schemas unrelated to namespace loss.
+
+Out of scope is changing human output formatting.
+
+Out of scope is adding new graph schema attributes.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and write failing tests before implementation.
+
+I will add formatter unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` that assert namespaced key preservation in JSON output for nested maps.
+
+I will add a collision test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` that includes both `:block/title` and `:logseq.property/title` and verifies both keys survive in JSON output simultaneously.
+
+I will add tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` asserting `:db/id`, `:db/ident`, and `:db/cardinality` are emitted as namespaced JSON keys.
+
+I will add a regression test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` ensuring UUID conversion still emits strings and does not regress while changing JSON key conversion.
+
+I will add CLI e2e expectation updates in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` for JSON paths that currently rely on flat keys, switching them to namespaced paths where the source keys are namespaced.
+
+I will add or update completion-related tests for `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/completion_generator.cljs` to ensure JSON key path usage remains correct when page titles are read from `block/title`.
+
+I will keep existing db-worker-node invoke contract tests green in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` to confirm no protocol regressions in `resultTransit` handling.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Architecture sketch
+
+```text
+db-worker-node (unchanged transit contract)
+  /v1/invoke -> {:ok true :resultTransit "..."}
+
+logseq-cli transport
+  decode transit -> Clojure data with keyword keys
+
+logseq-cli format
+  semantic JSON normalizer
+  keyword keys -> namespaced key strings
+  keyword ident values -> namespace-preserving machine strings
+  UUID -> string
+
+stdout JSON
+  canonical namespaced keys for graph-native parsing
+```
+
+## Implementation plan
+
+1. Read `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` and identify all JSON-path helpers currently used by `->json`.
+
+2. Add a RED formatter test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` that fails under current flattening for a map containing both `:block/title` and `:logseq.property/title`.
+
+3. Run the focused formatter test and confirm it fails for the expected key collision reason.
+
+4. Add a RED formatter test asserting list-property JSON exposes `db/cardinality` instead of only `cardinality`.
+
+5. Run focused tests and confirm failure before implementation.
+
+6. Add a RED formatter test asserting namespaced id key preservation for `:db/id` and `:db/ident` in JSON output.
+
+7. Run focused tests and confirm failure before implementation.
+
+8. Implement a JSON key conversion helper in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` that maps keyword keys to canonical JSON key strings using full namespace.
+
+9. Implement a JSON value normalization helper in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` that preserves namespace text for ident-like keyword values and keeps UUID string conversion.
+
+10. Replace direct `clj->js` serialization in `->json` with the new semantic JSON normalization pipeline.
+
+11. Remove or adjust `list-property` JSON-only remap in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` so canonical namespaced key output is preserved.
+
+12. Run formatter tests and ensure new JSON contract tests pass.
+
+13. Review `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/completion_generator.cljs` and update JSON extraction paths from flat keys to namespaced keys where required.
+
+14. Add or update completion generator tests to verify title extraction still works using namespaced JSON keys.
+
+15. Run focused completion-related tests and ensure green results.
+
+16. Update `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` JSON path assertions that currently depend on flattened keys.
+
+17. Run `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn test --skip-build` and verify non-sync CLI e2e passes with namespaced JSON paths.
+
+18. Update machine output documentation in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to describe namespaced JSON key behavior and migration examples.
+
+19. Add a migration table in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` mapping old flat keys to new canonical namespaced keys.
+
+20. Re-run focused formatter and e2e tests after docs-aligned contract updates.
+
+21. Run `bb dev:test -v logseq.cli.format-test` for full formatter regression.
+
+22. Run `bb dev:test -v frontend.worker.db-worker-node-test` to ensure transport protocol behavior remains unchanged.
+
+23. Run `bb dev:lint-and-test` for final regression verification.
+
+## File-by-file change map
+
+| File | Change |
+| --- | --- |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` | Add semantic JSON key/value serializer and switch `->json` to it. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` | Add collision and namespaced-key JSON contract tests. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/completion_generator.cljs` | Update JSON key lookup paths for namespaced key contract. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` | Update JSON path assertions to namespaced key paths. |
+| `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | Document canonical namespaced JSON output and migration guidance. |
+
+## Verification commands
+
+| Command | Expected result |
+| --- | --- |
+| `bb dev:test -v logseq.cli.format-test` | New and existing formatter tests pass, including namespaced key coverage. |
+| `bb -f cli-e2e/bb.edn test --skip-build` | Non-sync CLI e2e spec passes with updated JSON paths. |
+| `bb dev:test -v frontend.worker.db-worker-node-test` | db-worker-node invoke contract remains green. |
+| `bb dev:lint-and-test` | Repository lint and unit/integration checks remain green. |
+
+## Edge cases
+
+A payload map may contain both namespaced and unqualified keys with the same leaf name.
+
+A payload map may contain multiple namespaced keys sharing the same leaf name across different namespaces.
+
+Nested maps inside vectors and vectors inside maps must preserve key semantics recursively.
+
+Keyword values that are real user strings in data must not be mistyped by the serializer.
+
+String keys containing `/` must remain unchanged and must not be reinterpreted as keywords.
+
+`doctor` and auth outputs with simple keys should remain stable.
+
+Graph info `kv` already uses string keys like `logseq.kv/schema-version` and must remain unchanged.
+
+## Rollout and compatibility notes
+
+This change modifies machine output key names for JSON consumers that rely on flat keys.
+
+Internal completion scripts and cli-e2e specs must be migrated in the same change set.
+
+CLI docs must include a key migration table to avoid silent script breakage.
+
+If release policy requires a compatibility bridge, introduce a temporary opt-in or opt-out key mode as a follow-up decision.
+
+## Testing Details
+
+The most important behavioral tests are output-level assertions on actual JSON strings parsed back into maps, not helper internals.
+
+Collision tests must prove we can simultaneously represent `:block/title` and `:logseq.property/title` in one JSON object.
+
+E2E tests must confirm real CLI commands still work for scripting with updated key paths in shell-driven scenarios.
+
+Protocol safety is verified by keeping db-worker-node invoke tests unchanged and green, demonstrating this plan does not alter transit transport semantics.
+
+## Implementation Details
+
+- Keep `db-worker-node` non-direct-pass invoke contract unchanged.
+- Fix semantic loss only at CLI JSON formatting boundary.
+- Convert keyword keys to canonical namespaced JSON keys.
+- Preserve UUID string conversion behavior.
+- Preserve namespace text in ident-like keyword values.
+- Remove JSON-only flattening remaps that conflict with canonical namespaced contract.
+- Update completion generator JSON key lookup paths.
+- Update cli-e2e JSON path expectations.
+- Update CLI docs with migration mapping.
+- Validate with formatter tests, cli-e2e, and full lint-and-test.
+
+## Decisions
+
+`--output json` will switch directly to namespaced keys as the default behavior with no compatibility mode for legacy flat keys.
+
+Keyword and ident values in JSON output will be serialized as plain namespace-preserving strings, without type-tag objects.
+
+## Question
+
+None at this stage.
+
+---
diff --git a/docs/agent-guide/068-logseq-cli-profile-timing.md b/docs/agent-guide/068-logseq-cli-profile-timing.md
new file mode 100644
index 0000000000..68441d6fd6
--- /dev/null
+++ b/docs/agent-guide/068-logseq-cli-profile-timing.md
@@ -0,0 +1,272 @@
+# Logseq CLI Profile Stage Timing Implementation Plan
+
+Goal: Add a global `--profile` option with default `false` so every `logseq` command can print stage-by-stage elapsed time without breaking existing command output contracts.
+
+Architecture: Introduce a lightweight profiling session in `logseq-cli` that records ordered stage spans across argument parsing, config resolution, command execution, server orchestration, and transport calls.
+Architecture: Reuse existing `logseq-cli -> db-worker-node` boundaries by instrumenting `logseq.cli.main`, `logseq.cli.server`, and `logseq.cli.transport` rather than changing db-worker-node API contracts.
+Architecture: Emit profile report lines to stderr only so stdout remains identical for human, JSON, and EDN command outputs.
+
+Tech Stack: ClojureScript, `promesa`, `babashka.cli`, `lambdaisland.glogi`, Node.js process I/O, existing `logseq-cli` and `db-worker-node` runtime boundaries.
+
+Related: Builds on `docs/agent-guide/003-db-worker-node-cli-orchestration.md`, `docs/agent-guide/005-logseq-cli-output-and-db-worker-node-log.md`, and `docs/agent-guide/028-logseq-cli-verbose-debug.md`.
+
+## Problem statement
+
+`logseq-cli` currently has debug logging via `--verbose`, but it does not provide a stable per-stage timing summary for each command run.
+
+Developers can see individual transport elapsed logs in debug mode, but they cannot reliably answer where command time is spent end to end.
+
+This is especially painful for commands that include daemon startup, lock waiting, readiness checks, and multiple thread-api invocations.
+
+The feature request is to add a global `--profile` option with default `false` and print stage timing for command execution.
+
+The new behavior must avoid changing functional command results and must not pollute stdout machine output.
+
+## Current implementation baseline
+
+Global CLI options are defined in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` via `global-spec*` and `parse-leading-global-opts`.
+
+Command runtime orchestration is centralized in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` in `run!`.
+
+Action dispatch and pre-checks are centralized in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` in `execute`.
+
+Daemon lifecycle orchestration is centralized in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` with `ensure-server-started!` and helpers delegated to `logseq.db-worker.daemon`.
+
+Transport round trips are centralized in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs` in `invoke`.
+
+db-worker-node daemon CLI parsing lives in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` and currently has no profile flag.
+
+## Target behavior
+
+`--profile` is a global option for `logseq` commands and defaults to `false` when absent.
+
+When `--profile` is enabled, command stdout content remains unchanged and profile output is written to stderr.
+
+Profile output includes total duration and ordered stage rows with elapsed milliseconds.
+
+Repeated stages such as multiple `transport/invoke` calls are aggregated by stage key with count, total, and average durations.
+
+A failed command still prints profile data for stages that ran before the failure.
+
+Help and version paths also support profiling and print minimal stage reports.
+
+No db-worker-node HTTP endpoint or thread-api signature changes are required.
+
+### Proposed stage taxonomy
+
+| Stage key | Source file | Trigger |
+| --- | --- | --- |
+| `cli.parse-args` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` | `commands/parse-args` call. |
+| `cli.resolve-config` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` | `config/resolve-config` call. |
+| `cli.ensure-data-dir` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` | `data-dir/ensure-data-dir!` call. |
+| `cli.build-action` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` | `commands/build-action` call. |
+| `cli.execute-action` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` | `commands/execute` call. |
+| `server.ensure-started` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` | `ensure-server-started!` total path. |
+| `server.spawn-daemon` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` | daemon spawn branch only. |
+| `server.wait-lock` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` | wait for lock file and bound port. |
+| `server.wait-ready` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` | wait for `/readyz`. |
+| `transport.invoke:<method>` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs` | per thread-api HTTP invoke. |
+| `cli.format-result` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` | `format/format-result` call. |
+| `cli.total` | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` | whole `run!` lifecycle. |
+
+### Proposed stderr output example
+
+```text
+[profile] total=842ms command=graph-info status=ok
+[profile] cli.parse-args count=1 total=2ms avg=2ms
+[profile] cli.resolve-config count=1 total=1ms avg=1ms
+[profile] cli.ensure-data-dir count=1 total=3ms avg=3ms
+[profile] cli.build-action count=1 total=1ms avg=1ms
+[profile] server.ensure-started count=1 total=522ms avg=522ms
+[profile] server.wait-ready count=1 total=417ms avg=417ms
+[profile] transport.invoke:thread-api/q count=2 total=286ms avg=143ms
+[profile] cli.format-result count=1 total=2ms avg=2ms
+```
+
+## Scope and non-goals
+
+In scope is a global `--profile` option for `logseq` command execution profiling.
+
+In scope is timing visibility for CLI orchestration stages and transport boundaries that dominate latency.
+
+In scope is deterministic stderr profile output suitable for local debugging and CI logs.
+
+Out of scope is changing db-worker-node protocol payloads or introducing profile fields into command data output.
+
+Out of scope is a full distributed trace system across child processes.
+
+Out of scope is changing default command behavior when `--profile` is not provided.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and write failing tests before implementation.
+
+I will add a parser test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` that asserts `--profile` is accepted as a global option and is absent by default.
+
+I will add completion metadata tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` to verify `--profile` appears in generated zsh and bash completions.
+
+I will add runtime profiling tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/main_test.cljs` that assert profile lines are produced only when `--profile` is enabled.
+
+I will add transport profiling tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/transport_test.cljs` that assert `transport.invoke:<method>` stage records include elapsed timing and aggregation counts.
+
+I will add server lifecycle profiling tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` that verify spawn and wait stages are recorded in profile-enabled runs.
+
+I will add a regression test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` confirming stdout JSON remains parseable and profile lines only appear on stderr.
+
+I will update docs assertions or snapshots only where global option text changes.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Architecture sketch
+
+```text
+raw argv
+  -> cli.main/run!
+      -> profile session (enabled by --profile)
+      -> parse args
+      -> resolve config
+      -> ensure data dir
+      -> build action
+      -> execute action
+           -> cli.server ensure/start/reuse db-worker-node
+           -> cli.transport invoke thread-api methods
+      -> format result
+      -> stdout (unchanged command output)
+      -> stderr (profile summary when enabled)
+```
+
+## Implementation plan
+
+1. Read `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` and add `:profile` to `global-spec*` as boolean global option with help text.
+
+2. Add a RED test in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` proving `commands/parse-args` accepts `--profile` and stores it under `:options`.
+
+3. Run the focused parser test and confirm it fails for the expected missing-option reason.
+
+4. Add RED completion tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` asserting generated completion scripts include `--profile`.
+
+5. Run focused completion tests and confirm failure before implementation.
+
+6. Create `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/profile.cljs` with a small profiling session API for span recording, aggregation, and stderr rendering.
+
+7. Add RED unit tests for the new profiling helper in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/log_test.cljs` or a new `profile_test.cljs` namespace.
+
+8. Run focused profiling helper tests and confirm failure before implementation.
+
+9. Instrument `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` to create a profiling session when `--profile` is present and wrap top-level stages.
+
+10. Extend `run!` return shape to include profile report lines or profile metadata in a non-breaking internal field consumed by `main`.
+
+11. Update `main` in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` to print profile lines to stderr after command output handling.
+
+12. Add RED main runtime tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/main_test.cljs` for both enabled and disabled profile modes.
+
+13. Run focused main tests and confirm they fail before instrumentation is complete.
+
+14. Instrument `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` stage boundaries for ensure, spawn, wait-lock, and wait-ready using the shared profiling session in config.
+
+15. Add RED server profiling tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` to validate stage records for spawn and reuse paths.
+
+16. Run focused server tests and confirm expected failing assertions.
+
+17. Instrument `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs` so each invoke records `transport.invoke:<method>` spans.
+
+18. Add RED transport profiling tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/transport_test.cljs` verifying stage key naming and aggregation semantics.
+
+19. Run focused transport tests and confirm failure before final implementation pass.
+
+20. Wire profile context propagation through the existing config flow without changing command action schemas.
+
+21. Add integration coverage in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` to verify stdout contract safety with `--output json` plus `--profile`.
+
+22. Run focused integration tests and confirm profile output is stderr-only.
+
+23. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` with a concise `--profile` section including output stream and stability notes.
+
+24. Run `bb dev:test -v logseq.cli.main-test`, `bb dev:test -v logseq.cli.transport-test`, and `bb dev:test -v logseq.cli.server-test`.
+
+25. Run `bb dev:test -v logseq.cli.integration-test` and verify machine-output regression safety.
+
+26. Run `bb dev:lint-and-test` for final regression.
+
+## File-by-file change map
+
+| File | Change |
+| --- | --- |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` | Add `:profile` global option metadata. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/profile.cljs` | Add profile session lifecycle, span recording, aggregation, and render helpers. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/main.cljs` | Create profile session, wrap top-level stages, and print stderr report. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` | Record daemon lifecycle stage timings for ensure/spawn/wait phases. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs` | Record per-method invoke stage timings. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` | Add parse coverage for `--profile`. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` | Add completion coverage for new global option. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/main_test.cljs` | Add runtime profile-on and profile-off behavior tests. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` | Add stage timing coverage for daemon orchestration paths. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/transport_test.cljs` | Add invoke stage timing and aggregation tests. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` | Assert stdout stability with profile enabled. |
+| `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | Document `--profile` behavior and stderr output contract. |
+
+## Verification commands
+
+| Command | Expected result |
+| --- | --- |
+| `bb dev:test -v logseq.cli.commands-test` | Global option parse tests including `--profile` pass. |
+| `bb dev:test -v logseq.cli.completion-generator-test` | Completion output includes `--profile` for zsh and bash. |
+| `bb dev:test -v logseq.cli.main-test` | Profile output appears only when enabled. |
+| `bb dev:test -v logseq.cli.transport-test` | Per-method transport stage timing tests pass. |
+| `bb dev:test -v logseq.cli.server-test` | Daemon lifecycle stage profiling tests pass. |
+| `bb dev:test -v logseq.cli.integration-test` | Structured stdout contract remains stable with profiling enabled. |
+| `bb dev:lint-and-test` | Full lint and test suite remains green. |
+
+## Edge cases
+
+`--profile` combined with `--output json` or `--output edn` must not inject profile text into stdout.
+
+Commands that return early, such as `--help` and `--version`, should still produce valid and short profile reports when enabled.
+
+Commands failing during parse, config, or daemon startup should report only completed stages and not crash profile rendering.
+
+Commands with many thread-api calls, such as `show` and `sync download`, should aggregate repeated stage keys to avoid huge stderr output.
+
+Timing collection must remain low overhead when enabled and near-zero overhead when disabled.
+
+Concurrent async calls should keep deterministic aggregation and avoid data races in shared profile state.
+
+Detached daemon startup should still be represented from the CLI perspective even though child-process internals are not directly traced.
+
+## Rollout and compatibility notes
+
+This feature is opt-in and does not change default output behavior.
+
+Profile report output in this scope is human-readable text only.
+
+Stage key names are internal debug labels and are not a semver-stable public contract.
+
+If users request machine-parseable profile output later, add a follow-up `--profile-format` option instead of changing this first version.
+
+## Testing Details
+
+Behavioral coverage focuses on whether users can observe stage timing only when `--profile` is enabled and whether normal command output remains untouched.
+
+Integration tests must validate real command execution paths through server orchestration and transport boundaries, not only helper mocks.
+
+The most critical regression check is stdout purity for machine outputs while profiling data is emitted to stderr.
+
+## Implementation Details
+
+- Keep profile output stderr-only.
+- Add `--profile` to global option parsing and completion metadata.
+- Introduce a dedicated profile helper namespace instead of spreading ad hoc timing atoms.
+- Pass profile session through config to avoid broad action schema changes.
+- Instrument top-level `run!` stages in `main.cljs`.
+- Instrument db-worker lifecycle boundaries in `server.cljs`.
+- Instrument per-method invoke timing in `transport.cljs`.
+- Aggregate repeated stage keys with count, total, and average.
+- Preserve all existing command result formatting behavior.
+- Document option behavior in CLI docs.
+
+## Question
+
+None.
+
+---
diff --git a/docs/agent-guide/069-logseq-cli-search-subcommands.md b/docs/agent-guide/069-logseq-cli-search-subcommands.md
new file mode 100644
index 0000000000..787087cdca
--- /dev/null
+++ b/docs/agent-guide/069-logseq-cli-search-subcommands.md
@@ -0,0 +1,214 @@
+# Logseq CLI Search Verb Subcommands Implementation Plan
+
+Goal: Add `search` verb subcommands to `logseq-cli` with explicit entity scopes:
+- `search block` searches `:block/title`
+- `search page` searches `:block/name`
+- `search property` searches `:block/title` but only for Property entities
+- `search tag` searches `:block/title` but only for Tag entities
+
+Architecture: Follow the current `logseq-cli -> db-worker-node thread-api -> db_core -> logseq.cli.common.db-worker` split already used by `list` commands.
+Architecture: Keep search logic in db-worker-side helper functions and keep CLI command namespaces focused on parsing, action building, transport invocation, and output formatting.
+
+Tech Stack: ClojureScript, `babashka.cli`, `promesa`, Datascript datoms, existing `db-worker-node` HTTP `/v1/invoke` transport.
+
+Related:
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs`
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+
+## Problem statement
+
+The current main CLI command system (`src/main/logseq/cli/command/*` + `src/main/logseq/cli/commands.cljs`) has no active `search` command entries, so users cannot run first-class search commands in the current verb-subcommand architecture.
+
+At the same time, search behavior is still documented in older single-command form in `docs/cli/logseq-cli.md`, which is now out of sync with the current implementation structure.
+
+We need a new canonical `search` command group aligned with the current CLI design and db-worker-node execution model.
+
+## Current implementation baseline
+
+`logseq-cli` command parsing and dispatch are centralized in:
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs`
+
+Entity list commands already use this pattern:
+1. parse/build action in command namespace (`list.cljs`)
+2. invoke thread-api via transport (`:thread-api/cli-list-*`)
+3. execute in db worker (`db_core.cljs`)
+4. query helper in `logseq.cli.common.db-worker`
+
+db-worker-node HTTP invoke routing is generic (`/v1/invoke`) and does not require per-method route wiring for new read-only thread-api methods, as long as method names are registered via `def-thread-api` in `db_core.cljs`.
+
+## Target behavior
+
+### Command UX
+
+```text
+logseq search block <query> --graph <name>
+logseq search page <query> --graph <name>
+logseq search property <query> --graph <name>
+logseq search tag <query> --graph <name>
+```
+
+`<query>` is required positional text for all `search` subcommands.
+
+### Query semantics
+
+| Subcommand | Match field | Extra constraint |
+| --- | --- | --- |
+| `search block` | `:block/title` | none |
+| `search page` | `:block/name` | entity is a page (`:block/name` datoms) |
+| `search property` | `:block/title` | entity is tagged with `:logseq.class/Property` |
+| `search tag` | `:block/title` | entity is tagged with `:logseq.class/Tag` |
+
+### Result shape
+
+Use list-style result contract for consistency:
+- action result: `{:status :ok :data {:items [...]}}`
+- JSON/EDN keeps machine-readable item maps
+- human output uses table formatting and `Count: N`
+
+## Scope
+
+In scope:
+- Add `search` command group with four subcommands.
+- Add parsing/validation/build-action/execute paths.
+- Add db-worker read-only query helpers and thread-api methods.
+- Add human/json/edn output support for new command types.
+- Update command docs and CLI e2e coverage specs.
+
+Out of scope:
+- Re-introducing legacy `search --type ...` monolithic command shape.
+- Full-text or vector search integration.
+- Additional filters (tag filter, case-sensitive toggle, sort options) in this first pass.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and add failing tests first.
+
+1. Add parse/help tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for:
+   - `search` group help
+   - `search block/page/property/tag` parse success
+   - missing query validation
+2. Add command build/execute unit tests in new namespace:
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/search_test.cljs`
+3. Add db-worker helper tests in:
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/common/db_worker_test.cljs`
+   covering each new search function against fixture data.
+4. Add output-format tests in:
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`
+   for human/json/edn search outputs.
+5. Add command table/completion expectations in:
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs`
+6. Add/extend non-sync e2e cases:
+   - `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`
+   - `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`
+
+## Implementation plan
+
+1. Create `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/search.cljs` with four `entries`:
+   - `search block`
+   - `search page`
+   - `search property`
+   - `search tag`
+
+2. In `search.cljs`, add shared build helpers to:
+   - validate required positional query text
+   - produce action map `{:type :search-<kind> :repo ... :query ...}`
+
+3. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`:
+   - require `logseq.cli.command.search`
+   - add `search-command/entries` to command table
+   - add missing-query-text validation branch for search commands
+   - wire build-action case for `:search-block/:search-page/:search-property/:search-tag`
+   - wire execute case to call `search-command/execute-*`
+
+4. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` top-level summary groups to include `search` under Graph Inspect and Edit.
+
+5. Implement execute functions in `search.cljs` to use `transport/invoke` with new thread-api methods:
+   - `:thread-api/cli-search-blocks`
+   - `:thread-api/cli-search-pages`
+   - `:thread-api/cli-search-properties`
+   - `:thread-api/cli-search-tags`
+
+6. Extend `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` with corresponding `def-thread-api` entries that delegate to `logseq.cli.common.db-worker`.
+
+7. Extend `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs` with pure read helpers:
+   - `search-blocks`
+   - `search-pages`
+   - `search-properties`
+   - `search-tags`
+
+8. For property/tag searches, implement class filtering by reusing existing class-tag patterns used by list helpers:
+   - property: datoms on `:block/tags` with value `:logseq.class/Property`
+   - tag: datoms on `:block/tags` with value `:logseq.class/Tag`
+
+9. For block/page searches, implement substring matching over:
+   - block: `:block/title`
+   - page: `:block/name`
+   using case-insensitive normalized matching.
+
+10. Reuse list-style item shapes (id/title/timestamps/ident when available) so formatters can stay consistent.
+
+11. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` with command cases for:
+   - `:search-block`
+   - `:search-page`
+   - `:search-property`
+   - `:search-tag`
+   mapping to existing list-table formatting helpers where possible.
+
+12. Update user docs in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`:
+   - replace old monolithic search syntax with new verb subcommands
+   - document exact field semantics for each search subcommand.
+
+13. Update CLI e2e inventory/spec files to include the new search command group and at least one positive case per subcommand.
+
+14. Run focused tests and then full local suite:
+   - `bb dev:test -v logseq.cli.commands-test`
+   - `bb dev:test -v logseq.cli.command.search-test`
+   - `bb dev:test -v logseq.cli.common.db-worker-test`
+   - `bb dev:test -v logseq.cli.format-test`
+   - `bb dev:test -v logseq.cli.completion-generator-test`
+   - `bb -f cli-e2e/bb.edn test --skip-build`
+   - `bb dev:lint-and-test`
+
+## File-by-file change map
+
+| File | Change |
+| --- | --- |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/search.cljs` | New search command namespace: entries, build, execute. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` | Register search commands and dispatch/build/validation integration. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` | Include `search` in top-level help group summary. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` | Add `def-thread-api` search methods. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs` | Add search helper implementations per entity type. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` | Add human output mapping for search command types. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` | Add parser/help/validation tests for search group. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/search_test.cljs` | New unit tests for search action build + execute. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/common/db_worker_test.cljs` | Add db-level search behavior tests. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` | Add search output tests (human/json/edn). |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` | Ensure completion includes search subcommands. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` | Add non-sync e2e coverage for search subcommands. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` | Add search command/options inventory entries. |
+| `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | Update search documentation to new verb-subcommand UX. |
+
+## Edge cases
+
+- Empty or whitespace-only query should return a clear invalid-options error with hint.
+- Page search must use `:block/name` matching even when title differs.
+- Property/tag search must not return non-property/non-tag pages with similar titles.
+- Search should gracefully return empty list (`Count: 0`) when no matches.
+- Human output should remain stable for multiline titles (table alignment already handled by formatter utilities).
+
+## Rollout notes
+
+This change is additive for command surface area and aligns implementation with current CLI architecture.
+
+No db-worker-node HTTP contract changes are required, only additional thread-api methods.
+
+Docs currently mention a legacy search syntax; this plan explicitly updates docs to avoid user confusion.
+
+## Open questions
+
+None for this scope.
diff --git a/docs/agent-guide/070-logseq-cli-example-subcommand.md b/docs/agent-guide/070-logseq-cli-example-subcommand.md
new file mode 100644
index 0000000000..ecd850a8e6
--- /dev/null
+++ b/docs/agent-guide/070-logseq-cli-example-subcommand.md
@@ -0,0 +1,224 @@
+# Logseq CLI `example` Subcommand Implementation Plan
+
+Goal: Add a new `example` command group so users can ask for runnable command examples by command path or command prefix, for example:
+- `logseq example upsert page`
+- `logseq example upsert`
+- `logseq example show`
+- `logseq example search block`
+
+Phase 1 scope is limited to **all commands in the current `Graph Inspect and Edit` group**.
+
+Architecture: Keep this feature CLI-only in phase 1. Reuse command metadata already defined in `logseq-cli` command entries (`:examples`) and do not add any new `db-worker-node` invoke methods.
+
+Tech Stack: ClojureScript, `babashka.cli` dispatch table, existing `logseq.cli.command.*` entry model, existing formatter/completion/test stack.
+
+Related:
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/remove.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/query.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/search.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/completion_generator.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+
+## Problem statement
+
+Today users can see examples only via `--help` on each specific command entry.
+
+That creates two UX gaps:
+1. There is no dedicated way to request examples directly by command path.
+2. There is no single command namespace for future automation/docs workflows that want examples on demand.
+
+We need `example` as a first-class command group that resolves an existing command path and prints curated example lines.
+
+## Current baseline
+
+- Command registration is centralized in `src/main/logseq/cli/commands.cljs` with a single dispatch table built from `command/*` namespaces.
+- Command help rendering already supports per-entry `:examples` metadata through `logseq.cli.command.core/command-summary`.
+- `Graph Inspect and Edit` currently includes top-level commands:
+  - `list`
+  - `upsert`
+  - `remove`
+  - `query`
+  - `search`
+  - `show`
+- `db-worker-node` is an HTTP invoke daemon with no concept of CLI examples; this feature does not require worker protocol changes.
+
+## Phase 1 target coverage (Graph Inspect and Edit)
+
+Phase 1 must support `logseq example <target...>` for all of these command paths:
+
+| Group | Target command path |
+| --- | --- |
+| list | `list page`, `list tag`, `list property` |
+| upsert | `upsert block`, `upsert page`, `upsert tag`, `upsert property` |
+| remove | `remove block`, `remove page`, `remove tag`, `remove property` |
+| query | `query`, `query list` |
+| search | `search block`, `search page`, `search property`, `search tag` |
+| show | `show` |
+
+Additionally, phase 1 supports group-level prefix selectors for covered groups (`example list`, `example upsert`, `example remove`, `example query`, `example search`, `example show`).
+
+## Target UX
+
+### Main usage
+
+```text
+logseq example <command-or-prefix...>
+```
+
+Examples:
+
+```text
+logseq example upsert page
+logseq example upsert
+logseq example show
+logseq example search block
+```
+
+Selector semantics:
+- Exact command path: `example upsert page` returns examples only for `upsert page`.
+- Prefix command path: `example upsert` returns merged examples for all covered `upsert *` subcommands in a stable order.
+
+### Help behavior
+
+- `logseq example` shows available phase-1 example selectors.
+- `logseq example <target...> --help` shows command help for that example selector.
+- `logseq example upsert --help` and `logseq example upsert page --help` are both valid.
+
+### Output behavior
+
+- Human output: clear text block with selected target and example lines.
+- JSON/EDN output (**required**): include machine-readable fields, at minimum:
+  - `selector` (requested selector, e.g. `"upsert"` or `"upsert page"`)
+  - `matched-commands` (resolved command paths)
+  - `examples` (flattened example lines)
+  - `message` (human-readable summary string)
+
+## Design
+
+### 1) Create an `example` command namespace
+
+Add a new namespace, e.g. `src/main/logseq/cli/command/example.cljs`, responsible for:
+- declaring phase-1 target selector (Graph Inspect and Edit only)
+- generating mirrored `example` entries from existing command paths
+- validating requested target path
+- building non-worker action payloads
+- executing as pure local logic
+
+### 2) Mirror both exact paths and prefix selectors
+
+Use generated entries like:
+- exact: `example upsert page`, `example show`, `example search block`
+- prefix: `example upsert`, `example list`, `example remove`, `example query`, `example search`
+
+This keeps behavior aligned with existing dispatch/help/completion generation while also supporting grouped output (`example upsert`) without introducing ad-hoc free-form parsing.
+
+### 3) Reuse `:examples` metadata as source of truth
+
+For each supported target command entry:
+- pull `:examples` from the original entry metadata
+- for exact selectors, return only that entry's examples
+- for prefix selectors, aggregate examples from all matched covered subcommands
+
+If any matched target has missing/empty examples, return a clear CLI error (new code such as `:missing-examples`) so metadata coverage remains enforceable.
+
+### 4) Ensure metadata completeness for phase-1 targets
+
+Add/normalize `:examples` metadata on phase-1 target entries where missing (notably `query list`).
+
+### 5) Integrate into central command table
+
+In `commands.cljs`:
+- build a `base-table` from existing command namespaces
+- generate exact-selector and prefix-selector `example` entries from that base table
+- create final `table = base-table + example entries`
+
+Then wire command handling for example commands in:
+- parse/finalize branch (if needed)
+- `build-action`
+- `execute`
+
+No server ensure/invoke is needed for `example` actions.
+
+### 6) Update top-level help groups
+
+In `command/core.cljs` top-level summary groups, include `example` under `Utilities` so the command is visible in `logseq --help`.
+
+### 7) Completion support
+
+Because example commands are mirrored table entries, existing completion generation should include them automatically once table wiring is updated.
+
+## Testing plan (TDD)
+
+1. Add failing parser/help tests in `src/test/logseq/cli/commands_test.cljs`:
+   - `example` group help appears
+   - exact selectors: `example upsert page`, `example show`, `example search block`
+   - prefix selectors: `example upsert`, `example list`, `example query`
+   - unknown/uncovered selector returns expected error
+
+2. Add focused tests for new namespace (new test file):
+   - entry generation from base table
+   - phase-1 filtering only allows Graph Inspect and Edit targets
+   - missing examples metadata handling
+
+3. Extend completion tests in `src/test/logseq/cli/completion_generator_test.cljs`:
+   - example group appears
+   - mirrored example command functions are generated
+
+4. Add format assertions for required structured output:
+   - human output includes selector, matched commands, and example lines
+   - json/edn include `selector`, `matched-commands`, `examples`, and `message`
+
+5. Extend CLI e2e inventory/spec:
+   - add `example` command scope and selectors
+   - add non-sync cases for representative exact and prefix selectors (`example show`, `example upsert page`, `example upsert`, `example search block`)
+
+6. Run focused and full checks:
+   - `bb dev:test -v logseq.cli.commands-test`
+   - `bb dev:test -v logseq.cli.completion-generator-test`
+   - `bb -f cli-e2e/bb.edn test --skip-build`
+   - `bb dev:lint-and-test`
+
+## File-by-file change map
+
+| File | Change |
+| --- | --- |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/example.cljs` | New namespace: target filtering, mirrored entries, build/execute helpers. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` | Build base table, append generated example entries, wire build/execute for example actions. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` | Add `example` to top-level help groups (Utilities). |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/query.cljs` | Add missing `:examples` metadata for `query list` (if absent). |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` | Add explicit example formatting branch for human and structured (`json`/`edn`) output contract. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` | Add parse/help/build/execute coverage for `example` commands. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/example_test.cljs` | New unit tests for entry generation and target validation. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` | Assert completion output includes example command tree. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` | Add `example` command inventory coverage. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` | Add non-sync runtime cases for representative example commands. |
+| `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | Document `example` command usage and phase-1 coverage. |
+
+## db-worker-node impact
+
+No `db-worker-node` API, transport, or thread-api changes are required in phase 1.
+
+`example` is resolved and rendered entirely in CLI command metadata/action flow.
+
+## Rollout / extension plan
+
+- Phase 1 (this plan): only Graph Inspect and Edit coverage.
+- Phase 2: extend target selector to include Graph Management, Authentication, and Utilities commands.
+- Keep coverage policy explicit in tests so newly added CLI commands either:
+  - automatically receive `example` coverage, or
+  - are intentionally excluded with a documented reason.
+
+## Open questions
+
+1. For commands with sensitive placeholders, should we define a metadata convention to mark examples as redacted/non-runnable?
diff --git a/docs/agent-guide/071-logseq-cli-search-content-option.md b/docs/agent-guide/071-logseq-cli-search-content-option.md
new file mode 100644
index 0000000000..63d349f59d
--- /dev/null
+++ b/docs/agent-guide/071-logseq-cli-search-content-option.md
@@ -0,0 +1,219 @@
+# Search Content Option Migration Implementation Plan
+
+Goal: Replace positional `search` query arguments with explicit `--content` for all `search` subcommands so trailing global options are parsed reliably.
+
+Architecture: Keep query execution and `db-worker-node` transport unchanged and limit behavior change to CLI parsing, action building, help text, completion metadata, tests, and docs.
+Architecture: `logseq-cli` will continue to call `:thread-api/q` through `/v1/invoke`, so worker-side search semantics and result shape stay stable.
+
+Tech Stack: ClojureScript, `babashka.cli`, existing `logseq.cli.command.*` architecture, `db-worker-node` HTTP `/v1/invoke`, Datascript query execution.
+
+Related: Builds on `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/069-logseq-cli-search-subcommands.md`.
+Related: Touches `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+Related: Touches `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/search.cljs`.
+Related: References `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` parsing behavior.
+Related: References `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` for protocol compatibility.
+
+## Problem statement
+
+Current `search` commands use free-form positional query text.
+
+Current examples are `logseq search block task --graph my-graph` and similar forms.
+
+`parse-leading-global-opts` only extracts global options that appear before the command path.
+
+For `search`, trailing options can leak into positional args, which is why `search.cljs` currently has `extract-inline-graph` as a command-specific workaround.
+
+This workaround handles only `--graph` and `-g` and does not solve general trailing global options like `--output json`.
+
+As a result, commands like `search block something --output json` can produce unstable UX by mixing option tokens into query text or requiring option placement discipline that users do not expect.
+
+The CLI should use explicit command options for search input to avoid positional swallowing behavior.
+
+## Current baseline and compatibility constraints
+
+`search` entries are defined in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/search.cljs` with empty command-specific spec maps.
+
+`search` build logic currently receives positional `args` and joins them into `:query`.
+
+`commands.cljs` validation currently checks `(string/join " " args)` for `:missing-query-text`.
+
+Execution already uses `transport/invoke` with `:thread-api/q` and submits `[repo [query query-text]]`.
+
+`db-worker-node` invoke routing is method-generic and does not encode CLI syntax assumptions.
+
+Therefore this migration is a CLI surface change and test-doc update, not a worker protocol migration.
+
+## Target behavior
+
+### Canonical command syntax
+
+```text
+logseq search block --content <search-content> [global options]
+logseq search page --content <search-content> [global options]
+logseq search property --content <search-content> [global options]
+logseq search tag --content <search-content> [global options]
+```
+
+Examples:
+
+```text
+logseq search block --content "task" --graph my-graph --output json
+logseq search page --content "project notes" --output edn --graph my-graph
+```
+
+### Validation behavior
+
+`--content` is required for all four search subcommands.
+
+Blank content is rejected with `:missing-query-text`.
+
+Legacy positional query usage is rejected with an explicit `:invalid-options` message that instructs users to use `--content`.
+
+### Non-goals
+
+No change to search result schema.
+
+No change to Datascript query semantics.
+
+No new `db-worker-node` endpoints.
+
+No fuzzy search or ranking changes.
+
+## Testing Plan
+
+I will add unit and integration-style CLI tests that validate behavior rather than internal implementation details.
+
+I will first add failing parser tests that assert `search <scope> --content ...` succeeds and positional `search <scope> foo` fails with migration guidance.
+
+I will then add failing build-action tests that assert query text is sourced from options instead of positional args.
+
+I will add completion tests to ensure `--content` is discoverable in generated zsh/bash scripts.
+
+I will update CLI e2e cases so search coverage uses `--content` and includes a trailing global option order check.
+
+I will update docs examples and help snapshots where search syntax is listed.
+
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Implementation plan
+
+1. Add failing parse tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+
+2. Replace positional search parse expectations with `:options {:content ...}` expectations.
+
+3. Add a failing test that `search block positional` returns `:invalid-options` with migration guidance.
+
+4. Add a failing test that `search block --content alpha --output json` keeps query as `alpha` and does not consume `--output` as content.
+
+5. Add failing unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/search_test.cljs` for `build-action` using options map input.
+
+6. Add a failing unit test that blank `--content` is rejected with `:missing-query-text`.
+
+7. Update `search` command specs in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/search.cljs` to include `:content` option metadata.
+
+8. Remove positional-args normalization and inline graph extraction logic from `search.cljs`.
+
+9. Change `search-command/build-action` to read query text from `opts[:content]` and repo from resolved graph config path as already done by central parser.
+
+10. Update `commands.cljs` validation for search commands to read from `opts[:content]` and to reject unexpected positional args with a clear migration hint.
+
+11. Update `commands.cljs` call-site so search build-action is invoked with `options` instead of raw `args`.
+
+12. Keep execute path unchanged because worker invocation contract already accepts final query string only.
+
+13. Add completion assertions in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` for `--content` under search subcommands.
+
+14. Update CLI e2e inventory in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` so search options include `--content`.
+
+15. Update CLI e2e cases in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` to use `--content` and at least one trailing-global-order scenario.
+
+16. Update user docs in `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` to replace `search <scope> <query>` with `search <scope> --content <query>` across command list and examples.
+
+17. Run focused tests.
+
+18. Run broader lint and test suites.
+
+## File-by-file change map
+
+| File | Planned change |
+| --- | --- |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/search.cljs` | Add `:content` command option spec for all search subcommands and switch build-action input source to options. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` | Validate `--content`, reject legacy positional args for search, and pass options to search build-action. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/search_test.cljs` | Convert build-action tests from positional args to option-driven content and add migration failure coverage. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` | Update parse and build-action tests for search syntax and trailing global option behavior. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` | Assert completion output includes `--content` for search commands. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` | Add `--content` to search options inventory. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` | Replace search command invocations with `--content` and add option-order stability checks. |
+| `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | Update syntax, examples, and command reference text. |
+
+## db-worker-node impact
+
+No API route changes are required in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs`.
+
+No thread-api additions are required in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` for this migration.
+
+`logseq-cli` will still call `:thread-api/q` with the same query payload shape.
+
+This means rollout risk is concentrated in CLI parse and docs/test updates.
+
+## Verification commands
+
+```bash
+bb dev:test -v logseq.cli.command.search-test
+bb dev:test -v logseq.cli.commands-test
+bb dev:test -v logseq.cli.completion-generator-test
+bb -f cli-e2e/bb.edn test --skip-build
+bb dev:lint-and-test
+```
+
+Expected outcomes:
+
+All updated search parser tests pass with explicit `--content` syntax.
+
+No test still asserts positional query behavior for search.
+
+CLI e2e search cases pass with globals after command while preserving content fidelity.
+
+## Rollout notes
+
+This change intentionally breaks legacy positional search syntax to remove ambiguity and option swallowing risk.
+
+Error messaging must include a direct rewrite hint from `search <scope> <query>` to `search <scope> --content <query>`.
+
+If immediate hard cut is considered too disruptive, an optional short deprecation period can be introduced, but it should still reject option-like trailing tokens in positional mode to avoid unstable behavior.
+
+## Edge cases
+
+`--content "   "` should fail with missing query text.
+
+`--content` values containing leading dashes as literal text should remain accepted when properly quoted.
+
+`--content` should preserve multi-word queries exactly as user input after trim.
+
+Search commands should still fail with `:missing-repo` when graph resolution is unavailable.
+
+## Testing Details
+
+The tests will assert user-visible behavior for parse success, parse failure guidance, and stable interaction with trailing global options.
+
+The tests will not mock babashka.cli internals and will exercise `commands/parse-args`, `commands/build-action`, and real completion generation output strings.
+
+The e2e tests will verify actual executable command lines against a temporary graph and inspect output payload fields.
+
+## Implementation Details
+
+- Use command-specific `:content` option specs so help and completion are automatically generated.
+- Keep search execution logic and worker transport untouched to minimize regression surface.
+- Keep `:missing-query-text` code path for blank content.
+- Add explicit legacy positional rejection in central command finalization for consistent error style.
+- Update search examples in command entries to demonstrate trailing global options after `--content`.
+- Ensure docs and e2e inventory are updated together so command contract is synchronized.
+- Preserve existing table output format for search results.
+- Validate that `--graph` and `--output` can both appear after subcommands without affecting query extraction.
+- Prefer one clear migration error message over silent fallback behavior.
+
+## Question
+
+Should we enforce an immediate hard cut for positional search syntax, or keep a one-release compatibility shim with a warning and then remove it in the next release?
+
+---
diff --git a/docs/agent-guide/072-logseq-cli-graph-backup.md b/docs/agent-guide/072-logseq-cli-graph-backup.md
new file mode 100644
index 0000000000..23b23ef64c
--- /dev/null
+++ b/docs/agent-guide/072-logseq-cli-graph-backup.md
@@ -0,0 +1,297 @@
+# Graph Backup Subcommands Implementation Plan
+
+Goal: Add `graph backup` subcommands that create, list, restore, and remove backup graphs under `backup/` using SQLite backup API for backup creation.
+
+Architecture: Keep command parsing and human/json/edn output behavior in `logseq-cli`, and keep backup file generation inside `db-worker-node` through a new thread API that calls Node SQLite backup API.
+Architecture: Reuse the existing SQLite import path for restore to avoid introducing a second restore mechanism and to keep db bootstrap semantics aligned with current `graph import --type sqlite` behavior.
+
+Tech Stack: ClojureScript, `babashka.cli`, `logseq-cli` command pipeline, `db-worker-node` `/v1/invoke`, Node `node:sqlite`, filesystem operations under CLI data dir.
+
+Related: Builds on `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/006-logseq-cli-import-export.md`.
+Related: Builds on `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/037-db-worker-node-node-sqlite.md`.
+Related: Relates to `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/060-cli-graph-list-legacy-graph-dir-rename-command.md` and `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/061-graph-dir-space-preserve-canonical.md`.
+
+## Problem statement
+
+`logseq-cli` currently supports `graph export` and `graph import`, but it has no first-class backup lifecycle for graph snapshots.
+
+Current SQLite export reads `db.sqlite` bytes through `:thread-api/export-db-base64` after `wal_checkpoint`, which is functional but does not use SQLite backup API.
+
+We need backup-specific commands that treat backups as managed graph-like artifacts stored under `backup/` and independent from normal graph directories.
+
+The requested command set is `graph backup list`, `graph backup create`, `graph backup restore --src <backup-name> --dst <new-graph-name>`, and `graph backup remove`.
+
+The scope explicitly covers only `db.sqlite` and excludes `search-db.sqlite` and `client-ops-db.sqlite`.
+
+## Requested command contract
+
+| Command | Behavior | Notes |
+| --- | --- | --- |
+| `logseq graph backup list` | List all backup graphs under `<data-dir>/backup/`. | Returns metadata including name, created-at, and size-bytes. |
+| `logseq graph backup create [--name <name>]` | Create a backup graph for `--graph <name>` or current graph from config. | Must use SQLite backup API for `db.sqlite`. |
+| `logseq graph backup restore --src <backup-name> --dst <new-graph-name>` | Restore one backup graph into a new normal graph. | Destination must not already exist and must fail if it exists. |
+| `logseq graph backup remove --src <backup-name>` | Remove one backup graph directory. | Physical delete of backup entry. |
+
+`graph backup remove` uses `--src` to align with restore semantics.
+
+## Current baseline and constraints
+
+CLI graph subcommands are registered in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/graph.cljs` and routed in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+
+Graph list currently scans graph directories directly under `data-dir` using `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs`.
+
+Node runtime storage list in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs` also scans top-level directories under `data-dir`.
+
+If we add a top-level `backup/` directory, both scanners must explicitly ignore it to prevent `backup` from appearing as a normal graph.
+
+Worker-side SQLite import/export thread APIs already exist in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` and are exercised in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs`.
+
+Human formatting for graph commands is centralized in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`.
+
+Non-sync CLI e2e coverage is now shell-driven in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` and `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`.
+
+## Target architecture
+
+```text
+logseq graph backup create
+  -> logseq.cli.command.graph/execute-graph-backup-create
+    -> ensure db-worker-node for source repo
+      -> /v1/invoke :thread-api/backup-db-sqlite [repo dst-db-path]
+        -> node:sqlite backup API
+          -> <data-dir>/backup/<encoded-backup-name>/db.sqlite
+
+logseq graph backup restore --src A --dst B
+  -> resolve <data-dir>/backup/<encoded-A>/db.sqlite
+    -> reuse sqlite import flow into repo logseq_db_B
+      -> graph becomes normal top-level graph directory
+```
+
+Backup listing and removal stay CLI-side filesystem operations and do not require new worker endpoints.
+
+Backup creation is the only operation that must call SQLite backup API.
+
+## Storage and naming model
+
+Backup root path will be `<resolved-data-dir>/backup`.
+
+Each backup graph will be stored as `<resolved-data-dir>/backup/<encoded-backup-name>/db.sqlite`.
+
+Backup name is user-facing and decoded with existing graph-dir encode/decode helpers for consistency with current graph directory naming behavior.
+
+`graph backup create` will auto-generate backup name as `<source-graph>-<UTC-timestamp>`.
+
+When `--name <name>` is provided, backup name format becomes `<source-graph>-<name>-<UTC-timestamp>`.
+
+A short suffix is appended on collision.
+
+`graph backup list` returns decoded backup names with metadata including `created-at` and `size-bytes` derived from filesystem stat.
+
+No search db or client-ops db files are copied into backup entries.
+
+## Testing Plan
+
+I will follow `@test-driven-development` and implement this feature with failing tests first.
+
+I will start by adding failing CLI parse/build tests for all new commands and required options.
+
+I will add failing worker-side tests that prove backup creation returns a valid sqlite file that can be imported into another repo.
+
+I will add failing graph-directory scanner tests to ensure `backup/` is ignored by normal graph listing.
+
+I will add failing formatting tests for new human output messages and list rendering.
+
+I will add failing CLI e2e cases that run create -> list -> restore -> remove against a temp data dir.
+
+I will update CLI docs after behavior is stabilized and tests pass.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Implementation plan
+
+### Phase 1: Add failing tests for command parsing and action building.
+
+1. Add parse tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `graph backup list`, `graph backup create`, `graph backup restore`, and `graph backup remove`.
+
+2. Add parse tests asserting `graph backup create --name <name>` is accepted and passed through as optional naming input.
+
+3. Add parse tests asserting backup name generation follows `<graph>-<name>-<timestamp>` when `--name` is provided.
+
+4. Add parse tests asserting `graph backup restore` requires `--src` and `--dst`.
+
+5. Add parse tests asserting `graph backup remove` requires `--src`.
+
+6. Add build-action tests for each new command and assert resulting action `:type` values.
+
+7. Add build-action tests asserting `graph backup create` resolves source repo from `--graph` or current config graph and fails with `:missing-repo` when no graph is available.
+
+### Phase 2: Add failing tests for command execution and formatting.
+
+8. Add execution unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/graph_test.cljs` for backup list/create/restore/remove with mocked filesystem and transport calls.
+
+9. Add tests that backup create invokes new worker method `:thread-api/backup-db-sqlite` exactly once with source repo and destination sqlite path.
+
+10. Add tests that backup restore rejects missing source backup and rejects existing destination graph.
+
+11. Add tests that backup restore reuses sqlite import flow semantics and returns `new-graph? true` style success metadata.
+
+12. Add formatting tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` for human output of backup list/create/restore/remove.
+
+13. Add formatting tests for backup list metadata rendering (`name`, `created-at`, `size-bytes`) in human/json/edn output.
+
+### Phase 3: Add failing tests for graph scanners and worker backup API.
+
+14. Extend `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` so `list-graph-items` ignores top-level `backup` directory.
+
+15. Add platform node tests in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/platform_node_test.cljs` for backup API wrapper behavior.
+
+16. Add daemon-level test in `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` that calls `thread-api/backup-db-sqlite` and verifies produced sqlite file can seed another repo via existing import API.
+
+17. Add daemon-level lock test that backup API is treated as a write operation and fails for stale/non-owner lock states.
+
+### Phase 4: Implement worker-side backup API.
+
+18. Add a new thread API in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` named `:thread-api/backup-db-sqlite`.
+
+19. Implement thread API behavior to backup only main db connection for repo and return deterministic metadata `{ :path <dst> }`.
+
+20. Extend Node sqlite wrapper in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs` to expose backup capability from `DatabaseSync` through wrapped connection object.
+
+21. Guard destination writes with existing `write-guard-fn` semantics so lock ownership is enforced for backup generation.
+
+22. Ensure parent directory creation for destination file is handled before backup call.
+
+23. Add new worker method to write-method allowlist in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs`.
+
+24. Keep route protocol unchanged by continuing to use `/v1/invoke`.
+
+### Phase 5: Implement CLI backup storage helpers and command handlers.
+
+25. Add backup option specs and command entries in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/graph.cljs`, including optional `--name` for create and `--src` for remove.
+
+26. Add action builders for `:graph-backup-list`, `:graph-backup-create`, `:graph-backup-restore`, and `:graph-backup-remove`.
+
+27. Add execution functions in `graph.cljs` for list/create/restore/remove with focused responsibilities.
+
+28. Implement backup root and backup item helper functions using resolved CLI data dir and graph-dir encoding/decoding.
+
+29. Implement backup create execution to generate backup name from `<graph>-<timestamp>` or `<graph>-<name>-<timestamp>`, create target dir, and call `transport/invoke` with `:thread-api/backup-db-sqlite`.
+
+30. Implement backup restore execution to map `--src` to backup sqlite path and then reuse sqlite import workflow for destination repo.
+
+31. Implement backup remove execution to recursively remove target backup directory.
+
+32. Add validation and dispatch wiring in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` for new commands and required flags.
+
+33. Add context keys (`:src`, `:dst`, `:backup-name`) in execute result metadata for formatter use.
+
+### Phase 6: Keep normal graph listing behavior correct.
+
+34. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` directory classification to ignore `backup` root.
+
+35. Update `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs` list-graphs scanner to ignore `backup` root.
+
+36. Verify that `graph list` and `thread-api/list-db` do not show `backup` as a graph.
+
+### Phase 7: Update output, completion, docs, and e2e coverage.
+
+37. Add formatter branches in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` for backup commands with concise human lines and metadata rendering for list output.
+
+38. Update completion tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` so graph group includes backup subcommands and restore/remove flags.
+
+39. Update `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` to include new graph backup commands and options (`--name`, `--src`, `--dst`).
+
+40. Add e2e cases in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` for create/list/restore/remove flows, including one create case with `--name`.
+
+41. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` command list and examples for graph backup commands.
+
+42. Add one doc note that backup commands copy only `db.sqlite` and intentionally skip search/client-ops sqlite files.
+
+## File-by-file change map
+
+| File | Planned change |
+| --- | --- |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/graph.cljs` | Add backup command entries, option specs, action builders, filesystem helper functions, and execute logic for list/create/restore/remove. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` | Add parser validation for backup flags, build-action routing, execute dispatch, and context key propagation. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` | Add human output formatting for backup list/create/restore/remove and ensure machine outputs remain stable. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` | Ignore top-level `backup` directory when listing normal graphs. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` | Add `:thread-api/backup-db-sqlite` implementation for main sqlite db backup generation. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs` | Expose Node sqlite backup capability and ensure list-graphs ignores backup root. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs` | Register backup API as write method for lock-owner enforcement. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` | Add parse/build/execute tests for backup commands and required option errors. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/graph_test.cljs` | Add unit tests for backup command execution behaviors and transport invocation contract. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` | Add human/json/edn formatting tests for backup command outputs. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/server_test.cljs` | Add scanner tests proving `backup` root is excluded from graph list. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/platform_node_test.cljs` | Add unit tests for backup API wrapper behavior and destination file creation. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/frontend/worker/db_worker_node_test.cljs` | Add integration test covering backup API correctness and lock enforcement behavior. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` | Assert completion includes graph backup subcommands and options. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` | Include graph backup command and option coverage inventory entries. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` | Add end-to-end graph backup lifecycle cases. |
+| `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | Document backup commands and db.sqlite-only scope note. |
+
+## Edge cases and behavior guarantees
+
+Backup names with spaces and slashes are supported through existing graph-dir encode/decode helpers.
+
+Optional `--name` values with spaces and symbols are supported and encoded through the same helpers.
+
+Backup creation must fail clearly when source graph does not exist or backup target path cannot be created.
+
+Backup restore must fail clearly when source backup does not exist.
+
+Backup restore must fail clearly when destination graph already exists.
+
+Backup remove must fail clearly when source backup does not exist.
+
+`graph list` must not include backup entries.
+
+`graph backup list` metadata fields (`created-at`, `size-bytes`) must remain present and stable even when sorting order changes.
+
+Backup API must preserve binary integrity for large sqlite files and not truncate output.
+
+Backup operations must respect lock ownership semantics already enforced for write methods.
+
+## Verification commands
+
+```bash
+bb dev:test -v logseq.cli.command.graph-test
+bb dev:test -v logseq.cli.commands-test
+bb dev:test -v logseq.cli.format-test
+bb dev:test -v logseq.cli.server-test
+bb dev:test -v frontend.worker.platform-node-test
+bb dev:test -v frontend.worker.db-worker-node-test/db-worker-node-import-db-base64
+bb dev:test -v frontend.worker.db-worker-node-test/db-worker-node-write-mutation-fails-for-non-owner-pid
+bb -f cli-e2e/bb.edn test --skip-build
+bb dev:lint-and-test
+```
+
+Expected results are passing tests for parser behavior, backup API correctness, lock safety, graph-list isolation, and CLI end-to-end backup lifecycle.
+
+## Testing Details
+
+I will add tests that validate end-user behavior of backup command parsing, execution, output, and restore correctness.
+
+I will assert backup file validity by actually importing the generated sqlite backup into a new graph and querying known content.
+
+I will assert list isolation behavior by verifying backup root never appears in normal graph listings.
+
+I will keep lock-related assertions behavior-driven by invoking through daemon HTTP APIs rather than testing private internals.
+
+## Implementation Details
+
+- Add `graph backup` command entries under existing graph command group instead of creating a new top-level command.
+- Use existing global `--graph` resolution as backup source selector for `graph backup create`.
+- Introduce optional `--name` for create, `--src` and `--dst` for restore, and `--src` for remove.
+- Store backups under `<data-dir>/backup/<encoded-backup-name>/db.sqlite`.
+- Generate backup names as `<graph>-<timestamp>` by default and `<graph>-<name>-<timestamp>` when `--name` is provided, with collision suffix when needed.
+- Use a new worker thread API to call Node SQLite backup API for backup creation.
+- Reuse existing sqlite import flow for restore to keep db bootstrap behavior consistent.
+- Mark worker backup method as write operation so lock ownership checks remain enforced.
+- Ignore top-level `backup` directory in both CLI and node platform graph scanners.
+- Return backup list metadata including `created-at` and `size-bytes` in machine output and render it in human output.
+- Update completion, docs, and e2e specs together so command contract is synchronized.
+
+## Question
+
+Do we reserve the top-level graph name `backup` going forward, or do we need a migration strategy for users who already have a normal graph named `backup` in the same data dir?
+
+---
diff --git a/docs/agent-guide/073-logseq-cli-debug-command.md b/docs/agent-guide/073-logseq-cli-debug-command.md
new file mode 100644
index 0000000000..c7e8fbdf6d
--- /dev/null
+++ b/docs/agent-guide/073-logseq-cli-debug-command.md
@@ -0,0 +1,258 @@
+# Logseq CLI `debug` Command Implementation Plan
+
+Goal: Add a new `debug` command group with `debug pull` for low-level Datascript entity inspection via `db-worker-node`.
+
+Goal: `debug pull` must support `--graph <name>` or default to current graph resolution already used by existing commands.
+
+Goal: In global help (`logseq --help`), show `debug` under `Utilities` and do not show `debug` subcommands (same top-level-only behavior as `example`).
+
+Architecture: Keep command parsing, validation, and output behavior in `logseq-cli`, and reuse existing `db-worker-node` invoke API `:thread-api/pull` with selector `[*]`.
+
+Architecture: Avoid adding new worker thread APIs unless we discover a hard blocker; current worker already exposes `:thread-api/pull` and supports lookup refs.
+
+Tech Stack: ClojureScript, `babashka.cli` dispatch table, existing command pipeline in `logseq.cli.commands` (`parse-args -> build-action -> execute`), and existing CLI e2e spec harness.
+
+Related:
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/id.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/transport.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`
+
+## Problem statement
+
+Today we have user-facing inspection commands (`show`, `query`), but no direct debug command that exposes a raw `pull` for a single entity selector path.
+
+For debugging schema/data issues, we need a predictable command that can fetch one entity using either db id, uuid, or ident and return raw entity data.
+
+The requested command is:
+
+```text
+logseq debug pull --id <db-id>
+logseq debug pull --uuid <uuid>
+logseq debug pull --ident <db-ident>
+```
+
+with selector fixed to `[*]` and data source being the current graph DB served by `db-worker-node`.
+
+## Requested behavior contract
+
+| Area | Requirement |
+| --- | --- |
+| Command shape | Add top-level `debug` group with subcommand `pull`. |
+| Graph selection | Accept `--graph` globally; if omitted, use current graph resolution (same as existing commands using `pick-graph`). |
+| Target selector | `debug pull` accepts exactly one of `--id`, `--uuid`, `--ident`. |
+| Pull behavior | Execute `:thread-api/pull` with selector `[*]` and resolved lookup value. |
+| Global help | `logseq --help` shows `debug` in `Utilities` and does not list `debug pull` there. |
+| Group help | `logseq debug` and `logseq debug --help` show `debug pull` as subcommand. |
+
+## Current baseline
+
+- Top-level help grouping is implemented in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` with `Utilities` currently configured as top-level-only and already hiding `example` subcommands.
+- Graph fallback is implemented centrally via `logseq.cli.command.core/pick-graph` and is already used in `build-action` for graph-scoped commands.
+- `db-worker-node` already provides `:thread-api/pull` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`:
+  - accepts `(repo selector id)`
+  - supports integer ids and lookup refs (e.g. `[:db/ident kw]`, `[:block/uuid uuid]`)
+- Existing command modules (`show`, `query`) already demonstrate ensure-server + invoke flow and can be reused as implementation patterns.
+
+Conclusion: this feature should be mostly CLI-side wiring; worker protocol changes are likely unnecessary.
+
+## CLI design proposal
+
+### 1) New command namespace
+
+Add `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/debug.cljs`.
+
+Planned entry:
+- `debug pull` (`:debug-pull`)
+
+Planned command options:
+- `--id` (db id)
+- `--uuid` (UUID string)
+- `--ident` (strict EDN keyword string, e.g. `:logseq.class/Tag`)
+
+Global options (`--graph`, `--output`, etc.) continue to come from `command-entry` merged global spec.
+
+### 2) Selector normalization
+
+`debug pull` resolves exactly one lookup target:
+- `--id` -> numeric entity id
+- `--uuid` -> lookup ref `[:block/uuid <uuid>]`
+- `--ident` -> lookup ref `[:db/ident <keyword>]`
+
+Validation rules:
+- exactly one of `--id`, `--uuid`, `--ident` is required
+- reject multiple selectors with clear invalid-options message
+- reject invalid uuid / invalid id / invalid ident formats
+- `--ident` accepts only strict EDN keyword syntax with leading `:`
+
+### 3) Action model
+
+`build-action` output shape:
+
+```clojure
+{:type :debug-pull
+ :repo <resolved repo>
+ :lookup <id-or-lookup-ref>
+ :selector '[*]}
+```
+
+`repo` resolution should reuse existing command pipeline behavior:
+- `--graph` first
+- then config current graph
+- then repo fallback from config
+
+### 4) Execute model
+
+Execution pattern:
+1. ensure server for repo (`cli-server/ensure-server!`)
+2. invoke worker `:thread-api/pull` with `[repo selector lookup]`
+3. return structured data payload (include selector metadata for traceability)
+
+Suggested success payload:
+
+```clojure
+{:entity <pulled-entity>
+ :lookup <normalized lookup>
+ :selector '[*]}
+```
+
+For missing entity, return a clear typed error (e.g. `:entity-not-found`) instead of silently returning `nil`.
+
+## Global help behavior plan
+
+Update `top-level-summary` groups in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs`:
+
+- add `debug` to `Utilities` command set
+- keep `:top-level-only? true` for `Utilities`
+- add `desc-overrides` entry for `debug` so top-level help renders stable one-line description (instead of inheriting from `debug pull` text)
+
+Expected top-level help effect:
+- shows `debug`
+- does not show `debug pull`
+- remains consistent with current `example` visibility behavior
+
+## Testing Plan (TDD)
+
+I will follow `@test-driven-development` and write failing tests first.
+
+### Phase 1: Parser and help RED tests
+
+1. Extend `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`:
+   - top-level help includes `debug`
+   - top-level help does **not** include `debug pull`
+   - `Utilities` section still lists `example` and `completion`
+2. Add group-help tests:
+   - `parse-args ["debug"]` returns help summary containing `debug pull`
+3. Add parse success tests:
+   - `debug pull --id 1`
+   - `debug pull --uuid <uuid>`
+   - `debug pull --ident :logseq.class/Tag`
+4. Add parse failure tests:
+   - no selector
+   - multiple selectors
+   - malformed id / uuid / ident
+
+### Phase 2: Action and execute RED tests
+
+5. Add build-action tests in `commands_test.cljs`:
+   - uses `--graph` when provided
+   - falls back to current graph from config when `--graph` omitted
+   - returns missing-repo when neither explicit nor current graph exists
+6. Add execute tests (new file suggested: `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/debug_test.cljs`):
+   - verifies invoke contract `:thread-api/pull` with selector `[*]`
+   - verifies id/uuid/ident normalization to lookup argument
+   - verifies entity-not-found behavior
+
+### Phase 3: GREEN implementation
+
+7. Implement new namespace `command/debug.cljs` with entries + build + execute.
+8. Wire into `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`:
+   - include `debug-command/entries` in base table
+   - finalize-command validation branch for selector constraints
+   - build-action case `:debug-pull`
+   - execute case `:debug-pull`
+9. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` top-level group config for `Utilities` to include `debug` (hidden subcommands at global help).
+
+### Phase 4: Completion and e2e coverage
+
+10. Update completion tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs`:
+    - includes `debug` group and `pull` subcommand completion.
+11. Update inventory in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`:
+    - add `:debug` scope with command `debug pull`
+    - add options `--id`, `--uuid`, `--ident`
+12. Add e2e cases in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`:
+    - id-based pull
+    - uuid-based pull
+    - ident-based pull
+    - one case proving current-graph fallback (no `--graph` on debug call after config/graph setup)
+
+### Phase 5: Formatter and docs
+
+13. Add explicit human formatting branch in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` for `:debug-pull`:
+    - pretty-print entity as EDN for readable debugging output
+    - include compact header context (selector and lookup)
+14. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` with `debug pull` usage and examples.
+
+## File-by-file change map
+
+| File | Planned change |
+| --- | --- |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/debug.cljs` | New command namespace (`entries`, validation helpers, `build-action`, `execute-debug-pull`). |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` | Register debug entries; add parse/finalize validation, build-action route, and execute dispatch. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` | Add `debug` under `Utilities` top-level-only group and description override to hide subcommands in global help. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs` | Add explicit human formatter for debug output with pretty-printed EDN entity payload. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` | Add parser/help/build coverage for debug command and utilities help visibility rules. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/debug_test.cljs` | New execute/normalization tests for debug pull invoke contract. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` | Add completion coverage for `debug pull`. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` | Add debug scope and option coverage metadata. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` | Add non-sync end-to-end cases for id/uuid/ident and graph fallback behavior. |
+| `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | Document `debug pull` usage and selector examples. |
+
+## db-worker-node impact
+
+No new worker API is required for the requested scope.
+
+Reason:
+- `:thread-api/pull` already exists and already performs Datascript `d/pull`.
+- selector `[*]` is legal and directly maps to requested debug behavior.
+- lookup refs for `:db/ident` and `:block/uuid` are already supported by Datascript pull semantics.
+
+Potential worker-side follow-up is only needed if we later want:
+- multi-entity pull
+- custom selectors from CLI input
+- stricter nil/not-found error signaling at worker layer
+
+## Edge cases to explicitly cover
+
+| Scenario | Expected behavior |
+| --- | --- |
+| `debug pull` with no selector flags | Error: exactly one selector required. |
+| `debug pull --id 1 --uuid ...` | Error: only one of `--id`, `--uuid`, `--ident` allowed. |
+| `debug pull --ident logseq.class/Tag` (without leading `:`) | Error with explicit invalid ident message (`--ident` requires strict EDN keyword). |
+| `debug pull` without `--graph` and no current graph configured | Error: missing repo/graph. |
+| entity not found | Return typed error (`:entity-not-found`) instead of ambiguous success with nil. |
+| `logseq --help` | Shows `debug` under Utilities, not `debug pull`. |
+
+## Verification commands
+
+```bash
+bb dev:test -v logseq.cli.commands-test
+bb dev:test -v logseq.cli.command.debug-test
+bb dev:test -v logseq.cli.completion-generator-test
+bb -f cli-e2e/bb.edn test --skip-build
+bb dev:lint-and-test
+```
+
+Expected outcome: parser/help behavior, invoke contract, completion, and e2e coverage all green.
+
+## Resolved decisions
+
+1. `--ident` accepts only strict EDN keyword input.
+2. Not-found is a hard error (`:entity-not-found`).
+3. Human output for `debug pull` uses pretty-printed EDN.
\ No newline at end of file
diff --git a/docs/agent-guide/074-db-worker-node-invoke-main-thread-refactor.md b/docs/agent-guide/074-db-worker-node-invoke-main-thread-refactor.md
new file mode 100644
index 0000000000..d9a7952200
--- /dev/null
+++ b/docs/agent-guide/074-db-worker-node-invoke-main-thread-refactor.md
@@ -0,0 +1,318 @@
+# db-worker-node `invoke-main-thread` Removal and Worker-Local Refactor Plan
+
+Goal: Remove all production `invoke-main-thread` usage from db worker logic and make `db-worker-node` fully self-contained for API execution.
+
+Goal: Refactor each current main-thread API dependency into db-worker-owned implementations that work in both Node and Browser runtimes.
+
+Goal: For UI-dependent interactions, replace direct worker->main-thread invocation with a request/response protocol where worker sends `postMessage`, and main thread actively calls db-worker thread APIs to respond.
+
+Goal: Enforce request isolation with `request-id` across concurrent UI requests.
+
+Architecture: Keep runtime-specific logic behind worker platform adapters (`frontend.worker.platform`, `frontend.worker.platform.node`, `frontend.worker.platform.browser`) and keep shared logic runtime-agnostic.
+
+Related:
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/state.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/ui_request.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/assets.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/auth.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/assets.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/e2ee.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/user.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/persist_db/browser.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/worker.cljs`
+
+## Problem statement
+
+`db-worker-node` currently sets a main-thread stub that always rejects (`main-thread is not available in db-worker-node`).
+
+Historically, shared worker modules called `worker-state/<invoke-main-thread` for auth refresh, asset upload/download metadata, E2EE key/password operations, and search-idle checks.
+
+That created runtime divergence:
+- Browser worker could call main-thread APIs through Comlink.
+- Node daemon could not, so behavior depended on fallback code quality or failed outright.
+
+Target state: db worker owns all non-UI logic and uses only explicit message protocol for UI interactions.
+
+## Progress snapshot (current)
+
+### Completed migrations
+
+- Auth refresh dependency on `:thread-api/ensure-id&access-token` was removed from worker sync auth path.
+- Asset upload/download/metadata dependencies on main-thread thread APIs were removed and replaced by worker-local implementations through platform adapters.
+- Search idle dependency on `:thread-api/input-idle?` was removed from `db_core`; it now uses a **main-thread push + worker TTL cache** model:
+  - main thread periodically pushes `:thread-atom/search-input-idle-status` with `{repo {:idle? ... :ts ...}}`
+  - worker consumes that state with a TTL window and falls back to non-blocking behavior when state is missing/stale.
+- E2EE UI-interaction path in `frontend.worker.sync.crypt` was migrated to a worker-owned request manager:
+  - worker now emits `:db-worker/ui-request` with `request-id`
+  - main thread responds via `:thread-api/resolve-ui-request` / `:thread-api/reject-ui-request`
+  - worker crypt flow no longer directly calls `worker-state/<invoke-main-thread`
+  - pending UI requests are cancelled on close/shutdown paths (`close-db`, `db-sync-close-db`, `unsafe-unlink-db`, browser `stop-db-worker!`)
+
+### Remaining direct `invoke-main-thread` production usages
+
+- None in production worker modules.
+- `frontend.worker.state/<invoke-main-thread` remains as legacy infrastructure, but has no active production call sites.
+
+## Historical inventory of `invoke-main-thread` dependencies (baseline before migration)
+
+| Call site | Current main-thread API | Category | Runtime risk in `db-worker-node` |
+| --- | --- | --- | --- |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/auth.cljs` (`<resolve-ws-token`) | `:thread-api/ensure-id&access-token` | Auth/token refresh | Token refresh path may fail without worker-local refresh |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/assets.cljs` (`upload-remote-asset!`) | `:thread-api/rtc-upload-asset` | Asset I/O + network | Upload path depends on main-thread asset code |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/assets.cljs` (`download-remote-asset!`) | `:thread-api/rtc-download-asset` | Asset I/O + network | Download path depends on main-thread asset code |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/assets.cljs` (`request-asset-download!`) | `:thread-api/get-asset-file-metadata` | Asset metadata | Existence/checksum check depends on main thread |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` (`<native-save-password-text!`) | `:thread-api/native-save-e2ee-password` | Password persistence | Native keychain path unavailable in node daemon |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` (`<native-read-password-text`) | `:thread-api/native-get-e2ee-password` | Password persistence | Same |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` (`<native-delete-password-text!`) | `:thread-api/native-delete-e2ee-password` | Password persistence | Same |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` (`<generate-and-upload-user-rsa-key-pair!`) | `:thread-api/request-e2ee-password` | UI prompt | Requires explicit UI handshake |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` (`<decrypt-private-key`) | `:thread-api/decrypt-user-e2ee-private-key` | UI/session-dependent decrypt | Must be worker-local + UI fallback protocol |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/crypt.cljs` (`:thread-api/init-user-rsa-key-pair`) | `:thread-api/request-e2ee-password` | UI prompt | Same as above |
+| `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` (`<wait-for-search-index-idle!`) | `:thread-api/input-idle?` | UI state query | Tight loop currently requires main-thread sync point |
+
+## Design constraints and invariants
+
+1. `db-worker-node` must never depend on main-thread APIs.
+2. Shared worker code must run in both Node and Browser runtimes.
+3. UI interactions must use explicit async protocol with `request-id` correlation.
+4. Error shapes must remain stable (or be intentionally versioned) across transport layers.
+5. Migration should be incremental with behavior-compatible phases.
+
+## Target architecture
+
+### 1) Remove worker-side direct main-thread invocation from business paths
+
+Keep `frontend.worker.state/<invoke-main-thread` only as legacy infrastructure for browser compatibility during migration, then shrink/remove usage in production worker modules.
+
+Acceptance target after migration:
+- No production call sites to `<invoke-main-thread` outside temporary migration guards.
+- `db-worker-node` main-thread stub remains reject-only and never hit in normal flows.
+
+### 2) Move main-thread business logic into worker-owned modules
+
+#### Auth refresh (`:thread-api/ensure-id&access-token`)
+- Move token refresh implementation into worker sync auth module.
+- Reuse current refresh token and auth state from worker state (`:auth/id-token`, `:auth/refresh-token`) that is already synchronized.
+- Keep main thread responsible only for UI/session orchestration, not worker internal token lifecycle.
+
+#### Asset operations (`:thread-api/rtc-upload-asset`, `:thread-api/rtc-download-asset`, `:thread-api/get-asset-file-metadata`)
+- Introduce worker-side asset I/O + transfer module (shared, runtime-agnostic).
+- Move file read/write/checksum/upload/download logic from main-thread handler into worker with platform adapter calls.
+- Keep progress events emitted from worker via existing broadcast channel.
+
+#### E2EE password storage (`native-save/get/delete`)
+- Replace main-thread keychain dependency with worker platform capabilities.
+- Add explicit storage abstraction in platform adapters for encrypted password persistence.
+- Keep existing encrypted payload format unchanged where possible.
+
+#### Private key decrypt (`:thread-api/decrypt-user-e2ee-private-key`)
+- Make worker-local decrypt path primary.
+- Request UI password only when worker-local credentials are unavailable.
+
+### 3) UI request/response protocol (request-id isolated)
+
+For UI-dependent operations, worker should not call main-thread thread APIs directly.
+
+Use this flow:
+
+```text
+1) Worker needs UI input
+   -> postMessage event to main thread
+      {:type :db-worker/ui-request
+       :request-id <uuid-v4>
+       :action <keyword>
+       :payload <map>
+       :timeout-ms 60000}
+
+2) Main thread handles UI action (prompt/dialog/user interaction)
+
+3) Main thread actively calls db-worker thread API:
+   :thread-api/resolve-ui-request [request-id result]
+   or
+   :thread-api/reject-ui-request [request-id error]
+
+4) Worker resolves or rejects the pending promise by request-id.
+```
+
+Required worker internals:
+- `*ui-requests-in-flight` map keyed by `request-id`.
+- `request-id` is generated as UUID v4.
+- default request timeout is `60000ms` (60s), with optional per-action override.
+- timeout handling + cleanup.
+- duplicate/late response protection.
+- cancellation support for graph switch or worker shutdown.
+
+Required acceptance:
+- concurrent requests do not cross-resolve.
+- timed-out request cannot be resolved later.
+- all terminal states remove map entries.
+
+#### UI interaction contract: headless vs interactive
+
+The implementation uses two explicit modes instead of implicit fallback behavior.
+
+- **Headless mode (default for `db-worker-node`/CLI):**
+  - If an operation requires UI input and no interactive channel is available, return a typed error.
+  - Error code should be stable and machine-readable: `:ui-interaction-required`.
+  - Error payload should include at least `:action` and optional `:hint` (for example, configured password fallback).
+
+- **Interactive mode (browser app):**
+  - Worker emits `:db-worker/ui-request` with `request-id`.
+  - Main thread performs UI interaction and actively calls worker thread APIs to resolve or reject the request.
+  - Worker resumes flow only when matching `request-id` is resolved.
+
+This dual contract keeps headless behavior deterministic while preserving async interactive UX in browser runtime.
+
+### 4) Platform abstraction updates for Node/Browser parity
+
+Extend `frontend.worker.platform` contract with only capabilities required by migrated APIs.
+
+Likely additions:
+- secure encrypted secret storage (or equivalent persisted encrypted blob)
+- binary asset read/write/stat helpers
+- HTTP transfer helpers with progress hooks (if not already available in shared runtime)
+- monotonic clock/timer helpers for timeout handling
+
+Node implementation: `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/node.cljs`.
+
+Browser implementation: `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/platform/browser.cljs`.
+
+## Per-API migration matrix
+
+| Legacy main-thread API | New worker-owned implementation | UI request protocol needed? | Node/Browser notes |
+| --- | --- | --- | --- |
+| `:thread-api/ensure-id&access-token` | Worker-local refresh function in sync auth module | No | Must work without UI in node daemon |
+| `:thread-api/rtc-upload-asset` | Worker asset upload API | No | Use platform file + HTTP adapters |
+| `:thread-api/rtc-download-asset` | Worker asset download API | No | Same |
+| `:thread-api/get-asset-file-metadata` | Worker metadata/checksum API | No | Same |
+| `:thread-api/native-save-e2ee-password` | Worker secure persistence API | No | Use platform adapter implementations |
+| `:thread-api/native-get-e2ee-password` | Worker secure read API | No | Same |
+| `:thread-api/native-delete-e2ee-password` | Worker secure delete API | No | Same |
+| `:thread-api/request-e2ee-password` | Worker emits UI request and waits on `resolve-ui-request` | Yes | Node can return typed `:ui-interaction-required` unless configured fallback exists |
+| `:thread-api/decrypt-user-e2ee-private-key` | Worker-local decrypt + optional UI request for password | Yes (fallback) | Keep headless path for node |
+| `:thread-api/input-idle?` | Main thread pushes idle-state updates; worker consumes a local TTL cache for indexing decisions | Yes | Push+TTL is the default model to avoid high-frequency request storms |
+
+## Implementation phases
+
+### Phase 0: Safety rails and observability
+
+1. Add explicit metric/log points for any call to `<invoke-main-thread` in worker code.
+2. Add request-id propagation fields to db-worker-node invoke/event logs for traceability.
+3. Add temporary feature flag to switch between old and new path per migrated domain.
+
+### Phase 1: Non-UI API migration
+
+1. Migrate auth refresh from main thread to worker.
+2. Migrate asset metadata/upload/download to worker module + platform adapters.
+3. Migrate E2EE encrypted password persistence to worker platform APIs.
+4. Keep compatibility shims temporarily, but default to worker-local path.
+
+Exit criteria:
+- No non-UI flow depends on main thread.
+- CLI and db-worker-node sync paths pass regression tests.
+
+### Phase 2: UI request protocol
+
+1. Introduce generic worker UI request manager (`request-id`, timeout, cleanup).
+2. Add worker thread APIs for resolving/rejecting UI requests.
+3. Add main-thread handler wiring in `frontend.handler.worker` for `:db-worker/ui-request` events.
+4. Route E2EE prompt/decrypt UI-dependent flows through new protocol.
+
+Exit criteria:
+- concurrent password requests are isolated by `request-id`.
+- graph switch/shutdown does not leak pending requests.
+
+### Phase 3: Search idle and remaining UI-state dependencies
+
+1. Replace `:thread-api/input-idle?` direct invocation with **main-thread push + worker TTL cache** model.
+2. Define TTL window and stale-state behavior for indexing loops.
+3. Validate search indexing throughput and UI responsiveness.
+
+Exit criteria:
+- no direct worker->main-thread API invocation in search flow.
+- push+TTL idle-state model is active and covered by tests.
+- no regression in search build behavior.
+
+### Phase 4: Remove legacy dependencies
+
+1. Remove remaining production usages of `worker-state/<invoke-main-thread` in worker sync/core modules.
+2. Update `non-repo-methods` and API inventory if method ownership changed.
+3. Keep browser compatibility wrappers only if still required by bootstrapping internals.
+
+Final exit criteria:
+- `invoke-main-thread` usage in production code is zero (or explicitly limited to bootstrap-only internals with no business logic).
+- `db-worker-node` full API suite works without main-thread API dependencies.
+
+## Tests and verification plan
+
+### Unit tests
+
+- Worker auth tests: token refresh in worker without main-thread stubs.
+- Worker asset tests: metadata/upload/download via worker module and platform mocks.
+- Worker crypt tests: password storage/decrypt paths do not call main thread.
+- UI request manager tests: request-id isolation, timeout, duplicate response rejection.
+
+### Integration tests
+
+- Browser flow: UI request roundtrip (`postMessage` -> main thread -> `resolve-ui-request`).
+- Node flow: same API paths run headless and return typed errors when UI is mandatory.
+- Search indexing flow: idle-state protocol behavior under repeated checks.
+
+### Regression checks
+
+- `eca__grep` gate: no production `worker-state/<invoke-main-thread` call sites in migrated modules.
+- `db-worker-node` daemon invoke smoke tests for sync + e2ee + asset paths.
+- Existing CLI and worker tests remain green.
+
+## Risks and mitigations
+
+1. **E2EE flow regressions**
+   - Mitigation: migrate with feature flags and run dedicated crypt regression suite first.
+
+2. **Asset transfer behavior drift**
+   - Mitigation: keep payload format/checksum semantics unchanged during extraction.
+
+3. **Request map leaks / stale requests**
+   - Mitigation: enforce timeout + shutdown cleanup + finalizer assertions.
+
+4. **Search performance impact**
+   - Mitigation: add request throttling and local TTL cache for idle-state checks.
+
+5. **Protocol mismatch between main thread and worker**
+   - Mitigation: define strict message schema and validate fields at both ends.
+
+## Acceptance criteria
+
+1. Every current production `invoke-main-thread` dependency listed in this plan has a worker-owned replacement.
+2. `db-worker-node` runs without any required main-thread API bridge.
+3. UI-dependent flows use `postMessage` request + main-thread active callback to worker thread API.
+4. `request-id` enforces isolation for concurrent UI requests.
+5. In headless mode, UI-required operations return typed error `:ui-interaction-required` with stable machine-readable payload.
+6. Node and Browser runtimes both pass targeted tests for migrated paths.
+7. No unresolved pending UI requests remain after graph close or worker shutdown.
+
+## Suggested execution order
+
+1. Auth + non-UI crypt storage.
+2. Asset API migration.
+3. Generic UI request protocol.
+4. E2EE prompt/decrypt migration.
+5. Search idle-state migration.
+6. Legacy call-site removal and cleanup.
+
+## Confirmed decisions
+
+1. `request-id` format: UUID v4.
+2. Default UI request timeout: 60s (`60000ms`), optional per-action override.
+3. Search idle state model: main-thread push + worker TTL cache.
+4. Headless behavior: UI-required operations return typed error `:ui-interaction-required`.
+5. Execution order: follow the phased order defined in this document.
+
+## Notes
+
+This plan intentionally prioritizes behavior parity and migration safety over immediate deep refactor of all related modules.
+
+The protocol and platform abstraction should be stabilized first; broad code movement should follow once test harnesses are in place.
diff --git a/docs/agent-guide/075-sync-e2ee-password-persistence.md b/docs/agent-guide/075-sync-e2ee-password-persistence.md
new file mode 100644
index 0000000000..2d42f507f3
--- /dev/null
+++ b/docs/agent-guide/075-sync-e2ee-password-persistence.md
@@ -0,0 +1,249 @@
+# Sync E2EE Password Persistence Implementation Plan
+
+Goal: Persist and consume sync E2EE passwords only as refresh-token-encrypted data across CLI, desktop app, web app, and db-worker-node.
+
+Architecture: Keep password encryption and verification logic in `frontend.worker.sync.crypt` as the single source of truth.
+
+Architecture: Use runtime-specific persistence behind worker platform boundaries, with IndexedDB-backed secret storage on browser runtime and `<data-dir>/e2ee-password` file storage on node runtime.
+
+Architecture: Route CLI `sync start --e2ee-password` and `sync download --e2ee-password`, plus desktop UI password input, through the same worker-side validation and persistence flow.
+
+Tech Stack: ClojureScript, Promesa, db-worker platform adapters, babashka.cli command parsing, Electron renderer-to-worker UI request protocol.
+
+Related: Builds on `docs/agent-guide/047-logseq-cli-sync-command.md`, `docs/agent-guide/055-logseq-cli-login-logout.md`, and `docs/agent-guide/074-db-worker-node-invoke-main-thread-refactor.md`.
+
+## Problem statement
+
+Current behavior is inconsistent across runtimes and command paths.
+
+`frontend.worker.sync.crypt/<save-e2ee-password` encrypts password text by `refresh-token`, but password sourcing and persistence locations differ by flow.
+
+CLI still accepts and persists plain `:e2ee-password` in `cli.edn`, which conflicts with secure persistence requirements.
+
+Browser runtime currently persists non-native password file via OPFS (`e2ee-password`) instead of IndexedDB.
+
+CLI headless fallback currently includes config password and can return `:ui-interaction-required` rather than a direct `e2ee-password not found` outcome.
+
+Desktop interactive flow can decrypt via UI path, but the verify-and-persist behavior is not defined as an explicit shared worker API reused by CLI.
+
+The table below summarizes current state and required change.
+
+| Area | Current state | Required state |
+| --- | --- | --- |
+| CLI config | `sync config set|get|unset` accepts `e2ee-password` and stores in `cli.edn`. | Deprecate `:e2ee-password` in `cli.edn` and stop using config as password source. |
+| Password crypto key | Worker encrypt/decrypt helpers already accept `refresh-token`, but CLI fallback still depends on config and auth-token candidates. | Use refresh-token as the only password crypto key source for persisted password. |
+| Browser persistence | Non-native flow reads/writes OPFS file `e2ee-password`. | Store encrypted password in IndexedDB. |
+| Node persistence | Non-native flow reads/writes `<data-dir>/e2ee-password`. | Keep `<data-dir>/e2ee-password` as canonical node location. |
+| CLI UX | `sync start/status` does not provide a dedicated missing-password UX contract. | If password is unavailable, `sync start/status` should report `e2ee-password` not found with actionable hint. |
+| CLI input path | No `sync start --e2ee-password` or `sync download --e2ee-password` option. | Add `--e2ee-password` to `sync start` and `sync download`, verify it, encrypt it, then persist it. |
+| Desktop UI reuse | UI decrypt path exists, but shared CLI-equivalent verify/persist contract is not explicit. | Desktop missing-password interaction should call the same worker verify-and-persist flow as CLI. |
+
+## Target architecture
+
+```text
+CLI / Desktop UI / Web runtime
+        |
+        | password input (optional)
+        v
+frontend.worker.sync.crypt
+  - verify password against user encrypted private key
+  - encrypt/decrypt persisted password with refresh-token
+  - return typed missing-password errors
+        |
+        +--> Browser runtime: IndexedDB secret slot
+        |
+        +--> Node runtime: <data-dir>/e2ee-password
+```
+
+## Testing Plan
+
+I will add worker unit tests in `src/test/frontend/worker/sync/crypt_test.cljs` for runtime-specific storage routing, refresh-token-only encryption key usage, and typed missing-password behavior in CLI-headless mode.
+
+I will add CLI command tests in `src/test/logseq/cli/command/sync_test.cljs` for `sync start --e2ee-password`, `sync download --e2ee-password`, deprecation of config key handling, and missing-password reporting in `sync start/sync download/sync status` paths.
+
+I will add CLI config tests in `src/test/logseq/cli/integration_test.cljs` and `src/test/logseq/cli/format_test.cljs` to verify `:e2ee-password` is no longer treated as file config and to verify updated user-facing output.
+
+I will add desktop UI request tests in `src/test/frontend/handler/db_based/sync_test.cljs` or nearby handler tests to verify missing-password UI roundtrip invokes the shared worker verify-and-persist API instead of bespoke flow-only logic.
+
+I will run targeted tests first, then run `bb dev:lint-and-test` for final validation.
+
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Implementation plan
+
+### Phase 1. Define shared worker password vault behavior.
+
+1. Add failing tests in `src/test/frontend/worker/sync/crypt_test.cljs` that describe a new shared worker API for verify-and-persist password.
+
+2. Add failing tests that enforce refresh-token-only persisted password decrypt path in headless mode and reject config-only fallback.
+
+3. Implement a single worker helper in `src/main/frontend/worker/sync/crypt.cljs` that verifies a candidate password by decrypting user encrypted private key and then persists encrypted password payload.
+
+4. Expose the helper through a thread API that can be invoked by both CLI and desktop flows.
+
+5. Remove `:e2ee-password` config candidate usage from `crypt.cljs` headless candidate logic.
+
+6. Ensure CLI-headless path does not mask missing-password with `:ui-interaction-required` when no interactive channel exists.
+
+7. Add typed error payload and hint contract for missing persisted password.
+
+8. Run worker crypt tests and confirm failing cases are now passing.
+
+### Phase 2. Enforce browser and node persistence locations.
+
+1. Add failing tests for browser runtime persistence using IndexedDB secret storage rather than OPFS file route.
+
+2. Add failing tests for node runtime persistence at `<data-dir>/e2ee-password`.
+
+3. Update `src/main/frontend/worker/sync/crypt.cljs` storage branching to select persistence backend by runtime (`:browser` vs `:node`) rather than legacy native URL heuristics for this password feature.
+
+4. Keep node runtime read/write via `platform/read-text!` and `platform/write-text!` with path `e2ee-password`.
+
+5. Keep browser runtime read/write via `platform/read-secret-text` and `platform/save-secret-text!` so storage lands in IndexedDB-backed kv store.
+
+6. Add migration fallback in browser path to read legacy OPFS `e2ee-password` once, then re-save to IndexedDB, then remove legacy file.
+
+7. Add clear/delete behavior that correctly removes persisted password from both runtime backends.
+
+8. Run `frontend.worker.sync.crypt-test` to verify storage routing and migration behavior.
+
+### Phase 3. Deprecate `cli.edn` `:e2ee-password`.
+
+1. Add failing CLI tests in `src/test/logseq/cli/command/sync_test.cljs` that reject `sync config set|get|unset e2ee-password`.
+
+2. Add failing config tests in `src/test/logseq/cli/integration_test.cljs` showing `:e2ee-password` in old `cli.edn` is ignored and sanitized out without any deprecation warning.
+
+3. Remove `e2ee-password` from `config-key-map` and sync config command examples in `src/main/logseq/cli/command/sync.cljs`.
+
+4. Remove `:e2ee-password` from `sync-config` payload generated by CLI for worker runtime config.
+
+5. Add `:e2ee-password` into `removed-config-keys` in `src/main/logseq/cli/config.cljs` so persisted file config is automatically sanitized.
+
+6. Update `src/main/logseq/cli/format.cljs` and `src/test/logseq/cli/format_test.cljs` for changed sync-config output expectations.
+
+7. Run sync command and format tests to verify deprecation behavior.
+
+### Phase 4. Add CLI `--e2ee-password` on `sync start` and `sync download`, and enforce missing-password errors.
+
+1. Add failing parse/build-action tests in `src/test/logseq/cli/command/sync_test.cljs` for `--e2ee-password` on both `sync start` and `sync download`.
+
+2. Add failing execute tests that both commands invoke worker verify-and-persist before start or download work begins.
+
+3. Add CLI auth helper test coverage in `src/test/logseq/cli/integration_test.cljs` for resolving refresh-token from `auth.json` in runtime command execution path.
+
+4. Extend `src/main/logseq/cli/command/sync.cljs` command spec to include `--e2ee-password` for `sync start` and `sync download`.
+
+5. Add CLI-side runtime auth context helper usage so both flows have id-token and refresh-token available at execution time.
+
+6. When option is provided, call worker shared verify-and-persist API and fail fast on invalid password.
+
+7. In `sync start` and `sync download` execution paths, plus `sync status` reporting path, map missing-password diagnostics to explicit `e2ee-password not found` errors with actionable hint text.
+
+8. Ensure `sync status` returns error status and non-zero exit code when e2ee password is required but missing.
+
+9. Keep machine-readable error code stable for automation.
+
+10. Run sync command tests and relevant integration tests.
+
+### Phase 5. Reuse CLI flow from desktop missing-password interaction.
+
+1. Add failing UI request tests for missing persisted password path in desktop interactive runtime.
+
+2. In `src/main/frontend/worker/sync/crypt.cljs`, route interactive fallback to request password input, then call the same shared verify-and-persist helper used by CLI.
+
+3. Update `src/main/frontend/worker/ui_request.cljs` and `src/main/frontend/handler/worker.cljs` action contract so UI request returns password input and worker does verification/decryption centrally.
+
+4. Update desktop password modal flow in `src/main/frontend/handler/events/rtc.cljs` and `src/main/frontend/components/e2ee.cljs` only as needed to collect password and forward it to worker.
+
+5. Remove duplicate validation logic from UI-side code paths after worker shared flow is active.
+
+6. Run frontend handler/component tests and existing e2ee-related tests.
+
+### Phase 6. Documentation and acceptance.
+
+1. Update `docs/cli/logseq-cli.md` to remove `sync config ... e2ee-password` references.
+
+2. Document `sync start --e2ee-password` and `sync download --e2ee-password` usage, plus missing-password troubleshooting for `sync start/sync download/sync status`.
+
+3. Document persistence locations explicitly.
+
+4. Browser runtime stores encrypted password in IndexedDB.
+
+5. Node runtime stores encrypted password at `<data-dir>/e2ee-password`.
+
+6. Add migration note for users with legacy `cli.edn :e2ee-password` and legacy browser OPFS password file.
+
+7. Run a final lint and test pass.
+
+8. Confirm no docs still recommend `cli.edn :e2ee-password`.
+
+## Edge cases to cover
+
+Expired id-token with valid refresh-token in CLI should still allow password verification and persistence after auth refresh.
+
+Missing refresh-token in `auth.json` should produce a login-required error before any password persistence attempt.
+
+Wrong `--e2ee-password` should fail verification without overwriting previously stored encrypted password.
+
+Node file exists but is corrupted transit payload should return typed missing/invalid-password diagnostics and preserve existing UX hints.
+
+Browser migration should handle missing legacy OPFS file without error noise.
+
+Desktop interactive flow cancellation should not persist empty password and should keep prior stored password untouched.
+
+Multiple `sync start` invocations should avoid race conditions that overwrite password storage with stale data.
+
+## Verification commands
+
+Run targeted worker tests.
+
+`bb dev:test -v frontend.worker.sync.crypt-test`
+
+Run targeted CLI sync tests.
+
+`bb dev:test -v logseq.cli.command.sync-test`
+
+Run CLI format tests.
+
+`bb dev:test -v logseq.cli.format-test`
+
+Run CLI integration tests around sync/auth/config behavior.
+
+`bb dev:test -v logseq.cli.integration-test`
+
+Run full lint and test suite before merge.
+
+`bb dev:lint-and-test`
+
+## Testing Details
+
+The key behavior assertions are that password persistence is always encrypted with refresh-token, storage backend is runtime-correct, and user-facing CLI/desktop UX is deterministic when password is missing or invalid.
+
+Tests will validate command outcomes and worker behavior contracts instead of only checking internal data structures.
+
+## Implementation Details
+
+- Introduce one shared worker API for verify-and-persist E2EE password and reuse it from CLI and desktop.
+- Remove `:e2ee-password` from CLI file config lifecycle and sync config subcommands.
+- Keep refresh-token as the sole crypto key for persisted password encryption and decryption.
+- Move browser persistence to IndexedDB secret storage and keep node persistence at `<data-dir>/e2ee-password`.
+- Add legacy migration read path from browser OPFS password file to IndexedDB.
+- Add explicit missing-password diagnostics for CLI `sync start/sync download/sync status`, with `sync status` returning error when password is required but missing.
+- Add `sync start --e2ee-password` and `sync download --e2ee-password` options with verification-before-persist semantics.
+- Keep `:e2ee-password` deprecation behavior as silent ignore with no compatibility warning.
+- Preserve machine-readable error codes and CLI structured output compatibility.
+- Update user docs and troubleshooting guidance to match deprecation and new option flow.
+
+## Question
+
+No open questions.
+
+Decisions locked.
+
+Add `--e2ee-password` to `sync start` and `sync download` only.
+
+Ignore `cli.edn :e2ee-password` silently with no compatibility path.
+
+Return error for missing password in `sync status`.
+
+---
diff --git a/docs/agent-guide/076-worker-sync-auth-state-consolidation.md b/docs/agent-guide/076-worker-sync-auth-state-consolidation.md
new file mode 100644
index 0000000000..8caa960ea3
--- /dev/null
+++ b/docs/agent-guide/076-worker-sync-auth-state-consolidation.md
@@ -0,0 +1,178 @@
+# 076 — Move db-sync auth fields from `frontend.worker.state/*db-sync-config` to `frontend.worker.state/*state`
+
+Goal: Move all db-sync auth-related runtime fields out of `frontend.worker.state/*db-sync-config` and store them in `frontend.worker.state/*state`.
+
+Goal: Keep `*db-sync-config` focused on transport/runtime config (`ws-url`, `http-base`, and non-auth flags), and keep auth/token lifecycle in one place (`*state`).
+
+Goal: Align auth flow behavior across web app, desktop app, logseq-cli, and db-worker-node.
+
+Architecture: Worker sync modules (`frontend.worker.sync.util`, `frontend.worker.sync.auth`, related sync helpers) should read auth state from `worker-state/*state` only after migration.
+
+Architecture: `:thread-api/sync-app-state` becomes the canonical write path for auth fields; `:thread-api/set-db-sync-config` remains for non-auth sync config.
+
+Related:
+- `src/main/frontend/worker/state.cljs`
+- `src/main/frontend/worker/db_core.cljs`
+- `src/main/frontend/worker/sync/util.cljs`
+- `src/main/frontend/worker/sync/auth.cljs`
+- `src/main/frontend/persist_db/browser.cljs`
+- `src/main/frontend/handler/events/ui.cljs`
+- `src/main/frontend/components/repo.cljs`
+- `src/main/frontend/handler/events/rtc.cljs`
+- `src/main/frontend/handler/db_based/sync.cljs`
+- `src/main/logseq/cli/command/sync.cljs`
+- `src/main/frontend/worker/db_worker_node.cljs`
+
+## Current implementation snapshot
+
+### Web app
+
+- Worker init (`persist_db/browser.cljs`) currently sends `:thread-api/set-db-sync-config` with:
+  - `:ws-url`
+  - `:http-base`
+  - `:oauth-domain`
+  - `:oauth-client-id`
+- Auth tokens (`:auth/id-token`, `:auth/access-token`, `:auth/refresh-token`) are synced through `:thread-api/sync-app-state`.
+
+### Desktop app
+
+- Desktop renderer uses remote db-worker-node runtime (`persist_db/remote.cljs` + electron IPC `:db-worker-runtime`).
+- It shares the same frontend sync call sites (`events/ui.cljs`, `components/repo.cljs`) that currently push oauth fields through `:thread-api/set-db-sync-config`.
+- It also uses `:thread-api/sync-app-state` to sync token state before starting sync flows.
+
+### logseq-cli
+
+- `logseq.cli.command.sync` currently builds worker sync config with `:ws-url`, `:http-base`, and `:auth-token`.
+- CLI sends `:thread-api/set-db-sync-config` before sync operations.
+- CLI currently uses `:thread-api/get-db-sync-config` to preserve existing worker `:auth-token` for non-authenticated actions (`sync stop`, `sync status`) when runtime config has no token.
+- CLI does not currently treat `:thread-api/sync-app-state` as the primary auth write path.
+
+### db-worker-node
+
+- `frontend.worker.db-worker-node/non-repo-methods` already allows both:
+  - `:thread-api/set-db-sync-config`
+  - `:thread-api/get-db-sync-config`
+  - `:thread-api/sync-app-state`
+- db-worker-node currently persists whatever auth fields are sent in `set-db-sync-config` because worker stores the full map in `*db-sync-config`.
+
+## Auth field inventory to migrate
+
+Auth-related fields currently coupled to `*db-sync-config`:
+
+- `:auth-token`
+- `:oauth-token-url`
+- `:oauth-domain`
+- `:oauth-client-id`
+
+Non-auth fields that should remain in `*db-sync-config`:
+
+- `:ws-url`
+- `:http-base`
+- `:enabled?`
+- non-auth feature toggles/config flags
+
+## Target state contract
+
+After migration:
+
+- `*db-sync-config` contains only non-auth sync config.
+- `*state` contains all sync auth fields, including oauth metadata used for worker-side token refresh.
+
+Proposed worker auth keys in `*state`:
+
+- `:auth/id-token`
+- `:auth/access-token`
+- `:auth/refresh-token`
+- `:auth/oauth-token-url`
+- `:auth/oauth-domain`
+- `:auth/oauth-client-id`
+
+## Locked decisions
+
+1. `:thread-api/get-db-sync-config` must return non-auth fields only.
+2. Implementation must follow phase order in this document (Phase 1 → Phase 5) without reordering.
+
+## Implementation plan
+
+### Phase 1 — Worker state model + compatibility bridge
+
+1. Extend `frontend.worker.state/*state` defaults with oauth auth metadata keys.
+2. Add worker helpers to normalize/split auth fields from sync config payloads.
+3. Update `frontend.worker.sync.util/auth-token` and `frontend.worker.sync.auth/<refresh-id&access-token` to read auth fields from `*state`.
+4. Keep a temporary compatibility bridge in `:thread-api/set-db-sync-config`:
+   - If auth keys are present in incoming config, move/merge them into `*state`.
+   - Keep only non-auth keys in `*db-sync-config`.
+5. Enforce `:thread-api/get-db-sync-config` contract to return non-auth fields only from the beginning of migration.
+6. Add/update worker tests for auth resolution and oauth token URL/client ID lookup from `*state`.
+
+### Phase 2 — Web + desktop producer updates
+
+1. Update web/desktop `set-db-sync-config` call sites to stop sending auth-related fields:
+   - `src/main/frontend/persist_db/browser.cljs`
+   - `src/main/frontend/handler/events/ui.cljs`
+   - `src/main/frontend/components/repo.cljs`
+2. Ensure oauth metadata is sent through `:thread-api/sync-app-state` payloads (or equivalent state sync path) so worker auth refresh can still resolve oauth endpoints.
+3. Update state-sync payload builders:
+   - `src/main/frontend/handler/events/rtc.cljs`
+   - `src/main/frontend/handler/db_based/sync.cljs`
+4. Add/update frontend tests to assert new payload boundaries (`sync-app-state` carries auth metadata; `set-db-sync-config` carries non-auth config only).
+
+### Phase 3 — CLI migration to `sync-app-state` auth writes
+
+1. Remove `:auth-token` from CLI worker sync config payload (`sync-config` function in `logseq.cli.command.sync`).
+2. Replace CLI token-preservation logic that depends on `get-db-sync-config` with explicit auth-state sync:
+   - Resolve auth via `cli-auth/resolve-auth!` / `resolve-auth-token!`.
+   - Send auth into worker via `:thread-api/sync-app-state` as `:auth/*` fields.
+3. Keep `sync config set|get|unset` as non-auth config only (`ws-url`, `http-base`).
+4. Update CLI tests in:
+   - `src/test/logseq/cli/command/sync_test.cljs`
+   - `src/test/logseq/cli/integration_test.cljs`
+   to validate new invoke sequence (`sync-app-state` + `set-db-sync-config` non-auth payload).
+
+### Phase 4 — db-worker-node API contract alignment
+
+1. Keep method allowlist behavior unchanged (`sync-app-state` remains non-repo method).
+2. Update db-worker-node tests that currently assert `auth-token` inside `get-db-sync-config`:
+   - move assertions to `sync-app-state` behavior and sync runtime behavior.
+3. Ensure repo-mismatch behavior remains unchanged (no auth contract leakage into repo-bound checks).
+
+### Phase 5 — Remove temporary compatibility paths
+
+1. Remove fallback reads from `*db-sync-config` for auth fields once all producers are migrated.
+2. Keep `get-db-sync-config` strict: return non-auth fields only.
+3. Keep final state model strict:
+   - auth only from `*state`
+   - transport config only from `*db-sync-config`
+
+## Testing plan
+
+### Targeted tests
+
+- `bb dev:test -v frontend.worker.node-sync-test`
+- `bb dev:test -v frontend.worker.sync.crypt-test`
+- `bb dev:test -v frontend.worker.db-sync-test`
+- `bb dev:test -v frontend.worker.db-worker-node-test`
+- `bb dev:test -v frontend.handler.db-based.sync-test`
+- `bb dev:test -v frontend.components.repo-test`
+- `bb dev:test -v logseq.cli.command.sync-test`
+- `bb dev:test -v logseq.cli.integration-test`
+
+### Final verification
+
+- `bb dev:lint-and-test`
+
+## Edge cases and migration risks
+
+- Running daemon with stale in-memory auth state while CLI switches between commands.
+- Mixed-version compatibility (new CLI with old worker, old CLI with new worker) during rollout.
+- Worker token refresh requiring oauth metadata after migration; missing oauth fields must produce clear diagnostics.
+- Avoid confusion with unrelated db-worker HTTP auth token (`persist_db.node` / `persist_db.remote` transport auth); this plan only changes db-sync cloud auth state inside worker sync logic.
+
+## Acceptance criteria
+
+1. Worker sync auth logic no longer depends on auth fields inside `*db-sync-config`.
+2. All auth-related db-sync fields are sourced from `*state`.
+3. `set-db-sync-config` payloads from web/desktop/CLI carry only non-auth sync config.
+4. CLI sync flows remain functional (start/status/stop/upload/download/remote-graphs/ensure-keys/grant-access).
+5. db-worker-node tests and CLI tests pass with updated contracts.
+6. No regression in desktop/web db-sync startup and key-management flows.
diff --git a/docs/agent-guide/077-cli-e2e-sync-tests.md b/docs/agent-guide/077-cli-e2e-sync-tests.md
new file mode 100644
index 0000000000..aa4b3b33e7
--- /dev/null
+++ b/docs/agent-guide/077-cli-e2e-sync-tests.md
@@ -0,0 +1,195 @@
+# CLI E2E Sync Suite Implementation Plan
+
+Goal: Add a dedicated sync-focused `cli-e2e` suite that is isolated from non-sync coverage and validates MVP upload and download behavior using two independent `db-worker-node` processes driven only through CLI commands.
+
+Architecture: Keep the existing non-sync suite as the default `cli-e2e` path and introduce a separate sync suite with its own manifest files, runner entrypoint, and preconditions.
+Architecture: Model sync behavior with two distinct data directories that run two different `db-worker-node` processes against the same graph name, then assert health via `sync status` and data convergence via CLI queries.
+Architecture: Ship MVP coverage for upload and download first, while leaving realtime sync-start convergence tests for a follow-up phase.
+
+Tech Stack: Babashka, EDN case manifests, `logseq-cli`, `db-worker-node`, JSON parsing via Python 3 in shell helpers, existing CLI sync commands.
+
+Related: Builds on `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/064-logseq-cli-integration-test-shell-refactor.md`.
+Related: Relates to `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/047-logseq-cli-sync-command.md`.
+Related: Relates to `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/048-sync-download-start-reliability.md`.
+Related: Relates to `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/051-logseq-cli-sync-upload-fix.md`.
+
+## Problem statement
+
+`cli-e2e` currently excludes all `sync` commands by design.
+
+`/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` explicitly excludes the `sync` prefix, and `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/manifests.clj` only loads `non_sync_*` manifests.
+
+This keeps non-sync coverage clean, but there is currently no shell-first `cli-e2e` coverage for sync upload and download behavior.
+
+Current sync integration checks in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/integration_test.cljs` are mostly mocked transport-level tests and do not validate real shell command orchestration in a two-process setup.
+
+The requested test architecture requires two independent `db-worker-node` processes in different directories, both operating on the same graph name, with CLI-only operations and status-driven verification.
+
+## Current implementation snapshot
+
+| Area | Current file | Current behavior | Gap for this plan |
+| --- | --- | --- | --- |
+| Suite manifests | `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/manifests.clj` | Loads only `non_sync_inventory.edn` and `non_sync_cases.edn`. | No sync suite loading path. |
+| Non-sync inventory policy | `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` | Excludes `sync`, `login`, and `logout`. | Sync tests must live in separate manifests to avoid policy conflict. |
+| CLI runner tasks | `/Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn` | Exposes `test`, `list-cases`, and `build` for one suite. | Need dedicated sync tasks and clearer suite-level ergonomics. |
+| Case execution model | `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/runner.clj` | Supports shell-first setup and command chains with templating. | No built-in wait helper for polling `sync status` until pending queues are empty. |
+| Sync command behavior | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/sync.cljs` | `sync upload`, `sync download`, and `sync status` are implemented and return structured JSON. | E2E harness does not yet assert these behaviors with two independent workers. |
+| Server process isolation | `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/server.cljs` | Data-dir and graph path determine lock ownership and process identity. | Need explicit test cases that prove two data dirs produce two independent worker processes for the same graph name. |
+
+## Scope and MVP boundaries
+
+MVP in this plan covers upload and download flows only.
+
+MVP does not add coverage for long-running `sync start` websocket convergence behavior.
+
+MVP requires CLI-only graph operations during test execution, including graph creation, mutation, upload, download, status checks, and data verification queries.
+
+MVP keeps non-sync test behavior unchanged and isolated.
+
+## Testing Plan
+
+I will add runner-level unit tests that fail first when sync suite manifests and tasks are missing, and pass only after suite separation is implemented.
+
+I will add sync suite manifest coverage tests that fail first when required sync command options are not covered by MVP cases.
+
+I will add shell-first sync E2E cases that fail first and validate the two-data-dir architecture, `sync status` health checks, pending queue convergence checks, and graph data parity assertions.
+
+I will validate command ergonomics by running non-sync and sync suites independently and ensuring their outputs and selection logic remain deterministic.
+
+I will follow @test-driven-development for every behavior slice in this plan.
+
+NOTE: I will write all tests before I add any implementation behavior.
+
+## Target sync suite architecture
+
+```text
++----------------------------------+                 +----------------------------------+
+| data-dir A                       |                 | data-dir B                       |
+| graph: sync-e2e-mvp              |                 | graph: sync-e2e-mvp              |
+| db-worker-node process A         |                 | db-worker-node process B         |
++----------------+-----------------+                 +----------------+-----------------+
+                 |                                                    |
+                 | CLI commands only                                  | CLI commands only
+                 v                                                    v
+        logseq sync upload                                   logseq sync download
+                 |                                                    |
+                 +-------------------> remote sync backend <----------+
+
+Verification path:
+1) mutate graph via CLI in A.
+2) run sync upload via CLI in A.
+3) poll sync status via CLI until pending queues settle and last-error remains nil.
+4) run sync download via CLI in B.
+5) compare graph data via CLI queries in A and B.
+```
+
+## Detailed implementation plan
+
+### Phase 1. Add explicit sync suite separation in `cli-e2e`.
+
+1. Add a failing unit test in `/Users/rcmerci/gh-repos/logseq/cli-e2e/test/logseq/cli/e2e/main_test.clj` that expects a dedicated sync test entrypoint to load sync manifests instead of non-sync manifests.
+2. Add a failing unit test in `/Users/rcmerci/gh-repos/logseq/cli-e2e/test/logseq/cli/e2e/main_test.clj` that expects non-sync `test` to keep current behavior unchanged.
+3. Add `sync_inventory.edn` loading support in `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/manifests.clj` with a suite selector API.
+4. Add `sync_cases.edn` loading support in `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/manifests.clj` with the same suite selector API.
+5. Add suite-aware run helpers in `/Users/rcmerci/gh-repos/logseq/cli-e2e/src/logseq/cli/e2e/main.clj` so non-sync and sync share execution plumbing but load different manifests.
+6. Add new tasks in `/Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn` for `test-sync` and `list-sync-cases`.
+7. Keep existing `test` and `list-cases` mapped to non-sync manifests.
+8. Run `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn unit-test` and confirm failures turn green for the new suite selection behavior.
+
+### Phase 2. Define sync inventory and MVP case manifests.
+
+9. Create `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/sync_inventory.edn` with MVP required commands `sync upload`, `sync download`, and `sync status`.
+10. Include only MVP-required sync options in `sync_inventory.edn` to avoid over-scoping phase one.
+11. Add a failing coverage test in `/Users/rcmerci/gh-repos/logseq/cli-e2e/test/logseq/cli/e2e/coverage_test.clj` for missing sync command coverage.
+12. Create `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/sync_cases.edn` with initial empty or placeholder MVP case definitions that intentionally fail coverage.
+13. Run `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn test-sync --skip-build` and confirm coverage failure is clear and actionable.
+
+### Phase 3. Add reusable sync status and graph parity helper scripts.
+
+14. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/scripts/wait_sync_status.py` that repeatedly executes CLI `sync status --output json` until pending queues reach zero or timeout.
+15. Make `wait_sync_status.py` fail immediately when `status` is not `ok` or when `data.last-error` is not `null`.
+16. Add `/Users/rcmerci/gh-repos/logseq/cli-e2e/scripts/compare_graph_queries.py` that executes two CLI query commands and compares normalized payloads.
+17. Keep helper scripts CLI-only by calling `node static/logseq-cli.js` commands rather than reading DB files directly.
+18. Add shell-level tests for these helper scripts in `/Users/rcmerci/gh-repos/logseq/cli-e2e/test/logseq/cli/e2e/runner_test.clj` or a new helper test namespace using mocked command execution.
+
+### Phase 4. Implement MVP sync upload/download test case with two worker processes.
+
+19. Add one MVP case in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/sync_cases.edn` that provisions two data dirs under one temp root.
+20. In setup, create two separate config files for directory A and directory B with explicit sync endpoint keys and auth placeholders sourced from environment variables.
+21. In setup, create the graph in directory A via CLI and add deterministic marker data via CLI `upsert` commands.
+22. In setup, start `db-worker-node` for graph A via CLI `server start`.
+23. In main commands, run CLI `sync upload` in directory A.
+24. In main commands, run `wait_sync_status.py` against directory A to ensure `last-error` remains empty and pending counters settle.
+25. In main commands, run CLI `sync download` in directory B for the same graph name.
+26. In main commands, start `db-worker-node` for graph B via CLI `server start`.
+27. In main commands, use `compare_graph_queries.py` to compare deterministic query outputs between A and B.
+28. In cleanup, stop servers for both directory A and directory B via CLI `server stop`.
+29. Ensure the case `:covers` map marks `sync upload`, `sync download`, and `sync status` coverage in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/sync_cases.edn`.
+30. Run `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn test-sync --skip-build` and verify the MVP case passes.
+
+### Phase 5. Keep non-sync suite stable and document operator workflow.
+
+31. Run `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn test --skip-build` and verify non-sync behavior is unchanged.
+32. Update `/Users/rcmerci/gh-repos/logseq/cli-e2e/README.md` with separate commands for non-sync and sync suites.
+33. Add required environment variable documentation in `/Users/rcmerci/gh-repos/logseq/cli-e2e/README.md` for sync suite execution.
+34. Optionally add `dev:cli-e2e-sync` task in `/Users/rcmerci/gh-repos/logseq/bb.edn` that delegates to `bb -f cli-e2e/bb.edn test-sync`.
+35. Run `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn list-sync-cases` and ensure the new case is discoverable.
+
+## Verification commands and expected outcomes
+
+| Command | Expected outcome |
+| --- | --- |
+| `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn test --skip-build` | Runs non-sync suite only and remains green. |
+| `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn list-cases` | Lists non-sync case ids only. |
+| `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn list-sync-cases` | Lists sync case ids only. |
+| `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn test-sync --skip-build` | Runs sync suite only and validates MVP upload or download behavior. |
+| `bb -f /Users/rcmerci/gh-repos/logseq/cli-e2e/bb.edn test-sync --skip-build --case sync-upload-download-mvp` | Runs one sync MVP case with deterministic status and parity checks. |
+
+## Edge cases to include in MVP case design
+
+The sync suite must fail with a clear message when required auth or endpoint environment variables are missing.
+
+The status polling helper must fail on timeout and print the last seen status payload for debugging.
+
+The status polling helper must fail when `last-error` appears even if pending counters reach zero.
+
+The graph parity helper must compare normalized query results, not raw command output strings that can differ by formatting.
+
+Cleanup must tolerate partially started state and still attempt to stop both servers.
+
+The sync suite must not mutate or depend on `non_sync_*` manifest files.
+
+## Open clarifications to resolve before implementation
+
+MVP sync suite will target local db-sync by default (`http://localhost:8080` plus local websocket).
+
+CI integration is intentionally out of scope for this phase and will be decided after MVP stabilizes.
+
+Confirm the minimum auth material for sync MVP in test environments, including whether a refresh token is strictly required or whether pre-seeded runtime tokens in config are sufficient.
+
+## Testing Details
+
+The new tests validate real shell behavior through compiled `logseq-cli` commands and real `db-worker-node` process lifecycle handling across two independent data directories.
+
+The MVP sync case verifies behavior outcomes by checking sync health status, pending queue convergence, and cross-directory graph data parity for deterministic query payloads.
+
+The suite separation tests ensure sync coverage does not destabilize non-sync command coverage expectations.
+
+## Implementation Details
+
+- Keep non-sync manifests and command coverage unchanged.
+- Add sync manifests as a separate suite, not an extension of non-sync inventory.
+- Reuse existing `main/run!` and runner infrastructure with suite-aware manifest loading.
+- Keep all graph mutations and validations CLI-driven in case commands and helper scripts.
+- Use two explicit data directories per sync case to guarantee two independent `db-worker-node` processes.
+- Poll `sync status` until pending counters settle and fail on `last-error`.
+- Compare graph parity through deterministic CLI query outputs.
+- Document sync suite environment requirements in `cli-e2e/README.md`.
+- Keep sync suite runnable independently with `test-sync` and `list-sync-cases` tasks.
+- Defer `sync start` realtime scenarios to a follow-up plan after MVP upload and download stabilization.
+
+## Question
+
+Should MVP include only one-direction flow `A upload -> B download`, or should it also include the reverse-direction snapshot refresh in the same phase.
+
+---
diff --git a/docs/agent-guide/078-logseq-cli-task-subcommands.md b/docs/agent-guide/078-logseq-cli-task-subcommands.md
new file mode 100644
index 0000000000..55cf77bfd8
--- /dev/null
+++ b/docs/agent-guide/078-logseq-cli-task-subcommands.md
@@ -0,0 +1,195 @@
+# Logseq CLI Task Subcommands Implementation Plan
+
+Goal: Add task-oriented subcommands to the current `logseq-cli` command surface with `list task` and `upsert task`, where a task is any node tagged with `#Task` (`:logseq.class/Task`), including both blocks and pages.
+
+Architecture: Reuse the existing `logseq-cli -> transport/invoke -> db-worker-node thread-api` flow, and keep command parsing/build/validation in CLI command namespaces with db read logic in db-worker helpers.
+
+Architecture: Keep behavior aligned with current `list`/`upsert`/`remove` conventions, and avoid introducing a parallel command framework for tasks.
+
+Tech Stack: ClojureScript, `babashka.cli`, `promesa`, Datascript pull/query, existing `apply-outliner-ops` mutation path in db-worker.
+
+Related: Builds on [069-logseq-cli-search-subcommands.md](/Users/rcmerci/gh-repos/logseq/docs/agent-guide/069-logseq-cli-search-subcommands.md), [071-logseq-cli-search-content-option.md](/Users/rcmerci/gh-repos/logseq/docs/agent-guide/071-logseq-cli-search-content-option.md), and [docs/cli/logseq-cli.md](/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md).
+
+## Problem statement
+
+Current CLI supports generic node operations (`list page/tag/property`, `upsert block/page/tag/property`, `remove block/page/tag/property`) but has no task-focused command path.
+
+The product model already has built-in class `:logseq.class/Task` and task properties (`status`, `priority`, `deadline`, `scheduled`), so users currently need multiple generic commands or custom queries for common task workflows.
+
+We need a first-class task command group that maps to existing implementation patterns and is script-friendly.
+
+## Current baseline from implementation
+
+`list` commands already expose pagination and sort contracts and depend on db-worker helper functions via `:thread-api/cli-list-*`.
+
+`upsert block/page` already supports tag/property mutation via `--update-tags`, `--update-properties`, `--remove-tags`, and `--remove-properties`.
+
+`remove` commands already implement robust selector validation, name/id disambiguation, and best-effort multi-id behavior for blocks.
+
+Built-in class `:logseq.class/Task` exists and is treated as a tag class with task properties in db bootstrap.
+
+## Command surface proposal (for discussion first)
+
+This section is intentionally a proposal draft so we can converge on options before implementation.
+
+### 1) `list task` options proposal
+
+Recommended MVP options:
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `--status` | status alias | none | Accept same aliases as current `upsert block --status` normalization. |
+| `--priority` | `low|medium|high|urgent` | none | Task priority filter. |
+| `--content` | string | none | Case-insensitive substring filter on `:block/title`. |
+| `--fields` | csv | command default | Same pattern as existing `list` commands. |
+| `--limit` | long | none | Same as existing `list`. |
+| `--offset` | long | none | Same as existing `list`. |
+| `--sort` | enum | `updated-at` | Proposed sort fields: `updated-at`, `created-at`, `title`, `status`, `priority`. |
+| `--order` | `asc|desc` | `asc` | Same as existing `list`. |
+
+Recommended default output fields:
+
+`id,title,status,priority,scheduled,deadline,updated-at,created-at`.
+
+Phase 2 optional filters:
+
+`--scheduled-after`, `--scheduled-before`, `--deadline-after`, `--deadline-before`, and multi-status support.
+
+### 2) `upsert task` options proposal
+
+Recommended MVP options:
+
+| Option | Type | Purpose |
+| --- | --- | --- |
+| `--id` | long | Update an existing node as task by db/id. |
+| `--uuid` | uuid | Update an existing node as task by UUID. |
+| `--page` | string | Upsert a page task by page name. |
+| `--content` | string | Create a block task with content. |
+| `--target-id` | long | Block create target selector. |
+| `--target-uuid` | uuid | Block create target selector. |
+| `--target-page` | string | Block create target selector. |
+| `--pos` | `first-child|last-child|sibling` | Block create position control. |
+| `--status` | status alias | Set `:logseq.property/status`. |
+| `--priority` | enum | Set `:logseq.property/priority.*`. |
+| `--update-properties` | edn map | Advanced property mutation. |
+| `--remove-properties` | edn vector | Advanced property removal. |
+| `--update-tags` | edn vector | Optional extra tags beyond `#Task`. |
+| `--remove-tags` | edn vector | Optional tag removal with guardrails for `#Task`. |
+
+Recommended semantics:
+
+`upsert task` always ensures `:logseq.class/Task` tag exists on the target node.
+
+When selector is `--id` or `--uuid`, command runs in update mode and converts non-task node into task by adding `:logseq.class/Task`.
+
+When selector is `--page`, command upserts page and ensures task tag plus task properties.
+
+When selector is `--content` and no id/page selector is provided, command creates block task and supports current block targeting options.
+
+Key validation proposal:
+
+Only one of `--id`, `--uuid`, `--page` is allowed.
+
+`--content` and `--page` cannot be combined.
+
+`--target-*` and `--pos` are only valid for block-create path.
+
+Task removal strategy:
+
+Do not add `remove task` in this scope.
+
+Use existing `remove block` and `remove page` commands for deletion.
+
+## Proposed architecture and files
+
+Keep `list task` in list command flow and add db-worker helper method to avoid large query logic in CLI command layer.
+
+Implement `upsert task` by reusing existing upsert/tag/property helper functions and `apply-outliner-ops` patterns.
+
+Primary files to touch:
+
+- [/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs)
+- [/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs)
+- [/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs)
+- [/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs)
+- [/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs)
+- [/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs](/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs)
+- [/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md](/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md)
+- [/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn](/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn)
+- [/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn](/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn)
+
+## Testing Plan
+
+I will follow @test-driven-development and add all failing tests before implementation code changes.
+
+I will add parser and validation tests in [commands_test.cljs](/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs) for new command paths and option conflicts.
+
+I will add command execution tests for new task logic in [upsert_test.cljs](/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/upsert_test.cljs) and existing remove/list test files, or create focused task command test namespaces if coverage becomes too broad.
+
+I will add db-worker behavior tests for task listing in [db_worker_test.cljs](/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/common/db_worker_test.cljs).
+
+I will add output formatting tests in [format_test.cljs](/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs) for human/json/edn task command outputs.
+
+I will extend CLI e2e inventory and non-sync cases for `list task` and `upsert task`.
+
+I will run focused tests first and then run `bb dev:lint-and-test`.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Step-by-step implementation plan
+
+1. Add command entries for `list task` and `upsert task` with proposed option specs and examples.
+
+2. Wire new command keywords into parse-time validation in [commands.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs).
+
+3. Add build-action branches for new task commands and keep error codes aligned with existing style (`:missing-target`, `:invalid-options`, `:missing-page-name`).
+
+4. Add execute branch wiring for new task command types in [commands.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs).
+
+5. Implement `list task` db-worker helper query in [db_worker.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs) and expose it via new `:thread-api/cli-list-tasks` in [db_core.cljs](/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs).
+
+6. Implement `execute-list-task` in [list.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs) with existing sort/fields/offset/limit helpers.
+
+7. Implement `build-task-action` and `execute-upsert-task` in [upsert.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs) by composing existing tag/property resolution utilities and task-specific normalization for status and priority.
+
+8. Add `format` support for new command result shapes in [format.cljs](/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs).
+
+9. Update docs and CLI e2e coverage files once behavior is stable.
+
+## Edge cases to cover explicitly
+
+A target node can exist but not have `#Task`, and command should fail with explicit type-mismatch style error instead of silently mutating or deleting wrong entities.
+
+Task pages and task blocks must both be supported for list and upsert.
+
+`upsert task` status aliases should match current `upsert block --status` normalization so scripts can reuse existing values.
+
+`--scheduled` and `--deadline` are explicitly out of MVP and should be handled later via dedicated options or via `--update-properties`.
+
+`list task` sort behavior must stay stable with deterministic tie-breaker by `:db/id`, consistent with current list commands.
+
+## Testing Details
+
+I will verify parse/build/execute behavior at command layer and confirm db-worker helper output contracts without relying on ad hoc manual checks.
+
+I will ensure tests assert behavior for both block task and page task paths, including conversion of non-task nodes during upsert when selector-based update is used.
+
+I will include at least one e2e case that creates task via `upsert task` and lists it via `list task` in one flow.
+
+## Implementation Details
+
+- Keep task identity canonical as `:block/tags` containing `:logseq.class/Task`.
+- Reuse existing normalization helpers for status and property parsing to minimize duplicate parsing logic.
+- Prefer extending existing command namespaces over introducing a second task-only command framework.
+- Reuse existing list formatting utilities with task-specific column mapping.
+- Keep error code naming aligned with current conventions to avoid inconsistent CLI UX.
+- Keep JSON namespaced key behavior unchanged by routing through existing formatter normalization.
+- Ensure command help examples include both block and page task use cases.
+- Keep cli-e2e inventory and docs in lockstep with final option names.
+- Defer non-MVP filters (`deadline`/`scheduled` ranges, multi-status) and `upsert task` dedicated `--scheduled/--deadline` options.
+
+## Question
+
+No open questions.
+
+---
diff --git a/docs/agent-guide/079-logseq-cli-list-title-display-width.md b/docs/agent-guide/079-logseq-cli-list-title-display-width.md
new file mode 100644
index 0000000000..e0c6876191
--- /dev/null
+++ b/docs/agent-guide/079-logseq-cli-list-title-display-width.md
@@ -0,0 +1,246 @@
+# Logseq CLI List Title Display Width Implementation Plan
+
+Goal: Make every `TITLE` column in `logseq list *` human output use a fixed maximum visual width with correct CJK-aware width handling via `string-width`.
+
+Architecture: Keep list data retrieval unchanged in db-worker-node thread APIs and implement presentation-only changes in the CLI formatter layer.
+
+Architecture: Introduce a display-width-aware truncation and padding path that is applied to list title cells before table rendering.
+
+Tech Stack: ClojureScript, `logseq.cli.format`, `logseq.cli.command.list`, db-worker thread APIs in `frontend.worker.db-core`, JavaScript `string-width`.
+
+Related: Builds on `docs/agent-guide/062-logseq-cli-list-default-sort-updated-at.md`, `docs/agent-guide/066-logseq-cli-list-property-cardinality-column.md`, `docs/agent-guide/078-logseq-cli-task-subcommands.md`, and `docs/cli/logseq-cli.md`.
+
+## Problem statement
+
+Current human table rendering in `src/main/logseq/cli/format.cljs` uses `(count text)` for width calculation and right padding.
+
+`count` is code-point length, not terminal display width.
+
+This breaks alignment when titles contain CJK or mixed-width text.
+
+Current `list` human output also allows unbounded title length, which can push important columns out of view for `list page`, `list tag`, `list property`, and `list task`.
+
+We need a stable, readable table contract where `TITLE` is capped to a reasonable visual width and aligned correctly for mixed-language content.
+
+## Current baseline from implementation
+
+The active CLI stack is the `src/main/logseq/cli/*` implementation, not the legacy `deps/cli` command stack.
+
+List command data is produced by db-worker helpers and returned through thread APIs without formatter concerns.
+
+The relevant path is:
+
+```text
+logseq list <page|tag|property|task>
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs
+  -> transport/invoke :thread-api/cli-list-*
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs
+```
+
+`TITLE` columns are defined in formatter column configs in `src/main/logseq/cli/format.cljs`.
+
+All table rendering goes through `render-table` and `format-counted-table` in the same file.
+
+## Scope
+
+In scope commands are:
+
+| Command | Human output table has `TITLE` column | Source formatter function |
+| --- | --- | --- |
+| `logseq list page` | Yes | `format-list-page` |
+| `logseq list tag` | Yes | `format-list-tag` |
+| `logseq list property` | Yes | `format-list-property` |
+| `logseq list task` | Yes | `format-list-task` |
+
+The default max visual width target for title is `40` columns.
+
+The value is configurable in `cli.edn` via a new CLI config key.
+
+The cap is measured by display width, not character count.
+
+Out of scope commands include `search *`, `query list`, `graph list`, and `server list`.
+
+Out of scope outputs include JSON and EDN payload shape changes.
+
+## Design decisions
+
+### 1) Keep db-worker-node payloads unchanged
+
+No changes are required in `src/main/logseq/cli/common/db_worker.cljs` or thread API wiring in `src/main/frontend/worker/db_core.cljs`.
+
+db-worker should continue returning full `:block/title` values.
+
+Human formatting is the only layer that applies visual truncation.
+
+### 2) Add explicit title max-width policy in formatter
+
+Introduce a formatter default constant such as `list-human-title-max-display-width-default` with value `40`.
+
+Read an optional override from resolved CLI config using a new `cli.edn` key `:list-title-max-display-width`.
+
+Apply this policy only to `TITLE` extractors in list column definitions.
+
+Truncated values append a suffix `…` and remain within the max display width.
+
+### 3) Use `string-width` for display width operations
+
+Add npm interop in `src/main/logseq/cli/format.cljs` for `string-width`.
+
+Use `string-width` for:
+
+- Width measurement during truncation.
+- Width measurement during table column width calculation.
+- Padding logic in `pad-right` or equivalent.
+
+This ensures CJK and mixed-width titles align with other columns.
+
+### 4) Preserve existing list data semantics
+
+Sorting, filtering, `--fields`, `--limit`, and `--offset` behavior in `src/main/logseq/cli/command/list.cljs` remain unchanged.
+
+Only rendered human strings are affected.
+
+### 5) Keep non-list command behavior stable
+
+Prefer implementing title truncation in list-specific extractors.
+
+If `render-table` is upgraded to display-width-aware padding globally, verify non-list tables are unaffected except improved alignment.
+
+## Proposed implementation steps
+
+1. Invoke `@test-driven-development` and add failing formatter tests for long ASCII title truncation in each list command.
+
+2. Add failing formatter tests for long CJK and mixed CJK/ASCII titles in each list command.
+
+3. Add failing config resolution tests in `src/test/logseq/cli/config_test.cljs` for `:list-title-max-display-width`, including default fallback to `40` and valid `cli.edn` override.
+
+4. Add a focused formatter unit test for truncation helper behavior ensuring output display width is `<= 40` and suffix handling is correct.
+
+5. Add a focused formatter unit test for width-aware padding behavior with CJK text so column alignment is deterministic.
+
+6. Add config normalization helpers in `src/main/logseq/cli/config.cljs` to parse and validate `:list-title-max-display-width` as a positive integer.
+
+7. Add `string-width` import and helper functions in `src/main/logseq/cli/format.cljs`.
+
+8. Add title truncation helper and wire it into the `TITLE` extractor entries in `list-page-columns`, `list-tag-columns`, `list-property-columns`, and `list-task-columns`.
+
+9. Replace `(count ...)`-based width and padding internals in table rendering with display-width-aware logic.
+
+10. Run formatter and config tests and update exact spacing snapshots where needed.
+
+11. Update user-facing docs in `docs/cli/logseq-cli.md` to mention that list human `TITLE` uses default width `40`, supports `cli.edn` override, and always truncates with `…`.
+
+12. Optionally add one CLI e2e non-sync human-output case for long mixed-width title rendering if we want package-level regression protection.
+
+## Files to modify
+
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/config.cljs`.
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/config_test.cljs`.
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`.
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`.
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`.
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` (optional, only if we decide to cover human output end-to-end).
+- `/Users/rcmerci/gh-repos/logseq/package.json` (only if `string-width` is added as an explicit direct dependency).
+
+## Edge cases to cover
+
+A title with only CJK characters that exceeds max width.
+
+A title with alternating CJK and ASCII characters.
+
+A title exactly at width boundary.
+
+A title one display cell over boundary.
+
+A title containing emoji or variation selectors.
+
+A nil title where current logic falls back to `-`.
+
+A title containing newlines where current multiline row rendering is preserved.
+
+A very short title where no extra truncation marker appears.
+
+An invalid `cli.edn` width value such as `0`, negative numbers, or non-numeric values that must fall back to default `40`.
+
+## Risks and mitigation
+
+Risk: Moving width calculations to display width can shift spacing in non-list tables.
+
+Mitigation: Add or adjust tests for affected command outputs and constrain behavioral changes to alignment only.
+
+Risk: `string-width` import style may vary by bundling mode.
+
+Mitigation: Verify in unit tests and CLI runtime, and choose the interop form that matches current CJS usage conventions in the repo.
+
+Risk: New truncation can reduce discoverability of long titles.
+
+Mitigation: Keep JSON and EDN outputs untruncated and document this behavior clearly.
+
+Risk: Invalid `cli.edn` width values can produce inconsistent rendering if not normalized.
+
+Mitigation: Parse as positive integer with fallback to default `40` and add config tests for invalid values.
+
+## Open questions
+
+No open question.
+
+Decisions locked for this plan are default width `40`, `cli.edn` configurability, truncation suffix `…`, and list-only scope.
+
+## Testing Plan
+
+I will add formatter behavior tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` that verify title truncation and alignment for `list page`, `list tag`, `list property`, and `list task` human output.
+
+I will add helper-level tests in the same test namespace to validate width-aware truncation and padding with CJK and mixed-width samples.
+
+I will add config tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/config_test.cljs` to validate default value `40`, `cli.edn` override, and invalid-value fallback behavior.
+
+I will run focused tests first with `bb dev:test -v logseq.cli.format-test/test-human-output-list-page`, `bb dev:test -v logseq.cli.format-test/test-human-output-list-tag-property`, and `bb dev:test -v logseq.cli.format-test/test-human-output-list-task`.
+
+I will run broader CLI tests with `bb dev:test -v logseq.cli.format-test` and config tests with `bb dev:test -v logseq.cli.config-test`.
+
+If e2e coverage is added, I will run `bb -f cli-e2e/bb.edn test --skip-build`.
+
+I will finish with `bb dev:lint-and-test`.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Step-by-step execution checklist
+
+| Step | Action | Verification |
+| --- | --- | --- |
+| 1 | Add failing list title truncation tests. | Tests fail with current unbounded title output. |
+| 2 | Add failing CJK width alignment tests. | Tests fail due current `count`-based width logic. |
+| 3 | Add failing config tests for `:list-title-max-display-width`. | Tests fail before config parsing is implemented. |
+| 4 | Implement config parsing with default `40` and invalid fallback. | Config tests pass for default and override behavior. |
+| 5 | Implement `string-width` helpers. | Helper tests pass. |
+| 6 | Implement title truncation in list column extractors. | List tests show bounded title width and `…` suffix. |
+| 7 | Switch table padding/width to display-width-aware logic. | CJK alignment tests pass. |
+| 8 | Update docs and optional e2e. | Docs mention truncation behavior and tests stay green. |
+| 9 | Run full regression. | `bb dev:lint-and-test` passes. |
+
+## Testing Details
+
+The tests validate observable CLI behavior by asserting final human output strings for list commands, including truncation marker presence and table alignment under mixed-width input.
+
+The tests do not assert internal helper data structures beyond what is needed to validate final output semantics.
+
+## Implementation Details
+
+- Keep default max title width as formatter constant `40`.
+- Allow override from `cli.edn` key `:list-title-max-display-width`.
+- Parse config width as positive integer and fall back to default on invalid values.
+- Truncate by display width instead of character count.
+- Keep truncation policy limited to list `TITLE` columns.
+- Always use `…` as truncation suffix in human list output.
+- Preserve db-worker payload contracts and thread API names.
+- Preserve JSON and EDN full title output.
+- Ensure multiline table behavior is not regressed.
+- Document human-output-only truncation and config override in CLI docs.
+
+## Question
+
+No blocking question for implementation.
+
+---
diff --git a/docs/agent-guide/080-logseq-cli-status-option-cleanup.md b/docs/agent-guide/080-logseq-cli-status-option-cleanup.md
new file mode 100644
index 0000000000..22e8d4c3aa
--- /dev/null
+++ b/docs/agent-guide/080-logseq-cli-status-option-cleanup.md
@@ -0,0 +1,202 @@
+# Logseq CLI Status Option Cleanup Implementation Plan
+
+Goal: align task-related CLI semantics by removing `--status` from `upsert block`, adding consistent `-c` aliases for all `--content` options, and improving invalid `--status` error output to include all available values.
+
+Architecture: keep the current `logseq-cli -> command parse/build -> transport/invoke -> db-worker-node thread-api` flow, but move `--status` invalid-value reporting to runtime validation so it can use graph data.
+
+Architecture: add a small db-worker-node read endpoint for task status values from the current graph, and reuse it in CLI command validation/error messaging.
+
+Tech Stack: ClojureScript, `babashka.cli`, existing command modules under `src/main/logseq/cli/command/*`, formatter/error layer in `src/main/logseq/cli/format.cljs`.
+
+Related: builds on `docs/agent-guide/078-logseq-cli-task-subcommands.md` and current command contracts in `docs/cli/logseq-cli.md`.
+
+## Problem statement
+
+Current `upsert block` still accepts `--status`, even though task semantics are already represented by `upsert task`.
+
+Current `--content` aliasing is inconsistent: search/upsert already support `-c`, but `list task --content` does not.
+
+Current invalid enum error output for `--status` does not list accepted values, which slows down CLI troubleshooting.
+
+Example current output:
+
+```text
+logseq list task --status xxx
+Error (invalid-options): Invalid value for option :status: xxx
+```
+
+Target UX should include available values in the error output.
+
+## Current baseline from implementation
+
+### 1) `upsert block --status` is currently part of command spec and update path
+
+`src/main/logseq/cli/command/upsert.cljs` currently includes `:status` inside `upsert-block-spec` and examples include `upsert block --id 123 --status done`.
+
+`upsert block` update mode currently delegates to `src/main/logseq/cli/command/update.cljs`, where `:status` is parsed/normalized and merged into `:update-properties` as `:logseq.property/status`.
+
+### 2) `--content` aliasing is partly consistent
+
+Current `:content` options with `:alias :c` exist in:
+
+- `src/main/logseq/cli/command/search.cljs`
+- `src/main/logseq/cli/command/upsert.cljs` (`upsert block`, `upsert task`)
+
+Current `list task` in `src/main/logseq/cli/command/list.cljs` defines `:content` without alias.
+
+### 3) Invalid status message is parser-driven today, which blocks graph-derived values
+
+`src/main/logseq/cli/command/list.cljs` and `src/main/logseq/cli/command/upsert.cljs` currently define `:status` with static `:validate #{...}` sets.
+
+That causes invalid status values to fail at parse time, before repo/graph resolution and before any db query can run.
+
+With parse-time rejection, CLI cannot include values from the current graph.
+
+### 4) db-worker-node currently has no task-status-values endpoint
+
+`src/main/logseq/cli/common/db_worker.cljs` currently supports task listing/filtering, but does not expose a dedicated API to list available task status values from graph data.
+
+To satisfy the new requirement, we need a small read-only thread-api for status values and wire it through `src/main/frontend/worker/db_core.cljs`.
+
+## Scope
+
+In scope:
+
+1. Remove `--status` from `upsert block` option surface and help/examples.
+2. Ensure every CLI `--content` option has `-c` alias.
+3. When `--status` is invalid (e.g. `list task --status xxx`), show accepted values queried from the current graph in the error message.
+
+Out of scope:
+
+- New task query/filter semantics in db-worker.
+- Changing task storage/property schema.
+- New command groups beyond existing `upsert task` / `list task`.
+
+## Design decisions
+
+### Decision A: Task status writes move fully to `upsert task`
+
+`upsert block` will no longer expose `--status`.
+
+Task status changes should go through `upsert task --id|--uuid|--page|--content ... --status ...`.
+
+This removes overlap between generic block updates and task-specific semantics.
+
+### Decision B: Keep `-c` as the standard short alias for `--content`
+
+Add `:alias :c` to any remaining `:content` specs missing it (currently `list task`).
+
+No new short alias should be introduced for `content`.
+
+### Decision C: Validate `--status` against graph-derived values at runtime
+
+For `list task` / `upsert task` status validation, use values queried from the current graph instead of static hardcoded sets in command spec.
+
+This requires moving status value validation out of parse-time `:validate #{...}` and into command build/execute phase where graph/repo is available.
+
+Target output shape:
+
+```text
+Error (invalid-options): Invalid value for option :status: xxx. Available values (from current graph): todo, doing, done
+```
+
+(Exact values come from the active graph query result; ordering should be deterministic, e.g. sorted by status title.)
+
+## Proposed implementation plan
+
+1. Add RED parser tests for `upsert block --status` to assert it becomes invalid (unknown option path).
+2. Add RED parser tests for `list task -c <text>` to assert `-c` works as alias for `--content`.
+3. Add RED command tests asserting invalid task status errors include graph-derived available values in message text.
+4. Remove `:status` from `upsert-block-spec` in `src/main/logseq/cli/command/upsert.cljs`.
+5. Remove/adjust `upsert block` examples and help text that mention `--status`.
+6. If needed, add migration guidance in `src/main/logseq/cli/commands.cljs` for `upsert block --status` (guide user to `upsert task`).
+7. Add `:alias :c` to `list-task-spec :content` in `src/main/logseq/cli/command/list.cljs`.
+8. Remove parse-time static `:validate #{...}` for task `:status` options where graph-derived validation is required (`list task`, `upsert task`).
+9. Add db-worker helper in `src/main/logseq/cli/common/db_worker.cljs` to list available task status values from the current graph.
+10. Expose the helper via new thread-api in `src/main/frontend/worker/db_core.cljs`.
+11. In CLI command layer (`list.cljs` and `upsert.cljs`), fetch status values for current repo/graph and validate `--status`; on invalid input return `:invalid-options` with available-values suffix from graph query result.
+12. Keep output ordering deterministic (e.g. sorted asc by display name/ident) so error text and tests remain stable.
+13. Update completion tests and command docs to reflect final option surface.
+14. Update CLI user docs in `docs/cli/logseq-cli.md` for `upsert block`, `upsert task`, `list task -c`, and graph-derived status validation behavior.
+15. Update CLI e2e inventory/cases where `upsert block --status` is currently listed/covered.
+16. Run focused tests, then run full lint/test checks.
+
+## Files expected to change
+
+Primary implementation files:
+
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`
+
+Primary tests:
+
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` (only if formatted error snapshots/assertions are affected)
+
+Docs and e2e metadata:
+
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`
+
+## Testing plan
+
+I will follow `@test-driven-development` and implement tests before behavior changes.
+
+### Unit / command tests
+
+Add tests in `commands_test.cljs` for:
+
+- `upsert block --id 1 --status done` returns `:invalid-options` (or unknown option mapped to invalid-options).
+- `list task -c alpha` parses to `:list-task` with `:content "alpha"`.
+- invalid status errors for task commands include a graph-derived available-values suffix (using mocked thread-api responses).
+
+### Completion tests
+
+Update `completion_generator_test.cljs` to assert `list task` offers `-c` along with `--content`.
+
+### Docs/e2e coverage checks
+
+Ensure inventory and cases no longer advertise `upsert block --status`.
+
+Add/update one case that validates status updates via `upsert task` path.
+
+### Verification commands
+
+- `bb dev:test -v logseq.cli.commands-test`
+- `bb dev:test -v logseq.cli.completion-generator-test`
+- `bb dev:test -v logseq.cli.format-test` (if touched)
+- `bb -f cli-e2e/bb.edn test --skip-build` (if e2e specs are changed)
+- `bb dev:lint-and-test`
+
+## Risks and mitigations
+
+Risk: users relying on `upsert block --status` scripts will break.
+
+Mitigation: provide explicit migration guidance in parser error messaging and update docs clearly.
+
+Risk: status values query may return empty or unexpected shapes for some graphs.
+
+Mitigation: normalize db-worker response contract, sort deterministically, and provide a clear fallback suffix when no status values are found.
+
+Risk: moving status validation from parse time to runtime may change where errors are raised.
+
+Mitigation: add focused parser/build/execute tests for `list task` and `upsert task` to lock error codes/messages and avoid regressions on other options.
+
+## Acceptance criteria
+
+1. `upsert block` help/spec no longer includes `--status`.
+2. All CLI options named `--content` support `-c`.
+3. `logseq list task --status xxx` shows invalid-value error plus a deterministic available-values list queried from the current graph.
+4. Existing `upsert task --status ...` and `list task --status ...` happy paths remain green.
+5. CLI docs and e2e inventory reflect the new surface.
+
+## Question
+
+No blocking question.
+
+---
diff --git a/docs/agent-guide/081-logseq-cli-list-node-subcommand.md b/docs/agent-guide/081-logseq-cli-list-node-subcommand.md
new file mode 100644
index 0000000000..5e3dd989e6
--- /dev/null
+++ b/docs/agent-guide/081-logseq-cli-list-node-subcommand.md
@@ -0,0 +1,297 @@
+# Logseq CLI `list node` Subcommand Implementation Plan
+
+Goal: add a new `list node` subcommand to the existing `logseq-cli` surface so users can list ordinary nodes (both blocks and pages) filtered by tags and/or properties.
+
+Architecture: keep the current `logseq-cli -> command parse/build -> transport/invoke -> db-worker-node thread-api` flow and implement filter query logic in db-worker helpers.
+
+Architecture: reuse existing identifier resolution patterns from current CLI commands (especially tag/property resolution in `add.cljs`) instead of introducing a second resolver system.
+
+Tech Stack: ClojureScript, `babashka.cli`, Datascript query/datoms, `promesa`, current formatter/command framework.
+
+Related:
+- `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/078-logseq-cli-task-subcommands.md`
+- `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/062-cli-list-default-sort-updated-at.md`
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+
+## Problem statement
+
+Current CLI has `list page`, `list tag`, `list property`, and `list task`, but no generic `list node` path for querying ordinary content nodes by tag/property constraints.
+
+Users need a first-class command that can return both pages and blocks, with script-friendly filter options:
+
+- `--tags <tag1>,<tag2>,<tag3>`
+- `--properties <prop1>,<prop2>,<prop3>`
+
+Each filter item must support `id` / `uuid` / `ident` / `block-name`, and command execution must require at least one filter (`--tags` or `--properties`) to avoid returning unbounded node sets.
+
+## Current baseline from implementation
+
+### 1) List command framework is centralized and reusable
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs` already provides:
+
+- `list-common-spec` (`--expand`, `--fields`, `--limit`, `--offset`, `--sort`, `--order`)
+- shared helpers (`apply-sort`, `apply-offset-limit`, `apply-fields`)
+- per-subcommand field maps and execute functions
+
+This is the natural place to add `list-node-spec`, `list-node-field-map`, and `execute-list-node`.
+
+### 2) db-worker list read logic already lives in one namespace
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs` holds `list-pages`, `list-tags`, `list-properties`, and `list-tasks`.
+
+`/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs` exposes them via `:thread-api/cli-list-*` endpoints.
+
+A new `list-nodes` helper and `:thread-api/cli-list-nodes` should follow this same pattern.
+
+### 3) Existing resolver utilities already cover most selector forms
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` already contains reusable resolution logic:
+
+- tags: `resolve-tag-entity` / `resolve-tags` (supports id/uuid/ident/name through typed inputs)
+- properties: `resolve-property-identifiers` with `:allow-non-built-in? true` (supports id/ident/name)
+
+Gap to close for this plan:
+
+- property selector by `uuid` is not currently supported in property resolver path and should be added for parity with the requested contract.
+
+### 4) Command wiring and formatting are explicit and easy to extend
+
+- Command dispatch/build/validation currently enumerates list commands in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`.
+- Human output table formatting for list commands is in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`.
+- Command parser and behavior tests already exist in:
+  - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
+  - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/common/db_worker_test.cljs`
+  - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`
+
+## Command contract
+
+## CLI syntax
+
+```text
+logseq list node --graph <name> [--tags <csv>] [--properties <csv>] [common list options]
+```
+
+## Required filters
+
+At least one of the following must be present:
+
+- `--tags`
+- `--properties`
+
+If both are missing, return `:invalid-options` with a clear message:
+
+```text
+list node requires at least one of --tags or --properties
+```
+
+## Filter options
+
+### `--tags`
+
+`--tags <tag1>,<tag2>,<tag3>`
+
+Each tag token supports:
+
+- `id` (numeric)
+- `uuid`
+- `ident` (keyword form)
+- `block-name` (tag page name)
+
+### `--properties`
+
+`--properties <prop1>,<prop2>,<prop3>`
+
+Each property token supports:
+
+- `id` (numeric)
+- `uuid`
+- `ident` (keyword form)
+- `block-name` (property page name)
+
+## Filter semantics
+
+- CSV tokens are trimmed; blank tokens are ignored.
+- After normalization, empty filter lists are invalid.
+- `--tags a,b` means node must contain **all** resolved tag selectors.
+- `--properties x,y` means node must contain **all** resolved property selectors.
+- If both are provided, result must satisfy both groups (logical AND).
+
+## Node scope
+
+`list node` returns ordinary content nodes of two kinds:
+
+- pages
+- blocks
+
+Planned implementation should exclude schema-definition entities (for example, tag/property definition pages) so output focuses on content nodes.
+
+## Optional options (aligned with existing list commands)
+
+`list node` should support the same common list options already used by existing list subcommands:
+
+- `--expand`
+- `--fields <csv>`
+- `--limit <n>`
+- `--offset <n>`
+- `--sort <field>` (default `updated-at`)
+- `--order asc|desc`
+
+## Proposed sortable/field keys for `list node`
+
+MVP field map:
+
+- `id` -> `:db/id`
+- `ident` -> `:db/ident`
+- `title` -> `:block/title`
+- `uuid` -> `:block/uuid`
+- `type` -> `:node/type` (`"page"` or `"block"`)
+- `page-id` -> `:block/page-id` (for blocks)
+- `page-title` -> `:block/page-title` (for blocks)
+- `created-at` -> `:block/created-at`
+- `updated-at` -> `:block/updated-at`
+
+## Design details
+
+### A) CLI parsing and validation (`list.cljs` + `commands.cljs`)
+
+1. Add `list-node-field-map` and `list-node-spec` in `list.cljs`.
+2. Add new command entry:
+   - `[["list" "node"] :list-node ...]`
+3. Add CSV parser helper for selector options (`--tags` and `--properties`).
+4. Extend `invalid-options?` handling so `list node` enforces required filter presence without changing behavior of existing list subcommands.
+5. Wire `:list-node` through `commands.cljs` parse/build/execute branches.
+
+### B) Selector resolution strategy
+
+Resolve filters in CLI layer before invoking db-worker:
+
+- Tags:
+  - normalize token to typed selector (id/uuid/ident/name)
+  - resolve via existing tag resolver flow in `add.cljs`
+  - pass resolved tag ids to db-worker
+
+- Properties:
+  - extend resolver support to include uuid-based property lookup
+  - resolve to canonical property idents
+  - pass resolved property idents to db-worker
+
+This keeps db-worker focused on DB filtering, while CLI owns user-facing selector parsing/errors.
+
+### C) db-worker query strategy (`db_worker.cljs`)
+
+Add `list-nodes` function with options shape like:
+
+```clojure
+{:tag-ids [...]
+ :property-idents [...]
+ :expand true|false}
+```
+
+Implementation outline:
+
+1. Build candidate ordinary-node set (pages + blocks, excluding schema-definition entities).
+2. Apply tag intersection filter using `:block/tags` refs against resolved tag ids.
+3. Apply property-presence intersection filter by checking node datoms for each resolved property ident.
+4. Return minimal list item by default; include richer payload when `:expand true`.
+5. Include `:node/type` and block page context fields for downstream formatting/fields selection.
+
+### D) thread-api exposure (`db_core.cljs`)
+
+Add and wire:
+
+- `:thread-api/cli-list-nodes` -> `cli-db-worker/list-nodes`
+
+### E) Output formatting (`format.cljs`)
+
+Add `list-node` formatter branch with dedicated columns (including `TYPE`) and title width behavior identical to other list commands.
+
+### F) Completion/docs/e2e alignment
+
+Update:
+
+- command docs (`docs/cli/logseq-cli.md`)
+- command summary/help tests
+- optional completion tests if option specs affect completion surface
+- CLI e2e inventory/cases for new command coverage
+
+## Step-by-step implementation plan (TDD first)
+
+1. Add RED parser tests for `list node` command recognition and option parsing.
+2. Add RED validation tests asserting `list node` fails without `--tags` and `--properties`.
+3. Add RED tests for CSV parsing/normalization behavior for both filters.
+4. Add RED resolver tests for tag/property selectors covering id/uuid/ident/block-name.
+5. Add RED db-worker tests for node filtering semantics (all-of tags, all-of properties, combined AND).
+6. Implement resolver extensions (including property uuid support).
+7. Implement `list-node-spec`, command entry, action build, and execute path.
+8. Implement `cli-list-nodes` thread-api and `list-nodes` db-worker helper.
+9. Add/adjust formatter for human list-node output and structured output shape.
+10. Update command docs and e2e inventory/cases.
+11. Run focused tests, then full lint/test.
+
+## Files expected to change
+
+Core implementation:
+
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs` (property uuid resolution support)
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`
+
+Tests:
+
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/common/db_worker_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` (if option completion changes)
+
+Docs/e2e:
+
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`
+
+## Testing plan
+
+I will follow `@test-driven-development` and add failing tests before implementation changes.
+
+Focused verification commands:
+
+- `bb dev:test -v logseq.cli.commands-test`
+- `bb dev:test -v logseq.cli.common.db-worker-test`
+- `bb dev:test -v logseq.cli.format-test`
+- `bb dev:test -v logseq.cli.completion-generator-test` (if touched)
+- `bb -f cli-e2e/bb.edn test --skip-build` (if e2e specs changed)
+- `bb dev:lint-and-test`
+
+## Risks and mitigations
+
+Risk: property selector normalization can be ambiguous between ident and block-name.
+
+Mitigation: define deterministic precedence (id -> uuid -> explicit keyword ident -> block-name fallback) and lock with tests.
+
+Risk: filtering large graphs by multiple property idents can be slow.
+
+Mitigation: use set-intersection style filtering and limit payload in non-expand mode.
+
+Risk: “ordinary node” definition drift (schema entities leaking into output).
+
+Mitigation: encode explicit exclusion rules in db-worker tests.
+
+## Acceptance criteria
+
+1. `logseq list node` exists and is documented.
+2. It returns both block and page nodes (ordinary content nodes).
+3. `--tags` accepts comma-separated selectors and supports id/uuid/ident/block-name.
+4. `--properties` accepts comma-separated selectors and supports id/uuid/ident/block-name.
+5. At least one of `--tags` or `--properties` is required; otherwise command returns `:invalid-options`.
+6. Common list options (`--expand`, `--fields`, `--limit`, `--offset`, `--sort`, `--order`) are supported.
+7. Unit and e2e coverage is updated and green.
+
+## Open question
+
+No blocking question for this phase.
+
+---
diff --git a/docs/agent-guide/082-logseq-cli-upsert-task-option-cleanup.md b/docs/agent-guide/082-logseq-cli-upsert-task-option-cleanup.md
new file mode 100644
index 0000000000..1dc4ae4070
--- /dev/null
+++ b/docs/agent-guide/082-logseq-cli-upsert-task-option-cleanup.md
@@ -0,0 +1,274 @@
+# Logseq CLI `upsert task` Option Surface Cleanup Plan
+
+Goal: simplify `upsert task` into a task-focused command by removing generic tag/property mutation options, adding first-class `--deadline` / `--scheduled` options, and standardizing explicit clear semantics with `--no-status`, `--no-priority`, `--no-scheduled`, and `--no-deadline`.
+
+Architecture: keep the current `logseq-cli -> parse/build -> execute -> transport/invoke -> db-worker-node` flow, and **do not add new thread-api unless strictly necessary**.
+
+Architecture: this change should be implemented entirely in existing CLI command/build/execute logic (`upsert task`) and existing mutation endpoint (`:thread-api/apply-outliner-ops`), with no new db-worker-node API contract.
+
+Tech Stack: ClojureScript, `babashka.cli`, existing command modules under `src/main/logseq/cli/command/*`, existing CLI docs/e2e specs.
+
+Related:
+- `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/078-logseq-cli-task-subcommands.md`
+- `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/080-logseq-cli-status-option-cleanup.md`
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+
+## Problem statement
+
+Current `upsert task` still exposes generic mutation options:
+
+- `--update-tags`
+- `--update-properties`
+- `--remove-tags`
+- `--remove-properties`
+
+This overlaps with `upsert block`, which already serves as the general-purpose surface for tag/property updates/removals.
+
+At the same time, task-specific scheduling fields are missing as first-class options:
+
+- `--scheduled`
+- `--deadline`
+
+The command should become more cohesive:
+
+- task semantics stay in `upsert task` (status, priority, scheduled, deadline, and automatic `#Task` attachment)
+- generic tag/property mutations are done via `upsert block`
+- set/clear semantics are explicit and paired:
+  - set via `--status` / `--priority` / `--scheduled` / `--deadline`
+  - clear via `--no-status` / `--no-priority` / `--no-scheduled` / `--no-deadline`
+
+## Current baseline from implementation
+
+### 1) `upsert task` currently includes generic tag/property options
+
+`src/main/logseq/cli/command/upsert.cljs` currently defines these options in `upsert-task-spec`:
+
+- `:update-tags`
+- `:update-properties`
+- `:remove-tags`
+- `:remove-properties`
+
+### 2) `upsert task` execute path currently applies generic tag/property ops
+
+`execute-upsert-task-ops!` currently:
+
+- resolves update/remove tags and properties
+- merges task overrides (`status`, `priority`) into update properties
+- supports remove operations and guards against removing `#Task`
+
+### 3) Runtime status validation already uses existing `:thread-api/q`
+
+Status validation now relies on:
+
+- `src/main/logseq/cli/command/task_status.cljs`
+- query via existing `:thread-api/q`
+
+This should remain unchanged (no new thread-api needed).
+
+### 4) Task list/output already models `scheduled` and `deadline`
+
+Current list/format paths already include:
+
+- `:logseq.property/scheduled`
+- `:logseq.property/deadline`
+
+So adding write options in `upsert task` aligns with existing read/output behavior.
+
+## Scope
+
+In scope:
+
+1. Remove from `upsert task` option surface:
+   - `--update-tags`
+   - `--update-properties`
+   - `--remove-tags`
+   - `--remove-properties`
+2. Add to `upsert task` option surface:
+   - `--scheduled`
+   - `--deadline`
+   - `--no-status`
+   - `--no-priority`
+   - `--no-scheduled`
+   - `--no-deadline`
+3. Keep `status` runtime validation behavior as-is for `--status <value>` inputs (graph-derived values via existing `:thread-api/q`).
+4. Add explicit clear semantics: `--no-status`, `--no-priority`, `--no-scheduled`, and `--no-deadline` clear corresponding properties.
+5. Define and enforce conflict behavior: passing both set and clear for the same field (for example `--status X` + `--no-status`) is invalid and must return a clear validation error.
+6. Add migration guidance so removed task options point users to `upsert block`.
+7. Update tests/docs/e2e inventory to match the new option contract.
+
+Out of scope:
+
+- Any new thread-api endpoint.
+- Any schema/property/class additions.
+- Reworking `upsert block` behavior.
+- Introducing new date parser/normalizer infrastructure outside `upsert task` needs.
+
+## Design decisions
+
+### Decision A: `upsert task` becomes task-focused only
+
+Keep task-centric options:
+
+- selectors/targets: `--id`, `--uuid`, `--page`, `--content`, `--target-id`, `--target-uuid`, `--target-page`, `--pos`
+- task fields: `--status`, `--priority`, `--scheduled`, `--deadline`
+
+Remove generic options (`update/remove tags/properties`) from `upsert task`.
+
+### Decision B: Generic tag/property modifications are delegated to `upsert block`
+
+When users need:
+
+- `--update-tags`
+- `--update-properties`
+- `--remove-tags`
+- `--remove-properties`
+
+they should use `upsert block` on the target block/page id/uuid.
+
+### Decision C: Keep status runtime validation architecture, with explicit `--no-status` clear bypass
+
+`status` should continue using the existing runtime path for `--status <value>`:
+
+- query available status values from current graph via `:thread-api/q`
+- resolve/validate in `task_status.cljs`
+
+For `--no-status`, skip value resolution and clear `:logseq.property/status` directly.
+
+No additional thread-api is required.
+
+### Decision D: Paired set/clear options for task fields (`--field` and `--no-field`)
+
+`upsert task` will support direct set semantics:
+
+- `--status <value>` -> `:logseq.property/status` (resolved against graph statuses at runtime)
+- `--priority <value>` -> `:logseq.property/priority`
+- `--scheduled <value>` -> `:logseq.property/scheduled`
+- `--deadline <value>` -> `:logseq.property/deadline`
+
+And explicit clear semantics:
+
+- `--no-status` clears `:logseq.property/status`
+- `--no-priority` clears `:logseq.property/priority`
+- `--no-scheduled` clears `:logseq.property/scheduled`
+- `--no-deadline` clears `:logseq.property/deadline`
+
+Conflict rule: passing both set and clear for the same field in one command (for example `--status TODO` with `--no-status`) is invalid and must fail with a clear validation error.
+
+Implementation note: treat `--no-*` flags as explicit clear intent, and keep using existing mutation ops (`:batch-set-property` for set, `:batch-remove-property` for clear) without adding a new thread-api or a new global datetime validation subsystem.
+
+## Proposed implementation plan (TDD-first)
+
+1. Add RED parser tests asserting `upsert task` rejects removed options (`--update-tags`, `--update-properties`, `--remove-tags`, `--remove-properties`) with `:invalid-options`.
+2. Add RED parser/build tests asserting `upsert task` accepts `--scheduled` and `--deadline` in create/page/update modes.
+3. Add RED parser/build tests for clear semantics: `--no-status`, `--no-priority`, `--no-scheduled`, and `--no-deadline` are accepted and encoded as clear-intent (not invalid-option).
+4. Add RED parser/build tests for conflict behavior: set and clear for the same field in one command is invalid (`--status TODO` + `--no-status`, `--priority A` + `--no-priority`, etc.).
+5. Add RED execute tests asserting `upsert task`:
+   - writes `status`/`priority`/`scheduled`/`deadline` via batch property set ops,
+   - clears status/priority/scheduled/deadline via batch property remove ops when corresponding `--no-*` flag is present,
+   - still ensures `#Task` tag attachment.
+6. Update `upsert-task-spec` in `src/main/logseq/cli/command/upsert.cljs`:
+   - remove generic tag/property options
+   - add `:scheduled`, `:deadline`, `:no-status`, `:no-priority`, `:no-scheduled`, and `:no-deadline` options
+   - refresh examples to include paired set/clear usage.
+7. Refactor `build-task-action` in `upsert.cljs`:
+   - remove parsing/build wiring for removed generic options
+   - parse `--no-*` flags into clear intent for task properties
+   - validate set/no conflicts per field
+   - include scheduled/deadline in task property overrides map
+   - keep existing selector/target conflict validation.
+8. Refactor `execute-upsert-task-ops!` in `upsert.cljs`:
+   - remove user-driven update/remove tag/property resolution paths tied to removed options
+   - keep automatic `#Task` tag set
+   - apply only task property writes (`status`, `priority`, `scheduled`, `deadline`)
+   - add task property clear ops for `status`/`priority`/`scheduled`/`deadline` when clear intent is present.
+9. Update migration guidance in `src/main/logseq/cli/commands.cljs` so unknown upsert-task legacy options map to actionable messages (e.g. use `upsert block --update-properties`).
+10. Update completion/spec tests (`completion_generator_test.cljs`) to verify the new `upsert task` option surface.
+11. Update command behavior tests (`commands_test.cljs`, `upsert_test.cljs`) to remove old task-option assumptions and add paired set/clear assertions (including conflicts).
+12. Update CLI docs (`docs/cli/logseq-cli.md`) to reflect the new `upsert task` contract, explicit `--no-*` clear semantics, conflict behavior, and migration to `upsert block` for generic tag/property mutation.
+13. Update CLI e2e inventory/cases (`cli-e2e/spec/non_sync_inventory.edn`, `cli-e2e/spec/non_sync_cases.edn`) to remove deprecated task options and add cases covering `--scheduled` / `--deadline`, the full `--no-*` clear surface, and set/no conflict failures.
+14. Run focused tests and then broader checks.
+
+## Files expected to change
+
+Core implementation:
+
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+
+Tests:
+
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/upsert_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs`
+
+Docs/e2e:
+
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`
+
+Expected non-changes (unless implementation reveals an actual blocker):
+
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs`
+
+## Testing plan
+
+Follow `@test-driven-development` for this feature.
+
+Focused verification commands:
+
+- `bb dev:test -v logseq.cli.commands-test`
+- `bb dev:test -v logseq.cli.command.upsert-test`
+- `bb dev:test -v logseq.cli.completion-generator-test`
+- `bb -f cli-e2e/bb.edn test --skip-build` (if e2e specs changed)
+- `bb dev:lint-and-test`
+
+## Risks and mitigations
+
+Risk: existing scripts using removed `upsert task` generic options break.
+
+Mitigation:
+
+- add migration guidance in parse errors
+- update docs with explicit `upsert block` replacements
+- include e2e coverage for migration-safe paths
+
+Risk: ambiguity of accepted datetime string format for `--scheduled`/`--deadline`.
+
+Mitigation:
+
+- document expected input examples clearly
+- keep first implementation pass-through and avoid overfitting parser logic
+- add follow-up validation enhancement only if real failures appear
+
+Risk: users may pass both set and clear options for the same field (for example `--status TODO` and `--no-status`) and expect deterministic precedence.
+
+Mitigation:
+
+- define set/no-same-field combinations as explicit validation errors
+- add parser/build/execute tests locking conflict detection across all four fields
+- include explicit conflict examples in help/docs
+
+Risk: refactor accidentally drops guaranteed `#Task` tag attachment.
+
+Mitigation:
+
+- execute-level tests must assert task tag set op remains present for create/page/update modes
+
+## Acceptance criteria
+
+1. `upsert task` no longer exposes `--update-tags`, `--update-properties`, `--remove-tags`, `--remove-properties`.
+2. `upsert task` supports set semantics via `--status`, `--priority`, `--scheduled`, and `--deadline`.
+3. `upsert task` supports explicit clear semantics via `--no-status`, `--no-priority`, `--no-scheduled`, and `--no-deadline`.
+4. Passing both set and clear options for the same field in one command is rejected with a clear validation error.
+5. `upsert task` continues to support status runtime validation using existing `:thread-api/q` flow for `--status <value>` inputs.
+6. Generic tag/property modifications for task nodes are clearly migrated to `upsert block` (guidance + docs).
+7. No new thread-api is introduced unless a hard blocker is discovered.
+8. Unit tests and CLI e2e specs are updated and passing for changed behavior.
+
+## Open question
+
+No blocking question.
+
+---
diff --git a/docs/agent-guide/083-logseq-cli-skill-command.md b/docs/agent-guide/083-logseq-cli-skill-command.md
new file mode 100644
index 0000000000..a255b05dfd
--- /dev/null
+++ b/docs/agent-guide/083-logseq-cli-skill-command.md
@@ -0,0 +1,248 @@
+# Logseq CLI `skill` Subcommand Implementation Plan
+
+Goal: add a new `skill` utility command group so users and agents can print and install the built-in `logseq-cli` skill file with predictable local and global destinations.
+
+Architecture: keep all behavior in the existing CLI pipeline (`parse-args -> build-action -> execute -> format-result`) and treat `skill` as a pure local filesystem utility command that does not require graph resolution or `db-worker-node` server startup.
+
+Architecture: reuse current command wiring patterns from `completion` and `example`, and keep `db-worker-node` API and thread-api surface unchanged.
+
+Tech Stack: ClojureScript, `babashka.cli`, Node.js `fs/path/os`, existing command modules under `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command`, and existing CLI unit plus cli-e2e harness.
+
+Related: builds on `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/070-logseq-cli-example-subcommand.md`, `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/073-logseq-cli-debug-command.md`, `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/036-db-worker-node-ncc-bundling.md`, and `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`.
+
+## Problem statement
+
+The current CLI has utility commands (`completion`, `example`, `debug`) but no direct way to print or install the Logseq CLI skill definition for agent tooling.
+
+Users currently need to locate repository files manually, and installed package environments may not expose a documented command path for this content.
+
+We need a first-class command group under Utilities:
+
+- `logseq skill show` to print `logseq-cli` skill markdown.
+- `logseq skill install` to install into `./.agents/skills/logseq-cli`.
+- `logseq skill install --global` to install into `~/.agents/skills/logseq-cli`.
+
+## Current baseline from implementation
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` controls top-level help grouping and currently has `Utilities` with `completion`, `debug`, and `example` as top-level-only entries.
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` is the central integration point for command entry registration, parse-time validation, action building, and execute dispatch.
+
+The CLI command pipeline already supports utility commands that do not call `db-worker-node`.
+
+`completion` and `example` are implemented as CLI-local behaviors and are good templates for the new `skill` command.
+
+`/Users/rcmerci/gh-repos/logseq/skills/logseq-cli/SKILL.md` is the current source skill file in this repository.
+
+`/Users/rcmerci/gh-repos/logseq/package.json` currently publishes `dist/` and `static/logseq-cli.js`, so additional runtime source file availability for installed package use must be defined explicitly.
+
+## Scope
+
+In scope.
+
+Add `skill` command group with subcommands `show` and `install`.
+
+Add `--global` flag on `skill install`.
+
+Show `skill` in top-level `Utilities` help and keep subcommands hidden from global help.
+
+Add unit tests for parse, action, execute, and help rendering.
+
+Add completion tests for `skill` command/subcommands.
+
+Add cli-e2e non-sync coverage for show and local install behavior.
+
+Update CLI docs with usage and examples.
+
+Out of scope.
+
+Any new `db-worker-node` thread-api or HTTP invoke contract.
+
+Any graph mutation, server lifecycle behavior, or sync/auth behavior changes.
+
+Any new agent framework abstraction beyond requested install targets.
+
+## Proposed behavior contract
+
+| Command | Behavior |
+| --- | --- |
+| `logseq skill show` | Reads bundled `logseq-cli` skill markdown and prints raw markdown text to stdout regardless of `--output` mode. |
+| `logseq skill install` | Creates `./.agents/skills/logseq-cli` and installs `./.agents/skills/logseq-cli/SKILL.md`. |
+| `logseq skill install --global` | Creates `~/.agents/skills/logseq-cli` and installs `~/.agents/skills/logseq-cli/SKILL.md`. |
+| `logseq --help` | Shows `skill` under `Utilities`, while hiding `skill show` and `skill install` in top-level listing. |
+| `logseq skill` | Shows group help with `skill show` and `skill install`. |
+
+## Packaging and runtime file strategy
+
+The command must work in both repository development and packaged CLI environments.
+
+I will keep the source of truth as `/Users/rcmerci/gh-repos/logseq/skills/logseq-cli/SKILL.md`.
+
+I will add packaging support so installed CLI can still locate this file without repository checkout assumptions.
+
+I will prefer a minimal packaging update by including the skill file path in `/Users/rcmerci/gh-repos/logseq/package.json` `files` list.
+
+I will add a runtime path resolver in the new command module that resolves from CLI runtime directory and returns a clear typed error when the skill file is missing.
+
+I will keep this independent from `db-worker-node` bundle manifests because this feature is CLI-local and does not need daemon asset lifecycle semantics.
+
+## Architecture sketch
+
+```text
+argv
+  -> logseq.cli.commands/parse-args
+  -> logseq.cli.commands/build-action
+  -> logseq.cli.commands/execute
+      -> skill-command/execute-skill-*
+          -> fs/path/os local operations only
+  -> logseq.cli.format/format-result
+  -> stdout
+```
+
+```text
+No graph required.
+No server ensure/start.
+No transport/invoke.
+No db-worker-node thread-api change.
+```
+
+## Testing Plan
+
+I will follow `@test-driven-development` and write failing tests before implementation.
+
+I will add parser and help tests that prove `skill` appears in Utilities top-level help while `skill show` and `skill install` stay hidden there.
+
+I will add parser tests for `skill show`, `skill install`, and `skill install --global` success paths.
+
+I will add parser validation tests for invalid combinations and unknown options.
+
+I will add build-action tests that verify default local target resolution and global home-directory resolution.
+
+I will add execute tests that verify local install creates destination directories and writes expected file content.
+
+I will add execute tests for overwrite behavior and error behavior on unreadable source or unwritable destination.
+
+I will add completion generator tests that verify `skill` group and subcommands are present in zsh and bash output.
+
+I will add cli-e2e non-sync cases for `skill show` and local `skill install` using a temp working directory.
+
+I will update docs tests or snapshots only if existing harness requires it.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## TDD implementation steps
+
+1. Add failing tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for top-level help visibility under `Utilities` and group help for `skill`.
+
+2. Add failing parse tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` for `skill show`, `skill install`, and `skill install --global`.
+
+3. Add a new failing command test file `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/skill_test.cljs` covering source path resolution, install target resolution, and write/copy behavior.
+
+4. Add failing completion tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` for `skill` command coverage.
+
+5. Implement new command namespace `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/skill.cljs` with entries, action builders, and execute functions.
+
+6. Wire the new namespace into `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` for table registration, build-action cases, and execute dispatch.
+
+7. Update `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` Utilities group to include `skill` as top-level-only with a stable description override.
+
+8. Update `/Users/rcmerci/gh-repos/logseq/package.json` `files` list to include the published skill source path needed by packaged CLI runtime.
+
+9. Add cli-e2e inventory and cases in `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` and `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` for `skill show` and local install.
+
+10. Update `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` command reference and examples for `skill`.
+
+11. Run focused test commands and then full `bb dev:lint-and-test`.
+
+## Detailed file-by-file change map
+
+| File | Change |
+| --- | --- |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/skill.cljs` | New command module with `entries`, source resolver, destination resolver, `build-action`, and execute functions for show/install. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs` | Register `skill` entries and add build/execute dispatch branches for `:skill-show` and `:skill-install`. |
+| `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs` | Add `skill` to Utilities top-level group and description override. |
+| `/Users/rcmerci/gh-repos/logseq/package.json` | Include skill markdown path in publishable files to support packaged CLI runtime. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` | Add help/parse/build tests for `skill` group and options. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/skill_test.cljs` | New tests for resolver, install path logic, write behavior, and error handling. |
+| `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs` | Add completion assertions for `skill` group and `show`/`install` subcommands. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn` | Add `skill` command metadata. |
+| `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` | Add executable non-sync behavior cases for show and local install. |
+| `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md` | Document `skill show`, `skill install`, and `--global` semantics. |
+
+## Command output contract
+
+`skill show` should always print exact markdown payload to stdout so users can pipe it directly.
+
+`skill show` should ignore output format differences and keep markdown output even when `--output json` or `--output edn` is passed.
+
+`skill install` in human output should print installed path and source path.
+
+`skill install` in json or edn output can keep existing CLI structured conventions.
+
+## Edge cases and expected handling
+
+| Scenario | Expected behavior |
+| --- | --- |
+| Packaged CLI cannot find source skill file. | Return typed error with actionable message and checked path list. |
+| Local install destination already exists. | Overwrite installed skill file to keep command idempotent. |
+| Destination path is a file, not directory. | Return typed install error with destination path detail. |
+| `--global` used when home directory cannot be resolved. | Return typed error indicating home directory resolution failure. |
+| Running `skill show` with `--output json` or `--output edn`. | Still output raw markdown text exactly as `skill show` default behavior. |
+| Running command from read-only current working directory. | Return write-permission error and do not partially install. |
+
+## Verification commands
+
+```bash
+bb dev:test -v logseq.cli.commands-test
+bb dev:test -v logseq.cli.command.skill-test
+bb dev:test -v logseq.cli.completion-generator-test
+bb -f cli-e2e/bb.edn test --skip-build
+bb dev:lint-and-test
+```
+
+Expected outcomes.
+
+`commands-test`, `skill-test`, and completion tests pass with zero failures and zero errors.
+
+Non-sync e2e includes `skill` cases and passes in `--skip-build` mode after artifacts are present.
+
+`bb dev:lint-and-test` remains green.
+
+## Rollout and compatibility notes
+
+This feature is additive and does not break existing command paths.
+
+No db-worker server behavior changes are introduced.
+
+No schema changes are introduced.
+
+CLI users gain a portable way to acquire the built-in `logseq-cli` skill content.
+
+## Testing Details
+
+I will add behavior-focused parser, help, execute, and e2e tests that assert user-visible command contracts, not internal helper implementation details.
+
+I will ensure tests verify destination path semantics (`./.agents/...` and `~/.agents/...`), raw markdown show output, and explicit overwrite behavior.
+
+## Implementation Details
+
+- Add a dedicated `skill` command namespace instead of embedding logic in `commands.cljs`.
+- Keep source-of-truth content in `skills/logseq-cli/SKILL.md`.
+- Ensure packaged CLI can resolve source file by updating publish file list.
+- Add explicit typed error codes for source missing and install write failures.
+- Keep Utilities top-level summary behavior consistent with existing top-level-only commands.
+- Keep command design DRY by following `completion` and `example` patterns.
+- Keep behavior YAGNI by installing only requested `logseq-cli` skill.
+- Keep thread-api untouched and avoid any db-worker-node transport calls.
+- Document usage and path semantics in CLI docs.
+- Validate with unit tests first and cli-e2e second.
+
+## Decisions confirmed
+
+Installed filename is `SKILL.md`.
+
+Install behavior overwrites existing destination file.
+
+`skill show` always outputs markdown text regardless of `--output` option value.
+
+---
diff --git a/docs/agent-guide/084-logseq-cli-server-cleanup.md b/docs/agent-guide/084-logseq-cli-server-cleanup.md
new file mode 100644
index 0000000000..6968f71435
--- /dev/null
+++ b/docs/agent-guide/084-logseq-cli-server-cleanup.md
@@ -0,0 +1,217 @@
+# 084 — Replace `server status` with `server cleanup` for revision-mismatch processes
+
+## Summary
+
+This plan updates the CLI server command set by removing `server status` and adding `server cleanup`.
+
+`server cleanup` will terminate discovered `db-worker-node` processes that are both:
+
+- owned by `:cli`
+- revision-mismatched with the current CLI revision
+
+The implementation will reuse current `logseq-cli` and `db-worker-node` lifecycle primitives:
+
+- server discovery from lock files (`logseq.cli.server/list-servers`)
+- revision metadata persisted in locks by db-worker-node (`:revision`)
+- shutdown/kill paths already used by server stop/restart flows
+
+## Requested behavior changes
+
+1. Remove `logseq server status --graph <name>`.
+2. Add `logseq server cleanup`.
+3. `server cleanup` kills only discovered `:cli`-owned server processes where `server revision != current CLI revision`.
+
+## Current baseline
+
+- `server` command entries are defined in `src/main/logseq/cli/command/server.cljs` and currently include `list/status/start/stop/restart`.
+- CLI parse/build/execute routing is centralized in `src/main/logseq/cli/commands.cljs`.
+- Running server discovery already includes revision in `src/main/logseq/cli/server.cljs` (`list-servers` returns `:revision`).
+- Revision mismatch semantics already exist and use exact string comparison (`compute-revision-mismatches`).
+- db-worker-node writes revision into lock metadata in `src/main/frontend/worker/db_worker_node_lock.cljs`; legacy locks may have missing revision.
+
+## Product decisions (locked)
+
+1. **`server status` is removed, not deprecated.**
+   - No alias.
+   - Parsing `server status` should fail as unknown command after removal.
+
+2. **Mismatch rule remains exact string comparison.**
+   - If `cli-revision != server-revision`, it is a mismatch.
+   - `nil`/missing server revision is treated as mismatch.
+
+3. **Cleanup scope is discovered servers in current data-dir.**
+   - Source of truth is lock-file-backed discovery from `list-servers`.
+   - We do not add global OS-wide process scanning for all possible data dirs.
+
+4. **Cleanup ownership scope is `:cli` only.**
+   - Cleanup targets only servers where `:owner-source` is `:cli`.
+   - Mismatched servers owned by `:electron` (or other owners) are reported but not terminated.
+
+5. **Termination strategy is graceful-first for eligible targets.**
+   - Attempt graceful shutdown first.
+   - Fallback to process kill if needed.
+
+## CLI contract for `server cleanup`
+
+### Command surface
+
+- New command: `logseq server cleanup`
+- No `--graph` required.
+- Works with existing global options (`--data-dir`, `--config`, `--output`, etc.).
+
+### Result shape (proposed)
+
+Return structured data for stable JSON/EDN automation:
+
+- `:cli-revision`
+- `:checked` (count of discovered servers)
+- `:mismatched` (count)
+- `:eligible` (count of mismatched servers with `:owner-source :cli`)
+- `:skipped-owner` (mismatched servers not owned by `:cli`)
+- `:killed` (servers/pids successfully terminated)
+- `:failed` (servers/pids that could not be terminated)
+
+Human output should summarize counts and list failed targets if any.
+
+## Implementation design
+
+### 1) Remove `server status` wiring
+
+- Remove `server status` entry from `command/server.cljs`.
+- Remove `:server-status` branches in:
+  - parse-time graph-required validation set
+  - build-action dispatch
+  - execute dispatch
+- Remove status-specific formatter branch/tests.
+
+### 2) Add `server cleanup` command entry and action
+
+In `command/server.cljs`:
+
+- Add entry `['server' 'cleanup']` with description and example.
+- Add `build-action` branch for `:server-cleanup` (no repo requirement).
+- Add executor `execute-cleanup`.
+
+In `commands.cljs`:
+
+- Route `:server-cleanup` in build-action and execute.
+- Ensure graph-required command set excludes cleanup.
+
+### 3) Add cleanup orchestration in `logseq.cli.server`
+
+Introduce a new function (e.g. `cleanup-revision-mismatched-servers!`) that:
+
+1. resolves CLI revision (`logseq.cli.version/revision`, passed from command layer)
+2. calls `list-servers`
+3. computes mismatches using existing exact compare helper
+4. partitions mismatches into eligible (`:owner-source :cli`) vs skipped-owner targets
+5. terminates each eligible mismatched server process
+6. removes stale locks when PID no longer exists
+7. returns structured result data
+
+Implementation should reuse existing stop/shutdown logic where possible to avoid duplicate lifecycle behavior.
+
+### 4) Ownership-aware termination behavior
+
+Cleanup must not bypass ownership rules globally; it should only target mismatched servers owned by `:cli`.
+
+Recommended approach:
+
+- Filter mismatch targets to `:owner-source :cli` before termination.
+- Reuse existing stop/shutdown flow for eligible targets.
+- Keep existing owner-aware behavior unchanged for `stop`/`restart`.
+- Report non-CLI mismatched servers in `:skipped-owner` for visibility.
+
+### 5) Formatting and docs
+
+- Add human formatting branch for `:server-cleanup` in `format.cljs`.
+- Remove obsolete `:server-status` human formatting and associated tests.
+- Update CLI docs and examples in `docs/cli/logseq-cli.md`.
+
+## File scope (expected)
+
+- `src/main/logseq/cli/command/server.cljs`
+- `src/main/logseq/cli/commands.cljs`
+- `src/main/logseq/cli/server.cljs`
+- `src/main/logseq/cli/format.cljs`
+- `src/main/logseq/cli/command/core.cljs` (if help grouping text needs update)
+- `src/test/logseq/cli/commands_test.cljs`
+- `src/test/logseq/cli/command/server_test.cljs`
+- `src/test/logseq/cli/server_test.cljs`
+- `src/test/logseq/cli/format_test.cljs`
+- `cli-e2e/spec/non_sync_inventory.edn`
+- `cli-e2e/spec/non_sync_cases.edn`
+- `docs/cli/logseq-cli.md`
+
+## TDD execution plan
+
+1. Add failing parse/build tests for removing `server status` and adding `server cleanup`.
+2. Add failing command execute tests for cleanup action wiring.
+3. Add failing server lifecycle tests for mismatch selection and termination behavior.
+4. Add failing formatter tests for new human cleanup output and remove status output expectations.
+5. Implement command and server orchestration changes.
+6. Update docs and cli-e2e inventory/cases.
+7. Run focused tests, then full lint+test.
+
+## Testing plan
+
+### Unit tests
+
+- `commands_test.cljs`
+  - `server status` becomes unknown command.
+  - `server cleanup` parses/builds/dispatches.
+  - cleanup does not require `--graph`.
+
+- `command/server_test.cljs`
+  - cleanup execute returns structured summary.
+  - mismatch semantics remain exact compare.
+
+- `server_test.cljs`
+  - cleanup kills only mismatched revision servers with `:owner-source :cli`.
+  - mismatched servers owned by non-CLI owners are reported in `:skipped-owner` and remain untouched.
+  - matching revision servers are untouched.
+  - missing revision is treated as mismatch.
+  - failures are reported in `:failed`.
+
+- `format_test.cljs`
+  - human cleanup output includes counts and failure lines.
+  - status formatting tests removed/replaced.
+
+### CLI E2E
+
+- Remove `server status` coverage case.
+- Add `server cleanup` coverage case (at least smoke path with zero or controlled mismatches).
+- Update non-sync inventory command list under `:server`.
+
+### Verification commands
+
+```bash
+bb dev:test -v logseq.cli.commands-test
+bb dev:test -v logseq.cli.command.server-test
+bb dev:test -v logseq.cli.server-test
+bb dev:test -v logseq.cli.format-test
+bb -f cli-e2e/bb.edn test --skip-build
+bb dev:lint-and-test
+```
+
+## Risks and mitigations
+
+- **Risk:** Ownership metadata may be missing/legacy (`:unknown`) and reduce cleanup coverage.
+  - **Mitigation:** keep cleanup intentionally strict (`:cli` only) and report skipped-owner targets explicitly for operator follow-up.
+
+- **Risk:** Legacy locks without revision cause aggressive cleanup.
+  - **Mitigation:** keep behavior intentional and documented (`missing revision = mismatch`).
+
+- **Risk:** Duplicate stop logic divergence.
+  - **Mitigation:** reuse existing stop/shutdown flow for `:cli`-owned targets and keep ownership filtering in one cleanup helper.
+
+## Acceptance criteria
+
+1. `logseq server status ...` is no longer available.
+2. `logseq server cleanup` exists and executes without `--graph`.
+3. Cleanup terminates only discovered mismatch servers with `:owner-source :cli` (`server revision != CLI revision`).
+4. Mismatched servers with non-CLI ownership are not terminated and are reported as `:skipped-owner`.
+5. Matching-revision servers are not terminated.
+6. Structured JSON/EDN output reports `checked/mismatched/eligible/skipped-owner/killed/failed` summaries.
+7. Human output is clear and actionable.
+8. Unit tests and relevant cli-e2e coverage are updated and passing.
diff --git a/docs/agent-guide/085-logseq-cli-list-upsert-asset.md b/docs/agent-guide/085-logseq-cli-list-upsert-asset.md
new file mode 100644
index 0000000000..00d1849258
--- /dev/null
+++ b/docs/agent-guide/085-logseq-cli-list-upsert-asset.md
@@ -0,0 +1,290 @@
+# Logseq CLI `list asset` and `upsert asset` Plan
+
+Goal: add first-class asset commands to `logseq-cli` with current architecture constraints:
+
+1. Avoid introducing a new db-worker `thread-api` unless absolutely necessary.
+2. Add `list asset` to list asset nodes.
+3. Add `upsert asset` to create/update asset nodes, including create-time `--path <asset-file-path>` and shared `--content` behavior.
+4. Use the product definition of asset as **a node tagged with `#Asset`** (`:logseq.class/Asset`).
+
+Architecture direction: keep the existing `CLI -> command parse/build -> transport/invoke -> db-worker-node` pipeline, and reuse existing `list node` and `upsert block` flows as much as possible.
+
+Related files:
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/handler/editor.cljs`
+- `/Users/rcmerci/gh-repos/logseq/deps/db/src/logseq/db/frontend/class.cljs`
+- `/Users/rcmerci/gh-repos/logseq/deps/db/src/logseq/db/frontend/asset.cljs`
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+
+---
+
+## Current baseline (from codebase)
+
+### 1) Listing path is already sufficient for asset filtering
+
+- `list node` already resolves tag/property selectors and invokes `:thread-api/cli-list-nodes`.
+- db-worker already supports node filtering by tag IDs via `logseq.cli.common.db-worker/list-nodes`.
+- `:thread-api/cli-list-nodes` already exists in `frontend.worker.db_core`.
+
+Implication: `list asset` can be implemented as a thin wrapper over existing `list node` behavior by injecting the fixed `:logseq.class/Asset` selector. No new thread API required.
+
+### 2) Upsert path already has reusable create/update building blocks
+
+- `upsert block` already supports create/update mode split, target placement options, and `--content` semantics.
+- Existing helpers already resolve IDs/UUIDs, run outliner ops, and handle error normalization.
+
+Implication: `upsert asset` should reuse upsert/add internals, while adding asset-specific validation and metadata/file handling.
+
+### 3) Desktop/web app asset behavior to align with
+
+- `:logseq.class/Asset` exists as built-in class (`deps/db/.../class.cljs`).
+- Desktop creation (`new-asset-block`) sets:
+  - `:block/tags #{(:db/id (db/entity :logseq.class/Asset))}`
+  - `:logseq.property.asset/type`
+  - `:logseq.property.asset/size`
+  - `:logseq.property.asset/checksum`
+  - optional title override
+- Asset type/title helpers exist in `logseq.db.frontend.asset` (`asset-path->type`, `asset-name->title`).
+
+Implication: CLI create flow should follow the same shape for metadata/tagging and content/title semantics.
+
+---
+
+## Proposed command contracts
+
+## `list asset`
+
+### Syntax
+
+```text
+logseq list asset --graph <name> [options]
+```
+
+### Semantics
+
+- Returns nodes tagged with `#Asset` (`:logseq.class/Asset`).
+- Uses existing list-node backend filtering path.
+
+### Options (aligned with current list family)
+
+- `--fields <csv>`
+- `--limit <n>`
+- `--offset <n>`
+- `--sort <field>` (default `updated-at`)
+- `--order asc|desc`
+- `--expand`
+
+### Initial field map
+
+Keep MVP aligned with `list node`:
+
+- `id` -> `:db/id`
+- `title` -> `:block/title`
+- `type` -> `:node/type`
+- `page-id` -> `:block/page-id`
+- `page-title` -> `:block/page-title`
+- `created-at` -> `:block/created-at`
+- `updated-at` -> `:block/updated-at`
+
+---
+
+## `upsert asset`
+
+### Syntax
+
+Create mode:
+
+```text
+logseq upsert asset --graph <name> --path <asset-file-path> [--content <text>] [--target-page <name>|--target-id <id>|--target-uuid <uuid>] [--pos first-child|last-child|sibling]
+```
+
+Update mode:
+
+```text
+logseq upsert asset --graph <name> (--id <id>|--uuid <uuid>) [--content <text>]
+```
+
+### Mode rules
+
+- `--id` or `--uuid` => update mode.
+- otherwise => create mode.
+
+### Required/allowed options
+
+- `--path` is supported in create mode and required for create mode MVP.
+- `--content` is supported in both create and update modes.
+- In create mode, target options and `--pos` follow existing upsert block behavior.
+- In update mode, `--path`, target options, and `--pos` are invalid.
+
+### Asset definition and validation
+
+- Asset identity is tag-based: node must include `#Asset` (`:logseq.class/Asset`).
+- Update mode must verify target node is asset-tagged; otherwise return typed mismatch error.
+
+### Create-time metadata behavior
+
+Given `--path`:
+
+- derive `asset-type` from extension (same as `asset-path->type`)
+- read file size from filesystem
+- compute SHA-256 checksum
+- ensure created node has `#Asset` tag and metadata:
+  - `:logseq.property.asset/type`
+  - `:logseq.property.asset/size`
+  - `:logseq.property.asset/checksum`
+- copy file into graph assets directory as `<block-uuid>.<asset-type>`
+
+### `--content` behavior
+
+- create mode: sets block title (same semantics as regular block upsert content)
+- update mode: rewrites block title
+- if create mode omits `--content`, default title comes from file basename (without extension), matching desktop behavior
+
+---
+
+## Key design decisions
+
+1. **No new thread-api in MVP**
+   - `list asset` uses current `:thread-api/cli-list-nodes`.
+   - `upsert asset` uses current pull/apply-outliner APIs and CLI-side filesystem handling.
+
+2. **Thin list command implementation**
+   - Implement `list asset` by reusing list-node execution with fixed asset tag selector.
+
+3. **CLI-side file copy for `--path`**
+   - Use existing Node runtime capabilities in CLI layer (`fs`, `path`, `crypto`) and existing repo/data-dir helpers.
+   - Avoid adding db-worker API solely for file copy.
+
+4. **Asset identity remains tag-first**
+   - `#Asset` is the canonical selector for list/upsert identity checks.
+
+---
+
+## Implementation plan (phased)
+
+### Phase 1: parser and contract tests (RED)
+
+1. Add parser tests for `list asset` command recognition and options.
+2. Add parser tests for `upsert asset` create/update forms.
+3. Add validation tests:
+   - create mode requires `--path`
+   - update mode rejects `--path`
+   - update mode allows `--content`
+   - create/update mutual exclusion errors are clear.
+4. Add help/summary tests to ensure `list asset` and `upsert asset` appear consistently.
+
+Primary file:
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
+
+### Phase 2: implement `list asset`
+
+1. Add `list-asset` command spec and entry in `command/list.cljs`.
+2. Reuse list-node field map/options and execute path with fixed asset tag selector.
+3. Wire `:list-asset` in `commands.cljs` validation/build/execute branches.
+4. Add formatter branch in `format.cljs`, reusing node table layout.
+
+Primary files:
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`
+
+### Phase 3: implement `upsert asset`
+
+1. Add `upsert-asset` option spec + command entry in `command/upsert.cljs`.
+2. Implement build logic:
+   - mode detection by id/uuid
+   - create-mode path validation
+   - update-mode selector validation
+3. Implement execute logic:
+   - create mode:
+     - prepare metadata from `--path`
+     - create block (reusing add/upsert block path)
+     - ensure `#Asset` tag + required asset properties
+     - copy file into graph `assets/`
+   - update mode:
+     - resolve node by id/uuid
+     - enforce asset tag membership
+     - apply content update when provided
+4. Keep all DB writes via existing thread-api calls.
+
+Primary files:
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`
+
+### Phase 4: tests and docs/e2e
+
+1. Add/extend unit tests for upsert asset builder/executor behavior.
+2. Add format tests for list/upsert asset human output.
+3. Update CLI docs and command reference.
+4. Update CLI e2e inventory and add non-sync cases:
+   - `upsert asset --path ...` create
+   - `upsert asset --id|--uuid --content ...` update
+   - `list asset` returns asset nodes
+
+Primary files:
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/upsert_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`
+
+---
+
+## Verification plan
+
+Focused tests:
+
+```bash
+bb dev:test -v logseq.cli.commands-test
+bb dev:test -v logseq.cli.command.upsert-test
+bb dev:test -v logseq.cli.format-test
+```
+
+CLI e2e:
+
+```bash
+bb -f cli-e2e/bb.edn test --skip-build
+```
+
+Full regression:
+
+```bash
+bb dev:lint-and-test
+```
+
+---
+
+## Acceptance criteria
+
+1. `logseq list asset` is available and lists nodes tagged `#Asset`.
+2. `list asset` supports list-family options consistent with current commands.
+3. `logseq upsert asset` exists with create/update modes.
+4. `upsert asset` create mode supports `--path <asset-file-path>`.
+5. `--content` works in both create and update modes.
+6. Update mode enforces that target node is an asset (`#Asset`).
+7. MVP introduces no new db-worker thread-api unless a hard blocker is discovered.
+8. Unit tests + CLI e2e coverage are updated and passing.
+
+---
+
+## Risks and mitigations
+
+- **Risk:** create flow can leave DB/file inconsistencies on partial failure.
+  - **Mitigation:** implement best-effort rollback/cleanup order and test failure paths.
+
+- **Risk:** internal asset properties are not public and bypassing generic property parsers may be required.
+  - **Mitigation:** use dedicated asset metadata writing path with explicit property identifiers, not generic user property input.
+
+- **Risk:** ambiguity around whether create mode should allow asset node creation without `--path`.
+  - **Mitigation:** lock MVP contract to require `--path` in create mode; broaden later only if product needs it.
+
+---
+
+No blocking open question for MVP.
\ No newline at end of file
diff --git a/docs/agent-guide/086-logseq-cli-humanize-output.md b/docs/agent-guide/086-logseq-cli-humanize-output.md
new file mode 100644
index 0000000000..bdd4a283c2
--- /dev/null
+++ b/docs/agent-guide/086-logseq-cli-humanize-output.md
@@ -0,0 +1,209 @@
+# 086 — Introduce `org.clj-commons/humanize` for logseq-cli human output
+
+## Goal
+
+Adopt `org.clj-commons/humanize` in `logseq-cli` to improve readability and consistency of **human-mode** output while keeping `json` and `edn` output stable.
+
+This plan is based on the current implementation of:
+
+- CLI output layer: `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`
+- CLI command message producers: `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/*.cljs`
+- db-worker-node sync progress producers used by CLI: `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/download.cljs` and `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/sync/upload.cljs`
+
+---
+
+## Scope and constraints
+
+### In scope
+
+1. Add `org.clj-commons/humanize` dependency for CLI/runtime code paths.
+2. Replace ad-hoc human text formatting in CLI human output with library-backed helpers where it improves readability.
+3. Audit all practical human-output points that can benefit from this library and prioritize them.
+4. Keep output changes focused on `--output human` behavior.
+
+### Out of scope
+
+1. Changing `json` or `edn` payload schemas.
+2. Any `db-worker-node` code change (including sync progress message producers and thread-api payload changes).
+3. Rewriting CLI table layout/alignment logic (`string-width`, truncation, padding).
+4. Internationalization (the library is English-first and current CLI output is also English).
+
+### Locked decisions
+
+1. Keep relative time in short style (compatible with current `10s ago` / `1m ago` style).
+2. `list asset` `SIZE` displays human-readable size only (no extra raw-byte suffix).
+3. Apply grouped-number formatting consistently for `Count:` values.
+4. Formatter-only scope: do not modify any `db-worker-node` code.
+
+---
+
+## Why `org.clj-commons/humanize`
+
+Useful functions for current CLI needs:
+
+- `clj-commons.humanize/intcomma` for grouped numbers (`12,345`).
+- `clj-commons.humanize/filesize` for byte formatting (`2.0KiB`, `3.0MB`).
+- `clj-commons.humanize/relative-datetime` for relative time strings.
+- `clj-commons.humanize.inflect/pluralize-noun` for singular/plural grammar.
+- `clj-commons.humanize/oxford` for readable list joining in error/help text.
+
+---
+
+## Current baseline and optimization inventory
+
+## A) Central formatter (`format.cljs`) — highest impact
+
+| Area | Current behavior | Candidate improvement with `humanize` | Priority |
+|---|---|---|---|
+| `human-ago` for `UPDATED-AT`/`CREATED-AT` columns and graph metadata | Custom `s/m/h/d/mo/y ago` calculation with fixed month/year heuristics | Replace with `relative-datetime` brief mode via a wrapper to keep compact style | P0 |
+| `format-counted-table` (`Count: N`) used by list/search/query/server/graph tables | Raw integer | Use `intcomma` consistently for all `Count:` values | P0 |
+| `list asset` `SIZE` column | Raw bytes integer | Show human-readable size only (`filesize`, e.g. `2.0KiB`) | P0 |
+| `format-sync-status` pending counters and tx values | Raw numbers | `intcomma` for counters/tx ids | P1 |
+| `format-server-cleanup` summary counters | Raw numbers | `intcomma` + optional noun pluralization cleanup | P1 |
+| `format-upsert-block` change counts and `format-remove-block` multi-id count | Raw counts | `intcomma` for counts | P1 |
+| Graph-list legacy warning line (`Warning: N legacy graph directories detected.`) | Raw count with hardcoded noun | `intcomma` + `pluralize-noun` | P1 |
+
+## B) Command-level message producers (`command/*.cljs`)
+
+| File | Current behavior | Candidate improvement | Priority |
+|---|---|---|---|
+| `command/doctor.cljs` (`check-running-servers`, `check-server-revision-mismatch`) | Manual pluralization (`server`/`servers`, `uses`/`use`) | Use `pluralize-noun` (and centralized verb helper if needed) | P0 |
+| `command/graph.cljs` (`format-validation-errors`) | Manual `entity/entities` + raw count | `intcomma` + `pluralize-noun` | P0 |
+| `command/example.cljs` (`Found N examples ...`) | Raw count | `intcomma` + `pluralize-noun` | P1 |
+| `command/show.cljs` (`Linked References (N)`, `Referenced Entities (N)`) | Raw count | `intcomma` for large refs count | P1 |
+| `command/sync.cljs` (`missing required sync config ...`) | Comma-joined key list | Optionally use `oxford` for clearer list text | P2 |
+
+## C) Audited but excluded by current scope decision
+
+| File | Current behavior | Candidate improvement | Decision |
+|---|---|---|---|
+| `frontend/worker/sync/download.cljs` (`Importing data X/Y`) | Raw counters in message string | Could use `intcomma` for `X` and `Y` | Excluded (no db-worker changes) |
+| `frontend/worker/sync/upload.cljs` (`Uploading X/Y`) | Raw counters in message string | Could use `intcomma` for `X` and `Y` | Excluded (no db-worker changes) |
+
+## D) Candidate but likely keep as-is for now
+
+| File | Current behavior | Decision |
+|---|---|---|
+| `src/main/logseq/cli/profile.cljs` | Technical `Nms` tree output for profiling | Keep as technical output; do not humanize in phase 1 |
+
+---
+
+## Proposed design
+
+### 1) Add a CLI-local adapter namespace
+
+Create a small wrapper namespace (e.g. `src/main/logseq/cli/humanize.cljs`) that centralizes:
+
+- `format-count` (uses `intcomma`)
+- `pluralize` (uses `pluralize-noun`)
+- `format-filesize` (uses `filesize`, configurable binary/decimal)
+- `relative-ago` (uses `relative-datetime` with fixed CLI options)
+- Optional list helper (`oxford`)
+
+This avoids scattering direct library calls and keeps style decisions local to CLI.
+
+### 2) Preserve machine-output invariants
+
+All changes must keep:
+
+- `format-result` behavior for `:json` and `:edn`
+- existing keys in command `:data` and `:error`
+- transport payload compatibility
+
+### 3) Strict boundary: CLI formatter only
+
+- Do not modify any `db-worker-node` files.
+- Do not change sync event payload structure.
+- Limit all behavior changes to CLI human-output formatting paths.
+
+---
+
+## Implementation plan
+
+### Phase 1 — dependency + adapter (foundation)
+
+1. Add dependency in root project deps for CLI compile/runtime usage:
+   - `/Users/rcmerci/gh-repos/logseq/deps.edn`
+2. Add wrapper namespace:
+   - `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/humanize.cljs`
+3. Add unit tests for wrapper behavior (counts, pluralization, relative time, filesize).
+
+### Phase 2 — migrate high-impact formatter paths
+
+1. Replace `human-ago` implementation in `format.cljs` with wrapper call.
+2. Update `format-counted-table` count rendering with grouped numbers.
+3. Update list-asset size rendering to human-readable filesize.
+4. Update graph-list/server-cleanup/sync-status numeric display paths.
+
+Primary file:
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`
+
+### Phase 3 — migrate command message producers
+
+1. `command/doctor.cljs`: pluralization cleanup.
+2. `command/graph.cljs`: validation summary noun/count formatting.
+3. `command/example.cljs`: example count formatting.
+4. `command/show.cljs`: referenced count formatting.
+
+Primary files:
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/doctor.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/graph.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/example.cljs`
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs`
+
+### Phase 4 — tests and docs
+
+1. Update/extend formatter tests for expected human-output changes:
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`
+2. Update command tests where message text is asserted:
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/doctor_test.cljs`
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/graph_test.cljs`
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/show_test.cljs`
+   - `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/example_test.cljs`
+3. Update CLI documentation examples if human-mode samples are shown:
+   - `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
+
+---
+
+## Verification plan
+
+Run targeted tests first:
+
+```bash
+bb dev:test -v logseq.cli.format-test
+bb dev:test -v logseq.cli.command.doctor-test
+bb dev:test -v logseq.cli.command.graph-test
+bb dev:test -v logseq.cli.command.show-test
+bb dev:test -v logseq.cli.command.example-test
+```
+
+Then broader checks:
+
+```bash
+bb dev:lint-and-test
+bb -f cli-e2e/bb.edn test --skip-build
+```
+
+---
+
+## Acceptance criteria
+
+1. `org.clj-commons/humanize` is integrated and used by CLI human-output formatting paths.
+2. High-impact areas (relative time, `Count:` rendering with grouped numbers, asset filesize, pluralization in doctor/graph) are migrated.
+3. Relative time remains in compact short style compatible with current CLI behavior.
+4. `json` and `edn` outputs remain schema-compatible.
+5. No `db-worker-node` code changes are introduced.
+6. Existing CLI tests are updated and passing.
+
+---
+
+## Risks and mitigations
+
+- **Risk: output churn breaks exact-string tests.**
+  - Mitigation: migrate in phases and update tests in the same commit; avoid changing machine outputs.
+
+- **Risk: bundle-size increase from adding library + transitive time utilities.**
+  - Mitigation: route usage through wrapper, prefer only needed functions, and measure `static/logseq-cli.js` size delta.
+
+- **Risk: semantic drift in relative-time wording.**
+  - Mitigation: pin wrapper options to compact short style and keep compatibility snapshots in `format_test.cljs`.
diff --git a/docs/agent-guide/087-logseq-cli-show-block-breadcrumb.md b/docs/agent-guide/087-logseq-cli-show-block-breadcrumb.md
new file mode 100644
index 0000000000..7c0489370a
--- /dev/null
+++ b/docs/agent-guide/087-logseq-cli-show-block-breadcrumb.md
@@ -0,0 +1,255 @@
+# Logseq CLI Show Block Breadcrumb Implementation Plan
+
+Goal: Add a one-line parent breadcrumb above `logseq show` human output when the shown entity is an ordinary block.
+
+Architecture: Keep the existing `logseq-cli -> transport/invoke -> db-worker-node thread-api` flow and implement this as a human-rendering enhancement in `show` command orchestration.
+
+Architecture: Reuse existing thread APIs, especially `:thread-api/get-block-parents`, and avoid adding any new thread-api unless an implementation dead-end is proven.
+
+Tech Stack: ClojureScript, `logseq.cli.command.show`, db-worker-node `frontend.worker.db-core`, Datascript parent traversal from `logseq.db/get-block-parents`, ANSI styling helpers, and optional display-width truncation via `string-width`.
+
+Related: Builds on `docs/agent-guide/024-logseq-cli-show-updates.md`, `docs/agent-guide/029-logseq-cli-show-properties.md`, and `docs/agent-guide/065-logseq-cli-show-ref-id-footer.md`.
+
+## Problem statement
+
+Current `logseq show` human output starts directly from the selected entity line.
+
+When users show a deep block by id or uuid, they cannot quickly see where that block sits in the page hierarchy.
+
+The request is to add a breadcrumb above the shown block for ordinary block entities, where ordinary means not page, not property, and not tag.
+
+The breadcrumb must include parent lineage up to the page and keep each segment at a fixed maximum length.
+
+This should not require introducing new thread APIs when current db-worker-node capabilities are already sufficient.
+
+## Current baseline from implementation
+
+The current show flow is centered in `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs`.
+
+`fetch-tree` resolves the target entity by `--id`, `--uuid`, or `--page`, and builds children by querying blocks within the page.
+
+Human output is composed by `render-tree-text` and `tree->text`, with optional linked references and referenced-entity footer.
+
+db-worker-node already exposes `:thread-api/get-block-parents` in `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`.
+
+That API delegates to `logseq.db/get-block-parents` in `/Users/rcmerci/gh-repos/logseq/deps/db/src/logseq/db.cljs`, which traverses from a block to its ancestors.
+
+This means we can fetch breadcrumb lineage without adding a new thread API.
+
+## Scope and constraints
+
+### In scope.
+
+Add breadcrumb rendering for human output only when target is an ordinary block.
+
+Compute breadcrumb from page to nearest parent and render it as one line above root block text.
+
+Apply fixed segment truncation for each breadcrumb node label.
+
+Keep existing linked references and referenced-entities footer behavior intact.
+
+### Out of scope.
+
+Any change to JSON or EDN output payload schema.
+
+Any change to db-worker-node transport protocol.
+
+Any new thread-api, unless the implementation proves existing APIs cannot satisfy the requirement.
+
+### Locked decisions.
+
+Do not add new thread-api as a first approach.
+
+Breadcrumb is rendered only in `--output human` path.
+
+Segment max length is a fixed constant in CLI code, not a user option in this phase.
+
+## Ordinary block definition for this feature
+
+Use a data-driven rule on the shown root entity.
+
+| Condition | Meaning |
+| --- | --- |
+| `:block/page` exists with `:db/id` | Entity is a block under a page, not a page root. |
+| `:logseq.property/created-from-property` absent | Excludes property-value pseudo blocks. |
+| Class tags do not mark schema-definition roots | Defensive guard for tag/property/page schema entities when present. |
+
+Schema-definition detection should use class idents from `:block/tags`, such as `:logseq.class/Tag` and `:logseq.class/Property`, when available in pulled data.
+
+## Proposed UX
+
+For ordinary block targets, prepend one breadcrumb line.
+
+Example.
+
+```text
+Project Alpha > Milestone 2026 > API rollout
+5137 Implement retry policy for upload worker
+5138 ├── Add timeout backoff guard
+5139 └── Add deterministic retry test
+```
+
+For page targets, property targets, and tag targets, keep current output unchanged.
+
+For multi-id mode, each successful ordinary block segment gets its own breadcrumb line.
+
+## Breadcrumb truncation policy
+
+Introduce a constant such as `show-breadcrumb-segment-max-display-width` with value `24`.
+
+Truncate each segment independently to this visual width.
+
+Use an ellipsis suffix `…` when truncation happens.
+
+Prefer display-width-aware truncation to avoid CJK misalignment.
+
+Separator should be a plain ` > ` for compatibility and snapshot stability.
+
+## Integration design
+
+```text
+logseq show
+  -> execute-show
+    -> build-tree-data (existing)
+    -> enrich human render context (new)
+      -> if ordinary block
+         -> transport/invoke :thread-api/get-block-parents
+         -> format/truncate breadcrumb segments
+    -> render-tree-text
+      -> prepend breadcrumb line
+      -> existing tree text
+      -> existing linked refs and footer behavior
+```
+
+No db-worker-node API surface change is required.
+
+The only db-worker interaction addition is calling an existing method from CLI.
+
+## Files to modify
+
+`/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs`.
+
+`/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/show_test.cljs`.
+
+`/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`.
+
+`/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`.
+
+## Implementation plan (TDD order)
+
+1. Add failing unit tests for breadcrumb segment truncation helper, including ASCII, CJK, exact-width, and one-over-width cases.
+
+2. Add failing unit tests for root entity classification helper that distinguishes ordinary block vs page/property/tag.
+
+3. Add failing unit tests for breadcrumb text assembly order from page to nearest parent.
+
+4. Add failing `execute-show` tests in `show_test.cljs` asserting breadcrumb appears above root line for ordinary block targets.
+
+5. Add failing `execute-show` tests asserting breadcrumb is absent for page targets.
+
+6. Add failing `execute-show` tests asserting breadcrumb is absent for tag/property schema targets.
+
+7. Add failing multi-id tests asserting each successful ordinary block section contains its own breadcrumb.
+
+8. Add failing tests asserting `:thread-api/get-block-parents` is not called when target is non-ordinary.
+
+9. Run the new tests and verify they fail for missing breadcrumb behavior, not due to broken fixtures.
+
+10. Extend root selectors in `fetch-tree` pulls to include fields needed for classification, including class-tag idents and `:logseq.property/created-from-property` where necessary.
+
+11. Implement `ordinary-block-root?` helper in `show.cljs` using root entity shape and class tags.
+
+12. Implement breadcrumb label normalization helper with fallback order `:block/title`, `:block/name`, UUID string, and `:db/id` fallback.
+
+13. Implement display-width truncation helper and fixed max-width constant for breadcrumb segments.
+
+14. Implement `fetch-breadcrumb-parents` helper that calls existing `:thread-api/get-block-parents` only for ordinary block roots.
+
+15. Implement `render-breadcrumb-line` helper that joins truncated labels with ` > ` in page-to-parent order.
+
+16. Integrate breadcrumb composition in human render path before `tree->text` output.
+
+17. Ensure linked references section and referenced-entities footer still append exactly as before.
+
+18. Ensure structured output path remains unchanged by keeping breadcrumb context out of JSON and EDN payloads.
+
+19. Update or add command help documentation section in `docs/cli/logseq-cli.md` with one human-output example showing breadcrumb.
+
+20. Re-run targeted tests and then broader CLI regression suites.
+
+## Testing Plan
+
+I will add focused unit tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/show_test.cljs` for breadcrumb truncation, lineage ordering, and ordinary-block classification behavior.
+
+I will add behavioral render tests in the same file that call `execute-show` with mocked transport responses and verify breadcrumb placement above root tree output.
+
+I will extend `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs` only where shared tree rendering or option-level behavior needs regression coverage.
+
+I will run targeted tests with `bb dev:test -v logseq.cli.command.show-test` and `bb dev:test -v logseq.cli.commands-test`.
+
+I will then run `bb dev:lint-and-test`.
+
+I will run CLI e2e non-sync regression with `bb -f cli-e2e/bb.edn test --skip-build`.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Edge cases
+
+Parent chain contains missing titles, so breadcrumb must fallback deterministically.
+
+A block directly under page should produce a one-segment breadcrumb containing just the page.
+
+A very deep hierarchy must still render in correct order with each segment independently truncated.
+
+A target resolved by `--uuid` should behave identically to `--id` for breadcrumb behavior.
+
+Multi-id output must preserve existing delimiter and error segment behavior.
+
+When parent lookup fails transiently, show should still render the tree and omit breadcrumb rather than fail the command.
+
+## Risks and mitigation
+
+Risk: Extra parent fetch adds latency for each ordinary block render.
+
+Mitigation: Call `:thread-api/get-block-parents` only when classification says ordinary block.
+
+Risk: Classification drift if tag/property schemas are represented unexpectedly in data.
+
+Mitigation: Keep classification helper table-driven and back it with explicit tests for schema-tag variants.
+
+Risk: Truncation may produce unstable snapshots across mixed-width terminals.
+
+Mitigation: Use display-width-aware truncation with deterministic suffix handling and strip-ansi assertions in tests.
+
+## Testing Details
+
+Tests validate user-visible behavior by asserting final human text composition order and content, not private intermediate maps.
+
+Classification tests validate rendered outcomes and thread-api call gating instead of only testing helper internals.
+
+Multi-id tests verify segment-local breadcrumb insertion and unchanged delimiter behavior.
+
+## Implementation Details
+
+- Keep breadcrumb logic in `show.cljs` render orchestration and avoid changing formatter-wide code.
+- Reuse existing `:thread-api/get-block-parents` and do not introduce a new thread API.
+- Add only the minimal extra selector fields required for ordinary-block classification.
+- Use a fixed segment display-width constant with ellipsis truncation.
+- Render breadcrumb as a single line above the root block line.
+- Keep linked references rendering behavior unchanged.
+- Keep referenced-entity footer behavior unchanged.
+- Keep JSON and EDN output schema unchanged.
+- Ensure failures in breadcrumb enrichment degrade gracefully to current output.
+- Document the new human output behavior in CLI docs.
+
+## Question
+
+No open questions.
+
+Decisions confirmed.
+
+Use plain separator ` > `.
+
+Use breadcrumb segment max display width `24`.
+
+---
diff --git a/docs/agent-guide/task--db-worker-nodejs-compatible.md b/docs/agent-guide/task--db-worker-nodejs-compatible.md
new file mode 100644
index 0000000000..614eefa149
--- /dev/null
+++ b/docs/agent-guide/task--db-worker-nodejs-compatible.md
@@ -0,0 +1,183 @@
+# task--db-worker-nodejs-compatible
+
+## Goal
+Make `frontend.worker.db-worker` and its dependencies run in both browser and Node.js. Add a Node.js daemon that can be started from the command line and exposes HTTP APIs to the same worker capabilities.
+
+## Scope
+- Primary target: `src/main/frontend/worker/db_worker.cljs`.
+- All dependencies used by db-worker: `src/main/frontend/worker/**`, `src/main/frontend/worker_common/**`, and any browser-only utilities used by those namespaces.
+- Callers: `src/main/frontend/persist_db/browser.cljs`, `src/main/frontend/handler/worker.cljs`, and any callers that assume a WebWorker or Comlink transport.
+
+## Refactor Items (Concrete Work List)
+1. Split worker core logic from runtime-specific host APIs.
+   - Create a core module (e.g. `frontend.worker.db-core`) that contains thread-api functions and business logic.
+   - Move all direct uses of `js/self`, `js/location`, `js/navigator`, `importScripts`, `BroadcastChannel`, and `navigator.locks` out of core.
+2. Add a platform adapter layer with a consistent interface for browser and Node.js.
+   - Define `frontend.worker.platform` interface: storage, kv-store, broadcast, websocket, crypto, timers, and env flags.
+   - Implement `frontend.worker.platform.browser` using OPFS, IDB, BroadcastChannel, navigator.locks, WebSocket, and `globalThis`.
+   - Implement `frontend.worker.platform.node` using `fs/promises`, `path`, `crypto`, and `ws`.
+3. Abstract sqlite storage and VFS specifics.
+   - Browser: keep OPFS SAH pool implementation.
+   - Node: use file-backed sqlite storage via Node built-in `node:sqlite` (no OPFS, no sqlite-wasm).
+   - Route db path resolution through the platform adapter (data dir, per-repo paths).
+4. Replace `importScripts` bootstrap with an explicit init entrypoint.
+   - Browser build still uses `:web-worker`, but entrypoint should call `init!` with a browser platform adapter.
+   - Node build should call the same `init!` with a Node adapter.
+5. Normalize RPC and transport.
+   - Define a transport-agnostic RPC layer that accepts a method name and args (transit string or direct args).
+   - Keep Comlink for browser worker transport.
+   - Add HTTP transport for Node (see daemon section).
+6. Update shared-service for non-browser environments.
+   - Provide a "single-client" fallback for Node; no multi-client coordination is needed.
+7. Replace browser-only storage in RTC and crypto modules.
+   - `frontend.worker.rtc.crypt` uses IDB/OPFS and should switch to the platform kv-store and file API.
+   - Any other worker modules using `js/navigator` or OPFS should be routed through the platform adapter.
+8. Replace direct `js/WebSocket` usage with a platform websocket factory.
+   - Browser: `js/WebSocket`.
+   - Node: `ws` client with the same interface shape.
+9. Update caller-side initialization.
+   - Keep browser `frontend.persist-db.browser` using WebWorker + Comlink.
+10. Build config changes.
+    - Add a Node build target in `shadow-cljs.edn` for db-worker (e.g. `:db-worker-node`).
+    - Ensure shared code compiles for `:node-script` or `:node-library` with the correct externs.
+    - Use Node built-in `node:sqlite` and keep Node runtime on `>=22.20.0`.
+11. Tests and fixtures.
+    - Add unit tests for platform adapters and storage abstraction.
+    - Add a minimal integration test that starts the Node daemon and exercises a small RPC call.
+
+## Node.js sqlite Implementation (node:sqlite)
+Node runtime must not use OPFS or sqlite-wasm. Instead, use Node built-in `node:sqlite` as the direct file-backed sqlite engine.
+
+### Concrete Refactor Items (File + Function + Summary)
+- `src/main/frontend/worker/db_core.cljs` (`init-sqlite-module!`, `<get-opfs-pool`, `get-dbs`, `<export-db-file`, `<import-db`, `close-db-aux!`, `:thread-api/init`)
+  - Remove sqlite-wasm initialization and OPFS pool usage on Node.
+  - Route all sqlite open/close/exec/transaction operations through a platform-provided sqlite interface.
+  - Replace OPFS export/import with file-based export/import in Node.
+- `src/main/frontend/worker/platform.cljs` (`validate-platform!`)
+  - Extend platform contract to include a `:sqlite` section (or expand `:storage`) defining: `open-db`, `close-db`, `exec`, `transaction`, `export-db`, `import-db`.
+- `src/main/frontend/worker/platform/node.cljs` (`node-platform`, `install-opfs-pool`, `export-file`, `import-db`, `remove-vfs!`)
+  - Remove OPFS pool and sqlite-wasm Node VFS behavior.
+  - Implement `node:sqlite` adapter: open db files, exec, transactions, close.
+  - Resolve db paths under data-dir and ensure directories exist.
+- `src/main/frontend/worker/platform/browser.cljs` (`browser-platform`, `install-opfs-pool`)
+  - Keep sqlite-wasm + OPFS behavior but conform to the same `:sqlite` interface used by db-core.
+- `src/main/frontend/worker/state.cljs` (`*opfs-pools`, `get-opfs-pool`)
+  - Ensure Node path does not write/read OPFS pools; keep OPFS state browser-only.
+- `src/main/frontend/worker/db_worker_node.cljs` (`main`, `<init-worker!`)
+  - Initialize platform adapter before core init; mark readiness after sqlite adapter init.
+- `src/main/frontend/persist_db/node.cljs` (`start!`, `<invoke`)
+  - Keep API compatibility; update if any thread-api names or args change due to sqlite refactor.
+- `shadow-cljs.edn` (`:db-worker-node`)
+  - Ensure `node:sqlite` path remains standalone for Node target; no sqlite-wasm artifacts in Node path.
+- `package.json`
+  - Keep sqlite-wasm browser-only; Node path uses built-in `node:sqlite`.
+- Tests
+  - Add Node integration smoke test with `node:sqlite` backing: `list-db`, `create-or-open-db`, `q`, `transact`.
+
+## Refactor Steps (Milestones + Status)
+
+### Milestone 1: Architecture & Abstractions
+- DONE 1. Inventory db-worker dependencies and classify browser-only APIs.
+- DONE 2. Define a platform adapter interface (storage, kv, broadcast, websocket, crypto, timers, env flags).
+- DONE 3. Extract db-worker core logic into a platform-agnostic module (e.g. `frontend.worker.db-core`).
+#### Acceptance Criteria
+- Core worker module has zero direct references to `js/self`, `js/location`, `js/navigator`, `importScripts`, `BroadcastChannel`, or `navigator.locks`.
+- `frontend.worker.platform` exists with required sections and validation; platform adapter passes validation at init time.
+- Browser worker entry initializes via `init!`/`init-core!` with a platform adapter.
+- `bb dev:lint-and-test` passes.
+
+### Milestone 2: Browser Path Parity
+- DONE 4. Implement `frontend.worker.platform.browser`.
+- DONE 5. Update db-worker entry to inject the platform adapter and call core init.
+- DONE 6. Route OPFS/IDB usage through the platform adapter in worker submodules.
+- DONE 7. Replace direct `js/WebSocket` usage with platform websocket factory.
+#### Acceptance Criteria
+- Browser platform adapter encapsulates OPFS/IDB storage, kv-store, and WebSocket factory; worker submodules no longer import OPFS/IDB directly.
+- RTC WebSocket creation uses the platform adapter.
+- Browser db-worker entry injects the platform adapter and serves Comlink RPC.
+- `bb dev:lint-and-test` passes.
+
+### Milestone 3: Node Path & Daemon
+- DONE 8. Implement `frontend.worker.platform.node` in single-client mode (no locks or BroadcastChannel).
+- DONE 9. Update shared-service to no-op/single-client behavior in Node.
+- DONE 10. Add Node build target in `shadow-cljs.edn` for db-worker.
+- DONE 11. Implement Node daemon entrypoint and HTTP server.
+- LATER 12. Add a Node client in frontend to call the daemon (HTTP + SSE events).
+- DONE 12a. Switch Node sqlite implementation to built-in `node:sqlite` (no OPFS, no sqlite-wasm).
+#### Acceptance Criteria
+- Node platform adapter provides storage/kv/broadcast/websocket/crypto/timers and validates via `frontend.worker.platform`.
+- Node sqlite adapter uses built-in `node:sqlite` and opens file-backed dbs in data-dir.
+- Node build target compiles db-worker core without browser-only APIs.
+- Node daemon starts via CLI and reports readiness; `GET /healthz` and `GET /readyz` return `200 OK`.
+- `POST /v1/invoke` handles `list-db`, `create-or-open-db`, `q`, `transact` in a smoke test:
+  - test client script: `tmp_scripts/db-worker-smoke-test.clj`
+- LATER Node client can invoke at least one RPC and receive one event (SSE).
+- `bb dev:lint-and-test` passes.
+
+### Milestone 4: Validation
+- DONE 13. Add tests: adapter unit tests + daemon integration smoke test.
+#### Acceptance Criteria
+- Adapter unit tests cover browser and node implementations for storage/kv/broadcast/websocket factories.
+- Daemon integration smoke test starts the node process and exercises `/v1/invoke` with at least one method.
+- `bb dev:lint-and-test` passes.
+
+## Node.js Daemon Requirements
+The db-worker should be runnable as a standalone process for Node.js environments.
+
+### Entry Point
+- Provide a CLI entry (example: `bin/logseq-db-worker` or `./dist/db-worker-node.js`).
+- CLI flags (suggested):
+  - Binds to localhost on a random port and records it in the repo lock file.
+  - `--data-dir` (path for sqlite files, required or default to `~/logseq/cli-graphs`)
+  - `--repo` (optional: auto-open a repo on boot)
+  - `--rtc-ws-url` (optional)
+  - `--log-level` (default `info`)
+
+### Lifecycle
+1. Initialize platform adapter (Node).
+2. Initialize sqlite module and storage roots.
+3. Start HTTP server.
+4. Emit readiness when init completes.
+5. Graceful shutdown on SIGINT/SIGTERM (close dbs, flush logs).
+
+### HTTP API (Minimum)
+Use HTTP for RPC and event delivery. Prefer a single generic RPC entrypoint to avoid one endpoint per method.
+
+Required endpoints:
+- `GET /healthz` -> `200 OK` when process is alive.
+- `GET /readyz` -> `200 OK` only after sqlite init completes.
+- `POST /v1/invoke`
+  - Request JSON:
+    - `method`: string, e.g. `"thread-api/create-or-open-db"`
+    - `directPass`: boolean
+    - `argsTransit`: string (transit-encoded args) OR `args`: array for direct pass
+  - Response JSON:
+    - `ok`: boolean
+    - `resultTransit`: string (transit-encoded result) when `directPass=false`
+    - `result`: any (when `directPass=true`)
+    - `error`: error object if failed
+
+Event delivery options:
+- `GET /v1/events` using SSE for worker -> client events
+  - Event payload should mirror current `postMessage` payloads in `frontend.handler.worker`.
+  - Each event should be tagged with `type` and `payload`.
+- Alternatively, provide `WS /v1/events` with the same payload format.
+
+### Security
+- Bind to localhost by default.
+
+## Notes on Compatibility Gaps
+- OPFS and IndexedDB do not exist in Node; file-backed storage and a Node KV store are required.
+- `BroadcastChannel` and `navigator.locks` are browser-only; Node should use a simpler single-client mode.
+- `Comlink` is browser-optimized; the Node daemon should use HTTP, not Comlink.
+- sqlite-wasm must remain browser-only; Node uses built-in `node:sqlite` directly.
+- only db-graph supported in Node db-worker
+
+## Success Criteria
+- Browser build continues to work with WebWorker + Comlink.
+- Node daemon can start from CLI, open a repo, and respond to at least:
+  - `list-db`
+  - `create-or-open-db`
+  - `q`
+  - `transact`
+- A minimal client can call the daemon and receive event notifications.
diff --git a/docs/cli/logseq-cli.md b/docs/cli/logseq-cli.md
new file mode 100644
index 0000000000..db6cc1daca
--- /dev/null
+++ b/docs/cli/logseq-cli.md
@@ -0,0 +1,437 @@
+# Logseq CLI (Node)
+
+The Logseq CLI is a Node.js program compiled from ClojureScript that connects to a db-worker-node server managed by the CLI. When installed, the CLI binary name is `logseq`.
+
+## Build the CLI
+
+```bash
+clojure -M:cljs compile logseq-cli
+pnpm db-worker-node:release:bundle
+```
+
+`pnpm db-worker-node:release:bundle` compiles and bundles `db-worker-node` with Vite, and writes a standalone runtime to `dist/db-worker-node.js` plus an asset manifest at `dist/db-worker-node-assets.json` (which may contain an empty `assets` array when no extra files are required).
+
+## db-worker-node lifecycle
+
+`logseq` manages `db-worker-node` automatically. You should not start the server manually. The server binds to localhost on a random port and records that port in the repo lock file.
+
+Desktop + CLI shared semantics:
+- Electron desktop and CLI are expected to use the same `db-worker-node` and lock-file protocol for a graph.
+- Disk SQLite under `~/logseq/graphs` is the source of truth; OPFS periodic export is not part of the desktop primary write path.
+- If a daemon already exists for the graph, CLI reuses it via lock-file discovery instead of starting a second writer.
+- If lock ownership is invalid or stale, startup cleans stale lock state before retrying.
+- Lock metadata includes an `owner-source` value (`cli`, `electron`, `unknown`) and lifecycle actions enforce owner boundaries.
+- `server stop` and `server restart` are owner-aware: CLI can only stop/restart servers it owns (or legacy `unknown` ownership).
+- If lock is missing but a matching orphan `db-worker-node` process still exists for the same repo/root-dir, startup performs orphan cleanup before retrying.
+
+## Run the CLI
+
+```bash
+node ./dist/logseq.js graph list
+```
+
+You can also use npm link to make ./dist/logseq.js globally available, run:
+```
+npm link
+```
+
+If installed(or linked) globally, run:
+
+```bash
+logseq graph list
+```
+
+## Configuration
+
+The CLI config file defaults to `<root-dir>/cli.edn`, where `root-dir` defaults to `~/logseq`.
+
+Supported keys include:
+- `:graph` - The current active graph. Set this with `graph switch`.
+- `:root-dir` - CLI root directory. Default is `~/logseq`.
+  - Graph data directory is derived as `<root-dir>/graphs`.
+  - Config file default is derived as `<root-dir>/cli.edn`.
+  - Server list file default is derived as `<root-dir>/server-list`.
+  - Graph directories under `<root-dir>/graphs` are user-facing graph names e.g. `demo` and do not start with `logseq_db_`.
+- `:output-format` - Format for output. Default is `:human`. Use `:json` or `:edn` for scripting.
+- `:list-title-max-display-width` - For `:human` output, the max display width for TITLE column, defaulting to `40`.
+- `:http-base` - Http base domain for sync service. Interact with this via `sync config`.
+- `:ws-url` - Websocket url for sync service. Interact with this via `sync config`.
+- `:timeout-ms` - Request timeout in milliseconds.
+- `:login-timeout-ms` - Login callback timeout. Defaults to 5 minutes.
+- `:logout-timeout-ms` - Logout callback timeout. Defaults to 2 minutes.
+- `:custom-queries` - Map of custom queries which are run with `query --name`. See [below for more](#custom-queries).
+
+CLI global flags take precedence over environment variables, which take precedence over the config file. Here is a mapping of these three:
+
+| Config key | Environment variable | Global flag |
+| --- | --- | --- |
+| :graph | $LOGSEQ_CLI_GRAPH | --graph |
+| :root-dir | $LOGSEQ_CLI_ROOT_DIR | --root-dir |
+| :output-format | $LOGSEQ_CLI_OUTPUT | --output |
+| :timeout-ms | $LOGSEQ_CLI_TIMEOUT_MS | --timeout-ms |
+| :login-timeout-ms | $LOGSEQ_CLI_LOGIN_TIMEOUT_MS | n/a |
+| :logout-timeout-ms | $LOGSEQ_CLI_LOGOUT_TIMEOUT_MS | n/a  |
+
+Legacy notes:
+* Migration note: If you previously used `~/.logseq/cli-graphs` or `~/.logseq/cli.edn`, pass `--root-dir` and/or `--config` to continue using equivalent custom locations.
+* `:e2ee-password` in `cli.edn` is ignored and removed silently during config read/update. Use `sync start --e2ee-password` or `sync download --e2ee-password` instead.
+* `cli.edn` no longer persists cloud auth tokens. CLI login state is stored separately in `~/logseq/auth.json`.
+
+### Custom Queries
+
+Custom queries are defined in `:custom-queries` of a config file. This config is a map with the key as a query name and the value as a map with the following keys:
+* `:query` - Required datalog query as a vector. Queries can use built-in rules from `logseq.db.frontend.rules` by appending `%` to the `:in` part of a query. See `logseq.cli.command.query` for example queries.
+* `:doc` - Optional doc string describing the query.
+* `:inputs` - Optional vector of inputs where each input is a map. Valid keys for the map are `:name` and `:default`. This defines positional arguments to a query e.g. the arguments a user passes map to these inputs and the `:in` bindings in a `:query`.
+
+## Authentication
+
+Use `logseq login` to authenticate the current machine with Logseq cloud.
+
+- `logseq login` starts a temporary callback server at `http://localhost:8765/auth/callback`, opens a browser to the Logseq Cognito Hosted UI, exchanges the returned authorization code, and writes `~/logseq/auth.json`.
+- `logseq logout` removes `~/logseq/auth.json`, opens a browser to the Cognito Hosted UI logout endpoint, and completes the browser logout flow at `http://localhost:8765/logout-complete`.
+- Sync commands still pass an in-memory runtime `:auth-token` to db-sync, but that token is now resolved from `auth.json` instead of `cli.edn`.
+
+Default auth file: `~/logseq/auth.json`
+
+Auth file contents include the persisted Cognito `id-token`, `access-token`, `refresh-token`, `expires-at`, `sub`, `email`, and `updated-at` values needed for headless refresh.
+
+Verbose logging:
+- `--verbose` enables structured debug logs to stderr for CLI option parsing and db-worker-node API calls.
+- `sync download` can stream realtime progress lines to stdout when progress is enabled; debug previews remain truncated.
+
+Timeouts:
+- `--timeout-ms` continues to control request timeout behavior for CLI transport.
+- Login callback timeout is controlled separately by `:login-timeout-ms` / `LOGSEQ_CLI_LOGIN_TIMEOUT_MS` and defaults to 5 minutes.
+- Logout callback timeout is controlled separately by `:logout-timeout-ms` / `LOGSEQ_CLI_LOGOUT_TIMEOUT_MS` and defaults to 2 minutes.
+
+## Commands
+
+Graph commands:
+- `graph list` - list all db graphs
+- `graph create --graph <name>` - create a new db graph and switch to it
+- `graph switch --graph <name>` - switch current graph
+- `graph remove --graph <name>` - remove a graph
+- `graph validate --graph <name>` - validate graph data
+- `graph info [--graph <name>]` - show graph metadata (defaults to current graph)
+- `graph export --type edn|sqlite --file <path> [--graph <name>]` - export a graph to EDN or SQLite
+- `graph import --type edn|sqlite --input <path> --graph <name>` - import a graph from EDN or SQLite (new graph only)
+- `graph backup list` - list backup snapshots under `<root-dir>/graphs/<graph>/backup`
+- `graph backup create [--graph <name>] [--name <label>]` - create a backup snapshot for the selected graph
+- `graph backup restore --src <backup-name> --dst <graph-name>` - restore one backup snapshot into a new graph
+- `graph backup remove --src <backup-name>` - delete one backup snapshot
+
+For any command that requires `--graph`, if the target graph does not exist, the CLI returns `graph not exists` (except for `graph create`). `graph import` and `graph backup restore` fail if the target graph already exists.
+
+Backup scope note:
+- `graph backup create` copies only `db.sqlite`.
+- `search-db.sqlite` and `client-ops-db.sqlite` are intentionally excluded.
+
+Server commands:
+- `server list` - list running db-worker-node servers
+- `server cleanup` - terminate revision-mismatched CLI-owned db-worker-node servers discovered from lock files in the current root-dir
+- `server start --graph <name>` - start db-worker-node for a graph
+- `server stop --graph <name>` - stop db-worker-node for a graph
+- `server restart --graph <name>` - restart db-worker-node for a graph
+- `doctor [--dev-script]` - run runtime diagnostics for `db-worker-node.js`, `root-dir` permissions, and running server readiness (`--dev-script` checks `static/db-worker-node.js` explicitly)
+
+Auth commands:
+- `login` - authenticate this machine and create/update `~/logseq/auth.json`
+- `logout` - remove persisted CLI auth from `~/logseq/auth.json`
+
+Debug commands:
+- `debug pull --id <db-id> [--graph <name>]` - pull a raw entity by db id with selector `[*]`
+- `debug pull --uuid <uuid> [--graph <name>]` - pull a raw entity by block UUID lookup
+- `debug pull --ident <db-ident> [--graph <name>]` - pull a raw entity by `:db/ident` lookup
+  - `--ident` must be a strict EDN keyword (for example `:logseq.class/Tag`)
+  - exactly one of `--id`, `--uuid`, or `--ident` is required
+  - if `--graph` is omitted, CLI falls back to current graph config
+
+Utility commands:
+- `completion <zsh|bash>` - generate shell completion script to stdout
+- `example <command-or-prefix...>` - show runnable command examples for a command path or command prefix (phase 1 covers Graph Inspect and Edit commands)
+  - exact selector example: `logseq example upsert page`
+  - prefix selector example: `logseq example upsert`
+- `skill show` - print built-in `logseq-cli` skill markdown to stdout
+  - always prints raw markdown text, even when `--output json` or `--output edn` is set
+- `skill install` - install built-in skill to `./.agents/skills/logseq-cli/SKILL.md`
+- `skill install --global` - install built-in skill to `~/.agents/skills/logseq-cli/SKILL.md`
+
+Setup for zsh (add to `~/.zshrc`):
+```bash
+autoload -Uz compinit && compinit
+eval "$(logseq completion zsh)"
+```
+
+Setup for bash (add to `~/.bashrc`):
+```bash
+eval "$(logseq completion bash)"
+```
+
+Skill command examples:
+```bash
+# Print markdown content to stdout
+logseq skill show
+
+# Install for current working directory
+logseq skill install
+
+# Install for current user home directory
+logseq skill install --global
+```
+
+Server ownership behavior:
+- `server stop` and `server restart` can return `server-owned-by-other` if the daemon was started by another owner source.
+- `server start` can return `server-start-timeout-orphan` when lock creation times out and orphan matching processes are detected.
+- `server list` human output includes both `OWNER` and `REVISION` columns.
+- `server list` prints a compatibility warning in human output when any server revision string is not exactly equal to the local CLI revision string.
+- `server cleanup` checks discovered servers in the current root-dir, treats `revision != local CLI revision` (including missing revision) as mismatch, and attempts graceful-first termination only for `:owner-source :cli` targets.
+- `server cleanup` structured output includes `checked`, `mismatched`, `eligible`, `skipped-owner`, `killed`, and `failed` summaries.
+- Structured output (`--output json|edn`) includes per-server `revision` data but does not include human warning text.
+
+Sync commands:
+- `sync status --graph <name>` - show db-sync runtime state for a graph daemon
+- `sync start --graph <name> [--e2ee-password <password>]` - start db-sync websocket client for a graph
+- `sync stop --graph <name>` - stop db-sync client on a graph daemon
+- `sync upload --graph <name>` - upload local graph snapshot to remote
+- `sync download --graph <name> [--progress true|false] [--e2ee-password <password>]` - download remote graph `<name>` into a same-name local graph directory
+- `sync remote-graphs [--graph <name>]` - list remote graphs visible to the current login context
+- `sync ensure-keys [--graph <name>]` - ensure user RSA keys for sync/e2ee
+- `sync grant-access --graph <name> --graph-id <uuid> --email <email>` - grant encrypted graph access to a user
+- `sync config set [--graph <name>] ws-url|http-base <value>` - set non-auth db-sync runtime config key
+- `sync config get [--graph <name>] ws-url|http-base` - get non-auth db-sync runtime config key
+- `sync config unset [--graph <name>] ws-url|http-base` - remove non-auth db-sync runtime config key
+
+Sync start behavior:
+- `sync start --e2ee-password <password>` verifies the password against user encrypted private key before persisting it.
+- Verification and persistence run in worker-side sync crypt logic (shared with desktop/web interaction paths).
+- Wrong `--e2ee-password` fails fast and does not overwrite a previously stored encrypted password payload.
+
+Sync upload behavior:
+- `sync upload` requires `--graph <name>`.
+- The CLI starts or reuses that graph's `db-worker-node`, applies the current sync config, and uploads the local snapshot only after the worker has resolved a usable remote graph id.
+- If the local graph already has sync metadata, upload reuses the stored remote `graph-id`.
+- If the local graph does not have a stored remote `graph-id`, upload first lists visible remote graphs and reuses an exact same-name match when one exists.
+- If no same-name remote graph exists, upload creates a new remote graph and persists the returned remote metadata locally before snapshot transfer.
+- Successful upload persists graph identity metadata locally in both client-op state and graph KV (`logseq.kv/graph-uuid`, `logseq.kv/graph-remote?`, and `logseq.kv/graph-rtc-e2ee?`) so CLI and web upload/bootstrap flows stay aligned.
+- Fresh uploads default to encrypted remote graph creation unless local sync metadata explicitly marks the graph as non-e2ee. In headless CLI mode, run `logseq login` first so refresh-token based E2EE password persistence can be used by follow-up `sync start`/`sync download` flows.
+- `sync upload` returns a real error instead of false success when login state, remote graph bootstrap, or snapshot upload fails.
+- Common upload failures include missing/invalid CLI login state, missing `http-base`, remote graph creation failure, snapshot upload failure, and local DB/worker startup failure.
+- Troubleshooting: after a successful upload, run `graph info --graph <name> --output json` and confirm `data.kv.logseq.kv/graph-uuid` is present. If it is missing, rerun `sync upload` for the same graph to trigger identity backfill.
+
+Sync download behavior:
+- `sync download` requires `--graph <name>`.
+- If a local graph with the same name already exists, the CLI returns `graph-exists`.
+- If no remote graph with that name exists, the CLI returns `remote-graph-not-found`.
+- `sync download` starts `db-worker-node` in create-empty mode so local startup does not write `db-initial-data` before snapshot import.
+- The final snapshot download/import invoke uses a command-specific long-running timeout (30 minutes by default) rather than the generic short-request timeout path.
+- Progress streaming uses db-worker-node SSE `/v1/events` and shared `:rtc.log/download` events.
+- `--progress` defaults to `true` for human output.
+- For structured output (`--output json|edn`), progress is auto-disabled unless explicitly overridden with `--progress true`.
+- `--progress false` always suppresses progress streaming.
+- If the target graph DB is not empty at download time, the CLI returns `graph-db-not-empty` and aborts before import.
+- For e2ee remote graphs, provide `--e2ee-password` on `sync download` (or persist once via `sync start --e2ee-password`).
+- If e2ee password is required but missing, `sync start`, `sync download`, and `sync status` return `e2ee-password-not-found` with a hint to provide `--e2ee-password`.
+
+Sync config persistence:
+- `sync config set/unset` writes non-auth sync config to the CLI config file selected by `--config`.
+- If `--config` is not provided, the default config path is `~/logseq/cli.edn`.
+- `sync config get` reads from that same config source.
+- `:e2ee-password` is not part of sync config and is silently ignored when found in legacy `cli.edn`.
+- Cloud auth is persisted separately in `~/logseq/auth.json`.
+
+E2EE password persistence locations:
+- Browser runtime stores refresh-token-encrypted password payload in IndexedDB secret storage.
+- Node runtime stores refresh-token-encrypted password payload at `~/logseq/e2ee-password`.
+
+Inspect and edit commands:
+- `list page [--expand] [--limit <n>] [--offset <n>] [--sort <field>] [--order asc|desc]` - list pages (defaults to `--sort updated-at --order desc`)
+- `list tag [--expand] [--limit <n>] [--offset <n>] [--sort <field>] [--order asc|desc]` - list tags (defaults to `--sort updated-at --order desc`)
+- `list property [--expand] [--limit <n>] [--offset <n>] [--sort <field>] [--order asc|desc]` - list properties (defaults to `--sort updated-at --order desc`; `TYPE` and `CARDINALITY` are included by default even without `--expand`; missing schema cardinality is treated as `one`)
+- `list task [--status <status>] [--priority <low|medium|high|urgent>] [-c|--content <text>] [--fields <csv>] [--limit <n>] [--offset <n>] [--sort <field>] [--order asc|desc]` - list task nodes tagged with `#Task` (supports both pages and blocks; defaults to `--sort updated-at --order desc`)
+  - `--status` is validated at runtime using values from the current graph; invalid values return an error that includes available values from that graph.
+- `list node [--tags <csv>] [--properties <csv>] [--fields <csv>] [--limit <n>] [--offset <n>] [--sort <field>] [--order asc|desc]` - list ordinary nodes (pages and blocks) filtered by tags/properties (supports selector forms id/uuid/ident/name; at least one of `--tags` or `--properties` is required; defaults to `--sort updated-at --order desc`)
+  - `--tags` and `--properties` use **all-of** semantics, and when both are present they are combined with **AND**.
+  - CSV tokens are trimmed and empty tokens are ignored; if a provided filter becomes empty after normalization, CLI returns `invalid-options`.
+- `list asset [--fields <csv>] [--limit <n>] [--offset <n>] [--sort <field>] [--order asc|desc]` - list nodes tagged with `#Asset` (`:logseq.class/Asset`; defaults to `--sort updated-at --order desc`)
+- `upsert block --content <text> [--target-page <name>|--target-id <id>|--target-uuid <uuid>] [--pos first-child|last-child|sibling]` - create blocks; defaults to today’s journal page if no target is given
+- `upsert block --blocks <edn> [--target-page <name>|--target-id <id>|--target-uuid <uuid>] [--pos first-child|last-child|sibling]` - insert blocks via EDN vector
+- `upsert block --blocks-file <path> [--target-page <name>|--target-id <id>|--target-uuid <uuid>] [--pos first-child|last-child|sibling]` - insert blocks from an EDN file
+- `upsert block --id <id>|--uuid <uuid> [--content <text>] [--target-id <id>|--target-uuid <uuid>|--target-page <name>] [--pos first-child|last-child|sibling] [--update-tags <edn-vector>] [--update-properties <edn-map>] [--remove-tags <edn-vector>] [--remove-properties <edn-vector>]` - update and/or move a block
+  - `--status` is not supported on `upsert block`; use `upsert task --status ...` for task status updates.
+- `upsert page --page <name> [--update-tags <edn-vector>] [--update-properties <edn-map>] [--remove-tags <edn-vector>] [--remove-properties <edn-vector>]` - create (or update by page name) a page
+- `upsert page --id <id> [--update-tags <edn-vector>] [--update-properties <edn-map>] [--remove-tags <edn-vector>] [--remove-properties <edn-vector>]` - update a page by id (cannot be combined with `--page`)
+- `upsert task --content <text> [--target-page <name>|--target-id <id>|--target-uuid <uuid>] [--pos first-child|last-child|sibling] [--status <status>] [--priority <low|medium|high|urgent>] [--scheduled <datetime>] [--deadline <datetime>] [--no-status] [--no-priority] [--no-scheduled] [--no-deadline]` - create a task block and ensure `#Task` is attached
+- `upsert task --page <name> [--status <status>] [--priority <low|medium|high|urgent>] [--scheduled <datetime>] [--deadline <datetime>] [--no-status] [--no-priority] [--no-scheduled] [--no-deadline]` - create/update a task page and ensure `#Task` is attached
+- `upsert task --id <id>|--uuid <uuid> [--status <status>] [--priority <low|medium|high|urgent>] [--scheduled <datetime>] [--deadline <datetime>] [--no-status] [--no-priority] [--no-scheduled] [--no-deadline]` - update an existing node and ensure `#Task` is attached
+  - `--status` is validated at runtime using values from the current graph; invalid values return an error that includes available values from that graph.
+  - generic task tag/property mutation options are not supported on `upsert task`; use `upsert block --update-tags/--update-properties/--remove-tags/--remove-properties` when needed.
+  - for the same field, set and clear options are mutually exclusive (for example: `--status todo --no-status` is invalid).
+- `upsert asset --path <asset-file-path> [--content <text>] [--target-page <name>|--target-id <id>|--target-uuid <uuid>] [--pos first-child|last-child|sibling]` - create an asset node, add `#Asset`, set asset metadata (`type`, `size`, `checksum`), and copy the local file into graph `assets/` as `<block-uuid>.<ext>`
+- `upsert asset --id <id>|--uuid <uuid> [--content <text>]` - update an existing asset node title; target node must be tagged with `#Asset`
+  - create mode requires `--path`; update mode rejects `--path`.
+- `upsert tag --name <name>` - create or upsert a tag by name
+- `upsert tag --id <id> [--name <name>]` - validate a tag by id; when `--name` is provided, rename that tag id (no-op if normalized name is unchanged)
+- `upsert tag --id <id> --name <name>` conflicts: returns `tag-name-conflict` when target name is a non-tag page, and `tag-rename-conflict` when target name is another existing tag
+- `upsert property --name <name> [--type <type>] [--cardinality one|many] [--hide true|false] [--public true|false]` - create or update a property by name
+- `upsert property --id <id> [--type <type>] [--cardinality one|many] [--hide true|false] [--public true|false]` - update a property by id
+- `move --id <id>|--uuid <uuid> --target-id <id>|--target-uuid <uuid>|--target-page <name> [--pos first-child|last-child|sibling]` - move a block and its children (defaults to first-child)
+- `remove --id <id>|--uuid <uuid>|--page <name>` - remove blocks (by db/id or UUID) or pages
+- `search block --content <query>` - search blocks by `:block/title` (case-insensitive substring)
+- `search page --content <query>` - search pages by `:block/name` (case-insensitive substring)
+- `search property --content <query>` - search properties by `:block/title` (Property entities only)
+- `search tag --content <query>` - search tags by `:block/title` (Tag entities only)
+- `query --query <edn> [--inputs <edn-vector>]` - run a Datascript query against the graph
+- `query --name <query-name> [--inputs <edn-vector>]` - run a named query (built-in or from `cli.edn`)
+- `query list` - list available named queries
+- `show --page <name> [--level <n>]` - show page tree
+- `show --uuid <uuid> [--level <n>]` - show block tree
+- `show --id <id> [--level <n>]` - show block tree by db/id
+
+Help output:
+
+```
+Subcommands:
+  list page [options]      List pages
+  list tag [options]       List tags
+  list property [options]   List properties
+  list task [options]       List tasks
+  list node [options]       List nodes
+  list asset [options]      List assets
+  upsert block [options]    Upsert block
+  upsert page [options]     Upsert page
+  upsert task [options]     Upsert task
+  upsert asset [options]    Upsert asset
+  upsert tag [options]      Upsert tag
+  upsert property [options] Upsert property
+  move [options]           Move block
+  remove [options]          Remove block or page
+  search block [options]    Search blocks by title
+  search page [options]     Search pages by name
+  search property [options] Search properties by title
+  search tag [options]      Search tags by title
+  show [options]            Show tree
+```
+
+Options grouping:
+- Help output separates **Global options** (apply to all commands) and **Command options** (command-specific flags).
+
+Version output:
+- `logseq --version` prints:
+
+```
+Build time: <timestamp>
+Revision: <commit>
+```
+
+Output formats:
+- Global `--output <human|json|edn>` applies to all commands
+- Output formatting is controlled via global `--output`, `:output-format` in config, or `LOGSEQ_CLI_OUTPUT`.
+- Global `--profile` enables stage timing output to **stderr**. This is for debugging latency and does not change command stdout payloads.
+  - Human profile output is rendered as a tree (similar to `show` output style). The elapsed time column is printed at the far left with fixed width for alignment, for example:
+    ```text
+    146ms command=list status=ok
+         stages
+    146ms └── cli.total
+      4ms     ├── cli.parse-args
+    139ms     └── cli.execute-action
+    129ms         └── transport.invoke:thread-api/cli-list-pages
+    ```
+- Human output is plain text. List/search commands render tables with a final `Count: N` line. For list and search subcommands, the ID column uses `:db/id` (not UUID). If `:db/ident` exists, an `IDENT` column is included. `list property` includes dedicated `TYPE` and `CARDINALITY` columns; `list node`/`list asset` include a dedicated `TYPE` column (page/block) and page context columns for blocks. Search table columns are `ID` and `TITLE`. For `list page|tag|property|task|node|asset` in human output, the `TITLE` column is display-width-aware (CJK-safe), defaults to max width `40`, and truncates overflow with `…`; set `:list-title-max-display-width` in `cli.edn` to override. JSON/EDN outputs keep full titles (no truncation). Block titles can include multiple lines; multi-line rows align additional lines under the `TITLE` column. Times such as list `UPDATED-AT`/`CREATED-AT` and `graph info` `Created at` are shown in human-friendly relative form. Errors include error codes and may include a `Hint:` line. Use `--output json|edn` for structured output.
+- `example` human output includes `Selector`, `Matched commands`, and `Examples` sections. Structured output (`json`/`edn`) includes `selector`, `matched-commands`, `examples`, and `message` fields under `data`.
+- `skill show` always prints raw markdown text to stdout, regardless of `--output` mode.
+- `sync download` progress lines are streamed to stdout only when progress is enabled. In `json`/`edn` mode, progress is disabled by default unless `--progress true` is provided.
+- JSON machine output preserves namespaced keyword semantics:
+  - Namespaced keyword keys are emitted as canonical string keys in `namespace/name` form (for example `:block/title` -> `"block/title"`).
+  - Unqualified keyword keys remain plain strings (for example `:status` -> `"status"`).
+  - Keyword values are emitted as strings with namespace text preserved when present (for example `:db.cardinality/one` -> `"db.cardinality/one"`).
+  - UUID values are emitted as strings.
+- For `list property`, `TYPE` and cardinality are returned in default output (without `--expand`) for human and structured (`json`/`edn`) formats.
+  - Human output renders cardinality as `one` or `many` in the `CARDINALITY` column.
+  - JSON keeps namespaced key/value form via `"db/cardinality"` and values like `"db.cardinality/one"` or `"db.cardinality/many"`.
+  - EDN keeps `:db/cardinality` (for example `:db.cardinality/one` or `:db.cardinality/many`).
+  - When a property omits schema cardinality, CLI treats it as default `one`.
+
+JSON key migration (flat -> namespaced):
+
+| Old JSON key path | New JSON key path |
+| --- | --- |
+| `data.items[].title` | `data.items[].block/title` |
+| `data.items[].id` | `data.items[].db/id` |
+| `data.items[].type` | `data.items[].logseq.property/type` |
+| `data.items[].cardinality` | `data.items[].db/cardinality` |
+| `data.root.children[]` | `data.root.block/children[]` |
+- `upsert page`, `upsert block`, `upsert task`, and `upsert asset` return entity ids in `data.result` for JSON/EDN output, and include ids in human output.
+  - Human example:
+    ```text
+    Upserted page:
+    [123]
+    ```
+  - Human example:
+    ```text
+    Upserted blocks:
+    [201 202]
+    ```
+  - JSON example: `{"status":"ok","data":{"result":[123]}}`
+  - EDN example: `{:status :ok, :data {:result [123]}}`
+- `doctor` output includes overall status (`ok`, `warning`, `error`) and per-check rows for `db-worker-script`, `data-dir`, `running-servers`, and `server-revision-mismatch`. For scripting, `--output json|edn` keeps the structured check payload.
+- Common doctor failures and warnings:
+  - `doctor-script-missing`: `db-worker-node.js` runtime target is missing (default target: `dist/db-worker-node.js`; use `doctor --dev-script` to check `static/db-worker-node.js`).
+  - `doctor-script-unreadable`: script path exists but is not a readable file.
+  - `data-dir-permission`: configured data dir is not readable or writable.
+  - `doctor-server-not-ready`: one or more lock-discovered servers are still in `:starting` state (warning).
+  - `doctor-server-revision-mismatch`: one or more discovered servers use a different revision than the local CLI revision (warning). Follow the printed remediation command for each affected graph: `logseq server restart --graph <name>`.
+  - If bundled runtime startup fails with missing-module or missing-file errors, rebuild with `pnpm db-worker-node:release:bundle` and confirm `dist/db-worker-node.js` exists and every path listed in `dist/db-worker-node-assets.json` is present next to it.
+- `query` human output returns a plain string (the query result rendered via `pr-str`), which is convenient for pipelines like `logseq query ... | xargs logseq show --id`.
+- Built-in named queries currently include `block-search`, `task-search`, `recent-updated`, `list-status`, and `list-priority`. Use `query list` to see the full set for your config.
+- Show output resolves block reference UUIDs inside text, replacing `[[<uuid>]]` with the referenced block content. Nested references are resolved recursively up to 10 levels to avoid excessive expansion. For example: `[[<uuid1>]]` → `[[some text [[<uuid2>]]]]` and then `<uuid2>` is also replaced.
+- When `show` targets an ordinary block (`--id` or `--uuid`), human output prepends one breadcrumb line (`page > ... > nearest parent`) above the root block line. Each segment is display-width truncated to `24` with `…`.
+
+```text
+Project Alpha > Milestone 2026 > API rollout
+5137 Implement retry policy for upload worker
+5138 ├── Add timeout backoff guard
+5139 └── Add deterministic retry test
+```
+
+- `show` tree lines print `:db/id` as the first column:
+
+```text
+id1 block1
+id2 ├── b2
+id3 │   └── b3
+id4 ├── b4
+id5 │   ├── b5
+id6 │   │   └── b6
+id7 │   └── b7
+id8 └── b8
+```
+
+Troubleshooting:
+- If authenticated sync commands fail with missing or invalid local auth, run `logseq logout` and then `logseq login` again.
+- You can also manually remove `~/logseq/auth.json` and repeat `logseq login`.
+
+Examples:
+
+```bash
+node ./dist/logseq.js login
+node ./dist/logseq.js graph create --graph demo
+node ./dist/logseq.js graph export --type edn --file /tmp/demo.edn --graph demo
+node ./dist/logseq.js graph import --type edn --input /tmp/demo.edn --graph demo-import
+node ./dist/logseq.js graph backup create --graph demo --name nightly
+node ./dist/logseq.js graph backup list
+node ./dist/logseq.js graph backup restore --src demo-nightly-20260101T000000Z --dst demo-restore
+node ./dist/logseq.js graph backup remove --src demo-nightly-20260101T000000Z
+node ./dist/logseq.js upsert block --target-page TestPage --content "hello world"
+node ./dist/logseq.js move --uuid <uuid> --target-page TargetPage
+node ./dist/logseq.js search block --content "hello"
+node ./dist/logseq.js show --page TestPage --output json
+node ./dist/logseq.js debug pull --graph demo --ident :logseq.class/Tag --output json
+node ./dist/logseq.js server list
+node ./dist/logseq.js doctor
+node ./dist/logseq.js doctor --dev-script
+node ./dist/logseq.js doctor --output json
+node ./dist/logseq.js --graph demo sync start --e2ee-password "my-secret"
+node ./dist/logseq.js --graph demo sync download --e2ee-password "my-secret"
+node ./dist/logseq.js logout
+```
diff --git a/package.json b/package.json
index 7bff10ccda..568369cadf 100644
--- a/package.json
+++ b/package.json
@@ -4,6 +4,14 @@
     "private": true,
     "packageManager": "pnpm@10.33.0",
     "main": "static/electron.js",
+    "bin": {
+        "logseq": "dist/logseq.js"
+    },
+    "files": [
+        "dist/",
+        "static/logseq-cli.js",
+        ".agents/skills/logseq-cli/SKILL.md"
+    ],
     "engines": {
         "node": ">=22.20.0"
     },
@@ -98,36 +106,44 @@
         "electron:make": "node scripts/static-pipeline.mjs electron-maker",
         "css:build": "pnpm vite:css-build",
         "css:watch": "pnpm vite:css-watch",
-        "cljs:watch": "clojure -M:cljs watch app db-worker electron",
+        "cljs:watch": "clojure -M:cljs watch app db-worker db-worker-node electron",
         "css:mobile-build": "pnpm vite:css-mobile-build",
         "css:mobile-watch": "pnpm vite:css-mobile-watch",
-        "cljs:mobile-watch": "clojure -M:cljs watch mobile db-worker --config-merge \"{:asset-path \\\"/static/mobile/js\\\" :release {:asset-path \\\"http://localhost\\\"}}\"",
+        "cljs:mobile-watch": "clojure -M:cljs watch mobile db-worker db-worker-node --config-merge \"{:asset-path \\\"/static/mobile/js\\\" :release {:asset-path \\\"http://localhost\\\"}}\"",
         "cljs:release-mobile": "run-s cljs:release-mobile:shadow vite:mobile-build",
-        "cljs:release-mobile:shadow": "clojure -M:cljs release mobile db-worker --config-merge \"{:asset-path \\\"/static/mobile/js\\\" :release {:asset-path \\\"http://localhost\\\"}}\"",
-        "cljs:dev-watch": "clojure -M:cljs watch app db-worker electron mobile",
-        "cljs:app-watch": "clojure -M:cljs watch app db-worker",
+        "cljs:release-mobile:shadow": "clojure -M:cljs release mobile db-worker db-worker-node --config-merge \"{:asset-path \\\"/static/mobile/js\\\" :release {:asset-path \\\"http://localhost\\\"}}\"",
+        "cljs:dev-watch": "clojure -M:cljs watch app db-worker db-worker-node electron mobile logseq-cli",
+        "cljs:app-watch": "clojure -M:cljs watch app db-worker db-worker-node logseq-cli",
         "cljs:publishing-watch": "clojure -M:cljs watch publishing",
-        "cljs:electron-watch": "clojure -M:cljs watch app db-worker electron test --config-merge \"{:asset-path \\\"./js\\\"}\"",
+        "cljs:electron-watch": "clojure -M:cljs watch app db-worker db-worker-node electron logseq-cli test --config-merge \"{:asset-path \\\"./js\\\"}\"",
         "cljs:release": "run-s cljs:release:shadow vite:app-build vite:publishing-build",
-        "cljs:release:shadow": "clojure -M:cljs release app db-worker publishing electron",
+        "cljs:release:shadow": "clojure -M:cljs release app db-worker db-worker-node publishing electron logseq-cli",
         "cljs:release-electron": "run-s cljs:release-electron:shadow vite:app-build vite:publishing-build",
-        "cljs:release-electron:shadow": "clojure -M:cljs release app db-worker electron --debug && clojure -M:cljs release publishing",
+        "cljs:release-electron:shadow": "clojure -M:cljs release app db-worker db-worker-node electron logseq-cli --debug && clojure -M:cljs release publishing",
         "cljs:release-app": "run-s cljs:release-app:shadow vite:app-build",
-        "cljs:release-app:shadow": "clojure -M:cljs release app db-worker",
+        "cljs:release-app:shadow": "clojure -M:cljs release app db-worker db-worker-node logseq-cli",
         "cljs:release-publishing": "run-s cljs:release-publishing:shadow vite:app-build vite:publishing-build",
         "cljs:release-publishing:shadow": "clojure -M:cljs release app db-worker publishing",
         "cljs:test": "clojure -M:test compile test",
-        "cljs:run-test": "node static/tests.js -r \"^(?!logseq.db-sync.).*\" -e fix-me",
+        "cljs:run-test": "cross-env LOGSEQ_STABLE_IDENTS=1 node static/tests.js -r \"^(?!(?:logseq.db-sync.|logseq.cli.integration-test)).*\" -e fix-me",
+        "cljs:run-integration-test": "node static/tests.js -r '^(logseq.cli.integration-test).*'",
         "cljs:test-no-worker": "clojure -M:test compile test-no-worker",
         "cljs:run-test-no-worker": "node static/tests-no-worker.js",
+        "db-worker-node:compile": "clojure -M:cljs compile db-worker-node",
+        "db-worker-node:release": "clojure -M:cljs release db-worker-node",
+        "db-worker-node:bundle": "node ./scripts/build-db-worker-node-bundle.mjs",
+        "db-worker-node:release:bundle": "run-s db-worker-node:release db-worker-node:bundle",
+        "db-worker-node:compile:bundle": "run-s db-worker-node:compile db-worker-node:bundle",
+        "cli:e2e": "bb dev:cli-e2e",
+        "cli:e2e:skip-build": "bb dev:cli-e2e --skip-build",
         "cljs:dev-release-app": "run-s cljs:dev-release-app:shadow vite:app-build",
-        "cljs:dev-release-app:shadow": "clojure -M:cljs release app db-worker --config-merge \"{:closure-defines {frontend.config/DEV-RELEASE true}}\"",
+        "cljs:dev-release-app:shadow": "clojure -M:cljs release app db-worker db-worker-node --config-merge \"{:closure-defines {frontend.config/DEV-RELEASE true}}\"",
         "cljs:dev-release-electron": "run-s cljs:dev-release-electron:shadow vite:app-build vite:publishing-build",
-        "cljs:dev-release-electron:shadow": "clojure -M:cljs release app db-worker electron --debug --config-merge \"{:closure-defines {frontend.config/DEV-RELEASE true}}\" && clojure -M:cljs release publishing",
+        "cljs:dev-release-electron:shadow": "clojure -M:cljs release app db-worker db-worker-node electron --debug --config-merge \"{:closure-defines {frontend.config/DEV-RELEASE true}}\" && clojure -M:cljs release publishing",
         "cljs:debug": "run-s cljs:debug:shadow vite:app-build",
-        "cljs:debug:shadow": "clojure -M:cljs release app db-worker --debug",
-        "cljs:report": "clojure -M:cljs run shadow.cljs.build-report app db-worker report.html",
-        "cljs:build-electron": "clojure -A:cljs compile app db-worker electron",
+        "cljs:debug:shadow": "clojure -M:cljs release app db-worker db-worker-node --debug",
+        "cljs:report": "clojure -M:cljs run shadow.cljs.build-report app db-worker db-worker-node report.html",
+        "cljs:build-electron": "clojure -A:cljs compile app db-worker db-worker-node electron",
         "cljs:lint": "clojure -M:clj-kondo --parallel --lint src --cache false",
         "ios:dev": "cross-env PLATFORM=ios node scripts/static-pipeline.mjs cap",
         "android:dev": "cross-env PLATFORM=android node scripts/static-pipeline.mjs cap",
@@ -186,6 +202,7 @@
         "interactjs": "^1.10.27",
         "jszip": "3.10.1",
         "katex": "^0.16.40",
+        "keytar": "^7.9.0",
         "marked": "^17.0.5",
         "mldoc": "^1.5.9",
         "path": "0.12.7",
@@ -205,6 +222,7 @@
         "remove-accents": "0.5.0",
         "sanitize-filename": "1.6.4",
         "send-intent": "^7.0.0",
+        "string-width": "8.2.0",
         "tiny-pinyin": "1.3.2",
         "url": "^0.11.4",
         "util": "^0.12.5"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a3da6a4dda..f76608d152 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -180,6 +180,9 @@ importers:
       katex:
         specifier: ^0.16.40
         version: 0.16.40
+      keytar:
+        specifier: ^7.9.0
+        version: 7.9.0
       marked:
         specifier: ^17.0.5
         version: 17.0.5
@@ -237,6 +240,9 @@ importers:
       send-intent:
         specifier: ^7.0.0
         version: 7.0.0(@capacitor/core@8.2.0)
+      string-width:
+        specifier: 8.2.0
+        version: 8.2.0
       tiny-pinyin:
         specifier: 1.3.2
         version: 1.3.2
@@ -1290,6 +1296,10 @@ packages:
     resolution: {integrity: sha512-7HSX4QQb4CspciLpVFwyRe79O3xsIZDDLER21kERQ71oaPodF8jL725AgJMFAYbooIqolJoRLuM81SpeUkpkvA==}
     engines: {node: '>=12'}
 
+  ansi-regex@6.2.2:
+    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
+    engines: {node: '>=12'}
+
   ansi-styles@3.2.1:
     resolution: {integrity: sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==}
     engines: {node: '>=4'}
@@ -2195,6 +2205,10 @@ packages:
     resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
     engines: {node: 6.* || 8.* || >= 10.*}
 
+  get-east-asian-width@1.5.0:
+    resolution: {integrity: sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA==}
+    engines: {node: '>=18'}
+
   get-intrinsic@1.3.0:
     resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
     engines: {node: '>= 0.4'}
@@ -2629,6 +2643,9 @@ packages:
     resolution: {integrity: sha512-1DJcK/L05k1Y9Gf7wMcyuqFOL6BiY3vY0CFcAM/LPRN04NALxcl6u7lOWNsp3f/bCHWxigzQl6FbR95XJ4R84Q==}
     hasBin: true
 
+  keytar@7.9.0:
+    resolution: {integrity: sha512-VPD8mtVtm5JNtA2AErl6Chp06JBfy7diFQ7TQQhdpWOl6MrCRB+eRbvAZUsbGQS9kiMq0coJsy0W0vHpDCkWsQ==}
+
   keyv@4.5.4:
     resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
 
@@ -2994,6 +3011,9 @@ packages:
     resolution: {integrity: sha512-OhYaY5sDsIka7H7AtijtI9jwGYLyl29eQn/W623DiN/MIv5sUqc4g7BIDThX+gb7di9f6xK02nkp8sdfFWZLTg==}
     engines: {node: '>=10'}
 
+  node-addon-api@4.3.0:
+    resolution: {integrity: sha512-73sE9+3UaLYYFmDsFZnqCInzPyh3MqIwZO9cw58yIqAZhONrrabrYyYe3TuIqtIiOuTXVhsGau8hcrhhwSsDIQ==}
+
   node-addon-api@6.1.0:
     resolution: {integrity: sha512-+eawOlIgy680F0kBzPUNFhMZGtJ1YmqM6l4+Crf4IkImjYrO/mqPwRMh352g23uIaQKFItcQ64I7KMaJxHgAVA==}
 
@@ -3989,6 +4009,10 @@ packages:
     resolution: {integrity: sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==}
     engines: {node: '>=12'}
 
+  string-width@8.2.0:
+    resolution: {integrity: sha512-6hJPQ8N0V0P3SNmP6h2J99RLuzrWz2gvT7VnK5tKvrNqJoyS9W4/Fb8mo31UiPvy00z7DQXkP2hnKBVav76thw==}
+    engines: {node: '>=20'}
+
   string_decoder@1.1.1:
     resolution: {integrity: sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==}
 
@@ -4011,6 +4035,10 @@ packages:
     resolution: {integrity: sha512-iq6eVVI64nQQTRYq2KtEg2d2uU7LElhTJwsH4YzIHZshxlgZms/wIc4VoDQTlG/IvVIrBKG06CrZnp0qv7hkcQ==}
     engines: {node: '>=12'}
 
+  strip-ansi@7.2.0:
+    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
+    engines: {node: '>=12'}
+
   strip-bom@3.0.0:
     resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==}
     engines: {node: '>=4'}
@@ -5642,6 +5670,8 @@ snapshots:
 
   ansi-regex@6.1.0: {}
 
+  ansi-regex@6.2.2: {}
+
   ansi-styles@3.2.1:
     dependencies:
       color-convert: 1.9.3
@@ -6595,6 +6625,8 @@ snapshots:
 
   get-caller-file@2.0.5: {}
 
+  get-east-asian-width@1.5.0: {}
+
   get-intrinsic@1.3.0:
     dependencies:
       call-bind-apply-helpers: 1.0.2
@@ -6998,6 +7030,11 @@ snapshots:
     dependencies:
       commander: 8.3.0
 
+  keytar@7.9.0:
+    dependencies:
+      node-addon-api: 4.3.0
+      prebuild-install: 7.1.3
+
   keyv@4.5.4:
     dependencies:
       json-buffer: 3.0.1
@@ -7341,6 +7378,8 @@ snapshots:
     dependencies:
       semver: 7.7.4
 
+  node-addon-api@4.3.0: {}
+
   node-addon-api@6.1.0: {}
 
   node-fetch@2.7.0:
@@ -8399,6 +8438,11 @@ snapshots:
       emoji-regex: 9.2.2
       strip-ansi: 7.1.0
 
+  string-width@8.2.0:
+    dependencies:
+      get-east-asian-width: 1.5.0
+      strip-ansi: 7.2.0
+
   string_decoder@1.1.1:
     dependencies:
       safe-buffer: 5.1.2
@@ -8423,6 +8467,10 @@ snapshots:
     dependencies:
       ansi-regex: 6.1.0
 
+  strip-ansi@7.2.0:
+    dependencies:
+      ansi-regex: 6.2.2
+
   strip-bom@3.0.0: {}
 
   strip-eof@1.0.0: {}
diff --git a/resources/forge.config.test.js b/resources/forge.config.test.js
new file mode 100644
index 0000000000..1da63bf832
--- /dev/null
+++ b/resources/forge.config.test.js
@@ -0,0 +1,61 @@
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const path = require('path')
+
+const config = require('./forge.config')
+
+const repoRoot = path.resolve(__dirname, '..')
+
+function normalizeResourcePath(resourcePath) {
+  return path.resolve(resourcePath)
+}
+
+function collectExtraResources() {
+  return (config.packagerConfig?.extraResource || []).map(normalizeResourcePath)
+}
+
+function isCoveredByExtraResources(targetPath, extraResources) {
+  const normalizedTarget = path.resolve(targetPath)
+  return extraResources.some((resource) =>
+    normalizedTarget === resource || normalizedTarget.startsWith(resource + path.sep)
+  )
+}
+
+test('packager includes all JavaScript files under dist/', () => {
+  const distDir = path.resolve(repoRoot, 'dist')
+  const distJsFiles = fs
+    .readdirSync(distDir)
+    .filter((name) => name.endsWith('.js'))
+    .map((name) => path.join(distDir, name))
+
+  assert.ok(
+    distJsFiles.length > 0,
+    'Expected dist/ to contain at least one JavaScript file for packaging checks'
+  )
+
+  const extraResources = collectExtraResources()
+
+  for (const jsFile of distJsFiles) {
+    assert.ok(
+      isCoveredByExtraResources(jsFile, extraResources),
+      `Expected extraResource to include or cover ${jsFile}`
+    )
+  }
+})
+
+test('packager includes dist/build directory', () => {
+  const distBuildDir = path.resolve(repoRoot, 'dist/build')
+
+  assert.ok(
+    fs.existsSync(distBuildDir),
+    'Expected dist/build directory to exist for packaging checks'
+  )
+
+  const extraResources = collectExtraResources()
+
+  assert.ok(
+    isCoveredByExtraResources(distBuildDir, extraResources),
+    `Expected extraResource to include or cover ${distBuildDir}`
+  )
+})
diff --git a/resources/js/preload.js b/resources/js/preload.js
index 47b6ab76e2..7288a4f36f 100644
--- a/resources/js/preload.js
+++ b/resources/js/preload.js
@@ -135,6 +135,16 @@ contextBridge.exposeInMainWorld('apis', {
     return await ipcRenderer.invoke('call-main-win', type, ...args)
   },
 
+  /**
+   * Write binary data to a file, creating parent dirs as needed.
+   * Used for asset files that can't be transit-serialized through doAction.
+   */
+  writeFileBytes (filePath, data) {
+    const dir = path.dirname(filePath)
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(filePath, Buffer.from(data))
+  },
+
   getFilePathFromClipboard,
 
   getClipboardData,
diff --git a/resources/js/worker.js b/resources/js/worker.js
index 530d560ed6..139a3c80ac 100644
--- a/resources/js/worker.js
+++ b/resources/js/worker.js
@@ -20,6 +20,11 @@ const createFS = () => new LightningFS(fsName);
 let fs = createFS();
 let pfs = fs.promises;
 
+if (typeof self !== 'undefined') {
+  self.fs = fs;
+  self.pfs = pfs;
+}
+
 if (detect() === 'Worker') {
   const portal = new MagicPortal(self);
   portal.set('fs', fs);
diff --git a/resources/mobile/js/worker.js b/resources/mobile/js/worker.js
index fe041decf9..895dffb6b5 100644
--- a/resources/mobile/js/worker.js
+++ b/resources/mobile/js/worker.js
@@ -20,6 +20,11 @@ const createFS = () => new LightningFS(fsName);
 let fs = createFS();
 let pfs = fs.promises;
 
+if (typeof self !== 'undefined') {
+  self.fs = fs;
+  self.pfs = pfs;
+}
+
 if (detect() === 'Worker') {
   const portal = new MagicPortal(self);
   portal.set('fs', fs);
diff --git a/scripts/build-db-worker-node-bundle.mjs b/scripts/build-db-worker-node-bundle.mjs
new file mode 100644
index 0000000000..2dbbfd0745
--- /dev/null
+++ b/scripts/build-db-worker-node-bundle.mjs
@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+import { promises as fs } from "node:fs";
+import { builtinModules } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "vite";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, "..");
+const distDir = path.join(repoRoot, "dist");
+const shadowEntry = path.join(repoRoot, "static", "db-worker-node.js");
+const bundleEntry = path.join(distDir, "db-worker-node.js");
+const manifestPath = path.join(distDir, "db-worker-node-assets.json");
+const legacyNccOutDir = path.join(distDir, ".db-worker-node-ncc");
+const builtinModuleSet = new Set([
+  ...builtinModules,
+  ...builtinModules.map((moduleName) => `node:${moduleName}`),
+]);
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listFilesRecursive(baseDir, dir = baseDir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const absolute = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listFilesRecursive(baseDir, absolute)));
+    } else if (entry.isFile()) {
+      files.push(path.relative(baseDir, absolute));
+    }
+  }
+  return files.sort();
+}
+
+async function removeIfExists(targetPath) {
+  if (await exists(targetPath)) {
+    await fs.rm(targetPath, { recursive: true, force: true });
+  }
+}
+
+async function cleanupPreviousBundle() {
+  // Remove the legacy ncc output directory if it still exists from older builds.
+  await removeIfExists(legacyNccOutDir);
+  await removeIfExists(bundleEntry);
+
+  if (await exists(manifestPath)) {
+    let manifest;
+    try {
+      manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    } catch (error) {
+      throw new Error(`failed to read ${manifestPath}: ${error.message}`);
+    }
+
+    const assets = Array.isArray(manifest.assets) ? manifest.assets : [];
+    for (const relativePath of assets) {
+      if (typeof relativePath !== "string" || relativePath.length === 0) {
+        continue;
+      }
+      const assetPath = path.join(distDir, relativePath);
+      await removeIfExists(assetPath);
+    }
+  }
+
+  await removeIfExists(manifestPath);
+}
+
+async function main() {
+  if (!(await exists(shadowEntry))) {
+    throw new Error(`missing shadow entry: ${shadowEntry}`);
+  }
+
+  await cleanupPreviousBundle();
+  await fs.mkdir(distDir, { recursive: true });
+  const filesBefore = await listFilesRecursive(distDir);
+
+  await build({
+    configFile: false,
+    logLevel: "error",
+    build: {
+      codeSplitting: false,
+      minify: "terser",
+      target: "node22",
+      sourcemap: false,
+      write: true,
+      emptyOutDir: false,
+      outDir: distDir,
+      lib: {
+        entry: shadowEntry,
+        formats: ["cjs"],
+        fileName: () => "db-worker-node.js",
+      },
+      rollupOptions: {
+        external: (id) =>
+          id.endsWith(".node") || id.startsWith("node:") || builtinModuleSet.has(id),
+        output: {
+          format: "cjs",
+          exports: "auto",
+          entryFileNames: "db-worker-node.js",
+          chunkFileNames: "db-worker-node.js",
+        },
+      },
+    },
+  });
+
+  if (!(await exists(bundleEntry))) {
+    throw new Error(`vite bundle missing output file: ${bundleEntry}`);
+  }
+
+  let filesAfter = await listFilesRecursive(distDir);
+  if (filesAfter.includes("index.html") && !filesBefore.includes("index.html")) {
+    await removeIfExists(path.join(distDir, "index.html"));
+    filesAfter = await listFilesRecursive(distDir);
+  }
+
+  const extraJsFiles = filesAfter.filter(
+    (relativePath) =>
+      relativePath.endsWith(".js") &&
+      relativePath !== "db-worker-node.js" &&
+      !filesBefore.includes(relativePath)
+  );
+  if (extraJsFiles.length > 0) {
+    throw new Error(
+      `vite bundle produced unexpected JS outputs: ${extraJsFiles.join(", ")}`
+    );
+  }
+
+  await fs.writeFile(
+    manifestPath,
+    `${JSON.stringify(
+      {
+        assets: [],
+      },
+      null,
+      2
+    )}\n`,
+    "utf8"
+  );
+}
+
+main().catch((error) => {
+  console.error(`[db-worker-node-bundle] ${error.message}`);
+  process.exit(1);
+});
diff --git a/scripts/src/logseq/tasks/common_errors.clj b/scripts/src/logseq/tasks/common_errors.clj
index 862a78006c..c459d3fa2d 100644
--- a/scripts/src/logseq/tasks/common_errors.clj
+++ b/scripts/src/logseq/tasks/common_errors.clj
@@ -7,9 +7,9 @@
 (defn check-common-errors
   []
   (let [prompt (String. (fs/read-all-bytes "prompts/review.md"))
-        diff (:out (shell {:out :string} "git diff --no-prefix -U100 -- '*.cljs'"))]
+        diff (:out (shell {:out :string :shutdown nil} "git diff --no-prefix -U100 -- '*.cljs'"))]
     (when-not (string/blank? diff)
       (let [command (format "gh models run openai/gpt-5 \"%s\""
                             (str prompt
                                  (format "\n\n <diff>%s</diff>" diff)))]
-        (shell command)))))
+        (shell {:shutdown nil} command)))))
diff --git a/scripts/src/logseq/tasks/dev.clj b/scripts/src/logseq/tasks/dev.clj
index 6428f0dd88..3244d0514f 100644
--- a/scripts/src/logseq/tasks/dev.clj
+++ b/scripts/src/logseq/tasks/dev.clj
@@ -17,8 +17,8 @@
 (defn test
   "Run tests. Pass args through to cmd 'pnpm cljs:run-test'"
   [& args]
-  (shell "pnpm cljs:test")
-  (apply shell "pnpm cljs:run-test" args))
+  (shell {:shutdown nil} "pnpm cljs:test")
+  (apply shell {:shutdown nil} "pnpm cljs:run-test" args))
 
 (defn test-no-worker
   "Run tests without compiling worker namespaces. Pass args through to cmd 'pnpm cljs:run-test-no-worker'"
@@ -27,8 +27,7 @@
   (apply shell "pnpm cljs:run-test-no-worker" args))
 
 (defn lint-and-test
-  "Run all lint tasks, then run tests(exclude testcases tagged by :long).
-  pass args through to cmd 'pnpm cljs:run-test'"
+  "Run all lint tasks, then run tests excluding testcases tagged by :long and :fix-me."
   []
   (dev-lint/dev)
   (test "-e" "long" "-e" "fix-me"))
@@ -50,11 +49,12 @@
   (let [config-edn ".clj-kondo/metosin/malli-types/config.edn"
         compile-cmd "clojure -M:cljs compile gen-malli-kondo-config"]
     (println compile-cmd)
-    (shell compile-cmd)
+    (shell {:shutdown nil} compile-cmd)
     (println "generate kondo config: " config-edn)
     (io/make-parents config-edn)
     (let [config (with-out-str
-                   (pp/pprint (edn/read-string (:out (shell {:out :string} "node ./static/gen-malli-kondo-config.js")))))]
+                   (pp/pprint (edn/read-string (:out (shell {:out :string :shutdown nil}
+                                                            "node ./static/gen-malli-kondo-config.js")))))]
       (spit config-edn config))))
 
 (defn diff-datoms
@@ -81,19 +81,19 @@
                                                     (fs/glob "." "{src/main,deps/graph-parser/src}/**")))))]
     (do
       (println "Building publishing js asset...")
-      (shell "pnpm cljs:release-publishing"))
+      (shell {:shutdown nil} "pnpm cljs:release-publishing"))
     (println "Publishing js asset is up to date")))
 
 (defn publishing-backend
   "Builds publishing backend and copies over supporting frontend assets"
   [& args]
-  (apply shell {:dir "deps/publishing" :extra-env {"ORIGINAL_PWD" (fs/cwd)}}
+  (apply shell {:dir "deps/publishing" :extra-env {"ORIGINAL_PWD" (fs/cwd)} :shutdown nil}
          "pnpm exec nbb-logseq -cp src:../graph-parser/src script/publishing.cljs"
          (into ["static"] args)))
 
 (defn watch-publishing-frontend
   [& _args]
-  (shell "pnpm publishing-watch"))
+  (shell {:shutdown nil} "pnpm publishing-watch"))
 
 (defn watch-publishing-backend
   "Builds publishing backend once watch-publishing-frontend has built initial frontend"
@@ -115,4 +115,4 @@
     (doseq [file-graph file-graphs]
       (let [db-graph (fs/path parent-graph-dir (fs/file-name file-graph))]
         (println "Importing" (str db-graph) "...")
-        (apply shell "bb" "dev:import" file-graph db-graph (concat import-options ["--validate"]))))))
+        (apply shell {:shutdown nil} "bb" "dev:db-import" file-graph db-graph (concat import-options ["--validate"]))))))
diff --git a/scripts/src/logseq/tasks/dev/desktop.clj b/scripts/src/logseq/tasks/dev/desktop.clj
index 61b16f991a..257e5e3647 100644
--- a/scripts/src/logseq/tasks/dev/desktop.clj
+++ b/scripts/src/logseq/tasks/dev/desktop.clj
@@ -7,7 +7,7 @@
 (defn watch
   "Watches environment to reload cljs, css and other assets"
   []
-  (shell "pnpm electron-watch"))
+  (shell {:shutdown nil} "pnpm electron-watch"))
 
 (defn open-dev-electron-app
   "Opens dev-electron-app when watch process has built main.js"
@@ -16,6 +16,6 @@
     (dotimes [_n 1000]
              (if (and (fs/exists? "static/js/main.js")
                       (task-util/file-modified-later-than? "static/js/main.js" start-time))
-               (shell "pnpm dev-electron-app")
+               (shell {:shutdown nil} "pnpm dev-electron-app")
                (println "Waiting for app to build..."))
              (Thread/sleep 1000))))
diff --git a/scripts/src/logseq/tasks/dev/lint.clj b/scripts/src/logseq/tasks/dev/lint.clj
index e199091de2..894ceaa80b 100644
--- a/scripts/src/logseq/tasks/dev/lint.clj
+++ b/scripts/src/logseq/tasks/dev/lint.clj
@@ -18,14 +18,14 @@
                "bb lang:validate-translations"
                "bb lint:ns-docstrings"]]
     (println cmd)
-    (shell cmd)))
+    (shell {:shutdown nil} cmd)))
 
 (defn kondo-git-changes
   "Run clj-kondo across dirs and only for files that git diff detects as unstaged changes"
   []
   (let [kondo-dirs ["src" "deps/common" "deps/db" "deps/graph-parser" "deps/outliner" "deps/publishing" "deps/publish" "deps/cli"]
         dir-regex (re-pattern (str "^(" (string/join "|" kondo-dirs) ")"))
-        dir-to-files (->> (shell {:out :string} "git diff --name-only")
+        dir-to-files (->> (shell {:out :string :shutdown nil} "git diff --name-only")
                           :out
                           string/split-lines
                           (filter #(re-find #"\.(cljs|clj|cljc)$" %))
@@ -38,13 +38,13 @@
               files (mapv #(string/replace-first % (str dir "/") "") files*)
               cmd (str "cd " dir " && clj-kondo --lint " (string/join " " files))
               _ (println cmd)
-              res (apply shell {:dir dir :continue :true} "clj-kondo --lint" files)]
+              res (apply shell {:dir dir :continue :true :shutdown nil} "clj-kondo --lint" files)]
           (when (pos? (:exit res)) (System/exit (:exit res)))))
       (println "No clj* files have changed to lint."))))
 
 (defn- validate-frontend-not-in-workers
   []
-  (let [res (shell {:out :string}
+  (let [res (shell {:out :string :shutdown nil}
                    "git grep -h" "\\[frontend.*:as"
                    "src/main/frontend/worker" "src/main/frontend/worker_common")
         req-lines (->> (:out res)
@@ -60,7 +60,7 @@
 
 (defn- validate-workers-not-in-frontend
   []
-  (let [res (shell {:out :string :continue true}
+  (let [res (shell {:out :string :continue true :shutdown nil}
                    "git grep --untracked --exclude-standard"
                    "\\[frontend.worker.*:" "--" "src/main/frontend")
         ;; allow reset-file b/c it's only affects tests
diff --git a/scripts/src/logseq/tasks/dev/mobile.clj b/scripts/src/logseq/tasks/dev/mobile.clj
index 2d97c15f73..f5823813db 100644
--- a/scripts/src/logseq/tasks/dev/mobile.clj
+++ b/scripts/src/logseq/tasks/dev/mobile.clj
@@ -12,7 +12,7 @@
     (loop [n 1000]
       (if (and (fs/exists? "static/js/main.js")
                (task-util/file-modified-later-than? "static/js/main.js" start-time))
-        (shell cmd)
+        (shell {:shutdown nil} cmd)
         (println "Waiting for app to build..."))
       (Thread/sleep 1000)
       (when-not (or (and (fs/exists? "ios/App/App/public/js/main.js")
@@ -24,11 +24,11 @@
 (defn- set-system-env
   "Updates capacitor.config.ts serve url with IP from ifconfig"
   []
-  (let [ip (string/trim (:out (or (shell {:out :string :continue true} "ipconfig getifaddr en0")
-                                  (shell {:out :string} "ipconfig getifaddr en1"))))
+  (let [ip (string/trim (:out (or (shell {:out :string :continue true :shutdown nil} "ipconfig getifaddr en0")
+                                  (shell {:out :string :shutdown nil} "ipconfig getifaddr en1"))))
         logseq-app-server-url (format "%s://%s:%s" "http" ip "3001")]
     (println "Server URL:" logseq-app-server-url)
-    (shell "git checkout capacitor.config.ts")
+    (shell {:shutdown nil} "git checkout capacitor.config.ts")
     (let [new-body (-> (slurp "capacitor.config.ts")
                        (string/replace "// , server:" " , server:")
                        (string/replace "//    url:" "    url:")
@@ -46,28 +46,28 @@
   (doseq [cmd ["pnpm clean"
                "pnpm app-watch"]]
     (println cmd)
-    (shell cmd)))
+    (shell {:shutdown nil} cmd)))
 
 (defn cap-run-ios
   "Copy assets files to iOS build directory, and run app in Xcode"
   []
   (open-dev-app "pnpm exec cap sync ios")
-  (shell "pnpm exec cap open ios"))
+  (shell {:shutdown nil} "pnpm exec cap open ios"))
 
 (defn cap-run-android
   "Copy assets files to Android build directory, and run app in Android Studio"
   []
   (open-dev-app "pnpm exec cap sync android")
-  (shell "pnpm exec cap open android"))
+  (shell {:shutdown nil} "pnpm exec cap open android"))
 
 (defn run-ios-release
   "Build iOS app release"
   []
-  (shell "git checkout capacitor.config.ts")
-  (shell "pnpm run-ios-release"))
+  (shell {:shutdown nil} "git checkout capacitor.config.ts")
+  (shell {:shutdown nil} "pnpm run-ios-release"))
 
 (defn run-android-release
   "Build Android app release"
   []
-  (shell "git checkout capacitor.config.ts")
-  (shell "pnpm run-android-release"))
+  (shell {:shutdown nil} "git checkout capacitor.config.ts")
+  (shell {:shutdown nil} "pnpm run-android-release"))
diff --git a/shadow-cljs.edn b/shadow-cljs.edn
index 5d24fb4217..f070c74113 100644
--- a/shadow-cljs.edn
+++ b/shadow-cljs.edn
@@ -40,10 +40,6 @@
                           frontend.modules.instrumentation.sentry/SENTRY-DSN #shadow/env "LOGSEQ_SENTRY_DSN"
                           frontend.modules.instrumentation.posthog/POSTHOG-TOKEN #shadow/env "LOGSEQ_POSTHOG_TOKEN"
                           frontend.config/ENABLE-PLUGINS #shadow/env ["ENABLE_PLUGINS" :as :bool :default true]
-                          ;; Set to switch file sync server to dev, set this to false in `pnpm watch`
-                          frontend.config/ENABLE-FILE-SYNC-PRODUCTION #shadow/env ["ENABLE_FILE_SYNC_PRODUCTION" :as :bool :default true]
-                          frontend.config/ENABLE-RTC-SYNC-PRODUCTION #shadow/env ["ENABLE_RTC_SYNC_PRODUCTION" :as :bool :default true]
-
                           frontend.config/ENABLE-DB-SYNC-LOCAL #shadow/env ["ENABLE_DB_SYNC_LOCAL" :as :bool :default false]
                           frontend.config/REVISION #shadow/env ["LOGSEQ_REVISION" :default "dev"]} ;; set by git-revision-hook
 
@@ -86,6 +82,32 @@
                                     shadow.remote.runtime.cljs.browser]
                          :loader-mode :eval}}
 
+  :db-worker-node {:target :node-script
+                   :output-to "static/db-worker-node.js"
+                   :main frontend.worker.db-worker-node/main
+                   :build-hooks [(shadow.hooks/db-worker-node-metadata-hook "--long --always --dirty")]
+                   :compiler-options {:infer-externs :auto
+                                      :source-map true
+                                      :externs ["datascript/externs.js"
+                                                "externs.js"]
+                                      :warnings {:fn-deprecated false
+                                                 :redef false}}
+                   :closure-defines {goog.debug.LOGGING_ENABLED true}}
+
+  :logseq-cli {:target :node-script
+               :output-to "static/logseq-cli.js"
+               :main logseq.cli.main/main
+               :devtools {:enabled false}
+               :build-hooks [(shadow.hooks/logseq-cli-metadata-hook "--long --always --dirty")]
+               :closure-defines {goog.debug.LOGGING_ENABLED true
+                                 lambdaisland.glogi.console/colorize "false"
+                                 lambdaisland.glogi.console/timestamp "true"}
+               :compiler-options {:infer-externs :auto
+                                  :source-map true
+                                  :externs ["datascript/externs.js"
+                                            "externs.js"]
+                                  :warnings {:fn-deprecated false
+                                             :redef false}}}
   :mobile {:target        :browser
            :module-loader true
            :js-options    {:ignore-asset-requires true
@@ -117,10 +139,6 @@
             frontend.modules.instrumentation.sentry/SENTRY-DSN #shadow/env "LOGSEQ_SENTRY_DSN"
             frontend.modules.instrumentation.posthog/POSTHOG-TOKEN #shadow/env "LOGSEQ_POSTHOG_TOKEN"
             ;; frontend.config/ENABLE-PLUGINS #shadow/env ["ENABLE_PLUGINS" :as :bool :default true]
-            ;; Set to switch file sync server to dev, set this to false in `pnpm watch`
-            frontend.config/ENABLE-FILE-SYNC-PRODUCTION #shadow/env ["ENABLE_FILE_SYNC_PRODUCTION" :as :bool :default true]
-            frontend.config/ENABLE-RTC-SYNC-PRODUCTION #shadow/env ["ENABLE_RTC_SYNC_PRODUCTION" :as :bool :default true]
-
             frontend.config/ENABLE-DB-SYNC-LOCAL #shadow/env ["ENABLE_DB_SYNC_LOCAL" :as :bool :default false]
             frontend.config/REVISION #shadow/env ["LOGSEQ_REVISION" :default "dev"]}
 
@@ -143,13 +161,18 @@
                                 :externs ["datascript/externs.js"
                                           "externs.js"]
                                 :warnings {:fn-deprecated false
-                                           :redef false}}}
+                                           :redef false}}
+             :closure-defines {goog.debug.LOGGING_ENABLED true}}
 
   :test {:target :node-test
          :output-to "static/tests.js"
          :closure-defines {frontend.util/NODETEST true
                            frontend.worker-common.util/NODETEST true
-                           logseq.shui.util/NODETEST true}
+                           logseq.shui.util/NODETEST true
+                           frontend.worker.version/BUILD_TIME "test-worker-build-time"
+                           frontend.worker.version/REVISION "test-worker-revision"
+                           logseq.cli.version/BUILD_TIME "test-build-time"
+                           logseq.cli.version/REVISION "test-revision"}
          :devtools {:enabled false}
          ;; disable :static-fns to allow for with-redefs and repl development
          :compiler-options {:static-fns false}
diff --git a/src/dev-cljs/shadow/hooks.clj b/src/dev-cljs/shadow/hooks.clj
index 60b4cd34f4..492c866669 100644
--- a/src/dev-cljs/shadow/hooks.clj
+++ b/src/dev-cljs/shadow/hooks.clj
@@ -24,3 +24,47 @@
                   (assoc defines-in-config 'frontend.config/REVISION revision))
         (assoc-in [:compiler-options :closure-defines]
                   (assoc defines-in-options 'frontend.config/REVISION revision)))))
+
+(defn- env-or
+  [key fallback]
+  (or (System/getenv key) fallback))
+
+(defn- iso-now
+  []
+  (.format java.time.format.DateTimeFormatter/ISO_INSTANT (java.time.Instant/now)))
+
+(defn logseq-cli-metadata-hook
+  {:shadow.build/stage :configure}
+  [build-state & args]
+  (let [defines-in-config (get-in build-state [:shadow.build/config :closure-defines])
+        defines-in-options (get-in build-state [:compiler-options :closure-defines])
+        revision (env-or "LOGSEQ_REVISION" (or (exec "git" "describe" args) "dev"))
+        build-time (env-or "LOGSEQ_BUILD_TIME" (iso-now))]
+    (prn ::logseq-cli-metadata-hook {:revision revision :build-time build-time})
+    (-> build-state
+        (assoc-in [:shadow.build/config :closure-defines]
+                  (assoc defines-in-config
+                         'logseq.cli.version/REVISION revision
+                         'logseq.cli.version/BUILD_TIME build-time))
+        (assoc-in [:compiler-options :closure-defines]
+                  (assoc defines-in-options
+                         'logseq.cli.version/REVISION revision
+                         'logseq.cli.version/BUILD_TIME build-time)))))
+
+(defn db-worker-node-metadata-hook
+  {:shadow.build/stage :configure}
+  [build-state & args]
+  (let [defines-in-config (get-in build-state [:shadow.build/config :closure-defines])
+        defines-in-options (get-in build-state [:compiler-options :closure-defines])
+        revision (env-or "LOGSEQ_REVISION" (or (exec "git" "describe" args) "dev"))
+        build-time (env-or "LOGSEQ_BUILD_TIME" (iso-now))]
+    (prn ::db-worker-node-metadata-hook {:revision revision :build-time build-time})
+    (-> build-state
+        (assoc-in [:shadow.build/config :closure-defines]
+                  (assoc defines-in-config
+                         'frontend.worker.version/REVISION revision
+                         'frontend.worker.version/BUILD_TIME build-time))
+        (assoc-in [:compiler-options :closure-defines]
+                  (assoc defines-in-options
+                         'frontend.worker.version/REVISION revision
+                         'frontend.worker.version/BUILD_TIME build-time)))))
diff --git a/src/dev-cljs/shadow/user.clj b/src/dev-cljs/shadow/user.clj
index 1ef90c0196..dacf77c56d 100644
--- a/src/dev-cljs/shadow/user.clj
+++ b/src/dev-cljs/shadow/user.clj
@@ -26,6 +26,15 @@
   ([runtime-id]
    (api/repl :db-worker {:runtime-id runtime-id})))
 
+(defn worker-node-repl
+  ([]
+   (let [runtime-id (->> (api/repl-runtimes :db-worker-node)
+                         (map :client-id)
+                         first)]
+     (api/repl :db-worker-node {:runtime-id runtime-id})))
+  ([runtime-id]
+   (api/repl :db-worker-node {:runtime-id runtime-id})))
+
 (defn runtime-id-list
   [app]
   (->> (api/repl-runtimes app)
diff --git a/src/electron/electron/backup_file.cljs b/src/electron/electron/backup_file.cljs
index f9b35946d3..b6624f7e1f 100644
--- a/src/electron/electron/backup_file.cljs
+++ b/src/electron/electron/backup_file.cljs
@@ -4,7 +4,7 @@
             ["path" :as node-path]
             [clojure.string :as string]))
 
-(def backup-dir "logseq/bak")
+(def backup-dir "backups")
 
 (defn- get-backup-dir*
   [repo relative-path bak-dir]
@@ -19,17 +19,6 @@
   [repo relative-path]
   (get-backup-dir* repo relative-path backup-dir))
 
-(defn- truncate-old-versioned-files!
-  "reserve the latest `keep-versions` version files"
-  [dir keep-versions]
-  (let [entries (fs/readdirSync dir (clj->js {:withFileTypes true}))
-        files   (->> entries
-                     (filter #(.-isFile %))
-                     (mapv #(.-name %)))
-        old-versioned-files (drop keep-versions (reverse (sort files)))]
-    (doseq [file old-versioned-files]
-      (fs-extra/removeSync (node-path/join dir file)))))
-
 (defn- parse-backup-ts
   "Backup filenames are like: 2025-12-25T01_23_45.678Z.ext
    We turn '_' back into ':' and parse as ISO."
@@ -140,9 +129,9 @@
 (defn backup-file
   "backup CONTENT under DIR :backup-dir
   :backup-dir = `backup-dir`"
-  [repo dir relative-path ext content & {:keys [truncate-daily?
-                                                keep-versions backups-dir]
-                                         :or {keep-versions 6}}]
+  [repo dir relative-path ext content & {:keys [keep-versions backups-dir force-backup?]
+                                         :or {keep-versions 6
+                                              force-backup? false}}]
   (let [dir* (or backups-dir
                  ;; TODO: Remove when last usage of backupDbFile event is removed from frontend.fs.node
                  (case dir
@@ -151,9 +140,7 @@
         new-path (node-path/join dir*
                                  (str (string/replace (.toISOString (js/Date.)) ":" "_")
                                       ext))]
-    (when-not (and truncate-daily? (too-soon? dir*))
+    (when (or force-backup? (not (too-soon? dir*)))
       (fs/writeFileSync new-path content)
       (fs/statSync new-path)
-      (if truncate-daily?
-        (truncate-daily-versioned-files! dir* keep-versions)
-        (truncate-old-versioned-files! dir* keep-versions)))))
+      (truncate-daily-versioned-files! dir* keep-versions))))
diff --git a/src/electron/electron/core.cljs b/src/electron/electron/core.cljs
index 26406a7386..3745401cbd 100644
--- a/src/electron/electron/core.cljs
+++ b/src/electron/electron/core.cljs
@@ -330,7 +330,8 @@
                                     :else
                                     nil)))))
            (.on app' "before-quit" (fn [_e]
-                                     (reset! win/*quitting? true)))
+                                     (reset! win/*quitting? true)
+                                     (handler/stop-all-db-workers!)))
 
            (.on app' "activate" #(when @*win (.show win)))))))
 
@@ -367,6 +368,7 @@
 
       (.on app "window-all-closed" (fn []
                                      (logger/debug "window-all-closed" "Quitting...")
+                                     (handler/stop-all-db-workers!)
                                      (.quit app)))
       (on-app-ready! app))))
 
diff --git a/src/electron/electron/db.cljs b/src/electron/electron/db.cljs
index 1208a14b05..29789f8485 100644
--- a/src/electron/electron/db.cljs
+++ b/src/electron/electron/db.cljs
@@ -3,9 +3,19 @@
   (:require ["fs-extra" :as fs]
             ["path" :as node-path]
             [electron.backup-file :as backup-file]
+            [lambdaisland.glogi :as log]
             [logseq.cli.common.graph :as cli-common-graph]
-            [logseq.common.config :as common-config]
-            [logseq.db.common.sqlite :as common-sqlite]))
+            [logseq.common.graph-dir :as graph-dir]
+            [logseq.db.common.sqlite :as common-sqlite]
+            [logseq.db.sqlite.backup :as sqlite-backup]
+            [promesa.core :as p]))
+
+(def ^:private backup-interval-ms
+  (* 60 60 1000))
+
+(defonce *auto-backup
+  (atom {:window->repo {}
+         :interval-id nil}))
 
 (defn ensure-graphs-dir!
   []
@@ -14,7 +24,8 @@
 (defn ensure-graph-dir!
   [db-name]
   (ensure-graphs-dir!)
-  (let [graph-dir (node-path/join (cli-common-graph/get-db-graphs-dir) (common-sqlite/sanitize-db-name db-name))]
+  (let [graph-dir (node-path/join (cli-common-graph/get-db-graphs-dir)
+                                  (graph-dir/repo->encoded-graph-dir-name db-name))]
     (fs/ensureDirSync graph-dir)
     graph-dir))
 
@@ -25,30 +36,87 @@
     (when (fs/existsSync db-path)
       (fs/readFileSync db-path))))
 
-(defn save-db!
-  [db-name data]
-  (let [[db-name db-path] (common-sqlite/get-db-full-path (cli-common-graph/get-db-graphs-dir) db-name)
-        old-data (get-db db-name)
-        backups-path (common-sqlite/get-db-backups-path (cli-common-graph/get-db-graphs-dir) db-name)]
-    (when old-data
-      (backup-file/backup-file db-name nil nil
-                               ".sqlite"
-                               old-data
-                               {:backups-dir backups-path
-                                :truncate-daily? true
-                                :keep-versions 12}))
-    (fs/writeFileSync db-path data)))
+(defn- temp-backup-path
+  [backups-path]
+  (node-path/join backups-path
+                  (str ".tmp."
+                       (.now js/Date)
+                       "."
+                       (rand-int 1000000)
+                       ".sqlite")))
 
-(defn unlink-graph!
-  [repo]
-  (let [db-name (common-sqlite/sanitize-db-name repo)
-        path (node-path/join (cli-common-graph/get-db-graphs-dir) db-name)
-        unlinked (node-path/join (cli-common-graph/get-db-graphs-dir) common-config/unlinked-graphs-dir)
-        new-path (node-path/join unlinked db-name)
-        new-path-exists? (fs/existsSync new-path)
-        new-path' (if new-path-exists?
-                    (node-path/join unlinked (str db-name "-" (random-uuid)))
-                    new-path)]
-    (when (fs/existsSync path)
-      (fs/ensureDirSync unlinked)
-      (fs/moveSync path new-path'))))
+(defn backup-db!
+  [db-name {:keys [force-backup?]}]
+  (let [_ (ensure-graph-dir! db-name)
+        [_db-name db-path] (common-sqlite/get-db-full-path (cli-common-graph/get-db-graphs-dir) db-name)
+        backups-path (common-sqlite/get-db-backups-path (cli-common-graph/get-db-graphs-dir) db-name)]
+    (when (fs/existsSync db-path)
+      (let [tmp-path (temp-backup-path backups-path)]
+        (-> (p/let [_ (fs/ensureDirSync backups-path)
+                    _ (sqlite-backup/backup-db-file! db-path tmp-path)
+                    payload (fs/readFileSync tmp-path)]
+              (backup-file/backup-file db-name nil nil
+                                       ".sqlite"
+                                       payload
+                                       :backups-dir backups-path
+                                       :keep-versions 12
+                                       :force-backup? force-backup?))
+            (p/finally (fn []
+                         (try
+                           (fs/removeSync tmp-path)
+                           (catch :default _
+                             nil)))))))))
+
+(defn- active-repos
+  []
+  (->> (:window->repo @*auto-backup)
+       vals
+       (remove nil?)
+       set
+       vec))
+
+(defn run-auto-backup!
+  []
+  (p/all
+   (for [repo (active-repos)]
+     (-> (backup-db! repo {})
+         (p/catch (fn [error]
+                    (log/warn :electron/auto-db-backup-failed
+                              {:repo repo
+                               :error error})
+                    nil))))))
+
+(defn- reconcile-auto-backup-timer!
+  []
+  (let [{:keys [interval-id]} @*auto-backup
+        has-repos? (seq (active-repos))]
+    (cond
+      (and has-repos? (nil? interval-id))
+      (let [id (js/setInterval (fn [] (run-auto-backup!))
+                               backup-interval-ms)]
+        (swap! *auto-backup assoc :interval-id id))
+
+      (and (not has-repos?) interval-id)
+      (do
+        (js/clearInterval interval-id)
+        (swap! *auto-backup assoc :interval-id nil))
+
+      :else
+      nil)))
+
+(defn sync-auto-backup-repo!
+  [window-id repo]
+  (swap! *auto-backup
+         (fn [state]
+           (if (seq repo)
+             (assoc-in state [:window->repo window-id] repo)
+             (update state :window->repo dissoc window-id))))
+  (reconcile-auto-backup-timer!)
+  nil)
+
+(defn reset-auto-backup!
+  []
+  (when-let [interval-id (:interval-id @*auto-backup)]
+    (js/clearInterval interval-id))
+  (reset! *auto-backup {:window->repo {}
+                        :interval-id nil}))
diff --git a/src/electron/electron/db_worker.cljs b/src/electron/electron/db_worker.cljs
new file mode 100644
index 0000000000..2d8c0852d6
--- /dev/null
+++ b/src/electron/electron/db_worker.cljs
@@ -0,0 +1,234 @@
+(ns electron.db-worker
+  (:require [logseq.cli.server :as cli-server]
+            [logseq.db-worker.daemon :as daemon]
+            [promesa.core :as p]))
+
+(defn- initial-state
+  []
+  {:repos {}
+   :window->repo {}})
+
+(defn- ensure-state
+  [state]
+  (merge (initial-state) state))
+
+(defn- dissoc-window
+  [state window-id]
+  (update state :window->repo dissoc window-id))
+
+(defn- detach-window
+  [state window-id]
+  (let [state (ensure-state state)
+        repo (get-in state [:window->repo window-id])]
+    (if-not repo
+      [state nil]
+      (let [entry (get-in state [:repos repo])]
+        (if-not entry
+          [(dissoc-window state window-id) nil]
+          (let [remaining (disj (:windows entry) window-id)
+                state' (cond-> (dissoc-window state window-id)
+                         (seq remaining)
+                         (assoc-in [:repos repo :windows] remaining)
+
+                         (empty? remaining)
+                         (update :repos dissoc repo))]
+            [state' (when (empty? remaining) (:runtime entry))]))))))
+
+(defn- detach-window-from-repo
+  [state repo window-id]
+  (let [state (ensure-state state)
+        entry (get-in state [:repos repo])]
+    (if-not entry
+      [state nil]
+      (let [remaining (disj (:windows entry) window-id)
+            state' (cond-> state
+                     (= repo (get-in state [:window->repo window-id]))
+                     (update :window->repo dissoc window-id)
+
+                     (seq remaining)
+                     (assoc-in [:repos repo :windows] remaining)
+
+                     (empty? remaining)
+                     (update :repos dissoc repo))]
+        [state' (when (empty? remaining) (:runtime entry))]))))
+
+(defn- detach-repo
+  [state repo]
+  (let [state (ensure-state state)
+        entry (get-in state [:repos repo])]
+    (if-not entry
+      [state nil]
+      (let [windows (or (:windows entry) #{})
+            state' (-> state
+                       (update :repos dissoc repo)
+                       (update :window->repo
+                               (fn [window->repo]
+                                 (reduce (fn [m window-id]
+                                           (if (= repo (get m window-id))
+                                             (dissoc m window-id)
+                                             m))
+                                         window->repo
+                                         windows))))]
+        [state' (:runtime entry)]))))
+
+(defn create-manager
+  [{:keys [start-daemon! stop-daemon! runtime-ready?] :as deps}]
+  {:deps deps
+   :start-daemon! start-daemon!
+   :stop-daemon! stop-daemon!
+   :runtime-ready? (or runtime-ready? (fn [_runtime] (p/resolved true)))
+   :state (atom (initial-state))})
+
+(defn- owned-runtime?
+  [runtime]
+  (not= false (:owned? runtime)))
+
+(defn ensure-window-stopped!
+  [{:keys [state stop-daemon!]} window-id]
+  (let [runtime* (atom nil)]
+    (swap! state
+           (fn [current]
+             (let [[next-state runtime] (detach-window current window-id)]
+               (reset! runtime* runtime)
+               next-state)))
+    (if-let [runtime @runtime*]
+      (if (owned-runtime? runtime)
+        (p/let [_ (stop-daemon! runtime)]
+          true)
+        (p/resolved true))
+      (p/resolved false))))
+
+(defn ensure-started!
+  [{:keys [state start-daemon! stop-daemon! runtime-ready?] :as manager} repo window-id]
+  (p/let [current-repo (get-in (ensure-state @state) [:window->repo window-id])
+          _ (when (and current-repo (not= current-repo repo))
+              (ensure-window-stopped! manager window-id))]
+    (if-let [entry (get-in (ensure-state @state) [:repos repo])]
+      (p/let [runtime (:runtime entry)
+              ready? (runtime-ready? runtime)]
+        (if ready?
+          (do
+            (swap! state (fn [current]
+                           (-> (ensure-state current)
+                               (update-in [:repos repo :windows] (fnil conj #{}) window-id)
+                               (assoc-in [:window->repo window-id] repo))))
+            runtime)
+          (p/let [_ (when (owned-runtime? runtime)
+                      (-> (stop-daemon! runtime)
+                          (p/catch (fn [_] nil))))
+                  runtime' (start-daemon! repo)]
+            (swap! state
+                   (fn [current]
+                     (let [current' (ensure-state current)
+                           windows (get-in current' [:repos repo :windows] #{})]
+                       (-> current'
+                           (assoc-in [:repos repo] {:runtime runtime'
+                                                    :windows (conj windows window-id)})
+                           (assoc-in [:window->repo window-id] repo)))))
+            runtime')))
+      (p/let [runtime (start-daemon! repo)]
+        (swap! state (fn [current]
+                       (-> (ensure-state current)
+                           (assoc-in [:repos repo] {:runtime runtime
+                                                    :windows #{window-id}})
+                           (assoc-in [:window->repo window-id] repo))))
+        runtime))))
+
+(defn- parse-runtime-lock
+  [{:keys [base-url]}]
+  (when (seq base-url)
+    (try
+      (let [^js parsed-url (js/URL. base-url)
+            host (.-hostname parsed-url)
+            port-str (.-port parsed-url)
+            port (js/parseInt port-str 10)]
+        (when (and (seq host) (number? port) (pos-int? port))
+          {:host host
+           :port port}))
+      (catch :default _
+        nil))))
+
+(defn- runtime-ready-default?
+  [runtime]
+  (if-let [lock (parse-runtime-lock runtime)]
+    (daemon/ready? lock)
+    (p/resolved false)))
+
+(defn ensure-stopped!
+  [{:keys [state stop-daemon!]} repo window-id]
+  (if (= repo (get-in (ensure-state @state) [:window->repo window-id]))
+    (ensure-window-stopped! {:state state :stop-daemon! stop-daemon!} window-id)
+    (let [runtime* (atom nil)]
+      (swap! state
+             (fn [current]
+               (let [[next-state runtime] (detach-window-from-repo current repo window-id)]
+                 (reset! runtime* runtime)
+                 next-state)))
+      (if-let [runtime @runtime*]
+        (if (owned-runtime? runtime)
+          (p/let [_ (stop-daemon! runtime)]
+            true)
+          (p/resolved true))
+        (p/resolved false)))))
+
+(defn stop-all!
+  [{:keys [state stop-daemon!]}]
+  (let [entries (vals (:repos (ensure-state @state)))]
+    (-> (p/all (map (fn [{:keys [runtime]}]
+                      (if (owned-runtime? runtime)
+                        (stop-daemon! runtime)
+                        (p/resolved true)))
+                    entries))
+        (p/then (fn [_]
+                  (reset! state (initial-state))
+                  true)))))
+
+(defn ensure-repo-stopped!
+  [{:keys [state stop-daemon!]} repo]
+  (let [runtime* (atom nil)]
+    (swap! state
+           (fn [current]
+             (let [[next-state runtime] (detach-repo current repo)]
+               (reset! runtime* runtime)
+               next-state)))
+    (if-let [runtime @runtime*]
+      (if (owned-runtime? runtime)
+        (p/let [_ (stop-daemon! runtime)]
+          true)
+        (p/resolved true))
+      (p/resolved false))))
+
+(defn- start-managed-daemon!
+  [repo]
+  (p/let [config (cli-server/ensure-server! {:owner-source :electron} repo)]
+    {:repo repo
+     :base-url (:base-url config)
+     :auth-token nil
+     :owned? (:owned? config)}))
+
+(defn- stop-managed-daemon!
+  [{:keys [repo]}]
+  (p/let [result (cli-server/stop-server! {:owner-source :electron} repo)]
+    (:ok? result)))
+
+(defonce manager
+  (create-manager
+   {:start-daemon! start-managed-daemon!
+    :stop-daemon! stop-managed-daemon!
+    :runtime-ready? runtime-ready-default?}))
+
+(defn ensure-runtime!
+  [repo window-id]
+  (ensure-started! manager repo window-id))
+
+(defn release-window!
+  [window-id]
+  (ensure-window-stopped! manager window-id))
+
+(defn release-repo!
+  [repo]
+  (ensure-repo-stopped! manager repo))
+
+(defn stop-all-managed!
+  []
+  (stop-all! manager))
diff --git a/src/electron/electron/graph_switch_flow.cljs b/src/electron/electron/graph_switch_flow.cljs
new file mode 100644
index 0000000000..a91b405302
--- /dev/null
+++ b/src/electron/electron/graph_switch_flow.cljs
@@ -0,0 +1,13 @@
+(ns electron.graph-switch-flow)
+
+(defn release-runtime-on-set-current-graph?
+  "Decides whether `setCurrentGraph` should release db-worker runtime.
+
+  Returns `false` by design.
+
+  In Electron, `setCurrentGraph` is metadata synchronization for window graph
+  path only. Runtime lifecycle is handled by the `db-worker-runtime` IPC path
+  (switch/start) and window close path (release). Releasing here reintroduces
+  the stale double-release bug that can stop the newly bound runtime."
+  [_switch]
+  false)
diff --git a/src/electron/electron/handler.cljs b/src/electron/electron/handler.cljs
index 7eb3a653c3..719e4d7129 100644
--- a/src/electron/electron/handler.cljs
+++ b/src/electron/electron/handler.cljs
@@ -4,7 +4,6 @@
   (:require ["/electron/utils" :as js-utils]
             ["abort-controller" :as AbortController]
             ["buffer" :as buffer]
-            ["diff-match-patch" :as google-diff]
             ["electron" :refer [app dialog ipcMain shell]]
             ["electron-updater" :refer [autoUpdater]]
             ["electron-window-state" :as windowStateKeeper]
@@ -17,6 +16,7 @@
             [electron.backup-file :as backup-file]
             [electron.configs :as cfgs]
             [electron.db :as db]
+            [electron.db-worker :as db-worker]
             [electron.find-in-page :as find]
             [electron.handler-interface :refer [handle]]
             [electron.i18n :as i18n]
@@ -29,7 +29,10 @@
             [electron.state :as state]
             [electron.utils :as utils]
             [electron.window :as win]
+            [electron.graph-switch-flow :as graph-switch-flow]
             [logseq.cli.common.graph :as cli-common-graph]
+            [logseq.cli.common :as cli-common]
+            [logseq.common.config :as common-config]
             [logseq.common.graph :as common-graph]
             [logseq.db.sqlite.util :as sqlite-util]
             [promesa.core :as p]))
@@ -65,19 +68,6 @@
         (logger/error ::unlink path e)
         nil))))
 
-(defonce Diff (google-diff.))
-(defn string-some-deleted?
-  [old new]
-  (let [result (.diff_main Diff old new)]
-    (some (fn [a] (= -1 (first a))) result)))
-
-(defmethod handle :backupDbFile [_window [_ repo path db-content new-content]]
-  (when (and (string? db-content)
-             (string? new-content)
-             (string-some-deleted? db-content new-content))
-    (logger/info ::backup "backup db file" path)
-    (backup-file/backup-file repo :backup-dir path (node-path/extname path) db-content)))
-
 (defmethod handle :openFileInFolder [_window [_ full-path]]
   (when-let [full-path (utils/to-native-win-path! full-path)]
     (logger/info ::open-file-in-folder full-path)
@@ -119,20 +109,22 @@
       (utils/fs-stat->clj path)
       (catch :default e
         (logger/warn ::write-file path e)
-        (let [backup-path (try
+        (let [error-message (str e)
+              backup-path (try
                             (backup-file/backup-file repo :backup-dir path (node-path/extname path) content)
-                            (catch :default e
-                              (logger/error ::write-file "backup file failed:" e)))]
+                            (catch :default backup-error
+                              (logger/error ::write-file "backup file failed:" backup-error)))]
           (utils/send-to-renderer window "notification"
-                                 (if backup-path
-                                   {:type "error"
-                                    :payload (str "Write to the file " path " failed, " e ". A backup file was saved to " backup-path ".")
-                                    :i18n-key :electron/write-file-error-with-backup
-                                    :i18n-args [path e backup-path]}
-                                   {:type "error"
-                                    :payload (str "Write to the file " path " failed, " e)
-                                    :i18n-key :electron/write-file-error
-                                    :i18n-args [path e]})))))))
+                                  (if backup-path
+                                    {:type "error"
+                                     :payload (str "Write to the file " path " failed, " error-message ". A backup file was saved to " backup-path ".")
+                                     :i18n-key :electron/write-file-error-with-backup
+                                     :i18n-args [path error-message backup-path]}
+                                    {:type "error"
+                                     :payload (str "Write to the file " path " failed, " error-message)
+                                     :i18n-key :electron/write-file-error
+                                     :i18n-args [path error-message]})))))))
+
 (defmethod handle :rename [_window [_ old-path new-path]]
   (logger/info ::rename "from" old-path "to" new-path)
   (fs/renameSync old-path new-path))
@@ -184,12 +176,12 @@
                                 :files (get-files path)}))
         (catch js/Error e
           (do
-            (utils/send-to-renderer window "notification"
-                                   {:type "error"
-                                    :payload (str "Opening the specified directory failed.\n"
-                                                  (or (pretty-print-js-error e) (str "Unexpected error: " e)))
-                                    :i18n-key :electron/open-dir-error
-                                    :i18n-args [(or (pretty-print-js-error e) (str "Unexpected error: " e))]})
+            (let [error-message (or (pretty-print-js-error e) (str "Unexpected error: " e))]
+              (utils/send-to-renderer window "notification"
+                                      {:type "error"
+                                       :payload (str "Opening the specified directory failed.\n" error-message)
+                                       :i18n-key :electron/open-dir-error
+                                       :i18n-args [error-message]}))
             (p/rejected e))))
 
       (p/rejected (js/Error "path empty")))))
@@ -205,33 +197,54 @@
   []
   (distinct (cli-common-graph/get-db-based-graphs)))
 
+(defn- canonical-repo
+  [graph]
+  (common-config/canonicalize-db-version-repo graph))
+
 ;; TODO support alias mechanism
 (defn get-graph-name
   "Given a graph's name of string, returns the graph's fullname. For example, given
   `cat`, returns `logseq_db_cat`.  Returns `nil` if no such graph exists."
   [graph-identifier]
-  (->> (get-graphs)
-       (some #(when (or
-                     (= (utils/normalize-lc %) (utils/normalize-lc (str sqlite-util/db-version-prefix graph-identifier)))
-                     (string/ends-with? (utils/normalize-lc %)
-                                        (str "/" (utils/normalize-lc graph-identifier))))
-                %))))
+  (when-let [repo (canonical-repo graph-identifier)]
+    (let [graph-name (common-config/strip-leading-db-version-prefix repo)]
+      (->> (get-graphs)
+           (some #(when (or
+                         (= (utils/normalize-lc %) (utils/normalize-lc repo))
+                         (string/ends-with? (utils/normalize-lc %)
+                                            (str "/" (utils/normalize-lc graph-name))))
+                    %))))))
 
 (defmethod handle :getGraphs [_window [_]]
   (get-graphs))
 
 (defmethod handle :deleteGraph [_window [_ graph]]
-  (when graph
-    (db/unlink-graph! graph)))
+  (when-let [repo (canonical-repo graph)]
+    (p/let [_ (db-worker/release-repo! repo)]
+      (cli-common/unlink-graph! repo))))
 
 ;; DB related IPCs start
 
-(defmethod handle :db-export [_window [_ repo data]]
-  (db/ensure-graph-dir! repo)
-  (db/save-db! repo data))
+(defn stop-all-db-workers!
+  []
+  (db-worker/stop-all-managed!))
+
+(defmethod handle :db-worker-runtime [^js window [_ repo]]
+  (if (string/blank? repo)
+    (p/rejected (ex-info "repo is required" {:code :missing-repo}))
+    (db-worker/ensure-runtime! (canonical-repo repo) (.-id window))))
+
+(defmethod handle :db-export [_window [_ repo force-backup?]]
+  (when-let [repo (canonical-repo repo)]
+    (db/ensure-graph-dir! repo)
+    (db/backup-db! repo {:force-backup? force-backup?})))
 
 (defmethod handle :db-get [_window [_ repo]]
-  (db/get-db repo))
+  (when-let [repo (canonical-repo repo)]
+    (logger/warn ::db-get-compat
+                 {:repo repo
+                  :message "legacy db-get IPC path invoked; desktop should use db-worker runtime"})
+    (db/get-db repo)))
 
 ;; DB related IPCs End
 
@@ -318,8 +331,18 @@
   nil)
 
 (defmethod handle :setCurrentGraph [^js window [_ graph-name]]
-  (when graph-name
-    (set-current-graph! window (utils/get-graph-dir graph-name))))
+  (let [next-graph-path (when graph-name (utils/get-graph-dir graph-name))
+        current-graph-path (state/get-window-graph-path window)
+        release-runtime? (graph-switch-flow/release-runtime-on-set-current-graph?
+                          {:previous-graph-path current-graph-path
+                           :next-graph-path next-graph-path})]
+    (p/let [_ (when release-runtime?
+                (db-worker/release-window! (.-id window)))]
+      (db/sync-auto-backup-repo! (.-id window) graph-name)
+      (if next-graph-path
+        (set-current-graph! window next-graph-path)
+        (state/close-window! window))
+      nil)))
 
 (defmethod handle :updateElectronLocale [_window [_ locale]]
   (i18n/update-locale! locale))
@@ -477,21 +500,35 @@
 (defmethod handle :window/open-blank-callback [^js win [_ _type]]
   (win/setup-window-listeners! win) nil)
 
+(defn- decode-main-ipc-message
+  [args-js]
+  (if (string? args-js)
+    (sqlite-util/read-transit-str args-js)
+    (bean/->clj args-js)))
+
+(defn- command-name
+  [message]
+  (let [command (first message)]
+    (cond
+      (keyword? command) (name command)
+      (string? command) command
+      :else nil)))
+
 (defn set-ipc-handler! [window]
   (let [main-channel "main"]
     (.handle ipcMain main-channel
              (fn [^js event args-js]
-               (try
-                 (let [message (bean/->clj args-js)]
-                   ;; Be careful with the return values of `handle` defmethods.
-                   ;; Values that are not non-JS objects will cause this
-                   ;; exception -
-                   ;; https://www.electronjs.org/docs/latest/breaking-changes#behavior-changed-sending-non-js-objects-over-ipc-now-throws-an-exception
-                   (bean/->js (handle (or (utils/get-win-from-sender event) window) message)))
-                 (catch :default e
-                   (when-not (contains? #{"mkdir" "stat"} (nth args-js 0))
-                     (logger/error "IPC error: " {:event event
-                                                  :args args-js}
-                                   e))
-                   e))))
+               (let [message* (volatile! nil)]
+                 (->
+                  (p/let [message (decode-main-ipc-message args-js)
+                          _ (vreset! message* message)
+                          result (handle (or (utils/get-win-from-sender event) window) message)]
+                    (sqlite-util/write-transit-str result))
+                  (p/catch (fn [e]
+                             (let [command (command-name @message*)]
+                               (when-not (contains? #{"mkdir" "stat"} command)
+                                 (logger/error "IPC error: " {:event event
+                                                              :args args-js}
+                                               e)
+                                 (throw e)))))))))
     #(.removeHandler ipcMain main-channel)))
diff --git a/src/electron/electron/logger.cljs b/src/electron/electron/logger.cljs
index e94fe76610..35806df4cb 100644
--- a/src/electron/electron/logger.cljs
+++ b/src/electron/electron/logger.cljs
@@ -1,7 +1,7 @@
 (ns electron.logger
   "Electron logger, do not depends other libs"
-  (:require ["electron-log" :as logger]))
-
+  (:require ["electron-log" :as logger]
+            [lambdaisland.glogi :as log]))
 
 (defn- transform-args [args]
   (map #(cond
@@ -12,7 +12,6 @@
           %)
        args))
 
-
 (defn debug
   [& args]
   (apply (.-debug logger) (transform-args args)))
@@ -29,3 +28,13 @@
   [& args]
   (apply (.-error logger) (transform-args args)))
 
+(log/add-handler (fn [{:keys [level message exception]}]
+                   (let [f (case level
+                             :warn
+                             warn
+                             :error
+                             error
+                             :debug
+                             debug
+                             info)]
+                     (f message exception))))
diff --git a/src/electron/electron/utils.cljs b/src/electron/electron/utils.cljs
index 400a276591..228a25d901 100644
--- a/src/electron/electron/utils.cljs
+++ b/src/electron/electron/utils.cljs
@@ -9,7 +9,8 @@
             [electron.configs :as cfgs]
             [electron.logger :as logger]
             [logseq.cli.common.graph :as cli-common-graph]
-            [logseq.db.sqlite.util :as sqlite-util]
+            [logseq.common.graph-dir :as graph-dir]
+            [logseq.common.config :as common-config]
             [promesa.core :as p]
             [shadow.esm :refer [dynamic-import]]))
 
@@ -253,14 +254,17 @@
 (defn get-graph-dir
   "required by all internal state in the electron section"
   [graph-name]
-  (when (string/starts-with? graph-name sqlite-util/db-version-prefix)
-    (node-path/join (cli-common-graph/get-db-graphs-dir) (string/replace-first graph-name sqlite-util/db-version-prefix ""))))
+  (when (and (string? graph-name)
+             (string/starts-with? graph-name common-config/db-version-prefix))
+    (let [repo (common-config/canonicalize-db-version-repo graph-name)]
+      (node-path/join (cli-common-graph/get-db-graphs-dir)
+                      (graph-dir/repo->encoded-graph-dir-name repo)))))
 
 (comment
   (defn get-graph-name
     "Reverse `get-graph-dir`"
     [graph-dir]
-    (str sqlite-util/db-version-prefix (node-path/basename graph-dir))))
+    (str common-config/db-version-prefix (node-path/basename graph-dir))))
 
 (defn decode-protected-assets-schema-path
   [schema-path]
diff --git a/src/electron/electron/window.cljs b/src/electron/electron/window.cljs
index 1274adf9ad..5071254fdf 100644
--- a/src/electron/electron/window.cljs
+++ b/src/electron/electron/window.cljs
@@ -7,6 +7,7 @@
             [clojure.string :as string]
             [electron.configs :as cfgs]
             [electron.context-menu :as context-menu]
+            [electron.db-worker :as db-worker]
             [electron.i18n :refer [t]]
             [electron.logger :as logger]
             [electron.spell-check :as spell-check]
@@ -87,6 +88,7 @@
 (defn close-handler
   [^js win e]
   (.preventDefault e)
+  (db-worker/release-window! (.-id win))
   (state/close-window! win)
   (let [web-contents (. win -webContents)]
     (.send web-contents "persist-zoom-level" (.getZoomLevel web-contents)))
diff --git a/src/main/electron/ipc.cljs b/src/main/electron/ipc.cljs
index 75f8123eca..537164222e 100644
--- a/src/main/electron/ipc.cljs
+++ b/src/main/electron/ipc.cljs
@@ -2,15 +2,21 @@
   "Provides fns to send ipc messages to electron's main process"
   (:require [cljs-bean.core :as bean]
             [promesa.core :as p]
-            [frontend.util :as util]))
+            [frontend.util :as util]
+            [logseq.db.sqlite.util :as sqlite-util]))
+
+(defn- maybe-read-transit
+  [result]
+  (if (string? result)
+    (sqlite-util/read-transit-str result)
+    result))
 
-;; TODO: handle errors
-;;; TODO: transit-write args, transit-read response
 (defn ipc
   [& args]
   (when (util/electron?)
-    (p/let [result (js/window.apis.doAction (bean/->js args))]
-      result)))
+    (p/let [payload (sqlite-util/write-transit-str (vec args))
+            maybe-result-str (js/window.apis.doAction payload)]
+      (maybe-read-transit maybe-result-str))))
 
 (defn invoke
   [channel & args]
diff --git a/src/main/frontend/background_tasks.cljs b/src/main/frontend/background_tasks.cljs
index cf7c994bbc..f75c15af7f 100644
--- a/src/main/frontend/background_tasks.cljs
+++ b/src/main/frontend/background_tasks.cljs
@@ -6,6 +6,18 @@
             [logseq.db.common.entity-plus :as entity-plus]
             [missionary.core :as m]))
 
+(def ^:private search-input-idle-sync-interval-ms 500)
+(def ^:private search-input-idle-diff-ms 1000)
+
+(defn- search-input-idle-tick-flow
+  []
+  (m/observe
+   (fn [emit!]
+     (let [interval-id (js/setInterval #(emit! (js/Date.now)) search-input-idle-sync-interval-ms)]
+       (emit! (js/Date.now))
+       (fn []
+         (js/clearInterval interval-id))))))
+
 (c.m/run-background-task
  :logseq.db.common.entity-plus/reset-immutable-entities-cache!
  (m/reduce
@@ -22,3 +34,34 @@
     (when db-worker-ready?
       (state/<invoke-db-worker :thread-api/update-thread-atom :thread-atom/online-event online?)))
   (m/latest vector flows/network-online-event-flow state/db-worker-ready-flow)))
+
+(c.m/run-background-task
+ ::sync-to-worker-search-input-idle-status
+ (m/reduce
+  (fn [{:keys [last-synced-repo last-synced-idle? prev-db-worker-ready?] :as sync-state}
+       [_tick db-worker-ready? repo]]
+    (if (and db-worker-ready? (seq repo))
+      (let [idle? (state/input-idle? repo :diff search-input-idle-diff-ms)
+            should-sync?
+            (or (nil? last-synced-repo)
+                (not= last-synced-repo repo)
+                (and db-worker-ready? (not prev-db-worker-ready?))
+                (not= last-synced-idle? idle?))]
+        (when should-sync?
+          (state/<invoke-db-worker
+           :thread-api/update-thread-atom
+           :thread-atom/search-input-idle-status
+           {repo {:idle? idle?
+                  :ts (js/Date.now)}}))
+        (assoc sync-state
+               :last-synced-repo repo
+               :last-synced-idle? idle?
+               :prev-db-worker-ready? db-worker-ready?))
+      (assoc sync-state
+             :last-synced-repo nil
+             :last-synced-idle? nil
+             :prev-db-worker-ready? db-worker-ready?)))
+  (m/latest vector
+            (search-input-idle-tick-flow)
+            state/db-worker-ready-flow
+            flows/current-repo-flow)))
diff --git a/src/main/frontend/common/crypt.cljs b/src/main/frontend/common/crypt.cljs
index 1e52235d77..c73da2be2a 100644
--- a/src/main/frontend/common/crypt.cljs
+++ b/src/main/frontend/common/crypt.cljs
@@ -47,14 +47,6 @@
   (p/let [exported (.exportKey subtle "pkcs8" private-key)]
     (js/Uint8Array. exported)))
 
-(defn <import-private-key
-  [exported-private-key]
-  (assert (instance? js/Uint8Array exported-private-key))
-  (.importKey subtle "pkcs8" exported-private-key
-              #js {:name "RSA-OAEP" :hash "SHA-256"}
-              true
-              #js ["decrypt"]))
-
 (comment
   (->
    (p/let [kp (<generate-rsa-key-pair)
@@ -181,19 +173,15 @@
   "Decrypts an AES key with a private key."
   [private-key encrypted-aes-key-data]
   (assert (and (instance? js/CryptoKey private-key)
-               (instance? js/Uint8Array encrypted-aes-key-data)))
+               (instance? js/Uint8Array encrypted-aes-key-data))
+          [private-key encrypted-aes-key-data])
   (->
    (p/let [encrypted-aes-key (js/Uint8Array. encrypted-aes-key-data)
            decrypted-key-data (.decrypt subtle
                                         #js {:name "RSA-OAEP"}
                                         private-key
                                         encrypted-aes-key)]
-     (.importKey subtle
-                 "raw"
-                 decrypted-key-data
-                 "AES-GCM"
-                 true
-                 #js ["encrypt" "decrypt"]))
+     (<import-aes-key (js/Uint8Array. decrypted-key-data)))
    (p/catch (fn [e]
               (when-not (expected-crypto-operation-error? e)
                 (log/error "decrypt-aes-key failed" e))
diff --git a/src/main/frontend/common/file/opfs.cljs b/src/main/frontend/common/file/opfs.cljs
index d66b420493..fc41c2014b 100644
--- a/src/main/frontend/common/file/opfs.cljs
+++ b/src/main/frontend/common/file/opfs.cljs
@@ -26,13 +26,3 @@
           file        (.getFile file-handle)]
     (.text file)))
 
-(defn <delete-file!
-  "Delete `filename` from Origin Private File System.
-   Returns nil when file is missing."
-  [filename]
-  (-> (p/let [root (.. js/navigator -storage (getDirectory))]
-        (.removeEntry root filename))
-      (p/catch (fn [err]
-                 (if (= (.-name err) "NotFoundError")
-                   nil
-                   (throw err))))))
diff --git a/src/main/frontend/common/idbkv.js b/src/main/frontend/common/idbkv.js
deleted file mode 100644
index 3a60265c6d..0000000000
--- a/src/main/frontend/common/idbkv.js
+++ /dev/null
@@ -1,148 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, '__esModule', { value: true });
-
-class Store {
-    constructor(dbName = 'keyval-store', storeName = 'keyval', version = 1) {
-        this.storeName = storeName;
-        this._dbName = dbName;
-        this._storeName = storeName;
-        this._version = version;
-        this.id = `dbName:${dbName};;storeName:${storeName}`;
-        this._init();
-    }
-    _init() {
-      if (this._dbp) {
-        return;
-      }
-      this._dbp = new Promise((resolve, reject) => {
-        let idb = typeof window == 'object' ? window.indexedDB : indexedDB;
-        const openreq = idb.open(this._dbName, this._version);
-        openreq.onerror = () => reject(openreq.error);
-        openreq.onsuccess = () => resolve(openreq.result);
-        // First time setup: create an empty object store
-        openreq.onupgradeneeded = () => {
-          openreq.result.createObjectStore(this._storeName);
-        };
-      });
-    }
-    _withIDBStore(type, callback) {
-        this._init();
-        return this._dbp.then(db => new Promise((resolve, reject) => {
-            const transaction = db.transaction(this.storeName, type);
-            transaction.oncomplete = () => resolve();
-            transaction.onabort = transaction.onerror = () => reject(transaction.error);
-            callback(transaction.objectStore(this.storeName));
-        }));
-    }
-    _close() {
-        this._init();
-        return this._dbp.then(db => {
-            db.close();
-            this._dbp = undefined;
-        });
-    }
-}
-class Batcher {
-    constructor(executor) {
-        this.executor = executor;
-        this.items = [];
-    }
-  async process() {
-        const toProcess = this.items;
-        this.items = [];
-        await this.executor(toProcess.map(({ item }) => item));
-        toProcess.map(({ onProcessed }) => onProcessed());
-        if (this.items.length) {
-            this.ongoing = this.process();
-        }
-        else {
-            this.ongoing = undefined;
-        }
-    }
-    async queue(item) {
-        const result = new Promise((resolve) => this.items.push({ item, onProcessed: resolve }));
-        if (!this.ongoing)
-            this.ongoing = this.process();
-        return result;
-    }
-}
-let store;
-function getDefaultStore() {
-    if (!store)
-        store = new Store();
-    return store;
-}
-function get(key, store = getDefaultStore()) {
-    let req;
-    return store._withIDBStore('readwrite', store => {
-        req = store.get(key);
-    }).then(() => req.result);
-}
-const setBatchers = {};
-function set(key, value, store = getDefaultStore()) {
-    if (!setBatchers[store.id]) {
-        setBatchers[store.id] = new Batcher((items) => store._withIDBStore('readwrite', store => {
-            for (const item of items) {
-                store.put(item.value, item.key);
-            }
-        }));
-    }
-    return setBatchers[store.id].queue({ key, value });
-}
-function setBatch(items, store = getDefaultStore()) {
-  return store._withIDBStore('readwrite', store => {
-    for (const item of items) {
-            store.put(item.value, item.key);
-    }
-  });
-}
-function update(key, updater, store = getDefaultStore()) {
-    return store._withIDBStore('readwrite', store => {
-        const req = store.get(key);
-        req.onsuccess = () => {
-            store.put(updater(req.result), key);
-        };
-    });
-}
-function del(key, store = getDefaultStore()) {
-    return store._withIDBStore('readwrite', store => {
-        store.delete(key);
-    });
-}
-function clear(store = getDefaultStore()) {
-    return store._withIDBStore('readwrite', store => {
-        store.clear();
-    });
-}
-function keys(store = getDefaultStore()) {
-    const keys = [];
-    return store._withIDBStore('readwrite', store => {
-        // This would be store.getAllKeys(), but it isn't supported by Edge or Safari.
-        // And openKeyCursor isn't supported by Safari.
-        (store.openKeyCursor || store.openCursor).call(store).onsuccess = function () {
-            if (!this.result)
-                return;
-            keys.push(this.result.key);
-            this.result.continue();
-        };
-    }).then(() => keys);
-}
-function close(store = getDefaultStore()) {
-    return store._close();
-}
-
-function newStore(dbName = 'keyval-store', storeName = 'keyval', version = 1) {
-    return new Store(dbName, storeName, version);
-}
-
-exports.newStore = newStore;
-// exports.Store = Store; // use newStore instead
-exports.get = get;
-exports.set = set;
-exports.setBatch = setBatch;
-exports.update = update;
-exports.del = del;
-exports.clear = clear;
-exports.keys = keys;
-exports.close = close;
diff --git a/src/main/frontend/components/e2ee.cljs b/src/main/frontend/components/e2ee.cljs
index f5597aae98..7d26d6a872 100644
--- a/src/main/frontend/components/e2ee.cljs
+++ b/src/main/frontend/components/e2ee.cljs
@@ -57,14 +57,39 @@
                        (false? matched?))}
         (t :ui/submit))]]]))
 
+(rum/defc e2ee-request-password
+  [password-promise]
+  (let [[password set-password!] (hooks/use-state "")
+        on-submit (fn []
+                    (p/resolve! password-promise password)
+                    (shui/dialog-close!))]
+    [:div.e2ee-password-modal-overlay
+     [:div.e2ee-password-modal-content.flex.flex-col.gap-8.p-4
+      [:div.text-2xl.font-medium (t :encryption/enter-password-title)]
+      [:div.flex.flex-col.gap-4
+       (shui/toggle-password
+        {:value password
+         :on-key-press (fn [e]
+                         (when (= "Enter" (util/ekey e))
+                           (on-submit)))
+         :on-change (fn [e]
+                      (set-password! (-> e .-target .-value)))})
+       (shui/button
+        {:on-click on-submit
+         :disabled (string/blank? password)
+         :on-key-press (fn [e]
+                         (when (= "Enter" (util/ekey e))
+                           (on-submit)))}
+        (t :ui/submit))]]]))
+
 (rum/defc e2ee-password-to-decrypt-private-key
-  [encrypted-private-key private-key-promise refresh-token]
+  [encrypted-private-key private-key-promise]
   (let [[password set-password!] (hooks/use-state "")
         [decrypt-fail? set-decrypt-fail!] (hooks/use-state false)
         on-submit (fn []
                     (->
                      (p/let [private-key (crypt/<decrypt-private-key password encrypted-private-key)]
-                       (state/<invoke-db-worker :thread-api/save-e2ee-password refresh-token password)
+                       (state/<invoke-db-worker :thread-api/save-e2ee-password password)
                        (p/resolve! private-key-promise private-key)
                        (shui/dialog-close!))
                      (p/catch (fn [e]
@@ -83,11 +108,11 @@
           :on-change (fn [e]
                        (set-decrypt-fail! false)
                        (set-password! (-> e .-target .-value)))})
-          (when decrypt-fail? [:p.text-warning.text-sm (t :encryption/wrong-password)])]
+        (when decrypt-fail? [:p.text-warning.text-sm (t :encryption/wrong-password)])]
        (shui/button
         {:on-click on-submit
          :disabled (string/blank? password)
          :on-key-press (fn [e]
                          (when (= "Enter" (util/ekey e))
                            (on-submit)))}
-         (t :ui/submit))]]]))
+        (t :ui/submit))]]]))
diff --git a/src/main/frontend/components/repo.cljs b/src/main/frontend/components/repo.cljs
index 8c30298e7c..9a478fd677 100644
--- a/src/main/frontend/components/repo.cljs
+++ b/src/main/frontend/components/repo.cljs
@@ -460,6 +460,7 @@
   [{:keys [cloud? graph-e2ee? refresh-token token user-uuid e2ee-rsa-key-ensured?]} set-e2ee-rsa-key-ensured?]
   (if (and cloud? graph-e2ee? refresh-token token user-uuid (not e2ee-rsa-key-ensured?))
     (-> (p/do!
+         (state/pub-event! [:rtc/sync-app-state])
          (state/<invoke-db-worker :thread-api/set-db-sync-config
                                   {:enabled? true
                                    :ws-url (config/db-sync-ws-url)
diff --git a/src/main/frontend/config.cljs b/src/main/frontend/config.cljs
index cf7f48cd38..91836e9cf6 100644
--- a/src/main/frontend/config.cljs
+++ b/src/main/frontend/config.cljs
@@ -5,7 +5,9 @@
             [frontend.state :as state]
             [frontend.util :as util]
             [goog.crypt.Md5]
+            [logseq.common.cognito-config :as cognito-config]
             [logseq.common.config :as common-config]
+            [logseq.common.graph-dir :as common-graph-dir]
             [logseq.common.path :as path]
             [logseq.db.sqlite.util :as sqlite-util]
             [shadow.resource :as rc]))
@@ -19,30 +21,19 @@
 (goog-define REVISION "unknown")
 (defonce revision REVISION)
 
-(goog-define ENABLE-FILE-SYNC-PRODUCTION false)
-
 ;; this is a feature flag to enable the account tab
 ;; when it launches (when pro plan launches) it should be removed
 (def ENABLE-SETTINGS-ACCOUNT-TAB false)
 
-(if ENABLE-FILE-SYNC-PRODUCTION
-  (do (def API-DOMAIN "api.logseq.com")
-      (def COGNITO-IDP "https://cognito-idp.us-east-1.amazonaws.com/")
-      (def COGNITO-CLIENT-ID "69cs1lgme7p8kbgld8n5kseii6")
-      (def REGION "us-east-1")
-      (def USER-POOL-ID "us-east-1_dtagLnju8")
-      (def IDENTITY-POOL-ID "us-east-1:d6d3b034-1631-402b-b838-b44513e93ee0")
-      (def OAUTH-DOMAIN "logseq-prod.auth.us-east-1.amazoncognito.com")
-      (def default-publish-api-base "https://logseq.io"))
+(def COGNITO-CLIENT-ID cognito-config/COGNITO-CLIENT-ID)
+(def OAUTH-DOMAIN cognito-config/OAUTH-DOMAIN)
 
-  (do (def API-DOMAIN "api-dev.logseq.com")
-      (def COGNITO-IDP "https://cognito-idp.us-east-2.amazonaws.com/")
-      (def COGNITO-CLIENT-ID "1qi1uijg8b6ra70nejvbptis0q")
-      (def REGION "us-east-2")
-      (def USER-POOL-ID "us-east-2_kAqZcxIeM")
-      (def IDENTITY-POOL-ID "us-east-2:cc7d2ad3-84d0-4faf-98fe-628f6b52c0a5")
-      (def OAUTH-DOMAIN "logseq-test2.auth.us-east-2.amazoncognito.com")
-      (def default-publish-api-base "https://logseq-publish-staging.logseq.workers.dev")))
+(def API-DOMAIN "api.logseq.com")
+(def COGNITO-IDP "https://cognito-idp.us-east-1.amazonaws.com/")
+(def REGION "us-east-1")
+(def USER-POOL-ID "us-east-1_dtagLnju8")
+(def IDENTITY-POOL-ID "us-east-1:d6d3b034-1631-402b-b838-b44513e93ee0")
+(def default-publish-api-base "https://logseq.io")
 
 ;; Enable for local development
 ;; (def default-publish-api-base "http://localhost:8787")
@@ -53,15 +44,12 @@
 (defonce default-db-sync-ws-url
   (if db-sync-local?
     "ws://127.0.0.1:8787/sync/%s"
-    ;; "wss://api-staging.logseq.io/sync/%s"
     "wss://api.logseq.io/sync/%s"))
 
 (defonce default-db-sync-http-base
   (if db-sync-local?
     "http://127.0.0.1:8787"
-    ;; "https://api-staging.logseq.io"
-    "https://api.logseq.io"
-    ))
+    "https://api.logseq.io"))
 
 (defn get-custom-sync-server-url
   "Read the user-configured custom sync server URL from localStorage.
@@ -144,8 +132,7 @@
 
 (defn publish-api-base
   "Return the base URL for the single-page publish service. Uses the user-configured
-   URL from localStorage when set, otherwise the default from the ENABLE-FILE-SYNC-PRODUCTION
-   branch above. Read on each call so URL changes take effect without a restart."
+   URL from localStorage when set, otherwise the default url above. Read on each call so URL changes take effect without a restart."
   []
   (if-let [custom (get-custom-publish-server-url)]
     (custom-url->publish-api-base custom)
@@ -325,7 +312,7 @@
 
 (defn db-graph-name
   [repo-with-prefix]
-  (string/replace-first repo-with-prefix db-version-prefix ""))
+  (common-config/strip-leading-db-version-prefix repo-with-prefix))
 
 (defn db-based-graph?
   ([]
@@ -344,7 +331,7 @@
   (path/path-join (get-in @state/state [:system/info :home-dir])
                   "logseq"
                   "graphs"
-                  (string/replace repo db-version-prefix "")))
+                  (common-graph-dir/repo->encoded-graph-dir-name repo)))
 
 (defn get-electron-backup-dir
   [repo]
@@ -356,7 +343,7 @@
     (if (util/electron?)
       (get-local-dir repo-url)
       (str "memory:///"
-           (string/replace-first repo-url db-version-prefix "")))))
+           (db-graph-name repo-url)))))
 
 (defn get-repo-config-path
   []
@@ -378,16 +365,15 @@
    (when-let [repo-dir (get-repo-dir repo)]
      (path/path-join repo-dir app-name  export-css-file))))
 
-(defn get-current-repo-assets-root
-  []
-  (when-let [repo-dir (get-repo-dir (state/get-current-repo))]
-    (path/path-join repo-dir "assets")))
-
 (defn get-repo-assets-root
   [repo]
   (when-let [repo-dir (get-repo-dir repo)]
     (path/path-join repo-dir "assets")))
 
+(defn get-current-repo-assets-root
+  []
+  (get-repo-assets-root (state/get-current-repo)))
+
 (defn get-custom-js-path
   ([]
    (get-custom-js-path (state/get-current-repo)))
diff --git a/src/main/frontend/db/conn.cljs b/src/main/frontend/db/conn.cljs
index f74f76967b..3ef5ab6f58 100644
--- a/src/main/frontend/db/conn.cljs
+++ b/src/main/frontend/db/conn.cljs
@@ -1,7 +1,6 @@
 (ns frontend.db.conn
   "Contains db connections."
-  (:require [clojure.string :as string]
-            [datascript.core :as d]
+  (:require [datascript.core :as d]
             [frontend.config :as config]
             [frontend.db.conn-state :as db-conn-state]
             [frontend.mobile.util :as mobile-util]
@@ -52,7 +51,7 @@
                      :else
                      repo-name)]
     (if (config/db-based-graph? repo-name')
-      (string/replace-first repo-name' config/db-version-prefix "")
+      (config/db-graph-name repo-name')
       repo-name')))
 
 (defn remove-conn!
diff --git a/src/main/frontend/db/persist.cljs b/src/main/frontend/db/persist.cljs
index 092f709033..9e5f626dd3 100644
--- a/src/main/frontend/db/persist.cljs
+++ b/src/main/frontend/db/persist.cljs
@@ -3,22 +3,21 @@
   (:require [cljs-bean.core :as bean]
             [clojure.string :as string]
             [electron.ipc :as ipc]
-            [frontend.config :as config]
             [frontend.persist-db :as persist-db]
             [frontend.util :as util]
             [logseq.common.config :as common-config]
             [promesa.core :as p]))
 
-(defn local-file-based-graph?
+(defn- local-file-based-graph?
   [s]
   (and (string? s)
-       (string/starts-with? s common-config/file-version-prefix)))
+       (string/starts-with? s (str common-config/db-version-prefix common-config/file-version-prefix))))
 
 (defn- upload-temp-graph?
   [graph-name]
   (let [graph-name (some-> graph-name str string/lower-case)]
     (or (= "upload-temp" graph-name)
-        (= (str (string/lower-case config/db-version-prefix) "upload-temp") graph-name))))
+        (= (str (string/lower-case common-config/db-version-prefix) "upload-temp") graph-name))))
 
 (defn get-all-graphs
   []
@@ -30,17 +29,20 @@
                       (map
                        (fn [{:keys [name] :as repo}]
                          (assoc repo :name
-                                (str config/db-version-prefix name)))))
+                                (common-config/canonicalize-db-version-repo name)))))
           electron-disk-graphs (when (util/electron?) (ipc/ipc "getGraphs"))]
     (distinct
      (concat
       repos'
-      (map (fn [repo-name] {:name repo-name})
-           (remove upload-temp-graph?
-                   (some-> electron-disk-graphs bean/->clj)))))))
+      (->> (some-> electron-disk-graphs bean/->clj)
+           (remove upload-temp-graph?)
+           (map (fn [repo-name]
+                  {:name (common-config/canonicalize-db-version-repo repo-name)})))))))
 
 (defn delete-graph!
   [graph]
-  (p/let [_ (persist-db/<unsafe-delete graph)]
-    (when (util/electron?)
-      (ipc/ipc "deleteGraph" graph))))
+  (if (util/electron?)
+    (p/do
+      (persist-db/<close-db graph)
+      (ipc/ipc "deleteGraph" graph))
+    (persist-db/<unsafe-delete graph)))
diff --git a/src/main/frontend/fs.cljs b/src/main/frontend/fs.cljs
index d57b46aacb..597b272c3e 100644
--- a/src/main/frontend/fs.cljs
+++ b/src/main/frontend/fs.cljs
@@ -121,7 +121,9 @@
     (if (util/electron?)
       (let [assets-dir (path/path-join repo-dir common-config/local-assets-dir)
             file-path (path/path-join assets-dir file-name)]
-        (write-file! file-path data))
+        ;; Use writeFileBytes directly instead of ipc/ipc (write-file!) because
+        ;; binary data like ArrayBuffer can't be transit-serialized
+        (js/window.apis.writeFileBytes file-path data))
       (let [file-path (path/path-join common-config/local-assets-dir file-name)]
         (write-plain-text-file! repo repo-dir file-path data {:skip-transact? true
                                                               :skip-compare? true})))))
diff --git a/src/main/frontend/fs/node.cljs b/src/main/frontend/fs/node.cljs
index 5e75c0be69..a060a5f5e4 100644
--- a/src/main/frontend/fs/node.cljs
+++ b/src/main/frontend/fs/node.cljs
@@ -4,52 +4,23 @@
             [clojure.string :as string]
             [electron.ipc :as ipc]
             [frontend.config :as config]
-            [frontend.db :as db]
             [frontend.fs.protocol :as protocol]
             [frontend.util :as util]
             [lambdaisland.glogi :as log]
             [logseq.common.path :as path]
             [promesa.core :as p]))
 
-(defn- <contents-matched?
-  [disk-content db-content]
-  (when (and (string? disk-content) (string? db-content))
-    (p/resolved (= (string/trim disk-content) (string/trim db-content)))))
-
 (defn- write-file-impl!
-  [repo dir rpath content {:keys [ok-handler error-handler old-content skip-compare?]} stat]
+  [repo dir rpath content {:keys [ok-handler error-handler]} _stat]
   (let [file-fpath (path/path-join dir rpath)]
-    (if skip-compare?
-      (p/catch
-       (p/let [result (ipc/ipc "writeFile" repo file-fpath content)]
-         (when ok-handler
-           (ok-handler repo rpath result)))
-       (fn [error]
-         (if error-handler
-           (error-handler error)
-           (log/error :write-file-failed error))))
-
-      ;; TODO: Remove backupDbFile which is a file graph concept
-      (p/let [disk-content (when (not= stat :not-found)
-                             (-> (ipc/ipc "readFile" file-fpath)
-                                 (p/then bean/->clj)
-                                 (p/catch (fn [error]
-                                            (js/console.error error)
-                                            nil))))
-              disk-content (or disk-content "")
-              db-content (or old-content (db/get-file repo rpath) "")
-              contents-matched? (<contents-matched? disk-content db-content)]
-        (->
-         (p/let [result (ipc/ipc "writeFile" repo file-fpath content)]
-           (when-not contents-matched?
-             (ipc/ipc "backupDbFile" (config/get-local-dir repo) rpath disk-content content))
-           (when ok-handler
-             (ok-handler repo rpath result))
-           result)
-         (p/catch (fn [error]
-                    (if error-handler
-                      (error-handler error)
-                      (log/error :write-file-failed error)))))))))
+    (p/catch
+        (p/let [result (ipc/ipc "writeFile" repo file-fpath content)]
+          (when ok-handler
+            (ok-handler repo rpath result)))
+        (fn [error]
+          (if error-handler
+            (error-handler error)
+            (log/error :write-file-failed error))))))
 
 (defn- open-dir
   "Open a new directory"
diff --git a/src/main/frontend/handler.cljs b/src/main/frontend/handler.cljs
index 149cb19a6c..ee46f5ac9d 100644
--- a/src/main/frontend/handler.cljs
+++ b/src/main/frontend/handler.cljs
@@ -34,7 +34,6 @@
             [frontend.modules.instrumentation.core :as instrument]
             [frontend.modules.shortcut.core :as shortcut]
             [frontend.persist-db :as persist-db]
-            [frontend.persist-db.browser :as db-browser]
             [frontend.state :as state]
             [frontend.util :as util]
             [goog.object :as gobj]
@@ -126,10 +125,10 @@
   (let [t1 (util/time-ms)]
     (p/do!
      (idb/start)
+     (get-system-info)
      (plugin-handler/setup!)
      (render))
 
-    (get-system-info)
     (set-global-error-notification!)
 
     (register-components-fns!)
@@ -150,7 +149,7 @@
 
     (p/do!
      (-> (p/let [t2 (util/time-ms)
-                 _ (db-browser/start-db-worker!)
+                 _ (persist-db/<start-runtime!)
                  _ (log/info ::db-worker-spent-time (- (util/time-ms) t2))
                  repos (repo-handler/get-repos)
                  _ (state/set-repos! repos)
@@ -160,9 +159,6 @@
                      (repo-handler/new-db! config/demo-repo)
                      (restore-and-setup! repo))]
            (set-network-watcher!)
-
-           (when (util/electron?)
-             (persist-db/run-export-periodically!))
            (when (mobile-util/native-platform?)
              (state/restore-mobile-theme!)))
          (p/catch (fn [e]
diff --git a/src/main/frontend/handler/assets.cljs b/src/main/frontend/handler/assets.cljs
index 1b94be762c..a7cb3fdd5d 100644
--- a/src/main/frontend/handler/assets.cljs
+++ b/src/main/frontend/handler/assets.cljs
@@ -1,23 +1,15 @@
 (ns ^:no-doc frontend.handler.assets
-  (:require [cljs-http-missionary.client :as http]
-            [clojure.string :as string]
-            [frontend.common.crypt :as crypt]
-            [frontend.common.missionary :as c.m]
-            [frontend.common.thread-api :as thread-api :refer [def-thread-api]]
+  (:require [clojure.string :as string]
             [frontend.config :as config]
             [frontend.fs :as fs]
             [frontend.state :as state]
             [frontend.util :as util]
-            [lambdaisland.glogi :as log]
             [logseq.common.config :as common-config]
             [logseq.common.path :as path]
             [logseq.common.util :as common-util]
-            [logseq.db :as ldb]
             [logseq.db.frontend.asset :as db-asset]
             [medley.core :as medley]
-            [missionary.core :as m]
-            [promesa.core :as p])
-  (:import [missionary Cancelled]))
+            [promesa.core :as p]))
 
 (defn exceed-limit-size?
   "Asset size no more than 100M"
@@ -165,7 +157,7 @@
   (-> (if (string? file) file (.arrayBuffer file))
       (p/then db-asset/<get-file-array-buffer-checksum)))
 
-(defn- ->uint8
+(defn ->uint8
   [payload]
   (cond
     (instance? js/Uint8Array payload)
@@ -216,28 +208,6 @@
   (p/let [[repo-dir assets-dir] (ensure-assets-dir! (state/get-current-repo))]
     (path/path-join repo-dir assets-dir filename)))
 
-(defn <get-all-asset-file-paths
-  [repo]
-  (when-let [path (config/get-repo-assets-root repo)]
-    (p/catch (fs/readdir path {:path-only? true})
-             (constantly nil))))
-
-(defn <read-asset
-  "Throw if asset not found"
-  [repo asset-block-id asset-type]
-  (let [repo-dir (config/get-repo-dir repo)
-        file-path (path/path-join common-config/local-assets-dir
-                                  (str asset-block-id "." asset-type))]
-    (fs/read-file-raw repo-dir file-path {})))
-
-(defn <get-asset-file-metadata
-  [repo asset-block-id asset-type]
-  (-> (p/let [file (<read-asset repo asset-block-id asset-type)
-              blob (js/Blob. (array file) (clj->js {:type "image"}))
-              checksum (get-file-checksum blob)]
-        {:checksum checksum})
-      (p/catch (constantly nil))))
-
 (defn- asset-transfer-in-progress?
   [progress-entry]
   (let [{:keys [loaded total]} progress-entry]
@@ -268,150 +238,3 @@
        repo
        (:block/uuid asset-block))
       true)))
-
-(defn <write-asset
-  [repo asset-block-id asset-type data]
-  (let [asset-block-id-str (str asset-block-id)
-        file-name (str asset-block-id-str "." asset-type)]
-    (p/do!
-     (fs/write-asset-file! repo file-name data)
-     (state/update-state!
-      :assets/asset-file-write-finish
-      (fn [m] (assoc-in m [repo asset-block-id-str] (common-util/time-ms)))))))
-
-(comment
-  ;; en/decrypt assets
-  (def repo (state/get-current-repo))
-  (p/let [aes-key (crypt/<generate-aes-key)
-          asset (<read-asset repo "6903201e-9573-4914-ae88-7d3f1d095d1f" "png")
-          encrypted-asset (crypt/<encrypt-uint8array aes-key asset)
-          decrypted-asset (crypt/<decrypt-uint8array aes-key encrypted-asset)]
-    (def asset asset)
-    (def xxxx encrypted-asset)
-    (prn :decrypted (.-length decrypted-asset)
-         :origin (.-length asset))))
-
-(defn <unlink-asset
-  [repo asset-block-id asset-type]
-  (let [file-path (path/path-join (config/get-repo-dir repo)
-                                  common-config/local-assets-dir
-                                  (str asset-block-id "." asset-type))]
-    (p/catch (fs/unlink! repo file-path {}) (constantly nil))))
-
-(defn new-task--rtc-upload-asset
-  [repo aes-key asset-block-uuid-str asset-type checksum put-url & {:keys [extra-headers]}]
-  (assert (and asset-type checksum))
-  (m/sp
-    (let [asset-file (try (c.m/<? (<read-asset repo asset-block-uuid-str asset-type))
-                          (catch :default e
-                            (log/info :read-asset e)
-                            (throw (ex-info "read-asset failed" {:type :rtc.exception/read-asset-failed} e))))
-          asset-file (if aes-key
-                       (->uint8 asset-file)
-                       asset-file)
-          asset-file* (if (not aes-key)
-                        asset-file
-                        (ldb/write-transit-str
-                         (c.m/<? (crypt/<encrypt-uint8array aes-key asset-file))))
-          *progress-flow (atom nil)
-          headers (merge extra-headers
-                         {"x-amz-meta-checksum" checksum
-                          "x-amz-meta-type" asset-type})
-          http-task (http/put put-url {:headers headers
-                                       :body asset-file*
-                                       :with-credentials? false
-                                       :*progress-flow *progress-flow})]
-      (c.m/run-task :upload-asset-progress
-        (m/reduce (fn [_ v]
-                    (state/update-state!
-                     :rtc/asset-upload-download-progress
-                     (fn [m] (assoc-in m [repo asset-block-uuid-str] v))))
-                  @*progress-flow)
-        :succ (constantly nil))
-      (let [{:keys [status] :as r} (m/? http-task)]
-        (when-not (http/unexceptional-status? status)
-          (throw (ex-info "upload-asset failed"
-                          {:type :rtc.exception/upload-asset-failed :data (dissoc r :body)})))))))
-
-(defn new-task--rtc-download-asset
-  [repo aes-key asset-block-uuid-str asset-type get-url & {:keys [extra-headers]}]
-  (m/sp
-    (let [*progress-flow (atom nil)
-          http-task (http/get get-url {:with-credentials? false
-                                       :response-type :array-buffer
-                                       :headers extra-headers
-                                       :*progress-flow *progress-flow})
-          progress-canceler
-          (c.m/run-task :download-asset-progress
-            (m/reduce (fn [_ v]
-                        (state/update-state!
-                         :rtc/asset-upload-download-progress
-                         (fn [m] (assoc-in m [repo asset-block-uuid-str] v))))
-                      @*progress-flow)
-            :succ (constantly nil))]
-      (try
-        (let [{:keys [status body] :as r} (m/? http-task)]
-          (if-not (http/unexceptional-status? status)
-            (throw (ex-info "download asset failed"
-                            {:type :rtc.exception/download-asset-failed :data (dissoc r :body)}))
-            (let [asset-file
-                  (if (not aes-key)
-                    body
-                    (try
-                      (let [asset-file-untransited (ldb/read-transit-str (.decode (js/TextDecoder.) body))]
-                        (c.m/<? (crypt/<decrypt-uint8array aes-key asset-file-untransited)))
-                      (catch js/SyntaxError _
-                        body)
-                      (catch :default e
-                         ;; if decrypt failed, write origin-body
-                        (if (= "decrypt-uint8array" (ex-message e))
-                          body
-                          (throw e)))))]
-              (c.m/<? (<write-asset repo asset-block-uuid-str asset-type asset-file))
-              nil)))
-        (catch Cancelled e
-          (progress-canceler)
-          (throw e))))))
-
-(def-thread-api :thread-api/unlink-asset
-  [repo asset-block-id asset-type]
-  (<unlink-asset repo asset-block-id asset-type))
-
-(def-thread-api :thread-api/get-all-asset-file-paths
-  [repo]
-  (<get-all-asset-file-paths repo))
-
-(def-thread-api :thread-api/get-asset-file-metadata
-  [repo asset-block-id asset-type]
-  (<get-asset-file-metadata repo asset-block-id asset-type))
-
-(def-thread-api :thread-api/rtc-upload-asset
-  [repo exported-aes-key asset-block-uuid-str asset-type checksum put-url & {:as opts}]
-  (m/sp
-    (let [aes-key (when exported-aes-key (c.m/<? (crypt/<import-aes-key exported-aes-key)))]
-      (m/? (new-task--rtc-upload-asset repo aes-key asset-block-uuid-str asset-type checksum put-url opts)))))
-
-(def-thread-api :thread-api/rtc-download-asset
-  [repo exported-aes-key asset-block-uuid-str asset-type get-url & {:as opts}]
-  (m/sp
-    (let [aes-key (when exported-aes-key (c.m/<? (crypt/<import-aes-key exported-aes-key)))]
-      (m/? (new-task--rtc-download-asset repo aes-key asset-block-uuid-str asset-type get-url opts)))))
-
-(comment
-  ;; read asset
-  (p/let [repo "logseq_db_demo"
-          ;; Existing asset block's id
-          asset-block-id-str "672c5a1d-8171-4259-9f35-470c3c67e37f"
-          asset-type "png"
-          data (<read-asset repo asset-block-id-str asset-type)]
-    (js/console.dir data))
-
-  ;; write asset
-  (p/let [repo "logseq_db_demo"
-          ;; Existing asset block's id
-          asset-block-id-str "672c5a1d-8171-4259-9f35-470c3c67e37f"
-          asset-type "png"
-          data (<read-asset repo asset-block-id-str asset-type)
-          new-asset-id (random-uuid)
-          result (<write-asset repo new-asset-id asset-type data)]
-    (js/console.dir result)))
diff --git a/src/main/frontend/handler/db_based/sync.cljs b/src/main/frontend/handler/db_based/sync.cljs
index d05ea66b2f..2b49a83820 100644
--- a/src/main/frontend/handler/db_based/sync.cljs
+++ b/src/main/frontend/handler/db_based/sync.cljs
@@ -7,12 +7,12 @@
             [frontend.handler.notification :as notification]
             [frontend.handler.repo :as repo-handler]
             [frontend.handler.user :as user-handler]
+            [frontend.persist-db :as persist-db]
             [frontend.state :as state]
             [frontend.util :as util]
             [lambdaisland.glogi :as log]
             [logseq.db :as ldb]
             [logseq.db-sync.malli-schema :as db-sync-schema]
-            [logseq.db.sqlite.util :as sqlite-util]
             [promesa.core :as p]))
 
 (defn- ws->http-base [ws-url]
@@ -44,6 +44,7 @@
 (declare fetch-json)
 
 (declare coerce-http-response)
+(declare <sync-auth-state-to-db-worker!)
 
 (defn fetch-json
   [url opts {:keys [response-schema error-schema] :or {error-schema :error}}]
@@ -116,6 +117,14 @@
     true
     (true? graph-e2ee?)))
 
+(defn- <ensure-download-runtime-bound!
+  [repo]
+  (if (util/electron?)
+    (p/let [_ (persist-db/<fetch-init-data repo {:sync-download-graph? true})
+            _ (<sync-auth-state-to-db-worker!)]
+      nil)
+    (p/resolved nil)))
+
 (defn- <ensure-user-rsa-keys-on-server!
   [{:keys [server-rsa-keys-exists?]}]
   (if (not= false server-rsa-keys-exists?)
@@ -158,13 +167,32 @@
   (log/info :db-sync/stop true)
   (state/<invoke-db-worker :thread-api/db-sync-stop))
 
+(defn- sync-app-state-payload
+  []
+  (cond-> (select-keys @state/state [:git/current-repo :config
+                                     :auth/id-token :auth/access-token :auth/refresh-token
+                                     :auth/oauth-token-url :auth/oauth-domain :auth/oauth-client-id
+                                     :user/info])
+    (seq config/OAUTH-DOMAIN)
+    (assoc :auth/oauth-domain config/OAUTH-DOMAIN)
+
+    (seq config/COGNITO-CLIENT-ID)
+    (assoc :auth/oauth-client-id config/COGNITO-CLIENT-ID)))
+
+(defn- <sync-auth-state-to-db-worker!
+  []
+  (p/let [_ (js/Promise. user-handler/task--ensure-id&access-token)
+          payload (sync-app-state-payload)]
+    (state/<invoke-db-worker :thread-api/sync-app-state payload)))
+
 (defn <rtc-start!
   [repo & {:keys [_stop-before-start?] :as _opts}]
   (p/let [_ (<wait-for-db-worker-ready!)]
     (if (should-start-rtc? repo)
       (do
         (log/info :db-sync/start {:repo repo})
-        (state/<invoke-db-worker :thread-api/db-sync-start repo))
+        (p/let [_ (<sync-auth-state-to-db-worker!)]
+          (state/<invoke-db-worker :thread-api/db-sync-start repo)))
       (do
         (log/info :db-sync/skip-start {:repo repo :reason :graph-not-in-remote-list
                                        :remote-graphs-loading? (:rtc/loading-graphs? @state/state)
@@ -209,44 +237,8 @@
   ([repo graph-e2ee?]
    (<rtc-create-graph! repo graph-e2ee? true))
   ([repo graph-e2ee? graph-ready-for-use?]
-   (let [schema-version (some-> (ldb/get-graph-schema-version (db/get-db)) :major str)
-         graph-e2ee? (normalize-graph-e2ee? graph-e2ee?)
-         graph-ready-for-use? (not= false graph-ready-for-use?)
-         base (http-base)]
-     (if base
-       (p/let [_ (js/Promise. user-handler/task--ensure-id&access-token)
-               _ (state/<invoke-db-worker :thread-api/db-sync-ensure-user-rsa-keys
-                                          {:ensure-server? true})
-               body (coerce-http-request :graphs/create
-                                         {:graph-name (string/replace repo config/db-version-prefix "")
-                                          :schema-version schema-version
-                                          :graph-e2ee? graph-e2ee?
-                                          :graph-ready-for-use? graph-ready-for-use?})
-               result (if (nil? body)
-                        (p/rejected (ex-info "db-sync invalid create-graph body"
-                                             {:repo repo}))
-                        (fetch-json (str base "/graphs")
-                                    {:method "POST"
-                                     :headers {"content-type" "application/json"}
-                                     :body (js/JSON.stringify (clj->js body))}
-                                    {:response-schema :graphs/create}))
-               graph-id (:graph-id result)
-               graph-e2ee? (normalize-graph-e2ee?
-                            (if (contains? result :graph-e2ee?)
-                              (:graph-e2ee? result)
-                              graph-e2ee?))]
-         (if graph-id
-           (p/do!
-            (ldb/transact! repo [(sqlite-util/kv :logseq.kv/db-type "db")
-                                 (sqlite-util/kv :logseq.kv/graph-uuid (uuid graph-id))
-                                 (sqlite-util/kv :logseq.kv/graph-rtc-e2ee? graph-e2ee?)])
-            graph-id)
-           (p/rejected (ex-info "db-sync missing graph id in create response"
-                                {:type :db-sync/invalid-graph
-                                 :response result}))))
-       (p/rejected (ex-info "db-sync missing graph info"
-                            {:type :db-sync/invalid-graph
-                             :base base}))))))
+   (state/<invoke-db-worker :thread-api/db-sync-create-remote-graph
+                            repo graph-e2ee? graph-ready-for-use?)))
 
 (defn <rtc-delete-graph!
   [graph-uuid _schema-version]
@@ -276,7 +268,8 @@
      (-> (if (and graph-uuid base)
            (p/let [_ (js/Promise. user-handler/task--ensure-id&access-token)
                    graph (str config/db-version-prefix graph-name)
-                   _ (state/<invoke-db-worker :thread-api/db-sync-download-graph
+                   _ (<ensure-download-runtime-bound! graph)
+                   _ (state/<invoke-db-worker :thread-api/db-sync-download-graph-by-id
                                               graph graph-uuid graph-e2ee?)]
              true)
            (p/rejected (ex-info "db-sync missing graph info"
@@ -391,14 +384,11 @@
                           :graph-uuid graph-uuid}))))
 
 (defn <rtc-upload-graph!
-  [repo graph-e2ee?]
-  (p/let [graph-id (<rtc-create-graph! repo graph-e2ee? false)]
-    (when (nil? graph-id)
-      (throw (ex-info "graph id doesn't exist when uploading to server" {:repo repo})))
-    (p/do!
-     (state/<invoke-db-worker :thread-api/db-sync-upload-graph repo)
-     (<get-remote-graphs)
-     (<rtc-start! repo))))
+  [repo _graph-e2ee?]
+  (p/do!
+   (state/<invoke-db-worker :thread-api/db-sync-upload-graph repo)
+   (<get-remote-graphs)
+   (<rtc-start! repo)))
 
 (defn <rtc-create-graph-and-start-sync!
   [repo graph-e2ee?]
diff --git a/src/main/frontend/handler/e2ee.cljs b/src/main/frontend/handler/e2ee.cljs
index 3f8006e73b..6b01bb141b 100644
--- a/src/main/frontend/handler/e2ee.cljs
+++ b/src/main/frontend/handler/e2ee.cljs
@@ -1,12 +1,8 @@
 (ns frontend.handler.e2ee
   "rtc E2EE related fns"
   (:require [electron.ipc :as ipc]
-            [frontend.common.crypt :as crypt]
-            [frontend.common.thread-api :refer [def-thread-api]]
             [frontend.mobile.secure-storage :as secure-storage]
-            [frontend.state :as state]
             [frontend.util :as util]
-            [lambdaisland.glogi :as log]
             [promesa.core :as p]))
 
 (def ^:private save-op :keychain/save-e2ee-password)
@@ -49,34 +45,24 @@
     :else
     (p/resolved nil)))
 
-(def-thread-api :thread-api/request-e2ee-password
+(defn native-storage-supported?
   []
-  (p/let [password-promise (state/pub-event! [:rtc/request-e2ee-password])
-          password password-promise]
-    {:password password}))
+  (or (util/electron?) (util/capacitor?)))
 
-(defn- <decrypt-user-e2ee-private-key
-  [encrypted-private-key]
-  (->
-   (p/let [private-key-promise (state/pub-event! [:rtc/decrypt-user-e2ee-private-key encrypted-private-key])
-           private-key private-key-promise]
-     (crypt/<export-private-key private-key))
-   (p/catch (fn [e]
-              (log/error :<decrypt-user-e2ee-private-key e)
-              e))))
+(defn <native-save-secret!
+  [key encrypted-text]
+  (if (native-storage-supported?)
+    (<keychain-save! key encrypted-text)
+    (p/resolved nil)))
 
-(def-thread-api :thread-api/decrypt-user-e2ee-private-key
-  [encrypted-private-key]
-  (<decrypt-user-e2ee-private-key encrypted-private-key))
+(defn <native-get-secret
+  [key]
+  (if (native-storage-supported?)
+    (<keychain-get key)
+    (p/resolved nil)))
 
-(def-thread-api :thread-api/native-save-e2ee-password
-  [encrypted-text]
-  (<keychain-save! "logseq-encrypted-password" encrypted-text))
-
-(def-thread-api :thread-api/native-get-e2ee-password
-  []
-  (<keychain-get "logseq-encrypted-password"))
-
-(def-thread-api :thread-api/native-delete-e2ee-password
-  []
-  (<keychain-delete! "logseq-encrypted-password"))
+(defn <native-delete-secret!
+  [key]
+  (if (native-storage-supported?)
+    (<keychain-delete! key)
+    (p/resolved nil)))
diff --git a/src/main/frontend/handler/events.cljs b/src/main/frontend/handler/events.cljs
index 3973f886d8..e92c09202b 100644
--- a/src/main/frontend/handler/events.cljs
+++ b/src/main/frontend/handler/events.cljs
@@ -49,7 +49,8 @@
             [logseq.api.plugin :as plugin-api]
             [logseq.db.frontend.schema :as db-schema]
             [logseq.shui.ui :as shui]
-            [promesa.core :as p]))
+            [promesa.core :as p]
+            [cljs-time.core :as t]))
 
 ;; TODO: should we move all events here?
 
@@ -122,16 +123,15 @@
             (search-plugin/call-service! service "search:rebuildBlocksIndice" {}))))))))
 
 (defmethod handle :graph/switch [[_ graph opts]]
-  (let [switch-promise
-        (p/do!
-         (export/cancel-db-backup!)
-         (persist-db/export-current-graph!)
-         (state/set-state! :db/async-queries {})
-         (st/refresh!)
-         (graph-switch-on-persisted graph opts))]
-    (p/then switch-promise
-            (fn [_]
-              (export/backup-db-graph (state/get-current-repo))))))
+  (let [t1 (t/now)]
+    (p/do!
+    (export/cancel-db-backup!)
+    (state/set-state! :db/async-queries {})
+    (st/refresh!)
+    (graph-switch-on-persisted graph opts)
+    (export/backup-db-graph (state/get-current-repo))
+    (let [t2 (t/now)]
+      (log/info ::graph-switch-spent (- t2 t1))))))
 
 (defmethod handle :graph/open-new-window [[_ev target-repo]]
   (ui-handler/open-new-window-or-tab! target-repo))
@@ -171,7 +171,9 @@
 
 (defmethod handle :instrument [[_ {:keys [type payload] :as opts}]]
   (when-not (empty? (dissoc opts :type :payload))
-    (js/console.error "instrument data-map should only contains [:type :payload]"))
+    (log/error :event :invalid-instrument-payload-keys
+               :message "instrument data-map should only contain [:type :payload]"
+               :payload opts))
   (posthog/capture type payload))
 
 (defmethod handle :capture-error [[_ {:keys [error payload extra]}]]
@@ -248,7 +250,10 @@
     (state/pub-event! [:graph/ready graph])))
 
 (defmethod handle :graph/save-db-to-disk [[_ _opts]]
-  (persist-db/export-current-graph! {:succ-notification? true :force-save? true}))
+  (persist-db/export-current-graph! :succ-notification? true))
+
+(defmethod handle :graph/db-save-shortcut [[_]]
+  (handle [:graph/save-db-to-disk {:source :shortcut}]))
 
 (defmethod handle :ui/re-render-root [[_]]
   (ui-handler/re-render-root!))
diff --git a/src/main/frontend/handler/events/rtc.cljs b/src/main/frontend/handler/events/rtc.cljs
index 170483684b..c2e6567fef 100644
--- a/src/main/frontend/handler/events/rtc.cljs
+++ b/src/main/frontend/handler/events/rtc.cljs
@@ -3,6 +3,7 @@
   (:require [frontend.common.crypt :as crypt]
             [frontend.common.missionary :as c.m]
             [frontend.components.e2ee :as e2ee]
+            [frontend.config :as config]
             [frontend.context.i18n :refer [t]]
             [frontend.handler.events :as events]
             [frontend.handler.notification :as notification]
@@ -12,9 +13,15 @@
             [missionary.core :as m]
             [promesa.core :as p]))
 
+(defn rtc-collaborators-dialog?
+  []
+  (= :rtc-collaborators (state/get-modal-id)))
+
 (defmethod events/handle :rtc/decrypt-user-e2ee-private-key [[_ encrypted-private-key]]
   (let [private-key-promise (p/deferred)
         refresh-token (str (state/get-auth-refresh-token))]
+    (when-not (rtc-collaborators-dialog?)
+      (shui/dialog-close-all!))
     (->
      (p/let [{:keys [password]} (state/<invoke-db-worker :thread-api/get-e2ee-password refresh-token)
              private-key (crypt/<decrypt-private-key password encrypted-private-key)]
@@ -23,7 +30,7 @@
       (fn [error]
         (log/error :read-e2ee-password-failed error)
         (shui/dialog-open!
-         #(e2ee/e2ee-password-to-decrypt-private-key encrypted-private-key private-key-promise refresh-token)
+         #(e2ee/e2ee-password-to-decrypt-private-key encrypted-private-key private-key-promise)
          {:auto-width? true
           :content-props {:onPointerDownOutside #(.preventDefault %)}
           :on-close (fn []
@@ -31,10 +38,15 @@
                       (shui/dialog-close!))}))))
     private-key-promise))
 
-(defmethod events/handle :rtc/request-e2ee-password [[_]]
-  (let [password-promise (p/deferred)]
+(defmethod events/handle :rtc/request-e2ee-password [[_ {:keys [reason]}]]
+  (let [password-promise (p/deferred)
+        decrypt-reason? (= :decrypt-user-rsa-private-key reason)]
+    (when-not (rtc-collaborators-dialog?)
+      (shui/dialog-close-all!))
     (shui/dialog-open!
-     #(e2ee/e2ee-request-new-password password-promise)
+     #(if decrypt-reason?
+        (e2ee/e2ee-request-password password-promise)
+        (e2ee/e2ee-request-new-password password-promise))
      {:auto-width? true
       :content-props {:onPointerDownOutside #(.preventDefault %)}
       :on-close (fn []
@@ -53,9 +65,16 @@
   (let [state-flow
         (->> (m/watch state/state)
              (m/eduction
-              (map #(select-keys % [:git/current-repo :config
-                                    :auth/id-token :auth/access-token :auth/refresh-token
-                                    :user/info]))
+              (map (fn [app-state]
+                     (cond-> (select-keys app-state [:git/current-repo :config
+                                                     :auth/id-token :auth/access-token :auth/refresh-token
+                                                     :auth/oauth-token-url :auth/oauth-domain :auth/oauth-client-id
+                                                     :user/info])
+                       (seq config/OAUTH-DOMAIN)
+                       (assoc :auth/oauth-domain config/OAUTH-DOMAIN)
+
+                       (seq config/COGNITO-CLIENT-ID)
+                       (assoc :auth/oauth-client-id config/COGNITO-CLIENT-ID))))
               (dedupe)))
         <init-sync-done? (p/deferred)
         task (m/reduce
diff --git a/src/main/frontend/handler/user.cljs b/src/main/frontend/handler/user.cljs
index b9ac28a537..d56e98500d 100644
--- a/src/main/frontend/handler/user.cljs
+++ b/src/main/frontend/handler/user.cljs
@@ -7,6 +7,7 @@
             [cljs.core.async :as async :refer [<! go timeout]]
             [clojure.set :as set]
             [clojure.string :as string]
+            [electron.ipc :as ipc]
             [frontend.common.missionary :as c.m]
             [frontend.common.thread-api :refer [def-thread-api]]
             [frontend.config :as config]
@@ -15,6 +16,8 @@
             [frontend.flows :as flows]
             [frontend.handler.notification :as notification]
             [frontend.state :as state]
+            [frontend.util :as util]
+            [logseq.common.path :as path]
             [goog.crypt :as crypt]
             [goog.crypt.Hmac]
             [goog.crypt.Sha256]
@@ -100,6 +103,30 @@
    (js/localStorage.setItem "access-token" access-token)
    (js/localStorage.setItem "refresh-token" refresh-token)))
 
+(defn- auth-file-path
+  []
+  (when-let [home-dir (get-in @state/state [:system/info :home-dir])]
+    (path/path-join home-dir "logseq" "auth.json")))
+
+(defn- auth-file-payload
+  []
+  {:id-token (state/get-auth-id-token)
+   :access-token (:auth/access-token @state/state)
+   :refresh-token (state/get-auth-refresh-token)
+   :updated-at (.now js/Date)})
+
+(defn- persist-auth-file!
+  []
+  (when (util/electron?)
+    (when-let [auth-path (auth-file-path)]
+      (-> (ipc/ipc "writeFile"
+                   nil
+                   auth-path
+                   (js/JSON.stringify (clj->js (auth-file-payload)) nil 2))
+          (p/catch (fn [error]
+                     (js/console.warn :persist-auth-file-failed error)
+                     nil))))))
+
 (defn- clear-cognito-tokens!
   "Clear tokens for cognito's localstorage, prefix is 'CognitoIdentityServiceProvider'"
   []
@@ -119,7 +146,8 @@
       (let [refresh-token (js/localStorage.getItem refresh-token-key)]
         (when (and refresh-token (not= refresh-token "undefined"))
           (state/set-auth-refresh-token refresh-token)
-          (js/localStorage.setItem "refresh-token" refresh-token))))))
+          (js/localStorage.setItem "refresh-token" refresh-token)
+          (persist-auth-file!))))))
 
 (defn- clear-tokens
   ([]
@@ -127,7 +155,8 @@
    (state/set-auth-access-token nil)
    (state/set-auth-refresh-token nil)
    (set-token-to-localstorage! "" "" "")
-   (clear-cognito-tokens!))
+   (clear-cognito-tokens!)
+   (persist-auth-file!))
   ([except-refresh-token?]
    (state/set-auth-id-token nil)
    (state/set-auth-access-token nil)
@@ -135,13 +164,15 @@
      (state/set-auth-refresh-token nil))
    (if except-refresh-token?
      (set-token-to-localstorage! "" "")
-     (set-token-to-localstorage! "" "" ""))))
+     (set-token-to-localstorage! "" "" ""))
+   (persist-auth-file!)))
 
 (defn- set-tokens!
   ([id-token access-token]
    (state/set-auth-id-token id-token)
    (state/set-auth-access-token access-token)
    (set-token-to-localstorage! id-token access-token)
+   (persist-auth-file!)
    (some->> (parse-jwt (state/get-auth-id-token))
             (reset! flows/*current-login-user)))
   ([id-token access-token refresh-token]
@@ -149,6 +180,7 @@
    (state/set-auth-access-token access-token)
    (state/set-auth-refresh-token refresh-token)
    (set-token-to-localstorage! id-token access-token refresh-token)
+   (persist-auth-file!)
    (some->> (parse-jwt (state/get-auth-id-token))
             (reset! flows/*current-login-user))))
 
diff --git a/src/main/frontend/handler/worker.cljs b/src/main/frontend/handler/worker.cljs
index 749b32b568..a38514f280 100644
--- a/src/main/frontend/handler/worker.cljs
+++ b/src/main/frontend/handler/worker.cljs
@@ -2,11 +2,14 @@
   "Handle messages received from the webworkers"
   (:require [cljs-bean.core :as bean]
             [clojure.string :as string]
+            [frontend.common.crypt :as crypt]
             [frontend.context.i18n :as i18n]
+            [frontend.handler.e2ee :as e2ee-handler]
             [frontend.handler.notification :as notification]
             [frontend.state :as state]
             [lambdaisland.glogi :as log]
-            [logseq.db :as ldb]))
+            [logseq.db :as ldb]
+            [promesa.core :as p]))
 
 (defmulti handle identity)
 
@@ -42,6 +45,18 @@
   (let [state data]
     (state/pub-event! [:rtc/sync-state state])))
 
+(defmethod handle :rtc-asset-upload-download-progress [_ _worker {:keys [repo asset-id progress]}]
+  (when (and (seq repo) (seq asset-id) (map? progress))
+    (state/update-state!
+     :rtc/asset-upload-download-progress
+     (fn [m] (assoc-in m [repo asset-id] progress)))))
+
+(defmethod handle :asset-file-write-finish [_ _worker {:keys [repo asset-id ts]}]
+  (when (and (seq repo) (seq asset-id))
+    (state/update-state!
+     :assets/asset-file-write-finish
+     (fn [m] (assoc-in m [repo asset-id] (or ts (.now js/Date)))))))
+
 (defmethod handle :sync-db-changes [_ _worker data]
   (state/pub-event! [:db/sync-changes data]))
 
@@ -67,6 +82,100 @@
 (defmethod handle :remote-graph-gone []
   (state/pub-event! [:rtc/remote-graph-gone]))
 
+(defn- <invoke-worker-thread-api
+  [wrapped-worker qkw & args]
+  (apply wrapped-worker qkw false args))
+
+(defn- ui-request-error->payload
+  [error]
+  (let [data (ex-data error)]
+    (merge {:code (or (:code data) :ui-request-failed)
+            :message (or (ex-message error) (str error))}
+           (when (seq data)
+             {:data data}))))
+
+(defn- <db-worker-ui-action
+  [action payload]
+  (case action
+    :request-e2ee-password
+    (p/let [password-promise (state/pub-event! [:rtc/request-e2ee-password payload])
+            password password-promise]
+      {:password password})
+
+    :decrypt-user-e2ee-private-key
+    (let [encrypted-private-key (:encrypted-private-key payload)]
+      (p/let [private-key-promise (state/pub-event! [:rtc/decrypt-user-e2ee-private-key encrypted-private-key])
+              private-key private-key-promise]
+        (crypt/<export-private-key private-key)))
+
+    :native-save-e2ee-password
+    (let [{:keys [key encrypted-text]} payload]
+      (if-not (and (string? key) (string? encrypted-text))
+        (p/rejected (ex-info "invalid native-save-e2ee-password payload"
+                             {:code :invalid-ui-action-payload
+                              :action action
+                              :payload payload}))
+        (if-not (e2ee-handler/native-storage-supported?)
+          (p/resolved {:supported? false})
+          (p/let [_ (e2ee-handler/<native-save-secret! key encrypted-text)]
+            {:supported? true}))))
+
+    :native-get-e2ee-password
+    (let [{:keys [key]} payload]
+      (if-not (string? key)
+        (p/rejected (ex-info "invalid native-get-e2ee-password payload"
+                             {:code :invalid-ui-action-payload
+                              :action action
+                              :payload payload}))
+        (if-not (e2ee-handler/native-storage-supported?)
+          (p/resolved {:supported? false})
+          (p/let [encrypted-text (e2ee-handler/<native-get-secret key)]
+            {:supported? true
+             :encrypted-text encrypted-text}))))
+
+    :native-delete-e2ee-password
+    (let [{:keys [key]} payload]
+      (if-not (string? key)
+        (p/rejected (ex-info "invalid native-delete-e2ee-password payload"
+                             {:code :invalid-ui-action-payload
+                              :action action
+                              :payload payload}))
+        (if-not (e2ee-handler/native-storage-supported?)
+          (p/resolved {:supported? false})
+          (p/let [_ (e2ee-handler/<native-delete-secret! key)]
+            {:supported? true}))))
+
+    (p/rejected (ex-info "unsupported db-worker ui action"
+                         {:code :unsupported-ui-action
+                          :action action
+                          :payload payload}))))
+
+(defn- <handle-db-worker-ui-request
+  [wrapped-worker {:keys [request-id action payload]}]
+  (if (and (string? request-id) (keyword? action))
+    (-> (<db-worker-ui-action action payload)
+        (p/then (fn [result]
+                  (<invoke-worker-thread-api wrapped-worker
+                                             :thread-api/resolve-ui-request
+                                             request-id
+                                             result)))
+        (p/catch (fn [error]
+                   (log/warn :db-worker/ui-request-failed
+                             {:request-id request-id
+                              :action action
+                              :error error})
+                   (<invoke-worker-thread-api wrapped-worker
+                                              :thread-api/reject-ui-request
+                                              request-id
+                                              (ui-request-error->payload error)))))
+    (log/error :db-worker/ui-request-invalid
+               {:request-id request-id
+                :action action
+                :payload payload})))
+
+(defmethod handle :db-worker/ui-request [_ wrapped-worker data]
+  (<handle-db-worker-ui-request wrapped-worker data))
+
 (defmethod handle :default [_ _worker data]
   (prn :debug "Worker data not handled: " data))
 
diff --git a/src/main/frontend/modules/shortcut/config.cljs b/src/main/frontend/modules/shortcut/config.cljs
index 40975bce76..fc6bf1f224 100644
--- a/src/main/frontend/modules/shortcut/config.cljs
+++ b/src/main/frontend/modules/shortcut/config.cljs
@@ -367,7 +367,7 @@
                                              :inactive config/publishing?
                                              :binding false}
 
-   :graph/db-save                           {:fn #(state/pub-event! [:graph/save-db-to-disk])
+   :graph/db-save                           {:fn #(state/pub-event! [:graph/db-save-shortcut])
                                              :inactive (not (util/electron?))
                                              :binding "mod+s"}
 
diff --git a/src/main/frontend/persist_db.cljs b/src/main/frontend/persist_db.cljs
index a2461df247..cbc9e42634 100644
--- a/src/main/frontend/persist_db.cljs
+++ b/src/main/frontend/persist_db.cljs
@@ -1,13 +1,93 @@
 (ns frontend.persist-db
   "Backend of DB based graph"
-  (:require [frontend.db :as db]
+  (:require [electron.ipc :as ipc]
+            [frontend.config :as config]
+            [frontend.db.transact :as db-transact]
             [frontend.persist-db.browser :as browser]
             [frontend.persist-db.protocol :as protocol]
+            [frontend.persist-db.remote :as remote]
+            [frontend.handler.worker :as worker-handler]
             [frontend.state :as state]
             [frontend.util :as util]
+            [lambdaisland.glogi :as log]
+            [logseq.db :as ldb]
             [promesa.core :as p]))
 
 (defonce opfs-db (browser/->InBrowser))
+(defonce remote-db (atom nil))
+(defonce remote-repo (atom nil))
+
+(defn- clear-remote-runtime!
+  []
+  (reset! remote-db nil)
+  (reset! remote-repo nil)
+  (reset! state/*db-worker nil))
+
+(defn- <stop-remote-if-current!
+  [repo]
+  (if (and repo (= repo @remote-repo))
+    (if-let [remote-client @remote-db]
+      (-> (remote/stop! remote-client)
+          (p/finally
+           (fn []
+             (when (= repo @remote-repo)
+               (clear-remote-runtime!)))))
+      (do
+        (clear-remote-runtime!)
+        (p/resolved true)))
+    (p/resolved false)))
+
+(defn- node-runtime?
+  []
+  (and (exists? js/process)
+       (not (exists? js/window))))
+
+(defn- electron-runtime?
+  []
+  (and (not (node-runtime?))
+       (util/electron?)))
+
+(defn- current-db-sync-config
+  []
+  {:enabled? true
+   :ws-url (config/db-sync-ws-url)
+   :http-base (config/db-sync-http-base)})
+
+(defn- <ensure-remote!
+  [repo]
+  (if (or (nil? repo) (= repo @remote-repo))
+    (p/resolved @remote-db)
+    (p/let [_ (when @remote-db
+                (remote/stop! @remote-db))
+            runtime (ipc/ipc "db-worker-runtime" repo)
+            client (remote/start! (assoc runtime
+                                         :repo repo
+                                         :event-handler worker-handler/handle))]
+      (reset! remote-db client)
+      (reset! remote-repo repo)
+      (reset! state/*db-worker (:wrapped-worker client))
+      (p/let [_ (state/<invoke-db-worker :thread-api/set-db-sync-config
+                                         (current-db-sync-config))]
+        nil)
+      (ldb/register-transact-fn!
+       (fn remote-transact!
+         [repo tx-data tx-meta]
+         (db-transact/transact browser/transact!
+                               (if (string? repo) repo (state/get-current-repo))
+                               tx-data
+                               (assoc tx-meta :client-id (:client-id @state/state)))))
+      client)))
+
+(defn <start-runtime!
+  []
+  (cond
+    (electron-runtime?)
+    (if-let [repo (state/get-current-repo)]
+      (<ensure-remote! repo)
+      (p/resolved nil))
+
+    :else
+    (browser/start-db-worker!)))
 
 (defn- get-impl
   "Get the actual implementation of PersistentDB"
@@ -15,67 +95,81 @@
   opfs-db)
 
 (defn <list-db []
-  (protocol/<list-db (get-impl)))
+  (if (electron-runtime?)
+    (if-let [repo (or @remote-repo (state/get-current-repo))]
+      (p/let [client (<ensure-remote! repo)]
+        (protocol/<list-db client))
+      (p/resolved []))
+    (protocol/<list-db (get-impl))))
 
 (defn <unsafe-delete [repo]
-  (when repo (protocol/<unsafe-delete (get-impl) repo)))
+  (when repo
+    (if (electron-runtime?)
+      (p/let [client (<ensure-remote! repo)]
+        (protocol/<unsafe-delete client repo))
+      (protocol/<unsafe-delete (get-impl) repo))))
+
+(defn <close-db [repo]
+  (when repo
+    (if (electron-runtime?)
+      (if (= repo @remote-repo)
+        (if-let [remote-client @remote-db]
+          (p/let [_ (-> (remote/invoke! (:client remote-client) "thread-api/close-db" false [repo])
+                        (p/catch (fn [_] nil)))
+                  _ (<stop-remote-if-current! repo)]
+            nil)
+          (p/resolved nil))
+        (p/resolved nil))
+      (state/<invoke-db-worker :thread-api/close-db repo))))
 
 (defn <export-db
   [repo opts]
-  (when repo (protocol/<export-db (get-impl) repo opts)))
+  (when repo
+    (protocol/<export-db (get-impl) repo opts)))
 
 (defn <import-db
   [repo data]
-  (when repo (protocol/<import-db (get-impl) repo data)))
+  (when repo
+    (if (electron-runtime?)
+      (p/let [client (<ensure-remote! repo)]
+        (protocol/<import-db client repo data))
+      (protocol/<import-db (get-impl) repo data))))
 
 (defn <fetch-init-data
   ([repo]
    (<fetch-init-data repo {}))
   ([repo opts]
-   (when repo (protocol/<fetch-initial-data (get-impl) repo opts))))
+   (when repo
+     (if (electron-runtime?)
+       (p/let [client (<ensure-remote! repo)]
+         (protocol/<fetch-initial-data client repo opts))
+       (protocol/<fetch-initial-data (get-impl) repo opts)))))
 
 ;; FIXME: limit repo name's length and sanity
 ;; @shuyu Do we still need this?
 (defn <new [repo opts]
   {:pre [(<= (count repo) 128)]}
-  (p/let [_ (protocol/<new (get-impl) repo opts)]
+  (p/let [impl (if (electron-runtime?)
+                 (<ensure-remote! repo)
+                 (p/resolved (get-impl)))
+          _ (protocol/<new impl repo opts)]
     (<export-db repo {})))
 
-;; repo->max-tx
-(defonce *last-synced-graph->tx (atom {}))
-
-(defn- graph-has-changed?
-  [repo]
-  (let [tx (@*last-synced-graph->tx repo)
-        db (db/get-db repo)]
-    (or (nil? tx)
-        (> (:max-tx db) tx))))
-
 (defn export-current-graph!
-  [& {:keys [succ-notification? force-save?]}]
+  [& {:keys [succ-notification?]}]
   (when (util/electron?)
     (when-let [repo (state/get-current-repo)]
-      (when (or force-save? 
-                (and (graph-has-changed? repo)
-                     (state/input-idle? repo :diff 5000)))
-        (println :debug :save-db-to-disk repo)
-        (->
-         (p/do!
-          (<export-db repo {})
-          (swap! *last-synced-graph->tx assoc repo (:max-tx (db/get-db repo)))
-          (when succ-notification?
-            (state/pub-event!
-             [:notification/show {:content "The current db has been saved successfully to the disk."
-                                  :status :success}])))
-         (p/catch (fn [^js error]
-                    (js/console.error error)
-                    (state/pub-event!
-                     [:notification/show {:content (str (.getMessage error))
-                                          :status :error
-                                          :clear? false}]))))))))
-
-(defn run-export-periodically!
-  []
-  (js/setInterval export-current-graph!
-                  ;; every 30 seconds
-                  (* 30 1000)))
+      (log/debug :event :backup-db :graph repo)
+      (->
+       (p/do!
+         (ipc/ipc :db-export repo true)
+         (when succ-notification?
+           (state/pub-event!
+            [:notification/show {:content "DB backup successfully."
+                                 :status :success}])))
+       (p/catch (fn [^js error]
+                  (log/error :event :db-backup-failed :graph repo :error error)
+                  (state/pub-event!
+                   [:notification/show {:content (str (.getMessage error))
+                                        :status :error
+                                        :clear? false}])))))))
diff --git a/src/main/frontend/persist_db/browser.cljs b/src/main/frontend/persist_db/browser.cljs
index eb810d41af..220b0bcf59 100644
--- a/src/main/frontend/persist_db/browser.cljs
+++ b/src/main/frontend/persist_db/browser.cljs
@@ -121,6 +121,9 @@
 
 (defn stop-db-worker!
   []
+  (when @state/*db-worker
+    (-> (state/<invoke-db-worker :thread-api/cancel-ui-requests {:reason :stop-db-worker})
+        (p/catch (constantly nil))))
   (when-let [^js worker @state/*db-worker-thread]
     (set! (.-onmessage worker) nil)
     (.terminate worker))
@@ -180,9 +183,9 @@
                       (log/error :init-sqlite-wasm-error ["Can't init SQLite wasm" error]))))))))
 
 (defn <export-db!
-  [repo data]
+  [repo]
   (when (util/electron?)
-    (ipc/ipc :db-export repo data)))
+    (ipc/ipc :db-export repo false)))
 
 (defn- sqlite-error-handler
   [error]
@@ -211,11 +214,7 @@
     (state/<invoke-db-worker :thread-api/release-access-handles repo))
 
   (<fetch-initial-data [_this repo opts]
-    (-> (p/let [db-exists? (state/<invoke-db-worker :thread-api/db-exists repo)
-                disk-db-data (when-not db-exists? (ipc/ipc :db-get repo))
-                _ (when disk-db-data
-                    (state/<invoke-db-worker-direct-pass :thread-api/import-db repo disk-db-data))
-                _ (state/<invoke-db-worker :thread-api/create-or-open-db repo opts)]
+    (-> (p/let [_ (state/<invoke-db-worker :thread-api/create-or-open-db repo opts)]
           (state/<invoke-db-worker :thread-api/get-initial-data repo opts))
         (p/catch sqlite-error-handler)))
 
@@ -224,13 +223,15 @@
           (when data
             (if (:return-data? opts)
               data
-              (<export-db! repo data))))
+              (<export-db! repo))))
         (p/catch (fn [error]
                    (log/error :export-db-error repo error "SQLiteDB save error")
                    (notification/show! (t :storage/sqlitedb-save-error error) :error) {}))))
 
   (<import-db [_this repo data]
-    (-> (state/<invoke-db-worker-direct-pass :thread-api/import-db repo data)
-        (p/catch (fn [error]
-                   (log/error :import-db-error repo error "SQLiteDB import error")
-                   (notification/show! (t :storage/sqlitedb-import-error error) :error) {})))))
+    (->
+     (p/let [result-str (state/<invoke-db-worker-direct-pass :thread-api/import-db repo data)]
+       (ldb/read-transit-str result-str))
+     (p/catch (fn [error]
+                (log/error :import-db-error repo error "SQLiteDB import error")
+                (notification/show! (t :storage/sqlitedb-import-error error) :error) {})))))
diff --git a/src/main/frontend/persist_db/remote.cljs b/src/main/frontend/persist_db/remote.cljs
new file mode 100644
index 0000000000..c18bfd53a3
--- /dev/null
+++ b/src/main/frontend/persist_db/remote.cljs
@@ -0,0 +1,207 @@
+(ns frontend.persist-db.remote
+  "Remote `PersistentDB` implementation for Electron renderer via db-worker-node HTTP and SSE."
+  (:require [clojure.string :as string]
+            [frontend.persist-db.protocol :as protocol]
+            [logseq.db :as ldb]
+            [promesa.core :as p]
+            [lambdaisland.glogi :as log]
+            [frontend.handler.notification :as notification]
+            [frontend.context.i18n :refer [t]]))
+
+(defn- normalize-base-url
+  [base-url]
+  (string/replace (or base-url "") #"/$" ""))
+
+(defn- invoke-url
+  [base-url]
+  (str (normalize-base-url base-url) "/v1/invoke"))
+
+(defn- events-url
+  [base-url]
+  (str (normalize-base-url base-url) "/v1/events"))
+
+(defn- base-headers
+  [auth-token]
+  (cond-> {"Content-Type" "application/json"
+           "Accept" "application/json"}
+    (seq auth-token)
+    (assoc "Authorization" (str "Bearer " auth-token))))
+
+(defn- parse-response-body
+  [body]
+  (cond
+    (string? body) (js->clj (js/JSON.parse body) :keywordize-keys true)
+    (map? body) body
+    :else {}))
+
+(defn- normalize-code
+  [code]
+  (cond
+    (keyword? code) code
+    (string? code) (keyword code)
+    :else :invoke-failed))
+
+(defn- decode-event
+  [{:keys [type payload]}]
+  (let [decoded (when (some? payload)
+                  (try
+                    (ldb/read-transit-str payload)
+                    (catch :default _
+                      payload)))]
+    (if (and (vector? decoded)
+             (= 2 (count decoded))
+             (keyword? (first decoded)))
+      [(first decoded) (second decoded)]
+      [(when type (keyword type)) decoded])))
+
+(defn- data-line
+  [event-text]
+  (some (fn [line]
+          (when (string/starts-with? line "data: ")
+            (subs line 6)))
+        (string/split-lines event-text)))
+
+(defn create-client
+  [{:keys [fetch-fn open-sse-fn schedule-fn reconnect-delay-ms] :as opts}]
+  (let [default-fetch-fn
+        (fn [{:keys [method url headers body]}]
+          (p/let [^js res (js/fetch url (clj->js (cond-> {:method method
+                                                          :headers (or headers {})}
+                                                   body (assoc :body body))))
+                  text (.text res)]
+            {:status (.-status res)
+             :body text}))
+        default-open-sse-fn
+        (fn [{:keys [url on-message on-error]}]
+          (if (exists? js/EventSource)
+            (let [es (js/EventSource. url)]
+              (set! (.-onmessage es)
+                    (fn [event]
+                      (when on-message
+                        (on-message (str "data: " (.-data event) "\n\n")))))
+              (set! (.-onerror es)
+                    (fn [event]
+                      (when on-error
+                        (on-error event))))
+              {:close! (fn []
+                         (.close es))})
+            {:close! (fn [] nil)}))]
+  (assoc opts
+         :fetch-fn (or fetch-fn default-fetch-fn)
+         :open-sse-fn (or open-sse-fn default-open-sse-fn)
+         :schedule-fn (or schedule-fn (fn [f delay-ms]
+                                        (js/setTimeout f delay-ms)))
+         :reconnect-delay-ms (or reconnect-delay-ms 1000))))
+
+(defn invoke!
+  [{:keys [base-url auth-token fetch-fn]} method direct-pass? args]
+  (let [payload (js/JSON.stringify
+                 (clj->js (if direct-pass?
+                            {:method method
+                             :directPass true
+                             :args args}
+                            {:method method
+                             :directPass false
+                             :argsTransit (ldb/write-transit-str args)})))]
+    (p/let [{:keys [status body]}
+            (fetch-fn {:method "POST"
+                       :url (invoke-url base-url)
+                       :headers (base-headers auth-token)
+                       :body payload})
+            parsed (parse-response-body body)]
+      (if (<= 200 status 299)
+        (if direct-pass?
+          (:result parsed)
+          (ldb/read-transit-str (:resultTransit parsed)))
+        (let [error (:error parsed)]
+          (throw (ex-info (or (:message error) "db-worker invoke failed")
+                          (cond-> {:status status
+                                   :code (normalize-code (:code error))}
+                            error (assoc :error error)))))))))
+
+(defn connect-events!
+  [{:keys [base-url auth-token event-handler open-sse-fn schedule-fn reconnect-delay-ms]} wrapped-worker]
+  (let [connected? (atom true)
+        buffer (atom "")
+        subscription (atom nil)
+        dispatch! (fn [event-str]
+                    (when-let [line (data-line event-str)]
+                      (let [event (parse-response-body line)
+                            [event-type payload] (decode-event event)]
+                        (when (and event-handler event-type)
+                          (event-handler event-type wrapped-worker payload)))))]
+    (letfn [(open! []
+              (when @connected?
+                (reset! subscription
+                        (open-sse-fn
+                         {:url (events-url base-url)
+                          :headers (base-headers auth-token)
+                          :on-message (fn [chunk]
+                                        (when @connected?
+                                          (swap! buffer str chunk)
+                                          (loop []
+                                            (when-let [idx (string/index-of @buffer "\n\n")]
+                                              (let [event-str (subs @buffer 0 idx)
+                                                    next-buffer (subs @buffer (+ idx 2))]
+                                                (reset! buffer next-buffer)
+                                                (dispatch! event-str)
+                                                (recur))))))
+                          :on-error (fn [_error]
+                                      (when @connected?
+                                        (schedule-fn open! reconnect-delay-ms)))}))))]
+      (open!)
+      {:disconnect! (fn []
+                      (reset! connected? false)
+                      (when-let [close! (:close! @subscription)]
+                        (close!))
+                      nil)})))
+
+(defn- method->str
+  [qkw]
+  (str (namespace qkw) "/" (name qkw)))
+
+(defrecord InRemote [client wrapped-worker disconnect!]
+  protocol/PersistentDB
+  (<new [_this repo opts]
+    (invoke! client "thread-api/create-or-open-db" false [repo opts]))
+
+  (<list-db [_this]
+    (invoke! client "thread-api/list-db" false []))
+
+  (<unsafe-delete [_this repo]
+    (invoke! client "thread-api/unsafe-unlink-db" false [repo]))
+
+  (<release-access-handles [_this repo]
+    (invoke! client "thread-api/release-access-handles" false [repo]))
+
+  (<fetch-initial-data [_this repo opts]
+    (p/let [_ (invoke! client "thread-api/create-or-open-db" false [repo opts])]
+      (invoke! client "thread-api/get-initial-data" false [repo opts])))
+
+  (<export-db [_this repo _opts]
+    (invoke! client "thread-api/export-db" true [repo]))
+
+  (<import-db [_this repo data]
+    (->
+     (p/let [result-str (invoke! client "thread-api/import-db" true [repo data])]
+       (ldb/read-transit-str result-str))
+     (p/catch (fn [error]
+                (log/error :import-db-error repo error "SQLiteDB import error")
+                (notification/show! (t :storage/sqlitedb-import-error error) :error) {})))))
+
+(defn start!
+  [{:keys [base-url auth-token event-handler] :as opts}]
+  (let [client (create-client (assoc opts :base-url base-url :auth-token auth-token))
+        wrapped-worker (fn [qkw direct-pass? & args]
+                         (invoke! client (method->str qkw) direct-pass? args))
+        {:keys [disconnect!]} (connect-events! (assoc client
+                                                      :event-handler event-handler
+                                                      :auth-token auth-token)
+                                               wrapped-worker)]
+    (->InRemote client wrapped-worker disconnect!)))
+
+(defn stop!
+  [remote-client]
+  (when-let [disconnect! (:disconnect! remote-client)]
+    (disconnect!))
+  (p/resolved true))
diff --git a/src/main/frontend/util/text.cljs b/src/main/frontend/util/text.cljs
index c9a9135059..7c3255d564 100644
--- a/src/main/frontend/util/text.cljs
+++ b/src/main/frontend/util/text.cljs
@@ -101,4 +101,4 @@
    On iOS, repo-url might be nil"
   [repo-url]
   (when (not-empty repo-url)
-    (string/replace-first repo-url config/db-version-prefix "")))
+    (config/db-graph-name repo-url)))
diff --git a/src/main/frontend/worker/db/validate.cljs b/src/main/frontend/worker/db/validate.cljs
index bec0044d96..5dfc818d6e 100644
--- a/src/main/frontend/worker/db/validate.cljs
+++ b/src/main/frontend/worker/db/validate.cljs
@@ -221,42 +221,42 @@
                  {:fix-db? true})))
 
 (defn validate-db
-  ([conn]
-   (validate-db nil conn nil))
-  ([_repo conn _options]
-   (fix-extends-cardinality! conn)
-   (fix-icon-wrong-type! conn)
-   (db-migrate/ensure-built-in-data-exists! conn)
-   (fix-non-closed-values! conn)
-   (fix-num-prefix-db-idents! conn)
+  [conn & {:keys [fix] :or {fix true}}]
+  (when fix
+    (fix-extends-cardinality! conn)
+    (fix-icon-wrong-type! conn)
+    (db-migrate/ensure-built-in-data-exists! conn)
+    (fix-non-closed-values! conn)
+    (fix-num-prefix-db-idents! conn))
 
-   (let [db @conn
-         {:keys [errors datom-count entities]} (db-validate/validate-db db)
-         invalid-entity-ids (distinct (map (fn [e] (:db/id (:entity e))) errors))]
+  (let [db @conn
+        {:keys [errors datom-count entities]} (db-validate/validate-db db)
+        invalid-entity-ids (distinct (map (fn [e] (:db/id (:entity e))) errors))]
 
-     (doseq [error errors]
-       (prn :debug
-            :entity (:entity error)
-            :error (dissoc error :entity)))
+    (doseq [error errors]
+      (prn :debug
+           :entity (:entity error)
+           :error (dissoc error :entity)))
 
     (if errors
       (do
-        (fix-invalid-blocks! conn errors)
+        (when fix
+          (fix-invalid-blocks! conn errors))
         (shared-service/broadcast-to-clients! :log [:db-invalid :error
                                                     {:msg "Validation errors"
                                                      :errors errors}])
         (shared-service/broadcast-to-clients! :notification
-                                              [nil :warning false nil nil
-                                               {:i18n-key :graph.validation/invalid-blocks-detected
-                                                :i18n-args [(count errors)]}]))
+                                              [(str "Validation detected " (count errors) " invalid block(s). These blocks may be buggy."
+                                                    (when fix
+                                                      " Attempting to fix invalid blocks. Run validation again to see if they were fixed."))
+                                               :warning false]))
 
       (shared-service/broadcast-to-clients! :notification
-                                            [nil :success false nil nil
-                                             {:i18n-key :graph.validation/valid
-                                              :i18n-args [(assoc (db-validate/graph-counts db entities) :datoms datom-count)]}]))
+                                            [(str "Your graph is valid! " (assoc (db-validate/graph-counts db entities) :datoms datom-count))
+                                             :success false]))
     {:errors errors
      :datom-count datom-count
-     :invalid-entity-ids invalid-entity-ids})))
+     :invalid-entity-ids invalid-entity-ids}))
 
 (defn recompute-checksum-diagnostics
   [_repo conn {:keys [local-checksum remote-checksum] :as _sync-diagnostics}]
diff --git a/src/main/frontend/worker/db_core.cljs b/src/main/frontend/worker/db_core.cljs
new file mode 100644
index 0000000000..a04ebf24b6
--- /dev/null
+++ b/src/main/frontend/worker/db_core.cljs
@@ -0,0 +1,1409 @@
+(ns frontend.worker.db-core
+  "Core db-worker logic without host-specific bootstrap."
+  (:require
+   [cljs-bean.core :as bean]
+   [cljs.cache :as cache]
+   [clojure.set]
+   [clojure.string :as string]
+   [datascript.core :as d]
+   [datascript.storage :refer [IStorage] :as storage]
+   [frontend.common.cache :as common.cache]
+   [frontend.common.graph-view :as graph-view]
+   [frontend.common.missionary :as c.m]
+   [frontend.common.thread-api :as thread-api :refer [def-thread-api]]
+   [frontend.worker-common.util :as worker-util]
+   [frontend.worker.db-listener :as db-listener]
+   [frontend.worker.db.fix :as db-fix]
+   [frontend.worker.db.migrate :as db-migrate]
+   [frontend.worker.db.validate :as worker-db-validate]
+   [frontend.worker.export :as worker-export]
+   [frontend.worker.pipeline :as worker-pipeline]
+   [frontend.worker.platform :as platform]
+   [frontend.worker.publish]
+   [frontend.worker.search :as search]
+   [frontend.worker.shared-service :as shared-service]
+   [frontend.worker.state :as worker-state]
+   [frontend.worker.sync :as db-sync]
+   [frontend.worker.sync.client-op :as client-op]
+   [frontend.worker.sync.crypt :as sync-crypt]
+   [frontend.worker.sync.download :as sync-download]
+   [frontend.worker.thread-atom]
+   [frontend.worker.undo-redo :as worker-undo-redo]
+   [goog.functions :as gfun]
+   [lambdaisland.glogi :as log]
+   [logseq.cli.common.db-worker :as cli-db-worker]
+   [logseq.cli.common.mcp.tools :as cli-common-mcp-tools]
+   [logseq.common.graph-dir :as graph-dir]
+   [logseq.common.util :as common-util]
+   [logseq.db :as ldb]
+   [logseq.db.common.initial-data :as common-initial-data]
+   [logseq.db.common.order :as db-order]
+   [logseq.db.common.reference :as db-reference]
+   [logseq.db.common.sqlite :as common-sqlite]
+   [logseq.db.common.view :as db-view]
+   [logseq.db.frontend.class :as db-class]
+   [logseq.db.frontend.entity-util :as entity-util]
+   [logseq.db.frontend.schema :as db-schema]
+   [logseq.db.sqlite.create-graph :as sqlite-create-graph]
+   [logseq.db.sqlite.export :as sqlite-export]
+   [logseq.db.sqlite.gc :as sqlite-gc]
+   [logseq.db.sqlite.util :as sqlite-util]
+   [logseq.outliner.op :as outliner-op]
+   [logseq.outliner.recycle :as outliner-recycle]
+   [me.tonsky.persistent-sorted-set :as set :refer [BTSet]]
+   [missionary.core :as m]
+   [promesa.core :as p]))
+
+(defonce *sqlite worker-state/*sqlite)
+(defonce *sqlite-conns worker-state/*sqlite-conns)
+(defonce *datascript-conns worker-state/*datascript-conns)
+(defonce *client-ops-conns worker-state/*client-ops-conns)
+(defonce *opfs-pools worker-state/*opfs-pools)
+(defonce *publishing? (atom false))
+(defonce ^:private *node-pools (atom {}))
+
+(def search-db-version
+  "Current search index version, stored in PRAGMA user_version.
+  Bump to force a rebuild when the index format changes."
+  1)
+(def ^:private recycle-gc-kv :logseq.kv/recycle-last-gc-at)
+
+(def ^:private search-index-build-batch-size 200)
+(def ^:private search-index-build-time-budget-ms 8)
+(def ^:private search-index-build-idle-status-ttl-ms 2000)
+(def ^:private search-index-build-pause-ms 300)
+(defonce ^:private *search-index-build-ids (atom {}))
+(defonce ^:private *client-ops-cleanup-timers (atom {}))
+(def ^:private client-ops-cleanup-interval-ms (* 3 60 60 1000))
+(def ^:private wal-checkpoint-sql "PRAGMA wal_checkpoint(TRUNCATE)")
+
+
+(defn- node-runtime?
+  []
+  (= :node (platform/env-flag (platform/current) :runtime)))
+
+(defn- storage-pool-name
+  [graph]
+  (if (node-runtime?)
+    (graph-dir/repo->graph-dir-key graph)
+    (worker-util/get-pool-name graph)))
+
+(defn- get-storage-pool
+  [graph]
+  (if (node-runtime?)
+    (or (get @*node-pools graph)
+        (worker-state/get-opfs-pool graph))
+    (worker-state/get-opfs-pool graph)))
+
+(defn- remember-storage-pool!
+  [graph pool]
+  (if (node-runtime?)
+    (swap! *node-pools assoc graph pool)
+    (swap! *opfs-pools assoc graph pool)))
+
+(defn- forget-storage-pool!
+  [graph]
+  (if (node-runtime?)
+    (do
+      (swap! *node-pools dissoc graph)
+      (swap! *opfs-pools dissoc graph))
+    (swap! *opfs-pools dissoc graph)))
+
+(defn- <get-opfs-pool
+  [graph]
+  (when-not @*publishing?
+    (or (get-storage-pool graph)
+        (p/let [storage (platform/storage (platform/current))
+                ^js pool ((:install-opfs-pool storage) @*sqlite (storage-pool-name graph))]
+          (remember-storage-pool! graph pool)
+          pool))))
+
+(defn- init-sqlite-module!
+  []
+  (when-not @*sqlite
+    (p/let [publishing? (platform/env-flag (platform/current) :publishing?)
+            sqlite (platform/sqlite-init! (platform/current))]
+      (reset! *publishing? publishing?)
+      (reset! *sqlite (or sqlite ::sqlite-initialized))
+      nil)))
+
+(def repo-path "/db.sqlite")
+(def client-ops-repo-path (str "client-ops" repo-path))
+
+(defn- resolve-db-path
+  [repo pool path]
+  (let [storage (platform/storage (platform/current))]
+    (if-let [f (:resolve-db-path storage)]
+      (f repo pool path)
+      path)))
+
+(defn- checkpoint-db!
+  ([^Object db]
+   (checkpoint-db! nil db))
+  ([repo ^Object db]
+   (when (and db (fn? (.-exec db)))
+     (try
+       (.exec db wal-checkpoint-sql)
+       (catch :default e
+         (log/warn :db-worker/wal-checkpoint-failed
+                   (cond-> {:error e}
+                     repo (assoc :repo repo))))))))
+
+(defn- <export-db-file
+  ([repo]
+   (<export-db-file repo repo-path))
+  ([repo path]
+   (p/let [^js pool (<get-opfs-pool repo)]
+     (when pool
+       (let [storage (platform/storage (platform/current))]
+         ((:export-file storage) pool path))))))
+
+(defn- ->uint8array
+  [data]
+  (cond
+    (instance? js/Uint8Array data)
+    data
+
+    (js/ArrayBuffer.isView data)
+    (js/Uint8Array. (.-buffer data) (.-byteOffset data) (.-byteLength data))
+
+    (instance? js/ArrayBuffer data)
+    (js/Uint8Array. data)
+
+    (array? data)
+    (js/Uint8Array. data)
+
+    :else
+    data))
+
+(defn- <export-db-file-with-paths
+  [repo path-candidates]
+  (let [paths (->> path-candidates
+                   (filter string?)
+                   (remove string/blank?)
+                   distinct
+                   vec)]
+    (letfn [(try-export [remaining-paths]
+              (if-let [path (first remaining-paths)]
+                (-> (<export-db-file repo path)
+                    (p/then (fn [result]
+                              (let [payload (->uint8array result)]
+                                (if (instance? js/Uint8Array payload)
+                                  payload
+                                  (try-export (subvec remaining-paths 1))))))
+                    (p/catch (fn [_]
+                               (try-export (subvec remaining-paths 1)))))
+                (p/resolved nil)))]
+      (try-export paths))))
+
+(defn- <import-db
+  [^js pool data]
+  (let [storage (platform/storage (platform/current))]
+    ((:import-db storage) pool repo-path data)))
+
+(def ^:private sqlite-file-header "SQLite format 3\u0000")
+
+(defn- require-sqlite-payload
+  [repo data]
+  (let [payload (->uint8array data)]
+    (when-not (and (instance? js/Uint8Array payload)
+                   (>= (.-byteLength payload) (count sqlite-file-header))
+                   (= sqlite-file-header
+                      (.decode (js/TextDecoder.) (.subarray payload 0 (count sqlite-file-header)))))
+      (throw (ex-info "invalid sqlite import data"
+                      {:code :invalid-sqlite-import-data
+                       :repo repo})))
+    payload))
+
+(defn upsert-addr-content!
+  "Upsert addr+data-seq. Update sqlite-cli/upsert-addr-content! when making changes"
+  [db data]
+  (assert (some? db) "sqlite db not exists")
+  (.transaction
+   db
+   (fn [tx]
+     (doseq [item data]
+       (.exec tx #js {:sql "INSERT INTO kvs (addr, content, addresses) values ($addr, $content, $addresses) on conflict(addr) do update set content = $content, addresses = $addresses"
+                      :bind item})))))
+
+(defn restore-data-from-addr
+  "Update sqlite-cli/restore-data-from-addr when making changes"
+  [db addr]
+  (assert (some? db) "sqlite db not exists")
+  (when-let [result (-> (.exec db #js {:sql "select content, addresses from kvs where addr = ?"
+                                       :bind #js [addr]
+                                       :rowMode "array"})
+                        first)]
+    (let [[content addresses] (bean/->clj result)
+          addresses (when addresses
+                      (js/JSON.parse addresses))
+          data (sqlite-util/read-transit-str content)]
+      (if (and addresses (map? data))
+        (assoc data :addresses addresses)
+        data))))
+
+(defn new-sqlite-storage
+  "Update sqlite-cli/new-sqlite-storage when making changes"
+  [^Object db]
+  (reify IStorage
+    (-store [_ addr+data-seq _delete-addrs]
+      (let [data (map
+                  (fn [[addr data]]
+                    (let [data' (if (map? data) (dissoc data :addresses) data)
+                          addresses (when (map? data)
+                                      (when-let [addresses (:addresses data)]
+                                        (js/JSON.stringify (bean/->js addresses))))]
+                      #js {:$addr addr
+                           :$content (sqlite-util/write-transit-str data')
+                           :$addresses addresses}))
+                  addr+data-seq)]
+        (upsert-addr-content! db data)))
+
+    (-restore [_ addr]
+      (restore-data-from-addr db addr))))
+
+(defn- close-db-aux!
+  [repo ^Object db ^Object search ^Object client-ops]
+  (checkpoint-db! repo db)
+  (checkpoint-db! repo search)
+  (checkpoint-db! repo client-ops)
+  (sync-download/close-import-state-for-repo! repo)
+  (when-let [timer (get @*client-ops-cleanup-timers repo)]
+    (js/clearInterval timer))
+  (swap! *client-ops-cleanup-timers dissoc repo)
+  (swap! *sqlite-conns dissoc repo)
+  (swap! *datascript-conns dissoc repo)
+  (swap! *client-ops-conns dissoc repo)
+  (swap! client-op/*repo->pending-local-tx-count dissoc repo)
+  (swap! *search-index-build-ids dissoc repo)
+  (search/clear-fuzzy-search-indice! repo)
+  (when db (.close db))
+  (when search (.close search))
+  (when client-ops (.close client-ops))
+  (when-let [^js pool (get-storage-pool repo)]
+    (when (exists? (.-pauseVfs pool))
+      (.pauseVfs pool)))
+  (forget-storage-pool! repo))
+
+(defn- close-other-dbs!
+  [repo]
+  (doseq [[r {:keys [db search client-ops]}] @*sqlite-conns]
+    (when-not (= repo r)
+      (close-db-aux! r db search client-ops))))
+
+(defn close-db!
+  [repo]
+  (let [{:keys [db search client-ops]} (get @*sqlite-conns repo)]
+    (close-db-aux! repo db search client-ops)))
+
+(defn- <invalidate-search-db!
+  [repo]
+  (if-let [search-db (worker-state/get-sqlite-conn repo :search)]
+    (do
+      (search/truncate-table! search-db)
+      (p/resolved nil))
+    (when-not @*publishing?
+      (p/let [pool (<get-opfs-pool repo)
+              search-path (resolve-db-path repo pool (str "search" repo-path))
+              search-db (platform/sqlite-open (platform/current)
+                                              {:sqlite @*sqlite
+                                               :pool pool
+                                               :path search-path
+                                               :mode "c"})]
+        (try
+          (search/truncate-table! search-db)
+          (finally
+            (.close search-db)))
+        nil))))
+
+(defn reset-db!
+  [repo db-transit-str]
+  (when-let [conn (get @*datascript-conns repo)]
+    (let [new-db (ldb/read-transit-str db-transit-str)
+          new-db' (update new-db :eavt (fn [^BTSet s]
+                                         (set! (.-storage s) (.-storage (:eavt @conn)))
+                                         s))]
+      (d/reset-conn! conn new-db' {:reset-conn! true})
+      (d/reset-schema! conn (:schema new-db)))))
+
+(defn- get-dbs
+  [repo]
+  (if @*publishing?
+    (p/let [db (platform/sqlite-open (platform/current)
+                                     {:sqlite @*sqlite
+                                      :path "/db.sqlite"
+                                      :mode "c"})
+            search-db (platform/sqlite-open (platform/current)
+                                            {:sqlite @*sqlite
+                                             :path "/search-db.sqlite"
+                                             :mode "c"})]
+      [db search-db])
+    (p/let [^js pool (<get-opfs-pool repo)
+            capacity (when (exists? (.-getCapacity pool))
+                       (.getCapacity pool))
+            _ (when (and (some? capacity) (zero? capacity))
+                (.unpauseVfs pool))
+            db-path (resolve-db-path repo pool repo-path)
+            search-path (resolve-db-path repo pool (str "search" repo-path))
+            client-ops-path (resolve-db-path repo pool (str "client-ops-" repo-path))
+            _ (log/info :db-worker/get-dbs-open {:repo repo :db-path db-path})
+            db (platform/sqlite-open (platform/current)
+                                     {:sqlite @*sqlite
+                                      :pool pool
+                                      :path db-path})
+            _ (log/info :db-worker/get-dbs-open {:repo repo :search-path search-path})
+            search-db (platform/sqlite-open (platform/current)
+                                            {:sqlite @*sqlite
+                                             :pool pool
+                                             :path search-path})
+            _ (log/info :db-worker/get-dbs-open {:repo repo :client-ops-path client-ops-path})
+            client-ops-db (platform/sqlite-open (platform/current)
+                                                {:sqlite @*sqlite
+                                                 :pool pool
+                                                 :path client-ops-path})]
+      [db search-db client-ops-db])))
+
+(defn- enable-sqlite-wal-mode!
+  [^Object db]
+  (.exec db "PRAGMA locking_mode=exclusive")
+  (.exec db "PRAGMA journal_mode=WAL"))
+
+(defn- gc-sqlite-dbs!
+  "Gc main db weekly and rtc ops db each time when opening it"
+  [sqlite-db client-ops-db datascript-conn {:keys [full-gc?]}]
+  (let [last-gc-at (:kv/value (d/entity @datascript-conn :logseq.kv/graph-last-gc-at))]
+    (when (or full-gc?
+              (nil? last-gc-at)
+              (not (number? last-gc-at))
+              (> (- (common-util/time-ms) last-gc-at) (* 30 24 3600 1000))) ; 1 month ago
+      (log/info :gc-sqlite-dbs "gc current graph")
+      (doseq [db (if @*publishing? [sqlite-db] [sqlite-db client-ops-db])]
+        (sqlite-gc/gc-kvs-table! db {:full-gc? full-gc?})
+        (.exec db "VACUUM"))
+      (ldb/transact! datascript-conn [{:db/ident :logseq.kv/graph-last-gc-at
+                                       :kv/value (common-util/time-ms)}]
+        {:skip-validate-db? true
+         :persist-op? false}))))
+
+(defn- run-client-ops-cleanup!
+  [repo]
+  (let [protected-tx-ids (worker-undo-redo/referenced-history-tx-ids repo)]
+    (client-op/cleanup-finished-history-ops! repo protected-tx-ids)
+    nil))
+
+(defn- ensure-client-ops-cleanup-timer!
+  [repo]
+  (when (and (not @*publishing?)
+             repo
+             (nil? (get @*client-ops-cleanup-timers repo)))
+    (let [timer (js/setInterval (fn []
+                                  (run-client-ops-cleanup! repo))
+                                client-ops-cleanup-interval-ms)]
+      (swap! *client-ops-cleanup-timers assoc repo timer))
+    nil))
+
+(defn- maybe-run-recycle-gc!
+  [conn]
+  (let [now (common-util/time-ms)
+        last-gc-at (:kv/value (d/entity @conn recycle-gc-kv))]
+    (when (or (not (number? last-gc-at))
+              (> (- now last-gc-at) outliner-recycle/gc-interval-ms))
+      (outliner-recycle/gc! conn {:now-ms now})
+      (ldb/transact! conn [{:db/ident recycle-gc-kv
+                            :kv/value now}]
+                     {:persist-op? false
+                      :skip-validate-db? true}))))
+
+(defn- <create-or-open-db!
+  [repo {:keys [config datoms sync-download-graph?] :as opts}]
+  (when-not (worker-state/get-sqlite-conn repo)
+    (p/let [[db search-db client-ops-db :as dbs] (get-dbs repo)
+            storage (new-sqlite-storage db)]
+      (swap! *sqlite-conns assoc repo {:db db
+                                       :search search-db
+                                       :client-ops client-ops-db})
+      (doseq [db' dbs]
+        (enable-sqlite-wal-mode! db'))
+      (common-sqlite/create-kvs-table! db)
+      (when-not @*publishing? (common-sqlite/create-kvs-table! client-ops-db))
+      (search/create-tables-and-triggers! search-db)
+      (ldb/register-transact-pipeline-fn! worker-pipeline/transact-pipeline)
+      (ldb/register-debounce-fn! (gfun/debounce d/store 1000))
+      (let [conn (common-sqlite/get-storage-conn storage db-schema/schema)
+            _ (db-fix/check-and-fix-schema! conn)
+            _ (when datoms
+                (let [ident-eids (into #{}
+                                       (comp (filter (fn [datom]
+                                                       (= (:a datom) :db/ident)))
+                                             (map :e))
+                                       datoms)
+                      to-tx (fn [d] [:db/add (:e d) (:a d) (:v d)])
+                      batch-size 20000
+                      ident-batches (->> datoms
+                                         (filter #(contains? ident-eids (:e %)))
+                                         (map to-tx)
+                                         (partition-all batch-size))
+                      _ (doseq [batch ident-batches]
+                          (d/transact! conn batch {:initial-db? true}))
+                      non-ident-batches (->> datoms
+                                             (remove #(contains? ident-eids (:e %)))
+                                             (map to-tx)
+                                             (partition-all batch-size))]
+                  (doseq [batch non-ident-batches]
+                    (d/transact! conn batch {:initial-db? true}))))
+            client-ops-conn (when-not @*publishing? client-ops-db)
+            initial-data-exists? (when (nil? datoms)
+                                   (and (d/entity @conn :logseq.class/Root)
+                                        (= "db" (:kv/value (d/entity @conn :logseq.kv/db-type)))))]
+        (swap! *datascript-conns assoc repo conn)
+        (swap! *client-ops-conns assoc repo client-ops-conn)
+        (when-not @*publishing?
+          (client-op/ensure-sqlite-schema! client-ops-db))
+        (ensure-client-ops-cleanup-timer! repo)
+        (when (nil? (client-op/get-local-tx repo))
+          (client-op/update-local-tx repo 0))
+        (let [initial-tx-report (when-not (or initial-data-exists?
+                                              (seq datoms)
+                                              sync-download-graph?)
+                                  (let [config (or config "")
+                                        initial-data (sqlite-create-graph/build-db-initial-data
+                                                      config (select-keys opts [:import-type :graph-git-sha :remote-graph?]))]
+                                    (ldb/transact! conn initial-data
+                                                   {:initial-db? true})))]
+          (when-not sync-download-graph?
+            (db-migrate/migrate conn)
+            (gc-sqlite-dbs! db client-ops-db conn {})
+            (maybe-run-recycle-gc! conn))
+
+          (when initial-tx-report
+            (db-sync/handle-local-tx! repo initial-tx-report))
+
+          (db-listener/listen-db-changes! repo (get @*datascript-conns repo))
+
+          nil)))))
+
+(defn- <list-all-dbs
+  []
+  (p/let [storage (platform/storage (platform/current))
+          graph-names ((:list-graphs storage))]
+    (p/all (map (fn [graph-name]
+                  (p/let [repo (str sqlite-util/db-version-prefix graph-name)]
+                    {:name repo}))
+                graph-names))))
+
+(def-thread-api :thread-api/list-db
+  []
+  (<list-all-dbs))
+
+(defn- <db-exists?
+  [graph]
+  (let [storage (platform/storage (platform/current))]
+    ((:db-exists? storage) graph)))
+
+(defn- remove-vfs!
+  [^js pool]
+  (when pool
+    (let [storage (platform/storage (platform/current))]
+      ((:remove-vfs! storage) pool))))
+
+(defn- get-search-db
+  [repo]
+  (worker-state/get-sqlite-conn repo :search))
+
+(defn- search-index-version
+  [^js search-db]
+  (aget (aget (.exec search-db #js {:sql "PRAGMA user_version" :rowMode "array"}) 0) 0))
+
+(defn- start-search-index-build!
+  [repo]
+  (let [build-id (str (random-uuid))]
+    (swap! *search-index-build-ids assoc repo build-id)
+    build-id))
+
+(defn- clear-search-index-build!
+  [repo build-id]
+  (swap! *search-index-build-ids
+         (fn [builds]
+           (if (= build-id (get builds repo))
+             (dissoc builds repo)
+             builds))))
+
+(defn- ensure-active-search-index-build!
+  [repo build-id]
+  (when-not (= build-id (get @*search-index-build-ids repo))
+    (throw (ex-info "stale search index build"
+                    {:type :search/stale-index-build
+                     :repo repo
+                     :build-id build-id}))))
+
+(defn- report-search-index-progress!
+  [repo payload]
+  (-> (worker-state/<invoke-main-thread :thread-api/search-index-build-progress repo payload)
+      (p/catch (fn [_error] nil))))
+
+(def-thread-api :thread-api/init
+  []
+  (init-sqlite-module!))
+
+(def-thread-api :thread-api/set-db-sync-config
+  [config]
+  (reset! worker-state/*db-sync-config (worker-state/non-auth-db-sync-config config))
+  nil)
+
+(def-thread-api :thread-api/get-db-sync-config
+  []
+  (worker-state/non-auth-db-sync-config @worker-state/*db-sync-config))
+
+(def-thread-api :thread-api/db-sync-status
+  [repo]
+  (db-sync/status repo))
+
+(def-thread-api :thread-api/db-sync-start
+  [repo]
+  (db-sync/start! repo))
+
+(def-thread-api :thread-api/db-sync-stop
+  []
+  (db-sync/stop!))
+
+(def-thread-api :thread-api/db-sync-update-presence
+  [editing-block-uuid]
+  (db-sync/update-presence! editing-block-uuid))
+
+(def-thread-api :thread-api/db-sync-request-asset-download
+  [repo asset-uuid]
+  (db-sync/request-asset-download! repo asset-uuid))
+
+(def-thread-api :thread-api/db-sync-grant-graph-access
+  [repo graph-id target-email]
+  (sync-crypt/<grant-graph-access! repo graph-id target-email))
+
+(def-thread-api :thread-api/db-sync-ensure-user-rsa-keys
+  [& [opts]]
+  (sync-crypt/ensure-user-rsa-keys! opts))
+
+(def-thread-api :thread-api/db-sync-list-remote-graphs
+  []
+  (db-sync/list-remote-graphs!))
+
+(def-thread-api :thread-api/db-sync-upload-graph
+  [repo]
+  (db-sync/upload-graph! repo))
+
+(def-thread-api :thread-api/db-sync-create-remote-graph
+  [repo graph-e2ee? graph-ready-for-use?]
+  (db-sync/create-remote-graph! repo {:graph-e2ee? graph-e2ee?
+                                      :graph-ready-for-use? graph-ready-for-use?}))
+
+(def-thread-api :thread-api/db-sync-stop-upload
+  [repo]
+  (db-sync/stop-upload! repo))
+
+(def-thread-api :thread-api/db-sync-resume-upload
+  [repo]
+  (db-sync/resume-upload! repo))
+
+(def-thread-api :thread-api/db-sync-upload-stopped?
+  [repo]
+  (db-sync/upload-stopped? repo))
+
+(def-thread-api :thread-api/db-sync-download-graph-by-id
+  [repo graph-id graph-e2ee?]
+  (sync-download/download-graph-by-id! repo graph-id graph-e2ee?))
+
+;; [graph service]
+(defonce *service (atom []))
+
+(defonce fns {"remoteInvoke" thread-api/remote-function})
+
+(defn- start-db!
+  [repo {:keys [close-other-db?]
+         :or {close-other-db? true}
+         :as opts}]
+  (p/do!
+   (when close-other-db?
+     (close-other-dbs! repo))
+   (when @shared-service/*master-client?
+     (<create-or-open-db! repo (dissoc opts :close-other-db?)))
+   nil))
+
+(def-thread-api :thread-api/create-or-open-db
+  [repo opts]
+  (when-not (= repo (worker-state/get-current-repo)) ; graph switched
+    (reset! worker-state/*deleted-block-uuid->db-id {}))
+  (start-db! repo opts))
+
+(def-thread-api :thread-api/q
+  [repo inputs]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (apply d/q (first inputs) @conn (rest inputs))))
+
+(def-thread-api :thread-api/datoms
+  [repo & args]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (let [result (apply d/datoms @conn args)]
+      (map (fn [d] [(:e d) (:a d) (:v d) (:tx d) (:added d)]) result))))
+
+(def-thread-api :thread-api/pull
+  [repo selector id]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (let [eid (if (and (vector? id) (= :block/name (first id)))
+                (:db/id (ldb/get-page @conn (second id)))
+                id)]
+      (some->> eid
+               (d/pull @conn selector)
+               (common-initial-data/with-parent @conn)))))
+
+(def ^:private *get-blocks-cache (volatile! (cache/lru-cache-factory {} :threshold 1000)))
+(def ^:private get-blocks-with-cache
+  (common.cache/cache-fn
+   *get-blocks-cache
+   (fn [repo requests]
+     (let [db (some-> (worker-state/get-datascript-conn repo) deref)]
+       [[repo (:max-tx db) requests]
+        [db requests]]))
+   (fn [db requests]
+     (when db
+       (->> requests
+            (mapv (fn [{:keys [id opts]}]
+                    (let [id' (if (and (string? id) (common-util/uuid-string? id)) (uuid id) id)]
+                      (-> (common-initial-data/get-block-and-children db id' opts)
+                          (assoc :id id)))))
+            ldb/write-transit-str)))))
+
+(def-thread-api :thread-api/get-blocks
+  [repo requests]
+  (let [requests (ldb/read-transit-str requests)]
+    (get-blocks-with-cache repo requests)))
+
+(def-thread-api :thread-api/get-block-refs
+  [repo id]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (->> (db-reference/get-linked-references @conn id)
+         :ref-blocks
+         (map (fn [b] (assoc (into {} b) :db/id (:db/id b)))))))
+
+(def-thread-api :thread-api/get-block-refs-count
+  [repo id]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (ldb/get-block-refs-count @conn id)))
+
+(def-thread-api :thread-api/get-block-source
+  [repo id]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (:db/id (first (:block/_alias (d/entity @conn id))))))
+
+(defn- search-blocks
+  [repo q option]
+  (let [search-db (get-search-db repo)
+        conn (worker-state/get-datascript-conn repo)]
+    (search/search-blocks repo conn search-db q option)))
+
+(def-thread-api :thread-api/block-refs-check
+  [repo id {:keys [unlinked?]}]
+  (m/sp
+    (when-let [conn (worker-state/get-datascript-conn repo)]
+      (let [db @conn
+            block (d/entity db id)]
+        (if unlinked?
+          (let [title (string/lower-case (:block/title block))
+                result (m/? (search-blocks repo title {:limit 100}))]
+            (boolean (some (fn [b]
+                             (let [block (d/entity db (:db/id b))]
+                               (and (not= id (:db/id block))
+                                    (not ((set (map :db/id (:block/refs block))) id))
+                                    (string/includes? (string/lower-case (:block/title block)) title)))) result)))
+          (some? (first (common-initial-data/get-block-refs db (:db/id block)))))))))
+
+(def-thread-api :thread-api/get-block-parents
+  [repo id depth]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (let [block-id (:block/uuid (d/entity @conn id))]
+      (->> (ldb/get-block-parents @conn block-id {:depth (or depth 3)})
+           (map (fn [b] (d/pull @conn '[*] (:db/id b))))))))
+
+(def-thread-api :thread-api/set-context
+  [context]
+  (when context (worker-state/update-context! context))
+  nil)
+
+(def-thread-api :thread-api/transact
+  [repo tx-data tx-meta context]
+  (assert (some? repo))
+  (worker-state/set-db-latest-tx-time! repo)
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (assert (some? conn) {:repo repo})
+    (try
+      (let [tx-data' (if (contains? #{:insert-blocks} (:outliner-op tx-meta))
+                       (map (fn [m]
+                              (if (and (map? m) (nil? (:block/order m)))
+                                (assoc m :block/order (db-order/gen-key nil))
+                                m)) tx-data)
+                       tx-data)
+            _ (when context (worker-state/set-context! context))
+            tx-meta' (cond-> tx-meta
+                       true
+                       (dissoc :insert-blocks?))]
+        (when-not (and (:create-today-journal? tx-meta)
+                       (:today-journal-name tx-meta)
+                       (seq tx-data')
+                       (ldb/get-page @conn (:today-journal-name tx-meta))) ; today journal created already
+
+          ;; (prn :debug :transact :tx-data tx-data' :tx-meta tx-meta')
+
+          (worker-util/profile "Worker db transact"
+                               (ldb/transact! conn tx-data' tx-meta')))
+        (maybe-run-recycle-gc! conn)
+        nil)
+      (catch :default e
+        (prn :debug :worker-transact-failed :tx-meta tx-meta :tx-data tx-data)
+        (log/error ::worker-transact-failed e)
+        (throw e)))))
+
+(def-thread-api :thread-api/undo-redo-set-pending-editor-info
+  [repo editor-info]
+  (worker-undo-redo/set-pending-editor-info! repo editor-info)
+  nil)
+
+(def-thread-api :thread-api/undo-redo-record-editor-info
+  [repo editor-info]
+  (worker-undo-redo/record-editor-info! repo editor-info)
+  nil)
+
+(def-thread-api :thread-api/undo-redo-record-ui-state
+  [repo ui-state-str]
+  (worker-undo-redo/record-ui-state! repo ui-state-str)
+  nil)
+
+(def-thread-api :thread-api/undo-redo-undo
+  [repo]
+  (worker-undo-redo/undo repo))
+
+(def-thread-api :thread-api/undo-redo-redo
+  [repo]
+  (worker-undo-redo/redo repo))
+
+(def-thread-api :thread-api/undo-redo-clear-history
+  [repo]
+  (worker-undo-redo/clear-history! repo)
+  nil)
+
+(def-thread-api :thread-api/undo-redo-get-debug-state
+  [repo]
+  (worker-undo-redo/get-debug-state repo))
+
+(def-thread-api :thread-api/get-initial-data
+  [repo opts]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (if (:file-graph-import? opts)
+      {:schema (:schema @conn)
+       :initial-data (vec (d/datoms @conn :eavt))}
+      (common-initial-data/get-initial-data @conn))))
+
+(def-thread-api :thread-api/reset-db
+  [repo db-transit]
+  (reset-db! repo db-transit)
+  nil)
+
+(def-thread-api :thread-api/unsafe-unlink-db
+  [repo]
+  (p/let [pool (<get-opfs-pool repo)
+          _ (sync-crypt/cancel-ui-requests! {:reason :unsafe-unlink-db
+                                             :repo repo})
+          _ (close-db! repo)
+          _result (remove-vfs! pool)]
+    nil))
+
+(def-thread-api :thread-api/close-db
+  [repo]
+  (sync-crypt/cancel-ui-requests! {:reason :close-db
+                                   :repo repo})
+  (close-db! repo)
+  nil)
+
+(def-thread-api :thread-api/db-sync-close-db
+  [repo]
+  (sync-crypt/cancel-ui-requests! {:reason :db-sync-close-db
+                                   :repo repo})
+  (close-db! repo))
+
+(def-thread-api :thread-api/db-sync-invalidate-search-db
+  [repo]
+  (<invalidate-search-db! repo))
+
+(def-thread-api :thread-api/db-sync-recreate-lock
+  [repo]
+  (if-let [recreate-lock-fn (get-in (platform/current) [:env :recreate-lock-fn])]
+    (recreate-lock-fn repo)
+    nil))
+
+(def-thread-api :thread-api/db-sync-rehydrate-large-titles
+  [repo graph-id]
+  (db-sync/rehydrate-large-titles-from-db! repo graph-id))
+
+(def-thread-api :thread-api/db-sync-import-prepare
+  [repo reset? graph-id graph-e2ee? & [total-datoms]]
+  (sync-download/prepare-import! repo reset? graph-id graph-e2ee? total-datoms))
+
+(def-thread-api :thread-api/db-sync-import-rows-chunk
+  [rows graph-id import-id]
+  (sync-download/import-rows-chunk! rows graph-id import-id))
+
+(def-thread-api :thread-api/db-sync-import-finalize
+  [repo graph-id remote-tx import-id]
+  (sync-download/finalize-import! repo graph-id remote-tx import-id))
+
+(def-thread-api :thread-api/release-access-handles
+  [repo]
+  (sync-download/close-import-state-for-repo! repo)
+  (when-let [^js pool (get-storage-pool repo)]
+    (when (exists? (.-pauseVfs pool))
+      (.pauseVfs pool))
+    nil))
+
+(def-thread-api :thread-api/db-exists
+  [repo]
+  (<db-exists? repo))
+
+(def-thread-api :thread-api/export-db
+  [repo]
+  (when-let [^js db (worker-state/get-sqlite-conn repo :db)]
+    (checkpoint-db! repo db))
+  (p/let [data (<export-db-file repo)]
+    (platform/transfer (platform/current) data #js [(.-buffer data)])))
+
+(def-thread-api :thread-api/export-client-ops-db
+  [repo]
+  (when-let [^js db (worker-state/get-sqlite-conn repo :client-ops)]
+    (checkpoint-db! repo db))
+  (let [^js client-ops-db (worker-state/get-sqlite-conn repo :client-ops)
+        ^js pool (get-storage-pool repo)
+        db-filename (some-> client-ops-db .-filename)
+        resolved-client-ops-path (when pool
+                                   (resolve-db-path repo pool (str "client-ops-" repo-path)))
+        export-paths [db-filename
+                      resolved-client-ops-path
+                      client-ops-repo-path
+                      (str "/" client-ops-repo-path)
+                      (str "client-ops" repo-path)
+                      (str "/client-ops" repo-path)
+                      (str "client-ops-" repo-path)]]
+    (p/let [payload (<export-db-file-with-paths repo export-paths)]
+      (when (instance? js/Uint8Array payload)
+        (platform/transfer (platform/current) payload #js [(.-buffer payload)])))))
+
+(def-thread-api :thread-api/export-db-base64
+  [repo]
+  (when-let [^js db (worker-state/get-sqlite-conn repo :db)]
+    (checkpoint-db! repo db))
+  (p/let [data (<export-db-file repo)]
+    (when data
+      (let [buffer (if (instance? js/Buffer data)
+                     data
+                     (js/Buffer.from data))]
+        (.toString buffer "base64")))))
+
+(def-thread-api :thread-api/backup-db-sqlite
+  [repo dst-path]
+  (when-not (string/blank? repo)
+    (let [db (worker-state/get-sqlite-conn repo :db)
+          backup-db-fn (get-in (platform/current) [:sqlite :backup-db])]
+      (when-not db
+        (throw (ex-info "graph not opened" {:code :graph-not-opened
+                                            :repo repo})))
+      (when-not (fn? backup-db-fn)
+        (throw (ex-info "platform sqlite backup not supported"
+                        {:code :backup-not-supported
+                         :repo repo})))
+      (checkpoint-db! repo db)
+      (p/let [_ (backup-db-fn db dst-path)]
+        {:path dst-path}))))
+
+(def-thread-api :thread-api/import-db
+  [repo data]
+  (when-not (string/blank? repo)
+    (p/let [pool (<get-opfs-pool repo)
+            payload (require-sqlite-payload repo data)]
+      (<import-db pool payload)
+      nil)))
+
+(def-thread-api :thread-api/import-db-base64
+  [repo base64]
+  (when-not (string/blank? repo)
+    (p/let [pool (<get-opfs-pool repo)
+            data (require-sqlite-payload repo (js/Buffer.from base64 "base64"))
+            _ (close-db! repo)
+            _ (<import-db pool data)
+            _ (start-db! repo {:import-type :sqlite-db})]
+      nil)))
+
+(def-thread-api :thread-api/search-blocks
+  [repo q option]
+  (search-blocks repo q option))
+
+(def-thread-api :thread-api/search-upsert-blocks
+  [repo blocks]
+  (when-let [db (get-search-db repo)]
+    (search/upsert-blocks! db (bean/->js blocks))
+    nil))
+
+(def-thread-api :thread-api/search-delete-blocks
+  [repo ids]
+  (when-let [db (get-search-db repo)]
+    (search/delete-blocks! db ids)
+    nil))
+
+(def-thread-api :thread-api/search-truncate-tables
+  [repo]
+  (when-let [db (get-search-db repo)]
+    (search/truncate-table! db)
+    nil))
+
+(def-thread-api :thread-api/search-build-blocks-indice
+  [repo]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (search/build-blocks-indice repo @conn)))
+
+(defn- take-block-datoms-batch
+  [datoms batch-size time-budget-ms]
+  (let [deadline (+ (common-util/time-ms) time-budget-ms)]
+    (loop [batch (transient [])
+           remaining (seq datoms)
+           n 0]
+      (if (or (nil? remaining)
+              (>= n batch-size)
+              (and (pos? n) (>= (common-util/time-ms) deadline)))
+        [(persistent! batch) remaining]
+        (recur (conj! batch (first remaining))
+               (next remaining)
+               (inc n))))))
+
+(defn- search-index-input-idle?
+  [repo]
+  (if (node-runtime?)
+    true
+    (let [status-map @(:thread-atom/search-input-idle-status @worker-state/*state)
+          {:keys [idle? ts]} (get status-map repo)
+          fresh? (and (number? ts)
+                      (<= (- (common-util/time-ms) ts)
+                          search-index-build-idle-status-ttl-ms))]
+      (if (and fresh? (boolean? idle?))
+        idle?
+        true))))
+
+(defn- <wait-for-search-index-idle!
+  [repo build-id]
+  (p/loop []
+    (ensure-active-search-index-build! repo build-id)
+    (if (search-index-input-idle? repo)
+      nil
+      (p/let [_ (js/Promise. (fn [resolve] (js/setTimeout resolve search-index-build-pause-ms)))]
+        (p/recur)))))
+
+(defn- <build-blocks-fts!
+  "Build FTS index in batches with yielding. Sets user_version to search-db-version on completion."
+  [repo search-db conn build-id]
+  (ensure-active-search-index-build! repo build-id)
+  (search/truncate-table! search-db)
+  (let [db @conn
+        datoms (d/datoms db :avet :block/uuid)
+        total (count datoms)]
+    (p/do!
+     (report-search-index-progress! repo {:build-id build-id
+                                          :status :running
+                                          :progress 0
+                                          :processed 0
+                                          :total total})
+     (<wait-for-search-index-idle! repo build-id)
+     (p/loop [remaining (seq datoms)
+              processed 0
+              last-progress 0]
+       (ensure-active-search-index-build! repo build-id)
+       (if (seq remaining)
+         (let [[batch remaining'] (take-block-datoms-batch remaining
+                                                           search-index-build-batch-size
+                                                           search-index-build-time-budget-ms)
+               processed' (+ processed (count batch))
+               indexed (->> batch
+                            (keep #(d/entity db (:e %)))
+                            (remove search/hidden-entity?)
+                            (keep search/block->index))
+               progress (if (zero? total)
+                          100
+                          (min 100 (int (* 100 (/ processed' total)))))
+               should-report? (> progress last-progress)]
+           (when (seq indexed)
+             (search/upsert-blocks! search-db (bean/->js indexed)))
+           (when should-report?
+             (report-search-index-progress! repo {:build-id build-id
+                                                  :status :running
+                                                  :progress progress
+                                                  :processed processed'
+                                                  :total total}))
+           (p/let [_ (js/Promise. (fn [resolve] (js/setTimeout resolve 0)))]
+             (p/recur remaining' processed' (if should-report? progress last-progress))))
+         (do
+           (ensure-active-search-index-build! repo build-id)
+           (.exec search-db (str "PRAGMA user_version = " search-db-version))
+           (report-search-index-progress! repo {:build-id build-id
+                                                :status :completed
+                                                :progress 100
+                                                :processed total
+                                                :total total})))))))
+
+(def-thread-api :thread-api/search-build-blocks-indice-in-worker
+  [repo & [force?]]
+  (p/let [search-db (get-search-db repo)]
+    (when search-db
+      (let [version (search-index-version search-db)]
+        (if (and (= version search-db-version) (not force?))
+          version
+          (when-let [conn (worker-state/get-datascript-conn repo)]
+            (when force?
+              (search/build-fuzzy-search-indice repo @conn))
+            (let [build-id (start-search-index-build! repo)]
+              (-> (<build-blocks-fts! repo search-db conn build-id)
+                  (p/catch (fn [error]
+                             (when-not (= :search/stale-index-build (:type (ex-data error)))
+                               (throw error))))
+                  (p/finally (fn []
+                               (when (= build-id (get @*search-index-build-ids repo))
+                                 (report-search-index-progress! repo {:build-id build-id
+                                                                      :status :idle}))
+                               (clear-search-index-build! repo build-id)))))))))))
+
+(def-thread-api :thread-api/search-build-pages-indice
+  [_repo]
+  nil)
+
+(def-thread-api :thread-api/apply-outliner-ops
+  [repo ops opts]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (try
+      (worker-util/profile
+       "apply outliner ops"
+       (outliner-op/apply-ops! conn ops opts))
+      (catch :default e
+        (let [data (ex-data e)
+              {:keys [type payload]} (when (map? data) data)]
+          (case type
+            :notification
+            (do
+              (log/error ::apply-outliner-ops-failed e)
+              (shared-service/broadcast-to-clients! :notification [(:message payload) (:type payload) (:clear? payload) (:uid payload) (:timeout payload)])
+              ;; re-throw as CLI needs to see notification
+              (throw e))
+            (throw e)))))))
+
+(def-thread-api :thread-api/sync-app-state
+  [new-state]
+  (when (and (contains? new-state :git/current-repo)
+             (nil? (:git/current-repo new-state)))
+    (log/error :thread-api/sync-app-state new-state))
+  (worker-state/set-new-state! new-state)
+  nil)
+
+(def-thread-api :thread-api/export-get-debug-datoms
+  [repo]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (worker-export/get-debug-datoms conn)))
+
+(def-thread-api :thread-api/export-get-all-page->content
+  [repo options]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (worker-export/get-all-page->content @conn options)))
+
+(def-thread-api :thread-api/validate-db
+  [repo & [opts]]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (worker-db-validate/validate-db conn opts)))
+
+(defn- checksum-diagnostics
+  [repo]
+  {:local-checksum (client-op/get-local-checksum repo)
+   :remote-checksum (get @db-sync/*repo->latest-remote-checksum repo)})
+
+(def-thread-api :thread-api/recompute-checksum-diagnostics
+  [repo]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (let [result (worker-db-validate/recompute-checksum-diagnostics repo conn (checksum-diagnostics repo))
+          recomputed-checksum (:recomputed-checksum result)]
+      (when (and (some? recomputed-checksum)
+                 (worker-state/get-client-ops-conn repo))
+        (client-op/update-local-checksum repo recomputed-checksum))
+      (cond-> result
+        (some? recomputed-checksum)
+        (assoc :local-checksum recomputed-checksum)))))
+
+;; Returns an export-edn map for given repo. When there's an unexpected error, a map
+;; with key :export-edn-error is returned
+(def-thread-api :thread-api/export-edn
+  [repo options]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (try
+      (sqlite-export/build-export @conn options)
+      (catch :default e
+        (js/console.error "export-edn error: " e)
+        (js/console.error "Stack:\n" (.-stack e))
+        (platform/post-message! (platform/current)
+                                :notification
+                                [nil :error nil nil nil
+                                 {:i18n-key :export/error-unexpected}])
+        {:export-edn-error (.-message e)}))))
+
+(def-thread-api :thread-api/import-edn
+  [repo export-edn]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (when-not conn
+      (throw (ex-info "graph not opened" {:code :graph-not-opened :repo repo})))
+    (let [{:keys [init-tx block-props-tx misc-tx]} (sqlite-export/build-import export-edn @conn {})
+          tx-data (vec (concat init-tx block-props-tx misc-tx))
+          tx-meta {::sqlite-export/imported-data? true}]
+      (ldb/transact! conn tx-data tx-meta)
+      {:tx-count (count tx-data)})))
+
+(def-thread-api :thread-api/get-view-data
+  [repo view-id option]
+  (let [db @(worker-state/get-datascript-conn repo)]
+    (db-view/get-view-data db view-id option)))
+
+(def-thread-api :thread-api/get-class-objects
+  [repo class-id]
+  (let [db @(worker-state/get-datascript-conn repo)]
+    (->> (db-class/get-class-objects db class-id)
+         (map entity-util/entity->map))))
+
+(def-thread-api :thread-api/get-property-values
+  [repo {:keys [property-ident] :as option}]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (db-view/get-property-values @conn property-ident option)))
+
+(def-thread-api :thread-api/get-bidirectional-properties
+  [repo {:keys [target-id]}]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (worker-util/profile "get-bidirectional-properties"
+                         (ldb/get-bidirectional-properties @conn target-id))))
+
+(def-thread-api :thread-api/build-graph
+  [repo option]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (graph-view/build-graph @conn option)))
+
+(def ^:private *get-all-page-titles-cache (volatile! (cache/lru-cache-factory {})))
+(defn- get-all-page-titles
+  [db]
+  (let [pages (ldb/get-all-pages db)]
+    (sort (map :block/title pages))))
+
+(def ^:private get-all-page-titles-with-cache
+  (common.cache/cache-fn
+   *get-all-page-titles-cache
+   (fn [repo]
+     (let [db @(worker-state/get-datascript-conn repo)]
+       [[repo (:max-tx db)] ;cache-key
+        [db]             ;f-args
+        ]))
+   get-all-page-titles))
+
+(def-thread-api :thread-api/get-all-page-titles
+  [repo]
+  (get-all-page-titles-with-cache repo))
+
+(def-thread-api :thread-api/gc-graph
+  [repo]
+  (let [{:keys [db client-ops]} (get @*sqlite-conns repo)
+        conn (get @*datascript-conns repo)]
+    (when (and db conn)
+      (gc-sqlite-dbs! db client-ops conn {:full-gc? true})
+      nil)))
+
+(def-thread-api :thread-api/mobile-logs
+  []
+  @worker-state/*log)
+
+(def-thread-api :thread-api/get-rtc-graph-uuid
+  [repo]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (ldb/get-graph-rtc-uuid @conn)))
+
+;; Cli specific fns start with 'cli-'
+(def-thread-api :thread-api/cli-list-properties
+  [repo options]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-db-worker/list-properties @conn options)))
+
+(def-thread-api :thread-api/cli-list-tags
+  [repo options]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-db-worker/list-tags @conn options)))
+
+(def-thread-api :thread-api/cli-list-pages
+  [repo options]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-db-worker/list-pages @conn options)))
+
+(def-thread-api :thread-api/cli-list-tasks
+  [repo options]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-db-worker/list-tasks @conn options)))
+
+(def-thread-api :thread-api/cli-list-nodes
+  [repo options]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-db-worker/list-nodes @conn options)))
+
+;; API server specific fns start with 'api-'
+(def-thread-api :thread-api/api-get-page-data
+  [repo page-title]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-common-mcp-tools/get-page-data @conn page-title)))
+
+(def-thread-api :thread-api/api-list-properties
+  [repo options]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-common-mcp-tools/list-properties @conn options)))
+
+(def-thread-api :thread-api/api-list-tags
+  [repo options]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-common-mcp-tools/list-tags @conn options)))
+
+(def-thread-api :thread-api/api-list-pages
+  [repo options]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-common-mcp-tools/list-pages @conn options)))
+
+(def-thread-api :thread-api/api-build-upsert-nodes-edn
+  [repo ops]
+  (let [conn (worker-state/get-datascript-conn repo)]
+    (cli-common-mcp-tools/build-upsert-nodes-edn @conn ops)))
+
+(comment
+  (def-thread-api :general/dangerousRemoveAllDbs
+    []
+    (p/let [r (<list-all-dbs)
+            dbs (ldb/read-transit-str r)]
+      (p/all (map #(.unsafeUnlinkDB this (:name %)) dbs)))))
+
+(defn- on-become-master
+  [repo start-opts]
+  (js/Promise.
+   (m/sp
+     (log/info :db-worker/on-become-master-start {:repo repo
+                                                  :import-type (:import-type start-opts)})
+     (c.m/<? (init-sqlite-module!))
+     (when-not (:import-type start-opts)
+       (c.m/<? (start-db! repo start-opts))
+       (assert (some? (worker-state/get-datascript-conn repo))))
+     nil)))
+
+(def broadcast-data-types
+  (set (map
+        common-util/keyword->string
+        [:sync-db-changes
+         :notification
+         :log
+         :add-repo
+         :rtc-log
+         :rtc-sync-state])))
+
+(defn- <init-service!
+  [graph start-opts]
+  (let [[prev-graph service] @*service]
+    (cond
+      (nil? graph)
+      (do
+        (some-> prev-graph close-db!)
+        nil)
+
+      (and (= graph prev-graph) service)
+      service
+
+      :else
+      (do
+        (when (and prev-graph (not= graph prev-graph))
+          (close-db! prev-graph))
+        (log/info :db-worker/init-service {:graph graph
+                                           :prev-graph prev-graph
+                                           :import-type (:import-type start-opts)})
+        (p/let [service (shared-service/<create-service graph
+                                                        (bean/->js fns)
+                                                        #(on-become-master graph start-opts)
+                                                        broadcast-data-types
+                                                        {:import? (:import-type? start-opts)})]
+          (assert (p/promise? (get-in service [:status :ready])))
+          (reset! *service [graph service])
+          service)))))
+
+(defn- notify-invalid-data
+  [{:keys [tx-meta]} errors]
+  ;; don't notify on production when undo/redo failed
+  (when-not (and (or (:undo? tx-meta) (:redo? tx-meta))
+                 (not worker-util/dev?))
+    (shared-service/broadcast-to-clients! :notification
+                                          [nil :error nil nil nil
+                                           {:i18n-key :storage/invalid-data-writing}])
+    (platform/post-message! (platform/current)
+                            :capture-error
+                            {:error (ex-info "Invalid data writing to db" tx-meta)
+                             :payload {}
+                             :extra {:errors (str errors)
+                                     :tx-meta tx-meta}})))
+
+(defn- build-proxy-object
+  []
+  (->>
+   fns
+   (map
+    (fn [[k f]]
+      [k
+       (fn [& args]
+         (let [[_graph service] @*service
+               method-k (keyword (first args))]
+           (cond
+             (= :thread-api/create-or-open-db method-k)
+             ;; because shared-service operates at the graph level,
+             ;; creating a new database or switching to another one requires re-initializing the service.
+             (let [payload (last args)
+                   payload' (cond
+                              (string? payload) (ldb/read-transit-str payload)
+                              (array? payload) (js->clj payload :keywordize-keys true)
+                              :else payload)
+                   [graph opts] payload']
+               (p/let [service (<init-service! graph opts)
+                       client-id (:client-id service)]
+                 (when client-id
+                   (platform/post-message! (platform/current)
+                                           :record-worker-client-id
+                                           {:client-id client-id}))
+                 (get-in service [:status :ready])
+                 ;; wait for service ready
+                 (js-invoke (:proxy service) k args)))
+
+             (or (= :thread-api/sync-app-state method-k)
+                 (nil? service))
+             ;; only proceed down this branch before shared-service is initialized
+             (apply f args)
+
+             :else
+             ;; ensure service is ready
+             (p/let [_ready-value (get-in service [:status :ready])]
+               (js-invoke (:proxy service) k args)))))]))
+   (into {})
+   bean/->js))
+
+(defn init-core!
+  [platform']
+  (platform/set-platform! platform')
+  (ldb/register-transact-invalid-callback-fn! notify-invalid-data)
+  (build-proxy-object))
+
+(comment
+  (defn <remove-all-files!
+    "!! Dangerous: use it only for development."
+    []
+    (p/let [all-files (<list-all-files)
+            files (filter #(= (.-kind %) "file") all-files)
+            dirs (filter #(= (.-kind %) "directory") all-files)
+            _ (p/all (map (fn [file] (.remove file)) files))]
+      (p/all (map (fn [dir] (.remove dir)) dirs)))))
diff --git a/src/main/frontend/worker/db_listener.cljs b/src/main/frontend/worker/db_listener.cljs
index d24d7e8ab6..f4f5720ab6 100644
--- a/src/main/frontend/worker/db_listener.cljs
+++ b/src/main/frontend/worker/db_listener.cljs
@@ -81,5 +81,6 @@
                                         (sync-db-to-main-thread repo conn tx-report)
                                         tx-report)
                            opt {:repo repo}]
-                       (doseq [[k handler-fn] handlers]
-                         (handler-fn k opt tx-report')))))))))
+                       (when tx-report'
+                         (doseq [[k handler-fn] handlers]
+                           (handler-fn k opt tx-report'))))))))))
diff --git a/src/main/frontend/worker/db_worker.cljs b/src/main/frontend/worker/db_worker.cljs
index 9c3d357c8c..343671efc9 100644
--- a/src/main/frontend/worker/db_worker.cljs
+++ b/src/main/frontend/worker/db_worker.cljs
@@ -1,61 +1,15 @@
 (ns frontend.worker.db-worker
-  "Worker used for browser DB implementation"
-  (:require ["@sqlite.org/sqlite-wasm" :default sqlite3InitModule]
-            ["comlink" :as Comlink]
-            [cljs-bean.core :as bean]
-            [cljs.cache :as cache]
-            [clojure.set]
-            [clojure.string :as string]
-            [datascript.core :as d]
-            [datascript.storage :refer [IStorage] :as storage]
-            [frontend.common.cache :as common.cache]
-            [frontend.common.graph-view :as graph-view]
-            [frontend.common.missionary :as c.m]
-            [frontend.common.thread-api :as thread-api :refer [def-thread-api]]
-            [frontend.worker-common.util :as worker-util]
-            [frontend.worker.db-listener :as db-listener]
-            [frontend.worker.db.fix :as db-fix]
-            [frontend.worker.db.migrate :as db-migrate]
-            [frontend.worker.db.validate :as worker-db-validate]
-            [frontend.worker.export :as worker-export]
-            [frontend.worker.pipeline :as worker-pipeline]
-            [frontend.worker.publish]
-            [frontend.worker.search :as search]
-            [frontend.worker.shared-service :as shared-service]
+  "Browser worker entrypoint."
+  (:require ["comlink" :as Comlink]
+            [frontend.common.idb :as idb]
+            [frontend.worker.db-core :as db-core]
+            [frontend.worker.platform.browser :as platform-browser]
             [frontend.worker.state :as worker-state]
-            [frontend.worker.sync :as db-sync]
-            [frontend.worker.sync.asset-db-listener]
-            [frontend.worker.sync.client-op :as client-op]
-            [frontend.worker.sync.crypt :as sync-crypt]
-            [frontend.worker.sync.download :as sync-download]
-            [frontend.worker.thread-atom]
-            [frontend.worker.undo-redo :as worker-undo-redo]
             [goog.object :as gobj]
             [lambdaisland.glogi :as log]
             [lambdaisland.glogi.console :as glogi-console]
-            [logseq.cli.common.mcp.tools :as cli-common-mcp-tools]
-            [logseq.common.util :as common-util]
             [logseq.db :as ldb]
-            [logseq.db.common.entity-plus :as entity-plus]
-            [logseq.db.common.initial-data :as common-initial-data]
-            [logseq.db.common.order :as db-order]
-            [logseq.db.common.reference :as db-reference]
-            [logseq.db.common.sqlite :as common-sqlite]
-            [logseq.db.common.view :as db-view]
-            [logseq.db.frontend.class :as db-class]
-            [logseq.db.frontend.entity-util :as entity-util]
-            [logseq.db.frontend.schema :as db-schema]
-            [logseq.db.sqlite.create-graph :as sqlite-create-graph]
-            [logseq.db.sqlite.export :as sqlite-export]
-            [logseq.db.sqlite.gc :as sqlite-gc]
-            [logseq.db.sqlite.util :as sqlite-util]
-            [logseq.outliner.op :as outliner-op]
-            [logseq.outliner.recycle :as outliner-recycle]
-            [me.tonsky.persistent-sorted-set :as set :refer [BTSet]]
-            [missionary.core :as m]
-            [promesa.core :as p]
-            [goog.functions :as gfun]
-            [frontend.common.idb :as idb]))
+            [promesa.core :as p]))
 
 (def ^:private worker-bootstrap-loaded-key "__logseq_db_worker_bootstrap_loaded__")
 
@@ -67,1176 +21,25 @@
 
 (ensure-worker-bootstrap!)
 
-(declare <build-blocks-fts!)
-
-(def search-db-version
-  "Current search index version, stored in PRAGMA user_version.
-  Bump to force a rebuild when the index format changes."
-  1)
-
-(def ^:private search-index-build-batch-size 5000)
-(def ^:private search-index-build-time-budget-ms 8)
-(def ^:private search-index-build-idle-diff-ms 1000)
-(def ^:private search-index-build-pause-ms 300)
-(defonce *sqlite worker-state/*sqlite)
-(defonce *sqlite-conns worker-state/*sqlite-conns)
-(defonce *datascript-conns worker-state/*datascript-conns)
-(defonce *client-ops-conns worker-state/*client-ops-conns)
-(defonce *opfs-pools worker-state/*opfs-pools)
-(defonce *publishing? (atom false))
-(defonce ^:private *search-index-build-ids (atom {}))
-(defonce ^:private *client-ops-cleanup-timers (atom {}))
-(def ^:private client-ops-cleanup-interval-ms (* 3 60 60 1000))
-
 (defn- check-worker-scope!
   []
   (when (or (gobj/get js/self "React")
             (gobj/get js/self "module$react"))
     (throw (js/Error. "[db-worker] React is forbidden in worker scope!"))))
 
-(defn- <get-opfs-pool
-  [graph]
-  (when-not @*publishing?
-    (or (worker-state/get-opfs-pool graph)
-        (p/let [^js pool (.installOpfsSAHPoolVfs ^js @*sqlite #js {:name (worker-util/get-pool-name graph)
-                                                                   :initialCapacity 20})]
-          (swap! *opfs-pools assoc graph pool)
-          pool))))
-
-(defn- init-sqlite-module!
-  []
-  (when-not @*sqlite
-    (p/let [href (.. js/location -href)
-            publishing? (string/includes? href "publishing=true")
-            sqlite (sqlite3InitModule (clj->js {:print #(log/info :init-sqlite-module! %)
-                                                :printErr #(log/error :init-sqlite-module! %)}))]
-      (reset! *publishing? publishing?)
-      (reset! *sqlite sqlite)
-      nil)))
-
-(def repo-path "/db.sqlite")
-(def client-ops-repo-path (str "client-ops" repo-path))
-
-(defn- ->uint8array
-  [data]
-  (cond
-    (instance? js/Uint8Array data)
-    data
-
-    (js/ArrayBuffer.isView data)
-    (js/Uint8Array. (.-buffer data) (.-byteOffset data) (.-byteLength data))
-
-    (instance? js/ArrayBuffer data)
-    (js/Uint8Array. data)
-
-    (array? data)
-    (js/Uint8Array. data)
-
-    :else
-    data))
-
-(defn- export-db-file-with-paths
-  [repo path-candidates]
-  (p/let [^js pool (<get-opfs-pool repo)]
-    (when pool
-      (loop [paths (->> path-candidates
-                        (filter string?)
-                        (remove string/blank?)
-                        distinct
-                        vec)]
-        (when-let [path (first paths)]
-          (let [result (try
-                         (.exportFile ^js pool path)
-                         (catch :default _e
-                           nil))
-                payload (->uint8array result)]
-            (if (instance? js/Uint8Array payload)
-              payload
-              (recur (subvec paths 1)))))))))
-
-(defn- <export-db-file
-  ([repo]
-   (<export-db-file repo repo-path))
-  ([repo path]
-   (p/let [^js pool (<get-opfs-pool repo)]
-     (when pool
-       (.exportFile ^js pool path)))))
-
-(defn- <import-db
-  [^js pool data]
-  (.importDb ^js pool repo-path data))
-
-(defn upsert-addr-content!
-  "Upsert addr+data-seq. Update sqlite-cli/upsert-addr-content! when making changes"
-  [db data]
-  (assert (some? db) "sqlite db not exists")
-  (.transaction
-   db
-   (fn [tx]
-     (doseq [item data]
-       (.exec tx #js {:sql "INSERT INTO kvs (addr, content, addresses) values ($addr, $content, $addresses) on conflict(addr) do update set content = $content, addresses = $addresses"
-                      :bind item})))))
-
-(defn- enable-sqlite-wal-mode!
-  [^Object db]
-  (.exec db "PRAGMA locking_mode=exclusive")
-  (.exec db "PRAGMA journal_mode=WAL"))
-
-(defn restore-data-from-addr
-  "Update sqlite-cli/restore-data-from-addr when making changes"
-  [db addr]
-  (assert (some? db) "sqlite db not exists")
-  (when-let [result (-> (.exec db #js {:sql "select content, addresses from kvs where addr = ?"
-                                       :bind #js [addr]
-                                       :rowMode "array"})
-                        first)]
-    (let [[content addresses] (bean/->clj result)
-          addresses (when addresses
-                      (js/JSON.parse addresses))
-          data (sqlite-util/read-transit-str content)]
-      (if (and addresses (map? data))
-        (assoc data :addresses addresses)
-        data))))
-
-(defn new-sqlite-storage
-  "Update sqlite-cli/new-sqlite-storage when making changes"
-  [^Object db]
-  (reify IStorage
-    (-store [_ addr+data-seq _delete-addrs]
-      (let [data (map
-                  (fn [[addr data]]
-                    (let [data' (if (map? data) (dissoc data :addresses) data)
-                          addresses (when (map? data)
-                                      (when-let [addresses (:addresses data)]
-                                        (js/JSON.stringify (bean/->js addresses))))]
-                      #js {:$addr addr
-                           :$content (sqlite-util/write-transit-str data')
-                           :$addresses addresses}))
-                  addr+data-seq)]
-        (upsert-addr-content! db data)))
-
-    (-restore [_ addr]
-      (restore-data-from-addr db addr))))
-
-(defn- close-db-aux!
-  [repo ^Object db ^Object search ^Object client-ops]
-  (when-let [timer (get @*client-ops-cleanup-timers repo)]
-    (js/clearInterval timer))
-  (swap! *client-ops-cleanup-timers dissoc repo)
-  (swap! *sqlite-conns dissoc repo)
-  (swap! *datascript-conns dissoc repo)
-  (swap! *client-ops-conns dissoc repo)
-  (swap! client-op/*repo->pending-local-tx-count dissoc repo)
-  (swap! *search-index-build-ids dissoc repo)
-  (search/clear-fuzzy-search-indice! repo)
-  (when db (.close db))
-  (when search (.close search))
-  (when client-ops (.close client-ops))
-  (sync-download/close-import-state-for-repo! repo)
-  (when-let [^js pool (worker-state/get-opfs-pool repo)]
-    (try
-      (.pauseVfs pool)
-      (catch :default e
-        (log/warn :db-worker/pause-vfs-failed
-                  {:repo repo
-                   :error (str e)}))))
-  (swap! *opfs-pools dissoc repo))
-
-(defn- <invalidate-search-db!
-  [repo]
-  (if-let [search-db (worker-state/get-sqlite-conn repo :search)]
-    (do
-      (search/truncate-table! search-db)
-      (p/resolved nil))
-    (p/let [^js pool (<get-opfs-pool repo)
-            ^js search-db (new (.-OpfsSAHPoolDb pool) (str "search" repo-path))]
-      (try
-        (search/truncate-table! search-db)
-        (finally
-          (.close search-db)))
-      nil)))
-
-(defn- close-other-dbs!
-  [repo]
-  (doseq [[r {:keys [db search client-ops]}] @*sqlite-conns]
-    (when-not (= repo r)
-      (close-db-aux! r db search client-ops))))
-
-(defn close-db!
-  [repo]
-  (let [{:keys [db search client-ops]} (get @*sqlite-conns repo)]
-    (close-db-aux! repo db search client-ops)))
-
-(defn reset-db!
-  [repo db-transit-str]
-  (when-let [conn (get @*datascript-conns repo)]
-    (let [new-db (ldb/read-transit-str db-transit-str)
-          new-db' (update new-db :eavt (fn [^BTSet s]
-                                         (set! (.-storage s) (.-storage (:eavt @conn)))
-                                         s))]
-      (d/reset-conn! conn new-db' {:reset-conn! true})
-      (d/reset-schema! conn (:schema new-db)))))
-
-(defn- get-dbs
-  [repo]
-  (if @*publishing?
-    (p/let [^object DB (.-DB ^object (.-oo1 ^object @*sqlite))
-            db (new DB "/db.sqlite" "c")
-            search-db (new DB "/search-db.sqlite" "c")]
-      [db search-db])
-    (p/let [^js pool (<get-opfs-pool repo)
-            capacity (.getCapacity pool)
-            _ (when (zero? capacity)   ; file handle already releases since pool will be initialized only once
-                (.unpauseVfs pool))
-            db (new (.-OpfsSAHPoolDb pool) repo-path)
-            search-db (new (.-OpfsSAHPoolDb pool) (str "search" repo-path))
-            client-ops-db (new (.-OpfsSAHPoolDb pool) client-ops-repo-path)]
-      [db search-db client-ops-db])))
-
-(defn- gc-sqlite-dbs!
-  "Gc main db monthly and rtc ops db each time when opening it"
-  [sqlite-db client-ops-db datascript-conn {:keys [full-gc?]}]
-  (let [last-gc-at (:kv/value (d/entity @datascript-conn :logseq.kv/graph-last-gc-at))]
-    (when (or full-gc?
-              (nil? last-gc-at)
-              (not (number? last-gc-at))
-              (> (- (common-util/time-ms) last-gc-at) (* 30 24 3600 1000))) ; 1 month ago
-      (log/info :gc-sqlite-dbs "gc current graph")
-      (doseq [db (if @*publishing? [sqlite-db] [sqlite-db client-ops-db])]
-        (sqlite-gc/gc-kvs-table! db {:full-gc? full-gc?})
-        (.exec db "VACUUM"))
-      (ldb/transact! datascript-conn [{:db/ident :logseq.kv/graph-last-gc-at
-                                       :kv/value (common-util/time-ms)}]
-                     {:skip-validate-db? true}))))
-
-(defn- run-client-ops-cleanup!
-  [repo]
-  (let [protected-tx-ids (worker-undo-redo/referenced-history-tx-ids repo)]
-    (client-op/cleanup-finished-history-ops! repo protected-tx-ids)
-    nil))
-
-(defn- ensure-client-ops-cleanup-timer!
-  [repo]
-  (when (and (not @*publishing?)
-             repo
-             (nil? (get @*client-ops-cleanup-timers repo)))
-    (let [timer (js/setInterval (fn []
-                                  (run-client-ops-cleanup! repo))
-                                client-ops-cleanup-interval-ms)]
-      (swap! *client-ops-cleanup-timers assoc repo timer))
-    nil))
-
-(def ^:private recycle-gc-kv :logseq.kv/recycle-last-gc-at)
-
-(defn- maybe-run-recycle-gc!
-  [conn]
-  (let [now (common-util/time-ms)
-        last-gc-at (:kv/value (d/entity @conn recycle-gc-kv))]
-    (when (or (not (number? last-gc-at))
-              (> (- now last-gc-at) outliner-recycle/gc-interval-ms))
-      (outliner-recycle/gc! conn {:now-ms now})
-      (ldb/transact! conn [{:db/ident recycle-gc-kv
-                            :kv/value now}]
-                     {:persist-op? false
-                      :skip-validate-db? true}))))
-
-(defn- <create-or-open-db!
-  [repo {:keys [config datoms sync-download-graph? remote-graph?] :as opts}]
-  (when-not (worker-state/get-sqlite-conn repo)
-    (p/let [[db search-db client-ops-db :as dbs] (get-dbs repo)
-            storage (new-sqlite-storage db)]
-      (swap! *sqlite-conns assoc repo {:db db
-                                       :search search-db
-                                       :client-ops client-ops-db})
-      (doseq [db' dbs]
-        (enable-sqlite-wal-mode! db'))
-      (common-sqlite/create-kvs-table! db)
-      (when-not @*publishing? (common-sqlite/create-kvs-table! client-ops-db))
-      (search/create-tables-and-triggers! search-db)
-      (ldb/register-transact-pipeline-fn! worker-pipeline/transact-pipeline)
-      (ldb/register-debounce-fn! (gfun/debounce d/store 100))
-      (let [conn (common-sqlite/get-storage-conn storage db-schema/schema)
-            _ (db-fix/check-and-fix-schema! conn)
-            _ (when datoms
-                (let [ident-eids (into #{}
-                                       (comp (filter (fn [datom]
-                                                       (= (:a datom) :db/ident)))
-                                             (map :e))
-                                       datoms)
-                      to-tx (fn [d] [:db/add (:e d) (:a d) (:v d)])
-                      batch-size 20000
-                      ident-batches (->> datoms
-                                         (filter #(contains? ident-eids (:e %)))
-                                         (map to-tx)
-                                         (partition-all batch-size))
-                      _ (doseq [batch ident-batches]
-                          (d/transact! conn batch {:initial-db? true}))
-                      non-ident-batches (->> datoms
-                                             (remove #(contains? ident-eids (:e %)))
-                                             (map to-tx)
-                                             (partition-all batch-size))]
-                  (doseq [batch non-ident-batches]
-                    (d/transact! conn batch {:initial-db? true}))))
-            initial-data-exists? (when (nil? datoms)
-                                   (and (d/entity @conn :logseq.class/Root)
-                                        (= "db" (:kv/value (d/entity @conn :logseq.kv/db-type)))))]
-        (swap! *datascript-conns assoc repo conn)
-        (swap! *client-ops-conns assoc repo client-ops-db)
-        (when-not @*publishing?
-          (client-op/ensure-sqlite-schema! client-ops-db))
-        (ensure-client-ops-cleanup-timer! repo)
-        (let [initial-tx-report (when-not (or initial-data-exists?
-                                              (seq datoms)
-                                              sync-download-graph?)
-                                  (let [config (or config "")
-                                        initial-data (sqlite-create-graph/build-db-initial-data
-                                                      config (select-keys opts [:import-type :graph-git-sha :remote-graph?]))]
-                                    (ldb/transact! conn initial-data
-                                                   {:initial-db? true})))]
-          (when-not sync-download-graph?
-            (db-migrate/migrate conn)
-            (gc-sqlite-dbs! db client-ops-db conn {})
-            (maybe-run-recycle-gc! conn))
-
-          (when remote-graph?
-            (client-op/update-local-tx repo 0))
-
-          (when initial-tx-report
-            (db-sync/handle-local-tx! repo initial-tx-report))
-
-          (db-listener/listen-db-changes! repo (get @*datascript-conns repo))
-
-          nil)))))
-
-(defn- iter->vec [iter']
-  (when iter'
-    (p/loop [acc []]
-      (p/let [elem (.next iter')]
-        (if (.-done elem)
-          acc
-          (p/recur (conj acc (.-value elem))))))))
-
-(comment
-  (defn- <list-all-files
-    []
-    (let [dir? #(= (.-kind %) "directory")]
-      (p/let [^js root (.getDirectory js/navigator.storage)]
-        (p/loop [result []
-                 dirs [root]]
-          (if (empty? dirs)
-            result
-            (p/let [dir (first dirs)
-                    result (conj result dir)
-                    values-iter (when (dir? dir) (.values dir))
-                    values (when values-iter (iter->vec values-iter))
-                    current-dir-dirs (filter dir? values)
-                    result (concat result values)
-                    dirs (concat
-                          current-dir-dirs
-                          (rest dirs))]
-              (p/recur result dirs))))))))
-
-(defn- <list-all-dbs
-  []
-  (let [dir? #(= (.-kind %) "directory")
-        db-dir-prefix ".logseq-pool-"]
-    (p/let [^js root (.getDirectory js/navigator.storage)
-            values-iter (when (dir? root) (.values root))
-            values (when values-iter (iter->vec values-iter))
-            current-dir-dirs (filter dir? values)
-            db-dirs (filter (fn [file]
-                              (string/starts-with? (.-name file) db-dir-prefix))
-                            current-dir-dirs)]
-      (p/all (map (fn [dir]
-                    (p/let [graph-name (-> (.-name dir)
-                                           (string/replace-first ".logseq-pool-" "")
-                                           ;; TODO: DRY
-                                           (string/replace "+3A+" ":")
-                                           (string/replace "++" "/"))]
-                      {:name graph-name})) db-dirs)))))
-
-(def-thread-api :thread-api/list-db
-  []
-  (<list-all-dbs))
-
-(defn- <db-exists?
-  [graph]
-  (->
-   (p/let [^js root (.getDirectory js/navigator.storage)
-           _dir-handle (.getDirectoryHandle root (str "." (worker-util/get-pool-name graph)))]
-     true)
-   (p/catch
-    (fn [_e]                         ; not found
-      false))))
-
-(defn- remove-vfs!
-  [^js pool]
-  (when (fn? (some-> pool .-removeVfs))
-    (.removeVfs ^js pool)))
-
-(defn- get-search-db
-  [repo]
-  (worker-state/get-sqlite-conn repo :search))
-
-(defn- search-index-version
-  [^js search-db]
-  (aget (aget (.exec search-db #js {:sql "PRAGMA user_version" :rowMode "array"}) 0) 0))
-
-(defn- start-search-index-build!
-  [repo]
-  (let [build-id (str (random-uuid))]
-    (swap! *search-index-build-ids assoc repo build-id)
-    build-id))
-
-(defn- clear-search-index-build!
-  [repo build-id]
-  (swap! *search-index-build-ids
-         (fn [builds]
-           (if (= build-id (get builds repo))
-             (dissoc builds repo)
-             builds))))
-
-(defn- ensure-active-search-index-build!
-  [repo build-id]
-  (when-not (= build-id (get @*search-index-build-ids repo))
-    (throw (ex-info "stale search index build"
-                    {:type :search/stale-index-build
-                     :repo repo
-                     :build-id build-id}))))
-
-(defn- report-search-index-progress!
-  [repo payload]
-  (-> (worker-state/<invoke-main-thread :thread-api/search-index-build-progress repo payload)
-      (p/catch (fn [_error] nil))))
-
-(comment
-  (def-thread-api :thread-api/get-version
-    []
-    (when-let [sqlite @*sqlite]
-      (.-version sqlite))))
-
-(def-thread-api :thread-api/init
-  []
-  (init-sqlite-module!))
-
-(def-thread-api :thread-api/set-db-sync-config
-  [config]
-  (reset! worker-state/*db-sync-config config)
-  nil)
-
-(def-thread-api :thread-api/db-sync-start
-  [repo]
-  (db-sync/start! repo))
-
-(def-thread-api :thread-api/db-sync-stop
-  []
-  (db-sync/stop!))
-
-(def-thread-api :thread-api/db-sync-update-presence
-  [editing-block-uuid]
-  (db-sync/update-presence! editing-block-uuid))
-
-(def-thread-api :thread-api/db-sync-request-asset-download
-  [repo asset-uuid]
-  (db-sync/request-asset-download! repo asset-uuid))
-
-(def-thread-api :thread-api/db-sync-grant-graph-access
-  [repo graph-id target-email]
-  (sync-crypt/<grant-graph-access! repo graph-id target-email))
-
-(def-thread-api :thread-api/db-sync-ensure-user-rsa-keys
-  [& [opts]]
-  (sync-crypt/ensure-user-rsa-keys! opts))
-
-(def-thread-api :thread-api/db-sync-upload-graph
-  [repo]
-  (db-sync/upload-graph! repo))
-
-(def-thread-api :thread-api/db-sync-stop-upload
-  [repo]
-  (db-sync/stop-upload! repo))
-
-(def-thread-api :thread-api/db-sync-resume-upload
-  [repo]
-  (db-sync/resume-upload! repo))
-
-(def-thread-api :thread-api/db-sync-upload-stopped?
-  [repo]
-  (db-sync/upload-stopped? repo))
-
-(def-thread-api :thread-api/db-sync-download-graph
-  [repo graph-id graph-e2ee?]
-  (sync-download/download-graph-by-id! repo graph-id graph-e2ee?))
-
-;; [graph service]
-(defonce *service (atom []))
-
-(defonce fns {"remoteInvoke" thread-api/remote-function})
-
-(defn- start-db!
-  [repo {:keys [close-other-db?]
-         :or {close-other-db? true}
-         :as opts}]
-  (p/do!
-   (when close-other-db?
-     (close-other-dbs! repo))
-   (when @shared-service/*master-client?
-     (<create-or-open-db! repo (dissoc opts :close-other-db?)))
-   nil))
-
-(def-thread-api :thread-api/create-or-open-db
-  [repo opts]
-  (when-not (= repo (worker-state/get-current-repo)) ; graph switched
-    (reset! worker-state/*deleted-block-uuid->db-id {}))
-  (start-db! repo opts))
-
-(def-thread-api :thread-api/q
-  [repo inputs]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (worker-util/profile
-     (str "Datalog query: " inputs)
-     (apply d/q (first inputs) @conn (rest inputs)))))
-
-(def-thread-api :thread-api/datoms
-  [repo & args]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (let [result (apply d/datoms @conn args)]
-      (map (fn [d] [(:e d) (:a d) (:v d) (:tx d) (:added d)]) result))))
-
-(def-thread-api :thread-api/pull
-  [repo selector id]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (let [eid (if (and (vector? id) (= :block/name (first id)))
-                (:db/id (ldb/get-page @conn (second id)))
-                id)]
-      (some->> eid
-               (d/pull @conn selector)
-               (common-initial-data/with-parent @conn)))))
-
-(def ^:private *get-blocks-cache (volatile! (cache/lru-cache-factory {} :threshold 1000)))
-(def ^:private get-blocks-with-cache
-  (common.cache/cache-fn
-   *get-blocks-cache
-   (fn [repo requests]
-     (let [db (some-> (worker-state/get-datascript-conn repo) deref)]
-       [[repo (:max-tx db) requests]
-        [db requests]]))
-   (fn [db requests]
-     (when db
-       (->> requests
-            (mapv (fn [{:keys [id opts]}]
-                    (let [id' (if (and (string? id) (common-util/uuid-string? id)) (uuid id) id)]
-                      (-> (common-initial-data/get-block-and-children db id' opts)
-                          (assoc :id id)))))
-            ldb/write-transit-str)))))
-
-(def-thread-api :thread-api/get-blocks
-  [repo requests]
-  (let [requests (ldb/read-transit-str requests)]
-    (get-blocks-with-cache repo requests)))
-
-(def-thread-api :thread-api/get-block-refs
-  [repo id]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (->> (db-reference/get-linked-references @conn id)
-         :ref-blocks
-         (map (fn [b] (assoc (into {} b) :db/id (:db/id b)))))))
-
-(def-thread-api :thread-api/get-block-refs-count
-  [repo id]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (ldb/get-block-refs-count @conn id)))
-
-(def-thread-api :thread-api/get-block-source
-  [repo id]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (:db/id (first (:block/_alias (d/entity @conn id))))))
-
-(defn- search-blocks
-  [repo q option]
-  (let [search-db (get-search-db repo)
-        conn (worker-state/get-datascript-conn repo)]
-    (search/search-blocks repo conn search-db q option)))
-
-(def-thread-api :thread-api/block-refs-check
-  [repo id {:keys [unlinked?]}]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (let [db @conn
-          block (d/entity db id)]
-      (if unlinked?
-        (let [title (string/lower-case (:block/title block))
-              result (search-blocks repo title {:limit 100})]
-          (boolean (some (fn [b]
-                           (let [block (d/entity db (:db/id b))]
-                             (and (not= id (:db/id block))
-                                  (not ((set (map :db/id (:block/refs block))) id))
-                                  (string/includes? (string/lower-case (:block/title block)) title)))) result)))
-        (some? (first (common-initial-data/get-block-refs db (:db/id block))))))))
-
-(def-thread-api :thread-api/get-block-parents
-  [repo id depth]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (let [block-id (:block/uuid (d/entity @conn id))]
-      (->> (ldb/get-block-parents @conn block-id {:depth (or depth 3)})
-           (map (fn [b] (d/pull @conn '[*] (:db/id b))))))))
-
-(def-thread-api :thread-api/set-context
-  [context]
-  (when context (worker-state/update-context! context))
-  nil)
-
-(def-thread-api :thread-api/transact
-  [repo tx-data tx-meta context]
-  (assert (some? repo))
-  (worker-state/set-db-latest-tx-time! repo)
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (assert (some? conn) {:repo repo})
-    (try
-      (let [tx-data' (if (contains? #{:insert-blocks} (:outliner-op tx-meta))
-                       (map (fn [m]
-                              (if (and (map? m) (nil? (:block/order m)))
-                                (assoc m :block/order (db-order/gen-key nil))
-                                m)) tx-data)
-                       tx-data)
-            _ (when context (worker-state/set-context! context))
-            tx-meta' (cond-> tx-meta
-                       true
-                       (dissoc :insert-blocks?))]
-        (when-not (and (:create-today-journal? tx-meta)
-                       (:today-journal-name tx-meta)
-                       (seq tx-data')
-                       (ldb/get-page @conn (:today-journal-name tx-meta))) ; today journal created already
-
-          ;; (prn :debug :transact :tx-data tx-data' :tx-meta tx-meta')
-
-          (worker-util/profile "Worker db transact"
-                               (ldb/transact! conn tx-data' tx-meta')))
-        (maybe-run-recycle-gc! conn)
-        nil)
-      (catch :default e
-        (prn :debug :worker-transact-failed :tx-meta tx-meta :tx-data tx-data)
-        (log/error ::worker-transact-failed e)
-        (throw e)))))
-
-(def-thread-api :thread-api/undo-redo-set-pending-editor-info
-  [repo editor-info]
-  (worker-undo-redo/set-pending-editor-info! repo editor-info)
-  nil)
-
-(def-thread-api :thread-api/undo-redo-record-editor-info
-  [repo editor-info]
-  (worker-undo-redo/record-editor-info! repo editor-info)
-  nil)
-
-(def-thread-api :thread-api/undo-redo-record-ui-state
-  [repo ui-state-str]
-  (worker-undo-redo/record-ui-state! repo ui-state-str)
-  nil)
-
-(def-thread-api :thread-api/undo-redo-undo
-  [repo]
-  (worker-undo-redo/undo repo))
-
-(def-thread-api :thread-api/undo-redo-redo
-  [repo]
-  (worker-undo-redo/redo repo))
-
-(def-thread-api :thread-api/undo-redo-clear-history
-  [repo]
-  (worker-undo-redo/clear-history! repo)
-  nil)
-
-(def-thread-api :thread-api/undo-redo-get-debug-state
-  [repo]
-  (worker-undo-redo/get-debug-state repo))
-
-(def-thread-api :thread-api/get-initial-data
-  [repo opts]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (if (:file-graph-import? opts)
-      {:schema (:schema @conn)
-       :initial-data (vec (d/datoms @conn :eavt))}
-      (common-initial-data/get-initial-data @conn))))
-
-(def-thread-api :thread-api/reset-db
-  [repo db-transit]
-  (reset-db! repo db-transit)
-  nil)
-
-(defn- <unlink-db!
-  [repo]
-  (p/let [pool (<get-opfs-pool repo)
-          _ (close-db! repo)
-          _result (remove-vfs! pool)]
-    nil))
-
-(def-thread-api :thread-api/unsafe-unlink-db
-  [repo]
-  (<unlink-db! repo))
-
-(def-thread-api :thread-api/db-sync-close-db
-  [repo]
-  (close-db! repo))
-
-(def-thread-api :thread-api/db-sync-invalidate-search-db
-  [repo]
-  (<invalidate-search-db! repo))
-
-(def-thread-api :thread-api/db-sync-rehydrate-large-titles
-  [repo graph-id]
-  (db-sync/rehydrate-large-titles-from-db! repo graph-id))
-
-(def-thread-api :thread-api/db-sync-import-prepare
-  [repo reset? graph-id graph-e2ee? & [total-datoms]]
-  (sync-download/prepare-import! repo reset? graph-id graph-e2ee? total-datoms))
-
-(def-thread-api :thread-api/db-sync-import-rows-chunk
-  [rows graph-id import-id]
-  (sync-download/import-rows-chunk! rows graph-id import-id))
-
-(def-thread-api :thread-api/db-sync-import-finalize
-  [repo graph-id remote-tx import-id]
-  (sync-download/finalize-import! repo graph-id remote-tx import-id))
-
-(def-thread-api :thread-api/release-access-handles
-  [repo]
-  (sync-download/close-import-state-for-repo! repo)
-  (when-let [^js pool (worker-state/get-opfs-pool repo)]
-    (try
-      (.pauseVfs pool)
-      (catch :default e
-        (log/warn :db-worker/pause-vfs-failed
-                  {:repo repo
-                   :error (str e)})))
-    nil))
-
-(def-thread-api :thread-api/db-exists
-  [repo]
-  (<db-exists? repo))
-
-(def-thread-api :thread-api/export-db
-  [repo]
-  (when-let [^js db (worker-state/get-sqlite-conn repo :db)]
-    (.exec db "PRAGMA wal_checkpoint(2)"))
-  (p/let [data (<export-db-file repo)
-          payload (->uint8array data)]
-    (Comlink/transfer payload #js [(.-buffer payload)])))
-
-(def-thread-api :thread-api/export-client-ops-db
-  [repo]
-  (when-let [^js db (worker-state/get-sqlite-conn repo :client-ops)]
-    (.exec db "PRAGMA wal_checkpoint(2)"))
-  (let [^js client-ops-db (worker-state/get-sqlite-conn repo :client-ops)
-        db-filename (some-> client-ops-db (gobj/get "filename"))
-        export-paths [db-filename
-                      client-ops-repo-path
-                      (str "/" client-ops-repo-path)
-                      (str "client-ops" repo-path)
-                      (str "/client-ops" repo-path)]]
-    (p/let [payload (export-db-file-with-paths repo export-paths)]
-      (when (instance? js/Uint8Array payload)
-        (Comlink/transfer payload #js [(.-buffer payload)])))))
-
-(def-thread-api :thread-api/import-db
-  [repo data]
-  (when-not (string/blank? repo)
-    (p/let [pool (<get-opfs-pool repo)]
-      (<import-db pool data)
-      nil)))
-
-(def-thread-api :thread-api/search-blocks
-  [repo q option]
-  (search-blocks repo q option))
-
-(def-thread-api :thread-api/search-upsert-blocks
-  [repo blocks]
-  (p/let [db (get-search-db repo)]
-    (search/upsert-blocks! db (bean/->js blocks))
-    nil))
-
-(def-thread-api :thread-api/search-delete-blocks
-  [repo ids]
-  (p/let [db (get-search-db repo)]
-    (search/delete-blocks! db ids)
-    nil))
-
-(def-thread-api :thread-api/search-truncate-tables
-  [repo]
-  (p/let [db (get-search-db repo)]
-    (search/truncate-table! db)
-    nil))
-
-(def-thread-api :thread-api/search-build-blocks-indice
-  [repo]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (search/build-blocks-indice repo @conn)))
-
-(defn- take-block-datoms-batch
-  [datoms batch-size time-budget-ms]
-  (let [deadline (+ (common-util/time-ms) time-budget-ms)]
-    (loop [batch (transient [])
-           remaining (seq datoms)
-           n 0]
-      (if (or (nil? remaining)
-              (>= n batch-size)
-              (and (pos? n) (>= (common-util/time-ms) deadline)))
-        [(persistent! batch) remaining]
-        (recur (conj! batch (first remaining))
-               (next remaining)
-               (inc n))))))
-
-(defn- <wait-for-search-index-idle!
-  [repo build-id]
-  (p/loop []
-    (ensure-active-search-index-build! repo build-id)
-    (p/let [idle? (worker-state/<invoke-main-thread :thread-api/input-idle? repo search-index-build-idle-diff-ms)]
-      (if idle?
-        nil
-        (p/let [_ (js/Promise. (fn [resolve] (js/setTimeout resolve search-index-build-pause-ms)))]
-          (p/recur))))))
-
-(defn- <build-blocks-fts!
-  "Build FTS index in batches with yielding. Sets user_version to search-db-version on completion."
-  [repo search-db conn build-id]
-  (ensure-active-search-index-build! repo build-id)
-  (search/truncate-table! search-db)
-  (let [db @conn
-        datoms (d/datoms db :avet :block/uuid)
-        total (count datoms)]
-    (p/do!
-     (report-search-index-progress! repo {:build-id build-id
-                                          :status :running
-                                          :progress 0
-                                          :processed 0
-                                          :total total})
-     (<wait-for-search-index-idle! repo build-id)
-     (p/loop [remaining (seq datoms)
-              processed 0
-              last-progress 0]
-       (ensure-active-search-index-build! repo build-id)
-       (if (seq remaining)
-         (let [[batch remaining'] (take-block-datoms-batch remaining
-                                                           search-index-build-batch-size
-                                                           search-index-build-time-budget-ms)
-               processed' (+ processed (count batch))
-               indexed (->> batch
-                            (keep #(d/entity db (:e %)))
-                            (remove search/hidden-entity?)
-                            (keep search/block->index))
-               progress (if (zero? total)
-                          100
-                          (min 100 (int (* 100 (/ processed' total)))))
-               should-report? (> progress last-progress)]
-           (when (seq indexed)
-             (search/upsert-blocks! search-db (bean/->js indexed)))
-           (when should-report?
-             (report-search-index-progress! repo {:build-id build-id
-                                                  :status :running
-                                                  :progress progress
-                                                  :processed processed'
-                                                  :total total}))
-           (p/let [_ (js/Promise. (fn [resolve] (js/setTimeout resolve 0)))]
-             (p/recur remaining' processed' (if should-report? progress last-progress))))
-         (do
-           (ensure-active-search-index-build! repo build-id)
-           (.exec search-db (str "PRAGMA user_version = " search-db-version))
-           (report-search-index-progress! repo {:build-id build-id
-                                                :status :completed
-                                                :progress 100
-                                                :processed total
-                                                :total total})))))))
-
-(def-thread-api :thread-api/search-build-blocks-indice-in-worker
-  [repo & [force?]]
-  (p/let [search-db (get-search-db repo)]
-    (when search-db
-      (let [version (search-index-version search-db)]
-        (if (and (= version search-db-version) (not force?))
-          version
-          (when-let [conn (worker-state/get-datascript-conn repo)]
-            (when force?
-              (search/build-fuzzy-search-indice repo @conn))
-            (let [build-id (start-search-index-build! repo)]
-              (-> (<build-blocks-fts! repo search-db conn build-id)
-                  (p/catch (fn [error]
-                             (when-not (= :search/stale-index-build (:type (ex-data error)))
-                               (throw error))))
-                  (p/finally (fn []
-                               (when (= build-id (get @*search-index-build-ids repo))
-                                 (report-search-index-progress! repo {:build-id build-id
-                                                                      :status :idle}))
-                               (clear-search-index-build! repo build-id)))))))))))
-
-(def-thread-api :thread-api/search-build-pages-indice
-  [_repo]
-  nil)
-
-(def-thread-api :thread-api/apply-outliner-ops
-  [repo ops opts]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (try
-      (worker-util/profile
-       "apply outliner ops"
-       (outliner-op/apply-ops! conn ops opts))
-      (catch :default e
-        (let [data (ex-data e)
-              {:keys [type payload]} (when (map? data) data)]
-          (case type
-            :notification
-            (do
-              (log/error ::apply-outliner-ops-failed e)
-              (shared-service/broadcast-to-clients! :notification
-                                                    [(:message payload) (:type payload) (:clear? payload) (:uid payload) (:timeout payload)
-                                                     {:i18n-key (:i18n-key payload) :i18n-args (:i18n-args payload)}]))
-            (throw e)))))))
-
-(def-thread-api :thread-api/sync-app-state
-  [new-state]
-  (when (and (contains? new-state :git/current-repo)
-             (nil? (:git/current-repo new-state)))
-    (log/error :thread-api/sync-app-state new-state))
-  (worker-state/set-new-state! new-state)
-  nil)
-
-(def-thread-api :thread-api/export-get-debug-datoms
-  [repo]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (worker-export/get-debug-datoms conn)))
-
-(def-thread-api :thread-api/export-get-all-page->content
-  [repo options]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (worker-export/get-all-page->content @conn options)))
-
-(defn- sync-diagnostics-for-validation
-  [repo]
-  {:local-tx (client-op/get-local-tx repo)
-   :remote-tx (get @db-sync/*repo->latest-remote-tx repo)
-   :local-checksum (client-op/get-local-checksum repo)
-   :remote-checksum (get @db-sync/*repo->latest-remote-checksum repo)})
-
-(def-thread-api :thread-api/validate-db
-  [repo]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (worker-db-validate/validate-db repo conn (sync-diagnostics-for-validation repo))))
-
-(def-thread-api :thread-api/recompute-checksum-diagnostics
-  [repo]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (let [result (worker-db-validate/recompute-checksum-diagnostics repo conn (sync-diagnostics-for-validation repo))
-          recomputed-checksum (:recomputed-checksum result)]
-      (when (and (some? recomputed-checksum)
-                 (worker-state/get-client-ops-conn repo))
-        (client-op/update-local-checksum repo recomputed-checksum))
-      (cond-> result
-        (some? recomputed-checksum)
-        (assoc :local-checksum recomputed-checksum)))))
-
-;; Returns an export-edn map for given repo. When there's an unexpected error, a map
-;; with key :export-edn-error is returned
-(def-thread-api :thread-api/export-edn
-  [repo options]
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (try
-      (sqlite-export/build-export @conn options)
-      (catch :default e
-        (js/console.error "export-edn error: " e)
-        (js/console.error "Stack:\n" (.-stack e))
-        (worker-util/post-message :notification
-                                  [nil :error nil nil nil {:i18n-key :export/error-unexpected}])
-        {:export-edn-error (.-message e)}))))
-
-(def-thread-api :thread-api/get-view-data
-  [repo view-id option]
-  (let [db @(worker-state/get-datascript-conn repo)]
-    (db-view/get-view-data db view-id option)))
-
-(def-thread-api :thread-api/get-class-objects
-  [repo class-id]
-  (let [db @(worker-state/get-datascript-conn repo)]
-    (->> (db-class/get-class-objects db class-id)
-         (map entity-util/entity->map))))
-
-(def-thread-api :thread-api/get-property-values
-  [repo {:keys [property-ident] :as option}]
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (db-view/get-property-values @conn property-ident option)))
-
-(def-thread-api :thread-api/get-bidirectional-properties
-  [repo {:keys [target-id]}]
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (worker-util/profile "get-bidirectional-properties"
-                         (ldb/get-bidirectional-properties @conn target-id))))
-
-(def-thread-api :thread-api/build-graph
-  [repo option]
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (graph-view/build-graph @conn option)))
-
-(def ^:private *get-all-page-titles-cache (volatile! (cache/lru-cache-factory {})))
-(defn- get-all-page-titles
-  [db]
-  (let [pages (ldb/get-all-pages db)]
-    (sort (map :block/title pages))))
-
-(def ^:private get-all-page-titles-with-cache
-  (common.cache/cache-fn
-   *get-all-page-titles-cache
-   (fn [repo]
-     (let [db @(worker-state/get-datascript-conn repo)]
-       [[repo (:max-tx db)] ;cache-key
-        [db]             ;f-args
-        ]))
-   get-all-page-titles))
-
-(def-thread-api :thread-api/get-all-page-titles
-  [repo]
-  (get-all-page-titles-with-cache repo))
-
-(def-thread-api :thread-api/gc-graph
-  [repo]
-  (let [{:keys [db client-ops]} (get @*sqlite-conns repo)
-        conn (get @*datascript-conns repo)]
-    (when (and db conn)
-      (gc-sqlite-dbs! db client-ops conn {:full-gc? true})
-      nil)))
-
-(def-thread-api :thread-api/mobile-logs
-  []
-  @worker-state/*log)
-
-(def-thread-api :thread-api/get-rtc-graph-uuid
-  [repo]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (ldb/get-graph-rtc-uuid @conn)))
-
-(def-thread-api :thread-api/api-get-page-data
-  [repo page-title]
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (cli-common-mcp-tools/get-page-data @conn page-title)))
-
-(def-thread-api :thread-api/api-list-properties
-  [repo options]
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (cli-common-mcp-tools/list-properties @conn options)))
-
-(def-thread-api :thread-api/api-list-tags
-  [repo options]
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (cli-common-mcp-tools/list-tags @conn options)))
-
-(def-thread-api :thread-api/api-list-pages
-  [repo options]
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (cli-common-mcp-tools/list-pages @conn options)))
-
-(def-thread-api :thread-api/api-build-upsert-nodes-edn
-  [repo ops]
-  (let [conn (worker-state/get-datascript-conn repo)]
-    (cli-common-mcp-tools/build-upsert-nodes-edn @conn ops)))
-
-(comment
-  (def-thread-api :general/dangerousRemoveAllDbs
-    []
-    (p/let [r (<list-all-dbs)
-            dbs (ldb/read-transit-str r)]
-      (p/all (map #(.unsafeUnlinkDB this (:name %)) dbs)))))
-
-(defn- on-become-master
-  [repo start-opts]
-  (js/Promise.
-   (m/sp
-     (c.m/<? (init-sqlite-module!))
-     (when-not (:import-type start-opts)
-       (c.m/<? (start-db! repo start-opts))
-       (assert (some? (worker-state/get-datascript-conn repo))))
-     nil)))
-
-(def broadcast-data-types
-  (set (map
-        common-util/keyword->string
-        [:sync-db-changes
-         :notification
-         :log
-         :add-repo
-         :rtc-log
-         :rtc-sync-state])))
-
-(defn- <init-service!
-  [graph start-opts]
-  (let [[prev-graph service] @*service]
-    (some-> prev-graph close-db!)
-    (when graph
-      (if (= graph prev-graph)
-        service
-        (p/let [service (shared-service/<create-service graph
-                                                        (bean/->js fns)
-                                                        #(on-become-master graph start-opts)
-                                                        broadcast-data-types
-                                                        {:import? (:import-type? start-opts)})]
-          (assert (p/promise? (get-in service [:status :ready])))
-          (reset! *service [graph service])
-          service)))))
-
-(defn- notify-invalid-data
-  [{:keys [tx-meta]} errors]
-  ;; don't notify on production when undo/redo failed
-
-  (when-not (and (or (:undo? tx-meta) (:redo? tx-meta))
-                 (not worker-util/dev?))
-    (shared-service/broadcast-to-clients! :notification
-                                          [nil :error nil nil nil
-                                           {:i18n-key :storage/invalid-data-writing}])
-    (worker-util/post-message :capture-error
-                              {:error (ex-info "Invalid data writing to db" tx-meta)
-                               :payload {}
-                               :extra {:errors (str errors)
-                                       :tx-meta tx-meta}})))
-
 (defn init
   "web worker entry"
   []
-  (idb/start)
-
-  (ldb/register-transact-invalid-callback-fn! notify-invalid-data)
-
-  (let [proxy-object (->>
-                      fns
-                      (map
-                       (fn [[k f]]
-                         [k
-                          (fn [& args]
-                            (let [[_graph service] @*service
-                                  method-k (keyword (first args))]
-                              (cond
-                                (= :thread-api/create-or-open-db method-k)
-                                ;; because shared-service operates at the graph level,
-                                ;; creating a new database or switching to another one requires re-initializing the service.
-                                (let [[graph opts] (ldb/read-transit-str (last args))]
-                                  (p/let [service (<init-service! graph opts)
-                                          client-id (:client-id service)]
-                                    (when client-id
-                                      (worker-util/post-message :record-worker-client-id {:client-id client-id}))
-                                    (get-in service [:status :ready])
-                                    ;; wait for service ready
-                                    (js-invoke (:proxy service) k args)))
-
-                                (or (= :thread-api/sync-app-state method-k)
-                                    (nil? service))
-                                ;; only proceed down this branch before shared-service is initialized
-                                (apply f args)
-
-                                :else
-                                ;; ensure service is ready
-                                (p/let [_ready-value (get-in service [:status :ready])]
-                                  (js-invoke (:proxy service) k args)))))]))
-                      (into {})
-                      bean/->js)]
+  (let [platform (platform-browser/browser-platform)
+        proxy-object (db-core/init-core! platform)]
+    (idb/start)
     (glogi-console/install!)
     (log/set-levels {:glogi/root :info})
     (log/add-handler worker-state/log-append!)
     (check-worker-scope!)
-    (js/setInterval #(.postMessage js/self "keepAliveResponse") (* 1000 25))
+    ((get-in platform [:timers :set-interval!])
+     #(.postMessage js/self "keepAliveResponse")
+     (* 1000 25))
     (Comlink/expose proxy-object)
     (let [^js wrapped-main-thread* (Comlink/wrap js/self)
           wrapped-main-thread (fn [qkw direct-pass? & args]
@@ -1250,13 +53,3 @@
                                     result
                                     (ldb/read-transit-str result))))]
       (reset! worker-state/*main-thread wrapped-main-thread))))
-
-(comment
-  (defn <remove-all-files!
-    "!! Dangerous: use it only for development."
-    []
-    (p/let [all-files (<list-all-files)
-            files (filter #(= (.-kind %) "file") all-files)
-            dirs (filter #(= (.-kind %) "directory") all-files)
-            _ (p/all (map (fn [file] (.remove file)) files))]
-      (p/all (map (fn [dir] (.remove dir)) dirs)))))
diff --git a/src/main/frontend/worker/db_worker_node.cljs b/src/main/frontend/worker/db_worker_node.cljs
new file mode 100644
index 0000000000..99f6db96ae
--- /dev/null
+++ b/src/main/frontend/worker/db_worker_node.cljs
@@ -0,0 +1,656 @@
+(ns frontend.worker.db-worker-node
+  "Node.js daemon entrypoint for db-worker."
+  (:require ["fs" :as fs]
+            ["http" :as http]
+            ["path" :as node-path]
+            [clojure.string :as string]
+            [frontend.worker.db-core :as db-core]
+            [frontend.worker.db-worker-node-lock :as db-lock]
+            [frontend.worker.platform.node :as platform-node]
+            [frontend.worker.state :as worker-state]
+            [frontend.worker.version :as worker-version]
+            [lambdaisland.glogi :as log]
+            [logseq.cli.root-dir :as root-dir]
+            [logseq.cli.style :as style]
+            [logseq.db :as ldb]
+            [logseq.db-worker.server-list :as server-list]
+            [promesa.core :as p]))
+
+(defonce ^:private *ready? (atom false))
+(defonce ^:private *sse-clients (atom #{}))
+(defonce ^:private *lock-info (atom nil))
+(defonce ^:private *file-handler (atom nil))
+(defonce ^:private *server-list-file (atom nil))
+
+(defn- server-list-file-path
+  [root-dir]
+  (server-list/path root-dir))
+
+(defn- send-json!
+  [^js res status payload]
+  (.writeHead res status #js {"Content-Type" "application/json"})
+  (.end res (js/JSON.stringify (clj->js payload))))
+
+(defn- send-text!
+  [^js res status text]
+  (.writeHead res status #js {"Content-Type" "text/plain"})
+  (.end res text))
+
+(defn- <read-body
+  [^js req]
+  (p/create
+   (fn [resolve reject]
+     (let [chunks (array)]
+       (.on req "data" (fn [chunk] (.push chunks chunk)))
+       (.on req "end" (fn []
+                        (let [buf (js/Buffer.concat chunks)]
+                          (resolve (.toString buf "utf8")))))
+       (.on req "error" reject)))))
+
+(defn- parse-args
+  [argv]
+  (loop [args (vec (drop 2 argv))
+         opts {}]
+    (if (empty? args)
+      opts
+      (let [flag (first args)]
+        (case flag
+          "--root-dir" (recur (subvec args 2) (assoc opts :root-dir (second args)))
+          "--repo" (recur (subvec args 2) (assoc opts :repo (second args)))
+          "--owner-source" (recur (subvec args 2) (assoc opts :owner-source (second args)))
+          "--log-level" (recur (subvec args 2) (assoc opts :log-level (second args)))
+          "--create-empty-db" (recur (subvec args 1) (assoc opts :create-empty-db? true))
+          "--version" (recur (subvec args 1) (assoc opts :version? true))
+          "--help" (recur (subvec args 1) (assoc opts :help? true))
+          (recur (subvec args 1) opts))))))
+
+(defn- normalize-owner-source
+  [owner-source]
+  (db-lock/normalize-owner-source owner-source))
+
+(defn- encode-event-type
+  [type]
+  (cond
+    (keyword? type) (subs (str type) 1)
+    (string? type) type
+    (nil? type) nil
+    :else (str type)))
+
+(defn- encode-event-payload
+  [payload]
+  (if (string? payload)
+    payload
+    (ldb/write-transit-str payload)))
+
+(defn- normalize-method-kw
+  [method]
+  (cond
+    (keyword? method) method
+    (string? method) (keyword method)
+    (nil? method) nil
+    :else (keyword (str method))))
+
+(defn- normalize-method-str
+  [method]
+  (cond
+    (keyword? method) (subs (str method) 1)
+    (string? method) method
+    (nil? method) nil
+    :else (str method)))
+
+(defn- handle-event!
+  [type payload]
+  (let [event (js/JSON.stringify (clj->js {:type (encode-event-type type)
+                                           :payload (encode-event-payload payload)}))
+        message (str "data: " event "\n\n")]
+    (doseq [^js res @*sse-clients]
+      (try
+        (.write res message)
+        (catch :default e
+          (log/error :sse-write-failed e))))))
+
+(defn- sse-handler
+  [^js req ^js res]
+  (.writeHead res 200 #js {"Content-Type" "text/event-stream"
+                           "Cache-Control" "no-cache"
+                           "Connection" "keep-alive"})
+  (.write res "\n")
+  (swap! *sse-clients conj res)
+  (.on req "close" (fn []
+                     (swap! *sse-clients disj res))))
+
+(defn- <invoke!
+  [^js proxy method-str method-kw direct-pass? args]
+  (let [args' (if direct-pass?
+                (into-array (or args []))
+                (if (string? args)
+                  args
+                  (ldb/write-transit-str args)))
+        started-at (js/Date.now)
+        timeout-id (js/setTimeout
+                    (fn []
+                      (log/warn :db-worker-node-invoke-timeout
+                                {:method (or method-kw method-str)
+                                 :elapsed-ms (- (js/Date.now) started-at)}))
+                    10000)]
+    (-> (p/do! (.remoteInvoke proxy method-str (boolean direct-pass?) args'))
+        (p/finally (fn []
+                     (js/clearTimeout timeout-id))))))
+
+(defn- <init-worker!
+  [proxy]
+  (let [method-kw :thread-api/init
+        method-str (normalize-method-str method-kw)]
+    (<invoke! proxy method-str method-kw true #js [])))
+
+(defn- <close-bound-repo!
+  [proxy repo]
+  (if (string/blank? repo)
+    (p/resolved nil)
+    (let [method-kw :thread-api/close-db
+          method-str (normalize-method-str method-kw)]
+      (-> (<invoke! proxy method-str method-kw false [repo])
+          (p/catch (fn [error]
+                     (log/warn :db-worker-node-close-db-before-stop-failed
+                               {:repo repo
+                                :error error})
+                     nil))))))
+
+(def ^:private non-repo-methods
+  #{:thread-api/init
+    :thread-api/set-db-sync-config
+    :thread-api/get-db-sync-config
+    :thread-api/db-sync-stop
+    :thread-api/db-sync-list-remote-graphs
+    :thread-api/db-sync-update-presence
+    :thread-api/db-sync-ensure-user-rsa-keys
+    :thread-api/list-db
+    :thread-api/get-version
+    :thread-api/set-context
+    :thread-api/sync-app-state
+    :thread-api/update-thread-atom
+    :thread-api/mobile-logs
+    :thread-api/rtc-start
+    :thread-api/rtc-stop
+    :thread-api/rtc-toggle-auto-push
+    :thread-api/rtc-toggle-remote-profile
+    :thread-api/rtc-grant-graph-access
+    :thread-api/rtc-get-graphs
+    :thread-api/rtc-delete-graph
+    :thread-api/rtc-get-users-info
+    :thread-api/rtc-get-block-content-versions
+    :thread-api/rtc-get-debug-state
+    :thread-api/rtc-request-download-graph
+    :thread-api/rtc-wait-download-graph-info-ready
+    :thread-api/rtc-download-graph-from-s3
+    :thread-api/get-user-rsa-key-pair
+    :thread-api/init-user-rsa-key-pair
+    :thread-api/reset-user-rsa-key-pair
+    :thread-api/change-e2ee-password
+    :thread-api/get-e2ee-password
+    :thread-api/save-e2ee-password
+    :thread-api/verify-and-save-e2ee-password
+    :thread-api/resolve-ui-request
+    :thread-api/reject-ui-request
+    :thread-api/cancel-ui-requests})
+
+(def ^:private write-methods
+  #{:thread-api/transact
+    :thread-api/import-db
+    :thread-api/import-db-base64
+    :thread-api/backup-db-sqlite
+    :thread-api/import-edn
+    :thread-api/unsafe-unlink-db
+    :thread-api/search-upsert-blocks
+    :thread-api/search-delete-blocks
+    :thread-api/search-truncate-tables})
+
+(defn- repo-arg
+  [args]
+  (cond
+    (js/Array.isArray args) (aget args 0)
+    (sequential? args) (first args)
+    :else nil))
+
+(defn- repo-error
+  [method args bound-repo]
+  (let [method-kw (normalize-method-kw method)]
+    (when-not (contains? non-repo-methods method-kw)
+      (let [repo (repo-arg args)]
+        (cond
+          (or (not (string? repo))
+              (string/blank? repo))
+          {:status 400
+           :error {:code :missing-repo
+                   :message "repo is required"}}
+
+          (not= repo bound-repo)
+          {:status 409
+           :error {:code :repo-mismatch
+                   :message "repo does not match bound repo"
+                   :repo repo
+                   :bound-repo bound-repo}}
+
+          :else
+          nil)))))
+
+(defn- set-main-thread-stub!
+  []
+  (reset! worker-state/*main-thread
+          (fn [qkw _direct-pass? & _args]
+            (p/rejected (ex-info "main-thread is not available in db-worker-node"
+                                 {:method qkw})))))
+
+(defn- query-validation-error?
+  [data]
+  (= :parser/query (:error data)))
+
+(defn- notification-validation-error?
+  [data]
+  (= :notification (:type data)))
+
+(defn- invoke-error-status
+  [data]
+  (cond
+    (query-validation-error? data) 400
+    (notification-validation-error? data) 400
+    (#{:missing-repo :repo-mismatch :repo-locked} (:code data)) 409
+    (number? (:status data)) (:status data)
+    :else 500))
+
+(defn- invoke-error-code
+  [data]
+  (cond
+    (query-validation-error? data) :invalid-query
+    (:code data) (:code data)
+    (notification-validation-error? data) :validation-error
+    :else :exception))
+
+(defn- invoke-error-message
+  [error data]
+  (or (get-in data [:payload :message])
+      (.-message error)
+      (str error)))
+
+(defn- health-payload
+  [{:keys [bound-repo host port owner-source root-dir]}]
+  {:repo bound-repo
+   :status (if @*ready? "ready" "starting")
+   :host host
+   :port (if (satisfies? IDeref port) @port port)
+   :pid (.-pid js/process)
+   :owner-source (name (normalize-owner-source owner-source))
+   :root-dir root-dir
+   :revision (worker-version/revision)})
+
+(defn- make-server
+  [proxy {:keys [bound-repo stop-fn host port owner-source root-dir]}]
+  (http/createServer
+   (fn [^js req ^js res]
+     (let [url (.-url req)
+           method (.-method req)]
+       (cond
+         (= url "/healthz")
+         (send-json! res (if @*ready? 200 503)
+                     (health-payload {:bound-repo bound-repo
+                                      :host host
+                                      :port port
+                                      :owner-source owner-source
+                                      :root-dir root-dir}))
+
+         (= url "/v1/events")
+         (sse-handler req res)
+
+         (= url "/v1/invoke")
+         (if (= method "POST")
+           (-> (p/let [body (<read-body req)
+                       payload (js/JSON.parse body)
+                       {:keys [method directPass argsTransit args]} (js->clj payload :keywordize-keys true)
+                       method-kw (normalize-method-kw method)
+                       method-str (normalize-method-str method)
+                       direct-pass? (boolean directPass)
+                       args' (if direct-pass?
+                               args
+                               (or argsTransit args))
+                       args-for-validation (if direct-pass?
+                                             args'
+                                             (if (string? args')
+                                               (ldb/read-transit-str args')
+                                               args'))]
+                 (if-let [{:keys [status error]} (repo-error method-kw args-for-validation bound-repo)]
+                   (send-json! res status {:ok false :error error})
+                   (p/let [_ (when (contains? write-methods method-kw)
+                               (let [{:keys [path lock]} @*lock-info]
+                                 (db-lock/assert-lock-owner! path lock)))
+                           result (<invoke! proxy method-str method-kw direct-pass? args')]
+                     (send-json! res 200 (if direct-pass?
+                                           {:ok true :result result}
+                                           {:ok true :resultTransit result})))))
+               (p/catch (fn [error]
+                          (let [data (ex-data error)
+                                status (invoke-error-status data)
+                                code (invoke-error-code data)
+                                message (invoke-error-message error data)
+                                payload {:ok false
+                                         :error {:code code
+                                                 :message message}}]
+                            (log/error :db-worker-node-invoke-failed
+                                       {:status status
+                                        :code code
+                                        :message message})
+                            (send-json! res status payload)))))
+           (send-text! res 405 "method-not-allowed"))
+
+         (= url "/v1/shutdown")
+         (if (= method "POST")
+           (do
+             (send-json! res 200 {:ok true})
+             (js/setTimeout (fn []
+                              (when stop-fn
+                                (stop-fn)))
+                            10))
+           (send-text! res 405 "method-not-allowed"))
+
+         :else
+         (send-text! res 404 "not-found"))))))
+
+(defn- show-help!
+  []
+  (println (str (style/bold "db-worker-node") " " (style/bold "options") ":"))
+  (println (str "  " (style/bold "--root-dir") " <path>    (required)"))
+  (println (str "  " (style/bold "--repo") " <name>        (required)"))
+  (println (str "  " (style/bold "--create-empty-db") "  (start with empty initial datoms)"))
+  (println (str "  " (style/bold "--log-level") " <level>  (default info)"))
+  (println (str "  " (style/bold "--version") "            (print build metadata and exit)"))
+  (println "  logs: <root-dir>/graphs/<graph-dir>/db-worker-node-YYYYMMDD.log (retains 7)"))
+
+(defn- startup-db-opts
+  [{:keys [create-empty-db?]}]
+  (if create-empty-db?
+    {:datoms []
+     :sync-download-graph? true}
+    {}))
+
+(defn- pad2
+  [value]
+  (if (< value 10)
+    (str "0" value)
+    (str value)))
+
+(defn- yyyymmdd
+  [^js date]
+  (str (.getFullYear date)
+       (pad2 (inc (.getMonth date)))
+       (pad2 (.getDate date))))
+
+(defn- log-path
+  [root-dir repo]
+  (let [root-dir (db-lock/resolve-root-dir root-dir)
+        repo-dir (db-lock/repo-dir (db-lock/graphs-dir root-dir) repo)
+        date-str (yyyymmdd (js/Date.))]
+    (node-path/join repo-dir (str "db-worker-node-" date-str ".log"))))
+
+(defn- log-files
+  [repo-dir]
+  (->> (when (fs/existsSync repo-dir)
+         (fs/readdirSync repo-dir))
+       (filter (fn [^js name]
+                 (re-matches #"db-worker-node-\d{8}\.log" name)))
+       (sort)))
+
+(defn- enforce-log-retention!
+  [repo-dir]
+  (let [files (log-files repo-dir)
+        excess (max 0 (- (count files) 7))]
+    (doseq [name (take excess files)]
+      (fs/unlinkSync (node-path/join repo-dir name)))))
+
+(defn- format-log-line
+  [{:keys [time level message logger-name exception]}]
+  (let [ts (.toISOString (js/Date. time))
+        base (str ts
+                  " ["
+                  (name level)
+                  "] ["
+                  logger-name
+                  "] "
+                  (pr-str message))]
+    (str base (when exception (str " " (pr-str exception))) "\n")))
+
+(defn- install-file-logger!
+  [{:keys [root-dir repo log-level]}]
+  (let [root-dir (db-lock/resolve-root-dir root-dir)
+        repo-dir (db-lock/repo-dir (db-lock/graphs-dir root-dir) repo)
+        file-path (log-path root-dir repo)]
+    (fs/mkdirSync repo-dir #js {:recursive true})
+    (fs/writeFileSync file-path "" #js {:flag "a"})
+    (enforce-log-retention! repo-dir)
+    (when-let [handler @*file-handler]
+      (log/remove-handler handler))
+    (let [handler (fn [record]
+                    (fs/appendFileSync file-path (format-log-line record)))]
+      (reset! *file-handler handler)
+      (log/add-handler handler))
+    (log/set-levels {:glogi/root log-level})
+    file-path))
+
+(defn- assert-lock-owner!
+  []
+  (let [{:keys [path lock]} @*lock-info]
+    (db-lock/assert-lock-owner! path lock)))
+
+(defn- recreate-lock!
+  [target-repo]
+  (p/let [{:keys [path lock]} @*lock-info
+          _ (when-not (and (seq path) lock)
+              (throw (ex-info "lock owner missing"
+                              {:code :repo-locked
+                               :repo target-repo})))
+          _ (when (and (seq target-repo)
+                       (not= target-repo (:repo lock)))
+              (throw (ex-info "graph lock repo mismatch"
+                              {:code :repo-locked
+                               :repo target-repo
+                               :bound-repo (:repo lock)})))
+          updated-lock (db-lock/update-lock! path lock)]
+    (swap! *lock-info assoc :lock updated-lock)
+    nil))
+
+(defn- close-server!
+  [server]
+  (p/create
+   (fn [resolve _]
+     (try
+       (.close server (fn [] (resolve true)))
+       (catch :default _
+         (resolve true))))))
+
+(defn- clear-runtime-state!
+  [actual-port]
+  (reset! *ready? false)
+  (when-let [file-path @*server-list-file]
+    (server-list/remove-entry! file-path {:pid (.-pid js/process)
+                                          :port actual-port}))
+  (doseq [^js res @*sse-clients]
+    (try
+      (.end res)
+      (catch :default _)))
+  (reset! *sse-clients #{})
+  (when-let [lock-path (:path @*lock-info)]
+    (db-lock/remove-lock! lock-path)))
+
+(defn- make-stop!
+  [{:keys [proxy repo actual-port server stopped? on-stopped!]}]
+  (fn []
+    (if @stopped?
+      (p/resolved true)
+      (do
+        (reset! stopped? true)
+        (-> (p/let [_ (<close-bound-repo! proxy repo)]
+              (clear-runtime-state! actual-port)
+              (close-server! server)
+              true)
+            (p/finally
+             (fn []
+               (when (fn? on-stopped!)
+                 (on-stopped!)))))))))
+
+(defn- resolve-listening-daemon!
+  [{:keys [server proxy repo host port* stop!* stopped? on-stopped!]} resolve]
+  (let [address (.address server)
+        actual-port (if (number? address) address (.-port address))
+        _ (reset! port* actual-port)
+        stop! (make-stop! {:proxy proxy
+                           :repo repo
+                           :actual-port actual-port
+                           :server server
+                           :stopped? stopped?
+                           :on-stopped! on-stopped!})]
+    (reset! *ready? true)
+    (when-let [file-path @*server-list-file]
+      (server-list/append-entry! file-path {:pid (.-pid js/process)
+                                            :port actual-port}))
+    (reset! stop!* stop!)
+    (resolve {:host host
+              :port actual-port
+              :server server
+              :stop! stop!})))
+
+(defn- start-http-server!
+  [{:keys [proxy repo host port owner-source root-dir on-stopped!]}]
+  (let [stop!* (atom nil)
+        stopped? (atom false)
+        port* (atom nil)
+        server (make-server proxy {:bound-repo repo
+                                   :host host
+                                   :port port*
+                                   :owner-source owner-source
+                                   :root-dir root-dir
+                                   :stop-fn (fn []
+                                              (when-let [stop! @stop!*]
+                                                (stop!)))})]
+    (p/create
+     (fn [resolve reject]
+       (.listen server port host
+                (fn []
+                  (resolve-listening-daemon! {:server server
+                                              :proxy proxy
+                                              :repo repo
+                                              :host host
+                                              :port* port*
+                                              :stop!* stop!*
+                                              :stopped? stopped?
+                                              :owner-source owner-source
+                                              :root-dir root-dir
+                                              :on-stopped! on-stopped!}
+                                             resolve)))
+       (.on server "error" (fn [error]
+                              (when-let [lock-path (:path @*lock-info)]
+                                (db-lock/remove-lock! lock-path))
+                              (reject error)))))))
+
+(defn start-daemon!
+  [{:keys [root-dir repo log-level owner-source on-stopped!] :as opts}]
+  (let [host "127.0.0.1"
+        port 0
+        owner-source (normalize-owner-source owner-source)]
+    (cond
+      (not (seq root-dir))
+      (p/rejected (ex-info "root-dir is required" {:code :missing-root-dir}))
+
+      (not (seq repo))
+      (p/rejected (ex-info "repo is required" {:code :missing-repo}))
+
+      :else
+      (try
+        (let [root-dir (root-dir/ensure-root-dir! root-dir)
+              server-list-file (server-list-file-path root-dir)]
+          (install-file-logger! {:root-dir root-dir
+                                 :repo repo
+                                 :log-level (keyword (or log-level "info"))})
+          (reset! *ready? false)
+          (reset! *lock-info nil)
+          (reset! *server-list-file server-list-file)
+          (set-main-thread-stub!)
+          (-> (p/let [platform (platform-node/node-platform {:root-dir root-dir
+                                                             :event-fn handle-event!
+                                                             :write-guard-fn assert-lock-owner!
+                                                             :owner-source owner-source
+                                                             :recreate-lock-fn recreate-lock!})
+                      proxy (db-core/init-core! platform)
+                      _ (<init-worker! proxy)
+                      {:keys [path lock]} (db-lock/ensure-lock! {:root-dir root-dir
+                                                                 :repo repo
+                                                                 :owner-source owner-source})
+                      _ (reset! *lock-info {:path path :lock lock})
+                      _ (let [method-kw :thread-api/create-or-open-db
+                              method-str (normalize-method-str method-kw)]
+                          (<invoke! proxy method-str method-kw false [repo (startup-db-opts opts)]))]
+                (start-http-server! {:proxy proxy
+                                     :repo repo
+                                     :host host
+                                     :port port
+                                     :owner-source owner-source
+                                     :root-dir root-dir
+                                     :on-stopped! on-stopped!}))
+              (p/catch (fn [e]
+                         (when-let [lock-path (:path @*lock-info)]
+                           (db-lock/remove-lock! lock-path))
+                         (throw e)))))
+        (catch :default e
+          (p/rejected e))))))
+
+(defn main
+  []
+  (let [{:keys [root-dir repo help? version? owner-source] :as opts}
+        (parse-args (.-argv js/process))]
+    (when help?
+      (show-help!)
+      (.exit js/process 0))
+    (when version?
+      (println (worker-version/format-version))
+      (.exit js/process 0))
+    (when-not (seq root-dir)
+      (.error js/console "root-dir is required")
+      (.exit js/process 1))
+    (when-not (seq repo)
+      (.error js/console "repo is required")
+      (.exit js/process 1))
+    (-> (p/let [{:keys [stop!] :as daemon}
+                (start-daemon! {:root-dir root-dir
+                                :repo repo
+                                :create-empty-db? (:create-empty-db? opts)
+                                :owner-source owner-source
+                                :on-stopped! (fn []
+                                               (log/info :db-worker-node-stopped nil)
+                                               (.exit js/process 0))
+                                :log-level (:log-level opts)})]
+          (log/info :db-worker-node-ready {:host (:host daemon) :port (:port daemon)})
+          (let [shutdown (fn [] (stop!))]
+            (.on js/process "SIGINT" shutdown)
+            (.on js/process "SIGTERM" shutdown)))
+        (p/catch (fn [error]
+                   (let [data (ex-data error)
+                         code (:code data)
+                         message (or (.-message error) (str error))]
+                     (cond
+                       (#{:missing-root-dir :root-dir-permission} code)
+                       (.error js/console message)
+
+                       (or (string/includes? message ".node")
+                           (string/includes? message "Cannot find module")
+                           (string/includes? message "MODULE_NOT_FOUND")
+                           (string/includes? message "bindings file"))
+                       (.error js/console
+                               (str "db-worker-node failed to start: bundled runtime files are missing or incomplete. "
+                                    "Rebuild with `pnpm db-worker-node:release:bundle` and ensure "
+                                    "`dist/db-worker-node.js` exists and assets listed in "
+                                    "`dist/db-worker-node-assets.json` are next to it. "
+                                    "Root error: "
+                                    message))
+
+                       :else
+                       (.error js/console (str "db-worker-node failed to start: " message)))
+                     (when-let [stack (.-stack error)]
+                       (.error js/console stack))
+                     (.exit js/process 1)))))))
diff --git a/src/main/frontend/worker/db_worker_node_lock.cljs b/src/main/frontend/worker/db_worker_node_lock.cljs
new file mode 100644
index 0000000000..74d2646ccc
--- /dev/null
+++ b/src/main/frontend/worker/db_worker_node_lock.cljs
@@ -0,0 +1,193 @@
+(ns frontend.worker.db-worker-node-lock
+  "Lock file helpers for db-worker-node."
+  (:require ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]
+            [clojure.string :as string]
+            [frontend.worker-common.util :as worker-util]
+            [lambdaisland.glogi :as log]
+            [logseq.common.graph-dir :as graph-dir]
+            [logseq.common.config :as common-config]
+            [promesa.core :as p]))
+
+(defn- expand-home
+  [path]
+  (if (string/starts-with? path "~")
+    (node-path/join (.homedir os) (subs path 1))
+    path))
+
+(defn resolve-root-dir
+  [root-dir]
+  (expand-home (or root-dir (node-path/join (.homedir os) "logseq"))))
+
+(defn graphs-dir
+  [root-dir]
+  (node-path/join (resolve-root-dir root-dir) "graphs"))
+
+(defn repo->graph-dir-key
+  [repo]
+  (graph-dir/repo->graph-dir-key repo))
+
+(defn canonical-graph-dir-key?
+  [graph-dir-key]
+  (and (seq graph-dir-key)
+       (not (string/starts-with? graph-dir-key common-config/db-version-prefix))))
+
+(defn decode-canonical-graph-dir-key
+  [encoded-graph-dir-key]
+  (let [decoded (worker-util/decode-graph-dir-name encoded-graph-dir-key)]
+    (when (canonical-graph-dir-key? decoded)
+      decoded)))
+
+(defn repo-dir
+  [graphs-root repo]
+  (node-path/join graphs-root (worker-util/encode-graph-dir-name (repo->graph-dir-key repo))))
+
+(defn lock-path
+  [root-dir repo]
+  (node-path/join (repo-dir (graphs-dir root-dir) repo) "db-worker.lock"))
+
+(defn- pid-status
+  [pid]
+  (when (number? pid)
+    (try
+      (.kill js/process pid 0)
+      :alive
+      (catch :default e
+        (case (.-code e)
+          "ESRCH" :not-found
+          "EPERM" :no-permission
+          :error)))))
+
+(def ^:private valid-owner-sources
+  #{:cli :electron :unknown})
+
+(defn normalize-owner-source
+  [owner-source]
+  (let [owner-source (cond
+                       (keyword? owner-source) owner-source
+                       (string? owner-source) (keyword owner-source)
+                       :else :unknown)]
+    (if (contains? valid-owner-sources owner-source)
+      owner-source
+      :unknown)))
+
+(defn- normalize-lock
+  [lock]
+  (when lock
+    (assoc lock :owner-source (normalize-owner-source (:owner-source lock)))))
+
+(defn read-lock
+  [path]
+  (when (and (seq path) (fs/existsSync path))
+    (normalize-lock
+     (js->clj (js/JSON.parse (.toString (fs/readFileSync path) "utf8"))
+              :keywordize-keys true))))
+
+(defn remove-lock!
+  [path]
+  (when (and (seq path) (fs/existsSync path))
+    (fs/unlinkSync path)))
+
+(defn create-lock!
+  [{:keys [root-dir repo owner-source]}]
+  (p/create
+   (fn [resolve reject]
+     (try
+       (let [root-dir (resolve-root-dir root-dir)
+             path (lock-path root-dir repo)
+             existing (read-lock path)]
+         (when (and existing (contains? #{:alive :no-permission} (pid-status (:pid existing))))
+           (throw (ex-info "graph already locked" {:code :repo-locked :lock existing})))
+         (when (and existing (= :not-found (pid-status (:pid existing))))
+           (remove-lock! path))
+         (fs/mkdirSync (node-path/dirname path) #js {:recursive true})
+         (let [fd (fs/openSync path "wx")
+               lock {:repo repo
+                     :pid (.-pid js/process)
+                     :lock-id (str (random-uuid))
+                     :owner-source (normalize-owner-source owner-source)}]
+           (try
+             (fs/writeFileSync fd (js/JSON.stringify (clj->js lock)))
+             (finally
+               (fs/closeSync fd)))
+           (resolve lock)))
+       (catch :default e
+         (log/error :db-worker-node-lock-create-failed e)
+         (reject e))))))
+
+(defn update-lock!
+  [path lock]
+  (p/create
+   (fn [resolve reject]
+     (try
+       (let [existing (read-lock path)
+             lock' (if existing
+                     {:repo (:repo existing)
+                      :pid (:pid existing)
+                      :lock-id (or (:lock-id existing) (:lock-id lock))
+                      :owner-source (normalize-owner-source (:owner-source existing))}
+                     {:repo (:repo lock)
+                      :pid (:pid lock)
+                      :lock-id (:lock-id lock)
+                      :owner-source (normalize-owner-source (:owner-source lock))})]
+         (fs/mkdirSync (node-path/dirname path) #js {:recursive true})
+         (fs/writeFileSync path (js/JSON.stringify (clj->js lock')))
+         (resolve lock'))
+       (catch :default e
+         (log/error :db-worker-node-lock-update-failed e)
+         (reject e))))))
+
+(defn assert-lock-owner!
+  [path {:keys [repo pid lock-id] :as owner-lock}]
+  (let [lock (read-lock path)]
+    (cond
+      (nil? owner-lock)
+      (throw (ex-info "lock owner missing"
+                      {:code :repo-locked
+                       :path path}))
+
+      (nil? lock)
+      (throw (ex-info "graph lock missing"
+                      {:code :repo-locked
+                       :path path}))
+
+      (not= :alive (pid-status (:pid lock)))
+      (throw (ex-info "graph lock is stale"
+                      {:code :repo-locked
+                       :path path
+                       :lock lock}))
+
+      (not= repo (:repo lock))
+      (throw (ex-info "graph lock repo mismatch"
+                      {:code :repo-locked
+                       :path path
+                       :lock lock
+                       :owner owner-lock}))
+
+      (not= pid (:pid lock))
+      (throw (ex-info "graph lock pid mismatch"
+                      {:code :repo-locked
+                       :path path
+                       :lock lock
+                       :owner owner-lock}))
+
+      (not= lock-id (:lock-id lock))
+      (throw (ex-info "graph lock-id mismatch"
+                      {:code :repo-locked
+                       :path path
+                       :lock lock
+                       :owner owner-lock}))
+
+      :else
+      lock)))
+
+(defn ensure-lock!
+  [{:keys [root-dir repo owner-source]}]
+  (let [root-dir (resolve-root-dir root-dir)
+        path (lock-path root-dir repo)]
+    (p/let [lock (create-lock! {:root-dir root-dir
+                                :repo repo
+                                :owner-source owner-source})]
+      {:path path
+       :lock lock})))
diff --git a/src/main/frontend/worker/graph_dir.cljs b/src/main/frontend/worker/graph_dir.cljs
new file mode 100644
index 0000000000..5ea011c440
--- /dev/null
+++ b/src/main/frontend/worker/graph_dir.cljs
@@ -0,0 +1,8 @@
+(ns frontend.worker.graph-dir
+  "Compatibility wrapper around `logseq.common.graph-dir`."
+  (:require [logseq.common.graph-dir :as common-graph-dir]))
+
+(def repo->graph-dir-key common-graph-dir/repo->graph-dir-key)
+(def repo->encoded-graph-dir-name common-graph-dir/repo->encoded-graph-dir-name)
+(def decode-graph-dir-name common-graph-dir/decode-graph-dir-name)
+(def decode-legacy-graph-dir-name common-graph-dir/decode-legacy-graph-dir-name)
diff --git a/src/main/frontend/worker/platform.cljs b/src/main/frontend/worker/platform.cljs
new file mode 100644
index 0000000000..89bf300c6b
--- /dev/null
+++ b/src/main/frontend/worker/platform.cljs
@@ -0,0 +1,154 @@
+(ns frontend.worker.platform
+  "Platform adapter contract for db-worker runtimes.")
+
+(defn- normalize-missing-value
+  [value]
+  (if (identical? js/undefined value)
+    nil
+    value))
+
+(def ^:private required-sections
+  [:env :storage :kv :broadcast :websocket :crypto :timers :sqlite])
+
+(defonce ^:private *platform (atom nil))
+
+(defn validate-platform!
+  [platform]
+  (doseq [section required-sections]
+    (when-not (contains? platform section)
+      (throw (ex-info (str "platform adapter missing section: " section)
+                      {:section section
+                       :platform-keys (keys platform)}))))
+  platform)
+
+(defn set-platform!
+  [platform]
+  (reset! *platform (validate-platform! platform)))
+
+(defn current
+  []
+  (or @*platform
+      (throw (ex-info "platform adapter not initialized" {}))))
+
+(defn env-flag
+  [platform flag]
+  (get-in platform [:env flag]))
+
+(defn storage
+  [platform]
+  (:storage platform))
+
+(defn install-storage-pool
+  [platform sqlite pool-name]
+  (if-let [f (get-in platform [:storage :install-opfs-pool])]
+    (f sqlite pool-name)
+    (throw (ex-info "platform storage/install-opfs-pool missing"
+                    {:pool-name pool-name}))))
+
+(defn resolve-db-path
+  [platform repo pool path]
+  (if-let [f (get-in platform [:storage :resolve-db-path])]
+    (f repo pool path)
+    path))
+
+(defn remove-storage-pool!
+  [platform pool]
+  (if-let [f (get-in platform [:storage :remove-vfs!])]
+    (f pool)
+    nil))
+
+(defn kv-get
+  [platform k]
+  (if-let [f (get-in platform [:kv :get])]
+    (-> (f k)
+        (.then normalize-missing-value))
+    (throw (ex-info "platform kv/get missing" {:key k}))))
+
+(defn kv-set!
+  [platform k value]
+  (if-let [f (get-in platform [:kv :set!])]
+    (f k value)
+    (throw (ex-info "platform kv/set! missing" {:key k}))))
+
+(defn read-text!
+  [platform path]
+  (if-let [f (get-in platform [:storage :read-text!])]
+    (f path)
+    (throw (ex-info "platform storage/read-text! missing" {:path path}))))
+
+(defn write-text!
+  [platform path text]
+  (if-let [f (get-in platform [:storage :write-text!])]
+    (f path text)
+    (throw (ex-info "platform storage/write-text! missing" {:path path}))))
+
+(defn asset-read-bytes!
+  [platform repo file-name]
+  (if-let [f (get-in platform [:storage :asset-read-bytes!])]
+    (f repo file-name)
+    (throw (ex-info "platform storage/asset-read-bytes! missing"
+                    {:repo repo
+                     :file-name file-name}))))
+
+(defn asset-write-bytes!
+  [platform repo file-name payload]
+  (if-let [f (get-in platform [:storage :asset-write-bytes!])]
+    (f repo file-name payload)
+    (throw (ex-info "platform storage/asset-write-bytes! missing"
+                    {:repo repo
+                     :file-name file-name}))))
+
+(defn asset-stat
+  [platform repo file-name]
+  (if-let [f (get-in platform [:storage :asset-stat])]
+    (f repo file-name)
+    (throw (ex-info "platform storage/asset-stat missing"
+                    {:repo repo
+                     :file-name file-name}))))
+
+(defn save-secret-text!
+  [platform key text]
+  (if-let [f (get-in platform [:crypto :save-secret-text!])]
+    (f key text)
+    (throw (ex-info "platform crypto/save-secret-text! missing" {:key key}))))
+
+(defn read-secret-text
+  [platform key]
+  (if-let [f (get-in platform [:crypto :read-secret-text])]
+    (-> (f key)
+        (.then normalize-missing-value))
+    (throw (ex-info "platform crypto/read-secret-text missing" {:key key}))))
+
+(defn delete-secret-text!
+  [platform key]
+  (if-let [f (get-in platform [:crypto :delete-secret-text!])]
+    (f key)
+    (throw (ex-info "platform crypto/delete-secret-text! missing" {:key key}))))
+
+(defn websocket-connect
+  [platform url]
+  (if-let [f (get-in platform [:websocket :connect])]
+    (f url)
+    (throw (ex-info "platform websocket/connect missing" {:url url}))))
+
+(defn sqlite-init!
+  [platform]
+  (when-let [f (get-in platform [:sqlite :init!])]
+    (f)))
+
+(defn sqlite-open
+  [platform opts]
+  (if-let [f (get-in platform [:sqlite :open-db])]
+    (f opts)
+    (throw (ex-info "platform sqlite/open-db missing" {:opts opts}))))
+
+(defn post-message!
+  [platform type payload]
+  (when-let [f (get-in platform [:broadcast :post-message!])]
+    (f type payload)))
+
+(defn transfer
+  [platform data transferables]
+  (if-let [f (get-in platform [:storage :transfer])]
+    (f data transferables)
+    data))
diff --git a/src/main/frontend/worker/platform/browser.cljs b/src/main/frontend/worker/platform/browser.cljs
new file mode 100644
index 0000000000..763bbd1a2c
--- /dev/null
+++ b/src/main/frontend/worker/platform/browser.cljs
@@ -0,0 +1,222 @@
+(ns frontend.worker.platform.browser
+  "Browser platform adapter for db-worker."
+  (:require [frontend.common.idb :as idb]
+            ["@sqlite.org/sqlite-wasm" :default sqlite3InitModule]
+            ["comlink" :as Comlink]
+            [clojure.string :as string]
+            [frontend.common.file.opfs :as opfs]
+            [frontend.worker-common.util :as worker-util]
+            [lambdaisland.glogi :as log]
+            [logseq.common.config :as common-config]
+            [logseq.common.path :as path]
+            [promesa.core :as p]))
+
+(defn- iter->vec
+  [iter']
+  (when iter'
+    (p/loop [acc []]
+      (p/let [elem (.next iter')]
+        (if (.-done elem)
+          acc
+          (p/recur (conj acc (.-value elem))))))))
+
+(defn- list-graphs
+  []
+  (let [dir? #(= (.-kind %) "directory")
+        db-dir-prefix ".logseq-pool-"]
+    (p/let [^js root (.getDirectory js/navigator.storage)
+            values-iter (when (dir? root) (.values root))
+            values (when values-iter (iter->vec values-iter))
+            current-dir-dirs (filter dir? values)
+            db-dirs (filter (fn [file]
+                              (string/starts-with? (.-name file) db-dir-prefix))
+                            current-dir-dirs)
+            graph-names (map (fn [dir]
+                               (-> (.-name dir)
+                                   (string/replace-first ".logseq-pool-" "")
+                                   ;; TODO: DRY
+                                   (string/replace "+3A+" ":")
+                                   (string/replace "++" "/")))
+                             db-dirs)]
+      (log/info :db-dirs (map #(.-name %) db-dirs) :all-dirs (map #(.-name %) current-dir-dirs))
+      (vec graph-names))))
+
+(defn- db-exists?
+  [graph]
+  (->
+   (p/let [^js root (.getDirectory js/navigator.storage)
+           _dir-handle (.getDirectoryHandle root (str "." (worker-util/get-pool-name graph)))]
+     true)
+    (p/catch
+    (fn [_e]                         ; not found
+      false))))
+
+(defn- kv-get
+  [k]
+  (idb/get-item k))
+
+(defn- kv-set!
+  [k value]
+  (idb/set-item! k value))
+
+(defn- save-secret-text!
+  [key text]
+  (kv-set! key text))
+
+(defn- read-secret-text
+  [key]
+  (kv-get key))
+
+(defn- delete-secret-text!
+  [key]
+  (kv-set! key nil))
+
+(defn- install-opfs-pool
+  [sqlite pool-name]
+  (.installOpfsSAHPoolVfs ^js sqlite #js {:name pool-name
+                                          :initialCapacity 20}))
+
+(defn- export-file
+  [pool path]
+  (.exportFile ^js pool path))
+
+(defn- import-db
+  [pool path data]
+  (.importDb ^js pool path data))
+
+(defn- remove-vfs!
+  [pool]
+  (when pool
+    (.removeVfs ^js pool)))
+
+(defn- read-text!
+  [path]
+  (opfs/<read-text! path))
+
+(defn- write-text!
+  [path text]
+  (opfs/<write-text! path text))
+
+(defn- browser-pfs
+  []
+  (or (some-> js/globalThis .-window .-pfs)
+      (some-> js/globalThis .-pfs)
+      (throw (ex-info "browser pfs is not available" {}))))
+
+(defn- graph-assets-dir
+  [repo]
+  (when-let [graph-name (some-> repo common-config/strip-leading-db-version-prefix)]
+    (str "/" graph-name "/assets")))
+
+(defn- ensure-pfs-dir!
+  [^js pfs dir]
+  (cond
+    (or (nil? dir) (= "" dir) (= "/" dir) (= "." dir))
+    (p/resolved nil)
+
+    :else
+    (-> (.stat pfs dir)
+        (p/then (constantly nil))
+        (p/catch
+         (fn [_]
+           (p/do!
+            (ensure-pfs-dir! pfs (path/parent dir))
+            (.mkdir pfs dir)))))))
+
+(defn- asset-path
+  [repo file-name]
+  (if-let [assets-dir (graph-assets-dir repo)]
+    (path/path-join assets-dir file-name)
+    (throw (ex-info "missing repo for browser asset path"
+                    {:repo repo
+                     :file-name file-name}))))
+
+(defn- asset-read-bytes!
+  [repo file-name]
+  (when-let [^js bfs (browser-pfs)]
+    (.readFile bfs (asset-path repo file-name))))
+
+(defn- asset-write-bytes!
+  [repo file-name payload]
+  (let [^js pfs (browser-pfs)
+        file-path (asset-path repo file-name)]
+    (p/do!
+     (ensure-pfs-dir! pfs (path/parent file-path))
+     (.writeFile pfs file-path payload))))
+
+(defn- asset-stat
+  [repo file-name]
+  (let [^js pfs (browser-pfs)]
+    (-> (.stat pfs (asset-path repo file-name))
+        (p/then (fn [^js stat]
+                  {:size (.-size stat)
+                   :type (.-type stat)}))
+        (p/catch (constantly nil)))))
+
+(defn- asset-delete!
+  [repo file-name]
+  (-> (.unlink (browser-pfs) (asset-path repo file-name))
+      (p/catch (constantly nil))))
+
+(defn- websocket-connect
+  [url]
+  (js/WebSocket. url))
+
+(defn- init-sqlite!
+  []
+  (sqlite3InitModule (clj->js {:print #(log/info :init-sqlite-module! %)
+                               :printErr #(log/error :init-sqlite-module! %)})))
+
+(defn- open-sqlite-db
+  [{:keys [sqlite pool path mode]}]
+  (if pool
+    (new (.-OpfsSAHPoolDb ^js pool) path)
+    (let [^js DB (.-DB ^js (.-oo1 ^js sqlite))]
+      (new DB path (or mode "c")))))
+
+(defn- search-param-true?
+  [k]
+  (let [value (.get (js/URLSearchParams. (.-search js/location)) k)]
+    (or (= value "true")
+        (= value "1"))))
+
+(defn- owner-source
+  []
+  (cond
+    (search-param-true? "capacitor") :capacitor
+    (search-param-true? "electron") :electron
+    :else :browser))
+
+(defn browser-platform
+  []
+  {:env {:publishing? (string/includes? (.. js/location -href) "publishing=true")
+         :runtime :browser
+         :owner-source (owner-source)}
+   :storage {:install-opfs-pool install-opfs-pool
+             :list-graphs list-graphs
+             :db-exists? db-exists?
+             :resolve-db-path (fn [_repo _pool path] path)
+             :export-file export-file
+             :import-db import-db
+             :remove-vfs! remove-vfs!
+             :read-text! read-text!
+             :write-text! write-text!
+             :asset-read-bytes! asset-read-bytes!
+             :asset-write-bytes! asset-write-bytes!
+             :asset-stat asset-stat
+             :asset-delete! asset-delete!
+             :transfer (fn [data transferables]
+                         (Comlink/transfer data transferables))}
+   :kv {:get kv-get
+        :set! kv-set!}
+   :broadcast {:post-message! worker-util/post-message}
+   :websocket {:connect websocket-connect}
+   :sqlite {:init! init-sqlite!
+            :open-db open-sqlite-db
+            :close-db (fn [db] (.close db))
+            :exec (fn [db sql-or-opts] (.exec db sql-or-opts))
+            :transaction (fn [db f] (.transaction db f))}
+   :crypto {:save-secret-text! save-secret-text!
+            :read-secret-text read-secret-text
+            :delete-secret-text! delete-secret-text!}
+   :timers {:set-interval! (fn [f ms] (js/setInterval f ms))}})
diff --git a/src/main/frontend/worker/platform/node.cljs b/src/main/frontend/worker/platform/node.cljs
new file mode 100644
index 0000000000..22c985c051
--- /dev/null
+++ b/src/main/frontend/worker/platform/node.cljs
@@ -0,0 +1,463 @@
+(ns frontend.worker.platform.node
+  "Node.js platform adapter for db-worker."
+  (:require ["fs/promises" :as fs]
+            ["node:sqlite" :as node-sqlite]
+            ["os" :as os]
+            ["path" :as node-path]
+            ["ws" :as ws]
+            [clojure.string :as string]
+            [cognitect.transit :as transit]
+            [frontend.worker.db-worker-node-lock :as db-lock]
+            [goog.object :as gobj]
+            [lambdaisland.glogi :as log]
+            [logseq.common.config :as common-config]
+            [logseq.db.sqlite.backup :as sqlite-backup]
+            [promesa.core :as p]
+            ["keytar" :as keytar]))
+
+(defn- resolve-database-sync-ctor
+  []
+  (or (gobj/get node-sqlite "DatabaseSync")
+      (some-> (gobj/get node-sqlite "default")
+              (gobj/get "DatabaseSync"))
+      (let [default-export (gobj/get node-sqlite "default")]
+        (when (fn? default-export)
+          default-export))
+      (throw (ex-info "node:sqlite DatabaseSync constructor missing"
+                      {:module-keys (js->clj (js/Object.keys node-sqlite))}))))
+
+(def ^:private DatabaseSync
+  (resolve-database-sync-ctor))
+
+(defn- expand-home
+  [path]
+  (if (string/starts-with? path "~")
+    (node-path/join (.homedir os) (subs path 1))
+    path))
+
+(defn- ensure-dir!
+  [dir]
+  (fs/mkdir dir #js {:recursive true}))
+
+(defn- strip-leading-slash
+  [path]
+  (string/replace-first path #"^/" ""))
+
+(defn- repo-dir
+  [data-dir repo]
+  (db-lock/repo-dir data-dir repo))
+
+(defn- pool-path
+  [^js pool path]
+  (node-path/join (.-repoDir pool) (strip-leading-slash path)))
+
+(defn- path-under-data-dir
+  [data-dir path]
+  (let [expanded-path (expand-home path)]
+    (if (node-path/isAbsolute expanded-path)
+      expanded-path
+      (node-path/join data-dir expanded-path))))
+
+(defn- ->buffer
+  [data]
+  (cond
+    (instance? js/Buffer data) data
+    (instance? js/ArrayBuffer data) (js/Buffer.from data)
+    (and (some? data) (some? (.-buffer data))) (js/Buffer.from (.-buffer data))
+    :else (js/Buffer.from (str data))))
+
+(def ^:private backup-root-dir-name "backup")
+
+(defn- list-graphs
+  [data-dir]
+  (let [dir? #(and % (.isDirectory %))]
+    (p/let [entries (fs/readdir data-dir #js {:withFileTypes true})
+            db-dirs (->> entries
+                         (filter dir?))
+            graph-names (map (fn [dirent]
+                               (db-lock/decode-canonical-graph-dir-key (.-name dirent)))
+                             db-dirs)]
+      (->> graph-names
+           (remove #(or (= % common-config/unlinked-graphs-dir)
+                        (= % backup-root-dir-name)))
+           (filter some?)
+           (vec)))))
+
+(defn- db-exists?
+  [data-dir graph]
+  (p/let [db-path (node-path/join (repo-dir data-dir graph) "db.sqlite")]
+    (-> (fs/stat db-path)
+        (p/then (fn [_] true))
+        (p/catch (fn [_] false)))))
+
+(defn- normalize-bind
+  [bind]
+  (cond
+    (array? bind) bind
+    (and bind (object? bind))
+    (let [out (js-obj)]
+      (doseq [key (js/Object.keys bind)]
+        (let [value (gobj/get bind key)
+              normalized (cond
+                           (string/starts-with? key "$") (subs key 1)
+                           (string/starts-with? key ":") (subs key 1)
+                           :else key)]
+          (gobj/set out normalized value)))
+      out)
+    :else bind))
+
+(defn- stmt-all
+  [^js stmt bind]
+  (cond
+    (array? bind) (.apply (.-all stmt) stmt bind)
+    (some? bind) (.all stmt bind)
+    :else (.all stmt)))
+
+(defn- stmt-run
+  [^js stmt bind]
+  (cond
+    (array? bind) (.apply (.-run stmt) stmt bind)
+    (some? bind) (.run stmt bind)
+    :else (.run stmt)))
+
+(defn- exec-sql
+  [^js db opts-or-sql]
+  (if (string? opts-or-sql)
+    (.exec db opts-or-sql)
+    (let [sql (gobj/get opts-or-sql "sql")
+          bind (gobj/get opts-or-sql "bind")
+          row-mode (gobj/get opts-or-sql "rowMode")
+          return-value (gobj/get opts-or-sql "returnValue")
+          bind' (normalize-bind bind)
+          ^js stmt (.prepare db sql)]
+      (if (or (= row-mode "array")
+              (= row-mode "object")
+              (= return-value "resultRows"))
+        (do
+          (when (= row-mode "array")
+            (.setReturnArrays stmt true))
+          (stmt-all stmt bind'))
+        (do
+          (stmt-run stmt bind')
+          nil)))))
+
+(defn- with-transaction
+  [^js db tx-depth savepoint-seq tx-body]
+  (let [outermost? (zero? @tx-depth)
+        savepoint (when-not outermost?
+                    (str "__logseq_tx_" (swap! savepoint-seq inc)))]
+    (if outermost?
+      (.exec db "BEGIN")
+      (.exec db (str "SAVEPOINT " savepoint)))
+    (swap! tx-depth inc)
+    (try
+      (let [result (tx-body)]
+        (if outermost?
+          (.exec db "COMMIT")
+          (.exec db (str "RELEASE SAVEPOINT " savepoint)))
+        result)
+      (catch :default e
+        (if outermost?
+          (try
+            (.exec db "ROLLBACK")
+            (catch :default _))
+          (do
+            (try
+              (.exec db (str "ROLLBACK TO SAVEPOINT " savepoint))
+              (catch :default _))
+            (try
+              (.exec db (str "RELEASE SAVEPOINT " savepoint))
+              (catch :default _))))
+        (throw e))
+      (finally
+        (swap! tx-depth dec)))))
+
+(defn- backup-db!
+  [write-guard-fn ^js db path]
+  (p/let [_ (when write-guard-fn
+              (write-guard-fn))
+          _ (ensure-dir! (node-path/dirname path))]
+    (sqlite-backup/backup-connection! db path)))
+
+(defn- wrap-node-sqlite-db
+  [db write-guard-fn]
+  (let [wrapper (js-obj)
+        closed? (atom false)
+        tx-depth (atom 0)
+        savepoint-seq (atom 0)]
+    (set! (.-exec wrapper) (fn [opts-or-sql] (exec-sql db opts-or-sql)))
+    (set! (.-transaction wrapper)
+          (fn [f]
+            (with-transaction db tx-depth savepoint-seq
+              (fn []
+                (f wrapper)))))
+    (set! (.-backup wrapper)
+          (fn [path]
+            (backup-db! write-guard-fn db path)))
+    (set! (.-close wrapper)
+          (fn []
+            (when-not @closed?
+              (reset! closed? true)
+              (try
+                (.close db)
+                (catch :default e
+                  (when-not (string/includes? (str e) "database is not open")
+                    (throw e)))))
+            nil))
+    wrapper))
+
+(defn- open-sqlite-db
+  [write-guard-fn {:keys [path]}]
+  (p/let [_ (ensure-dir! (node-path/dirname path))]
+    (wrap-node-sqlite-db (new DatabaseSync path) write-guard-fn)))
+
+(defn- install-opfs-pool
+  [data-dir _sqlite pool-name]
+  (p/let [repo-dir-path (repo-dir data-dir pool-name)
+          _ (ensure-dir! repo-dir-path)
+          ^js pool (js-obj)]
+    (set! (.-repoDir pool) repo-dir-path)
+    (set! (.-getCapacity pool) (fn [] 1))
+    (set! (.-pauseVfs pool) (fn [] nil))
+    (set! (.-unpauseVfs pool) (fn [] nil))
+    pool))
+
+(defn- export-file
+  [pool path]
+  (fs/readFile (pool-path pool path)))
+
+(defn- import-db
+  [write-guard-fn pool path data]
+  (let [full-path (pool-path pool path)
+        dir (node-path/dirname full-path)]
+    (p/let [_ (when write-guard-fn
+                (write-guard-fn))
+            _ (ensure-dir! dir)]
+      (fs/writeFile full-path (->buffer data)))))
+
+(defn- remove-vfs!
+  [^js pool]
+  (when pool
+    (fs/rm (.-repoDir pool) #js {:recursive true :force true})))
+
+(defn- read-text!
+  [data-dir path]
+  (fs/readFile (path-under-data-dir data-dir path) "utf8"))
+
+(defn- write-text!
+  [write-guard-fn data-dir path text]
+  (let [full-path (path-under-data-dir data-dir path)
+        dir (node-path/dirname full-path)]
+    (p/let [_ (when write-guard-fn
+                (write-guard-fn))
+            _ (ensure-dir! dir)]
+      (fs/writeFile full-path text "utf8"))))
+
+(defn- asset-file-path
+  [data-dir repo file-name]
+  (node-path/join (repo-dir data-dir repo)
+                  common-config/local-assets-dir
+                  file-name))
+
+(defn- asset-read-bytes!
+  [data-dir repo file-name]
+  (fs/readFile (asset-file-path data-dir repo file-name)))
+
+(defn- asset-write-bytes!
+  [write-guard-fn data-dir repo file-name payload]
+  (let [full-path (asset-file-path data-dir repo file-name)
+        dir (node-path/dirname full-path)]
+    (p/let [_ (when write-guard-fn
+                (write-guard-fn))
+            _ (ensure-dir! dir)]
+      (fs/writeFile full-path (->buffer payload)))))
+
+(defn- asset-stat
+  [data-dir repo file-name]
+  (-> (fs/stat (asset-file-path data-dir repo file-name))
+      (p/then (fn [^js stat]
+                {:size (.-size stat)
+                 :is-file? (.isFile stat)}))
+      (p/catch (constantly nil))))
+
+(defn- asset-delete!
+  [write-guard-fn data-dir repo file-name]
+  (let [full-path (asset-file-path data-dir repo file-name)]
+    (p/let [_ (when write-guard-fn
+                (write-guard-fn))]
+      (-> (fs/rm full-path #js {:force true})
+          (p/catch (constantly nil))))))
+
+(defn- websocket-connect
+  [url]
+  (ws. url))
+
+(def ^:private kv-transit-writer
+  (transit/writer
+   :json
+   {:handlers
+    {js/Uint8Array
+     (transit/write-handler
+      (constantly "uint8array")
+      (fn [value]
+        (js->clj (js/Array.from value))))}}))
+
+(def ^:private kv-transit-reader
+  (transit/reader
+   :json
+   {:handlers
+    {"uint8array"
+     (fn [value]
+       (js/Uint8Array. (clj->js value)))}}))
+
+(defn- parse-kv-state
+  [contents]
+  (try
+    (let [state (transit/read kv-transit-reader contents)]
+      (if (map? state)
+        state
+        {}))
+    (catch :default error
+      (log/warn :db-worker-node-kv-parse-failed
+                {:error error})
+      {})))
+
+(defn- serialize-kv-state
+  [state]
+  (transit/write kv-transit-writer state))
+
+(def ^:private keychain-service "Logseq E2EE")
+
+(defn- <save-secret-text!
+  [kv key text]
+  (-> (p/let [_ (.setPassword ^js keytar keychain-service key text)]
+        nil)
+      (p/catch (fn [e]
+                 (log/warn :db-worker/keychain-save-failed {:error e
+                                                            :key key})
+                 ((:set! kv) key text)))))
+
+(defn- <read-secret-text
+  [kv key]
+  (-> (p/let [secret (.getPassword ^js keytar keychain-service key)]
+        secret)
+      (p/catch (fn [e]
+                 (log/warn :db-worker/keychain-read-failed {:error e
+                                                            :key key})
+                 ((:get kv) key)))))
+
+(defn- <delete-secret-text!
+  [kv key]
+  (-> (p/let [_ (.deletePassword ^js keytar keychain-service key)]
+        nil)
+      (p/catch (fn [e]
+                 (log/warn :db-worker/keychain-delete-failed {:error e
+                                                              :key key})
+                 ((:set! kv) key nil)))))
+
+(defn- truthy-env?
+  [value]
+  (contains? #{"1" "true" "yes" "on"}
+             (string/lower-case (string/trim (str (or value ""))))))
+
+(defn- use-keychain-for-owner?
+  [owner-source]
+  (not (and (= :cli owner-source)
+            (truthy-env? (gobj/get (.-env js/process) "CLI_E2E_TEST")))))
+
+(defn- <save-secret-text-by-owner!
+  [kv owner-source key text]
+  (if (use-keychain-for-owner? owner-source)
+    (<save-secret-text! kv key text)
+    ((:set! kv) key text)))
+
+(defn- <read-secret-text-by-owner
+  [kv owner-source key]
+  (if (use-keychain-for-owner? owner-source)
+    (<read-secret-text kv key)
+    ((:get kv) key)))
+
+(defn- <delete-secret-text-by-owner!
+  [kv owner-source key]
+  (if (use-keychain-for-owner? owner-source)
+    (<delete-secret-text! kv key)
+    ((:set! kv) key nil)))
+
+(defn- kv-store
+  [data-dir]
+  (let [kv-path (node-path/join data-dir "kv-store.json")
+        state (atom nil)
+        <load! (fn []
+                 (if (some? @state)
+                   (p/resolved @state)
+                   (-> (fs/readFile kv-path "utf8")
+                       (p/then (fn [contents]
+                                 (let [data (parse-kv-state contents)]
+                                   (reset! state data)
+                                   @state)))
+                       (p/catch (fn [_]
+                                  (reset! state {})
+                                  @state)))))]
+    {:get (fn [k]
+            (p/let [_ (<load!)]
+              (get @state k)))
+     :set! (fn [k value]
+             (p/let [_ (<load!)
+                     _ (swap! state assoc k value)
+                     payload (serialize-kv-state @state)]
+               (fs/writeFile kv-path payload "utf8")))}))
+
+(defn node-platform
+  [{:keys [root-dir event-fn write-guard-fn owner-source recreate-lock-fn]}]
+  (let [root-dir (db-lock/resolve-root-dir root-dir)
+        data-dir (db-lock/graphs-dir root-dir)
+        owner-source (db-lock/normalize-owner-source owner-source)
+        kv (kv-store root-dir)]
+    (p/do!
+     (ensure-dir! root-dir)
+     (ensure-dir! data-dir)
+     (log/info :db-worker-node-platform {:root-dir root-dir})
+     {:env {:publishing? false
+            :runtime :node
+            :root-dir root-dir
+            :owner-source owner-source
+            :recreate-lock-fn recreate-lock-fn}
+      :storage {:install-opfs-pool (fn [sqlite-module pool-name]
+                                     (install-opfs-pool data-dir sqlite-module pool-name))
+                :list-graphs (fn [] (list-graphs data-dir))
+                :db-exists? (fn [graph] (db-exists? data-dir graph))
+                :resolve-db-path (fn [_repo pool path]
+                                   (pool-path pool path))
+                :export-file export-file
+                :import-db (fn [pool path data] (import-db write-guard-fn pool path data))
+                :remove-vfs! (fn [pool] (remove-vfs! pool))
+                :read-text! (fn [path] (read-text! data-dir path))
+                :write-text! (fn [path text] (write-text! write-guard-fn data-dir path text))
+                :asset-read-bytes! (fn [repo file-name]
+                                     (asset-read-bytes! data-dir repo file-name))
+                :asset-write-bytes! (fn [repo file-name payload]
+                                      (asset-write-bytes! write-guard-fn data-dir repo file-name payload))
+                :asset-stat (fn [repo file-name]
+                              (asset-stat data-dir repo file-name))
+                :asset-delete! (fn [repo file-name]
+                                 (asset-delete! write-guard-fn data-dir repo file-name))}
+      :kv {:get (:get kv)
+           :set! (:set! kv)}
+      :broadcast {:post-message! (fn [type payload]
+                                   (when event-fn
+                                     (event-fn type payload)))}
+      :websocket {:connect websocket-connect}
+      :sqlite {:init! (fn [] nil)
+               :open-db (fn [opts] (open-sqlite-db write-guard-fn opts))
+               :close-db (fn [db] (.close db))
+               :exec (fn [db sql-or-opts] (.exec db sql-or-opts))
+               :transaction (fn [db f] (.transaction db f))
+               :backup-db (fn [^js db path]
+                            (.backup db path))}
+      :crypto {:save-secret-text! (fn [key text]
+                                    (<save-secret-text-by-owner! kv owner-source key text))
+               :read-secret-text (fn [key]
+                                   (<read-secret-text-by-owner kv owner-source key))
+               :delete-secret-text! (fn [key]
+                                      (<delete-secret-text-by-owner! kv owner-source key))}
+      :timers {:set-interval! (fn [f ms] (js/setInterval f ms))}})))
diff --git a/src/main/frontend/worker/search.cljs b/src/main/frontend/worker/search.cljs
index 07b2cfd58f..a13f7c0eab 100644
--- a/src/main/frontend/worker/search.cljs
+++ b/src/main/frontend/worker/search.cljs
@@ -131,6 +131,7 @@ DROP TRIGGER IF EXISTS blocks_au;
 
 (defn upsert-blocks!
   [^Object db blocks]
+  (assert db ::upsert-blocks!)
   (.transaction db (fn [tx]
                      (doseq [batch (partition-all upsert-blocks-batch-size blocks)]
                        (doseq [item batch]
@@ -141,6 +142,7 @@ DROP TRIGGER IF EXISTS blocks_au;
 
 (defn delete-blocks!
   [db ids]
+  (assert db ::delete-blocks!)
   (let [sql (str "DELETE from blocks WHERE id IN " (clj-list->sql ids))]
     (.exec db sql)))
 
diff --git a/src/main/frontend/worker/shared_service.cljs b/src/main/frontend/worker/shared_service.cljs
index 85ed56e210..c2ebdcc0ce 100644
--- a/src/main/frontend/worker/shared_service.cljs
+++ b/src/main/frontend/worker/shared_service.cljs
@@ -1,6 +1,7 @@
 (ns frontend.worker.shared-service
   "This allows multiple workers to share some resources (e.g. db access)"
   (:require [cljs-bean.core :as bean]
+            [frontend.worker.platform :as platform]
             [goog.object :as gobj]
             [lambdaisland.glogi :as log]
             [logseq.common.util :as common-util]
@@ -35,6 +36,12 @@
 (defonce *client-id (atom nil))
 (defonce *master-client-lock (atom nil))
 
+(defn- node-runtime?
+  []
+  (try
+    (= :node (platform/env-flag (platform/current) :runtime))
+    (catch :default _ false)))
+
 (defn- next-request-id
   []
   (vswap! *current-request-id inc))
@@ -307,60 +314,80 @@
                           forward the data broadcast from the master client directly to the UI thread."
   [service-name target on-become-master-handler broadcast-data-types {:keys [import?]}]
   (clear-old-service!)
-  (when import? (reset! *master-client? true))
-  (p/let [broadcast-data-types (set broadcast-data-types)
-          status {:ready (p/deferred)}
-          common-channel (ensure-common-channel service-name)
-          client-id (<ensure-client-id)
-          <check-master-slave-fn!
-          (fn []
-            (<check-master-or-slave-client!
-             service-name
-             #(<on-become-master
-               client-id service-name common-channel target
-               on-become-master-handler (:ready status))
-             #(<on-become-slave
-               client-id service-name common-channel broadcast-data-types (:ready status))))]
-    (<check-master-slave-fn!)
+  (if (node-runtime?)
+    (p/do!
+     (reset! *master-client? true)
+     (reset! *client-id "node")
+     (p/let [status {:ready (p/deferred)}]
+       (p/do!
+        (on-become-master-handler service-name)
+        (p/resolve! (:ready status)))
+       {:proxy #js {"remoteInvoke"
+                    (fn [args]
+                      (<apply-target-f! target "remoteInvoke" args))}
+        :status status
+        :client-id @*client-id}))
+    (do
+      (when import? (reset! *master-client? true))
+      (p/let [broadcast-data-types (set broadcast-data-types)
+              status {:ready (p/deferred)}
+              common-channel (ensure-common-channel service-name)
+              client-id (<ensure-client-id)
+              <check-master-slave-fn!
+              (fn []
+                (<check-master-or-slave-client!
+                 service-name
+                 #(<on-become-master
+                   client-id service-name common-channel target
+                   on-become-master-handler (:ready status))
+                 #(<on-become-slave
+                   client-id service-name common-channel broadcast-data-types (:ready status))))]
+        (<check-master-slave-fn!)
+        (log/info :shared-service/create-client {:service service-name
+                                                 :client-id client-id
+                                                 :import? import?})
 
-    (add-watch *master-re-check-trigger :check-master
-               (fn [_ _ _ new-value]
-                 (when (= new-value :re-check)
-                   (p/do!
-                    (p/delay 100)      ; why need delay here?
-                    (<check-master-slave-fn!)))))
+        (add-watch *master-re-check-trigger :check-master
+                   (fn [_ _ _ new-value]
+                     (when (= new-value :re-check)
+                       (p/do!
+                        (p/delay 100)      ; why need delay here?
+                        (<check-master-slave-fn!)))))
 
-    {:proxy (js/Proxy. target
-                       #js {:get (fn [target method]
-                                   (if (= "remoteInvoke" method)
-                                     (fn [args]
-                                       (cond
-                                         @*master-client?
-                                         (<apply-target-f! target method args)
+        {:proxy (js/Proxy. target
+                           #js {:get (fn [target method]
+                                       (if (= "remoteInvoke" method)
+                                         (fn [args]
+                                           (cond
+                                             @*master-client?
+                                             (<apply-target-f! target method args)
 
-                                         :else
-                                         (let [request-id (next-request-id)
-                                               client-channel (ensure-client-channel client-id service-name)]
-                                           (p/create
-                                            (fn [resolve-fn reject-fn]
-                                              (vswap! *requests-in-flight assoc request-id {:method method
-                                                                                            :args args
-                                                                                            :resolve-fn resolve-fn
-                                                                                            :reject-fn reject-fn})
-                                              (.postMessage client-channel (bean/->js
-                                                                            {:id request-id
-                                                                             :type "request"
-                                                                             :method method
-                                                                             :args args})))))))
-                                     (log/error :invalid-invoke-method method)))})
-     :status status
-     :client-id client-id}))
+                                             :else
+                                             (let [request-id (next-request-id)
+                                                   client-channel (ensure-client-channel client-id service-name)]
+                                               (p/create
+                                                (fn [resolve-fn reject-fn]
+                                                  (vswap! *requests-in-flight assoc request-id {:method method
+                                                                                                :args args
+                                                                                                :resolve-fn resolve-fn
+                                                                                                :reject-fn reject-fn})
+                                                  (.postMessage client-channel (bean/->js
+                                                                                {:id request-id
+                                                                                 :type "request"
+                                                                                 :method method
+                                                                                 :args args})))))))
+                                         (log/error :invalid-invoke-method method)))})
+         :status status
+         :client-id client-id}))))
 
 (defn broadcast-to-clients!
   [type' data]
   (let [transit-payload (ldb/write-transit-str [type' data])]
-    (when (exists? js/self) (.postMessage js/self transit-payload))
-    (when-let [common-channel @*common-channel]
-      (let [str-type' (common-util/keyword->string type')]
-        (.postMessage common-channel #js {:type str-type'
-                                          :data transit-payload})))))
+    (if (node-runtime?)
+      (platform/post-message! (platform/current) type' transit-payload)
+      (do
+        (when (exists? js/self) (.postMessage js/self transit-payload))
+        (when-let [common-channel @*common-channel]
+          (let [str-type' (common-util/keyword->string type')]
+            (.postMessage common-channel #js {:type str-type'
+                                              :data transit-payload})))))))
diff --git a/src/main/frontend/worker/state.cljs b/src/main/frontend/worker/state.cljs
index 2872fb536d..819f875180 100644
--- a/src/main/frontend/worker/state.cljs
+++ b/src/main/frontend/worker/state.cljs
@@ -1,29 +1,18 @@
 (ns frontend.worker.state
   "State hub for worker"
-  (:require [logseq.common.util :as common-util]))
+  (:require [frontend.worker.platform :as platform]
+            [logseq.common.util :as common-util]
+            [promesa.core :as p]))
 
 (defonce *main-thread (atom nil))
 (defonce *deleted-block-uuid->db-id (atom {}))
 
-(defn- <invoke-main-thread*
-  [qkw direct-pass? args-list]
-  (let [main-thread @*main-thread]
-    (when (nil? main-thread)
-      (prn :<invoke-main-thread-error qkw)
-      (throw (ex-info "main-thread has not been initialized" {})))
-    (apply main-thread qkw direct-pass? args-list)))
-
 (defn <invoke-main-thread
-  "invoke main thread api"
   [qkw & args]
-  (<invoke-main-thread* qkw false args))
-
-(comment
-  (defn <invoke-main-thread-direct-pass
-    "invoke main thread api.
-  But directly pass args to main-thread and result from main-thread as well."
-    [qkw & args]
-    (<invoke-main-thread* qkw true args)))
+  (if-let [main-thread @*main-thread]
+    (apply main-thread qkw false args)
+    (p/rejected (ex-info "main thread is not available in db-worker"
+                         {:method qkw}))))
 
 (defonce *state (atom {:db/latest-transact-time {}
                        :worker/context {}
@@ -35,10 +24,21 @@
                        :auth/id-token nil
                        :auth/access-token nil
                        :auth/refresh-token nil
+                       :auth/oauth-token-url nil
+                       :auth/oauth-domain nil
+                       :auth/oauth-client-id nil
 
                        :user/info nil
                        ;; thread atoms, these atoms' value are syncing from ui-thread
-                       :thread-atom/online-event (atom nil)}))
+                       :thread-atom/online-event (atom nil)
+                       :thread-atom/search-input-idle-status (atom {})}))
+
+(def ^:private db-sync-config-auth-keys
+  #{:auth-token :oauth-token-url :oauth-domain :oauth-client-id})
+
+(defn non-auth-db-sync-config
+  [config]
+  (apply dissoc (or config {}) db-sync-config-auth-keys))
 
 (defonce *db-sync-config (atom {:ws-url nil}))
 (defonce *db-sync-client (atom nil))
@@ -105,9 +105,28 @@
   []
   (:auth/id-token @*state))
 
+(defn- node-runtime?
+  []
+  (try
+    (= :node (get-in (platform/current) [:env :runtime]))
+    (catch :default _
+      false)))
+
+(defn- node-online?
+  []
+  (try
+    (let [online? (some-> js/globalThis .-navigator .-onLine)]
+      (if (boolean? online?)
+        online?
+        true))
+    (catch :default _
+      true)))
+
 (defn online?
   []
-  @(:thread-atom/online-event @*state))
+  (if (node-runtime?)
+    (node-online?)
+    @(:thread-atom/online-event @*state)))
 
 (comment
   (defn mobile?
diff --git a/src/main/frontend/worker/sync.cljs b/src/main/frontend/worker/sync.cljs
index 8de24eb462..12a4e68066 100644
--- a/src/main/frontend/worker/sync.cljs
+++ b/src/main/frontend/worker/sync.cljs
@@ -1,6 +1,7 @@
 (ns frontend.worker.sync
   "Sync client"
   (:require
+   [frontend.worker.platform :as platform]
    [frontend.worker.shared-service :as shared-service]
    [frontend.worker.state :as worker-state]
    [frontend.worker.sync.apply-txs :as sync-apply]
@@ -8,38 +9,33 @@
    [frontend.worker.sync.auth :as sync-auth]
    [frontend.worker.sync.client-op :as client-op]
    [frontend.worker.sync.handle-message :as sync-handle-message]
-   [frontend.worker.sync.large-title :as sync-large-title]
    [frontend.worker.sync.presence :as sync-presence]
    [frontend.worker.sync.transport :as sync-transport]
    [frontend.worker.sync.upload :as sync-upload]
+   [frontend.worker.sync.util :as sync-util]
    [frontend.worker-common.util :as worker-util]
    [lambdaisland.glogi :as log]
    [logseq.common.util :as common-util]
    [logseq.db-sync.checksum :as sync-checksum]
    [promesa.core :as p]
-   ;; [logseq.db :as ldb]
-   ))
+   [logseq.common.config :as common-config]))
 
 (def ^:private reconnect-base-delay-ms 1000)
 (def ^:private reconnect-max-delay-ms 30000)
 (def ^:private reconnect-jitter-ms 250)
 (def ^:private ws-stale-kill-interval-ms 60000)
 (def ^:private ws-stale-timeout-ms 600000)
+(def fail-fast sync-util/fail-fast)
 
 (defonce *repo->latest-remote-tx sync-apply/*repo->latest-remote-tx)
 (defonce *repo->latest-remote-checksum sync-apply/*repo->latest-remote-checksum)
 (defonce *start-inflight-target (atom nil))
 
-(defn fail-fast
-  [tag data]
-  (log/error tag data)
-  (throw (ex-info (name tag) data)))
-
 (defn- current-client
   [repo]
   (sync-presence/current-client worker-state/*db-sync-client repo))
 
-(defn- sync-counts
+(defn status
   [repo]
   (sync-presence/sync-counts
    {:get-datascript-conn worker-state/get-datascript-conn
@@ -77,7 +73,7 @@
   (when client
     (shared-service/broadcast-to-clients!
      :rtc-sync-state
-     (sync-presence/rtc-state-payload sync-counts client))))
+     (sync-presence/rtc-state-payload status client))))
 
 (defn- set-ws-state!
   [client ws-state]
@@ -91,21 +87,11 @@
   []
   (sync-auth/ws-base-url @worker-state/*db-sync-config))
 
-(defn- auth-token
-  []
-  (worker-state/get-id-token))
+(def auth-token sync-util/auth-token)
 
-(defn- id-token-expired?
-  [token]
-  (sync-auth/id-token-expired? token))
+(def id-token-expired? sync-auth/id-token-expired?)
 
-(defn- <resolve-ws-token
-  []
-  (sync-auth/<resolve-ws-token
-   {:auth-token-f auth-token
-    :id-token-expired?-f id-token-expired?
-    :invoke-main-thread-f #(worker-state/<invoke-main-thread :thread-api/ensure-id&access-token)
-    :set-id-token-f #(worker-state/set-new-state! {:auth/id-token %})}))
+(def <resolve-ws-token sync-auth/<resolve-ws-token)
 
 (defn- ensure-client-graph-uuid!
   [repo graph-id]
@@ -193,6 +179,7 @@
    :asset-queue (atom (p/resolved nil))
    :pending-pull-since (atom nil)
    :inflight (atom [])
+   :last-sync-error (atom nil)
    :reconnect (atom {:attempt 0 :timer nil})
    :stale-kill-timer (atom nil)
    :last-ws-message-ts (atom (common-util/time-ms))
@@ -296,7 +283,7 @@
   (when (:ws client)
     (stop-client! client))
   (when-let [token' (or token (auth-token))]
-    (let [ws (js/WebSocket. (sync-transport/append-token url token'))
+    (let [ws (platform/websocket-connect (platform/current) (sync-transport/append-token url token'))
           updated (assoc client :ws ws)]
       (attach-ws-handlers! repo updated ws url)
       (set! (.-onopen ws)
@@ -304,6 +291,7 @@
               (reset-reconnect! updated)
               (touch-last-ws-message! updated)
               (set-ws-state! updated :open)
+              (sync-util/clear-last-sync-error! updated)
               (send! ws {:type "hello" :client repo})
               (sync-assets/enqueue-asset-sync!
                repo updated
@@ -320,45 +308,68 @@
     (reset! worker-state/*db-sync-client nil))
   (p/resolved nil))
 
+(declare list-remote-graphs!)
+
+(defn- <resolve-start-graph-id
+  [repo]
+  (if-let [graph-id (sync-util/get-graph-id repo)]
+    (p/resolved graph-id)
+    (let [target-graph-name (some-> repo common-config/strip-leading-db-version-prefix)]
+      (if-not (seq target-graph-name)
+        (p/resolved nil)
+        (p/let [remote-graphs (list-remote-graphs!)
+                remote-graph-id (some (fn [{:keys [graph-name graph-id]}]
+                                        (when (= target-graph-name graph-name)
+                                          graph-id))
+                                      remote-graphs)]
+          (when (seq remote-graph-id)
+            (ensure-client-graph-uuid! repo remote-graph-id)
+            remote-graph-id))))))
+
 (defn start!
   [repo]
   (let [base (ws-base-url)
-        graph-id (sync-large-title/get-graph-id worker-state/get-datascript-conn repo)
+        graph-id (sync-util/get-graph-id repo)
         start-target [repo graph-id]
         inflight-target @*start-inflight-target
         current @worker-state/*db-sync-client]
-    (cond
-      (not (and (string? base) (seq base) (seq graph-id)))
+    (if-not (and (string? base) (seq base))
       (do
         (log/info :db-sync/start-skipped {:repo repo :graph-id graph-id :base base})
         (p/resolved nil))
+      (p/let [graph-id (<resolve-start-graph-id repo)]
+        (cond
+          (not (seq graph-id))
+          (do
+            (log/info :db-sync/start-skipped {:repo repo :graph-id graph-id :base base})
+            (p/resolved nil))
 
-      (= start-target inflight-target)
-      (p/resolved nil)
+          (= start-target inflight-target)
+          (p/resolved nil)
 
-      (active-client-for? current repo graph-id)
-      (do
-        (broadcast-rtc-state! current)
-        (p/resolved nil))
+          (active-client-for? current repo graph-id)
+          (do
+            (broadcast-rtc-state! current)
+            (p/resolved nil))
 
-      :else
-      (do
-        (reset! *start-inflight-target start-target)
-        (->
-         (p/do!
-          (stop!)
-          (p/let [client (ensure-client-state! repo)
-                  url (sync-transport/format-ws-url base graph-id)
-                  _ (ensure-client-graph-uuid! repo graph-id)
-                  connected (assoc client :graph-id graph-id)
-                  token (<resolve-ws-token)
-                  connected (connect! repo connected url token)]
-            (reset! worker-state/*db-sync-client connected)
-            nil))
-         (p/finally
-           (fn []
-             (when (= start-target @*start-inflight-target)
-               (reset! *start-inflight-target nil)))))))))
+          :else
+          (do
+            (reset! *start-inflight-target start-target)
+            (->
+             (p/do!
+              (stop!)
+              (p/let [client (ensure-client-state! repo)
+                      url (sync-transport/format-ws-url base graph-id)
+                      _ (ensure-client-graph-uuid! repo graph-id)
+                      connected (assoc client :graph-id graph-id)
+                      token (<resolve-ws-token)
+                      connected (connect! repo connected url token)]
+                (reset! worker-state/*db-sync-client connected)
+                nil))
+             (p/finally
+               (fn []
+                 (when (= start-target @*start-inflight-target)
+                   (reset! *start-inflight-target nil)))))))))))
 
 (defn enqueue-local-tx!
   [repo tx-report]
@@ -380,6 +391,12 @@
   [repo]
   (sync-upload/upload-graph! repo))
 
+(defn create-remote-graph!
+  [repo opts]
+  (sync-upload/create-remote-graph! repo opts))
+
+(def list-remote-graphs! sync-upload/list-remote-graphs!)
+
 (defn stop-upload!
   [repo]
   (sync-apply/set-upload-stopped! repo true))
diff --git a/src/main/frontend/worker/sync/apply_txs.cljs b/src/main/frontend/worker/sync/apply_txs.cljs
index 3bb005a75f..a4f6607f9c 100644
--- a/src/main/frontend/worker/sync/apply_txs.cljs
+++ b/src/main/frontend/worker/sync/apply_txs.cljs
@@ -13,6 +13,7 @@
    [frontend.worker.sync.large-title :as sync-large-title]
    [frontend.worker.sync.presence :as sync-presence]
    [frontend.worker.sync.transport :as sync-transport]
+   [frontend.worker.sync.util :refer [fail-fast]]
    [frontend.worker.undo-redo :as worker-undo-redo]
    [lambdaisland.glogi :as log]
    [logseq.db :as ldb]
@@ -31,15 +32,10 @@
 
 (defonce *repo->latest-remote-tx (atom {}))
 (defonce *repo->latest-remote-checksum (atom {}))
-(defonce *upload-temp-opfs-pool (atom nil))
 ;; Debug-only gate to reproduce one-way sync:
 ;; still pull/rebase remote txs, but skip local tx batch uploads.
 (defonce *repo->upload-stopped? (atom {}))
 
-(defn fail-fast [tag data]
-  (log/error tag data)
-  (throw (ex-info (name tag) data)))
-
 (defn set-upload-stopped!
   [repo stopped?]
   (swap! *repo->upload-stopped? assoc repo (boolean stopped?))
@@ -113,9 +109,6 @@
   {:normalized-tx-data (normalize-tx-data db-after db-before tx-data)
    :reversed-datoms (reverse-tx-data db-before db-after tx-data)})
 
-(defn- get-graph-id [repo]
-  (sync-large-title/get-graph-id worker-state/get-datascript-conn repo))
-
 (defn- auth-headers []
   (sync-auth/auth-headers (worker-state/get-id-token)))
 
@@ -155,7 +148,6 @@
                                :fail-fast-f fail-fast
                                :decrypt-text-value-f sync-crypt/<decrypt-text-value})))
           :get-conn-f worker-state/get-datascript-conn
-          :get-graph-id-f get-graph-id
           :graph-e2ee?-f sync-crypt/graph-e2ee?
           :ensure-graph-aes-key-f sync-crypt/<ensure-graph-aes-key
           :fail-fast-f fail-fast)))
diff --git a/src/main/frontend/worker/sync/assets.cljs b/src/main/frontend/worker/sync/assets.cljs
index f539da688f..a77e566046 100644
--- a/src/main/frontend/worker/sync/assets.cljs
+++ b/src/main/frontend/worker/sync/assets.cljs
@@ -3,38 +3,149 @@
   (:require
    [datascript.core :as d]
    [frontend.common.crypt :as crypt]
+   [frontend.worker.platform :as platform]
+   [frontend.worker.shared-service :as shared-service]
    [frontend.worker.state :as worker-state]
    [frontend.worker.sync.auth :as sync-auth]
    [frontend.worker.sync.client-op :as client-op]
    [frontend.worker.sync.crypt :as sync-crypt]
    [frontend.worker.sync.large-title :as sync-large-title]
    [lambdaisland.glogi :as log]
+   [logseq.common.util :as common-util]
    [logseq.db :as ldb]
    [promesa.core :as p]))
 
 (def max-asset-size (* 100 1024 1024))
 
-(defn exported-graph-aes-key
+(defn graph-aes-key
   [repo graph-id fail-fast-f]
   (if (sync-crypt/graph-e2ee? repo)
     (p/let [aes-key (sync-crypt/<ensure-graph-aes-key repo graph-id)
             _ (when (nil? aes-key)
                 (fail-fast-f :db-sync/missing-field {:repo repo :field :aes-key}))]
-      (crypt/<export-aes-key aes-key))
+      aes-key)
     (p/resolved nil)))
 
+(defn- asset-file-name
+  [asset-uuid asset-type]
+  (str asset-uuid "." asset-type))
+
+(defn- ->uint8
+  [payload]
+  (cond
+    (instance? js/Uint8Array payload)
+    payload
+
+    (instance? js/ArrayBuffer payload)
+    (js/Uint8Array. payload)
+
+    (and (exists? js/ArrayBuffer)
+         (.isView js/ArrayBuffer payload))
+    (js/Uint8Array. (.-buffer payload) (.-byteOffset payload) (.-byteLength payload))
+
+    (array? payload)
+    (js/Uint8Array. payload)
+
+    (sequential? payload)
+    (js/Uint8Array. (clj->js payload))
+
+    (and (object? payload)
+         (= "Buffer" (aget payload "type"))
+         (array? (aget payload "data")))
+    (js/Uint8Array. (aget payload "data"))
+
+    :else
+    (throw (ex-info "unsupported binary payload"
+                    {:payload-type (str (type payload))}))))
+
+(defn- payload-size
+  [payload]
+  (cond
+    (string? payload) (count payload)
+    (some? (.-byteLength payload)) (.-byteLength payload)
+    (some? (.-length payload)) (.-length payload)
+    :else 0))
+
+(defn- notify-asset-progress!
+  [repo asset-id direction loaded total]
+  (shared-service/broadcast-to-clients!
+   :rtc-asset-upload-download-progress
+   {:repo repo
+    :asset-id asset-id
+    :progress {:direction direction
+               :loaded loaded
+               :total total}}))
+
+(defn- mark-asset-write-finish!
+  [repo asset-id]
+  (shared-service/broadcast-to-clients!
+   :asset-file-write-finish
+   {:repo repo
+    :asset-id asset-id
+    :ts (common-util/time-ms)}))
+
+(defn- <read-asset-bytes
+  [repo asset-id asset-type]
+  (platform/asset-read-bytes! (platform/current)
+                              repo
+                              (asset-file-name asset-id asset-type)))
+
+(defn- <write-asset-bytes!
+  [repo asset-id asset-type payload]
+  (p/let [_ (platform/asset-write-bytes! (platform/current)
+                                         repo
+                                         (asset-file-name asset-id asset-type)
+                                         payload)]
+    (mark-asset-write-finish! repo asset-id)
+    nil))
+
 (defn upload-remote-asset!
   [repo graph-id asset-uuid asset-type checksum]
   (let [base (sync-auth/http-base-url @worker-state/*db-sync-config)]
     (if (and (seq base) (seq graph-id) (seq asset-type) (seq checksum))
-      (p/let [exported-aes-key (exported-graph-aes-key
-                                repo graph-id
-                                (fn [tag data]
-                                  (throw (ex-info (name tag) data))))]
-        (worker-state/<invoke-main-thread :thread-api/rtc-upload-asset
-                                          repo exported-aes-key (str asset-uuid) asset-type checksum
-                                          (sync-large-title/asset-url base graph-id (str asset-uuid) asset-type)
-                                          {:extra-headers (sync-auth/auth-headers (worker-state/get-id-token))}))
+      (-> (p/let [aes-key (graph-aes-key
+                           repo graph-id
+                           (fn [tag data]
+                             (throw (ex-info (name tag) data))) )
+                  asset-id (str asset-uuid)
+                  put-url (sync-large-title/asset-url base graph-id asset-id asset-type)
+                  asset-file (try
+                               (<read-asset-bytes repo asset-id asset-type)
+                               (catch :default e
+                                 (log/info :read-asset e)
+                                 (throw (ex-info "read-asset failed"
+                                                 {:type :rtc.exception/read-asset-failed}
+                                                 e))))
+                  asset-file (if aes-key (->uint8 asset-file) asset-file)
+                  payload (if (not aes-key)
+                            asset-file
+                            (ldb/write-transit-str
+                             (crypt/<encrypt-uint8array aes-key asset-file)))
+                  total (payload-size payload)
+                  _ (notify-asset-progress! repo asset-id :upload 0 total)
+                  headers (merge (sync-auth/auth-headers (worker-state/get-id-token))
+                                 {"x-amz-meta-checksum" checksum
+                                  "x-amz-meta-type" asset-type})
+                  ^js resp (js/fetch put-url
+                                     (clj->js {:method "PUT"
+                                               :headers headers
+                                               :body payload}))
+                  status (.-status resp)
+                  _ (notify-asset-progress! repo asset-id :upload total total)]
+            (when-not (.-ok resp)
+              (throw (ex-info "upload-asset failed"
+                              {:type :rtc.exception/upload-asset-failed
+                               :data {:status status}})))
+            nil)
+          (p/catch
+           (fn [e]
+             (if (contains? #{:rtc.exception/read-asset-failed
+                              :rtc.exception/upload-asset-failed}
+                            (:type (ex-data e)))
+               (p/rejected e)
+               (p/rejected (ex-info "upload-asset failed"
+                                    {:type :rtc.exception/upload-asset-failed}
+                                    e))))))
       (p/rejected (ex-info "missing asset upload info"
                            {:repo repo
                             :asset-uuid asset-uuid
@@ -166,18 +277,60 @@
       :broadcast-rtc-state!-f broadcast-rtc-state!-f
       :fail-fast-f fail-fast-f})))
 
+(defn- parse-content-length
+  [^js resp]
+  (when-let [content-length (some-> (.-headers resp) (.get "content-length"))]
+    (let [length (js/parseInt content-length 10)]
+      (when (not (js/isNaN length))
+        length))))
+
 (defn download-remote-asset!
   [repo graph-id asset-uuid asset-type]
   (let [base (sync-auth/http-base-url @worker-state/*db-sync-config)]
     (if (and (seq base) (seq graph-id) (seq asset-type))
-      (p/let [exported-aes-key (exported-graph-aes-key
-                                repo graph-id
-                                (fn [tag data]
-                                  (throw (ex-info (name tag) data))))]
-        (worker-state/<invoke-main-thread :thread-api/rtc-download-asset
-                                          repo exported-aes-key (str asset-uuid) asset-type
-                                          (sync-large-title/asset-url base graph-id (str asset-uuid) asset-type)
-                                          {:extra-headers (sync-auth/auth-headers (worker-state/get-id-token))}))
+      (-> (p/let [aes-key (graph-aes-key
+                           repo graph-id
+                           (fn [tag data]
+                             (throw (ex-info (name tag) data))))
+                  asset-id (str asset-uuid)
+                  get-url (sync-large-title/asset-url base graph-id asset-id asset-type)
+                  headers (sync-auth/auth-headers (worker-state/get-id-token))
+                  request-opts (cond-> {:method "GET"}
+                                 (seq headers) (assoc :headers headers))
+                  ^js resp (js/fetch get-url
+                                     (clj->js request-opts))
+                  status (.-status resp)
+                  _ (when-not (.-ok resp)
+                      (throw (ex-info "download asset failed"
+                                      {:type :rtc.exception/download-asset-failed
+                                       :data {:status status}})))
+                  total (or (parse-content-length resp) 0)
+                  _ (notify-asset-progress! repo asset-id :download 0 total)
+                  body (.arrayBuffer resp)
+                  body-size (.-byteLength body)
+                  total' (if (pos? total) total body-size)
+                  _ (notify-asset-progress! repo asset-id :download body-size total')
+                  asset-file
+                  (if (not aes-key)
+                    body
+                    (try
+                      (let [asset-file-untransited (ldb/read-transit-str (.decode (js/TextDecoder.) body))]
+                        (crypt/<decrypt-uint8array aes-key asset-file-untransited))
+                      (catch js/SyntaxError _
+                        body)
+                      (catch :default e
+                        ;; if decrypt failed, write origin-body
+                        (if (= "decrypt-uint8array" (ex-message e))
+                          body
+                          (throw e)))))]
+            (<write-asset-bytes! repo asset-id asset-type asset-file))
+          (p/catch
+           (fn [e]
+             (if (= :rtc.exception/download-asset-failed (:type (ex-data e)))
+               (p/rejected e)
+               (p/rejected (ex-info "download asset failed"
+                                    {:type :rtc.exception/download-asset-failed}
+                                    e))))))
       (p/rejected (ex-info "missing asset download info"
                            {:repo repo
                             :asset-uuid asset-uuid
@@ -193,22 +346,28 @@
        client
        #(when-let [conn (worker-state/get-datascript-conn repo)]
           (when-let [ent (d/entity @conn [:block/uuid asset-uuid])]
-            (let [asset-type (:logseq.property.asset/type ent)]
-              (-> (p/let [meta (when (seq asset-type)
-                                 (worker-state/<invoke-main-thread
-                                  :thread-api/get-asset-file-metadata
-                                  repo (str asset-uuid) asset-type))]
-                    (when (and (seq asset-type)
-                               (:logseq.property.asset/remote-metadata ent)
-                               (nil? meta))
-                      (p/let [_ (download-remote-asset! repo graph-id asset-uuid asset-type)]
-                        (when (d/entity @conn [:block/uuid asset-uuid])
-                          (ldb/transact!
-                           conn
-                           [{:block/uuid asset-uuid
-                             :logseq.property.asset/remote-metadata nil}]
-                           {:persist-op? true}))
-                        (client-op/remove-asset-op repo asset-uuid)
-                        (broadcast-rtc-state!-f client))))
+            (let [asset-type (:logseq.property.asset/type ent)
+                  asset-id (str asset-uuid)
+                  should-download? (and (seq asset-type)
+                                        (:logseq.property.asset/remote-metadata ent))]
+              (-> (p/let [meta (when should-download?
+                                 (platform/asset-stat (platform/current)
+                                                      repo
+                                                      (asset-file-name asset-id asset-type)))
+                          missing-local? (and should-download? (nil? meta))
+                          _ (when missing-local?
+                              (download-remote-asset! repo graph-id asset-uuid asset-type))
+                          _ (when missing-local?
+                              (when-let [target-ent (d/entity @conn [:block/uuid asset-uuid])]
+                                (ldb/transact!
+                                 conn
+                                 [[:db/retract (:db/id target-ent)
+                                   :logseq.property.asset/remote-metadata]]
+                                 {:persist-op? true})))
+                          _ (when missing-local?
+                              (client-op/remove-asset-op repo asset-uuid))
+                          _ (when missing-local?
+                              (broadcast-rtc-state!-f client))]
+                    nil)
                   (p/catch (fn [e]
                              (js/console.error e)))))))))))
diff --git a/src/main/frontend/worker/sync/auth.cljs b/src/main/frontend/worker/sync/auth.cljs
index 93bca161f1..2f5b0a0570 100644
--- a/src/main/frontend/worker/sync/auth.cljs
+++ b/src/main/frontend/worker/sync/auth.cljs
@@ -2,6 +2,8 @@
   "Auth and endpoint helpers for db sync."
   (:require [clojure.string :as string]
             [frontend.worker-common.util :as worker-util]
+            [frontend.worker.state :as worker-state]
+            [frontend.worker.sync.util :as sync-util]
             [logseq.common.util :as common-util]
             [promesa.core :as p]))
 
@@ -34,15 +36,59 @@
       (catch :default _
         true))))
 
+(defn oauth-token-url
+  [state]
+  (or (:auth/oauth-token-url state)
+      (when-let [domain (not-empty (:auth/oauth-domain state))]
+        (str "https://" domain "/oauth2/token"))))
+
+(defn <refresh-id&access-token
+  []
+  (let [state @worker-state/*state
+        refresh-token (:auth/refresh-token state)
+        token-url (oauth-token-url state)
+        oauth-client-id (:auth/oauth-client-id state)]
+    (when-not (seq refresh-token)
+      (throw (ex-info "worker auth refresh requires refresh token"
+                      {:code :missing-refresh-token})))
+    (when-not (seq token-url)
+      (throw (ex-info "worker auth refresh requires oauth token url"
+                      {:code :missing-oauth-token-url})))
+    (when-not (seq oauth-client-id)
+      (throw (ex-info "worker auth refresh requires oauth client id"
+                      {:code :missing-oauth-client-id})))
+    (let [form-data (js/URLSearchParams.)]
+      (.set form-data "grant_type" "refresh_token")
+      (.set form-data "client_id" oauth-client-id)
+      (.set form-data "refresh_token" refresh-token)
+      (p/let [resp (js/fetch token-url #js {:method "POST"
+                                            :headers #js {"content-type" "application/x-www-form-urlencoded"}
+                                            :body (.toString form-data)})
+              text (.text resp)
+              data (when (seq text)
+                     (js->clj (js/JSON.parse text) :keywordize-keys true))]
+        (if (.-ok resp)
+          {:id-token (:id_token data)
+           :access-token (:access_token data)}
+          (throw (ex-info "worker auth refresh failed"
+                          {:code :auth-refresh-failed
+                           :status (.-status resp)
+                           :token-url token-url
+                           :body data})))))))
+
 (defn <resolve-ws-token
-  [{:keys [auth-token-f id-token-expired?-f invoke-main-thread-f set-id-token-f]}]
-  (let [token (auth-token-f)]
-    (if (id-token-expired?-f token)
-      (p/let [resp (invoke-main-thread-f)
-              refreshed-token (:id-token resp)]
-        (when (string? refreshed-token)
-          (set-id-token-f refreshed-token)
-          refreshed-token))
+  []
+  (let [token (sync-util/auth-token)
+        token-expired? (id-token-expired? token)]
+    (if (and (not (sync-util/cli-node-owner?)) token-expired?)
+      (p/let [{:keys [id-token access-token]} (<refresh-id&access-token)]
+        (when-not (seq id-token)
+          (throw (ex-info "worker auth refresh returned empty id-token"
+                          {:code :auth-refresh-empty-id-token})))
+        (worker-state/set-new-state!
+         (cond-> {:auth/id-token id-token}
+           (seq access-token) (assoc :auth/access-token access-token)))
+        id-token)
       (p/resolved token))))
 
 (defn get-user-uuid
diff --git a/src/main/frontend/worker/sync/client_op.cljs b/src/main/frontend/worker/sync/client_op.cljs
index 6119e063c2..df0d054fd3 100644
--- a/src/main/frontend/worker/sync/client_op.cljs
+++ b/src/main/frontend/worker/sync/client_op.cljs
@@ -238,8 +238,8 @@
 
 (defn get-graph-uuid
   [repo]
-  (some-> (sqlite-store-or-throw repo)
-          (sqlite-get-meta :graph-uuid)))
+  (when-let [store (sqlite-store-or-throw repo)]
+    (sqlite-get-meta store :graph-uuid)))
 
 (defn get-local-tx
   [repo]
@@ -263,7 +263,9 @@
 (defn reset-local-tx
   "Should be used only when uploading a graph"
   [repo]
-  (update-local-tx repo 0))
+  (let [store (sqlite-store-or-throw repo)]
+    (assert (some? store) repo)
+    (sqlite-set-meta! store :local-tx 0)))
 
 (defn update-local-checksum
   [repo checksum]
diff --git a/src/main/frontend/worker/sync/crypt.cljs b/src/main/frontend/worker/sync/crypt.cljs
index 20c9520ddf..51c36bab6f 100644
--- a/src/main/frontend/worker/sync/crypt.cljs
+++ b/src/main/frontend/worker/sync/crypt.cljs
@@ -1,31 +1,29 @@
 (ns frontend.worker.sync.crypt
   "E2EE helpers for db-sync."
-  (:require [frontend.common.idb :as idb]
-            [clojure.string :as string]
+  (:require [clojure.string :as string]
             [frontend.common.crypt :as crypt]
-            [frontend.common.file.opfs :as opfs]
             [frontend.common.thread-api :refer [def-thread-api]]
             [frontend.worker-common.util :as worker-util]
+            [frontend.worker.platform :as platform]
             [frontend.worker.state :as worker-state]
+            [frontend.worker.sync.auth :as sync-auth]
             [frontend.worker.sync.const :as sync-const]
+            [frontend.worker.ui-request :as ui-request]
             [lambdaisland.glogi :as log]
             [logseq.db :as ldb]
-            [logseq.db-sync.malli-schema :as db-sync-schema]
-            [promesa.core :as p]))
+            [promesa.core :as p]
+            [frontend.worker.sync.util :refer [fail-fast fetch-json coerce-http-request] :as sync-util]))
 
 (defonce ^:private *graph->aes-key (atom {}))
 (defonce ^:private *user-rsa-key-pair-inflight (atom {}))
-(defonce ^:private e2ee-password-file "e2ee-password")
-(defonce ^:private native-env?
-  (let [href (try (.. js/self -location -href)
-                  (catch :default _ nil))]
-    (boolean (and (string? href)
-                  (or (string/includes? href "electron=true")
-                      (string/includes? href "capacitor=true"))))))
-
-(def ^:private invalid-coerce ::invalid-coerce)
+(defonce ^:private node-default-auth-file "~/logseq/auth.json")
+(defonce ^:private e2ee-password-secret-key "logseq-encrypted-password")
 (def ^:private invalid-transit ::invalid-transit)
 
+(defn- runtime
+  [platform']
+  (get-in platform' [:env :runtime]))
+
 (defn- read-transit-safe
   [value]
   (try
@@ -33,96 +31,162 @@
     (catch :default _
       invalid-transit)))
 
-(defn- native-worker?
-  []
-  native-env?)
+(defn- browser-runtime?
+  [platform']
+  (= :browser (runtime platform')))
 
-(defn- <native-save-password-text!
-  [encrypted-text]
-  (worker-state/<invoke-main-thread :thread-api/native-save-e2ee-password encrypted-text))
+(defn- owner-source
+  [platform']
+  (get-in platform' [:env :owner-source]))
 
-(defn- <native-read-password-text
-  []
-  (worker-state/<invoke-main-thread :thread-api/native-get-e2ee-password))
+(defn- capacitor-runtime?
+  [platform']
+  (and (= :browser (runtime platform'))
+       (= :capacitor (owner-source platform'))))
 
-(defn- <native-delete-password-text!
+(defn- auth-file-path
   []
-  (worker-state/<invoke-main-thread :thread-api/native-delete-e2ee-password))
+  node-default-auth-file)
+
+(defn- interactive-runtime?
+  []
+  (let [env (:env (platform/current))
+        runtime' (:runtime env)
+        owner-source' (:owner-source env)]
+    (or (= :browser runtime')
+        (and (= :node runtime')
+             (= :electron owner-source')))))
+
+(defn- missing-e2ee-password-ex
+  [data]
+  (ex-info "missing-e2ee-password"
+           (merge {:code :db-sync/missing-e2ee-password
+                   :field :e2ee-password}
+                  data)))
+
+(defn- fail-missing-e2ee-password!
+  [data]
+  (fail-fast :db-sync/missing-e2ee-password
+             (merge {:code :db-sync/missing-e2ee-password
+                     :field :e2ee-password}
+                    data)))
+
+(defn- throw-missing-e2ee-password!
+  [data]
+  (throw (missing-e2ee-password-ex data)))
+
+(defn- ensure-refresh-token!
+  [refresh-token]
+  (when-not (seq refresh-token)
+    (fail-missing-e2ee-password! {:reason :missing-refresh-token
+                                  :hint "Run logseq login first."})))
+
+(defn- missing-persisted-password-error?
+  [error]
+  (let [data (ex-data error)]
+    (and (contains? #{:db-sync/missing-e2ee-password
+                      :missing-e2ee-password}
+                    (or (:code data)
+                        (some-> error ex-message keyword)))
+         (= :missing-persisted-password (:reason data)))))
+
+(defn- parse-auth-file
+  [text]
+  (when (seq text)
+    (try
+      (js->clj (js/JSON.parse text) :keywordize-keys true)
+      (catch :default _
+        invalid-transit))))
+
+(defn- <read-refresh-token-from-auth-file
+  [platform']
+  (p/let [text (-> (platform/read-text! platform' (auth-file-path))
+                   (p/catch (fn [_]
+                              nil)))
+          auth-data (parse-auth-file text)]
+    (when (= invalid-transit auth-data)
+      (fail-missing-e2ee-password! {:reason :invalid-auth-file
+                                    :hint "Run logseq login first."}))
+    (let [refresh-token (:refresh-token auth-data)]
+      (ensure-refresh-token! refresh-token)
+      refresh-token)))
 
 (defn- <save-e2ee-password
-  [refresh-token password]
-  (p/let [result (crypt/<encrypt-text-by-text-password refresh-token password)
-          text (ldb/write-transit-str result)]
-    (if (native-worker?)
-      (-> (p/let [_ (<native-save-password-text! text)]
-            nil)
-          (p/catch (fn [e]
-                     (log/error :native-save-e2ee-password {:error e})
-                     (opfs/<write-text! e2ee-password-file text))))
-      (opfs/<write-text! e2ee-password-file text))))
+  [password]
+  (p/let [platform' (platform/current)
+          refresh-token (if (browser-runtime? platform')
+                          (:auth/refresh-token @worker-state/*state)
+                          (<read-refresh-token-from-auth-file platform'))
+          _ (ensure-refresh-token! refresh-token)
+          result (crypt/<encrypt-text-by-text-password refresh-token password)
+          text (ldb/write-transit-str result)
+          native-saved? (if (capacitor-runtime? platform')
+                          (-> (ui-request/<request :native-save-e2ee-password
+                                                   {:key e2ee-password-secret-key
+                                                    :encrypted-text text})
+                              (p/then (fn [resp]
+                                        (true? (:supported? resp))))
+                              (p/catch (fn [e]
+                                         (log/warn :db-sync/save-e2ee-password-native-failed {:error e})
+                                         false)))
+                          false)]
+    (if native-saved?
+      nil
+      (platform/save-secret-text! platform' e2ee-password-secret-key text))))
+
+(defn- <read-platform-e2ee-password-text
+  [platform']
+  (-> (platform/read-secret-text platform' e2ee-password-secret-key)
+      (p/catch (fn [e]
+                 (log/warn :db-sync/read-e2ee-password-secret-failed {:error e})
+                 nil))))
 
 (defn- <read-e2ee-password
   [refresh-token]
-  (p/let [text (if (native-worker?)
-                 (<native-read-password-text)
-                 (opfs/<read-text! e2ee-password-file))
-          data (ldb/read-transit-str text)
-          password (crypt/<decrypt-text-by-text-password refresh-token data)]
-    password))
+  (ensure-refresh-token! refresh-token)
+  (p/let [platform' (platform/current)
+          native-result (if (capacitor-runtime? platform')
+                          (-> (ui-request/<request :native-get-e2ee-password
+                                                   {:key e2ee-password-secret-key})
+                              (p/catch (fn [e]
+                                         (log/warn :db-sync/read-e2ee-password-native-failed {:error e})
+                                         {:supported? false})))
+                          {:supported? false})
+          text (if (:supported? native-result)
+                 (:encrypted-text native-result)
+                 (<read-platform-e2ee-password-text platform'))]
+    (when-not (seq text)
+      (throw-missing-e2ee-password! {:reason :missing-persisted-password
+                                     :hint "Provide --e2ee-password to persist it."}))
+    (let [data (try
+                 (ldb/read-transit-str text)
+                 (catch :default _
+                   invalid-transit))]
+      (when (= invalid-transit data)
+        (fail-fast :db-sync/invalid-e2ee-password-payload
+                   {:field :e2ee-password
+                    :reason :invalid-transit-payload}))
+      (crypt/<decrypt-text-by-text-password refresh-token data))))
 
 (defn- <clear-e2ee-password!
   []
-  (p/let [_ (when (native-worker?)
-              (-> (<native-delete-password-text!)
+  (p/let [platform' (platform/current)
+          native-deleted? (if (capacitor-runtime? platform')
+                            (-> (ui-request/<request :native-delete-e2ee-password
+                                                     {:key e2ee-password-secret-key})
+                                (p/then (fn [resp]
+                                          (true? (:supported? resp))))
+                                (p/catch (fn [e]
+                                           (log/warn :db-sync/delete-e2ee-password-native-failed {:error e})
+                                           false)))
+                            false)
+          _ (when-not native-deleted?
+              (-> (platform/delete-secret-text! platform' e2ee-password-secret-key)
                   (p/catch (fn [e]
-                             (log/error :native-delete-e2ee-password {:error e})
-                             nil))))
-          _ (-> (opfs/<delete-file! e2ee-password-file)
-                (p/catch (fn [e]
-                           (log/error :opfs-delete-e2ee-password {:error e})
-                           nil)))]
+                             (log/warn :db-sync/delete-e2ee-password-secret-failed {:error e})
+                             nil))))]
     nil))
 
-(defn- auth-token []
-  (worker-state/get-id-token))
-
-(defn- auth-headers []
-  (let [token (auth-token)]
-    (when (nil? token)
-      (throw (ex-info "Empty token" {})))
-    {"authorization" (str "Bearer " token)}))
-
-(defn- with-auth-headers [opts]
-  (if-let [auth (auth-headers)]
-    (assoc opts :headers (merge (or (:headers opts) {}) auth))
-    opts))
-
-(defn- coerce
-  [coercer value context]
-  (try
-    (coercer value)
-    (catch :default e
-      (log/error :db-sync/malli-coerce-failed (merge context {:error e :value value}))
-      invalid-coerce)))
-
-(defn- coerce-http-request [schema-key body]
-  (if-let [coercer (get db-sync-schema/http-request-coercers schema-key)]
-    (let [coerced (coerce coercer body {:schema schema-key :dir :request})]
-      (when-not (= coerced invalid-coerce)
-        coerced))
-    body))
-
-(defn- coerce-http-response [schema-key body]
-  (if-let [coercer (get db-sync-schema/http-response-coercers schema-key)]
-    (let [coerced (coerce coercer body {:schema schema-key :dir :response})]
-      (when-not (= coerced invalid-coerce)
-        coerced))
-    body))
-
-(defn fail-fast [tag data]
-  (log/error tag data)
-  (throw (ex-info (name tag) data)))
-
 (defn e2ee-base
   []
   (or (:http-base @worker-state/*db-sync-config)
@@ -137,54 +201,45 @@
                      :else ws-url)]
           (string/replace base #"/sync/%s$" "")))))
 
-(defn- fetch-json
-  [url opts {:keys [response-schema error-schema] :or {error-schema :error}}]
-  (p/let [resp (js/fetch url (clj->js (with-auth-headers opts)))
-          text (.text resp)
-          data (when (seq text) (js/JSON.parse text))]
-    (if (.-ok resp)
-      (let [body (js->clj data :keywordize-keys true)
-            body (if response-schema
-                   (coerce-http-response response-schema body)
-                   body)]
-        (if (or (nil? response-schema) body)
-          body
-          (throw (ex-info "db-sync invalid response"
-                          {:status (.-status resp)
-                           :url url
-                           :body body}))))
-      (let [body (when data (js->clj data :keywordize-keys true))
-            body (if error-schema
-                   (coerce-http-response error-schema body)
-                   body)]
-        (throw (ex-info "db-sync request failed"
-                        {:status (.-status resp)
-                         :url url
-                         :body body}))))))
-
 (defn graph-e2ee?
   [repo]
   (when-let [conn (worker-state/get-datascript-conn repo)]
-    (true? (ldb/get-graph-rtc-e2ee? @conn))))
+    (ldb/get-graph-rtc-e2ee? @conn)))
 
 (defn- get-user-uuid []
-  (some-> (worker-state/get-id-token) worker-util/parse-jwt :sub))
+  (some-> (sync-util/auth-token) worker-util/parse-jwt :sub))
+
+(defn- token->user-uuid
+  [token]
+  (some-> token worker-util/parse-jwt :sub))
+
+(defn- <resolve-user-uuid
+  []
+  (let [user-id (get-user-uuid)]
+    (if (seq user-id)
+      (p/resolved user-id)
+      (-> (sync-auth/<resolve-ws-token)
+          (p/then token->user-uuid)
+          (p/catch (fn [_error]
+                     nil))))))
 
 (defn- <get-item
   [k]
-  (assert (and k @idb/store))
-  (p/let [r (idb/get-item k)]
-    (some-> r (js->clj :keywordize-keys true))))
+  (assert k)
+  (p/let [r (platform/kv-get (platform/current) k)]
+    (cond
+      (instance? js/ArrayBuffer r) (js/Uint8Array. r)
+      :else r)))
 
 (defn- <set-item!
   [k value]
-  (assert (and k @idb/store))
-  (idb/set-item! k value))
+  (assert k)
+  (platform/kv-set! (platform/current) k value))
 
 (defn- <clear-item!
   [k]
-  (assert (and k @idb/store))
-  (idb/remove-item! k))
+  (assert k)
+  (platform/kv-set! (platform/current) k nil))
 
 (defn- graph-encrypted-aes-key-idb-key
   [graph-id]
@@ -201,9 +256,10 @@
               {:response-schema :e2ee/user-keys}))
 
 (defn- user-rsa-key-pair-valid?
-  [{:keys [public-key encrypted-private-key]}]
-  (and (string? public-key)
-       (string? encrypted-private-key)))
+  [pair]
+  (and (map? pair)
+       (string? (:public-key pair))
+       (string? (:encrypted-private-key pair))))
 
 (defn- <set-user-rsa-key-pair-to-idb!
   [base user-id pair]
@@ -231,7 +287,7 @@
 
 (defn- <get-user-rsa-key-pair-raw
   [base]
-  (let [user-id (get-user-uuid)]
+  (p/let [user-id (<resolve-user-uuid)]
     (when-not (and (string? base) (string? user-id))
       (fail-fast :db-sync/missing-field {:base base :user-id user-id :field :user-rsa-key-pair}))
     (let [k [base user-id]]
@@ -244,7 +300,7 @@
                              (if (user-rsa-key-pair-valid? pair)
                                (p/let [_ (<set-user-rsa-key-pair-to-idb! base user-id pair)]
                                  pair)
-                               pair))))
+                               nil))))
                        (p/finally (fn []
                                     (swap! *user-rsa-key-pair-inflight dissoc k))))]
           (swap! *user-rsa-key-pair-inflight assoc k task)
@@ -262,14 +318,56 @@
                               :headers {"content-type" "application/json"}
                               :body (js/JSON.stringify (clj->js body))}
                              {:response-schema :e2ee/user-keys})
-            user-id (get-user-uuid)
+            user-id (<resolve-user-uuid)
             _ (<set-user-rsa-key-pair-to-idb! base user-id pair)]
       pair)))
 
+(defn- <request-e2ee-password-from-ui
+  [payload]
+  (p/let [{:keys [password]} (ui-request/<request :request-e2ee-password
+                                                   payload
+                                                   {:hint "Provide e2ee-password to continue."})]
+    (when-not (seq password)
+      (fail-fast :db-sync/missing-e2ee-password {:field :e2ee-password
+                                                 :reason :empty-ui-password}))
+    password))
+
+(defn- <verify-and-save-e2ee-password!
+  [password encrypted-private-key-or-str]
+  (when-not (seq password)
+    (fail-missing-e2ee-password! {:reason :empty-password}))
+  (p/let [encrypted-private-key (if (string? encrypted-private-key-or-str)
+                                  (ldb/read-transit-str encrypted-private-key-or-str)
+                                  encrypted-private-key-or-str)
+          private-key (crypt/<decrypt-private-key password encrypted-private-key)
+          _ (<save-e2ee-password password)]
+    private-key))
+
+(defn- <verify-and-save-e2ee-password-from-server!
+  [password]
+  (let [base (e2ee-base)]
+    (when-not (string? base)
+      (fail-fast :db-sync/missing-field {:base base
+                                         :field :e2ee-base}))
+    (p/let [{:keys [encrypted-private-key]} (<get-user-rsa-key-pair-raw base)]
+      (when-not (string? encrypted-private-key)
+        (fail-fast :db-sync/missing-field {:base base
+                                           :field :encrypted-private-key}))
+      (<verify-and-save-e2ee-password! password encrypted-private-key))))
+
 (defn- <generate-and-upload-user-rsa-key-pair!
-  [base]
+  [base {:keys [password]}]
   (p/let [{:keys [publicKey privateKey]} (crypt/<generate-rsa-key-pair)
-          {:keys [password]} (worker-state/<invoke-main-thread :thread-api/request-e2ee-password)
+          password (cond
+                     (and (string? password) (seq password))
+                     password
+
+                     (interactive-runtime?)
+                     (<request-e2ee-password-from-ui {:reason :generate-user-rsa-key-pair})
+
+                     :else
+                     (fail-missing-e2ee-password! {:reason :missing-password-for-generate-user-rsa-key-pair
+                                                   :hint "Provide --e2ee-password when running sync ensure-keys --upload-keys."}))
           encrypted-private-key (crypt/<encrypt-private-key password privateKey)
           exported-public-key (crypt/<export-public-key publicKey)
           public-key-str (ldb/write-transit-str exported-public-key)
@@ -280,7 +378,7 @@
        :password password})))
 
 (defn- <ensure-user-rsa-key-pair-raw
-  [base {:keys [ensure-server? server-rsa-keys-exists?]}]
+  [base {:keys [ensure-server? server-rsa-keys-exists?] :as opts}]
   (p/let [existing (<get-user-rsa-key-pair-raw base)
           existing-valid? (user-rsa-key-pair-valid? existing)
           server-rsa-keys-exists?
@@ -299,7 +397,7 @@
         existing)
 
       :else
-      (<generate-and-upload-user-rsa-key-pair! base))))
+      (<generate-and-upload-user-rsa-key-pair! base opts))))
 
 (defn ensure-user-rsa-keys!
   ([]
@@ -314,11 +412,29 @@
 
 (defn- <decrypt-private-key
   [encrypted-private-key-str]
-  (p/let [encrypted-private-key (ldb/read-transit-str encrypted-private-key-str)
-          exported-private-key (worker-state/<invoke-main-thread
-                                :thread-api/decrypt-user-e2ee-private-key
-                                encrypted-private-key)]
-    (crypt/<import-private-key exported-private-key)))
+  (let [<decrypt-in-headless
+        (fn [encrypted-private-key]
+          (let [refresh-token (:auth/refresh-token @worker-state/*state)]
+            (p/let [password (<read-e2ee-password refresh-token)]
+              (when-not (seq password)
+                (fail-missing-e2ee-password! {:reason :headless-empty-password
+                                              :hint "Provide --e2ee-password to persist it."}))
+              (crypt/<decrypt-private-key password encrypted-private-key))))
+
+        <decrypt-with-ui-request
+        (fn [encrypted-private-key]
+          (p/let [password (<request-e2ee-password-from-ui {:reason :decrypt-user-rsa-private-key})]
+            (<verify-and-save-e2ee-password! password encrypted-private-key)))]
+    (p/let [encrypted-private-key (ldb/read-transit-str encrypted-private-key-str)]
+      (-> (<decrypt-in-headless encrypted-private-key)
+          (p/catch (fn [headless-error]
+                     (if-not (interactive-runtime?)
+                       (p/rejected headless-error)
+                       (-> (<decrypt-with-ui-request encrypted-private-key)
+                           (p/catch (fn [ui-error]
+                                      (if (missing-persisted-password-error? headless-error)
+                                        (p/rejected ui-error)
+                                        (p/rejected headless-error))))))))))))
 
 (defn- <import-public-key
   [public-key-str]
@@ -383,53 +499,67 @@
                                              :retry-error retry-error})
                                   (throw retry-error)))))))))
 
+(defn <preflight-upload-e2ee!
+  [repo encrypted-graph?]
+  (if-not (true? encrypted-graph?)
+    (p/resolved nil)
+    (let [base (e2ee-base)]
+      (p/let [user-id (<resolve-user-uuid)]
+        (when-not (and (string? base) (string? user-id))
+          (fail-fast :db-sync/missing-field {:repo repo
+                                             :base base
+                                             :user-id user-id
+                                             :field :user-rsa-key-pair}))
+        (p/let [_ (<load-user-rsa-key-material base user-id nil)]
+          nil)))))
+
 (defn <ensure-graph-aes-key
   [repo graph-id]
   (if-not (graph-e2ee? repo)
     (p/resolved nil)
     (if-let [cached (get @*graph->aes-key graph-id)]
       (p/resolved cached)
-      (let [base (e2ee-base)
-            user-id (get-user-uuid)]
-        (when-not (and (string? base) (string? user-id))
-          (fail-fast :db-sync/missing-field {:base base :user-id user-id :graph-id graph-id}))
-        (p/let [{:keys [public-key private-key]} (<load-user-rsa-key-material base user-id graph-id)
-                local-encrypted (when graph-id
-                                  (<get-item (graph-encrypted-aes-key-idb-key graph-id)))
-                remote-encrypted (when (and (nil? local-encrypted) graph-id)
-                                   (<fetch-graph-encrypted-aes-key base graph-id))
-                encrypted-aes-key (or local-encrypted remote-encrypted)
-                aes-key (if encrypted-aes-key
-                          (-> (crypt/<decrypt-aes-key private-key encrypted-aes-key)
-                              (p/catch (fn [error]
-                                         (if-not (and graph-id local-encrypted)
-                                           (throw error)
-                                           (let [aes-key-k (graph-encrypted-aes-key-idb-key graph-id)]
-                                             (-> (p/let [_ (<clear-item! aes-key-k)
-                                                         refetched-encrypted (<fetch-graph-encrypted-aes-key base graph-id)]
-                                                   (if-not refetched-encrypted
-                                                     (throw error)
-                                                     (p/let [aes-key (crypt/<decrypt-aes-key private-key refetched-encrypted)
-                                                             _ (<set-item! aes-key-k refetched-encrypted)]
-                                                       aes-key)))
-                                                 (p/catch (fn [retry-error]
-                                                            (log/warn :db-sync/graph-aes-key-cache-invalid
-                                                                      {:base base
-                                                                       :user-id user-id
-                                                                       :graph-id graph-id
-                                                                       :first-error error
-                                                                       :retry-error retry-error})
-                                                            (throw retry-error)))))))))
-                          (p/let [aes-key (crypt/<generate-aes-key)
-                                  encrypted (crypt/<encrypt-aes-key public-key aes-key)
-                                  encrypted-str (ldb/write-transit-str encrypted)
-                                  _ (<upsert-graph-encrypted-aes-key! base graph-id encrypted-str)
-                                  _ (<set-item! (graph-encrypted-aes-key-idb-key graph-id) encrypted)]
-                            aes-key))
-                _ (when (and graph-id encrypted-aes-key (nil? local-encrypted))
-                    (<set-item! (graph-encrypted-aes-key-idb-key graph-id) encrypted-aes-key))]
-          (swap! *graph->aes-key assoc graph-id aes-key)
-          aes-key)))))
+      (let [base (e2ee-base)]
+        (p/let [user-id (<resolve-user-uuid)]
+          (when-not (and (string? base) (string? user-id))
+            (fail-fast :db-sync/missing-field {:base base :user-id user-id :graph-id graph-id}))
+          (p/let [{:keys [public-key private-key]} (<load-user-rsa-key-material base user-id graph-id)
+                  local-encrypted (when graph-id
+                                    (<get-item (graph-encrypted-aes-key-idb-key graph-id)))
+                  remote-encrypted (when (and (nil? local-encrypted) graph-id)
+                                     (<fetch-graph-encrypted-aes-key base graph-id))
+                  encrypted-aes-key (or local-encrypted remote-encrypted)
+                  aes-key (if encrypted-aes-key
+                            (-> (crypt/<decrypt-aes-key private-key encrypted-aes-key)
+                                (p/catch (fn [error]
+                                           (if-not (and graph-id local-encrypted)
+                                             (throw error)
+                                             (let [aes-key-k (graph-encrypted-aes-key-idb-key graph-id)]
+                                               (-> (p/let [_ (<clear-item! aes-key-k)
+                                                           refetched-encrypted (<fetch-graph-encrypted-aes-key base graph-id)]
+                                                     (if-not refetched-encrypted
+                                                       (throw error)
+                                                       (p/let [aes-key (crypt/<decrypt-aes-key private-key refetched-encrypted)
+                                                               _ (<set-item! aes-key-k refetched-encrypted)]
+                                                         aes-key)))
+                                                   (p/catch (fn [retry-error]
+                                                              (log/warn :db-sync/graph-aes-key-cache-invalid
+                                                                        {:base base
+                                                                         :user-id user-id
+                                                                         :graph-id graph-id
+                                                                         :first-error error
+                                                                         :retry-error retry-error})
+                                                              (throw retry-error)))))))))
+                            (p/let [aes-key (crypt/<generate-aes-key)
+                                    encrypted (crypt/<encrypt-aes-key public-key aes-key)
+                                    encrypted-str (ldb/write-transit-str encrypted)
+                                    _ (<upsert-graph-encrypted-aes-key! base graph-id encrypted-str)
+                                    _ (<set-item! (graph-encrypted-aes-key-idb-key graph-id) encrypted)]
+                              aes-key))
+                  _ (when (and graph-id encrypted-aes-key (nil? local-encrypted))
+                      (<set-item! (graph-encrypted-aes-key-idb-key graph-id) encrypted-aes-key))]
+            (swap! *graph->aes-key assoc graph-id aes-key)
+            aes-key))))))
 
 (defn <fetch-graph-aes-key-for-download
   [graph-id]
@@ -636,7 +766,7 @@
     (ldb/write-transit-str new-encrypted-private-key)))
 
 (defn <change-e2ee-password!
-  [refresh-token user-uuid old-password new-password]
+  [_refresh-token user-uuid old-password new-password]
   (let [base (e2ee-base)]
     (when-not (string? base)
       (fail-fast :db-sync/missing-field {:base base :user-uuid user-uuid}))
@@ -645,9 +775,13 @@
         (fail-fast :db-sync/missing-field {:base base :user-uuid user-uuid :field :user-rsa-key-pair}))
       (p/let [encrypted-private-key' (<re-encrypt-private-key encrypted-private-key old-password new-password)
               _ (<upload-user-rsa-key-pair! base public-key encrypted-private-key')
-              _ (<save-e2ee-password refresh-token new-password)]
+              _ (<save-e2ee-password new-password)]
         nil))))
 
+(defn cancel-ui-requests!
+  [context]
+  (ui-request/cancel-all! context))
+
 (def-thread-api :thread-api/get-user-rsa-key-pair
   [_token _user-uuid]
   (let [base (e2ee-base)]
@@ -659,7 +793,7 @@
          :encrypted-private-key encrypted-private-key}))))
 
 (def-thread-api :thread-api/init-user-rsa-key-pair
-  [_token refresh-token _user-uuid]
+  [_token _refresh-token _user-uuid]
   (let [base (e2ee-base)]
     (when-not (string? base)
       (fail-fast :db-sync/missing-field {:base base}))
@@ -667,17 +801,17 @@
       (when-not (and (string? (:public-key existing))
                      (string? (:encrypted-private-key existing)))
         (p/let [{:keys [publicKey privateKey]} (crypt/<generate-rsa-key-pair)
-                {:keys [password]} (worker-state/<invoke-main-thread :thread-api/request-e2ee-password)
+                password (<request-e2ee-password-from-ui {:reason :init-user-rsa-key-pair})
                 encrypted-private-key (crypt/<encrypt-private-key password privateKey)
                 exported-public-key (crypt/<export-public-key publicKey)
                 public-key-str (ldb/write-transit-str exported-public-key)
                 encrypted-private-key-str (ldb/write-transit-str encrypted-private-key)
                 _ (<upload-user-rsa-key-pair! base public-key-str encrypted-private-key-str)
-                _ (<save-e2ee-password refresh-token password)]
+                _ (<save-e2ee-password password)]
           nil)))))
 
 (def-thread-api :thread-api/reset-user-rsa-key-pair
-  [_token refresh-token _user-uuid new-password]
+  [_token _refresh-token _user-uuid new-password]
   (p/let [{:keys [publicKey privateKey]} (crypt/<generate-rsa-key-pair)
           encrypted-private-key (crypt/<encrypt-private-key new-password privateKey)
           exported-public-key (crypt/<export-public-key publicKey)
@@ -687,24 +821,26 @@
     (when-not (string? base)
       (fail-fast :db-sync/missing-field {:base base}))
     (p/let [_ (<upload-user-rsa-key-pair! base public-key-str encrypted-private-key-str)
-            _ (<save-e2ee-password refresh-token new-password)]
+            _ (<save-e2ee-password new-password)]
       nil)))
 
 (def-thread-api :thread-api/change-e2ee-password
   [_token refresh-token user-uuid old-password new-password]
   (<change-e2ee-password! refresh-token user-uuid old-password new-password))
 
+(def-thread-api :thread-api/verify-and-save-e2ee-password
+  [_refresh-token password]
+  (p/let [_ (<verify-and-save-e2ee-password-from-server! password)]
+    nil))
+
 (def-thread-api :thread-api/get-e2ee-password
   [refresh-token]
-  (-> (p/let [password (<read-e2ee-password refresh-token)]
-        {:password password})
-      (p/catch (fn [e]
-                 (log/error :read-e2ee-password e)
-                 (ex-info ":thread-api/get-e2ee-password" {})))))
+  (p/let [password (<read-e2ee-password refresh-token)]
+    {:password password}))
 
 (def-thread-api :thread-api/save-e2ee-password
-  [refresh-token password]
-  (<save-e2ee-password refresh-token password))
+  [password]
+  (<save-e2ee-password password))
 
 (def-thread-api :thread-api/clear-e2ee-password
   []
diff --git a/src/main/frontend/worker/sync/download.cljs b/src/main/frontend/worker/sync/download.cljs
index 54b399a99d..1fb4213e36 100644
--- a/src/main/frontend/worker/sync/download.cljs
+++ b/src/main/frontend/worker/sync/download.cljs
@@ -4,6 +4,7 @@
    [datascript.core :as d]
    [frontend.common.thread-api :as thread-api]
    [frontend.worker-common.util :as worker-util]
+   [frontend.worker.platform :as platform]
    [frontend.worker.search :as search]
    [frontend.worker.shared-service :as shared-service]
    [frontend.worker.state :as worker-state]
@@ -12,11 +13,13 @@
    [frontend.worker.sync.crypt :as sync-crypt]
    [frontend.worker.sync.log-and-state :as rtc-log-and-state]
    [frontend.worker.sync.temp-sqlite :as sync-temp-sqlite]
-   [frontend.worker.sync.transport :as sync-transport]
+   [frontend.worker.sync.util :refer [fail-fast] :as sync-util]
+   [lambdaisland.glogi :as log]
    [logseq.db-sync.snapshot :as snapshot]
    [logseq.db.common.sqlite :as common-sqlite]
    [logseq.db.frontend.schema :as db-schema]
-   [promesa.core :as p]))
+   [promesa.core :as p]
+   [logseq.db :as ldb]))
 
 (defn- ->uint8 [data]
   (cond
@@ -80,18 +83,28 @@
       (nil? body)
       (p/resolved nil)
 
-      (and (= "gzip" encoding) (exists? js/DecompressionStream))
-      (if (fn? (.-tee body))
-        (let [branches (.tee body)
-              probe (aget branches 0)
-              payload (aget branches 1)]
-          (-> (<stream-starts-with-gzip? probe)
-              (p/then (fn [gzip?]
-                        (if gzip?
-                          (.pipeThrough payload (js/DecompressionStream. "gzip"))
-                          payload)))
-              (p/catch (fn [_] payload))))
-        (p/resolved (.pipeThrough body (js/DecompressionStream. "gzip"))))
+      ;; Never trust `content-encoding` alone.
+      ;; Some runtimes (e.g. Node/undici fetch) may auto-decompress body while
+      ;; still exposing `content-encoding: gzip` in headers.
+      ;; We only stream-decompress when the first bytes are actual gzip magic.
+      (and (= "gzip" encoding)
+           (exists? js/DecompressionStream)
+           (fn? (.-tee body)))
+      (let [branches (.tee body)
+            probe (aget branches 0)
+            payload (aget branches 1)]
+        (-> (<stream-starts-with-gzip? probe)
+            (p/then (fn [gzip?]
+                      (if gzip?
+                        (.pipeThrough payload (js/DecompressionStream. "gzip"))
+                        payload)))
+            ;; If probing fails, keep original payload stream.
+            (p/catch (fn [_] payload))))
+
+      ;; If we cannot safely probe (no tee support), do not guess.
+      ;; Fall back to the arrayBuffer path where we inspect magic bytes first.
+      (= "gzip" encoding)
+      (p/resolved nil)
 
       :else
       (p/resolved body))))
@@ -141,15 +154,7 @@
 
 (defn- fetch-json
   [url opts schema]
-  (sync-transport/fetch-json
-   with-auth-headers
-   url
-   opts
-   {:response-schema schema}))
-
-(defn- fail-fast
-  [tag data]
-  (throw (ex-info (name tag) data)))
+  (sync-util/fetch-json url opts {:response-schema schema}))
 
 (defonce ^:private *import-state (atom nil))
 (def ^:private snapshot-import-datoms-batch-size 10000)
@@ -171,7 +176,7 @@
                                    :graph-uuid graph-id
                                    :message "Graph is ready!"})
        (when-let [^js db (worker-state/get-sqlite-conn repo :db)]
-         (.exec db "PRAGMA wal_checkpoint(2)"))
+         (.exec db "PRAGMA wal_checkpoint(TRUNCATE)"))
        (client-op/update-local-tx repo remote-tx)
        (shared-service/broadcast-to-clients! :add-repo {:repo repo}))
       (p/catch (fn [error]
@@ -191,27 +196,27 @@
             :graph-id graph-id
             :import-id import-id}))
 
-(defn- <remove-import-temp-db-file!
-  [repo path]
-  (-> (p/let [^js root (.getDirectory js/navigator.storage)
-              ^js dir (.getDirectoryHandle root (str "." (worker-util/get-pool-name repo)))]
-        (.removeEntry dir (subs path 1)))
-      (p/catch
-       (fn [error]
-         (if (= "NotFoundError" (.-name error))
-           nil
-           (p/rejected error))))))
+(defn- import-temp-pool-name
+  [repo]
+  (worker-util/get-pool-name (str "download-import-" repo)))
 
 (defn- close-import-state!
-  [{:keys [repo rows-db rows-path]}]
+  [{:keys [rows-db rows-pool]}]
   (when rows-db
     (try
       (.close rows-db)
       (catch :default _)))
-  (when (and repo rows-path)
-    (-> (<remove-import-temp-db-file! repo rows-path)
+  (when rows-pool
+    (-> (platform/remove-storage-pool! (platform/current) rows-pool)
         (p/catch (fn [_] nil)))))
 
+(defn close-import-state-for-repo!
+  [repo]
+  (when-let [state @*import-state]
+    (when (= repo (:repo state))
+      (close-import-state! state)
+      (reset! *import-state nil))))
+
 (defn- clear-import-state!
   [import-id]
   (when-let [state @*import-state]
@@ -219,14 +224,6 @@
       (close-import-state! state)
       (reset! *import-state nil))))
 
-(defn close-import-state-for-repo!
-  [repo]
-  (when-let [state @*import-state]
-    (when (= repo (:repo state))
-      (close-import-state! state)
-      (reset! *import-state nil)))
-  nil)
-
 (defn- require-import-state!
   [repo graph-id import-id]
   (let [state @*import-state]
@@ -262,29 +259,39 @@
 
 (defn- <create-import-temp-db!
   [repo]
-  (if-let [^js pool (worker-state/get-opfs-pool repo)]
-    (p/let [path (str "/download-import-" (random-uuid) ".sqlite")
-            ^js db (new (.-OpfsSAHPoolDb pool) path)]
-      (common-sqlite/create-kvs-table! db)
-      {:rows-db db
-       :rows-path path})
-    (fail-fast :db-sync/missing-field {:repo repo :field :opfs-pool})))
+  (if-let [sqlite @worker-state/*sqlite]
+    (let [current-platform (platform/current)
+          pool-name (import-temp-pool-name repo)]
+      (p/let [pool (platform/install-storage-pool current-platform sqlite pool-name)
+              path (platform/resolve-db-path current-platform pool-name pool "/download-import.sqlite")
+              db (platform/sqlite-open current-platform
+                                       {:sqlite sqlite
+                                        :pool pool
+                                        :path path
+                                        :mode "c"})]
+        (common-sqlite/create-kvs-table! db)
+        {:rows-db db
+         :rows-path path
+         :rows-pool pool}))
+    (fail-fast :db-sync/missing-field {:repo repo :field :sqlite})))
 
 (defn- <ensure-import-rows-db!
   [{:keys [import-id repo rows-db] :as state}]
   (if rows-db
     (p/resolved state)
-    (p/let [{:keys [rows-db rows-path]} (<create-import-temp-db! repo)]
+    (p/let [{:keys [rows-db rows-path rows-pool]} (<create-import-temp-db! repo)]
       (swap! *import-state
              (fn [current]
                (if (= import-id (:import-id current))
                  (assoc current
                         :rows-db rows-db
-                        :rows-path rows-path)
+                        :rows-path rows-path
+                        :rows-pool rows-pool)
                  current)))
       (assoc state
              :rows-db rows-db
-             :rows-path rows-path))))
+             :rows-path rows-path
+             :rows-pool rows-pool))))
 
 (defn- datom->tx
   [{:keys [e a v]}]
@@ -380,6 +387,7 @@
   (let [graph-e2ee? (if (nil? graph-e2ee?) true (true? graph-e2ee?))]
     (-> (p/let [close-db-f (require-thread-api-f! :thread-api/db-sync-close-db)
                 unlink-db-f (require-thread-api-f! :thread-api/unsafe-unlink-db)
+                recreate-lock-f (require-thread-api-f! :thread-api/db-sync-recreate-lock)
                 invalidate-search-db-f (require-thread-api-f! :thread-api/db-sync-invalidate-search-db)
                 create-or-open-db-f (require-thread-api-f! :thread-api/create-or-open-db)
                 _ (when-let [state @*import-state]
@@ -388,6 +396,7 @@
                 _ (reset! *import-state nil)
                 _ (when reset? (close-db-f repo))
                 _ (when reset? (unlink-db-f repo))
+                _ (when reset? (recreate-lock-f repo))
                 _ (when reset? (invalidate-search-db-f repo))
                 import-id (str (random-uuid))
                 aes-key (when graph-e2ee?
@@ -408,6 +417,7 @@
                                  :rows-db nil
                                  :rows-imported? false
                                  :rows-path nil
+                                 :rows-pool nil
                                  :repo repo
                                  :total-datoms total-datoms})
           {:import-id import-id})
@@ -437,61 +447,102 @@
               _ (when (:rows-imported? state)
                   (<replay-imported-rows! state))
               result (complete-datoms-import! repo graph-id remote-tx)
-              _ (reset! *import-state nil)]
+              _ (clear-import-state! import-id)]
         result)
       (p/catch (fn [error]
                  (when-not (= :db-sync/stale-import (:type (ex-data error)))
                    (clear-import-state! import-id))
                  (throw error)))))
 
+(defn- set-graph-sync-metadata!
+  [conn graph-id graph-e2ee?]
+  (assert (uuid? graph-id))
+  (ldb/transact! conn [(ldb/kv :logseq.kv/graph-uuid graph-id)
+                       (ldb/kv :logseq.kv/graph-remote? true)
+                       (ldb/kv :logseq.kv/graph-rtc-e2ee? (true? graph-e2ee?))]
+    {:persist-op? false}))
+
 (defn download-graph-by-id!
   [repo graph-id graph-e2ee?]
   (let [base (sync-auth/http-base-url @worker-state/*db-sync-config)]
     (if (and (seq repo) (seq graph-id) (seq base))
-      (p/let [log-f (fn [payload]
-                      (rtc-log-and-state/rtc-log :rtc.log/download payload))
-              _ (log-f {:sub-type :download-progress
-                        :graph-uuid graph-id
-                        :message "Preparing graph snapshot download"})
-              pull-resp (fetch-json (str base "/sync/" graph-id "/pull")
-                                    {:method "GET"}
-                                    :sync/pull)
-              remote-tx (:t pull-resp)
-              _ (when-not (integer? remote-tx)
-                  (throw (ex-info "non-integer remote-tx when downloading graph"
+      (let [stage* (atom :init)
+            import-id* (atom nil)]
+        (-> (p/let [log-f (fn [payload]
+                            (rtc-log-and-state/rtc-log :rtc.log/download payload))
+                    _ (log-f {:sub-type :download-progress
+                              :graph-uuid graph-id
+                              :message "Preparing graph snapshot download"})
+                    _ (reset! stage* :fetch-pull)
+                    pull-resp (fetch-json (str base "/sync/" graph-id "/pull")
+                                          {:method "GET"}
+                                          :sync/pull)
+                    remote-tx (:t pull-resp)
+                    _ (when-not (integer? remote-tx)
+                        (throw (ex-info "non-integer remote-tx when downloading graph"
+                                        {:repo repo
+                                         :remote-tx remote-tx})))
+                    _ (reset! stage* :fetch-snapshot-download)
+                    snapshot-resp (fetch-json (str base "/sync/" graph-id "/snapshot/download")
+                                              {:method "GET"}
+                                              :sync/snapshot-download)
+                    _ (reset! stage* :fetch-snapshot-stream)
+                    resp (js/fetch (:url snapshot-resp)
+                                   (clj->js (with-auth-headers {:method "GET"})))
+                    _ (log-f {:sub-type :download-progress
+                              :graph-uuid graph-id
+                              :message "Start downloading graph snapshot"})]
+              (when-not (.-ok resp)
+                (throw (ex-info "snapshot download failed"
+                                {:repo repo
+                                 :status (.-status resp)})))
+              (let [ensure-import! (fn []
+                                     (if-let [import-id @import-id*]
+                                       (p/resolved import-id)
+                                       (p/let [_ (reset! stage* :prepare-import)
+                                               {:keys [import-id]} (prepare-import! repo true graph-id graph-e2ee?)]
+                                         (reset! import-id* import-id)
+                                         import-id)))]
+                (p/let [_ (do
+                            (reset! stage* :stream-snapshot)
+                            (<stream-snapshot-row-batches!
+                             resp
+                             25000
+                             (fn [rows]
+                               (p/let [import-id (ensure-import!)]
+                                 (import-rows-chunk! rows graph-id import-id)))))
+                        _ (log-f {:sub-type :download-completed
+                                  :graph-uuid graph-id
+                                  :message "Graph snapshot downloaded"})
+                        _ (when-let [import-id @import-id*]
+                            (reset! stage* :finalize-import)
+                            (finalize-import! repo graph-id remote-tx import-id))]
+                  (when-let [conn (worker-state/get-datascript-conn repo)]
+                    (set-graph-sync-metadata! conn (uuid graph-id) graph-e2ee?))
+                  {:repo repo
+                   :graph-id graph-id
+                   :remote-tx remote-tx
+                   :graph-e2ee? graph-e2ee?})))
+            (p/catch (fn [error]
+                       (when-let [import-id @import-id*]
+                         (clear-import-state! import-id))
+                       (log/error :db-sync/download-graph-by-id-failed
                                   {:repo repo
-                                   :remote-tx remote-tx})))
-              snapshot-resp (fetch-json (str base "/sync/" graph-id "/snapshot/download")
-                                        {:method "GET"}
-                                        :sync/snapshot-download)
-              resp (js/fetch (:url snapshot-resp)
-                             (clj->js (with-auth-headers {:method "GET"})))
-              _ (log-f {:sub-type :download-progress
-                        :graph-uuid graph-id
-                        :message "Start downloading graph snapshot"})]
-        (when-not (.-ok resp)
-          (throw (ex-info "snapshot download failed"
-                          {:repo repo
-                           :status (.-status resp)})))
-        (let [import-id* (atom nil)
-              ensure-import! (fn []
-                               (if-let [import-id @import-id*]
-                                 (p/resolved import-id)
-                                 (p/let [{:keys [import-id]} (prepare-import! repo true graph-id graph-e2ee?)]
-                                   (reset! import-id* import-id)
-                                   import-id)))]
-          (p/let [_ (<stream-snapshot-row-batches!
-                     resp
-                     25000
-                     (fn [rows]
-                       (p/let [import-id (ensure-import!)]
-                         (import-rows-chunk! rows graph-id import-id))))
-                  _ (log-f {:sub-type :download-completed
-                            :graph-uuid graph-id
-                            :message "Graph snapshot downloaded"})
-                  _ (when-let [import-id @import-id*]
-                      (finalize-import! repo graph-id remote-tx import-id))]
-            true)))
+                                   :graph-id graph-id
+                                   :graph-e2ee? graph-e2ee?
+                                   :stage @stage*
+                                   :error error
+                                   :error-stack (when (instance? js/Error error)
+                                                  (.-stack error))})
+                       (throw (ex-info "db-sync download failed"
+                                      {:repo repo
+                                       :graph-id graph-id
+                                       :graph-e2ee? graph-e2ee?
+                                       :stage @stage*
+                                       :error-message (or (ex-message error)
+                                                           (when (instance? js/Error error)
+                                                             (.-message error)))}
+                                       error))))))
       (p/rejected (ex-info "db-sync missing graph download info"
                            {:repo repo
                             :graph-id graph-id
diff --git a/src/main/frontend/worker/sync/handle_message.cljs b/src/main/frontend/worker/sync/handle_message.cljs
index 5ef16b4d15..c83e8bd9e7 100644
--- a/src/main/frontend/worker/sync/handle_message.cljs
+++ b/src/main/frontend/worker/sync/handle_message.cljs
@@ -10,6 +10,7 @@
             [frontend.worker.sync.log-and-state :as sync-log-state]
             [frontend.worker.sync.presence :as sync-presence]
             [frontend.worker.sync.transport :as sync-transport]
+            [frontend.worker.sync.util :as sync-util]
             [lambdaisland.glogi :as log]
             [logseq.db-sync.checksum :as sync-checksum]
             [promesa.core :as p]
@@ -259,6 +260,7 @@
   (let [current-local-tx (client-op/get-local-tx repo)
         next-local-tx (max current-local-tx remote-tx)]
     (client-op/update-local-tx repo next-local-tx)
+    (sync-util/clear-last-sync-error! client)
     (broadcast-rtc-state! client)
     (sync-apply/mark-pending-txs-false! repo @(:inflight client))
     (reset! (:inflight client) [])
@@ -267,20 +269,25 @@
 
 (defn- update-latest-remote-state!
   [repo message]
-  (let [remote-tx (:t message)
+  (let [message-type (:type message)
+        remote-tx (:t message)
         remote-checksum (:checksum message)
         has-checksum? (contains? message :checksum)
         latest-remote-tx (get @sync-apply/*repo->latest-remote-tx repo)
+        authoritative? (contains? #{"hello" "changed"} message-type)
         stale-remote-tx? (and (number? remote-tx)
                               (number? latest-remote-tx)
-                              (< remote-tx latest-remote-tx))]
+                              (< remote-tx latest-remote-tx)
+                              (not authoritative?))]
     (when (number? remote-tx)
-      (swap! sync-apply/*repo->latest-remote-tx
-             update repo
-             (fn [prev]
-               (if (number? prev)
-                 (max prev remote-tx)
-                 remote-tx))))
+      (if authoritative?
+        (swap! sync-apply/*repo->latest-remote-tx assoc repo remote-tx)
+        (swap! sync-apply/*repo->latest-remote-tx
+               update repo
+               (fn [prev]
+                 (if (number? prev)
+                   (max prev remote-tx)
+                   remote-tx)))))
     (when (and has-checksum? (not stale-remote-tx?))
       (swap! sync-apply/*repo->latest-remote-checksum assoc repo remote-checksum))
     {:stale-remote-tx? stale-remote-tx?
@@ -334,26 +341,31 @@
                                 :tx-data (parse-transit (:tx data) {:repo repo :type "pull/ok"})})
                              txs)]
         (when (seq remote-txs)
-          (p/let [graph-e2ee? (sync-crypt/graph-e2ee? repo)
-                  aes-key (sync-crypt/<ensure-graph-aes-key repo (:graph-id client))
-                  _ (when (and graph-e2ee? (nil? aes-key))
-                      (fail-fast :db-sync/missing-field {:repo repo :field :aes-key}))
-                  remote-txs* (if aes-key
-                                (p/all (mapv (fn [{:keys [t tx-data]}]
-                                               (p/let [tx-data* (sync-crypt/<decrypt-tx-data aes-key tx-data)]
-                                                 {:t t
-                                                  :tx-data tx-data*}))
-                                             remote-txs))
-                                (p/resolved remote-txs))]
-            (try
-              (sync-apply/apply-remote-txs! repo client remote-txs*)
-              (catch :default e
-                (log/error ::apply-remote-tx e)
-                (throw e)))
-            (client-op/update-local-tx repo remote-tx)
-            (broadcast-rtc-state! client)
-            (verify-sync-checksum! repo client remote-tx remote-tx remote-checksum {:type "pull/ok"})
-            (sync-apply/enqueue-flush-pending! repo client)))))))
+          (->
+           (p/let [graph-e2ee? (sync-crypt/graph-e2ee? repo)
+                   aes-key (sync-crypt/<ensure-graph-aes-key repo (:graph-id client))
+                   _ (when (and graph-e2ee? (nil? aes-key))
+                       (fail-fast :db-sync/missing-field {:repo repo :field :aes-key}))
+                   remote-txs* (if aes-key
+                                 (p/all (mapv (fn [{:keys [t tx-data]}]
+                                                (p/let [tx-data* (sync-crypt/<decrypt-tx-data aes-key tx-data)]
+                                                  {:t t
+                                                   :tx-data tx-data*}))
+                                              remote-txs))
+                                 (p/resolved remote-txs))]
+             (try
+               (sync-apply/apply-remote-txs! repo client remote-txs*)
+               (catch :default e
+                 (log/error ::apply-remote-tx e)
+                 (throw e)))
+             (client-op/update-local-tx repo remote-tx)
+             (broadcast-rtc-state! client)
+             (verify-sync-checksum! repo client remote-tx remote-tx remote-checksum {:type "pull/ok"})
+             (sync-apply/enqueue-flush-pending! repo client))
+           (p/then (fn [_]
+                     (sync-util/clear-last-sync-error! client)))
+           (p/catch (fn [error]
+                      (sync-util/set-last-sync-error! client error)))))))))
 
 (defn- handle-changed!
   [repo client local-tx remote-tx]
diff --git a/src/main/frontend/worker/sync/large_title.cljs b/src/main/frontend/worker/sync/large_title.cljs
index a50b6120b3..2e4802c867 100644
--- a/src/main/frontend/worker/sync/large_title.cljs
+++ b/src/main/frontend/worker/sync/large_title.cljs
@@ -2,7 +2,8 @@
   "Large title offload and rehydration helpers for db sync."
   (:require [datascript.core :as d]
             [logseq.db :as ldb]
-            [promesa.core :as p]))
+            [promesa.core :as p]
+            [frontend.worker.sync.util :refer [get-graph-id]]))
 
 (def large-title-byte-limit 4096)
 (def large-title-asset-type "txt")
@@ -36,12 +37,6 @@
        (string? (:asset-uuid value))
        (string? (:asset-type value))))
 
-(defn get-graph-id
-  [get-datascript-conn repo]
-  (when-let [conn (get-datascript-conn repo)]
-    (when-let [graph-uuid (ldb/get-graph-rtc-uuid @conn)]
-      (str graph-uuid))))
-
 (defn asset-url
   [base graph-id asset-uuid asset-type]
   (str base "/assets/" graph-id "/" asset-uuid "." asset-type))
@@ -134,12 +129,11 @@
                 tx-data
                 conn
                 get-conn-f
-                get-graph-id-f
                 graph-e2ee?-f
                 ensure-graph-aes-key-f
                 fail-fast-f]}]
   (when-let [conn* (or conn (get-conn-f repo))]
-    (let [graph-id* (or graph-id (get-graph-id-f repo))
+    (let [graph-id* (or graph-id (get-graph-id repo))
           items (if (seq tx-data)
                   (->> tx-data
                        (keep (fn [item]
diff --git a/src/main/frontend/worker/sync/presence.cljs b/src/main/frontend/worker/sync/presence.cljs
index de2ab4e5ff..e82bd209e7 100644
--- a/src/main/frontend/worker/sync/presence.cljs
+++ b/src/main/frontend/worker/sync/presence.cljs
@@ -1,6 +1,7 @@
 (ns frontend.worker.sync.presence
   "Presence and rtc state helpers for db sync."
-  (:require [logseq.common.util :as common-util]))
+  (:require [logseq.common.util :as common-util]
+            [frontend.worker.state :as worker-state]))
 
 (defn current-client
   [db-sync-client repo]
@@ -34,15 +35,23 @@
           remote-checksum (get latest-remote-checksum repo)
           pending-server (when (and (number? local-tx) (number? remote-tx))
                            (max 0 (- remote-tx local-tx)))
-          graph-uuid (get-graph-uuid repo)]
-      {:pending-local pending-local
+          graph-uuid (get-graph-uuid repo)
+          client (current-client worker-state/*db-sync-client repo)
+          ws-url (:ws-url @worker-state/*db-sync-config)
+          ws-state (or (some-> client :ws-state deref)
+                       (if (seq ws-url) :stopped :inactive))
+          last-error (some-> client :last-sync-error deref)]
+      {:repo repo
+       :graph-id graph-uuid
+       :pending-local pending-local
        :pending-asset pending-asset
        :pending-server pending-server
        :local-tx local-tx
        :remote-tx remote-tx
        :local-checksum local-checksum
        :remote-checksum remote-checksum
-       :graph-uuid graph-uuid})))
+       :ws-state ws-state
+       :last-error last-error})))
 
 (defn normalize-online-users
   [users]
diff --git a/src/main/frontend/worker/sync/temp_sqlite.cljs b/src/main/frontend/worker/sync/temp_sqlite.cljs
index 835ec2dd35..684cec2b65 100644
--- a/src/main/frontend/worker/sync/temp_sqlite.cljs
+++ b/src/main/frontend/worker/sync/temp_sqlite.cljs
@@ -5,7 +5,13 @@
             [datascript.storage :refer [IStorage]]
             [logseq.db.common.sqlite :as common-sqlite]
             [logseq.db.sqlite.util :as sqlite-util]
-            [promesa.core :as p]))
+            [promesa.core :as p]
+            [frontend.worker-common.util :as worker-util]
+            [frontend.worker.platform :as platform]
+            [frontend.worker.state :as worker-state]
+            [frontend.worker.sync.util :refer [fail-fast]]))
+
+(def upload-temp-pool-name (worker-util/get-pool-name "upload-temp"))
 
 (defn- upsert-addr-content!
   [^js db data]
@@ -49,60 +55,38 @@
     (-restore [_ addr]
       (restore-data-from-addr db addr))))
 
-(defn <get-upload-temp-sqlite-pool
-  [{:keys [*pool sqlite pool-name fail-fast-f]}]
-  (if-let [pool @*pool]
-    (p/resolved pool)
-    (if-let [sqlite* sqlite]
-      (p/let [^js pool (.installOpfsSAHPoolVfs ^js sqlite* #js {:name pool-name
-                                                                :initialCapacity 20})]
-        (reset! *pool pool)
-        pool)
-      (fail-fast-f :db-sync/missing-field {:field :sqlite}))))
-
-(defn upload-temp-sqlite-path
-  []
-  (str "/upload-" (random-uuid) ".sqlite"))
-
 (defn <create-temp-sqlite-db!
-  [{:keys [get-pool-f upload-path-f]}]
-  (p/let [^js pool (get-pool-f)
-          capacity (.getCapacity pool)
-          _ (when (zero? capacity)
-              (.unpauseVfs pool))
-          path (upload-path-f)
-          ^js db (new (.-OpfsSAHPoolDb pool) path)]
-    (common-sqlite/create-kvs-table! db)
-    {:db db
-     :path path
-     :pool pool}))
+  []
+  (if-let [sqlite @worker-state/*sqlite]
+    (let [current-platform (platform/current)]
+      (p/let [pool (platform/install-storage-pool current-platform sqlite upload-temp-pool-name)
+              path (platform/resolve-db-path current-platform upload-temp-pool-name pool "/upload.sqlite")
+              db (platform/sqlite-open current-platform
+                                       {:sqlite sqlite
+                                        :pool pool
+                                        :path path
+                                        :mode "c"})]
+        (common-sqlite/create-kvs-table! db)
+        {:db db
+         :pool pool
+         :path path}))
+    (fail-fast :db-sync/missing-field {:field :sqlite})))
 
 (defn <create-temp-sqlite-conn
-  [schema datoms create-db-f]
-  (p/let [{:keys [db path pool]} (create-db-f)
+  [schema datoms]
+  (p/let [{:keys [db path pool]} (<create-temp-sqlite-db!)
           storage (new-temp-sqlite-storage db)
           conn (d/conn-from-datoms datoms schema {:storage storage})]
     {:db db
      :conn conn
-     :path path
-     :pool pool}))
-
-(defn <remove-upload-temp-sqlite-db-file!
-  [pool-name path]
-  (-> (p/let [^js root (.getDirectory js/navigator.storage)
-              ^js dir (.getDirectoryHandle root (str "." pool-name))]
-        (.removeEntry dir (subs path 1)))
-      (p/catch
-       (fn [error]
-         (if (= "NotFoundError" (.-name error))
-           nil
-           (p/rejected error))))))
+     :pool pool
+     :path path}))
 
 (defn cleanup-temp-sqlite!
-  [{:keys [db conn path]} remove-file-f]
+  [{:keys [db conn pool]}]
   (when conn
     (reset! conn nil))
   (when db
     (.close db))
-  (when path
-    (remove-file-f path)))
+  (when pool
+    (platform/remove-storage-pool! (platform/current) pool)))
diff --git a/src/main/frontend/worker/sync/transport.cljs b/src/main/frontend/worker/sync/transport.cljs
index 87158d7451..ca798ae27e 100644
--- a/src/main/frontend/worker/sync/transport.cljs
+++ b/src/main/frontend/worker/sync/transport.cljs
@@ -1,10 +1,10 @@
 (ns frontend.worker.sync.transport
   "Transport and message-shaping helpers for db sync."
-  (:require [clojure.string :as string]
-            [lambdaisland.glogi :as log]
-            [logseq.db-sync.malli-schema :as db-sync-schema]
-            [logseq.db.sqlite.util :as sqlite-util]
-            [promesa.core :as p]))
+  (:require
+   [clojure.string :as string]
+   [lambdaisland.glogi :as log]
+   [logseq.db-sync.malli-schema :as db-sync-schema]
+   [logseq.db.sqlite.util :as sqlite-util]))
 
 (def invalid-coerce ::invalid-coerce)
 
@@ -78,14 +78,6 @@
     (catch :default e
       (fail-fast-f :db-sync/response-parse-failed (assoc context :error e)))))
 
-(defn coerce-http-response
-  [schema-key body]
-  (if-let [coercer (get db-sync-schema/http-response-coercers schema-key)]
-    (let [coerced (coerce coercer body {:schema schema-key :dir :response})]
-      (when-not (= coerced invalid-coerce)
-        coerced))
-    body))
-
 (defn reconnect-delay-ms
   [attempt {:keys [base-delay-ms max-delay-ms jitter-ms]}]
   (let [exp (js/Math.pow 2 attempt)
@@ -100,31 +92,6 @@
     (catch :default _
       nil)))
 
-(defn fetch-json
-  [with-auth-headers-f url opts {:keys [response-schema error-schema] :or {error-schema :error}}]
-  (p/let [resp (js/fetch url (clj->js (with-auth-headers-f opts)))
-          text (.text resp)
-          data (when (seq text) (js/JSON.parse text))]
-    (if (.-ok resp)
-      (let [body (js->clj data :keywordize-keys true)
-            body (if response-schema
-                   (coerce-http-response response-schema body)
-                   body)]
-        (if (or (nil? response-schema) body)
-          body
-          (throw (ex-info "db-sync invalid response"
-                          {:status (.-status resp)
-                           :url url
-                           :body body}))))
-      (let [body (when data (js->clj data :keywordize-keys true))
-            body (if error-schema
-                   (coerce-http-response error-schema body)
-                   body)]
-        (throw (ex-info "db-sync request failed"
-                        {:status (.-status resp)
-                         :url url
-                         :body body}))))))
-
 (defn send!
   [coerce-ws-client-message-f ws message]
   (when (ws-open? ws)
diff --git a/src/main/frontend/worker/sync/upload.cljs b/src/main/frontend/worker/sync/upload.cljs
index 56edf449ff..b682f8a67f 100644
--- a/src/main/frontend/worker/sync/upload.cljs
+++ b/src/main/frontend/worker/sync/upload.cljs
@@ -1,21 +1,22 @@
 (ns frontend.worker.sync.upload
   "Snapshot upload helpers for db sync."
-  (:require [cljs-bean.core :as bean]
-            [datascript.core :as d]
-            [frontend.worker-common.util :as worker-util]
-            [frontend.worker.state :as worker-state]
-            [frontend.worker.sync.apply-txs :as sync-apply]
-            [frontend.worker.sync.auth :as sync-auth]
-            [frontend.worker.sync.client-op :as client-op]
-            [frontend.worker.sync.crypt :as sync-crypt]
-            [frontend.worker.sync.large-title :as sync-large-title]
-            [frontend.worker.sync.temp-sqlite :as sync-temp-sqlite]
-            [frontend.worker.sync.transport :as sync-transport]
-            [lambdaisland.glogi :as log]
-            [logseq.db :as ldb]
-            [logseq.db-sync.checksum :as sync-checksum]
-            [logseq.db.sqlite.util :as sqlite-util]
-            [promesa.core :as p]))
+  (:require
+   [cljs-bean.core :as bean]
+   [datascript.core :as d]
+   [frontend.worker-common.util :as worker-util]
+   [frontend.worker.state :as worker-state]
+   [frontend.worker.sync.apply-txs :as sync-apply]
+   [frontend.worker.sync.auth :as sync-auth]
+   [frontend.worker.sync.client-op :as client-op]
+   [frontend.worker.sync.crypt :as sync-crypt]
+   [frontend.worker.sync.large-title :as sync-large-title]
+   [frontend.worker.sync.temp-sqlite :as sync-temp-sqlite]
+   [frontend.worker.sync.util :refer [coerce-http-request fail-fast fetch-json] :as sync-util]
+   [logseq.common.config :as common-config]
+   [logseq.db :as ldb]
+   [logseq.db-sync.checksum :as sync-checksum]
+   [logseq.db.sqlite.util :as sqlite-util]
+   [promesa.core :as p]))
 
 (def upload-kvs-batch-size 500)
 (def upload-prepare-datoms-batch-size 100000)
@@ -25,21 +26,11 @@
 (def snapshot-content-type "application/transit+json")
 (def snapshot-content-encoding "gzip")
 (def snapshot-text-encoder (js/TextEncoder.))
-(def upload-temp-pool-name (worker-util/get-pool-name "upload-temp"))
-
-(defn- fail-fast
-  [tag data]
-  (log/error tag data)
-  (throw (ex-info (name tag) data)))
 
 (defn- http-base-url
   []
   (sync-auth/http-base-url @worker-state/*db-sync-config))
 
-(defn- get-graph-id
-  [repo]
-  (sync-large-title/get-graph-id worker-state/get-datascript-conn repo))
-
 (defn- ensure-client-graph-uuid!
   [repo graph-id]
   (when (seq graph-id)
@@ -184,27 +175,9 @@
                 _ (auth-fetch-f upload-url headers body)]
           (p/recur (next remaining) false)))
       nil)))
-
-(defn set-graph-sync-metadata!
-  [repo graph-e2ee?]
-  (when-let [conn (worker-state/get-datascript-conn repo)]
-    (ldb/transact! conn [(ldb/kv :logseq.kv/graph-remote? true)
-                         (ldb/kv :logseq.kv/graph-rtc-e2ee? (true? graph-e2ee?))]
-                   {:persist-op? false})))
-
 (defn <prepare-upload-temp-sqlite!
   [repo graph-id source-conn aes-key update-progress]
-  (p/let [temp (sync-temp-sqlite/<create-temp-sqlite-conn
-                (d/schema @source-conn)
-                []
-                #(sync-temp-sqlite/<create-temp-sqlite-db!
-                  {:get-pool-f (fn []
-                                 (sync-temp-sqlite/<get-upload-temp-sqlite-pool
-                                  {:*pool sync-apply/*upload-temp-opfs-pool
-                                   :sqlite @worker-state/*sqlite
-                                   :pool-name upload-temp-pool-name
-                                   :fail-fast-f fail-fast}))
-                   :upload-path-f sync-temp-sqlite/upload-temp-sqlite-path}))
+  (p/let [temp (sync-temp-sqlite/<create-temp-sqlite-conn (d/schema @source-conn) [])
           datoms (d/datoms @source-conn :eavt)
           _ (sync-large-title/process-upload-datoms-in-batches!
              datoms
@@ -234,29 +207,157 @@
                                              (str "Preparing " processed "/" total))}))})]
     temp))
 
+(defn- normalize-graph-e2ee?
+  [graph-e2ee?]
+  (if (nil? graph-e2ee?)
+    true
+    (true? graph-e2ee?)))
+
+(defn- graph-id->uuid
+  [repo graph-id]
+  (when-not (seq graph-id)
+    (fail-fast :db-sync/missing-field {:repo repo :field :graph-id}))
+  (try
+    (uuid graph-id)
+    (catch :default e
+      (fail-fast :db-sync/invalid-field {:repo repo
+                                         :field :graph-id
+                                         :value graph-id
+                                         :error e}))))
+
+(defn- set-graph-sync-metadata!
+  [repo graph-id graph-e2ee?]
+  (when-let [conn (worker-state/get-datascript-conn repo)]
+    (ldb/transact! conn [(ldb/kv :logseq.kv/graph-uuid (graph-id->uuid repo graph-id))
+                         (ldb/kv :logseq.kv/graph-remote? true)
+                         (ldb/kv :logseq.kv/graph-rtc-e2ee? (true? graph-e2ee?))]
+      {:outliner-op :set-kvs})))
+
+(defn- persist-upload-graph-identity!
+  [repo graph-id graph-e2ee?]
+  (let [graph-id (some-> graph-id str)
+        graph-e2ee? (normalize-graph-e2ee? graph-e2ee?)]
+    (when-not (seq graph-id)
+      (fail-fast :db-sync/missing-field {:repo repo :field :graph-id}))
+    (set-graph-sync-metadata! repo graph-id graph-e2ee?)
+    (ensure-client-graph-uuid! repo graph-id)
+    {:graph-id graph-id
+     :graph-e2ee? graph-e2ee?}))
+
+(defn- <create-remote-graph-aux!
+  [repo {:keys [graph-e2ee? graph-ready-for-use?]}]
+  (let [base (http-base-url)
+        graph-name (some-> repo common-config/strip-leading-db-version-prefix)
+        schema-version (some-> (worker-state/get-datascript-conn repo)
+                               deref
+                               ldb/get-graph-schema-version
+                               :major
+                               str)
+        graph-e2ee? (normalize-graph-e2ee? graph-e2ee?)]
+    (cond
+      (not (seq base))
+      (fail-fast :db-sync/missing-field {:repo repo :field :http-base})
+
+      (not (seq graph-name))
+      (fail-fast :db-sync/missing-field {:repo repo :field :graph-name})
+
+      :else
+      (do
+        (sync-util/require-auth-token! {:repo repo :field :auth-token})
+        (p/let [_ (sync-crypt/ensure-user-rsa-keys! {:ensure-server? true})
+                body (coerce-http-request :graphs/create
+                                          {:graph-name graph-name
+                                           :schema-version schema-version
+                                           :graph-e2ee? graph-e2ee?
+                                           :graph-ready-for-use? (not= false graph-ready-for-use?)})
+                _ (when (nil? body)
+                    (fail-fast :db-sync/invalid-field {:repo repo
+                                                       :field :create-graph-body}))
+                result (fetch-json (str base "/graphs")
+                                   {:method "POST"
+                                    :headers {"content-type" "application/json"}
+                                    :body (js/JSON.stringify (clj->js body))}
+                                   {:response-schema :graphs/create})
+                graph-id (:graph-id result)
+                graph-e2ee? (normalize-graph-e2ee? (if (contains? result :graph-e2ee?)
+                                                     (:graph-e2ee? result)
+                                                     graph-e2ee?))]
+          (when-not (seq graph-id)
+            (fail-fast :db-sync/missing-field {:repo repo
+                                               :field :graph-id
+                                               :op :create-graph}))
+          (persist-upload-graph-identity! repo graph-id graph-e2ee?)
+          {:graph-id graph-id
+           :graph-e2ee? graph-e2ee?})))))
+
+(defn list-remote-graphs!
+  []
+  (let [base (sync-auth/http-base-url @worker-state/*db-sync-config)]
+    (if-not (seq base)
+      (p/resolved [])
+      (do
+        (sync-util/require-auth-token! {:op :list-remote-graphs})
+        (p/let [resp (fetch-json (str base "/graphs")
+                                           {:method "GET"}
+                                           {:response-schema :graphs/list})]
+          (vec (or (:graphs resp) [])))))))
+
+(defn- fail-upload-graph-already-exists!
+  [repo {:keys [graph-id graph-name]}]
+  (throw (ex-info "remote graph already exists; delete it before uploading again"
+                  {:code :db-sync/graph-already-exists
+                   :repo repo
+                   :graph-id graph-id
+                   :graph-name graph-name})))
+
+(defn- remote-graph-matches-upload-target?
+  [target-graph-name {:keys [graph-name]}]
+  (= target-graph-name graph-name))
+
+(defn create-remote-graph!
+  [repo {:keys [graph-e2ee? graph-ready-for-use?]}]
+  (let [target-graph-name (some-> repo common-config/strip-leading-db-version-prefix)]
+    (cond
+      (not (seq target-graph-name))
+      (fail-fast :db-sync/missing-field {:repo repo :field :graph-name})
+
+      :else
+      (p/let [remote-graphs (list-remote-graphs!)
+              matching-graphs (filterv (partial remote-graph-matches-upload-target?
+                                                target-graph-name)
+                                       remote-graphs)]
+        (cond
+          (> (count matching-graphs) 1)
+          (fail-fast :db-sync/ambiguous-graph-match {:repo repo
+                                                     :graph-name target-graph-name
+                                                     :match-count (count matching-graphs)})
+
+          (= 1 (count matching-graphs))
+          (fail-upload-graph-already-exists! repo {:graph-name target-graph-name})
+
+          :else
+          (p/let [_ (sync-crypt/<preflight-upload-e2ee! repo graph-e2ee?)]
+            (<create-remote-graph-aux! repo {:graph-e2ee? graph-e2ee?
+                                             :graph-ready-for-use? graph-ready-for-use?})))))))
+
 (defn upload-graph!
   [repo]
   (let [base (http-base-url)
-        graph-id (get-graph-id repo)
         update-progress (fn [payload]
                           (worker-util/post-message :rtc-log
-                                                    (merge {:type :rtc.log/upload
-                                                            :graph-uuid graph-id}
+                                                    (merge {:type :rtc.log/upload}
                                                            payload)))]
-    (cond
-      (not (and (seq base) (seq graph-id)))
-      (p/rejected (ex-info "db-sync missing upload info"
-                           {:repo repo :base base :graph-id graph-id}))
-
-      :else
+    (if-not (seq base)
+      (p/rejected (ex-info "db-sync missing base"
+                           {:repo repo :base base}))
       (if-let [source-conn (worker-state/get-datascript-conn repo)]
-        (let [graph-e2ee? (true? (sync-crypt/graph-e2ee? repo))]
+        (p/let [graph-e2ee? (normalize-graph-e2ee? (sync-crypt/graph-e2ee? repo))
+                {:keys [graph-id]} (create-remote-graph! repo {:graph-e2ee? graph-e2ee?
+                                                               :graph-ready-for-use? false})]
           (p/let [aes-key (when graph-e2ee?
                             (sync-crypt/<ensure-graph-aes-key repo graph-id))
                   _ (when (and graph-e2ee? (nil? aes-key))
                       (fail-fast :db-sync/missing-field {:repo repo :field :aes-key}))]
-            (set-graph-sync-metadata! repo graph-e2ee?)
-            (ensure-client-graph-uuid! repo graph-id)
             (let [snapshot-checksum (sync-checksum/recompute-checksum @source-conn)]
               (client-op/update-local-checksum repo snapshot-checksum)
               (p/let [_ (update-progress {:sub-type :upload-progress
@@ -302,11 +403,7 @@
                                         :checksum snapshot-checksum
                                         :auth-fetch-f
                                         (fn [upload-url headers body]
-                                          (sync-transport/fetch-json
-                                           (fn [opts]
-                                             (sync-auth/with-auth-headers
-                                               #(sync-auth/auth-headers (worker-state/get-id-token))
-                                               opts))
+                                          (fetch-json
                                            upload-url
                                            {:method "POST"
                                             :headers headers
@@ -317,9 +414,6 @@
                               (p/recur max-addr false loaded'))))))
                     (p/finally
                       (fn []
-                        (sync-temp-sqlite/cleanup-temp-sqlite!
-                         temp
-                         (partial sync-temp-sqlite/<remove-upload-temp-sqlite-db-file!
-                                  upload-temp-pool-name)))))))))
+                        (sync-temp-sqlite/cleanup-temp-sqlite! temp))))))))
         (p/rejected (ex-info "db-sync missing datascript conn"
-                             {:repo repo :graph-id graph-id}))))))
+                             {:repo repo}))))))
diff --git a/src/main/frontend/worker/sync/util.cljs b/src/main/frontend/worker/sync/util.cljs
new file mode 100644
index 0000000000..fb1b62a254
--- /dev/null
+++ b/src/main/frontend/worker/sync/util.cljs
@@ -0,0 +1,129 @@
+(ns frontend.worker.sync.util
+  "Helpers for sync"
+  (:require [lambdaisland.glogi :as log]
+            [frontend.worker.platform :as platform]
+            [frontend.worker.state :as worker-state]
+            [logseq.db :as ldb]
+            [frontend.worker.sync.client-op :as client-op]
+            [logseq.common.util :as common-util]
+            [logseq.db-sync.malli-schema :as db-sync-schema]
+            [promesa.core :as p]))
+
+(defn fail-fast [tag data]
+  (log/error tag data)
+  (throw (ex-info (name tag) data)))
+
+(defn cli-node-owner?
+  []
+  (try
+    (let [env (:env (platform/current))]
+      (and (= :node (:runtime env))
+           (= :cli (:owner-source env))))
+    (catch :default _ false)))
+
+(defn auth-token
+  []
+  (let [state @worker-state/*state]
+    (or (:auth/id-token state)
+        (:auth/access-token state))))
+
+(defn get-graph-id
+  [repo]
+  (or (when-let [conn (worker-state/get-datascript-conn repo)]
+        (let [db @conn
+              graph-uuid (ldb/get-graph-rtc-uuid db)]
+          (when graph-uuid
+            (str graph-uuid))))
+      (some-> (client-op/get-graph-uuid repo) str)))
+
+(defn require-auth-token!
+  [context]
+  (when-not (seq (auth-token))
+    (fail-fast :db-sync/missing-field (assoc context :field :auth-token))))
+
+(defn- ex-message->code
+  [message]
+  (when (and (string? message)
+             (re-matches #"[a-zA-Z0-9._/\-]+" message))
+    (keyword message)))
+
+(defn- error->diagnostic
+  [error]
+  (let [data (or (ex-data error) {})
+        code (or (:code data)
+                 (ex-message->code (ex-message error))
+                 :exception)]
+    {:code code
+     :message (or (ex-message error) (str error))
+     :at (common-util/time-ms)
+     :data (when (seq data) data)}))
+
+(defn set-last-sync-error!
+  [client error]
+  (when-let [*last-error (:last-sync-error client)]
+    (reset! *last-error (error->diagnostic error))))
+
+(defn clear-last-sync-error!
+  [client]
+  (when-let [*last-error (:last-sync-error client)]
+    (reset! *last-error nil)))
+
+(def ^:private invalid-coerce ::invalid-coerce)
+
+(defn coerce
+  [coercer value context]
+  (try
+    (coercer value)
+    (catch :default e
+      (log/error :db-sync/malli-coerce-failed (merge context {:error e :value value}))
+      invalid-coerce)))
+
+(defn coerce-http-request [schema-key body]
+  (if-let [coercer (get db-sync-schema/http-request-coercers schema-key)]
+    (let [coerced (coerce coercer body {:schema schema-key :dir :request})]
+      (when-not (= coerced invalid-coerce)
+        coerced))
+    body))
+
+(defn coerce-http-response [schema-key body]
+  (if-let [coercer (get db-sync-schema/http-response-coercers schema-key)]
+    (let [coerced (coerce coercer body {:schema schema-key :dir :response})]
+      (when-not (= coerced invalid-coerce)
+        coerced))
+    body))
+
+(defn- auth-headers []
+  (let [token (auth-token)]
+    (when (nil? token)
+      (throw (ex-info "Empty token" {})))
+    {"authorization" (str "Bearer " token)}))
+
+(defn- with-auth-headers [opts]
+  (if-let [auth (auth-headers)]
+    (assoc opts :headers (merge (or (:headers opts) {}) auth))
+    opts))
+
+(defn fetch-json
+  [url opts {:keys [response-schema error-schema] :or {error-schema :error}}]
+  (p/let [resp (js/fetch url (clj->js (with-auth-headers opts)))
+          text (.text resp)
+          data (when (seq text) (js/JSON.parse text))]
+    (if (.-ok resp)
+      (let [body (js->clj data :keywordize-keys true)
+            body (if response-schema
+                   (coerce-http-response response-schema body)
+                   body)]
+        (if (or (nil? response-schema) body)
+          body
+          (throw (ex-info "db-sync invalid response"
+                          {:status (.-status resp)
+                           :url url
+                           :body body}))))
+      (let [body (when data (js->clj data :keywordize-keys true))
+            body (if error-schema
+                   (coerce-http-response error-schema body)
+                   body)]
+        (throw (ex-info "db-sync request failed"
+                        {:status (.-status resp)
+                         :url url
+                         :body body}))))))
diff --git a/src/main/frontend/worker/ui_request.cljs b/src/main/frontend/worker/ui_request.cljs
new file mode 100644
index 0000000000..70c9858f8c
--- /dev/null
+++ b/src/main/frontend/worker/ui_request.cljs
@@ -0,0 +1,175 @@
+(ns frontend.worker.ui-request
+  "UI request/response manager for worker-side interactive flows."
+  (:require [frontend.common.thread-api :refer [def-thread-api]]
+            [frontend.worker.platform :as platform]
+            [lambdaisland.glogi :as log]
+            [promesa.core :as p]))
+
+(defonce ^:private *ui-requests-in-flight (atom {}))
+
+(def ^:private default-timeout-ms 60000)
+
+(defn- interactive-runtime?
+  []
+  (let [env (:env (platform/current))
+        runtime (:runtime env)
+        owner-source (:owner-source env)]
+    (or (= :browser runtime)
+        (and (= :node runtime)
+             (= :electron owner-source)))))
+
+(defn- ui-interaction-required-error
+  [action hint]
+  (ex-info "ui-interaction-required"
+           (cond-> {:code :ui-interaction-required
+                    :action action}
+             (seq hint) (assoc :hint hint))))
+
+(defn- normalize-timeout-ms
+  [timeout-ms]
+  (if (and (number? timeout-ms) (pos? timeout-ms))
+    timeout-ms
+    default-timeout-ms))
+
+(defn- take-request!
+  [request-id]
+  (let [request (get @*ui-requests-in-flight request-id)]
+    (when request
+      (swap! *ui-requests-in-flight dissoc request-id)
+      request)))
+
+(defn- timeout-error
+  [request-id action timeout-ms]
+  (ex-info "ui-request-timeout"
+           {:code :ui-request-timeout
+            :request-id request-id
+            :action action
+            :timeout-ms timeout-ms}))
+
+(defn- cancel-error
+  [request-id action context]
+  (ex-info "ui-request-cancelled"
+           {:code :ui-request-cancelled
+            :request-id request-id
+            :action action
+            :context context}))
+
+(defn- reject-error
+  [request-id action error]
+  (let [data (ex-data error)
+        message (or (ex-message error) "ui-request-rejected")]
+    (ex-info message
+             (merge {:code :ui-request-rejected
+                     :request-id request-id
+                     :action action}
+                    (when (seq data)
+                      {:data data})))))
+
+(defn- ->rejectable-error
+  [request-id action error]
+  (cond
+    (instance? cljs.core.ExceptionInfo error)
+    (reject-error request-id action error)
+
+    (instance? js/Error error)
+    (reject-error request-id action error)
+
+    (map? error)
+    (let [message (or (:message error) "ui-request-rejected")
+          data (dissoc error :message)]
+      (ex-info message
+               (merge {:code :ui-request-rejected
+                       :request-id request-id
+                       :action action}
+                      (when (seq data)
+                        {:data data}))))
+
+    (string? error)
+    (ex-info error
+             {:code :ui-request-rejected
+              :request-id request-id
+              :action action})
+
+    :else
+    (ex-info "ui-request-rejected"
+             {:code :ui-request-rejected
+              :request-id request-id
+              :action action
+              :error error})))
+
+(defn <request
+  ([action payload]
+   (<request action payload nil))
+  ([action payload {:keys [timeout-ms hint]}]
+   (if-not (interactive-runtime?)
+     (p/rejected (ui-interaction-required-error action hint))
+     (let [request-id (str (random-uuid))
+           timeout-ms (normalize-timeout-ms timeout-ms)
+           deferred (p/deferred)
+           timeout-id (js/setTimeout
+                       (fn []
+                         (when-let [{:keys [deferred action timeout-ms]} (take-request! request-id)]
+                           (p/reject! deferred (timeout-error request-id action timeout-ms))))
+                       timeout-ms)]
+       (swap! *ui-requests-in-flight assoc request-id
+              {:request-id request-id
+               :action action
+               :deferred deferred
+               :timeout-id timeout-id
+               :timeout-ms timeout-ms})
+       (try
+         (platform/post-message! (platform/current)
+                                 :db-worker/ui-request
+                                 {:request-id request-id
+                                  :action action
+                                  :payload payload
+                                  :timeout-ms timeout-ms})
+         (catch :default error
+           (when-let [{:keys [deferred timeout-id action]} (take-request! request-id)]
+             (js/clearTimeout timeout-id)
+             (p/reject! deferred (reject-error request-id action error)))))
+       deferred))))
+
+(defn resolve-request!
+  [request-id result]
+  (if-let [{:keys [deferred timeout-id]} (take-request! request-id)]
+    (do
+      (js/clearTimeout timeout-id)
+      (p/resolve! deferred result)
+      {:ok true})
+    (do
+      (log/warn :db-worker/ui-request-missing-resolve {:request-id request-id})
+      {:ok false :reason :request-not-found :request-id request-id})))
+
+(defn reject-request!
+  [request-id error]
+  (if-let [{:keys [deferred timeout-id action]} (take-request! request-id)]
+    (do
+      (js/clearTimeout timeout-id)
+      (p/reject! deferred (->rejectable-error request-id action error))
+      {:ok true})
+    (do
+      (log/warn :db-worker/ui-request-missing-reject {:request-id request-id
+                                                      :error error})
+      {:ok false :reason :request-not-found :request-id request-id})))
+
+(defn cancel-all!
+  [context]
+  (let [requests (vals @*ui-requests-in-flight)]
+    (reset! *ui-requests-in-flight {})
+    (doseq [{:keys [request-id deferred timeout-id action]} requests]
+      (js/clearTimeout timeout-id)
+      (p/reject! deferred (cancel-error request-id action context)))
+    {:ok true :cancelled (count requests)}))
+
+(def-thread-api :thread-api/resolve-ui-request
+  [request-id result]
+  (resolve-request! request-id result))
+
+(def-thread-api :thread-api/reject-ui-request
+  [request-id error]
+  (reject-request! request-id error))
+
+(def-thread-api :thread-api/cancel-ui-requests
+  [context]
+  (cancel-all! context))
diff --git a/src/main/frontend/worker/version.cljs b/src/main/frontend/worker/version.cljs
new file mode 100644
index 0000000000..cd259a9a5e
--- /dev/null
+++ b/src/main/frontend/worker/version.cljs
@@ -0,0 +1,18 @@
+(ns frontend.worker.version
+  "Build metadata for db-worker-node.")
+
+(goog-define BUILD_TIME "unknown")
+(goog-define REVISION "dev")
+
+(defn build-time
+  []
+  BUILD_TIME)
+
+(defn revision
+  []
+  REVISION)
+
+(defn format-version
+  []
+  (str "Build time: " (build-time) "\n"
+       "Revision: " (revision)))
diff --git a/src/main/frontend/worker_common/util.cljc b/src/main/frontend/worker_common/util.cljc
index 5605cca85a..30edb2d940 100644
--- a/src/main/frontend/worker_common/util.cljc
+++ b/src/main/frontend/worker_common/util.cljc
@@ -6,8 +6,9 @@
                      [goog.crypt.base64 :as base64]
                      [goog.crypt.Hmac]
                      [goog.crypt.Sha256]
+                     [logseq.common.graph-dir :as common-graph-dir]
                      [logseq.db :as ldb]
-                     [logseq.db.common.sqlite :as common-sqlite])))
+                     [logseq.db.sqlite.util :as sqlite-util])))
 
 ;; Copied from https://github.com/tonsky/datascript-todo
 #?(:clj
@@ -32,12 +33,25 @@
    (do
      (defn post-message
        [type data & {:keys [port]}]
-       (when-let [worker (or port js/self)]
+       (when-let [worker (or port (when (exists? js/self) js/self))]
          (.postMessage worker (ldb/write-transit-str [type data]))))
 
+     (defn encode-graph-dir-name
+       [graph-name]
+       (common-graph-dir/encode-graph-dir-name graph-name))
+
+     (defn decode-graph-dir-name
+       [dir-name]
+       (common-graph-dir/decode-graph-dir-name dir-name))
+
      (defn get-pool-name
        [graph-name]
-       (str "logseq-pool-" (common-sqlite/sanitize-db-name graph-name)))
+       (str "logseq-pool-"
+            (-> graph-name
+                (string/replace sqlite-util/db-version-prefix "")
+                (string/replace "/" "_")
+                (string/replace "\\" "_")
+                (string/replace ":" "_"))))
 
      (defn- decode-username
        [username]
diff --git a/src/main/logseq/cli/AGENTS.md b/src/main/logseq/cli/AGENTS.md
new file mode 100644
index 0000000000..6e6dddb7e5
--- /dev/null
+++ b/src/main/logseq/cli/AGENTS.md
@@ -0,0 +1,16 @@
+# logseq CLI
+
+## Dev rules
+- Ensure `--output json`, `--output edn`, and `--output human` produce reasonable, consistent, and user-friendly output.
+- Ensure all command outputs are user/agent-friendly, especially error outputs.
+- Do not implement new `thread-api` in db-worker unless it is absolutely necessary.
+- Use logseq-cli skill; test the changed parts with the new-built logseq-cli & db-worker-node server.
+- Ensure at least all cli-e2e non-sync cases passed.
+
+## Debug tools
+- `--verbose` - debug cli process
+- `--profile` - performance check
+- Logseq-cli skill - explore cli self in agent
+- db-worker-node.log - logs for db-worker-node process
+- logseq-repl skill - Directly validate some db worker node code in the REPL
+
diff --git a/src/main/logseq/cli/auth.cljs b/src/main/logseq/cli/auth.cljs
new file mode 100644
index 0000000000..d9019758d1
--- /dev/null
+++ b/src/main/logseq/cli/auth.cljs
@@ -0,0 +1,492 @@
+(ns logseq.cli.auth
+  "CLI auth helpers for persisted login state."
+  (:require [clojure.string :as string]
+            [logseq.cli.transport :as transport]
+            [logseq.common.cognito-config :as cognito-config]
+            [promesa.core :as p]
+            ["child_process" :as child-process]
+            ["crypto" :as crypto]
+            ["fs" :as fs]
+            ["http" :as http]
+            ["os" :as os]
+            ["path" :as node-path]))
+
+(def ^:private default-login-timeout-ms 300000)
+(def ^:private default-logout-timeout-ms 120000)
+(def ^:private redirect-path "/auth/callback")
+(def ^:private logout-complete-path "/logout-complete")
+(def ^:private callback-host "localhost")
+(def ^:private callback-port 8765)
+(def ^:private auth-provider "cognito")
+(def ^:private default-scope "email openid phone")
+(def ^:private token-endpoint-path "/oauth2/token")
+(def ^:private authorize-endpoint-path "/oauth2/authorize")
+(def ^:private logout-endpoint-path "/logout")
+
+(defn default-auth-path
+  []
+  (node-path/join (.homedir os) "logseq" "auth.json"))
+
+(defn auth-path
+  [{custom-auth-path :auth-path}]
+  (or custom-auth-path (default-auth-path)))
+
+(defn- ensure-auth-dir!
+  [path]
+  (let [dir (node-path/dirname path)]
+    (when (and (seq dir) (not (fs/existsSync dir)))
+      (.mkdirSync fs dir #js {:recursive true}))))
+
+(defn- try-chmod!
+  [path]
+  (try
+    (.chmodSync fs path 384)
+    (catch :default _
+      nil)))
+
+(defn- parse-json
+  [text]
+  (js->clj (js/JSON.parse text) :keywordize-keys true))
+
+(defn- oauth-client-id
+  []
+  cognito-config/CLI-COGNITO-CLIENT-ID)
+
+(defn- oauth-scope
+  []
+  (or cognito-config/OAUTH-SCOPE
+      default-scope))
+
+(defn- oauth-domain
+  []
+  cognito-config/OAUTH-DOMAIN)
+
+(defn- logout-complete-uri
+  []
+  (str "http://" callback-host ":" callback-port logout-complete-path))
+
+(defn- token-endpoint
+  []
+  (str "https://" (oauth-domain) token-endpoint-path))
+
+(defn- authorize-endpoint
+  []
+  (str "https://" (oauth-domain) authorize-endpoint-path))
+
+(defn- logout-endpoint
+  []
+  (str "https://" (oauth-domain) logout-endpoint-path))
+
+(defn- build-logout-url
+  []
+  (let [params (doto (js/URLSearchParams.)
+                 (.set "client_id" (oauth-client-id))
+                 (.set "logout_uri" (logout-complete-uri)))]
+    (str (logout-endpoint) "?" (.toString params))))
+
+(defn- parse-jwt
+  [jwt]
+  (when (seq jwt)
+    (try
+      (let [parts (string/split jwt #"\.")
+            payload (second parts)]
+        (when-not (and (= 3 (count parts))
+                       (seq payload))
+          (throw (ex-info "invalid auth token"
+                          {:code :invalid-auth-token
+                           :token jwt})))
+        (-> (js/Buffer.from payload "base64url")
+            (.toString "utf8")
+            parse-json))
+      (catch :default e
+        (if (= :invalid-auth-token (:code (ex-data e)))
+          (throw e)
+          (throw (ex-info "invalid auth token"
+                          {:code :invalid-auth-token
+                           :token jwt}
+                          e)))))))
+
+(defn write-auth-file!
+  [opts auth-data]
+  (let [path (auth-path opts)
+        payload (js/JSON.stringify (clj->js auth-data) nil 2)]
+    (ensure-auth-dir! path)
+    (.writeFileSync fs path payload "utf8")
+    (try-chmod! path)
+    auth-data))
+
+(defn read-auth-file
+  [opts]
+  (let [path (auth-path opts)]
+    (when (fs/existsSync path)
+      (try
+        (-> (fs/readFileSync path)
+            (.toString "utf8")
+            parse-json)
+        (catch :default e
+          (throw (ex-info "invalid auth file"
+                          {:code :invalid-auth-file
+                           :auth-path path}
+                          e)))))))
+
+(defn delete-auth-file!
+  [opts]
+  (let [path (auth-path opts)]
+    (when (fs/existsSync path)
+      (.unlinkSync fs path))
+    nil))
+
+(declare start-logout-complete-server! open-browser!)
+
+(defn logout!
+  [opts]
+  (let [path (auth-path opts)
+        existed? (fs/existsSync path)
+        logout-url (build-logout-url)]
+    (delete-auth-file! opts)
+    (p/let [callback-server (start-logout-complete-server! opts)]
+      (-> (p/let [open-result (open-browser! logout-url)
+                  _ (when-not (:opened? open-result)
+                      (throw (ex-info "failed to open browser for logout"
+                                      {:code :logout-browser-open-failed
+                                       :logout-url logout-url})))
+                  _ ((:wait! callback-server))]
+            {:auth-path path
+             :deleted? existed?
+             :logout-url logout-url
+             :opened? true
+             :logout-completed? true})
+          (p/finally (fn []
+                       ((:stop! callback-server))))))))
+
+(defn expired-auth?
+  [{:keys [expires-at]}]
+  (or (not (number? expires-at))
+      (<= expires-at (js/Date.now))))
+
+(defn- random-base64url
+  [size]
+  (.toString (.randomBytes crypto size) "base64url"))
+
+(defn- code-challenge
+  [code-verifier]
+  (-> (.createHash crypto "sha256")
+      (.update code-verifier)
+      (.digest "base64url")))
+
+(defn build-authorize-url
+  [{:keys [redirect-uri state pkce-challenge]}]
+  (let [params (doto (js/URLSearchParams.)
+                 (.set "response_type" "code")
+                 (.set "client_id" (oauth-client-id))
+                 (.set "scope" (oauth-scope))
+                 (.set "redirect_uri" redirect-uri)
+                 (.set "state" state)
+                 (.set "code_challenge" pkce-challenge)
+                 (.set "code_challenge_method" "S256"))]
+    (str (authorize-endpoint) "?" (.toString params))))
+
+(defn- stop-server!
+  [server]
+  (if (some? server)
+    (p/create (fn [resolve _reject]
+                (.close server (fn []
+                                 (resolve true)))))
+    (p/resolved true)))
+
+(defn start-login-callback-server!
+  [{:keys [state login-timeout-ms]}]
+  (p/create
+   (fn [resolve reject]
+     (let [callback-handlers (atom nil)
+           settled? (atom false)
+           callback-promise (p/create (fn [resolve' reject']
+                                        (reset! callback-handlers {:resolve resolve'
+                                                                   :reject reject'})))
+           finish! (fn [kind payload]
+                     (when-not @settled?
+                       (reset! settled? true)
+                       (when-let [{:keys [resolve reject]} @callback-handlers]
+                         ((if (= kind :resolve) resolve reject) payload))))
+           server (.createServer http
+                                 (fn [^js req ^js res]
+                                   (let [url (js/URL. (str "http://" callback-host (.-url req)))
+                                         pathname (.-pathname url)
+                                         params (.-searchParams url)
+                                         code (.get params "code")
+                                         callback-state (.get params "state")
+                                         error-code (.get params "error")]
+                                     (cond
+                                       (not= redirect-path pathname)
+                                       (do
+                                         (.writeHead res 404 #js {"Content-Type" "text/plain; charset=utf-8"})
+                                         (.end res "Not found"))
+
+                                       (seq error-code)
+                                       (do
+                                         (.writeHead res 400 #js {"Content-Type" "text/plain; charset=utf-8"})
+                                         (.end res "Login failed. You can return to the CLI.")
+                                         (finish! :reject (ex-info "login callback returned oauth error"
+                                                                   {:code :login-callback-error
+                                                                    :oauth-error error-code})))
+
+                                       (not= state callback-state)
+                                       (do
+                                         (.writeHead res 400 #js {"Content-Type" "text/plain; charset=utf-8"})
+                                         (.end res "Login failed due to state mismatch. Return to the CLI and retry.")
+                                         (finish! :reject (ex-info "login callback state mismatch"
+                                                                   {:code :invalid-callback-state})))
+
+                                       (not (seq code))
+                                       (do
+                                         (.writeHead res 400 #js {"Content-Type" "text/plain; charset=utf-8"})
+                                         (.end res "Login failed because the callback did not include a code.")
+                                         (finish! :reject (ex-info "missing authorization code"
+                                                                   {:code :missing-callback-code})))
+
+                                       :else
+                                       (do
+                                         (.writeHead res 200 #js {"Content-Type" "text/plain; charset=utf-8"})
+                                         (.end res "Login successful. You can return to the CLI.")
+                                         (finish! :resolve {:code code}))))))
+           timeout-id (js/setTimeout (fn []
+                                       (finish! :reject (ex-info "login callback timed out"
+                                                                 {:code :login-timeout})))
+                                     (or login-timeout-ms default-login-timeout-ms))]
+       (.on server "error" (fn [error]
+                              (js/clearTimeout timeout-id)
+                              (reject (ex-info "failed to start login callback server"
+                                               {:code :login-callback-server-start-failed}
+                                               error))))
+       (.listen server callback-port callback-host
+                (fn []
+                  (let [address (.address server)
+                        port (.-port address)
+                        redirect-uri (str "http://" callback-host ":" port redirect-path)]
+                    (resolve {:port port
+                              :redirect-uri redirect-uri
+                              :wait! (fn []
+                                       (-> callback-promise
+                                           (p/finally (fn []
+                                                        (js/clearTimeout timeout-id)))))
+                              :stop! (fn []
+                                       (js/clearTimeout timeout-id)
+                                       (stop-server! server))}))))))))
+
+(defn start-logout-complete-server!
+  [{:keys [logout-timeout-ms]}]
+  (p/create
+   (fn [resolve reject]
+     (let [settled? (atom false)
+           callback-handlers (atom nil)
+           callback-promise (p/create (fn [resolve' reject']
+                                        (reset! callback-handlers {:resolve resolve'
+                                                                   :reject reject'})))
+           finish! (fn [kind payload]
+                     (when-not @settled?
+                       (reset! settled? true)
+                       (when-let [{:keys [resolve reject]} @callback-handlers]
+                         ((if (= kind :resolve) resolve reject) payload))))
+           server (.createServer http
+                                 (fn [^js req ^js res]
+                                   (let [url (js/URL. (str "http://" callback-host (.-url req)))
+                                         pathname (.-pathname url)]
+                                     (if (= logout-complete-path pathname)
+                                       (do
+                                         (.writeHead res 200 #js {"Content-Type" "text/plain; charset=utf-8"})
+                                         (.end res "Logout successful. You can return to the CLI.")
+                                         (finish! :resolve true))
+                                       (do
+                                         (.writeHead res 404 #js {"Content-Type" "text/plain; charset=utf-8"})
+                                         (.end res "Not found"))))))
+           timeout-id (js/setTimeout (fn []
+                                       (finish! :reject (ex-info "logout callback timed out"
+                                                                 {:code :logout-timeout})))
+                                     (or logout-timeout-ms default-logout-timeout-ms))]
+       (.on server "error" (fn [error]
+                              (js/clearTimeout timeout-id)
+                              (reject (ex-info "failed to start logout callback server"
+                                               {:code :logout-callback-server-start-failed}
+                                               error))))
+       (.listen server callback-port callback-host
+                (fn []
+                  (resolve {:logout-uri (logout-complete-uri)
+                            :wait! (fn []
+                                     (-> callback-promise
+                                         (p/finally (fn []
+                                                      (js/clearTimeout timeout-id)))))
+                            :stop! (fn []
+                                     (js/clearTimeout timeout-id)
+                                     (stop-server! server))})))))))
+
+(defn- browser-open-command
+  [platform url]
+  (letfn [(unwrap-double-quoted [s]
+            (if (and (string/starts-with? s "\"")
+                     (string/ends-with? s "\"")
+                     (> (count s) 1))
+              (subs s 1 (dec (count s)))
+              s))
+          (windows-start-url-command [s]
+            (str "start \"\" \"" (unwrap-double-quoted s) "\""))]
+    (case platform
+      "darwin" ["open" [url]]
+      "linux" ["xdg-open" [url]]
+      "win32" ["cmd.exe" ["/d" "/c" (windows-start-url-command url)]]
+      [nil nil])))
+
+(defn- browser-open-spawn-options
+  [platform]
+  (cond-> {:detached true
+           :stdio "ignore"
+           :shell false}
+    (= platform "win32")
+    (assoc :windowsVerbatimArguments true)))
+
+(defn open-browser!
+  [url]
+  (let [platform (.-platform js/process)
+        [command args] (browser-open-command platform url)
+        spawn-opts (browser-open-spawn-options platform)]
+    (if-not (seq command)
+      (p/rejected (ex-info "unsupported platform for browser open"
+                           {:code :browser-open-unsupported-platform
+                            :platform platform}))
+      (p/create
+       (fn [resolve reject]
+         (try
+           (let [child (.spawn child-process command (clj->js args) (clj->js spawn-opts))]
+             (.unref child)
+             (resolve {:opened? true
+                       :command command}))
+           (catch :default e
+             (reject (ex-info "failed to open browser"
+                              {:code :browser-open-failed
+                               :command command}
+                              e)))))))))
+
+(defn- oauth-token-request!
+  [params]
+  (let [search-params (js/URLSearchParams.)]
+    (.set search-params "client_id" (oauth-client-id))
+    (doseq [[k v] params]
+      (.set search-params k (str v)))
+    (let [body (.toString search-params)]
+      (-> (transport/request {:method "POST"
+                              :url (token-endpoint)
+                              :headers {"Content-Type" "application/x-www-form-urlencoded"
+                                        "Accept" "application/json"}
+                              :body body
+                              :timeout-ms 10000})
+          (p/then (fn [{:keys [body]}]
+                    (parse-json body)))))))
+
+(defn- token-body->auth-data
+  [token-body current-auth]
+  (let [id-token (:id_token token-body)
+        _ (when-not (seq id-token)
+            (throw (ex-info "auth token response missing id_token"
+                            {:code :missing-id-token})))
+        claims (parse-jwt id-token)
+        refresh-token (or (:refresh_token token-body)
+                          (:refresh-token current-auth))]
+    {:provider auth-provider
+     :id-token id-token
+     :access-token (:access_token token-body)
+     :refresh-token refresh-token
+     :expires-at (some-> (:exp claims) (* 1000))
+     :sub (:sub claims)
+     :email (:email claims)
+     :updated-at (js/Date.now)}))
+
+(defn exchange-code-for-auth!
+  [_opts {:keys [code redirect-uri code-verifier]}]
+  (-> (oauth-token-request! {"grant_type" "authorization_code"
+                             "code" code
+                             "redirect_uri" redirect-uri
+                             "code_verifier" code-verifier})
+      (p/then (fn [token-body]
+                (token-body->auth-data token-body nil)))
+      (p/catch (fn [error]
+                 (let [data (ex-data error)]
+                   (p/rejected
+                    (ex-info "authorization code exchange failed"
+                             (merge {:code :auth-code-exchange-failed}
+                                    (when data {:context data}))
+                             error)))))))
+
+(defn refresh-auth!
+  [opts auth-data]
+  (let [refresh-token (:refresh-token auth-data)]
+    (if (seq refresh-token)
+      (-> (oauth-token-request! {"grant_type" "refresh_token"
+                                 "refresh_token" refresh-token})
+          (p/then (fn [token-body]
+                    (token-body->auth-data token-body auth-data)))
+          (p/catch (fn [error]
+                     (let [data (ex-data error)
+                           parsed-body (try
+                                         (some-> (:body data) parse-json)
+                                         (catch :default _
+                                           nil))]
+                       (if (= "invalid_grant" (:error parsed-body))
+                         (p/rejected
+                          (ex-info "refresh token is invalid"
+                                   {:code :missing-auth
+                                    :hint "Run `logseq login` first."
+                                    :auth-path (auth-path opts)}
+                                   error))
+                         (p/rejected
+                          (ex-info "auth refresh failed"
+                                   {:code :auth-refresh-failed
+                                    :hint "Run `logseq login` first."
+                                    :auth-path (auth-path opts)
+                                    :context data}
+                                   error)))))))
+      (p/rejected (ex-info "missing refresh token"
+                           {:code :missing-auth
+                            :hint "Run `logseq login` first."
+                            :auth-path (auth-path opts)})))))
+
+(defn login!
+  [opts]
+  (let [state (or (:state opts) (random-base64url 24))
+        code-verifier (or (:code-verifier opts) (random-base64url 48))
+        authorize-payload {:state state
+                           :pkce-challenge (code-challenge code-verifier)}]
+    (p/let [callback-server (start-login-callback-server! (merge opts {:state state}))
+            redirect-uri (:redirect-uri callback-server)
+            authorize-url (build-authorize-url (assoc authorize-payload :redirect-uri redirect-uri))]
+      (-> (p/let [open-result (open-browser! authorize-url)
+                  callback-result ((:wait! callback-server))
+                  auth-data (exchange-code-for-auth! opts {:code (:code callback-result)
+                                                           :redirect-uri redirect-uri
+                                                           :code-verifier code-verifier})
+                  _ (write-auth-file! opts auth-data)]
+            {:auth-path (auth-path opts)
+             :authorize-url authorize-url
+             :opened? (:opened? open-result)
+             :email (:email auth-data)
+             :sub (:sub auth-data)
+             :updated-at (:updated-at auth-data)})
+          (p/finally (fn []
+                       ((:stop! callback-server))))))))
+
+(defn resolve-auth!
+  [opts]
+  (if-let [current-auth (read-auth-file opts)]
+    (if (expired-auth? current-auth)
+      (p/let [refreshed-auth (refresh-auth! opts current-auth)
+              next-auth (merge current-auth refreshed-auth)]
+        (write-auth-file! opts next-auth)
+        next-auth)
+      (p/resolved current-auth))
+    (p/rejected (ex-info "missing auth"
+                         {:code :missing-auth
+                          :hint "Run `logseq login` first."
+                          :auth-path (auth-path opts)}))))
+
+(defn resolve-auth-token!
+  [opts]
+  (p/let [auth (resolve-auth! opts)]
+    (:id-token auth)))
diff --git a/src/main/logseq/cli/command/add.cljs b/src/main/logseq/cli/command/add.cljs
new file mode 100644
index 0000000000..7be8577ee5
--- /dev/null
+++ b/src/main/logseq/cli/command/add.cljs
@@ -0,0 +1,1213 @@
+(ns logseq.cli.command.add
+  "Add-related CLI commands. Used by upsert to provide create mode"
+  (:require ["fs" :as fs]
+            [cljs-time.coerce :as tc]
+            [cljs-time.core :as t]
+            [cljs.reader :as reader]
+            [clojure.string :as string]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.util :as common-util]
+            [logseq.common.util.date-time :as date-time-util]
+            [logseq.common.util.page-ref :as page-ref]
+            [logseq.common.uuid :as common-uuid]
+            [logseq.db :as ldb]
+            [logseq.db.frontend.content :as db-content]
+            [logseq.db.frontend.property :as db-property]
+            [logseq.db.frontend.property.type :as db-property-type]
+            [promesa.core :as p]))
+
+(defn- today-page-title
+  [config repo]
+  (p/let [journal (transport/invoke config :thread-api/pull false
+                                    [repo [:logseq.property.journal/title-format] :logseq.class/Journal])
+          formatter (or (:logseq.property.journal/title-format journal) "MMM do, yyyy")
+          now (-> (js/Date.)
+                  tc/from-date
+                  t/to-default-time-zone)]
+    (date-time-util/format now formatter)))
+
+(defn find-pages-by-name
+  "Query all live (non-recycled) pages matching a given name. Returns a vector
+   of entity maps. Because :block/name is not unique (a tag, property and page
+   can share the same name), callers should check for ambiguity."
+  [config repo page-name selector]
+  (p/let [results (transport/invoke config :thread-api/q false
+                                    [repo
+                                     [{:find [[(list 'pull '?e selector) '...]]
+                                       :in '[$ ?name]
+                                       :where '[[?e :block/name ?name]]}
+                                      (common-util/page-name-sanity-lc page-name)]])]
+    (vec (remove ldb/recycled? (or results [])))))
+
+(defn throw-ambiguous-page-error!
+  "Throws when multiple pages match the same name. Callers should present the
+   candidates so the user can rerun with --id."
+  [page-name matches]
+  (let [candidates (->> matches
+                        (map (fn [item]
+                               {:id (:db/id item)
+                                :name (or (:block/title item) (:block/name item))}))
+                        (filter :id)
+                        vec)]
+    (throw (ex-info (str "multiple pages match name: " page-name "; rerun with --id")
+                    {:code :ambiguous-page-name
+                     :candidates candidates}))))
+
+(defn- ensure-page!
+  "Ensure a page only if it is unique. Otherwise returns an ambiugous error to let user choose the specific
+   intended page"
+  [config repo page-name]
+  (p/let [live (find-pages-by-name config repo page-name
+                                   [:db/id :block/uuid :block/name :block/title])
+          _ (when (> (count live) 1)
+              (throw-ambiguous-page-error! page-name live))
+          page (first live)]
+    (if (:db/id page)
+      page
+      (let [page-name-lc (common-util/page-name-sanity-lc page-name)]
+        (p/let [_ (transport/invoke config :thread-api/apply-outliner-ops false
+                                    [repo [[:create-page [page-name {}]]] {}])]
+          (transport/invoke config :thread-api/pull false
+                            [repo [:db/id :block/uuid :block/name :block/title] [:block/name page-name-lc]]))))))
+
+(defn pull-tag-by-name
+  "Look up a tag by name, constrained to entities tagged with :logseq.class/Tag."
+  [config repo tag-name selector]
+  (p/let [result (transport/invoke config :thread-api/q false
+                                   [repo
+                                    [{:find [[(list 'pull '?e selector) '...]]
+                                      :in '[$ ?name]
+                                      :where '[[?e :block/name ?name]
+                                               [?e :block/tags ?t]
+                                               [?t :db/ident :logseq.class/Tag]]}
+                                     (common-util/page-name-sanity-lc tag-name)]])]
+    (first result)))
+
+(defn pull-property-by-name
+  "Look up a property by name, constrained to entities tagged with :logseq.class/Property."
+  [config repo property-name selector]
+  (p/let [result (transport/invoke config :thread-api/q false
+                                   [repo
+                                    [{:find [[(list 'pull '?e selector) '...]]
+                                      :in '[$ ?name]
+                                      :where '[[?e :block/name ?name]
+                                               [?e :block/tags ?t]
+                                               [?t :db/ident :logseq.class/Property]]}
+                                     (common-util/page-name-sanity-lc property-name)]])]
+    (first result)))
+
+(def ^:private add-positions
+  #{"first-child" "last-child" "sibling"})
+
+(def ^:private status-aliases
+  {"todo" :logseq.property/status.todo
+   "doing" :logseq.property/status.doing
+   "done" :logseq.property/status.done
+   "now" :logseq.property/status.doing
+   "later" :logseq.property/status.todo
+   "wait" :logseq.property/status.backlog
+   "waiting" :logseq.property/status.backlog
+   "backlog" :logseq.property/status.backlog
+   "canceled" :logseq.property/status.canceled
+   "cancelled" :logseq.property/status.canceled
+   "in-review" :logseq.property/status.in-review
+   "in_review" :logseq.property/status.in-review
+   "inreview" :logseq.property/status.in-review
+   "in-progress" :logseq.property/status.doing
+   "in progress" :logseq.property/status.doing
+   "inprogress" :logseq.property/status.doing})
+
+(defn normalize-status
+  [value]
+  (let [text (some-> value string/trim)
+        parsed (when (and (seq text) (string/starts-with? text ":"))
+                 (common-util/safe-read-string {:log-error? false} text))
+        normalized (cond
+                     (qualified-keyword? parsed)
+                     parsed
+
+                     (keyword? parsed)
+                     (get status-aliases (name parsed))
+
+                     (seq text)
+                     (get status-aliases (string/lower-case text))
+
+                     :else nil)]
+    normalized))
+
+(defn- ensure-block-uuids
+  [blocks]
+  (mapv (fn ensure-block-uuid [block]
+          (let [current (:block/uuid block)
+                block (cond
+                        (some? current)
+                        (update block :block/uuid (fn [value]
+                                                    (if (and (string? value) (common-util/uuid-string? value))
+                                                      (uuid value)
+                                                      value)))
+
+                        :else
+                        (assoc block :block/uuid (common-uuid/gen-uuid)))]
+            (if (seq (:block/children block))
+              (update block :block/children ensure-block-uuids)
+              block)))
+        blocks))
+
+(defn- normalize-created-ids
+  [ids]
+  (->> ids
+       (remove nil?)
+       distinct
+       vec))
+
+(defn- normalized-uuid
+  [value]
+  (cond
+    (uuid? value) value
+    (and (string? value) (common-util/uuid-string? (string/trim value)))
+    (uuid (string/trim value))
+    :else nil))
+
+(defn- collect-created-block-uuids
+  [blocks]
+  (letfn [(walk [acc block]
+            (let [block-uuid (normalized-uuid (:block/uuid block))
+                  acc (if block-uuid
+                        (conj acc block-uuid)
+                        acc)
+                  children (:block/children block)]
+              (if (seq children)
+                (reduce walk acc children)
+                acc)))]
+    (->> (reduce walk [] blocks)
+         distinct
+         vec)))
+
+(defn- flatten-block-tree
+  [blocks]
+  (letfn [(walk [parent-uuid block]
+            (let [children (:block/children block)
+                  block (cond-> (dissoc block :block/children)
+                          parent-uuid
+                          (assoc :block/parent [:block/uuid parent-uuid]))
+                  block-uuid (normalized-uuid (:block/uuid block))]
+              (into [block]
+                    (mapcat #(walk block-uuid %) children))))]
+    (vec (mapcat #(walk nil %) blocks))))
+
+(defn- created-ids-in-order
+  [ordered-uuids entities entity-kind]
+  (let [id-by-uuid (reduce (fn [acc {:keys [db/id block/uuid]}]
+                             (if-let [entity-uuid (normalized-uuid uuid)]
+                               (if (some? id)
+                                 (assoc acc entity-uuid id)
+                                 acc)
+                               acc))
+                           {}
+                           entities)
+        missing-uuids (->> ordered-uuids
+                           (remove #(contains? id-by-uuid %))
+                           vec)]
+    (when (seq missing-uuids)
+      (throw (ex-info "unable to resolve created ids"
+                      {:code :add-id-resolution-failed
+                       :entity-kind entity-kind
+                       :missing-uuids missing-uuids})))
+    (normalize-created-ids (map #(get id-by-uuid %) ordered-uuids))))
+
+(defn- resolve-created-block-ids
+  [config repo blocks insert-result]
+  (let [ordered-uuids (or (seq (collect-created-block-uuids (:tx-data insert-result)))
+                          (seq (collect-created-block-uuids blocks))
+                          (seq (collect-created-block-uuids (:blocks insert-result))))]
+    (if-not (seq ordered-uuids)
+      (p/rejected (ex-info "unable to resolve created block ids"
+                           {:code :add-id-resolution-failed
+                            :entity-kind :block
+                            :reason :missing-created-uuids}))
+      (p/let [entities (p/all
+                        (map (fn [block-uuid]
+                               (transport/invoke config :thread-api/pull false
+                                                 [repo [:db/id :block/uuid] [:block/uuid block-uuid]]))
+                             ordered-uuids))]
+        (created-ids-in-order ordered-uuids entities :block)))))
+
+(defn- extract-page-refs
+  [title]
+  (when (string? title)
+    (->> (re-seq page-ref/page-ref-re title)
+         (map second)
+         (remove string/blank?))))
+
+(defn- collect-page-refs
+  [blocks]
+  (->> blocks
+       (mapcat (fn walk [block]
+                 (let [refs (extract-page-refs (:block/title block))
+                       children (:block/children block)]
+                   (if (seq children)
+                     (concat refs (mapcat walk children))
+                     refs))))
+       (remove string/blank?)
+       vec))
+
+(defn- integer-string?
+  [s]
+  (boolean (re-matches #"-?\d+" s)))
+
+(defn- partition-ref-values
+  [refs]
+  (reduce
+   (fn [acc ref-value]
+     (let [value (string/trim ref-value)]
+       (cond
+         (string/blank? value)
+         acc
+
+         (common-util/uuid-string? value)
+         (update acc :uuid-refs conj value)
+
+         (integer-string? value)
+         (update acc :id-refs conj value)
+
+         :else
+         (update acc :page-refs conj value))))
+   {:uuid-refs [] :page-refs [] :id-refs []}
+   refs))
+
+(defn- resolve-page-ref-entities
+  [config repo page-refs]
+  (if (seq page-refs)
+    (let [unique (reduce (fn [acc ref-value]
+                           (let [value (string/trim ref-value)]
+                             (if (string/blank? value)
+                               acc
+                               (assoc acc (common-util/page-name-sanity-lc value) value))))
+                         {}
+                         page-refs)]
+      (p/let [resolved (p/all
+                        (map (fn [[_ page-name]]
+                               (p/let [page (ensure-page! config repo page-name)
+                                       page-uuid (:block/uuid page)]
+                                 (when-not page-uuid
+                                   (throw (ex-info "page not found"
+                                                   {:code :page-not-found
+                                                    :page page-name})))
+                                 {:block/uuid page-uuid
+                                  :block/title (or (:block/title page) page-name)}))
+                             unique))]
+        (vec resolved)))
+    (p/resolved nil)))
+
+(defn- ensure-block-refs-exist!
+  [config repo uuid-refs]
+  (when (seq uuid-refs)
+    (p/all
+     (map (fn [uuid-ref]
+            (p/let [entity (transport/invoke config :thread-api/pull false
+                                             [repo [:db/id :block/uuid] [:block/uuid (uuid uuid-ref)]])]
+              (when-not (:db/id entity)
+                (throw (ex-info (str "block ref not found: " uuid-ref)
+                                {:code :block-ref-not-found
+                                 :uuid uuid-ref})))))
+          (distinct uuid-refs)))))
+
+(defn- resolve-id-ref-entities
+  "Resolve integer id refs (db/id values) to entity maps with :block/uuid and
+   :block/title so they can be normalized like page-name refs."
+  [config repo id-refs]
+  (if (seq id-refs)
+    (p/let [entities (p/all
+                      (map (fn [id-str]
+                             (let [id (parse-long id-str)]
+                               (p/let [entity (transport/invoke config :thread-api/pull false
+                                                                [repo [:db/id :block/uuid :block/title] id])]
+                                 (when-not (:db/id entity)
+                                   (throw (ex-info (str "id ref not found: " id-str)
+                                                   {:code :id-ref-not-found
+                                                    :id id-str})))
+                                 {:block/uuid (:block/uuid entity)
+                                  :block/title id-str})))
+                           (distinct id-refs)))]
+      (vec entities))
+    (p/resolved nil)))
+
+(defn- normalize-block-title-refs
+  [blocks refs]
+  (mapv (fn update-block [block]
+          (let [block' (if (string? (:block/title block))
+                         (update block :block/title
+                                 #(db-content/title-ref->id-ref % refs :replace-tag? false))
+                         block)]
+            (if (seq (:block/children block'))
+              (update block' :block/children #(normalize-block-title-refs % refs))
+              block')))
+        blocks))
+
+(defn- invalid-options-result
+  [message]
+  {:ok? false
+   :error {:code :invalid-options
+           :message message}})
+
+(defn- parse-edn-option
+  [value]
+  (when (seq value)
+    (common-util/safe-read-string {:log-error? false} value)))
+
+(defn- normalize-tag-value
+  [value]
+  (cond
+    (uuid? value) value
+    (number? value) value
+    (and (string? value) (common-util/uuid-string? (string/trim value)))
+    (uuid (string/trim value))
+    (keyword? value) value
+    (string? value) (let [text (-> value string/trim (string/replace #"^#+" ""))]
+                      (cond
+                        (string/blank? text) nil
+                        (common-util/valid-edn-keyword? text)
+                        (common-util/safe-read-string {:log-error? false} text)
+                        :else text))
+    :else nil))
+
+(defn parse-tags-option
+  [value]
+  (if-not (seq value)
+    {:ok? true :value nil}
+    (let [parsed (parse-edn-option value)]
+      (cond
+        (nil? parsed)
+        (invalid-options-result "tags must be valid EDN vector")
+
+        (not (vector? parsed))
+        (invalid-options-result "tags must be a vector")
+
+        (empty? parsed)
+        (invalid-options-result "tags must be a non-empty vector")
+
+        :else
+        (let [tags (mapv normalize-tag-value parsed)]
+          (if (some nil? tags)
+            (invalid-options-result "tags must be strings, keywords, uuids, or ids")
+            {:ok? true :value tags}))))))
+
+(defn parse-tags-vector-option
+  [value]
+  (parse-tags-option value))
+
+(defn- normalize-property-key
+  [value]
+  (cond
+    (keyword? value) value
+    (string? value)
+    (let [text (string/trim value)]
+      (cond
+        (string/blank? text) nil
+        (common-util/valid-edn-keyword? text)
+        (common-util/safe-read-string {:log-error? false} text)
+        :else (keyword text)))
+    :else nil))
+
+(def ^:private built-in-properties-by-title
+  (into {}
+        (keep (fn [[ident {:keys [title]}]]
+                (when (string? title)
+                  [(common-util/page-name-sanity-lc title) ident])))
+        db-property/built-in-properties))
+
+(defn- property-title->ident
+  [value]
+  (when (string? value)
+    (let [text (string/trim value)]
+      (when (seq text)
+        (get built-in-properties-by-title (common-util/page-name-sanity-lc text))))))
+
+(defn normalize-property-key-input
+  [value]
+  (cond
+    (keyword? value) {:type :ident :value value}
+    (number? value) {:type :id :value value}
+    (string? value)
+    (let [text (string/trim value)]
+      (cond
+        (string/blank? text) nil
+        (common-util/valid-edn-keyword? text)
+        (let [parsed (common-util/safe-read-string {:log-error? false} text)]
+          (when (keyword? parsed)
+            {:type :ident :value parsed}))
+        :else
+        (if-let [ident (property-title->ident text)]
+          {:type :ident :value ident}
+          {:type :ident :value (keyword text)})))
+    :else nil))
+
+(defn- parse-boolean-value
+  [value]
+  (cond
+    (or (true? value) (false? value)) {:ok? true :value value}
+    (string? value) (let [text (string/lower-case (string/trim value))]
+                      (cond
+                        (= text "true") {:ok? true :value true}
+                        (= text "false") {:ok? true :value false}
+                        :else {:ok? false}))
+    :else {:ok? false}))
+
+(defn- parse-number-value
+  [value]
+  (cond
+    (number? value) {:ok? true :value value}
+    (string? value) (let [parsed (js/parseFloat value)]
+                      (if (js/isNaN parsed)
+                        {:ok? false}
+                        {:ok? true :value parsed}))
+    :else {:ok? false}))
+
+(defn- parse-datetime-value
+  [value]
+  (cond
+    (number? value) {:ok? true :value value}
+    (string? value) (let [date (js/Date. value)
+                          ms (.getTime date)]
+                      (if (js/isNaN ms)
+                        {:ok? false}
+                        {:ok? true :value ms}))
+    :else {:ok? false}))
+
+(defn- parse-keyword-value
+  [value]
+  (cond
+    (keyword? value) {:ok? true :value value}
+    (string? value) (let [text (string/trim value)]
+                      (if (string/blank? text)
+                        {:ok? false}
+                        (if (common-util/valid-edn-keyword? text)
+                          (let [parsed (common-util/safe-read-string {:log-error? false} text)]
+                            (if (keyword? parsed)
+                              {:ok? true :value parsed}
+                              {:ok? false}))
+                          {:ok? true :value (keyword text)})))
+    :else {:ok? false}))
+
+(defn- coerce-property-value-basic
+  [property value]
+  (let [type (get-in property [:schema :type] :default)]
+    (cond
+      (nil? value)
+      {:ok? false :message "property value must not be nil"}
+
+      (= type :checkbox)
+      (let [{:keys [ok? value]} (parse-boolean-value value)]
+        (if ok?
+          {:ok? true :value value}
+          {:ok? false :message "checkbox property expects true or false"}))
+
+      (= type :number)
+      (let [{:keys [ok? value]} (parse-number-value value)]
+        (if ok?
+          {:ok? true :value value}
+          {:ok? false :message "number property expects a numeric value"}))
+
+      (= type :raw-number)
+      (if (number? value)
+        {:ok? true :value value}
+        {:ok? false :message "raw-number property expects a number"})
+
+      (= type :datetime)
+      (let [{:keys [ok? value]} (parse-datetime-value value)]
+        (if ok?
+          {:ok? true :value value}
+          {:ok? false :message "datetime property expects an ISO date string"}))
+
+      (= type :keyword)
+      (let [{:keys [ok? value]} (parse-keyword-value value)]
+        (if ok?
+          {:ok? true :value value}
+          {:ok? false :message "keyword property expects a keyword"}))
+
+      (= type :string)
+      (if (string? value)
+        {:ok? true :value value}
+        {:ok? false :message "string property expects a string"})
+
+      (= type :map)
+      (if (map? value)
+        {:ok? true :value value}
+        {:ok? false :message "map property expects a map"})
+
+      (= type :coll)
+      (if (and (coll? value) (not (string? value)))
+        {:ok? true :value (vec value)}
+        {:ok? false :message "coll property expects a collection"})
+
+      (= type :url)
+      (if (and (string? value) (or (db-property-type/url? value) (db-property-type/macro-url? value)))
+        {:ok? true :value value}
+        {:ok? false :message "url property expects a valid url"})
+
+      (= type :date)
+      (if (string? value)
+        {:ok? true :value value}
+        {:ok? false :message "date property expects a date string"})
+
+      (= type :default)
+      (if (or (string? value) (keyword? value))
+        {:ok? true :value value}
+        {:ok? false :message "default property expects a string value or keyword"})
+
+      (contains? #{:entity :page :class :property :node :any} type)
+      {:ok? true :value value}
+
+      :else
+      {:ok? true :value value})))
+
+(defn- normalize-property-values
+  [property value]
+  (let [many? (= :many (get-in property [:schema :cardinality]))
+        values (if many?
+                 (if (and (coll? value) (not (string? value))) value [value])
+                 [value])]
+    (loop [remaining values
+           normalized []]
+      (if (empty? remaining)
+        {:ok? true
+         :value (if many? (vec normalized) (first normalized))}
+        (let [result (coerce-property-value-basic property (first remaining))]
+          (if-not (:ok? result)
+            {:ok? false
+             :message (:message result)}
+            (recur (rest remaining) (conj normalized (:value result)))))))))
+
+(defn- property-public?
+  [property]
+  (true? (get-in property [:schema :public?])))
+
+(defn parse-properties-option
+  ([value]
+   (parse-properties-option value {:allow-non-built-in? false}))
+  ([value {:keys [allow-non-built-in?]
+           :or {allow-non-built-in? false}}]
+   (if-not (seq value)
+     {:ok? true :value nil}
+     (let [parsed (parse-edn-option value)]
+       (cond
+         (nil? parsed)
+         (invalid-options-result "properties must be valid EDN map")
+
+         (not (map? parsed))
+         (invalid-options-result "properties must be a map")
+
+         (empty? parsed)
+         (invalid-options-result "properties must be a non-empty map")
+
+         :else
+         (loop [prop-entries (seq parsed)
+                acc {}]
+           (if (empty? prop-entries)
+             {:ok? true :value acc}
+             (let [[k v] (first prop-entries)
+                   key-result (normalize-property-key-input k)]
+               (if-not key-result
+                 (invalid-options-result (str "invalid property key: " k))
+                 (let [{:keys [type value]} key-result
+                       key-ident value]
+                   (if (= type :id)
+                     (recur (rest prop-entries) (assoc acc key-ident v))
+                     (let [property (get db-property/built-in-properties key-ident)]
+                       (cond
+                         (nil? property)
+                         (if allow-non-built-in?
+                           (recur (rest prop-entries) (assoc acc key-ident v))
+                           (invalid-options-result (str "unknown built-in property: " key-ident)))
+
+                         (not (property-public? property))
+                         (invalid-options-result (str "property is not public: " key-ident))
+
+                         :else
+                         (let [{:keys [ok? value message]} (normalize-property-values property v)
+                               normalized-value value]
+                           (if-not ok?
+                             (invalid-options-result (str "invalid value for " key-ident ": " message))
+                             (recur (rest prop-entries) (assoc acc key-ident normalized-value)))))))))))))))))
+
+(defn parse-properties-vector-option
+  ([value]
+   (parse-properties-vector-option value {:allow-non-built-in? false}))
+  ([value {:keys [allow-non-built-in?]
+           :or {allow-non-built-in? false}}]
+   (if-not (seq value)
+     {:ok? true :value nil}
+     (let [parsed (parse-edn-option value)]
+       (cond
+         (nil? parsed)
+         (invalid-options-result "properties must be valid EDN vector")
+
+         (not (vector? parsed))
+         (invalid-options-result "properties must be a vector")
+
+         (empty? parsed)
+         (invalid-options-result "properties must be a non-empty vector")
+
+         :else
+         (loop [prop-entries (seq parsed)
+                acc []]
+           (if (empty? prop-entries)
+             {:ok? true :value acc}
+             (let [entry (first prop-entries)
+                   key-result (normalize-property-key-input entry)]
+               (if-not key-result
+                 (invalid-options-result (str "invalid property key: " entry))
+                 (let [{:keys [type value]} key-result]
+                   (if (= type :id)
+                     (recur (rest prop-entries) (conj acc value))
+                     (let [property (get db-property/built-in-properties value)]
+                       (cond
+                         (nil? property)
+                         (if allow-non-built-in?
+                           (recur (rest prop-entries) (conj acc value))
+                           (invalid-options-result (str "unknown built-in property: " value)))
+
+                         (not (property-public? property))
+                         (invalid-options-result (str "property is not public: " value))
+
+                         :else
+                         (recur (rest prop-entries) (conj acc value)))))))))))))))
+
+(defn invalid-options?
+  [opts]
+  (let [pos (some-> (:pos opts) string/trim string/lower-case)
+        target-id (:target-id opts)
+        target-uuid (some-> (:target-uuid opts) string/trim)
+        target-page (some-> (:target-page-name opts) string/trim)
+        target-selectors (filter some? [target-id target-uuid target-page])
+        has-blocks? (or (seq (:blocks opts)) (seq (:blocks-file opts)))
+        has-tags? (seq (some-> (:tags opts) string/trim))
+        has-properties? (seq (some-> (:properties opts) string/trim))]
+    (cond
+      (and (seq pos) (not (contains? add-positions pos)))
+      (str "invalid pos: " (:pos opts))
+
+      (> (count target-selectors) 1)
+      "only one of --target-id, --target-uuid, or --target-page-name is allowed"
+
+      (and (= pos "sibling") (or (seq target-page) (empty? target-selectors)))
+      "--pos sibling is only valid for block targets"
+
+      (and has-blocks? (or has-tags? has-properties?))
+      "tags and properties cannot be combined with --blocks or --blocks-file"
+
+      (or (:remove-tags opts) (:remove-properties opts))
+      "--remove-tags and --remove-properties are only for update mode"
+
+      :else
+      nil)))
+
+(defn- pull-entity
+  [config repo selector lookup]
+  (transport/invoke config :thread-api/pull false [repo selector lookup]))
+
+(defn- tag-lookup-ref
+  [tag]
+  (cond
+    (number? tag) tag
+    (uuid? tag) [:block/uuid tag]
+    (and (string? tag) (common-util/uuid-string? (string/trim tag))) [:block/uuid (uuid (string/trim tag))]
+    (keyword? tag) [:db/ident tag]
+    :else nil))
+
+(defn- resolve-tag-entity
+  [config repo tag]
+  (let [tag-selector [:db/id :block/name :block/title :block/uuid
+                      {:block/tags [:db/ident]}
+                      :logseq.property/public? :logseq.property/built-in?]]
+    (p/let [entity (cond
+                     (and (string? tag) (common-util/uuid-string? (string/trim tag)))
+                     (pull-entity config repo tag-selector [:block/uuid (uuid (string/trim tag))])
+
+                     (string? tag)
+                     (pull-tag-by-name config repo tag tag-selector)
+
+                     :else
+                     (let [lookup (or (tag-lookup-ref tag)
+                                      (throw (ex-info "invalid tag value" {:code :invalid-tag :tag tag})))]
+                       (pull-entity config repo tag-selector lookup)))]
+      (cond
+        (nil? (:db/id entity))
+        (throw (ex-info (str "tag not found: " (pr-str tag)) {:code :tag-not-found :tag tag}))
+
+        (not (some #(= :logseq.class/Tag (:db/ident %)) (:block/tags entity)))
+        (throw (ex-info (str "This is not a tag: " (pr-str tag)) {:code :not-a-tag :tag tag}))
+
+        (false? (:logseq.property/public? entity))
+        (throw (ex-info (str "tag is not public: " (pr-str tag)) {:code :tag-not-public :tag tag}))
+
+        :else
+        entity))))
+
+(defn resolve-tags
+  [config repo tags]
+  (if (seq tags)
+    (p/let [entities (p/all (map #(resolve-tag-entity config repo %) tags))]
+      (vec entities))
+    (p/resolved nil)))
+
+(defn- resolve-entity-id
+  [config repo lookup]
+  (p/let [entity (pull-entity config repo [:db/id] lookup)]
+    (if-let [id (:db/id entity)]
+      id
+      (throw (ex-info "entity not found" {:code :entity-not-found :lookup lookup})))))
+
+(defn- resolve-page-id
+  [config repo value]
+  (cond
+    (number? value) (p/resolved value)
+    (uuid? value) (resolve-entity-id config repo [:block/uuid value])
+    (and (string? value) (common-util/uuid-string? (string/trim value)))
+    (resolve-entity-id config repo [:block/uuid (uuid (string/trim value))])
+    (string? value)
+    (p/let [page (ensure-page! config repo value)]
+      (or (:db/id page)
+          (throw (ex-info "page not found" {:code :page-not-found :value value}))))
+    :else
+    (p/rejected (ex-info "page must be a name or uuid" {:code :invalid-page :value value}))))
+
+(defn- resolve-class-id
+  [config repo value]
+  (p/let [entity (resolve-tag-entity config repo value)]
+    (:db/id entity)))
+
+(defn- resolve-property-id
+  [config repo value]
+  (let [key (normalize-property-key value)]
+    (when-not key
+      (throw (ex-info "property must be a keyword" {:code :invalid-property :value value})))
+    (resolve-entity-id config repo [:db/ident key])))
+
+(defn- resolve-node-id
+  [config repo value]
+  (cond
+    (number? value) (p/resolved value)
+    (uuid? value) (resolve-entity-id config repo [:block/uuid value])
+    (and (string? value) (common-util/uuid-string? (string/trim value)))
+    (resolve-entity-id config repo [:block/uuid (uuid (string/trim value))])
+    (string? value)
+    (resolve-page-id config repo value)
+    :else
+    (p/rejected (ex-info "node must be a number, uuid or page name" {:code :invalid-node :value value}))))
+
+(defn- resolve-date-page-id
+  [config repo value]
+  (when-not (string? value)
+    (throw (ex-info "date property value must be a string" {:code :invalid-date :value value})))
+  (p/let [journal (pull-entity config repo [:logseq.property.journal/title-format] :logseq.class/Journal)
+          formatter (or (:logseq.property.journal/title-format journal) "MMM do, yyyy")
+          formatters (date-time-util/safe-journal-title-formatters formatter)
+          journal-day (date-time-util/journal-title->int value formatters)
+          _ (when-not journal-day
+              (throw (ex-info (str "invalid date property value: " (pr-str value))
+                              {:code :invalid-date :value value})))
+          title (date-time-util/int->journal-title journal-day formatter)
+          page (ensure-page! config repo title)]
+    (if-let [id (:db/id page)]
+      id
+      (throw (ex-info "journal page not found" {:code :page-not-found :value value})))))
+
+(defn- resolve-property-value
+  [config repo property value]
+  (let [type (get-in property [:schema :type] :default)]
+    (case type
+      :page (resolve-page-id config repo value)
+      :class (resolve-class-id config repo value)
+      :property (resolve-property-id config repo value)
+      :entity (resolve-entity-id config repo (cond
+                                               (number? value) value
+                                               (uuid? value) [:block/uuid value]
+                                               (and (string? value) (common-util/uuid-string? (string/trim value)))
+                                               [:block/uuid (uuid (string/trim value))]
+                                               :else value))
+      :node (resolve-node-id config repo value)
+      :date (resolve-date-page-id config repo value)
+      (p/resolved value))))
+
+(def ^:private property-entity-selector
+  [:db/id :db/ident :block/name :block/title
+   :logseq.property/type :db/cardinality :logseq.property/public?])
+
+(defn- property-entity?
+  [entity]
+  (some? (:logseq.property/type entity)))
+
+(defn- property-entity-public?
+  [entity]
+  (not (false? (:logseq.property/public? entity))))
+
+(defn- property-entity->property
+  [entity]
+  {:schema {:type (or (:logseq.property/type entity) :default)
+            :cardinality (if (= :db.cardinality/many (:db/cardinality entity))
+                           :many
+                           :one)
+            :public? (property-entity-public? entity)}})
+
+(defn- lookup-property-entity
+  [config repo property-key]
+  (let [lookup-by-title (fn [title]
+                          (pull-property-by-name config repo title property-entity-selector))]
+    (cond
+      (number? property-key)
+      (pull-entity config repo property-entity-selector property-key)
+
+      (uuid? property-key)
+      (pull-entity config repo property-entity-selector [:block/uuid property-key])
+
+      (keyword? property-key)
+      (p/let [entity (pull-entity config repo property-entity-selector [:db/ident property-key])]
+        (if (or (:db/id entity) (qualified-keyword? property-key))
+          entity
+          (lookup-by-title (name property-key))))
+
+      (string? property-key)
+      (let [text (string/trim property-key)
+            ident (normalize-property-key text)]
+        (if-not (seq text)
+          (p/resolved nil)
+          (if (common-util/uuid-string? text)
+            (pull-entity config repo property-entity-selector [:block/uuid (uuid text)])
+            (p/let [entity (lookup-by-title text)]
+              (if (:db/id entity)
+                entity
+                (if ident
+                  (pull-entity config repo property-entity-selector [:db/ident ident])
+                  (p/resolved nil)))))))
+
+      :else
+      (p/resolved nil))))
+
+(defn- resolve-property-entry-allow-non-built-in
+  [config repo property-key]
+  (p/let [entity (lookup-property-entity config repo property-key)
+          ident (:db/ident entity)]
+    (cond
+      (nil? (:db/id entity))
+      (throw (ex-info (str "property not found: " (pr-str property-key))
+                      {:code :property-not-found
+                       :property property-key}))
+
+      (not (property-entity? entity))
+      (throw (ex-info (str "This is not a property: " (pr-str property-key))
+                      {:code :invalid-property-target
+                       :property property-key}))
+
+      (nil? ident)
+      (throw (ex-info (str "property not found: " (pr-str property-key))
+                      {:code :property-not-found
+                       :property property-key}))
+
+      (not (property-entity-public? entity))
+      (throw (ex-info (str "property is not public: " (pr-str (name property-key)))
+                      {:code :property-not-public
+                       :property ident}))
+
+      :else
+      {:ident ident
+       :property (property-entity->property entity)})))
+
+(defn resolve-properties
+  ([config repo properties]
+   (resolve-properties config repo properties {:allow-non-built-in? false}))
+  ([config repo properties {:keys [allow-non-built-in?]
+                            :or {allow-non-built-in? false}}]
+   (if-not (seq properties)
+     (p/resolved nil)
+     (p/let [resolved-entries (p/all
+                               (map (fn [[k v]]
+                                      (p/let [{:keys [ident property]}
+                                              (if allow-non-built-in?
+                                                (resolve-property-entry-allow-non-built-in config repo k)
+                                                (cond
+                                                  (keyword? k)
+                                                  (let [property (get db-property/built-in-properties k)]
+                                                    (when-not property
+                                                      (throw (ex-info "unknown built-in property"
+                                                                      {:code :unknown-property :property k})))
+                                                    (when-not (property-public? property)
+                                                      (throw (ex-info "property is not public"
+                                                                      {:code :property-not-public :property k})))
+                                                    (p/resolved {:ident k :property property}))
+
+                                                  (number? k)
+                                                  (p/let [entity (pull-entity config repo [:db/ident] k)
+                                                          ident (:db/ident entity)
+                                                          property (get db-property/built-in-properties ident)]
+                                                    (cond
+                                                      (nil? ident)
+                                                      (throw (ex-info "property not found"
+                                                                      {:code :property-not-found :property k}))
+
+                                                      (nil? property)
+                                                      (throw (ex-info "unknown built-in property"
+                                                                      {:code :unknown-property :property ident}))
+
+                                                      (not (property-public? property))
+                                                      (throw (ex-info "property is not public"
+                                                                      {:code :property-not-public :property ident}))
+
+                                                      :else
+                                                      {:ident ident :property property}))
+
+                                                  (string? k)
+                                                  (let [ident (or (property-title->ident k)
+                                                                  (normalize-property-key k))
+                                                        property (get db-property/built-in-properties ident)]
+                                                    (when-not property
+                                                      (throw (ex-info "unknown built-in property"
+                                                                      {:code :unknown-property :property k})))
+                                                    (when-not (property-public? property)
+                                                      (throw (ex-info "property is not public"
+                                                                      {:code :property-not-public :property ident})))
+                                                    (p/resolved {:ident ident :property property}))
+
+                                                  :else
+                                                  (p/rejected (ex-info "invalid property key"
+                                                                       {:code :invalid-property :property k}))))
+                                              {:keys [ok? value message]} (normalize-property-values property v)]
+                                        (when-not ok?
+                                          (throw (ex-info (str "invalid value for property " (pr-str (name k)) ": " message)
+                                                          {:code :invalid-property-value
+                                                           :property ident
+                                                           :message message})))
+                                        (let [many? (= :many (get-in property [:schema :cardinality]))
+                                              values (if many?
+                                                       (if (and (coll? value) (not (string? value))) value [value])
+                                                       [value])]
+                                          (p/let [resolved (p/all (map #(resolve-property-value config repo property %) values))
+                                                  final-value (if many? (vec resolved) (first resolved))]
+                                            [ident final-value]))))
+                                    properties))]
+       (into {} resolved-entries)))))
+
+(defn resolve-property-identifiers
+  ([config repo properties]
+   (resolve-property-identifiers config repo properties {:allow-non-built-in? false}))
+  ([config repo properties {:keys [allow-non-built-in?]
+                            :or {allow-non-built-in? false}}]
+   (if-not (seq properties)
+     (p/resolved nil)
+     (p/let [resolved-entries (p/all
+                               (map (fn [k]
+                                      (if allow-non-built-in?
+                                        (p/let [{:keys [ident]} (resolve-property-entry-allow-non-built-in config repo k)]
+                                          ident)
+                                        (cond
+                                          (keyword? k)
+                                          (let [property (get db-property/built-in-properties k)]
+                                            (when-not property
+                                              (throw (ex-info "unknown built-in property"
+                                                              {:code :unknown-property :property k})))
+                                            (when-not (property-public? property)
+                                              (throw (ex-info "property is not public"
+                                                              {:code :property-not-public :property k})))
+                                            (p/resolved k))
+
+                                          (number? k)
+                                          (p/let [entity (pull-entity config repo [:db/ident] k)
+                                                  ident (:db/ident entity)
+                                                  property (get db-property/built-in-properties ident)]
+                                            (cond
+                                              (nil? ident)
+                                              (throw (ex-info "property not found"
+                                                              {:code :property-not-found :property k}))
+
+                                              (nil? property)
+                                              (throw (ex-info "unknown built-in property"
+                                                              {:code :unknown-property :property ident}))
+
+                                              (not (property-public? property))
+                                              (throw (ex-info "property is not public"
+                                                              {:code :property-not-public :property ident}))
+
+                                              :else
+                                              ident))
+
+                                          (string? k)
+                                          (let [ident (or (property-title->ident k)
+                                                          (normalize-property-key k))
+                                                property (get db-property/built-in-properties ident)]
+                                            (when-not property
+                                              (throw (ex-info "unknown built-in property"
+                                                              {:code :unknown-property :property k})))
+                                            (when-not (property-public? property)
+                                              (throw (ex-info "property is not public"
+                                                              {:code :property-not-public :property ident})))
+                                            (p/resolved ident))
+
+                                          :else
+                                          (p/rejected (ex-info "invalid property key"
+                                                               {:code :invalid-property :property k})))))
+                                    properties))]
+       (vec resolved-entries)))))
+
+(defn- resolve-add-target
+  [config {:keys [repo target-id target-uuid target-page-name]}]
+  (cond
+    (some? target-id)
+    (p/let [block (transport/invoke config :thread-api/pull false
+                                    [repo [:db/id :block/uuid :block/title] target-id])]
+      (if-let [block-uuid (:block/uuid block)]
+        block-uuid
+        (throw (ex-info "target block not found" {:code :target-not-found}))))
+
+    (seq target-uuid)
+    (p/let [block (transport/invoke config :thread-api/pull false
+                                    [repo [:db/id :block/uuid :block/title] [:block/uuid (uuid target-uuid)]])]
+      (if-let [block-uuid (:block/uuid block)]
+        block-uuid
+        (throw (ex-info "target block not found" {:code :target-not-found}))))
+
+    :else
+    (p/let [page-name (if (seq target-page-name) target-page-name (today-page-title config repo))
+            page-entity (ensure-page! config repo page-name)]
+      (or (:block/uuid page-entity)
+          (throw (ex-info "page not found" {:code :page-not-found}))))))
+
+(defn- read-blocks
+  [options command-args]
+  (cond
+    (seq (:blocks options))
+    {:ok? true :value (reader/read-string (:blocks options))}
+
+    (seq (:blocks-file options))
+    (let [contents (.toString (fs/readFileSync (:blocks-file options)) "utf8")]
+      {:ok? true :value (reader/read-string contents)})
+
+    (seq (:content options))
+    {:ok? true :value [{:block/title (:content options)}]}
+
+    (seq command-args)
+    {:ok? true :value [{:block/title (string/join " " command-args)}]}
+
+    :else
+    {:ok? false
+     :error {:code :missing-content
+             :message "content is required"}}))
+
+(defn- ensure-blocks
+  [value]
+  (if (vector? value)
+    {:ok? true :value value}
+    {:ok? false
+     :error {:code :invalid-blocks
+             :message "blocks must be a vector"}}))
+
+(defn build-add-block-action
+  [options args repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for add"}}
+    (let [blocks-result (read-blocks options args)
+          status-text (some-> (:status options) string/trim)
+          status (when (seq status-text) (normalize-status status-text))
+          tags-result (parse-tags-option (:tags options))
+          properties-result (parse-properties-option (:properties options))
+          tags (:value tags-result)
+          properties (:value properties-result)]
+      (cond
+        (and (seq status-text) (nil? status))
+        {:ok? false
+         :error {:code :invalid-options
+                 :message (str "invalid status: " status-text)}}
+
+        (not (:ok? tags-result))
+        tags-result
+
+        (not (:ok? properties-result))
+        properties-result
+
+        :else
+        (if-not (:ok? blocks-result)
+          blocks-result
+          (let [vector-result (ensure-blocks (:value blocks-result))]
+            (if-not (:ok? vector-result)
+              vector-result
+              (let [blocks (ensure-block-uuids (:value vector-result))]
+                {:ok? true
+                 :action {:type :add-block
+                          :repo repo
+                          :graph (core/repo->graph repo)
+                          :target-id (:target-id options)
+                          :target-uuid (some-> (:target-uuid options) string/trim)
+                          :target-page-name (some-> (:target-page-name options) string/trim)
+                          :pos (or (some-> (:pos options) string/trim string/lower-case) "last-child")
+                          :status status
+                          :tags tags
+                          :properties properties
+                          :blocks blocks}}))))))))
+
+(defn execute-add-block
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              target-block-uuid (resolve-add-target cfg action)
+              ref-values (collect-page-refs (:blocks action))
+              {:keys [uuid-refs page-refs id-refs]} (partition-ref-values ref-values)
+              _ (ensure-block-refs-exist! cfg (:repo action) uuid-refs)
+              page-refs' (or (resolve-page-ref-entities cfg (:repo action) page-refs) [])
+              id-refs' (or (resolve-id-ref-entities cfg (:repo action) id-refs) [])
+              refs (into page-refs' id-refs')
+              blocks (if (seq refs)
+                       (normalize-block-title-refs (:blocks action) refs)
+                       (:blocks action))
+              blocks-for-insert (flatten-block-tree blocks)
+              status (:status action)
+              tags (if (contains? action :resolved-tags)
+                     (:resolved-tags action)
+                     (resolve-tags cfg (:repo action) (:tags action)))
+              properties (if (contains? action :resolved-properties)
+                           (:resolved-properties action)
+                           (resolve-properties cfg (:repo action) (:properties action)))
+              remove-properties (if (contains? action :resolved-remove-properties)
+                                  (:resolved-remove-properties action)
+                                  (resolve-property-identifiers cfg (:repo action) (:remove-properties action)
+                                                                {:allow-non-built-in? true}))
+              pos (:pos action)
+              keep-uuid? true
+              opts (case pos
+                     "last-child" {:sibling? false :bottom? true}
+                     "sibling" {:sibling? true}
+                     {:sibling? false})
+              opts (cond-> opts
+                     keep-uuid?
+                     (assoc :keep-uuid? true))
+              block-uuids (->> blocks-for-insert
+                               (map :block/uuid)
+                               (remove nil?)
+                               vec)
+              tag-ids (->> (or tags [])
+                           (map :db/id)
+                           (remove nil?)
+                           distinct
+                           vec)
+              ops (cond-> [[:insert-blocks [blocks-for-insert
+                                            target-block-uuid
+                                            (assoc opts :outliner-op :insert-blocks)]]]
+                    (and (seq block-uuids) (seq remove-properties))
+                    (into (map (fn [property-id]
+                                 [:batch-remove-property [block-uuids property-id]])
+                               remove-properties))
+                    (and status (seq block-uuids))
+                    (conj [:batch-set-property [block-uuids :logseq.property/status status {}]])
+                    (and (seq tag-ids) (seq block-uuids))
+                    (into (map (fn [tag-id]
+                                 [:batch-set-property [block-uuids :block/tags tag-id {}]])
+                               tag-ids))
+                    (and (seq properties) (seq block-uuids))
+                    (into (map (fn [[k v]]
+                                 [:batch-set-property [block-uuids k v {}]])
+                               properties)))
+              apply-result (transport/invoke cfg :thread-api/apply-outliner-ops false [(:repo action) ops {}])
+              created-ids (resolve-created-block-ids cfg (:repo action) blocks-for-insert apply-result)]
+        {:status :ok
+         :data {:result created-ids}})))
diff --git a/src/main/logseq/cli/command/auth.cljs b/src/main/logseq/cli/command/auth.cljs
new file mode 100644
index 0000000000..b557cef619
--- /dev/null
+++ b/src/main/logseq/cli/command/auth.cljs
@@ -0,0 +1,48 @@
+(ns logseq.cli.command.auth
+  "Authentication-related CLI commands."
+  (:require [logseq.cli.auth :as cli-auth]
+            [logseq.cli.command.core :as core]
+            [promesa.core :as p]))
+
+(def entries
+  [(core/command-entry ["login"]
+                       :login
+                       "Authenticate this machine with Logseq cloud"
+                       {})
+   (core/command-entry ["logout"]
+                       :logout
+                       "Remove persisted CLI auth"
+                       {})])
+
+(defn build-action
+  [command]
+  {:ok? true
+   :action {:type command}})
+
+(defn- exception->error
+  [error]
+  (let [data (or (ex-data error) {})
+        code (or (:code data) :exception)]
+    {:status :error
+     :error (merge {:code code
+                    :message (or (ex-message error) (str error))}
+                   (when (seq data) {:context data}))}))
+
+(defn execute
+  [action config]
+  (case (:type action)
+    :login
+    (-> (p/let [data (cli-auth/login! config)]
+          {:status :ok
+           :data data})
+        (p/catch exception->error))
+
+    :logout
+    (-> (p/let [data (cli-auth/logout! config)]
+          {:status :ok
+           :data data})
+        (p/catch exception->error))
+
+    (p/resolved {:status :error
+                 :error {:code :unknown-action
+                         :message "unknown auth action"}})))
diff --git a/src/main/logseq/cli/command/completion.cljs b/src/main/logseq/cli/command/completion.cljs
new file mode 100644
index 0000000000..996aff46e1
--- /dev/null
+++ b/src/main/logseq/cli/command/completion.cljs
@@ -0,0 +1,31 @@
+(ns logseq.cli.command.completion
+  "Shell completion command."
+  (:require [clojure.string :as string]
+            [logseq.cli.command.core :as core]))
+
+(def ^:private completion-spec
+  {:shell {:desc "Shell (zsh, bash)"
+           :validate #{"zsh" "bash"}}})
+
+(def ^:private long-desc
+  (string/join "\n"
+               ["Generate shell completion script for the specified shell."
+                "Outputs a completion script to stdout that can be evaluated"
+                "by your shell to enable tab-completion for logseq commands."
+                ""
+                "Setup for zsh:"
+                "  # Add to ~/.zshrc"
+                "  autoload -Uz compinit && compinit"
+                "  eval \"$(logseq completion zsh)\""
+                ""
+                "Setup for bash:"
+                "  # Add to ~/.bashrc"
+                "  eval \"$(logseq completion bash)\""]))
+
+(def entries
+  [(core/command-entry ["completion"] :completion
+                       "Generate shell completion script"
+                       completion-spec
+                       {:long-desc long-desc
+                        :examples ["logseq completion zsh"
+                                   "logseq completion bash"]})])
diff --git a/src/main/logseq/cli/command/core.cljs b/src/main/logseq/cli/command/core.cljs
new file mode 100644
index 0000000000..20255b0d5a
--- /dev/null
+++ b/src/main/logseq/cli/command/core.cljs
@@ -0,0 +1,296 @@
+(ns logseq.cli.command.core
+  "Shared CLI parsing utilities."
+  (:require [babashka.cli :as cli]
+            [clojure.string :as string]
+            [logseq.cli.output-mode :as output-mode]
+            [logseq.cli.style :as style]
+            [logseq.common.config :as common-config]))
+
+(def ^:private global-spec*
+  {:help {:alias :h
+          :desc "Show help"
+          :coerce :boolean}
+   :version {:desc "Show version"
+             :coerce :boolean}
+   :config {:desc "Path to cli.edn (default <root-dir>/cli.edn)"
+            :complete :file}
+   :graph {:desc "Graph name"
+           :alias :g
+           :complete :graphs}
+   :root-dir {:desc "Path to CLI root dir (default ~/logseq)"
+              :complete :dir}
+   :timeout-ms {:desc "Request timeout in ms (default 10000)"
+                :coerce :long}
+   :output {:desc "Output format. Default: human"
+            :alias :o
+            :validate output-mode/allowed-values}
+   :verbose {:desc "Enable verbose debug logging to stderr"
+             :alias :v
+             :coerce :boolean}
+   :profile {:desc "Enable stage timing profile output to stderr"
+             :coerce :boolean}})
+
+(defn global-spec
+  []
+  global-spec*)
+
+(defn- merge-spec
+  [spec]
+  (merge global-spec* (or spec {})))
+
+(defn command-entry
+  ([cmds command desc spec]
+   (command-entry cmds command desc spec nil))
+  ([cmds command desc spec {:keys [long-desc examples]}]
+   (let [spec* (merge-spec spec)]
+     {:cmds cmds
+      :command command
+      :desc desc
+      :long-desc long-desc
+      :examples examples
+      :spec spec*
+      :restrict true
+      :fn (fn [{:keys [opts args]}]
+            {:command command
+             :cmds cmds
+             :spec spec*
+             :long-desc long-desc
+             :examples examples
+             :opts opts
+             :args args})})))
+
+(defn- command-usage
+  [cmds spec]
+  (let [base (string/join " " cmds)
+        has-options? (seq spec)]
+    (cond-> base
+      has-options? (str " [options]"))))
+
+(defn- command-label
+  [cmds]
+  (string/join " " cmds))
+
+(defn- format-commands
+  [table]
+  (let [rows (->> table
+                  (filter (comp seq :cmds))
+                  (map (fn [{:keys [cmds desc]}]
+                         (let [command (command-label cmds)]
+                           {:command command
+                            :command-styled (style/bold command)
+                            :desc desc}))))
+        width (apply max 0 (map (comp count :command) rows))]
+    (->> rows
+         (map (fn [{:keys [command command-styled desc]}]
+                (let [padding (apply str (repeat (- width (count command)) " "))]
+                  (cond-> (str "  " command-styled padding)
+                    (seq desc) (str "  " desc)))))
+         (string/join "\n"))))
+
+(defn- format-opts
+  [spec]
+  (style/bold-options (cli/format-opts {:spec (into (sorted-map) spec)})))
+
+(defn- cmds-prefix?
+  [prefix cmds]
+  (and (<= (count prefix) (count cmds))
+       (= prefix (subvec cmds 0 (count prefix)))))
+
+(defn group-summary
+  [group table]
+  (let [group-cmds (if (string? group) [group] (vec group))
+        group-label (string/join " " group-cmds)
+        group-table (filter #(cmds-prefix? group-cmds (:cmds %)) table)]
+    (string/join "\n"
+                 [(str "Usage: logseq " group-label " <subcommand> [options]")
+                  ""
+                  (str (style/bold "Subcommands") ":")
+                  (format-commands group-table)
+                  ""
+                  (str "Global " (style/bold "options") ":")
+                  (format-opts global-spec*)
+                  ""
+                  (str "Command " (style/bold "options") ":")
+                  (str "  See `logseq " group-label " <subcommand> --help`")])))
+
+(defn top-level-summary
+  [table]
+  (let [groups [{:title "Graph Inspect and Edit"
+                 :commands #{"list" "upsert" "remove" "query" "search" "show"}}
+                {:title "Graph Management"
+                 :commands #{"graph" "server" "doctor" "sync"}}
+                {:title "Authentication"
+                 :commands #{"login" "logout"}}
+                {:title "Utilities"
+                 :commands #{"completion" "debug" "example" "skill"}
+                 :top-level-only? true
+                 :desc-overrides {"debug" "Pull raw entity data for debugging"
+                                  "example" "Show command examples"
+                                  "skill" "Show/install built-in logseq-cli skill"}}]
+        to-top-level-entries (fn [entries commands desc-overrides]
+                               (->> commands
+                                    sort
+                                    (keep (fn [command]
+                                            (let [command-entries (filter #(= command (first (:cmds %))) entries)
+                                                  leaf-entry (first (filter #(= 1 (count (:cmds %)))
+                                                                            command-entries))
+                                                  desc (or (get desc-overrides command)
+                                                           (:desc leaf-entry)
+                                                           (:desc (first command-entries)))]
+                                              (when (seq command-entries)
+                                                {:cmds [command]
+                                                 :desc desc}))))))
+        render-group (fn [{:keys [title commands top-level-only? desc-overrides]}]
+                       (let [entries (filter #(contains? commands (first (:cmds %))) table)
+                             entries* (if top-level-only?
+                                        (to-top-level-entries entries commands (or desc-overrides {}))
+                                        entries)]
+                         (string/join "\n" [title (format-commands entries*)])))]
+    (string/join "\n"
+                 ["Usage: logseq <command> [options]"
+                  ""
+                  (str (style/bold "Commands") ":")
+                  (string/join "\n\n" (map render-group groups))
+                  ""
+                  (str "Global " (style/bold "options") ":")
+                  (format-opts global-spec*)
+                  ""
+                  (str "Command " (style/bold "options") ":")
+                  "  See `logseq <command> --help`"])))
+
+(defn- format-examples
+  [examples]
+  (->> examples
+       (keep (fn [example]
+               (let [line (some-> example str string/trim)]
+                 (when (seq line)
+                   line))))
+       (take 5)
+       (map #(str "  " %))
+       (string/join "\n")))
+
+(defn command-summary
+  [{:keys [cmds spec long-desc examples]}]
+  (let [command-spec (apply dissoc spec (keys global-spec*))
+        formatted-examples (format-examples examples)]
+    (string/join "\n"
+                 (cond-> [(str "Usage: logseq " (command-usage cmds spec))]
+                   (seq long-desc) (conj "" long-desc)
+                   true (conj ""
+                              (str "Global " (style/bold "options") ":")
+                              (format-opts global-spec*)
+                              ""
+                              (str "Command " (style/bold "options") ":")
+                              (format-opts command-spec))
+                   (seq formatted-examples) (conj ""
+                                                  (str (style/bold "Examples") ":")
+                                                  formatted-examples)))))
+
+(defn normalize-opts
+  [opts]
+  (cond-> opts
+    (:config opts) (-> (assoc :config-path (:config opts))
+                       (dissoc :config))))
+
+(defn ok-result
+  [command opts args summary]
+  {:ok? true
+   :command command
+   :options (normalize-opts opts)
+   :args (vec args)
+   :summary summary})
+
+(defn help-result
+  [summary]
+  {:ok? false
+   :help? true
+   :summary summary})
+
+(defn invalid-options-result
+  [summary message]
+  {:ok? false
+   :error {:code :invalid-options
+           :message (style/bold-options message)}
+   :summary summary})
+
+(defn unknown-command-result
+  [summary message]
+  {:ok? false
+   :error {:code :unknown-command
+           :message message}
+   :summary summary})
+
+(def ^:private global-aliases
+  (->> global-spec*
+       (keep (fn [[k {:keys [alias]}]]
+               (when alias
+                 [alias k])))
+       (into {})))
+
+(def ^:private global-flag-options
+  (->> global-spec*
+       (keep (fn [[k {:keys [coerce]}]]
+               (when (= coerce :boolean) k)))
+       (set)))
+
+(defn- global-opt-key
+  [token]
+  (cond
+    (string/starts-with? token "--")
+    (keyword (subs token 2))
+
+    (and (string/starts-with? token "-")
+         (= 2 (count token)))
+    (get global-aliases (keyword (subs token 1)))
+
+    :else nil))
+
+(defn- valid-leading-global-value?
+  [opt-key value]
+  (case opt-key
+    :output (contains? output-mode/allowed-values value)
+    true))
+
+(defn parse-leading-global-opts
+  [args]
+  (loop [remaining args
+         opts {}]
+    (if (empty? remaining)
+      {:opts opts :args []}
+      (let [token (first remaining)]
+        (if-let [opt-key (global-opt-key token)]
+          (if (contains? global-flag-options opt-key)
+            (recur (rest remaining) (assoc opts opt-key true))
+            (if-let [value (second remaining)]
+              (if (valid-leading-global-value? opt-key value)
+                (recur (drop 2 remaining) (assoc opts opt-key value))
+                {:opts opts :args remaining})
+              {:opts opts :args (rest remaining)}))
+          {:opts opts :args remaining})))))
+
+(defn cli-error->result
+  [summary {:keys [msg]}]
+  (invalid-options-result summary (or msg "invalid options")))
+
+(defn graph->repo
+  [graph]
+  (some-> graph
+          string/trim
+          common-config/canonicalize-db-version-repo))
+
+(defn repo->graph
+  [repo]
+  (when (seq repo)
+    (common-config/strip-leading-db-version-prefix repo)))
+
+(defn resolve-repo
+  [graph]
+  (let [graph (some-> graph string/trim)]
+    (when (seq graph)
+      (graph->repo graph))))
+
+(defn pick-graph
+  [options _command-args config]
+  (or (:graph options)
+      (:graph config)
+      (repo->graph (:repo config))))
diff --git a/src/main/logseq/cli/command/debug.cljs b/src/main/logseq/cli/command/debug.cljs
new file mode 100644
index 0000000000..d6f3d47997
--- /dev/null
+++ b/src/main/logseq/cli/command/debug.cljs
@@ -0,0 +1,97 @@
+(ns logseq.cli.command.debug
+  "Debug-related CLI commands."
+  (:require [clojure.string :as string]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.util :as common-util]
+            [promesa.core :as p]))
+
+(def ^:private debug-pull-spec
+  {:id {:desc "Entity db/id"
+        :coerce :long}
+   :uuid {:desc "Entity UUID"
+          :validate {:pred (comp parse-uuid str)
+                     :ex-msg (constantly "Option uuid must be a valid UUID string")}}
+   :ident {:desc "Entity db/ident as strict EDN keyword"}})
+
+(def entries
+  [(core/command-entry ["debug" "pull"]
+                       :debug-pull
+                       "Pull raw entity by id, uuid, or ident"
+                       debug-pull-spec
+                       {:examples ["logseq debug pull --graph my-graph --id 123"
+                                   "logseq debug pull --graph my-graph --uuid 11111111-1111-1111-1111-111111111111"
+                                   "logseq debug pull --graph my-graph --ident :logseq.class/Tag"]})])
+
+(defn- parse-ident-option
+  [value]
+  (let [text (some-> value str string/trim)
+        parsed (when (seq text)
+                 (common-util/safe-read-string {:log-error? false} text))]
+    (if (keyword? parsed)
+      {:ok? true :value parsed}
+      {:ok? false
+       :error {:code :invalid-options
+               :message "ident must be a strict EDN keyword (e.g. :logseq.class/Tag)"}})))
+
+(defn invalid-options?
+  [opts]
+  (let [selectors (filter some? [(:id opts)
+                                 (some-> (:uuid opts) string/trim seq)
+                                 (some-> (:ident opts) str string/trim seq)])
+        ident-text (some-> (:ident opts) str string/trim)
+        ident-result (when (seq ident-text)
+                       (parse-ident-option ident-text))]
+    (cond
+      (empty? selectors)
+      "exactly one of --id, --uuid, or --ident is required"
+
+      (> (count selectors) 1)
+      "only one of --id, --uuid, or --ident is allowed"
+
+      (and ident-result (not (:ok? ident-result)))
+      (get-in ident-result [:error :message])
+
+      :else
+      nil)))
+
+(defn build-action
+  [options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for debug pull"}}
+    (let [uuid-text (some-> (:uuid options) string/trim)
+          ident-text (some-> (:ident options) str string/trim)
+          ident-result (when (seq ident-text)
+                         (parse-ident-option ident-text))]
+      (cond
+        (and ident-result (not (:ok? ident-result)))
+        ident-result
+
+        :else
+        {:ok? true
+         :action {:type :debug-pull
+                  :repo repo
+                  :graph (core/repo->graph repo)
+                  :lookup (cond
+                            (some? (:id options)) (:id options)
+                            (seq uuid-text) [:block/uuid (uuid uuid-text)]
+                            (seq ident-text) [:db/ident (:value ident-result)]
+                            :else nil)
+                  :selector '[*]}}))))
+
+(defn execute-debug-pull
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              entity (transport/invoke cfg :thread-api/pull false
+                                       [(:repo action) (:selector action) (:lookup action)])]
+        (if (some? entity)
+          {:status :ok
+           :data {:entity entity
+                  :lookup (:lookup action)
+                  :selector (:selector action)}}
+          {:status :error
+           :error {:code :entity-not-found
+                   :message "entity not found"}}))))
diff --git a/src/main/logseq/cli/command/doctor.cljs b/src/main/logseq/cli/command/doctor.cljs
new file mode 100644
index 0000000000..babd89ed18
--- /dev/null
+++ b/src/main/logseq/cli/command/doctor.cljs
@@ -0,0 +1,189 @@
+(ns logseq.cli.command.doctor
+  "Doctor command for CLI runtime diagnostics."
+  (:require ["fs" :as fs]
+            [clojure.string :as string]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.humanize :as cli-humanize]
+            [logseq.cli.root-dir :as root-dir]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.version :as version]
+            [promesa.core :as p]))
+
+(def entries
+  [(core/command-entry ["doctor"]
+                       :doctor
+                       "Run runtime diagnostics"
+                       {:dev-script {:desc "Check static/db-worker-node.js instead of bundled dist runtime"
+                                     :coerce :boolean}}
+                       {:examples ["logseq doctor --dev-script"]})])
+
+(defn build-action
+  ([]
+   (build-action {}))
+  ([options]
+   {:ok? true
+    :action (cond-> {:type :doctor}
+              (:dev-script options)
+              (assoc :script-path (cli-server/db-worker-dev-script-path)))}))
+
+(defn- doctor-error
+  [checks code message]
+  {:status :error
+   :error {:code code
+           :message message
+           :checks checks}
+   :data {:status :error
+          :checks checks}})
+
+(defn check-db-worker-script
+  [action]
+  (let [path (or (:script-path action)
+                 (cli-server/db-worker-runtime-script-path))]
+    (try
+      (cond
+        (not (fs/existsSync path))
+        {:ok? false
+         :check {:id :db-worker-script
+                 :status :error
+                 :code :doctor-script-missing
+                 :path path
+                 :message (str "db-worker script is missing: " path)}}
+
+        :else
+        (let [stat (fs/statSync path)]
+          (if-not (.isFile stat)
+            {:ok? false
+             :check {:id :db-worker-script
+                     :status :error
+                     :code :doctor-script-unreadable
+                     :path path
+                     :message (str "db-worker script path is not a file: " path)}}
+            (let [constants (.-constants fs)]
+              (fs/accessSync path (.-R_OK constants))
+              {:ok? true
+               :check {:id :db-worker-script
+                       :status :ok
+                       :path path
+                       :message (str "Found readable file: " path)}}))))
+      (catch :default e
+        {:ok? false
+         :check {:id :db-worker-script
+                 :status :error
+                 :code :doctor-script-unreadable
+                 :path path
+                 :cause (.-code e)
+                 :message (str "db-worker script is not readable: " path)}}))))
+
+(defn- check-root-dir
+  [config]
+  (try
+    (let [path (root-dir/ensure-root-dir! (:root-dir config))]
+      {:ok? true
+       :check {:id :root-dir
+               :status :ok
+               :path path
+               :message (str "Read/write access confirmed: " path)}})
+    (catch :default e
+      (let [data (ex-data e)
+            code (or (:code data) :root-dir-permission)
+            path (or (:path data) (:root-dir config))
+            message (or (.-message e)
+                        "root-dir check failed")]
+        {:ok? false
+         :check {:id :root-dir
+                 :status :error
+                 :code code
+                 :path path
+                 :cause (:cause data)
+                 :message message}}))))
+
+(defn- check-running-servers
+  [config]
+  (-> (p/let [servers (or (cli-server/list-servers config) [])
+              starting (vec (filter #(= :starting (:status %)) servers))]
+        (if (seq starting)
+          {:ok? true
+           :warning? true
+           :servers servers
+           :check {:id :running-servers
+                   :status :warning
+                   :code :doctor-server-not-ready
+                   :servers starting
+                   :message (str (cli-humanize/format-count-with-noun (count starting) "server")
+                                 " still starting: "
+                                 (string/join ", " (map :repo starting)))}}
+          {:ok? true
+           :warning? false
+           :servers servers
+           :check {:id :running-servers
+                   :status :ok
+                   :servers servers
+                   :message (if (seq servers)
+                              "All running servers are ready"
+                              "No running db-worker servers detected")}}))
+      (p/catch (fn [e]
+                 {:ok? false
+                  :check {:id :running-servers
+                          :status :error
+                          :code :doctor-server-check-failed
+                          :message (or (.-message e)
+                                       "running server check failed")}}))))
+
+(defn- check-server-revision-mismatch
+  [cli-revision servers]
+  (let [revision-mismatch (cli-server/compute-revision-mismatches cli-revision servers)
+        mismatch-servers (mapv (fn [{:keys [repo revision]}]
+                                 {:repo repo
+                                  :graph (core/repo->graph repo)
+                                  :revision revision})
+                               (or (:servers revision-mismatch) []))
+        mismatch-count (count mismatch-servers)]
+    (if (pos? mismatch-count)
+      {:ok? true
+       :warning? true
+       :check {:id :server-revision-mismatch
+               :status :warning
+               :code :doctor-server-revision-mismatch
+               :cli-revision cli-revision
+               :servers mismatch-servers
+               :message (str (cli-humanize/format-count-with-noun mismatch-count "server")
+                             " "
+                             (if (= 1 mismatch-count) "uses" "use")
+                             " a different revision than this CLI")}}
+      {:ok? true
+       :warning? false
+       :check {:id :server-revision-mismatch
+               :status :ok
+               :cli-revision cli-revision
+               :servers []
+               :message "All discovered servers match this CLI revision"}})))
+
+(defn execute-doctor
+  [action config]
+  (p/let [script-check (check-db-worker-script action)]
+    (if-not (:ok? script-check)
+      (let [check (:check script-check)]
+        (doctor-error [check] (:code check) (:message check)))
+      (let [checks [(:check script-check)]
+            root-dir-check (check-root-dir config)]
+        (if-not (:ok? root-dir-check)
+          (let [check (:check root-dir-check)
+                checks (conj checks check)]
+            (doctor-error checks (:code check) (:message check)))
+          (p/let [server-check (check-running-servers config)]
+            (if-not (:ok? server-check)
+              (let [checks (conj checks (:check root-dir-check) (:check server-check))
+                    check (:check server-check)]
+                (doctor-error checks (:code check) (:message check)))
+              (let [revision-check (check-server-revision-mismatch (version/revision)
+                                                                   (:servers server-check))
+                    checks (conj checks
+                                 (:check root-dir-check)
+                                 (:check server-check)
+                                 (:check revision-check))]
+                {:status :ok
+                 :data {:status (if (or (:warning? server-check)
+                                        (:warning? revision-check))
+                                  :warning
+                                  :ok)
+                        :checks checks}}))))))))
diff --git a/src/main/logseq/cli/command/example.cljs b/src/main/logseq/cli/command/example.cljs
new file mode 100644
index 0000000000..f0a5ceb90d
--- /dev/null
+++ b/src/main/logseq/cli/command/example.cljs
@@ -0,0 +1,135 @@
+(ns logseq.cli.command.example
+  "Example command generation and execution."
+  (:require [clojure.string :as string]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.humanize :as cli-humanize]
+            [promesa.core :as p]))
+
+(def ^:private phase1-groups
+  ["list" "upsert" "remove" "query" "search" "show"])
+
+(defn- command-path->label
+  [cmds]
+  (string/join " " cmds))
+
+(defn- normalize-example-lines
+  [examples]
+  (->> (or examples [])
+       (keep (fn [example]
+               (let [line (some-> example str string/trim)]
+                 (when (seq line)
+                   line))))
+       vec))
+
+(defn phase1-target-entries
+  [base-table]
+  (->> base-table
+       (filter (fn [entry]
+                 (contains? (set phase1-groups)
+                            (first (:cmds entry)))))
+       vec))
+
+(defn- selector-definitions
+  [base-table]
+  (let [targets (phase1-target-entries base-table)
+        by-group (group-by (comp first :cmds) targets)
+        prefix-defs (->> phase1-groups
+                         (keep (fn [group]
+                                 (when-let [matches (seq (get by-group group))]
+                                   {:selector [group]
+                                    :matches (vec matches)}))))
+        prefix-selector-set (set (map :selector prefix-defs))
+        exact-defs (->> targets
+                        (mapv (fn [entry]
+                                {:selector (:cmds entry)
+                                 :matches [entry]}))
+                        (remove (fn [{:keys [selector]}]
+                                  (contains? prefix-selector-set selector))))]
+    (vec (concat prefix-defs exact-defs))))
+
+(defn- selector-entry
+  [{:keys [selector matches]}]
+  (let [selector-label (command-path->label selector)
+        matched-labels (mapv (comp command-path->label :cmds) matches)
+        matched-count (count matched-labels)
+        command-cmds (into ["example"] selector)
+        examples (->> matches
+                      (mapcat (comp normalize-example-lines :examples))
+                      vec)
+        desc (if (> matched-count 1)
+               (str "Show examples for " selector-label " subcommands")
+               (str "Show examples for " selector-label))]
+    (core/command-entry command-cmds :example desc {}
+                        {:examples examples
+                         :long-desc (str "Show runnable command examples for selector `"
+                                         selector-label
+                                         "`." )})))
+
+(defn build-example-entries
+  [base-table]
+  (->> (selector-definitions base-table)
+       (mapv selector-entry)))
+
+(defn resolve-selector
+  [base-table selector-cmds]
+  (let [targets (phase1-target-entries base-table)
+        selector-cmds (vec selector-cmds)
+        prefix? (= 1 (count selector-cmds))
+        matches (if prefix?
+                  (filterv #(= (first selector-cmds)
+                               (first (:cmds %)))
+                           targets)
+                  (filterv #(= selector-cmds (:cmds %))
+                           targets))
+        missing-example-commands (->> matches
+                                      (filter #(empty? (normalize-example-lines (:examples %))))
+                                      (mapv (comp command-path->label :cmds)))
+        matched-commands (mapv (comp command-path->label :cmds) matches)
+        examples (->> matches
+                      (mapcat (comp normalize-example-lines :examples))
+                      vec)
+        selector (command-path->label selector-cmds)]
+    {:selector selector
+     :matched-commands matched-commands
+     :examples examples
+     :missing-example-commands missing-example-commands}))
+
+(defn build-action
+  [base-table cmds]
+  (let [selector-cmds (vec (rest (or cmds [])))
+        {:keys [selector matched-commands examples missing-example-commands]}
+        (resolve-selector base-table selector-cmds)]
+    (cond
+      (empty? selector-cmds)
+      {:ok? false
+       :error {:code :missing-example-selector
+               :message "example selector is required"}}
+
+      (empty? matched-commands)
+      {:ok? false
+       :error {:code :unknown-command
+               :message (str "unknown example selector: " selector)}}
+
+      (seq missing-example-commands)
+      {:ok? false
+       :error {:code :missing-examples
+               :message (str "missing examples metadata for: "
+                             (string/join ", " missing-example-commands))}}
+
+      :else
+      {:ok? true
+       :action {:type :example
+                :selector selector
+                :matched-commands matched-commands
+                :examples examples
+                :message (str "Found "
+                              (cli-humanize/format-count (count examples))
+                              " "
+                              (cli-humanize/pluralize-noun (count examples) "example")
+                              " for selector "
+                              selector)}})))
+
+(defn execute-example
+  [action _config]
+  (p/resolved {:status :ok
+               :data (select-keys action [:selector :matched-commands :examples :message])}))
diff --git a/src/main/logseq/cli/command/graph.cljs b/src/main/logseq/cli/command/graph.cljs
new file mode 100644
index 0000000000..36ac594787
--- /dev/null
+++ b/src/main/logseq/cli/command/graph.cljs
@@ -0,0 +1,562 @@
+(ns logseq.cli.command.graph
+  "Graph-related CLI commands."
+  (:require ["fs" :as fs]
+            ["path" :as node-path]
+            [cljs.pprint :as pprint]
+            [clojure.string :as string]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.common :as cli-common]
+            [logseq.cli.config :as cli-config]
+            [logseq.cli.humanize :as cli-humanize]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.graph :as common-graph]
+            [logseq.common.graph-dir :as graph-dir]
+            [promesa.core :as p]))
+
+(def ^:private graph-export-spec
+  {:type {:desc "Export type"
+          :alias :t
+          :validate #{"edn" "sqlite"}}
+   :file {:desc "Export file path"
+          :coerce common-graph/expand-home
+          :complete :file}})
+
+(def ^:private graph-import-spec
+  {:type {:desc "Import type"
+          :alias :t
+          :validate #{"edn" "sqlite"}}
+   :input {:desc "Input path"
+           :coerce common-graph/expand-home
+           :complete :file}})
+
+(def ^:private graph-validate-spec
+  {:fix {:desc "Attempt to fix validation errors"
+         :alias :f
+         :coerce :boolean
+         :default false}})
+
+(def ^:private graph-backup-create-spec
+  {:name {:desc "Optional backup label"}})
+
+(def ^:private graph-backup-restore-spec
+  {:src {:desc "Source backup name"}
+   :dst {:desc "Destination graph name"}})
+
+(def ^:private graph-backup-remove-spec
+  {:src {:desc "Source backup name"}})
+
+(def ^:private backup-root-dir-name "backup")
+(def ^:private backup-db-file-name "db.sqlite")
+
+(def entries
+  [(core/command-entry ["graph" "list"] :graph-list "List graphs" {})
+   (core/command-entry ["graph" "create"] :graph-create "Create graph" {}
+                       {:examples ["logseq graph create --graph my-graph"]})
+   (core/command-entry ["graph" "switch"] :graph-switch "Switch current graph" {}
+                       {:examples ["logseq graph switch --graph my-graph"]})
+   (core/command-entry ["graph" "remove"] :graph-remove "Remove graph" {}
+                       {:examples ["logseq graph remove --graph my-graph"]})
+   (core/command-entry ["graph" "validate"] :graph-validate "Validate graph" graph-validate-spec
+                       {:examples ["logseq graph validate --graph my-graph"
+                                   "logseq graph validate --graph my-graph --fix"]})
+   (core/command-entry ["graph" "info"] :graph-info "Graph metadata" {}
+                       {:examples ["logseq graph info --graph my-graph"]})
+   (core/command-entry ["graph" "export"] :graph-export "Export graph" graph-export-spec
+                       {:examples ["logseq graph export --graph my-graph --type edn --file /tmp/my-graph.edn"]})
+   (core/command-entry ["graph" "import"] :graph-import "Import graph" graph-import-spec
+                       {:examples ["logseq graph import --graph my-graph --type edn --input /tmp/my-graph.edn"]})
+   (core/command-entry ["graph" "backup" "list"] :graph-backup-list "List graph backups" {})
+   (core/command-entry ["graph" "backup" "create"] :graph-backup-create "Create graph backup" graph-backup-create-spec
+                       {:examples ["logseq graph backup create --graph my-graph"
+                                   "logseq graph backup create --graph my-graph --name nightly"]})
+   (core/command-entry ["graph" "backup" "restore"] :graph-backup-restore "Restore graph backup" graph-backup-restore-spec
+                       {:examples ["logseq graph backup restore --src my-graph-nightly --dst my-graph-restore"]})
+   (core/command-entry ["graph" "backup" "remove"] :graph-backup-remove "Remove graph backup" graph-backup-remove-spec
+                       {:examples ["logseq graph backup remove --src my-graph-nightly"]})])
+
+(def ^:private graph-info-kv-query
+  '[:find ?ident ?value
+    :where
+    [?e :db/ident ?ident]
+    [(namespace ?ident) ?ns]
+    [(= "logseq.kv" ?ns)]
+    [?e :kv/value ?value]])
+
+(defn normalize-import-export-type
+  [value]
+  (some-> value string/lower-case string/trim))
+
+(defn- missing-graph-error
+  []
+  {:ok? false
+   :error {:code :missing-graph
+           :message "graph name is required"}})
+
+(defn- pad2
+  [value]
+  (if (< value 10)
+    (str "0" value)
+    (str value)))
+
+(defn- utc-timestamp
+  []
+  (let [now (js/Date.)]
+    (str (.getUTCFullYear now)
+         (pad2 (inc (.getUTCMonth now)))
+         (pad2 (.getUTCDate now))
+         "T"
+         (pad2 (.getUTCHours now))
+         (pad2 (.getUTCMinutes now))
+         (pad2 (.getUTCSeconds now))
+         "Z")))
+
+(defn- trimmed-option
+  [value]
+  (some-> value str string/trim not-empty))
+
+(defn build-backup-list-action
+  [repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for backup list"}}
+    {:ok? true
+     :action {:type :graph-backup-list
+              :command :graph-backup-list
+              :repo repo
+              :graph (core/repo->graph repo)}}))
+
+(defn build-backup-create-action
+  [repo name]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for backup create"}}
+    (let [graph (core/repo->graph repo)
+          name-part (trimmed-option name)
+          backup-name (if (seq name-part)
+                        (str graph "-" name-part "-" (utc-timestamp))
+                        (str graph "-" (utc-timestamp)))]
+      {:ok? true
+       :action {:type :graph-backup-create
+                :command :graph-backup-create
+                :repo repo
+                :graph graph
+                :backup-name backup-name}})))
+
+(defn build-backup-restore-action
+  [source-repo src dst]
+  (let [src (trimmed-option src)
+        dst (trimmed-option dst)
+        destination-repo (core/resolve-repo dst)]
+    (cond
+      (not (seq source-repo))
+      {:ok? false
+       :error {:code :missing-repo
+               :message "repo is required for backup restore"}}
+
+      (not (seq destination-repo))
+      {:ok? false
+       :error {:code :missing-dst
+               :message "destination graph name is required"}}
+
+      :else
+      {:ok? true
+       :action {:type :graph-backup-restore
+                :command :graph-backup-restore
+                :repo destination-repo
+                :graph (core/repo->graph destination-repo)
+                :source-repo source-repo
+                :source-graph (core/repo->graph source-repo)
+                :src src
+                :dst dst
+                :allow-missing-graph true
+                :require-missing-graph true}})))
+
+(defn build-backup-remove-action
+  [repo src]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for backup remove"}}
+    {:ok? true
+     :action {:type :graph-backup-remove
+              :command :graph-backup-remove
+              :repo repo
+              :graph (core/repo->graph repo)
+              :src (trimmed-option src)}}))
+
+(defn build-graph-action
+  [command graph repo options]
+  (case command
+    :graph-list
+    {:ok? true
+     :action {:type :graph-list
+              :command :graph-list}}
+
+    :graph-create
+    (if-not (seq graph)
+      (missing-graph-error)
+      {:ok? true
+       :action {:type :invoke
+                :command :graph-create
+                :method :thread-api/create-or-open-db
+                :direct-pass? false
+                :args [repo {}]
+                :repo repo
+                :graph (core/repo->graph repo)
+                :allow-missing-graph true
+                :persist-repo (core/repo->graph repo)}})
+
+    :graph-switch
+    (if-not (seq graph)
+      (missing-graph-error)
+      {:ok? true
+       :action {:type :graph-switch
+                :command :graph-switch
+                :repo repo
+                :graph (core/repo->graph repo)}})
+
+    :graph-remove
+    (if-not (seq graph)
+      (missing-graph-error)
+      {:ok? true
+       :action {:type :graph-remove
+                :command :graph-remove
+                :repo repo
+                :graph (core/repo->graph repo)}})
+
+    :graph-validate
+    (if-not (seq repo)
+      (missing-graph-error)
+      {:ok? true
+       :action {:type :invoke
+                :command :graph-validate
+                :method :thread-api/validate-db
+                :direct-pass? false
+                :args [repo options]
+                :repo repo
+                :graph (core/repo->graph repo)}})
+
+    :graph-info
+    (if-not (seq repo)
+      (missing-graph-error)
+      {:ok? true
+       :action {:type :graph-info
+                :command :graph-info
+                :repo repo
+                :graph (core/repo->graph repo)}})))
+
+(defn build-export-action
+  [repo export-type file]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for export"}}
+    {:ok? true
+     :action {:type :graph-export
+              :repo repo
+              :graph (core/repo->graph repo)
+              :export-type export-type
+              :file file}}))
+
+(defn build-import-action
+  [repo import-type input]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for import"}}
+    {:ok? true
+     :action {:type :graph-import
+              :repo repo
+              :graph (core/repo->graph repo)
+              :import-type import-type
+              :input input
+              :allow-missing-graph true
+              :require-missing-graph (= import-type "sqlite")}}))
+
+(defn- graph-item->graph-name
+  [item]
+  (case (:kind item)
+    :canonical (:graph-name item)
+    :legacy (or (:legacy-graph-name item)
+                (:legacy-dir item))
+    :legacy-undecodable (:legacy-dir item)
+    nil))
+
+(defn- backup-root-path
+  [config repo]
+  (when-let [graph-dir-name (graph-dir/repo->encoded-graph-dir-name repo)]
+    (node-path/join (cli-server/graphs-dir config)
+                    graph-dir-name
+                    backup-root-dir-name)))
+
+(defn- backup-dir-name
+  [backup-name]
+  (graph-dir/graph-dir-key->encoded-dir-name backup-name))
+
+(defn- backup-dir-path
+  [config repo backup-name]
+  (some->> (backup-dir-name backup-name)
+           (node-path/join (backup-root-path config repo))))
+
+(defn- backup-db-path
+  [config repo backup-name]
+  (some-> (backup-dir-path config repo backup-name)
+          (node-path/join backup-db-file-name)))
+
+(defn- backup-metadata
+  [^js dirent root-path]
+  (let [dir-name (.-name dirent)
+        backup-name (graph-dir/decode-graph-dir-name dir-name)
+        db-path (node-path/join root-path dir-name backup-db-file-name)]
+    (when (and (seq backup-name)
+               (fs/existsSync db-path))
+      (let [stat (fs/statSync db-path)]
+        (when (.isFile stat)
+          {:name backup-name
+           :created-at (.-mtimeMs stat)
+           :size-bytes (.-size stat)})))))
+
+(defn- list-backups
+  [config repo]
+  (if-let [root-path (backup-root-path config repo)]
+    (let [dirents (if (fs/existsSync root-path)
+                    (fs/readdirSync root-path #js {:withFileTypes true})
+                    #js [])]
+      (->> dirents
+           (filter #(.isDirectory ^js %))
+           (keep #(backup-metadata % root-path))
+           (sort-by (juxt :name :created-at))
+           vec))
+    []))
+
+(defn- next-backup-target
+  [config repo base-name]
+  (loop [suffix 0]
+    (let [backup-name (if (zero? suffix)
+                        base-name
+                        (str base-name "-" suffix))
+          dir-path (backup-dir-path config repo backup-name)]
+      (if (and (seq dir-path)
+               (fs/existsSync dir-path))
+        (recur (inc suffix))
+        {:backup-name backup-name
+         :dir-path dir-path
+         :db-path (when (seq dir-path)
+                    (node-path/join dir-path backup-db-file-name))}))))
+
+(defn execute-graph-list
+  [_action config]
+  (let [graph-items (vec (cli-server/list-graph-items config))
+        graphs (->> graph-items
+                    (keep graph-item->graph-name)
+                    (mapv core/repo->graph))
+        legacy-count (->> graph-items
+                          (filter (fn [{:keys [kind]}]
+                                    (contains? #{:legacy :legacy-undecodable} kind)))
+                          count)]
+    (cond-> {:status :ok
+             :data {:graphs graphs
+                    :graph-items graph-items}}
+      (pos? legacy-count) (assoc :human {:graph-list {:legacy-count legacy-count}}))))
+
+(defn execute-graph-backup-list
+  [action config]
+  {:status :ok
+   :data {:backups (list-backups config (:repo action))}})
+
+(defn execute-graph-backup-create
+  [action config]
+  (p/let [cfg (cli-server/ensure-server! config (:repo action))
+          {:keys [backup-name dir-path db-path]} (next-backup-target config (:repo action) (:backup-name action))
+          _ (when-not (seq dir-path)
+              (throw (ex-info "invalid backup target path"
+                              {:code :invalid-backup-path
+                               :backup-name backup-name})))
+          _ (fs/mkdirSync dir-path #js {:recursive true})
+          _ (transport/invoke cfg
+                              :thread-api/backup-db-sqlite
+                              true
+                              [(:repo action) db-path])]
+    {:status :ok
+     :data {:backup-name backup-name
+            :path db-path
+            :message (str "Created backup " backup-name)}}))
+
+(declare execute-graph-import)
+
+(defn execute-graph-backup-restore
+  [action config]
+  (let [src-path (backup-db-path config (:source-repo action) (:src action))]
+    (if-not (and (seq src-path)
+                 (fs/existsSync src-path))
+      {:status :error
+       :error {:code :backup-not-found
+               :message (str "backup not found: " (:src action))}}
+      (execute-graph-import (assoc action
+                                   :import-type "sqlite"
+                                   :input src-path)
+                            config))))
+
+(defn execute-graph-backup-remove
+  [action config]
+  (let [dir-path (backup-dir-path config (:repo action) (:src action))]
+    (if-not (and (seq dir-path)
+                 (fs/existsSync dir-path))
+      {:status :error
+       :error {:code :backup-not-found
+               :message (str "backup not found: " (:src action))}}
+      (do
+        (fs/rmSync dir-path #js {:recursive true :force true})
+        {:status :ok
+         :data {:message (str "Removed backup " (:src action))}}))))
+
+(defn- format-validation-errors
+  [errors]
+  (let [error-count (count errors)]
+    (str "Graph invalid. Found "
+         (cli-humanize/format-count error-count)
+         " "
+         (cli-humanize/pluralize-noun error-count "entity")
+         " with errors:\n"
+         (with-out-str (pprint/pprint errors)))))
+
+(defn- graph-validate-result
+  [result]
+  (if (seq (:errors result))
+    {:status :error
+     :error {:code :graph-validation-failed
+             :message (format-validation-errors (:errors result))}
+     :data {:errors (:errors result)}}
+    {:status :ok :data {:result result}}))
+
+(defn execute-invoke
+  [action config]
+  (p/let [cfg (if-let [repo (:repo action)]
+                (cli-server/ensure-server! config repo)
+                (p/resolved config))
+          result (transport/invoke cfg
+                                   (:method action)
+                                   (:direct-pass? action)
+                                   (:args action))]
+    (when-let [repo (:persist-repo action)]
+      (cli-config/update-config! config {:graph repo}))
+    (let [write (:write action)]
+      (cond
+        (= :graph-validate (:command action))
+        (graph-validate-result result)
+
+        write
+        (let [{:keys [format path]} write]
+          (transport/write-output {:format format :path path :data result})
+          {:status :ok
+           :data {:message (str "wrote " path)}})
+
+        :else
+        {:status :ok :data {:result result}}))))
+
+(defn execute-graph-remove
+  [action config]
+  (-> (p/let [stop-result (cli-server/stop-server! config (:repo action))
+              _ (when-not (or (:ok? stop-result)
+                              (= :server-not-found (get-in stop-result [:error :code])))
+                  (throw (ex-info (get-in stop-result [:error :message] "failed to stop server")
+                                  {:code (get-in stop-result [:error :code])})))
+              unlinked-dir (cli-common/unlink-graph! (cli-server/graphs-dir config) (:repo action))]
+        (if unlinked-dir
+          {:status :ok
+           :data {:result nil}}
+          {:status :error
+           :error {:code :graph-not-removed
+                   :message "unable to remove graph"}}))))
+
+(defn execute-graph-switch
+  [action config]
+  (-> (p/let [graphs (cli-server/list-graphs config)
+              graph (:graph action)]
+        (if-not (some #(= graph %) graphs)
+          {:status :error
+           :error {:code :graph-not-found
+                   :message (str "graph not found: " graph)}}
+          (p/let [_ (cli-server/ensure-server! config (:repo action))]
+            (cli-config/update-config! config {:graph graph})
+            {:status :ok
+             :data {:message (str "switched to " graph)}})))))
+
+(defn execute-graph-info
+  [action config]
+  (let [ident->kv-key (fn [ident]
+                        (if (keyword? ident)
+                          (if-let [ident-ns (namespace ident)]
+                            (str ident-ns "/" (name ident))
+                            (name ident))
+                          (str ident)))
+        kv-lookup (fn [kv key]
+                    (or (get kv key)
+                        (get kv (str ":" key))))]
+    (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+                rows (transport/invoke cfg :thread-api/q false [(:repo action) [graph-info-kv-query]])
+                kv (reduce (fn [acc [ident value]]
+                             (assoc acc (ident->kv-key ident) value))
+                           {}
+                           (or rows []))
+                created-at (kv-lookup kv "logseq.kv/graph-created-at")
+                schema-version (kv-lookup kv "logseq.kv/schema-version")]
+        {:status :ok
+         :data {:graph (:graph action)
+                :logseq.kv/graph-created-at created-at
+                :logseq.kv/schema-version schema-version
+                :kv kv}}))))
+
+(defn execute-graph-export
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              export-type (:export-type action)
+              export-result (case export-type
+                              "edn"
+                              (transport/invoke cfg
+                                                :thread-api/export-edn
+                                                false
+                                                [(:repo action) {:export-type :graph}])
+                              "sqlite"
+                              (transport/invoke cfg
+                                                :thread-api/export-db-base64
+                                                true
+                                                [(:repo action)])
+                              (throw (ex-info "unsupported export type" {:export-type export-type})))
+              data (if (= export-type "sqlite")
+                     (js/Buffer.from export-result "base64")
+                     export-result)
+              format (if (= export-type "sqlite") :sqlite :edn)]
+        (transport/write-output {:format format :path (:file action) :data data})
+        {:status :ok
+         :data {:message (str "wrote " (:file action))}})))
+
+(defn execute-graph-import
+  [action config]
+  (-> (p/let [existing-graphs (cli-server/list-graphs config)
+              graph (core/repo->graph (:repo action))
+              new-graph? (not (some #(= graph %) existing-graphs))
+              _ (cli-server/stop-server! config (:repo action))
+              cfg (cli-server/ensure-server! config (:repo action))
+              import-type (:import-type action)
+              input-data (case import-type
+                           "edn" (transport/read-input {:format :edn :path (:input action)})
+                           "sqlite" (transport/read-input {:format :sqlite :path (:input action)})
+                           (throw (ex-info "unsupported import type" {:import-type import-type})))
+              payload (if (= import-type "sqlite")
+                        (.toString (js/Buffer.from input-data) "base64")
+                        input-data)
+              method (if (= import-type "sqlite")
+                       :thread-api/import-db-base64
+                       :thread-api/import-edn)
+              direct-pass? (= import-type "sqlite")
+              _ (transport/invoke cfg method direct-pass? [(:repo action) payload])
+              _ (cli-server/restart-server! config (:repo action))]
+        {:status :ok
+         :data {:new-graph? new-graph?
+                :message (str (when new-graph?
+                                (str "Created graph " graph "\n"))
+                              "Imported " import-type " from " (:input action))}})))
diff --git a/src/main/logseq/cli/command/id.cljs b/src/main/logseq/cli/command/id.cljs
new file mode 100644
index 0000000000..1d5ed82c00
--- /dev/null
+++ b/src/main/logseq/cli/command/id.cljs
@@ -0,0 +1,49 @@
+(ns logseq.cli.command.id
+  "Shared id parsing helpers for CLI commands."
+  (:require [clojure.string :as string]
+            [logseq.common.util :as common-util]))
+
+(defn valid-id?
+  [value]
+  (and (number? value) (integer? value)))
+
+(defn parse-id-option
+  [value]
+  (let [invalid (fn [message]
+                  {:ok? false :message message})]
+    (cond
+      (nil? value)
+      {:ok? true :value nil :multi? false}
+
+      (vector? value)
+      (cond
+        (empty? value) (invalid "id vector must contain at least one id")
+        (every? valid-id? value) {:ok? true :value (vec value) :multi? true}
+        :else (invalid "id vector must contain only integers"))
+
+      (valid-id? value)
+      {:ok? true :value [value] :multi? false}
+
+      (string? value)
+      (let [text (string/trim value)]
+        (cond
+          (string/blank? text)
+          (invalid "id is required")
+
+          (string/starts-with? text "[")
+          (let [parsed (common-util/safe-read-string {:log-error? false} text)]
+            (cond
+              (nil? parsed) (invalid "invalid id edn")
+              (not (vector? parsed)) (invalid "id must be a vector")
+              (empty? parsed) (invalid "id vector must contain at least one id")
+              (every? valid-id? parsed) {:ok? true :value (vec parsed) :multi? true}
+              :else (invalid "id vector must contain only integers")))
+
+          (re-matches #"-?\d+" text)
+          {:ok? true :value [(js/parseInt text 10)] :multi? false}
+
+          :else
+          (invalid "id must be a number or vector of numbers")))
+
+      :else
+      (invalid "id must be a number or vector of numbers"))))
diff --git a/src/main/logseq/cli/command/list.cljs b/src/main/logseq/cli/command/list.cljs
new file mode 100644
index 0000000000..03e5850348
--- /dev/null
+++ b/src/main/logseq/cli/command/list.cljs
@@ -0,0 +1,494 @@
+(ns logseq.cli.command.list
+  "List-related CLI commands."
+  (:require [clojure.string :as string]
+            [logseq.cli.command.add :as add-command]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.command.task-status :as task-status-command]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.util :as common-util]
+            [logseq.db.frontend.property :as db-property]
+            [promesa.core :as p]))
+
+;; Common for all subcommands
+(def ^:private list-common-spec
+  {:fields {:desc "Select output fields (comma separated)"
+            :alias :f}
+   :limit {:desc "Limit results"
+           :coerce :long}
+   :offset {:desc "Offset results"
+            :coerce :long}
+   :sort {:desc "Sort field. Default: updated-at"
+          :alias :s}
+   :order {:desc "Sort order. Default: desc"
+           :validate #{"asc" "desc"}}})
+
+;; Common for all page-related subcommands
+(def ^:private list-common-page-spec
+  {:expand {:desc "Include expanded metadata"
+            :alias :e
+            :coerce :boolean}
+   :include-built-in {:desc "Include built-in nodes"
+                      :coerce :boolean}})
+
+(def ^:private default-sort-field "updated-at")
+
+(def ^:private available-task-priority-values
+  ["low" "medium" "high" "urgent"])
+
+(def ^:private available-task-priority-values-set
+  (set available-task-priority-values))
+
+(def ^:private task-priority-aliases
+  {"low" :logseq.property/priority.low
+   "medium" :logseq.property/priority.medium
+   "high" :logseq.property/priority.high
+   "urgent" :logseq.property/priority.urgent})
+
+(defn- invalid-task-priority-message
+  [priority-input]
+  (let [value (if (map? priority-input)
+                (:value priority-input)
+                priority-input)]
+    (str "Invalid value for option :priority: " value
+         ". Available values: "
+         (string/join ", " available-task-priority-values))))
+
+(defn- effective-sort-field
+  [options]
+  (or (:sort options) default-sort-field))
+
+;; Update format/list-page-columns to make field visible
+(def ^:private list-page-field-map
+  {"id" :db/id
+   "ident" :db/ident
+   "title" :block/title
+   "uuid" :block/uuid
+   "created-at" :block/created-at
+   "updated-at" :block/updated-at})
+
+(def ^:private list-page-spec
+  (merge-with
+   merge
+   list-common-spec
+   list-common-page-spec
+   {:sort {:validate (set (keys list-page-field-map))}
+    :fields {:multiple-values (keys list-page-field-map)}
+    :include-journal {:desc "Include journal pages"
+                      :coerce :boolean}
+    :journal-only {:desc "Only journal pages"
+                   :coerce :boolean}
+    :include-hidden {:desc "Include hidden pages"
+                     :coerce :boolean}
+    :updated-after {:desc "Filter by updated-at (ISO8601)"}
+    :created-after {:desc "Filter by created-at (ISO8601)"}}))
+
+;; Update format/list-tag-columns to make field visible
+(def ^:private list-tag-field-map
+  {"id" :db/id
+   "ident" :db/ident
+   "title" :block/title
+   "uuid" :block/uuid
+   "created-at" :block/created-at
+   "updated-at" :block/updated-at
+   "properties" :logseq.property.class/properties
+   "extends" :logseq.property.class/extends
+   "description" :logseq.property/description})
+
+(def ^:private list-tag-spec
+  (merge-with
+   merge
+   list-common-spec
+   list-common-page-spec
+   {:sort {:validate (set (keys list-tag-field-map))}
+    :fields {:multiple-values (keys list-tag-field-map)}
+    :with-properties {:desc "Include tag properties"
+                      :coerce :boolean}
+    :with-extends {:desc "Include tag extends"
+                   :coerce :boolean}}))
+
+;; Update format/list-property-columns to make field visible
+(def ^:private list-property-field-map
+  {"id" :db/id
+   "ident" :db/ident
+   "title" :block/title
+   "uuid" :block/uuid
+   "created-at" :block/created-at
+   "updated-at" :block/updated-at
+   "classes" :logseq.property/classes
+   "type" :logseq.property/type
+   "cardinality" :db/cardinality
+   "description" :logseq.property/description})
+
+(def ^:private list-property-spec
+  (merge-with
+   merge
+   list-common-spec
+   list-common-page-spec
+   {:sort {:validate (set (keys list-property-field-map))}
+    :fields {:multiple-values (keys list-property-field-map)}
+    :with-classes {:desc "Include property classes"
+                   :coerce :boolean}
+    :with-type {:desc "Include property type"
+                :default true
+                :coerce :boolean}}))
+
+(def ^:private list-task-field-map
+  {"id" :db/id
+   "title" :block/title
+   "status" :logseq.property/status
+   "priority" :logseq.property/priority
+   "scheduled" :logseq.property/scheduled
+   "deadline" :logseq.property/deadline
+   "updated-at" :block/updated-at
+   "created-at" :block/created-at})
+
+(def ^:private list-task-spec
+  (merge-with
+   merge
+   list-common-spec
+   {:status {:desc "Filter by task status"
+             :values (mapv (comp string/lower-case :value)
+                           (db-property/built-in-closed-values :logseq.property/status))}
+    :priority {:desc "Filter by task priority"
+               :validate {:pred available-task-priority-values-set
+                          :ex-msg invalid-task-priority-message}}
+    :content {:desc "Filter by task title content"
+              :alias :c}
+    :sort {:validate (set (keys list-task-field-map))}
+    :fields {:multiple-values (keys list-task-field-map)}}))
+
+(def ^:private list-node-field-map
+  {"id" :db/id
+   "title" :block/title
+   "type" :node/type
+   "page-id" :block/page-id
+   "page-title" :block/page-title
+   "created-at" :block/created-at
+   "updated-at" :block/updated-at})
+
+(def ^:private list-node-spec
+  (merge-with
+   merge
+   list-common-spec
+   {:tags {:desc "Filter by tags (comma separated selectors)"
+           ;; Autocomplete first tag until there is comma-delimited tags completion
+           :complete :tags}
+    :properties {:desc "Filter by properties (comma separated selectors)"
+                 :complete :properties}
+    :sort {:validate (set (keys list-node-field-map))}
+    :fields {:multiple-values (keys list-node-field-map)}}))
+
+(def ^:private list-asset-field-map
+  {"id" :db/id
+   "title" :block/title
+   "asset-type" :logseq.property.asset/type
+   "size" :logseq.property.asset/size
+   "updated-at" :block/updated-at
+   "created-at" :block/created-at})
+
+(def ^:private list-asset-spec
+  (merge-with
+   merge
+   list-common-spec
+   {:sort {:validate (set (keys list-asset-field-map))}
+    :fields {:multiple-values (keys list-asset-field-map)}}))
+
+(def entries
+  [(core/command-entry ["list" "page"] :list-page "List pages" list-page-spec
+                       {:examples ["logseq list page --graph my-graph"
+                                   "logseq list page --graph my-graph --journal-only --limit 20"
+                                   "logseq list page --graph my-graph --limit 50 --sort updated-at --order desc"]})
+   (core/command-entry ["list" "tag"] :list-tag "List tags" list-tag-spec
+                       {:examples ["logseq list tag --graph my-graph --with-properties"
+                                   "logseq list tag --graph my-graph --include-built-in --limit 20 --output json"]})
+   (core/command-entry ["list" "property"] :list-property "List properties" list-property-spec
+                       {:examples ["logseq list property --graph my-graph --with-type"
+                                   "logseq list property --graph my-graph --include-built-in --limit 20 --output json"]})
+   (core/command-entry ["list" "task"] :list-task "List tasks" list-task-spec
+                       {:examples ["logseq list task --graph my-graph --status todo --priority high"
+                                   "logseq list task --graph my-graph --content \"release\" --sort updated-at --order desc"]})
+   (core/command-entry ["list" "node"] :list-node "List nodes" list-node-spec
+                       {:examples ["logseq list node --graph my-graph --tags project,work"
+                                   "logseq list node --graph my-graph --properties status,priority --sort updated-at --order desc"]})
+   (core/command-entry ["list" "asset"] :list-asset "List assets" list-asset-spec
+                       {:examples ["logseq list asset --graph my-graph"
+                                   "logseq list asset --graph my-graph --limit 20 --sort updated-at --order desc"]})])
+
+(defn- parse-csv-option
+  [value]
+  (when (some? value)
+    (->> (string/split (str value) #",")
+         (map string/trim)
+         (remove string/blank?)
+         vec)))
+
+(defn- normalize-csv-option
+  [value]
+  (when-let [values (seq (parse-csv-option value))]
+    (string/join "," values)))
+
+(defn normalize-options
+  [command opts]
+  (if (= command :list-node)
+    (cond-> opts
+      (contains? opts :tags) (update :tags normalize-csv-option)
+      (contains? opts :properties) (update :properties normalize-csv-option))
+    opts))
+
+(defn invalid-options?
+  [command opts]
+  (let [{:keys [include-journal journal-only tags properties]} opts
+        tags-specified? (contains? opts :tags)
+        properties-specified? (contains? opts :properties)]
+    (cond
+      (and include-journal journal-only)
+      "include-journal and journal-only are mutually exclusive"
+
+      (and (= command :list-node) tags-specified? (not (seq tags)))
+      "list node --tags must include at least one non-empty value"
+
+      (and (= command :list-node) properties-specified? (not (seq properties)))
+      "list node --properties must include at least one non-empty value"
+
+      (and (= command :list-node)
+           (not (seq tags))
+           (not (seq properties)))
+      "list node requires at least one of --tags or --properties"
+
+      :else
+      nil)))
+
+(defn build-action
+  [command options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for list"}}
+    {:ok? true
+     :action {:type command
+              :repo repo
+              :options options}}))
+
+(defn- parse-field-list
+  [fields]
+  (when (seq fields)
+    (->> (string/split fields #",")
+         (map string/trim)
+         (remove string/blank?)
+         vec)))
+
+(defn- apply-fields
+  [items fields field-map]
+  (if (seq fields)
+    (let [keys (->> fields
+                    (map #(get field-map %))
+                    (remove nil?)
+                    vec)]
+      (if (seq keys)
+        (mapv #(select-keys % keys) items)
+        items))
+    items))
+
+(defn- apply-sort
+  [items sort-field order field-map]
+  (if (seq sort-field)
+    (let [sort-key (get field-map sort-field)
+          sorted (if sort-key
+                   (sort-by (fn [item]
+                              [(get item sort-key) (:db/id item)])
+                            items)
+                   items)
+          sorted (if (= "desc" order) (reverse sorted) sorted)]
+      (vec sorted))
+    (vec items)))
+
+(defn- apply-offset-limit
+  [items offset limit]
+  (cond-> items
+    (some? offset) (->> (drop offset) vec)
+    (some? limit) (->> (take limit) vec)))
+
+(defn- prepare-tag-item
+  [item {:keys [with-properties with-extends fields]}]
+  (cond-> item
+    (not with-properties) (dissoc :logseq.property.class/properties)
+    (not with-extends) (dissoc :logseq.property.class/extends)
+    (not (string/includes? (str fields) "description")) (dissoc :logseq.property/description)))
+
+(defn- prepare-property-item
+  [item {:keys [with-classes with-type fields]}]
+  (cond-> item
+    (not with-classes) (dissoc :logseq.property/classes)
+    (not with-type) (dissoc :logseq.property/type)
+    (not (string/includes? (str fields) "description")) (dissoc :logseq.property/description)))
+
+(defn execute-list-page
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              options (:options action)
+              items (transport/invoke cfg :thread-api/cli-list-pages false
+                                      [(:repo action) options])
+              sort-field (effective-sort-field options)
+              order (or (:order options) "desc")
+              fields (parse-field-list (:fields options))
+              sorted (apply-sort items sort-field order list-page-field-map)
+              limited (apply-offset-limit sorted (:offset options) (:limit options))
+              final (apply-fields limited fields list-page-field-map)]
+        {:status :ok
+         :data {:items final}})))
+
+(defn execute-list-tag
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              options (cond-> (:options action)
+                        ((some-fn :with-extends :with-properties) (:options action))
+                        (assoc :expand true))
+              items (transport/invoke cfg :thread-api/cli-list-tags false
+                                      [(:repo action) options])
+              sort-field (effective-sort-field options)
+              order (or (:order options) "desc")
+              fields (parse-field-list (:fields options))
+              prepared (mapv #(prepare-tag-item % options) items)
+              sorted (apply-sort prepared sort-field order list-tag-field-map)
+              limited (apply-offset-limit sorted (:offset options) (:limit options))
+              final (apply-fields limited fields list-tag-field-map)]
+        {:status :ok
+         :data {:items final}})))
+
+(defn execute-list-property
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              options (cond-> (:options action)
+                        (:with-classes (:options action)) (assoc :expand true))
+              items (transport/invoke cfg :thread-api/cli-list-properties false
+                                      [(:repo action) options])
+              sort-field (effective-sort-field options)
+              order (or (:order options) "desc")
+              fields (parse-field-list (:fields options))
+              prepared (mapv #(prepare-property-item % options) items)
+              sorted (apply-sort prepared sort-field order list-property-field-map)
+              limited (apply-offset-limit sorted (:offset options) (:limit options))
+              final (apply-fields limited fields list-property-field-map)]
+        {:status :ok
+         :data {:items final}})))
+
+(defn- parse-selector-token
+  [token]
+  (let [text (some-> token str string/trim)]
+    (cond
+      (not (seq text)) nil
+      (re-matches #"^-?\d+$" text) (js/parseInt text 10)
+      (common-util/uuid-string? text) (uuid text)
+      (common-util/valid-edn-keyword? text)
+      (let [value (common-util/safe-read-string {:log-error? false} text)]
+        (if (keyword? value) value text))
+      :else text)))
+
+(defn- parse-selector-csv
+  [value]
+  (->> (parse-csv-option value)
+       (map parse-selector-token)
+       (remove nil?)
+       vec))
+
+(defn- resolve-tag-ids
+  [config repo tags-csv]
+  (let [selectors (parse-selector-csv tags-csv)]
+    (if (seq selectors)
+      (p/let [entities (add-command/resolve-tags config repo selectors)]
+        (mapv :db/id entities))
+      (p/resolved nil))))
+
+(defn- resolve-property-idents
+  [config repo properties-csv]
+  (let [selectors (parse-selector-csv properties-csv)]
+    (if (seq selectors)
+      (add-command/resolve-property-identifiers config repo selectors {:allow-non-built-in? true})
+      (p/resolved nil))))
+
+(defn execute-list-node
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              options (:options action)
+              tag-ids (resolve-tag-ids cfg (:repo action) (:tags options))
+              property-idents (resolve-property-idents cfg (:repo action) (:properties options))
+              worker-options (cond-> (dissoc options :tags :properties)
+                               (seq tag-ids) (assoc :tag-ids tag-ids)
+                               (seq property-idents) (assoc :property-idents property-idents))
+              items (transport/invoke cfg :thread-api/cli-list-nodes false
+                                      [(:repo action) worker-options])
+              sort-field (effective-sort-field options)
+              order (or (:order options) "desc")
+              fields (parse-field-list (:fields options))
+              sorted (apply-sort items sort-field order list-node-field-map)
+              limited (apply-offset-limit sorted (:offset options) (:limit options))
+              final (apply-fields limited fields list-node-field-map)]
+        {:status :ok
+         :data {:items final}})))
+
+(def ^:private asset-tag-ident
+  :logseq.class/Asset)
+
+(defn- ensure-asset-tag-id!
+  [config repo]
+  (p/let [entity (transport/invoke config :thread-api/pull false
+                                   [repo [:db/id] [:db/ident asset-tag-ident]])]
+    (if-let [tag-id (:db/id entity)]
+      tag-id
+      (throw (ex-info "asset tag not found"
+                      {:code :asset-tag-not-found})))))
+
+(defn execute-list-asset
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              options (:options action)
+              asset-tag-id (ensure-asset-tag-id! cfg (:repo action))
+              worker-options (assoc options :tag-ids [asset-tag-id])
+              items (transport/invoke cfg :thread-api/cli-list-nodes false
+                                      [(:repo action) worker-options])
+              sort-field (effective-sort-field options)
+              order (or (:order options) "desc")
+              fields (parse-field-list (:fields options))
+              sorted (apply-sort items sort-field order list-asset-field-map)
+              limited (apply-offset-limit sorted (:offset options) (:limit options))
+              final (apply-fields limited fields list-asset-field-map)]
+        {:status :ok
+         :data {:items final}})))
+
+(defn- normalize-priority
+  [value]
+  (let [text (some-> value string/trim string/lower-case)]
+    (when (seq text)
+      (get task-priority-aliases text))))
+
+(defn execute-list-task
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              options (:options action)
+              status-input (some-> (:status options) string/trim)
+              available-statuses (when (seq status-input)
+                                   (transport/invoke cfg :thread-api/q false
+                                                     [(:repo action)
+                                                      [task-status-command/status-closed-values-query]]))
+              resolved-status (when (seq status-input)
+                                (task-status-command/resolve-status-ident status-input available-statuses))]
+        (if (and (seq status-input) (not resolved-status))
+          {:status :error
+           :error {:code :invalid-options
+                   :message (task-status-command/invalid-status-message status-input available-statuses)}}
+          (let [normalized-options (cond-> options
+                                     resolved-status
+                                     (assoc :status resolved-status)
+                                     (seq (some-> (:priority options) string/trim))
+                                     (assoc :priority (normalize-priority (:priority options))))]
+            (p/let [items (transport/invoke cfg :thread-api/cli-list-tasks false
+                                            [(:repo action) normalized-options])
+                    sort-field (effective-sort-field normalized-options)
+                    order (or (:order normalized-options) "desc")
+                    fields (parse-field-list (:fields normalized-options))
+                    sorted (apply-sort items sort-field order list-task-field-map)
+                    limited (apply-offset-limit sorted (:offset normalized-options) (:limit normalized-options))
+                    final (apply-fields limited fields list-task-field-map)]
+              {:status :ok
+               :data {:items final}}))))))
diff --git a/src/main/logseq/cli/command/query.cljs b/src/main/logseq/cli/command/query.cljs
new file mode 100644
index 0000000000..a7c69ab060
--- /dev/null
+++ b/src/main/logseq/cli/command/query.cljs
@@ -0,0 +1,292 @@
+(ns logseq.cli.command.query
+  "Query-related CLI commands."
+  (:require [clojure.string :as string]
+            [frontend.util.datalog :as datalog-util]
+            [logseq.db.frontend.rules :as rules]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.util :as common-util]
+            [promesa.core :as p]))
+
+(def ^:private query-spec
+  {:query {:desc "Datascript query EDN"}
+   :name {:desc "Query name from cli.edn custom-queries or built-ins"
+          :complete :queries}
+   :inputs {:desc "EDN vector of query inputs"}})
+
+(def ^:private query-list-spec
+  {})
+
+(def entries
+  [(core/command-entry ["query"] :query "Run a Datascript query" query-spec
+                       {:examples ["logseq query --graph my-graph --name recent-updated --inputs '[30]'"
+                                   "logseq query --graph my-graph --name task-search --inputs '[:logseq.property/status.done \"daily\"]'"
+                                   "logseq query --graph my-graph --query '[:find [?e ...] :where [?e :block/name]]'"]})
+   (core/command-entry ["query" "list"] :query-list "List available queries" query-list-spec
+                       {:examples ["logseq query list --graph my-graph"
+                                   "logseq query list --graph my-graph --output edn"]})])
+
+(def ^:private built-in-query-specs
+  {"task-search"
+   {:doc "Find tasks by status, optional title substring, optional recent-days."
+    :inputs [{:name "search-status"}
+             {:name "?search-title" :default ""}
+             {:name "?recent-days" :default 0}
+             {:name "?now-ms" :default :now-ms}]
+    :query '[:find [(pull ?e [:db/id :block/title :block/updated-at]) ...]
+             :in $ ?search-status ?search-title ?recent-days ?now-ms
+             :where
+             [?e :block/title ?title]
+             [?e :logseq.property/status ?status]
+             [?status :db/ident ?status-ident]
+             [(= ?status-ident ?search-status)]
+             [(clojure.string/lower-case ?title) ?title-lower-case]
+             [(str ?search-title) ?search-title-string]
+             [(clojure.string/lower-case ?search-title-string) ?search-title-lower-case]
+             [(clojure.string/includes? ?title-lower-case ?search-title-lower-case)]
+             [(get-else $ ?e :block/updated-at 0) ?updated-at]
+             (or-join [?recent-days ?updated-at ?now-ms ?days-ago]
+                      (and [(nil? ?recent-days)]
+                           [(identity 0) ?days-ago])
+                      (and [(<= ?recent-days 0)]
+                           [(identity 0) ?days-ago])
+                      (and [(* ?recent-days 86400000) ?recent-days-ms]
+                           [(- ?now-ms ?recent-days-ms) ?days-ago]
+                           [(>= ?updated-at ?days-ago)]))]}
+
+   "recent-updated"
+   {:doc "Find entities updated within recent-days."
+    :inputs [{:name "recent-days"}
+             {:name "?now-ms" :default :now-ms}]
+    :query '[:find [(pull ?e [:db/id :block/title :block/updated-at]) ...]
+             :in $ ?recent-days ?now-ms
+             :where
+             [?e :block/updated-at ?updated-at]
+             [(missing? $ ?e :logseq.property/built-in?)]
+             [(* ?recent-days 86400000) ?recent-days-ms]
+             [(- ?now-ms ?recent-days-ms) ?days-ago]
+             [(>= ?updated-at ?days-ago)]]}
+
+  "list-status"
+  {:doc "List closed values for the Status property."
+   :inputs []
+   :query '[:find [(pull ?value [:db/id :db/ident :block/order]) ...]
+            :where
+            [?property :db/ident :logseq.property/status]
+            [?value :block/closed-value-property ?property]]}
+
+  "list-priority"
+  {:doc "List closed values for the Priority property."
+   :inputs []
+   :query '[:find [(pull ?value [:db/id :db/ident :block/order]) ...]
+            :where
+            [?property :db/ident :logseq.property/priority]
+            [?value :block/closed-value-property ?property]]}})
+
+(defn- parse-edn
+  [label value]
+  (let [parsed (common-util/safe-read-string {:log-error? false} value)]
+    (if (nil? parsed)
+      {:ok? false
+       :error {:code :invalid-options
+               :message (str "invalid " label " edn")}}
+      {:ok? true :value parsed})))
+
+(defn- normalize-query-name
+  [name']
+  (when (some? name')
+    (let [raw (if (keyword? name') (name name') (str name'))
+          text (string/trim raw)]
+      (when (seq text) text))))
+
+(defn- normalize-query-entry
+  [name source spec]
+  (let [spec (cond
+               (vector? spec) {:query spec}
+               (map? spec) spec
+               :else nil)
+        query (:query spec)
+        name (normalize-query-name name)]
+    (when (and name query)
+      (cond-> (assoc spec :name name :source source)
+        (nil? (:inputs spec)) (assoc :inputs [])))))
+
+(defn- hide-internal-inputs
+  [entry]
+  (let [inputs (vec (remove (fn [input]
+                              (let [name (cond
+                                           (string? (:name input)) (:name input)
+                                           (keyword? (:name input)) (name (:name input))
+                                           :else nil)]
+                                (= "?now-ms" name)))
+                            (or (:inputs entry) [])))]
+    (assoc entry :inputs inputs)))
+
+(defn list-queries
+  [config]
+  (let [built-ins (mapv (fn [[name spec]]
+                          (normalize-query-entry name :built-in spec))
+                        built-in-query-specs)
+        custom-queries (or (:custom-queries config) {})
+        customs (mapv (fn [[name spec]]
+                        (normalize-query-entry name :custom spec))
+                      custom-queries)
+        merged (reduce (fn [acc entry]
+                         (if entry
+                           (assoc acc (:name entry) entry)
+                           acc))
+                       {}
+                       (concat built-ins customs))]
+    (->> (vals merged)
+         (sort-by :name)
+         vec)))
+
+(defn- find-query
+  [config name]
+  (some #(when (= name (:name %)) %) (list-queries config)))
+
+(defn- optional-input?
+  [input]
+  (let [name (cond
+               (string? input) input
+               (keyword? input) (name input)
+               (map? input) (some-> (:name input) str)
+               :else nil)]
+    (and (string? name) (string/starts-with? name "?"))))
+
+(defn- input-default
+  [input]
+  (when (map? input)
+    (if (contains? input :default)
+      (let [value (:default input)]
+        (if (= :now-ms value)
+          (js/Date.now)
+          value))
+      nil)))
+
+(defn- normalize-named-inputs
+  [entry inputs]
+  (let [spec-inputs (or (:inputs entry) [])
+        required-count (count (remove optional-input? spec-inputs))
+        inputs (or inputs [])]
+    (if (< (count inputs) required-count)
+      {:ok? false
+       :error {:code :invalid-options
+               :message "inputs missing required values"}}
+      {:ok? true
+       :value (if (< (count inputs) (count spec-inputs))
+                (let [missing (subvec (vec spec-inputs) (count inputs))]
+                  (into (vec inputs) (map input-default missing)))
+                inputs)})))
+
+(defn- normalize-task-search-inputs
+  [entry inputs]
+  (if (and entry (= "task-search" (:name entry)) (seq inputs))
+    (let [status (first inputs)
+          normalized (cond
+                       (keyword? status) status
+                       (string? status) (let [text (string/trim status)]
+                                          (if (seq text)
+                                            (keyword "logseq.property"
+                                                     (str "status." (string/lower-case text)))
+                                            status))
+                       :else status)]
+      (assoc (vec inputs) 0 normalized))
+    inputs))
+
+(defn- validate-recent-updated-inputs
+  [entry inputs]
+  (if (and entry
+           (= "recent-updated" (:name entry))
+           (= :built-in (:source entry)))
+    (let [recent-days (first inputs)]
+      (if (and (integer? recent-days) (pos? recent-days))
+        {:ok? true :value inputs}
+        {:ok? false
+         :error {:code :invalid-options
+                 :message "recent-days must be a positive integer"}}))
+    {:ok? true :value inputs}))
+
+(defn build-action
+  [options repo config]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for query"}}
+    (let [query-text (some-> (:query options) string/trim)
+          query-name (normalize-query-name (:name options))]
+      (cond
+        (and (seq query-text) (seq query-name))
+        {:ok? false
+         :error {:code :invalid-options
+                 :message "use either --query or --name, not both"}}
+
+        (and (not (seq query-text)) (not (seq query-name)))
+        {:ok? false
+         :error {:code :missing-query
+                 :message "query is required"}}
+
+        :else
+        (let [query-result (if (seq query-text)
+                             (parse-edn "query" query-text)
+                             (if-let [entry (find-query config query-name)]
+                               {:ok? true :value (:query entry) :entry entry}
+                               {:ok? false
+                                :error {:code :unknown-query
+                                        :message (str "unknown query: " query-name)}}))]
+          (if-not (:ok? query-result)
+            query-result
+            (let [inputs-text (some-> (:inputs options) string/trim)
+                  inputs-result (when (seq inputs-text)
+                                  (parse-edn "inputs" inputs-text))]
+              (cond
+                (and inputs-result (not (:ok? inputs-result)))
+                inputs-result
+
+                (and inputs-result (not (vector? (:value inputs-result))))
+                {:ok? false
+                 :error {:code :invalid-options
+                         :message "inputs must be a vector"}}
+
+                :else
+                (let [named-inputs (when-let [entry (:entry query-result)]
+                                     (normalize-named-inputs entry (or (:value inputs-result) [])))]
+                  (if (and named-inputs (not (:ok? named-inputs)))
+                    named-inputs
+                    (let [inputs (normalize-task-search-inputs
+                                  (:entry query-result)
+                                  (or (:value named-inputs)
+                                      (:value inputs-result)
+                                      []))
+                          validated (validate-recent-updated-inputs (:entry query-result) inputs)]
+                      (if-not (:ok? validated)
+                        validated
+                        {:ok? true
+                         :action {:type :query
+                                  :repo repo
+                                  :graph (core/repo->graph repo)
+                                  :query (:value query-result)
+                                  :inputs (:value validated)}}))))))))))))
+
+(defn build-list-action
+  [_options _repo]
+  {:ok? true
+   :action {:type :query-list}})
+
+(defn execute-query
+  [action config]
+  (case (:type action)
+    (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+                query-map (datalog-util/query-vec->map (:query action))
+                args (cond-> (into [(:query action)] (:inputs action))
+                       (= '% (last (:in query-map)))
+                       (conj (rules/extract-rules rules/db-query-dsl-rules)))
+                results (transport/invoke cfg :thread-api/q false [(:repo action) args])]
+          {:status :ok
+           :data {:result results}}))))
+
+(defn execute-query-list
+  [_action config]
+  (p/resolved {:status :ok
+               :data {:queries (mapv hide-internal-inputs (list-queries config))}}))
diff --git a/src/main/logseq/cli/command/remove.cljs b/src/main/logseq/cli/command/remove.cljs
new file mode 100644
index 0000000000..880d4ba86e
--- /dev/null
+++ b/src/main/logseq/cli/command/remove.cljs
@@ -0,0 +1,510 @@
+(ns logseq.cli.command.remove
+  "Remove-related CLI commands."
+  (:require [clojure.string :as string]
+            [logseq.cli.command.add :as add-command]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.command.id :as id-command]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.util :as common-util]
+            [promesa.core :as p]))
+
+(def ^:private remove-block-spec
+  {:id {:desc "Block db/id or EDN vector of ids"}
+   :uuid {:desc "Block UUID"
+          :validate {:pred (comp parse-uuid str)
+                     :ex-msg (constantly "Option uuid must be a valid UUID string")}}})
+
+(def ^:private remove-page-spec
+  {:id {:desc "Page db/id"
+        :coerce :long}
+   :page {:desc "Page name"
+          :complete :pages}})
+
+(def ^:private remove-tag-spec
+  {:id {:desc "Entity db/id"
+        :coerce :long}
+   :name {:desc "Tag name"
+          :complete :tags}})
+
+(def ^:private remove-property-spec
+  {:id {:desc "Entity db/id"
+        :coerce :long}
+   :name {:desc "Property name"
+          :complete :properties}})
+
+(def entries
+  [(core/command-entry ["remove" "block"] :remove-block "Remove blocks" remove-block-spec
+                       {:examples ["logseq remove block --graph my-graph --id 123"
+                                   "logseq remove block --graph my-graph --id '[123,456]'"
+                                   "logseq remove block --graph my-graph --uuid 7f0f4bb3-2e48-4b46-ae0f-18f52ef0f8be"]})
+   (core/command-entry ["remove" "page"] :remove-page "Remove page" remove-page-spec
+                       {:examples ["logseq remove page --graph my-graph --page Home"
+                                   "logseq remove page --graph my-graph --id 123"]})
+   (core/command-entry ["remove" "tag"] :remove-tag "Remove tag" remove-tag-spec
+                       {:examples ["logseq remove tag --graph my-graph --name project"]})
+   (core/command-entry ["remove" "property"] :remove-property "Remove property" remove-property-spec
+                       {:examples ["logseq remove property --graph my-graph --name owner"
+                                   "logseq remove property --graph my-graph --id 321"]})])
+
+(defn invalid-options?
+  [command opts]
+  (case command
+    :remove-block
+    (let [id-result (id-command/parse-id-option (:id opts))
+          selectors (filter some? [(:id opts) (some-> (:uuid opts) string/trim)])]
+      (cond
+        (and (some? (:id opts)) (not (:ok? id-result)))
+        (:message id-result)
+
+        (> (count selectors) 1)
+        "only one of --id or --uuid is allowed"
+
+        :else
+        nil))
+
+    :remove-page
+    (let [page (some-> (:page opts) string/trim)
+          selectors (filter some? [(:id opts) page])]
+      (cond
+        (> (count selectors) 1)
+        "only one of --id or --page is allowed"
+
+        (and (contains? opts :page)
+             (string/blank? (or (:page opts) "")))
+        "page must be non-empty"
+
+        :else
+        nil))
+
+    (:remove-tag :remove-property)
+    (let [name (some-> (:name opts) string/trim)
+          selectors (filter some? [(:id opts) name])]
+      (cond
+        (> (count selectors) 1)
+        "only one of --id or --name is allowed"
+
+        (and (contains? opts :name) (string/blank? (or (:name opts) "")))
+        "name must be non-empty"
+
+        :else
+        nil))
+
+    nil))
+
+(def ^:private block-id-selector
+  [:db/id :block/uuid :block/name])
+
+(def ^:private page-id-selector
+  [:db/id :block/uuid :block/name :block/title :logseq.property/deleted-at])
+
+(def ^:private entity-selector
+  [:db/id :db/ident :block/uuid :block/name :block/title
+   :logseq.property/type :logseq.property/public? :logseq.property/built-in?
+   {:block/tags [:db/id :db/ident :block/title :block/name]}])
+
+(defn- fetch-block-by-id
+  [config repo id]
+  (transport/invoke config :thread-api/pull false
+                    [repo block-id-selector id]))
+
+(defn- fetch-block-by-uuid
+  [config repo uuid-str]
+  (p/let [entity (transport/invoke config :thread-api/pull false
+                                   [repo block-id-selector [:block/uuid (uuid uuid-str)]])]
+    (if (:db/id entity)
+      entity
+      (transport/invoke config :thread-api/pull false
+                        [repo block-id-selector [:block/uuid uuid-str]]))))
+
+(defn- delete-block-uuids
+  [config repo block-uuids]
+  (transport/invoke config :thread-api/apply-outliner-ops false
+                    [repo [[:delete-blocks [block-uuids {}]]] {}]))
+
+(defn- delete-page-by-uuid
+  [config repo page-uuid]
+  (p/let [result (transport/invoke config :thread-api/apply-outliner-ops false
+                                   [repo [[:delete-page [page-uuid {}]]] {}])]
+    (if (nil? result) true result)))
+
+(defn- remove-block-id
+  [config repo id]
+  (p/let [entity (fetch-block-by-id config repo id)]
+    (cond
+      (not (:db/id entity))
+      (throw (ex-info "block not found" {:code :block-not-found}))
+
+      (:block/name entity)
+      (throw (ex-info "target is not a block, use 'remove page' instead" {:code :invalid-target}))
+
+      (nil? (:block/uuid entity))
+      (throw (ex-info "block uuid not found" {:code :block-not-found}))
+
+      :else
+      (delete-block-uuids config repo [(:block/uuid entity)]))))
+
+(defn- remove-block-ids-best-effort
+  [config repo ids]
+  (p/let [entities (p/all (map (fn [id]
+                                 (fetch-block-by-id config repo id))
+                               ids))
+          id-entities (map vector ids entities)
+          block? (fn [[_id entity]] (and (:db/id entity) (not (:block/name entity))))
+          existing-ids (vec (keep (fn [[id :as pair]] (when (block? pair) id))
+                                  id-entities))
+          existing-uuids (vec (keep (fn [[_id entity]]
+                                      (when (and (:db/id entity)
+                                                 (not (:block/name entity)))
+                                        (:block/uuid entity)))
+                                    id-entities))
+          missing-ids (vec (keep (fn [[id entity]]
+                                   (when-not (:db/id entity) id))
+                                 id-entities))
+          page-ids (vec (keep (fn [[id entity]]
+                                (when (and (:db/id entity) (:block/name entity)) id))
+                              id-entities))
+          _ (when (and (empty? existing-ids) (seq page-ids))
+              (throw (ex-info "target is not a block, use 'remove page' instead" {:code :invalid-target})))
+          result (if (seq existing-uuids)
+                   (delete-block-uuids config repo existing-uuids)
+                   nil)]
+    (cond-> {:deleted-ids existing-ids
+             :missing-ids missing-ids
+             :result result}
+      (seq page-ids) (assoc :page-ids page-ids))))
+
+(defn- perform-remove-block
+  [config {:keys [repo ids multi-id? uuid]}]
+  (cond
+    (and (seq ids) multi-id?)
+    (remove-block-ids-best-effort config repo ids)
+
+    (seq ids)
+    (remove-block-id config repo (first ids))
+
+    (seq uuid)
+    (p/let [entity (fetch-block-by-uuid config repo uuid)]
+      (if-let [block-uuid (:block/uuid entity)]
+        (delete-block-uuids config repo [block-uuid])
+        (throw (ex-info "block not found" {:code :block-not-found}))))
+
+    :else
+    (p/rejected (ex-info "block is required" {:code :missing-target}))))
+
+(defn- resolve-page-by-name
+  [config repo name]
+  (p/let [live (add-command/find-pages-by-name config repo name page-id-selector)]
+    (cond
+      (empty? live) nil
+      (> (count live) 1) {:ambiguous? true :matches live}
+      :else (first live))))
+
+(defn- resolve-page-by-id
+  [config repo id]
+  (transport/invoke config :thread-api/pull false
+                    [repo page-id-selector id]))
+
+(defn- item-id
+  [item]
+  (or (:db/id item) (:id item)))
+
+(defn- item-name
+  [item]
+  (or (:block/title item) (:title item) (:name item) (:block/name item)))
+
+(defn- normalize-name
+  [value]
+  (common-util/page-name-sanity-lc (or value "")))
+
+(defn- tag-entity?
+  [entity]
+  (some #(= :logseq.class/Tag (:db/ident %))
+        (:block/tags entity)))
+
+(defn- property-entity?
+  [entity]
+  (some? (:logseq.property/type entity)))
+
+(defn- list-matches-by-name
+  [config repo method name]
+  (let [normalized (normalize-name name)]
+    (p/let [items (transport/invoke config method false [repo {:include-built-in true :expand true}])
+            matches (->> (or items [])
+                         (filter (fn [item]
+                                   (= normalized (normalize-name (item-name item)))))
+                         vec)]
+      matches)))
+
+(defn- ambiguous-error
+  [code label name matches]
+  (let [candidates (->> matches
+                        (map (fn [item]
+                               {:id (item-id item)
+                                :name (item-name item)}))
+                        (filter :id)
+                        vec)]
+    {:code code
+     :message (str "multiple " label "s match name: " name "; rerun with --id")
+     :candidates candidates}))
+
+(defn- resolve-target
+  [config repo {:keys [id name]} {:keys [list-method not-found-code ambiguous-code label]}]
+  (cond
+    (some? id)
+    (p/resolved {:ok? true
+                 :lookup id
+                 :id id})
+
+    (seq name)
+    (p/let [matches (list-matches-by-name config repo list-method name)]
+      (cond
+        (empty? matches)
+        {:ok? false
+         :error {:code not-found-code
+                 :message (str label " not found")}}
+
+        (> (count matches) 1)
+        {:ok? false
+         :error (ambiguous-error ambiguous-code label name matches)}
+
+        :else
+        {:ok? true
+         :lookup [:block/name (normalize-name (or (item-name (first matches)) name))]
+         :id (item-id (first matches))
+         :name (item-name (first matches))}))
+
+    :else
+    (p/resolved {:ok? false
+                 :error {:code :missing-target
+                         :message (str label " name or id is required")}})))
+
+(defn- validate-tag-target
+  [entity]
+  (cond
+    (nil? (:db/id entity))
+    {:ok? false
+     :error {:code :tag-not-found
+             :message "tag not found"}}
+
+    (not (tag-entity? entity))
+    {:ok? false
+     :error {:code :invalid-tag-target
+             :message "target is not a tag"}}
+
+    (true? (:logseq.property/built-in? entity))
+    {:ok? false
+     :error {:code :tag-built-in
+             :message "built-in tag cannot be removed"}}
+
+    (false? (:logseq.property/public? entity))
+    {:ok? false
+     :error {:code :tag-hidden
+             :message "hidden tag cannot be removed"}}
+
+    (nil? (:block/uuid entity))
+    {:ok? false
+     :error {:code :tag-not-found
+             :message "tag uuid not found"}}
+
+    :else
+    {:ok? true
+     :entity entity}))
+
+(defn- validate-property-target
+  [entity]
+  (cond
+    (nil? (:db/id entity))
+    {:ok? false
+     :error {:code :property-not-found
+             :message "property not found"}}
+
+    (not (property-entity? entity))
+    {:ok? false
+     :error {:code :invalid-property-target
+             :message "target is not a property"}}
+
+    (true? (:logseq.property/built-in? entity))
+    {:ok? false
+     :error {:code :property-built-in
+             :message "built-in property cannot be removed"}}
+
+    (false? (:logseq.property/public? entity))
+    {:ok? false
+     :error {:code :property-hidden
+             :message "hidden property cannot be removed"}}
+
+    (nil? (:block/uuid entity))
+    {:ok? false
+     :error {:code :property-not-found
+             :message "property uuid not found"}}
+
+    :else
+    {:ok? true
+     :entity entity}))
+
+(defn- perform-remove-entity
+  [config action {:keys [list-method not-found-code ambiguous-code label validate-fn]}]
+  (p/let [resolved (resolve-target config (:repo action) action
+                                   {:list-method list-method
+                                    :not-found-code not-found-code
+                                    :ambiguous-code ambiguous-code
+                                    :label label})]
+    (if-not (:ok? resolved)
+      {:status :error
+       :error (:error resolved)}
+      (p/let [entity (transport/invoke config :thread-api/pull false
+                                       [(:repo action) entity-selector (:lookup resolved)])
+              validation (validate-fn entity)]
+        (if-not (:ok? validation)
+          {:status :error
+           :error (:error validation)}
+          (p/let [result (delete-page-by-uuid config (:repo action) (:block/uuid entity))]
+            {:status :ok
+             :data {:result result
+                    :id (:db/id entity)
+                    :name (or (:name resolved) (:block/title entity) (:block/name entity))}}))))))
+
+(defn build-action
+  [command options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for remove"}}
+    (case command
+      :remove-block
+      (let [id-result (id-command/parse-id-option (:id options))
+            ids (:value id-result)
+            multi-id? (:multi? id-result)
+            uuid (some-> (:uuid options) string/trim)
+            selectors (filter some? [(:id options) uuid])]
+        (cond
+          (empty? selectors)
+          {:ok? false
+           :error {:code :missing-target
+                   :message "block is required"}}
+
+          (> (count selectors) 1)
+          {:ok? false
+           :error {:code :invalid-options
+                   :message "only one of --id or --uuid is allowed"}}
+
+          (and (some? (:id options)) (not (:ok? id-result)))
+          {:ok? false
+           :error {:code :invalid-options
+                   :message (:message id-result)}}
+
+          :else
+          {:ok? true
+           :action {:type :remove-block
+                    :repo repo
+                    :graph (core/repo->graph repo)
+                    :id (when (and (seq ids) (not multi-id?)) (first ids))
+                    :ids ids
+                    :multi-id? multi-id?
+                    :uuid uuid}}))
+
+      :remove-page
+      (let [page (some-> (:page options) string/trim)
+            id (:id options)
+            selectors (filter some? [id page])]
+        (cond
+          (empty? selectors)
+          {:ok? false
+           :error {:code :missing-page-name
+                   :message "page name or id is required"}}
+
+          (> (count selectors) 1)
+          {:ok? false
+           :error {:code :invalid-options
+                   :message "only one of --id or --page is allowed"}}
+
+          :else
+          {:ok? true
+           :action {:type :remove-page
+                    :repo repo
+                    :graph (core/repo->graph repo)
+                    :id id
+                    :page page}}))
+
+      (:remove-tag :remove-property)
+      (let [name (some-> (:name options) string/trim)
+            id (:id options)
+            selectors (filter some? [id name])]
+        (cond
+          (empty? selectors)
+          {:ok? false
+           :error {:code :missing-target
+                   :message "name or id is required"}}
+
+          (> (count selectors) 1)
+          {:ok? false
+           :error {:code :invalid-options
+                   :message "only one of --id or --name is allowed"}}
+
+          :else
+          {:ok? true
+           :action {:type command
+                    :repo repo
+                    :graph (core/repo->graph repo)
+                    :id id
+                    :name name}}))
+
+      {:ok? false
+       :error {:code :unknown-command
+               :message (str "unknown remove command: " command)}})))
+
+(defn execute-remove-block
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              result (perform-remove-block cfg action)]
+        {:status :ok
+         :data (cond-> {:result result}
+                 (map? result) (merge (dissoc result :result)))})
+      (p/catch (fn [e]
+                 (if-let [code (:code (ex-data e))]
+                   {:status :error
+                    :error {:code code
+                            :message (or (ex-message e) (str e))}}
+                   (p/rejected e))))))
+
+(defn execute-remove-page
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              entity (if (:id action)
+                       (resolve-page-by-id cfg (:repo action) (:id action))
+                       (resolve-page-by-name cfg (:repo action) (:page action)))]
+        (cond
+          (:ambiguous? entity)
+          {:status :error
+           :error (ambiguous-error :ambiguous-page-name "page" (:page action) (:matches entity))}
+
+          (:block/uuid entity)
+          (p/let [result (delete-page-by-uuid cfg (:repo action) (:block/uuid entity))]
+            {:status :ok
+             :data {:result result}})
+
+          :else
+          {:status :error
+           :error {:code :page-not-found
+                   :message "page not found"}}))))
+
+(defn execute-remove-tag
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))]
+        (perform-remove-entity cfg action
+                               {:list-method :thread-api/cli-list-tags
+                                :not-found-code :tag-not-found
+                                :ambiguous-code :ambiguous-tag-name
+                                :label "tag"
+                                :validate-fn validate-tag-target}))))
+
+(defn execute-remove-property
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))]
+        (perform-remove-entity cfg action
+                               {:list-method :thread-api/cli-list-properties
+                                :not-found-code :property-not-found
+                                :ambiguous-code :ambiguous-property-name
+                                :label "property"
+                                :validate-fn validate-property-target}))))
diff --git a/src/main/logseq/cli/command/search.cljs b/src/main/logseq/cli/command/search.cljs
new file mode 100644
index 0000000000..5e44e0a9fc
--- /dev/null
+++ b/src/main/logseq/cli/command/search.cljs
@@ -0,0 +1,142 @@
+(ns logseq.cli.command.search
+  "Search-related CLI commands."
+  (:require [clojure.string :as string]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.db :as ldb]
+            [promesa.core :as p]))
+
+(def ^:private search-spec
+  {:content {:alias :c
+             :desc "Search content text"}})
+
+(def entries
+  [(core/command-entry ["search" "block"] :search-block "Search blocks by title" search-spec
+                       {:examples ["logseq search block --content \"task\" --graph my-graph"]})
+   (core/command-entry ["search" "page"] :search-page "Search pages by name" search-spec
+                       {:examples ["logseq search page --content \"home\" --graph my-graph"]})
+   (core/command-entry ["search" "property"] :search-property "Search properties by title" search-spec
+                       {:examples ["logseq search property --content \"owner\" --graph my-graph"]})
+   (core/command-entry ["search" "tag"] :search-tag "Search tags by title" search-spec
+                       {:examples ["logseq search tag --content \"quote\" --graph my-graph"]})])
+
+(defn build-action
+  [command opts repo]
+  (let [query (some-> (:content opts) str string/trim)]
+    (cond
+      (not (seq repo))
+      {:ok? false
+       :error {:code :missing-repo
+               :message "repo is required for search"}}
+
+      (not (seq query))
+      {:ok? false
+       :error {:code :missing-query-text
+               :message "query text is required"}}
+
+      :else
+      {:ok? true
+       :action {:type command
+                :repo repo
+                :graph (core/repo->graph repo)
+                :query query}})))
+
+(def ^:private search-block-query
+  ;; The recursive `{:block/parent ...}` pull lets `ldb/recycled?` walk up to
+  ;; the containing page so blocks on a recycled page are filtered too — a
+  ;; recycled page has `:logseq.property/deleted-at` set on itself, which the
+  ;; parent walk lands on.
+  '[:find [(pull ?e [:db/id :db/ident :block/title :logseq.property/deleted-at
+                     {:block/parent ...}]) ...]
+    :in $ ?query
+    :where
+    [?e :block/title ?title]
+    [(clojure.string/lower-case ?title) ?title-lower]
+    [(clojure.string/lower-case ?query) ?query-lower]
+    [(clojure.string/includes? ?title-lower ?query-lower)]])
+
+(def ^:private search-page-query
+  '[:find [(pull ?e [:db/id :db/ident :block/title :logseq.property/deleted-at]) ...]
+    :in $ ?query
+    :where
+    [?e :block/name ?name]
+    [(clojure.string/lower-case ?name) ?name-lower]
+    [(clojure.string/lower-case ?query) ?query-lower]
+    [(clojure.string/includes? ?name-lower ?query-lower)]])
+
+(def ^:private search-property-query
+  '[:find [(pull ?e [:db/id :db/ident :block/title]) ...]
+    :in $ ?query
+    :where
+    [?e :block/tags :logseq.class/Property]
+    [?e :block/title ?title]
+    [(clojure.string/lower-case ?title) ?title-lower]
+    [(clojure.string/lower-case ?query) ?query-lower]
+    [(clojure.string/includes? ?title-lower ?query-lower)]])
+
+(def ^:private search-tag-query
+  '[:find [(pull ?e [:db/id :db/ident :block/title]) ...]
+    :in $ ?query
+    :where
+    [?e :block/tags :logseq.class/Tag]
+    [?e :block/title ?title]
+    [(clojure.string/lower-case ?title) ?title-lower]
+    [(clojure.string/lower-case ?query) ?query-lower]
+    [(clojure.string/includes? ?title-lower ?query-lower)]])
+
+(defn- query-by-command
+  [command]
+  (case command
+    :search-block search-block-query
+    :search-page search-page-query
+    :search-property search-property-query
+    :search-tag search-tag-query
+    nil))
+
+(defn- sort-items
+  [items]
+  (->> items
+       (sort-by (juxt (fn [item]
+                        (some-> (:block/title item) string/lower-case))
+                      :db/id))
+       vec))
+
+(defn- normalize-items
+  [items]
+  (->> (or items [])
+       (filter map?)
+       (map #(select-keys % [:db/id :db/ident :block/title]))
+       sort-items))
+
+(defn- execute-search
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              query (query-by-command (:type action))
+              result (transport/invoke cfg :thread-api/q false
+                                       [(:repo action) [query (:query action)]])
+              ;; Hide recycled entries so search doesn't surface entries that
+              ;; `remove page` / `remove block` already soft-deleted. Tag and
+              ;; property pages are hard-retracted in `outliner-page/delete!`,
+              ;; so the recycle filter only applies to page and block search.
+              filtered (cond->> (or result [])
+                         (#{:search-page :search-block} (:type action))
+                         (remove ldb/recycled?))]
+        {:status :ok
+         :data {:items (normalize-items filtered)}})))
+
+(defn execute-search-block
+  [action config]
+  (execute-search action config))
+
+(defn execute-search-page
+  [action config]
+  (execute-search action config))
+
+(defn execute-search-property
+  [action config]
+  (execute-search action config))
+
+(defn execute-search-tag
+  [action config]
+  (execute-search action config))
diff --git a/src/main/logseq/cli/command/server.cljs b/src/main/logseq/cli/command/server.cljs
new file mode 100644
index 0000000000..cead8d0820
--- /dev/null
+++ b/src/main/logseq/cli/command/server.cljs
@@ -0,0 +1,96 @@
+(ns logseq.cli.command.server
+  "Server-related CLI commands."
+  (:require [logseq.cli.command.core :as core]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.version :as version]
+            [promesa.core :as p]))
+
+(def entries
+  [(core/command-entry ["server" "list"] :server-list "List db-worker-node servers" {})
+   (core/command-entry ["server" "cleanup"] :server-cleanup "Clean up revision-mismatched CLI-owned db-worker-node servers" {}
+                       {:examples ["logseq server cleanup"]})
+   (core/command-entry ["server" "start"] :server-start "Start db-worker-node for a graph" {}
+                       {:examples ["logseq server start --graph my-graph"]})
+   (core/command-entry ["server" "stop"] :server-stop "Stop db-worker-node for a graph" {}
+                       {:examples ["logseq server stop --graph my-graph"]})
+   (core/command-entry ["server" "restart"] :server-restart "Restart db-worker-node for a graph" {}
+                       {:examples ["logseq server restart --graph my-graph"]})])
+
+(defn build-action
+  [command repo]
+  (case command
+    :server-list
+    {:ok? true
+     :action {:type :server-list}}
+
+    :server-cleanup
+    {:ok? true
+     :action {:type :server-cleanup}}
+
+    :server-start
+    (if-not (seq repo)
+      {:ok? false
+       :error {:code :missing-repo
+               :message "repo is required for server start"}}
+      {:ok? true
+       :action {:type :server-start
+                :repo repo}})
+
+    :server-stop
+    (if-not (seq repo)
+      {:ok? false
+       :error {:code :missing-repo
+               :message "repo is required for server stop"}}
+      {:ok? true
+       :action {:type :server-stop
+                :repo repo}})
+
+    :server-restart
+    (if-not (seq repo)
+      {:ok? false
+       :error {:code :missing-repo
+               :message "repo is required for server restart"}}
+      {:ok? true
+       :action {:type :server-restart
+                :repo repo}})
+
+    {:ok? false
+     :error {:code :unknown-command
+             :message (str "unknown server command: " command)}}))
+
+(defn- server-result->response
+  [result]
+  (if (:ok? result)
+    {:status :ok
+     :data (:data result)}
+    {:status :error
+     :error (:error result)}))
+
+(defn execute-list
+  [_action config]
+  (-> (p/let [servers (cli-server/list-servers config)
+              revision-mismatch (cli-server/compute-revision-mismatches (version/revision) servers)]
+        (cond-> {:status :ok
+                 :data {:servers servers}}
+          revision-mismatch
+          (assoc :human {:server-list {:revision-mismatch revision-mismatch}})))))
+
+(defn execute-cleanup
+  [_action config]
+  (-> (p/let [result (cli-server/cleanup-revision-mismatched-servers! config (version/revision))]
+        (server-result->response result))))
+
+(defn execute-start
+  [action config]
+  (-> (p/let [result (cli-server/start-server! config (:repo action))]
+        (server-result->response result))))
+
+(defn execute-stop
+  [action config]
+  (-> (p/let [result (cli-server/stop-server! config (:repo action))]
+        (server-result->response result))))
+
+(defn execute-restart
+  [action config]
+  (-> (p/let [result (cli-server/restart-server! config (:repo action))]
+        (server-result->response result))))
diff --git a/src/main/logseq/cli/command/show.cljs b/src/main/logseq/cli/command/show.cljs
new file mode 100644
index 0000000000..61921a06d2
--- /dev/null
+++ b/src/main/logseq/cli/command/show.cljs
@@ -0,0 +1,1193 @@
+(ns logseq.cli.command.show
+  "Show-related CLI commands."
+  (:require ["fs" :as fs]
+            [clojure.set :as set]
+            [clojure.string :as string]
+            [clojure.walk :as walk]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.command.id :as id-command]
+            [logseq.cli.humanize :as cli-humanize]
+            [logseq.cli.output-mode :as output-mode]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.style :as style]
+            [logseq.cli.transport :as transport]
+            [logseq.common.util :as common-util]
+            [logseq.db :as ldb]
+            [logseq.db.frontend.property :as db-property]
+            [promesa.core :as p]
+            ["string-width" :default string-width]))
+
+(def ^:private show-spec
+  {:id {:desc "Block db/id or EDN vector of ids"}
+   :uuid {:desc "Block UUID"
+          :validate {:pred (comp parse-uuid str)
+                     :ex-msg (constantly "Option uuid must be a valid UUID string")}}
+   :page {:desc "Page name"
+          :complete :pages}
+   :linked-references {:desc "Include linked references (default true)"
+                       :coerce :boolean}
+   :ref-id-footer {:desc "Show referenced entity id footer (default true)"
+                   :coerce :boolean}
+   :level {:desc "Limit tree depth (default 10)"
+           :coerce :long}})
+
+(def entries
+  [(core/command-entry ["show"] :show "Show tree" show-spec
+                       {:examples ["logseq show --graph my-graph --page Home"
+                                   "logseq show --graph my-graph --page \"Meeting Notes\" --level 2"
+                                   "logseq show --graph my-graph --id 123 --level 3"
+                                   "logseq show --graph my-graph --id '[123,456,789]'"
+                                   "logseq show --graph my-graph --uuid 11111111-1111-1111-1111-111111111111"]})])
+
+(def ^:private multi-id-delimiter "\n================================================================\n")
+(def ^:private show-breadcrumb-segment-max-display-width 24)
+(def ^:private breadcrumb-separator " > ")
+(def ^:private breadcrumb-truncation-suffix "…")
+(def ^:private breadcrumb-truncation-suffix-width (string-width breadcrumb-truncation-suffix))
+(def ^:private schema-definition-class-idents
+  #{:logseq.class/Tag
+    :logseq.class/Property
+    :logseq.class/Page})
+
+(defn- entity-id-text
+  [entity]
+  (str (or (:db/id entity) "-")))
+
+(defn- id-column-width
+  [entities]
+  (apply max (map (comp count entity-id-text) entities)))
+
+(defn- render-id-column
+  [entity id-width]
+  (let [id-text (entity-id-text entity)
+        padding (max 0 (- id-width (count id-text)))]
+    (style/dim (str id-text (apply str (repeat padding " "))))))
+
+(defn- render-id-column-padding
+  [id-width]
+  (style/dim (apply str (repeat (inc id-width) " "))))
+
+(defn- breadcrumb-label
+  [entity]
+  (or (:block/title entity)
+      (:block/name entity)
+      (some-> (:block/uuid entity) str)
+      (some-> (:db/id entity) str)))
+
+(defn- breadcrumb-display-width
+  [value]
+  (string-width (str (or value ""))))
+
+(defn- take-to-display-width
+  [text max-width]
+  (loop [remaining-chars (seq (js/Array.from (or text "")))
+         acc ""]
+    (if-let [ch (first remaining-chars)]
+      (let [candidate (str acc ch)]
+        (if (<= (breadcrumb-display-width candidate) max-width)
+          (recur (next remaining-chars) candidate)
+          acc))
+      acc)))
+
+(defn- truncate-breadcrumb-segment
+  ([value]
+   (truncate-breadcrumb-segment value show-breadcrumb-segment-max-display-width))
+  ([value max-width]
+   (let [value (str (or value ""))
+         max-width (max 1 max-width)]
+     (if (<= (breadcrumb-display-width value) max-width)
+       value
+       (if (<= max-width breadcrumb-truncation-suffix-width)
+         (take-to-display-width breadcrumb-truncation-suffix max-width)
+         (str (take-to-display-width value (- max-width breadcrumb-truncation-suffix-width))
+              breadcrumb-truncation-suffix))))))
+
+(defn- schema-definition-root?
+  [root]
+  (boolean (some schema-definition-class-idents
+                 (keep :db/ident (:block/tags root)))))
+
+(declare property-value-block?)
+
+(defn- ordinary-block-root?
+  [root]
+  (and (map? root)
+       (some? (get-in root [:block/page :db/id]))
+       (not (property-value-block? root))
+       (not (schema-definition-root? root))))
+
+(defn- fetch-breadcrumb-parents
+  [config repo root]
+  (if (and (ordinary-block-root? root)
+           (:db/id root))
+    (-> (transport/invoke config :thread-api/get-block-parents false [repo (:db/id root)])
+        (p/then (fn [parents]
+                  (or parents []))))
+    (p/resolved [])))
+
+(defn- render-breadcrumb-line
+  [parents]
+  (let [rows (->> parents
+                  (map (fn [parent]
+                         (let [label (-> parent breadcrumb-label truncate-breadcrumb-segment)]
+                           (when-not (string/blank? label)
+                             {:parent parent
+                              :label label}))))
+                  (remove nil?)
+                  vec)]
+    (when (seq rows)
+      (let [id-width (id-column-width (map :parent rows))]
+        (->> rows
+             (map-indexed (fn [idx {:keys [parent label]}]
+                            (let [tree-indent (apply str (repeat (* idx 2) " "))]
+                              (str (render-id-column parent id-width)
+                                   tree-indent
+                                   breadcrumb-separator
+                                   label))))
+             (string/join "\n"))))))
+
+(defn read-stdin
+  []
+  (.toString (fs/readFileSync 0) "utf8"))
+
+(defn- normalize-stdin-id
+  [value]
+  (let [text (string/trim (or value ""))
+        last-line (-> text string/split-lines last (or "") string/trim)]
+    (cond
+      (string/blank? text) text
+      (string/starts-with? text "[") text
+      (re-matches #"-?\d+" text) text
+      (re-matches #"\[[\d\s,]*\]" last-line) last-line
+      :else
+      (let [tokens (->> (string/split text #"\s+")
+                        (remove string/blank?))]
+        (if (and (seq tokens) (every? #(re-matches #"-?\d+" %) tokens))
+          (str "[" (string/join " " tokens) "]")
+          text)))))
+
+(defn- resolve-stdin-id
+  [options]
+  (let [stdin (cond
+                (contains? options :stdin) (:stdin options)
+                (:id-from-stdin? options) (read-stdin)
+                :else nil)
+        normalized (normalize-stdin-id stdin)]
+    (if (string/blank? normalized)
+      options
+      (assoc options :id normalized))))
+
+(defn invalid-options?
+  [opts]
+  (let [level (:level opts)
+        id-value (:id opts)
+        id-missing? (and (:id-from-stdin? opts)
+                         (or (nil? id-value)
+                             (and (string? id-value) (string/blank? id-value))))
+        id-result (when-not id-missing?
+                    (id-command/parse-id-option id-value))]
+    (cond
+      (and (some? level) (< level 1))
+      "level must be >= 1"
+
+      (and (some? id-value) (not id-missing?) (not (:ok? id-result)))
+      (:message id-result)
+
+      :else
+      nil)))
+
+(def ^:private show-root-selector
+  [:db/id
+   :db/ident
+   :block/name
+   :block/uuid
+   :block/title
+   :logseq.property/created-from-property
+   {:logseq.property/status [:db/ident :block/title]}
+   {:block/page [:db/id :block/title :block/name :block/uuid]}
+   {:block/tags [:db/id :db/ident :block/name :block/title :block/uuid]}])
+
+(def ^:private tree-block-selector
+  [:db/id
+   :db/ident
+   :block/uuid
+   :block/title
+   :logseq.property/created-from-property
+   {:logseq.property/status [:db/ident :block/title]}
+   :block/order
+   {:block/parent [:db/id]}
+   {:block/tags [:db/id :block/name :block/title :block/uuid]}])
+
+(def ^:private linked-ref-selector
+  [:db/id
+   :db/ident
+   :block/uuid
+   :block/title
+   :logseq.property/created-from-property
+   {:logseq.property/status [:db/ident :block/title]}
+   {:block/tags [:db/id :block/name :block/title :block/uuid]}
+   {:block/page [:db/id :block/name :block/title :block/uuid]}
+   {:block/parent [:db/id
+                   :block/name
+                   :block/title
+                   :block/uuid
+                   {:block/page [:db/id :block/name :block/title :block/uuid]}]}])
+
+(declare tree->text
+         attach-user-properties
+         attach-user-properties-to-entity)
+
+(def ^:private uuid-ref-pattern #"\[\[([0-9a-fA-F-]{36})\]\]")
+(def ^:private uuid-ref-max-depth 10)
+
+(defn- tag-label
+  [tag]
+  (or (:block/title tag)
+      (:block/name tag)
+      (some-> (:block/uuid tag) str)))
+
+(defn- replace-uuid-refs-once
+  [value uuid->label]
+  (if (and (string? value) (seq uuid->label))
+    (string/replace value uuid-ref-pattern
+                    (fn [[_ id]]
+                      (if-let [label (get uuid->label (string/lower-case id))]
+                        (str "[[" label "]]")
+                        (str "[[" id "]]"))))
+    value))
+
+(defn- replace-uuid-refs
+  [value uuid->label]
+  (loop [current value
+         remaining uuid-ref-max-depth]
+    (if (or (not (string? current)) (zero? remaining) (empty? uuid->label))
+      current
+      (let [next (replace-uuid-refs-once current uuid->label)]
+        (if (= next current)
+          current
+          (recur next (dec remaining)))))))
+
+(defn- tags->suffix
+  [tags]
+  (let [labels (->> tags
+                    (map tag-label)
+                    (remove string/blank?))]
+    (when (seq labels)
+      (string/join " " (map #(style/bold (str "#" %)) labels)))))
+
+(def ^:private displayable-built-in-properties
+  "Built-in properties that are displayed alongside user properties."
+  (set/difference db-property/public-built-in-properties
+                  ;; Exclude built-in properties handled elsewhere in this command
+                  #{:block/tags :logseq.property/status}))
+
+(defn- user-property-key?
+  [k]
+  (and (qualified-keyword? k)
+       (= db-property/default-user-namespace (namespace k))))
+
+(defn- displayable-property-key?
+  [k]
+  (or (user-property-key? k)
+      (contains? displayable-built-in-properties k)))
+
+(defn- nonblank-string
+  [value]
+  (when (and (string? value) (not (string/blank? value)))
+    value))
+
+(defn- lookup-ref?
+  [value]
+  (and (vector? value)
+       (= 2 (count value))
+       (= :block/uuid (first value))
+       (uuid? (second value))))
+
+(defn- epoch-ms->iso-string
+  [ms]
+  (when-not (number? ms)
+    (throw (ex-info "datetime value must be a number"
+                    {:code :invalid-datetime-value
+                     :value ms})))
+  (when-not (js/Number.isFinite ms)
+    (throw (ex-info "datetime value must be finite"
+                    {:code :invalid-datetime-value
+                     :value ms})))
+  (.toISOString (js/Date. ms)))
+
+(defn- property-value->string
+  ([value] (property-value->string value nil))
+  ([value labels]
+   (cond
+     (string? value) (nonblank-string value)
+     (number? value) (or (get labels value) (str value))
+     (uuid? value) (or (get labels value) (str value))
+     (lookup-ref? value) (let [uuid (second value)]
+                           (or (get labels uuid) (str uuid)))
+     (boolean? value) (str value)
+     (keyword? value) (str value)
+     (map? value) (or (nonblank-string (:block/title value))
+                      (nonblank-string (:block/name value))
+                      (when-let [id (:db/id value)]
+                        (get labels id))
+                      (when-let [uuid (:block/uuid value)]
+                        (get labels uuid))
+                      (when-let [val (:logseq.property/value value)]
+                        (if (string? val)
+                          (nonblank-string val)
+                          (str val)))
+                      (pr-str value))
+     (some? value) (str value)
+     :else nil)))
+
+(defn- normalize-property-values
+  ([value] (normalize-property-values value nil))
+  ([value labels]
+   (let [values (cond
+                  (set? value) (seq value)
+                  (sequential? value) value
+                  (nil? value) nil
+                  :else [value])
+         rendered (->> values
+                       (map #(property-value->string % labels))
+                       (remove string/blank?)
+                       vec)]
+     (if (set? value)
+       (vec (sort rendered))
+       rendered))))
+
+(defn- node-user-property-entries
+  ([node] (node-user-property-entries node nil))
+  ([node labels]
+   (->> node
+        (filter (fn [[k _]] (displayable-property-key? k)))
+        (map (fn [[k v]] [k (normalize-property-values v labels)]))
+        (remove (fn [[_ values]] (empty? values)))
+        vec)))
+
+(defn- sort-property-entries
+  [property-entries]
+  (sort-by (comp name first) property-entries))
+
+(defn- property-title-for
+  [property-titles property-key]
+  (let [title (get property-titles property-key)]
+    (nonblank-string title)))
+
+(defn- format-property-lines
+  [indent title values]
+  (let [title* (style/bold title)]
+    (when (seq values)
+      (if (= 1 (count values))
+        [(str indent title* ": " (first values))]
+        (let [item-indent (str indent "  ")]
+          (into [(str indent title* ":")]
+                (map #(str item-indent "- " %) values)))))))
+
+(defn- node-property-lines
+  [node property-titles property-value-labels indent]
+  (let [property-entries (->> (node-user-property-entries node property-value-labels)
+                              sort-property-entries)]
+    (->> property-entries
+         (mapcat (fn [[property-key values]]
+                   (when-let [title (property-title-for property-titles property-key)]
+                     (format-property-lines indent title values))))
+         vec)))
+
+(def ^:private status-color-map
+  {:logseq.property/status.backlog style/magenta
+   :logseq.property/status.todo style/yellow
+   :logseq.property/status.doing style/blue
+   :logseq.property/status.in-review style/cyan
+   :logseq.property/status.done style/green
+   :logseq.property/status.canceled style/red})
+
+(defn- style-status
+  [status]
+  (when (seq status)
+    (let [color-fn (get status-color-map (:db/ident status) identity)]
+      (style/bold (color-fn (:block/title status))))))
+
+(defn- block-label
+  [node]
+  (let [text (:block/title node)
+        status (style-status (:logseq.property/status node))
+        uuid->label (:uuid->label node)
+        base (cond
+               (and text (seq status)) (str status " " text)
+               text text
+               (:block/name node) (:block/name node)
+               (:block/uuid node) (some-> (:block/uuid node) str))
+        base (replace-uuid-refs base uuid->label)
+        tags-suffix (tags->suffix (:block/tags node))]
+    (cond
+      (and base tags-suffix) (str base " " tags-suffix)
+      tags-suffix tags-suffix
+      :else base)))
+
+(defn- resolve-uuid-refs-in-node
+  [node uuid->label]
+  (cond-> node
+    (:block/title node) (update :block/title replace-uuid-refs uuid->label)
+    (:block/name node) (update :block/name replace-uuid-refs uuid->label)
+    (:block/children node) (update :block/children (fn [children]
+                                                     (mapv #(resolve-uuid-refs-in-node % uuid->label) children)))
+    (:block/page node) (update :block/page (fn [page]
+                                             (if (map? page)
+                                               (resolve-uuid-refs-in-node page uuid->label)
+                                               page)))
+    (:block/tags node) (update :block/tags (fn [tags]
+                                             (mapv #(resolve-uuid-refs-in-node % uuid->label) tags)))))
+
+(defn- resolve-uuid-refs-in-tree-data
+  [{:keys [linked-references] :as tree-data} uuid->label]
+  (let [resolve-node #(resolve-uuid-refs-in-node % uuid->label)]
+    (cond-> (update tree-data :root resolve-node)
+      (seq (:blocks linked-references))
+      (update :linked-references
+              (fn [refs]
+                (update refs :blocks #(mapv resolve-node %)))))))
+
+(defn- page-label
+  [block]
+  (let [page (:block/page block)]
+    (or (:block/title page)
+        (:block/name page)
+        (some-> (:block/uuid page) str)
+        (some-> (:block/uuid block) str))))
+
+(defn- fetch-linked-references
+  [config repo root-id]
+  (p/let [refs (transport/invoke config :thread-api/get-block-refs false [repo root-id])
+          ref-ids (vec (keep :db/id refs))
+          pulled (if (seq ref-ids)
+                   (p/all (map (fn [id]
+                                 (transport/invoke config :thread-api/pull false [repo linked-ref-selector id]))
+                               ref-ids))
+                   [])]
+    (let [blocks (vec (remove (fn [block]
+                                (or (nil? block)
+                                    (property-value-block? block)))
+                              pulled))
+          page-lookup-key (fn [value]
+                            (cond
+                              (map? value) (or (:db/id value)
+                                               (when-let [uuid (:block/uuid value)]
+                                                 [:block/uuid uuid]))
+                              (number? value) value
+                              (uuid? value) [:block/uuid value]
+                              (and (string? value) (common-util/uuid-string? value)) [:block/uuid (uuid value)]
+                              :else nil))
+          page-id-from (fn [block]
+                         (let [page (:block/page block)
+                               parent (:block/parent block)
+                               parent-page (:block/page parent)]
+                           (or (page-lookup-key page)
+                               (page-lookup-key parent-page)
+                               (page-lookup-key parent))))
+          page-ids (->> blocks
+                        (keep page-id-from)
+                        distinct
+                        vec)]
+      (p/let [blocks (attach-user-properties config repo blocks)
+              pages (if (seq page-ids)
+                      (p/all (map (fn [id]
+                                    (transport/invoke config :thread-api/pull false
+                                                      [repo [:db/id :block/name :block/title :block/uuid] id]))
+                                  page-ids))
+                      [])]
+        (let [page-id->page (zipmap page-ids pages)
+              blocks (mapv (fn [block]
+                             (let [page (:block/page block)
+                                   parent (:block/parent block)
+                                   parent-page (:block/page parent)
+                                   page-id (page-id-from block)
+                                   page (or (when (map? page)
+                                              (select-keys page [:db/id :block/name :block/title :block/uuid]))
+                                            (when (map? parent-page)
+                                              (select-keys parent-page [:db/id :block/name :block/title :block/uuid]))
+                                            (get page-id->page page-id)
+                                            (when (map? parent)
+                                              (select-keys parent [:db/id :block/name :block/title :block/uuid]))
+                                            (when (or (:block/title block) (:block/name block) (:block/uuid block))
+                                              (select-keys block [:db/id :block/name :block/title :block/uuid])))]
+                               (cond-> (dissoc block :block/parent)
+                                 page (assoc :block/page page))))
+                           blocks)]
+          {:count (count blocks)
+           :blocks blocks})))))
+
+(defn- linked-refs->text
+  [blocks uuid->label property-titles property-value-labels]
+  (let [page-key (fn [block]
+                   (let [page (:block/page block)]
+                     (or (:db/id page)
+                         (:block/uuid page)
+                         (page-label block))))
+        page-node (fn [block]
+                    (let [page (:block/page block)]
+                      (cond
+                        (map? page) page
+                        (some? page) {:db/id page}
+                        :else {})))
+        groups (->> blocks
+                    (group-by page-key)
+                    (sort-by (fn [[_ page-blocks]]
+                               (page-label (first page-blocks)))))]
+    (string/join
+     "\n\n"
+     (map (fn [[_ page-blocks]]
+            (let [root (page-node (first page-blocks))
+                  root (assoc root :block/children (vec page-blocks))]
+              (tree->text {:root root
+                           :uuid->label uuid->label
+                           :property-titles property-titles
+                           :property-value-labels property-value-labels})))
+          groups))))
+
+(defn- extract-uuid-refs
+  [value]
+  (->> (re-seq uuid-ref-pattern (or value ""))
+       (map second)
+       (filter common-util/uuid-string?)
+       distinct))
+
+(defn- collect-uuid-refs
+  [{:keys [root]} linked-refs]
+  (let [collect-nodes (fn collect-nodes [node]
+                        (if-let [children (:block/children node)]
+                          (into [node] (mapcat collect-nodes children))
+                          [node]))
+        nodes (when root (collect-nodes root))
+        ref-blocks (:blocks linked-refs)
+        pages (keep :block/page ref-blocks)
+        texts (->> (concat nodes ref-blocks pages)
+                   (mapcat (fn [node] (keep node [:block/title :block/name])))
+                   (remove string/blank?))]
+    (->> texts
+         (mapcat extract-uuid-refs)
+         distinct
+         vec)))
+
+(defn- uuid-entity-label
+  [entity]
+  (let [uuid-str (some-> (:block/uuid entity) str)]
+    (or (:block/title entity)
+        (:block/name entity)
+        uuid-str)))
+
+(defn- fetch-uuid-entities
+  [config repo uuid-strings]
+  (if (seq uuid-strings)
+    (p/let [blocks (p/all (map (fn [uuid-str]
+                                 (transport/invoke config :thread-api/pull false
+                                                   [repo [:db/id :block/uuid :block/title :block/name]
+                                                    [:block/uuid (uuid uuid-str)]]))
+                               uuid-strings))]
+      (->> blocks
+           (remove nil?)
+           (map (fn [block]
+                  (let [uuid-str (some-> (:block/uuid block) str)]
+                    [(string/lower-case uuid-str)
+                     {:id (:db/id block)
+                      :label (uuid-entity-label block)}])))
+           (into {})))
+    (p/resolved {})))
+
+(defn- collect-user-property-keys
+  [{:keys [root linked-references]}]
+  (letfn [(collect-node [node]
+            (let [node-keys (->> (keys node)
+                                 (filter displayable-property-key?))]
+              (reduce (fn [acc child]
+                        (into acc (collect-node child)))
+                      (set node-keys)
+                      (or (:block/children node) []))))]
+    (let [root-keys (if root (collect-node root) #{})
+          linked-keys (reduce (fn [acc block]
+                                (into acc (collect-node block)))
+                              #{}
+                              (or (:blocks linked-references) []))]
+      (into root-keys linked-keys))))
+
+(defn- property-value-label
+  [entity]
+  (when (map? entity)
+    (or (nonblank-string (:block/title entity))
+        (nonblank-string (:block/name entity))
+        (when-let [val (:logseq.property/value entity)]
+          (if (string? val)
+            (nonblank-string val)
+            (str val))))))
+
+(defn- collect-property-value-refs
+  [{:keys [root linked-references]}]
+  (letfn [(collect-value [acc value]
+            (cond
+              (lookup-ref? value)
+              (update acc :uuids conj (second value))
+
+              (uuid? value)
+              (update acc :uuids conj value)
+
+              (number? value)
+              (update acc :ids conj value)
+
+              (map? value)
+              (let [resolved? (or (nonblank-string (:block/title value))
+                                  (nonblank-string (:block/name value))
+                                  (some? (:logseq.property/value value)))]
+                (if resolved?
+                  acc
+                  (cond-> acc
+                    (:block/uuid value) (update :uuids conj (:block/uuid value))
+                    (:db/id value) (update :ids conj (:db/id value)))))
+
+              (set? value)
+              (reduce collect-value acc value)
+
+              (sequential? value)
+              (reduce collect-value acc value)
+
+              :else acc))
+          (collect-node [acc node]
+            (let [acc (reduce (fn [acc [k v]]
+                                (if (displayable-property-key? k)
+                                  (collect-value acc v)
+                                  acc))
+                              acc
+                              node)]
+              (reduce collect-node acc (or (:block/children node) []))))]
+    (let [init {:ids #{} :uuids #{}}
+          acc-root (if root (collect-node init root) init)]
+      (reduce collect-node acc-root (or (:blocks linked-references) [])))))
+
+(defn- property-visible?
+  [entity]
+  (and (map? entity)
+       (not (true? (:logseq.property/hide? entity)))
+       (not (false? (:logseq.property/public? entity)))))
+
+(defn- property-entity-title
+  [entity]
+  (or (nonblank-string (:block/title entity))
+      (nonblank-string (:block/name entity))))
+
+(defn- property-value-block?
+  [block]
+  (some? (:logseq.property/created-from-property block)))
+
+(defn- fetch-property-titles
+  [config repo property-keys]
+  (if (seq property-keys)
+    (let [keys (vec property-keys)
+          selector [:db/id :db/ident :block/title :block/name
+                    :logseq.property/hide? :logseq.property/public?]]
+      (p/let [entities (p/all (map (fn [property-key]
+                                     (transport/invoke config :thread-api/pull false
+                                                       [repo selector [:db/ident property-key]]))
+                                   keys))]
+        (->> (map vector keys entities)
+             (keep (fn [[property-key entity]]
+                     (when (property-visible? entity)
+                       (when-let [title (property-entity-title entity)]
+                         [property-key title]))))
+             (into {}))))
+    (p/resolved {})))
+
+(defn- fetch-property-value-labels
+  [config repo {:keys [ids uuids]}]
+  (if (or (seq ids) (seq uuids))
+    (let [selector [:db/id :block/uuid :block/title :block/name :logseq.property/value]
+          ids* (vec ids)
+          uuids* (vec uuids)]
+      (p/let [id-entities (if (seq ids*)
+                            (p/all (map (fn [id]
+                                          (transport/invoke config :thread-api/pull false
+                                                            [repo selector id]))
+                                        ids*))
+                            [])
+              uuid-entities (if (seq uuids*)
+                              (p/all (map (fn [uuid]
+                                            (transport/invoke config :thread-api/pull false
+                                                              [repo selector [:block/uuid uuid]]))
+                                          uuids*))
+                              [])]
+        (->> (concat id-entities uuid-entities)
+             (remove nil?)
+             (reduce (fn [acc entity]
+                       (if-let [label (property-value-label entity)]
+                         (cond-> acc
+                           (:db/id entity) (assoc (:db/id entity) label)
+                           (:block/uuid entity) (assoc (:block/uuid entity) label))
+                         acc))
+                     {}))))
+    (p/resolved {})))
+
+(defn- merge-fetched-property-value
+  [existing value]
+  (cond
+    (nil? existing) value
+    (= existing value) existing
+    (sequential? existing) (if (some #(= % value) existing)
+                             existing
+                             (conj (vec existing) value))
+    :else [existing value]))
+
+(defn- fetch-user-properties
+  [config repo block-ids]
+  (if (seq block-ids)
+    (let [idents-query '[:find ?a ?type
+                         :where
+                         [?e :db/ident ?a]
+                         [(namespace ?a) ?ns]
+                         [(= "user.property" ?ns)]
+                         [(get-else $ ?e :logseq.property/type :default) ?type]]
+          built-in-query '[:find ?a ?type
+                           :in $ [?a ...]
+                           :where
+                           [?e :db/ident ?a]
+                           [(get-else $ ?e :logseq.property/type :default) ?type]]
+          props-query '[:find ?b ?a ?v
+                        :in $ [?b ...] [?a ...]
+                        :where
+                        [?b ?a ?v]]
+          ids (vec block-ids)
+          built-in-idents (vec displayable-built-in-properties)]
+      (p/let [user-pairs (transport/invoke config :thread-api/q false [repo [idents-query]])
+              built-in-pairs (transport/invoke config :thread-api/q false
+                                               [repo [built-in-query built-in-idents]])
+              ident-type-pairs (into (vec user-pairs) built-in-pairs)
+              datetime-idents (set (keep (fn [[a type]] (when (= :datetime type) a)) ident-type-pairs))
+              property-idents (vec (map first ident-type-pairs))]
+        (if (seq property-idents)
+          (p/let [rows (transport/invoke config :thread-api/q false
+                                         [repo [props-query ids property-idents]])]
+            (reduce (fn [acc [block-id attr value]]
+                      (let [value (if (and (number? value) (contains? datetime-idents attr))
+                                    (epoch-ms->iso-string value)
+                                    value)]
+                        (update-in acc [block-id attr] merge-fetched-property-value value)))
+                    {}
+                    rows))
+          {})))
+    (p/resolved {})))
+
+(defn- attach-user-properties
+  [config repo blocks]
+  (let [block-ids (vec (keep :db/id blocks))]
+    (p/let [id->props (fetch-user-properties config repo block-ids)]
+      (mapv (fn [block]
+              (if-let [props (get id->props (:db/id block))]
+                (merge block props)
+                block))
+            blocks))))
+
+(defn- attach-user-properties-to-entity
+  [config repo entity]
+  (if-let [block-id (:db/id entity)]
+    (p/let [id->props (fetch-user-properties config repo [block-id])]
+      (if-let [props (get id->props block-id)]
+        (merge entity props)
+        entity))
+    (p/resolved entity)))
+
+(defn- attach-property-titles
+  [config repo tree-data]
+  (let [property-keys (collect-user-property-keys tree-data)
+        value-refs (collect-property-value-refs tree-data)]
+    (p/let [titles (fetch-property-titles config repo property-keys)
+            value-labels (fetch-property-value-labels config repo value-refs)]
+      (assoc tree-data
+             :property-titles titles
+             :property-value-labels value-labels))))
+
+(defn- fetch-blocks-for-page
+  [config repo page-id]
+  (let [query [:find (list 'pull '?b tree-block-selector)
+               :in '$ '?page-id
+               :where ['?b :block/page '?page-id]]]
+    (p/let [rows (transport/invoke config :thread-api/q false [repo [query page-id]])
+            blocks (->> rows
+                        (map first)
+                        (remove property-value-block?)
+                        vec)
+            blocks (attach-user-properties config repo blocks)]
+      blocks)))
+
+(defn- build-tree
+  [blocks root-id max-depth]
+  (let [parent->children (group-by #(get-in % [:block/parent :db/id]) blocks)
+        sort-children (fn [children]
+                        (vec (sort-by :block/order children)))
+        build (fn build [parent-id depth]
+                (mapv (fn [b]
+                        (let [children (build (:db/id b) (inc depth))]
+                          (cond-> b
+                            (seq children) (assoc :block/children children))))
+                      (if (and max-depth (>= depth max-depth))
+                        []
+                        (sort-children (get parent->children parent-id)))))]
+    (build root-id 1)))
+
+(defn- entity-id-only?
+  [entity]
+  (and (map? entity)
+       (contains? entity :db/id)
+       (= #{:db/id} (set (keys entity)))))
+
+(defn- missing-show-entity?
+  [entity]
+  (or (nil? entity)
+      (entity-id-only? entity)))
+
+(defn- fetch-tree
+  [config {:keys [repo id page level] :as opts}]
+  (let [max-depth (or level 10)
+        uuid-str (:uuid opts)]
+    (cond
+      (some? id)
+      (p/let [entity (transport/invoke config :thread-api/pull false
+                                       [repo show-root-selector id])]
+        (p/let [entity (attach-user-properties-to-entity config repo entity)]
+          (if (missing-show-entity? entity)
+            (throw (ex-info "entity not found" {:code :entity-not-found}))
+            (if-let [page-id (get-in entity [:block/page :db/id])]
+              (p/let [blocks (fetch-blocks-for-page config repo page-id)
+                      children (build-tree blocks (:db/id entity) max-depth)]
+                {:root (assoc entity :block/children children)})
+              (if-let [entity-id (:db/id entity)]
+                (p/let [blocks (fetch-blocks-for-page config repo entity-id)
+                        children (build-tree blocks entity-id max-depth)]
+                  {:root (assoc entity :block/children children)})
+                (throw (ex-info "entity not found" {:code :entity-not-found})))))))
+
+      (seq uuid-str)
+      (p/let [entity (transport/invoke config :thread-api/pull false
+                                       [repo show-root-selector
+                                        [:block/uuid (uuid uuid-str)]])
+              entity (if (:db/id entity)
+                       entity
+                       (transport/invoke config :thread-api/pull false
+                                         [repo show-root-selector
+                                          [:block/uuid uuid-str]]))]
+        (p/let [entity (attach-user-properties-to-entity config repo entity)]
+          (if (missing-show-entity? entity)
+            (throw (ex-info "entity not found" {:code :entity-not-found}))
+            (if-let [page-id (get-in entity [:block/page :db/id])]
+              (p/let [blocks (fetch-blocks-for-page config repo page-id)
+                      children (build-tree blocks (:db/id entity) max-depth)]
+                {:root (assoc entity :block/children children)})
+              (if-let [entity-id (:db/id entity)]
+                (p/let [blocks (fetch-blocks-for-page config repo entity-id)
+                        children (build-tree blocks entity-id max-depth)]
+                  {:root (assoc entity :block/children children)})
+                (throw (ex-info "entity not found" {:code :entity-not-found})))))))
+
+      (seq page)
+      (p/let [page-entity (transport/invoke config :thread-api/pull false
+                                            [repo [:db/id :db/ident :block/uuid :block/title
+                                                   :logseq.property/deleted-at
+                                                   {:logseq.property/status [:db/ident :block/title]}
+                                                   {:block/tags [:db/id :block/name :block/title :block/uuid]}]
+                                             [:block/name page]])]
+        (p/let [page-entity (attach-user-properties-to-entity config repo page-entity)]
+          (if-let [page-id (and (not (ldb/recycled? page-entity))
+                                (:db/id page-entity))]
+            (p/let [blocks (fetch-blocks-for-page config repo page-id)
+                    children (build-tree blocks page-id max-depth)]
+              {:root (assoc (dissoc page-entity :logseq.property/deleted-at)
+                            :block/children children)})
+            (throw (ex-info "page not found" {:code :page-not-found})))))
+
+      :else
+      (p/rejected (ex-info "block or page required" {:code :missing-target})))))
+
+(defn tree->text
+  [{:keys [root uuid->label property-titles property-value-labels]}]
+  (let [label (fn [node]
+                (or (block-label (assoc node :uuid->label uuid->label)) "-"))
+        collect-nodes (fn collect-nodes [node]
+                        (if-let [children (:block/children node)]
+                          (into [node] (mapcat collect-nodes children))
+                          [node]))
+        nodes (collect-nodes root)
+        id-width (id-column-width nodes)
+        id-padding (render-id-column-padding id-width)
+        split-lines (fn [value]
+                      (string/split (or value "") #"\n"))
+        style-glyph (fn [value]
+                      (style/dim value))
+        lines (atom [])
+        property-indent (fn [prefix]
+                          (str id-padding (style-glyph prefix)))
+        append-property-lines (fn [node prefix]
+                                (let [indent (property-indent prefix)
+                                      prop-lines (node-property-lines node property-titles property-value-labels indent)]
+                                  (doseq [line prop-lines]
+                                    (swap! lines conj line))))
+        walk (fn walk [node prefix]
+               (let [children (:block/children node)
+                     total (count children)]
+                 (doseq [[idx child] (map-indexed vector children)]
+                   (let [last-child? (= idx (dec total))
+                         branch (if last-child? "└── " "├── ")
+                         next-prefix (str prefix (if last-child? "    " "│   "))
+                         rows (split-lines (label child))
+                         first-row (first rows)
+                         rest-rows (rest rows)
+                         line (str (render-id-column child id-width) " "
+                                   (style-glyph prefix)
+                                   (style-glyph branch)
+                                   first-row)]
+                     (swap! lines conj line)
+                     (doseq [row rest-rows]
+                       (swap! lines conj (str id-padding (style-glyph next-prefix) row)))
+                     (append-property-lines child next-prefix)
+                     (walk child next-prefix)))))]
+    (let [rows (split-lines (label root))
+          first-row (first rows)
+          rest-rows (rest rows)]
+      (swap! lines conj (str (render-id-column root id-width) " " first-row))
+      (doseq [row rest-rows]
+        (swap! lines conj (str id-padding row))))
+    (append-property-lines root "")
+    (walk root "")
+    (string/join "\n" @lines)))
+
+(defn- tree->text-with-linked-refs
+  [{:keys [linked-references uuid->label property-titles property-value-labels] :as tree-data}]
+  (let [tree-text (tree->text tree-data)
+        refs (:blocks linked-references)
+        count (:count linked-references)]
+    (if (seq refs)
+      (str tree-text
+           "\n\n"
+           "Linked References ("
+           (cli-humanize/format-count count)
+           ")\n"
+           (linked-refs->text refs uuid->label property-titles property-value-labels))
+      tree-text)))
+
+(defn- referenced-entity-row
+  [uuid uuid->entity]
+  (let [{:keys [id label]} (get uuid->entity (string/lower-case uuid))
+        id* (or id "-")
+        label* (or label uuid)]
+    (str id* " -> " label*)))
+
+(defn- render-referenced-entities-footer
+  [ordered-uuids uuid->entity]
+  (let [ordered-uuids (vec (distinct (remove string/blank? ordered-uuids)))]
+    (when (seq ordered-uuids)
+      (str "Referenced Entities ("
+           (cli-humanize/format-count (count ordered-uuids))
+           ")\n"
+           (string/join "\n" (map #(referenced-entity-row % uuid->entity) ordered-uuids))))))
+
+(defn build-action
+  [options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for show"}}
+    (let [options (resolve-stdin-id options)
+          id-result (id-command/parse-id-option (:id options))
+          ids (:value id-result)
+          multi-id? (:multi? id-result)
+          targets (filter some? [(:id options) (:uuid options) (:page options)])]
+      (if (empty? targets)
+        {:ok? false
+         :error {:code :missing-target
+                 :message "block or page is required"}}
+        (if (and (some? (:id options)) (not (:ok? id-result)))
+          {:ok? false
+           :error {:code :invalid-options
+                   :message (:message id-result)}}
+          {:ok? true
+           :action {:type :show
+                    :repo repo
+                    :id (when (and (seq ids) (not multi-id?)) (first ids))
+                    :ids ids
+                    :multi-id? multi-id?
+                    :linked-references? (if (contains? options :linked-references)
+                                          (:linked-references options)
+                                          true)
+                    :ref-id-footer? (if (contains? options :ref-id-footer)
+                                      (:ref-id-footer options)
+                                      true)
+                    :uuid (:uuid options)
+                    :page (:page options)
+                    :level (:level options)}})))))
+
+(defn- build-tree-data
+  [config action]
+  (p/let [tree-data (fetch-tree config action)
+          root-id (get-in tree-data [:root :db/id])
+          linked-enabled? (not= false (:linked-references? action))
+          linked-refs (when (and linked-enabled? root-id)
+                        (fetch-linked-references config (:repo action) root-id))
+          linked-refs* (if linked-enabled?
+                         (or linked-refs {:count 0 :blocks []})
+                         {:count 0 :blocks []})
+          uuid-refs (collect-uuid-refs tree-data linked-refs*)
+          uuid->entity (fetch-uuid-entities config (:repo action) uuid-refs)
+          uuid->label (->> uuid->entity
+                           (keep (fn [[uuid-key {:keys [label]}]]
+                                   (when (seq label)
+                                     [uuid-key label])))
+                           (into {}))
+          tree-data (cond-> (assoc tree-data
+                                   :referenced-uuids uuid-refs
+                                   :uuid->entity uuid->entity
+                                   :uuid->label uuid->label)
+                      linked-enabled? (assoc :linked-references linked-refs*))
+          tree-data (resolve-uuid-refs-in-tree-data tree-data uuid->label)]
+    tree-data))
+
+(defn- multi-id-error-message
+  [id error]
+  (let [data (ex-data error)
+        code (:code data)
+        message (or (:message data) (.-message error) (str error))]
+    (if (or (= code :block-not-found)
+            (= code :entity-not-found))
+      (str "Entity " id " not found")
+      (str "Entity " id ": " message))))
+
+(defn- multi-id-error-entry
+  [id error]
+  (let [data (ex-data error)
+        code (:code data)
+        message (multi-id-error-message id error)
+        error-map (cond-> {:message message}
+                    code (assoc :code code))]
+    {:id id
+     :error error-map}))
+
+(defn- collect-tree-ids
+  [root]
+  (letfn [(walk [node acc]
+            (let [acc (cond-> acc
+                        (:db/id node) (conj (:db/id node)))]
+              (reduce (fn [memo child]
+                        (walk child memo))
+                      acc
+                      (or (:block/children node) []))))]
+    (if root
+      (walk root #{})
+      #{})))
+
+(defn- strip-block-uuid
+  [tree-data]
+  (walk/postwalk
+   (fn [entry]
+     (if (map? entry)
+       (dissoc entry :block/uuid)
+       entry))
+   tree-data))
+
+(defn- strip-show-internal-data
+  [tree-data]
+  (dissoc tree-data :referenced-uuids :uuid->entity))
+
+(defn- render-tree-text
+  [tree-data action]
+  (let [tree-text (if (false? (:linked-references? action))
+                    (tree->text tree-data)
+                    (tree->text-with-linked-refs tree-data))
+        breadcrumb-line (:breadcrumb-line tree-data)
+        tree-text (if (seq breadcrumb-line)
+                    (str breadcrumb-line "\n" tree-text)
+                    tree-text)
+        footer-enabled? (not= false (:ref-id-footer? action))
+        linked-refs (when (not= false (:linked-references? action))
+                      (:linked-references tree-data))
+        ordered-uuids (or (:referenced-uuids tree-data)
+                          (collect-uuid-refs tree-data linked-refs))
+        footer (when footer-enabled?
+                 (render-referenced-entities-footer ordered-uuids (:uuid->entity tree-data)))]
+    (if (seq footer)
+      (str tree-text "\n\n" footer)
+      tree-text)))
+
+(defn- attach-breadcrumb-line
+  [config action tree-data]
+  (p/let [parents (fetch-breadcrumb-parents config (:repo action) (:root tree-data))
+          breadcrumb-line (render-breadcrumb-line parents)]
+    (if (seq breadcrumb-line)
+      (assoc tree-data :breadcrumb-line breadcrumb-line)
+      tree-data)))
+
+(defn- render-tree-text-with-properties
+  [config action tree-data]
+  (p/let [tree-data (attach-property-titles config (:repo action) tree-data)
+          tree-data (attach-breadcrumb-line config action tree-data)]
+    (render-tree-text tree-data action)))
+
+(defn- sanitize-structured-tree
+  [tree-data]
+  (-> tree-data
+      strip-show-internal-data
+      strip-block-uuid))
+
+(defn- structured-show-result
+  [mode data]
+  {:status :ok
+   :data data
+   :output-format mode})
+
+(defn- multi-id-structured-data
+  [results]
+  (mapv (fn [{:keys [ok? tree id error]}]
+          (if ok?
+            (sanitize-structured-tree tree)
+            (multi-id-error-entry id error)))
+        results))
+
+(defn execute-show
+  [action config]
+  (p/let [cfg (cli-server/ensure-server! config (:repo action))
+          mode (output-mode/parse (:output-format config))
+          ids (:ids action)
+          multi-id? (:multi-id? action)]
+    (if (and (seq ids) multi-id?)
+      (p/let [results (p/all (map (fn [id]
+                                    (-> (build-tree-data cfg (assoc action :id id))
+                                        (p/then (fn [tree-data]
+                                                  {:ok? true
+                                                   :id id
+                                                   :tree tree-data}))
+                                        (p/catch (fn [error]
+                                                   {:ok? false
+                                                    :id id
+                                                    :error error}))))
+                                  ids))
+              ok-results (filter :ok? results)
+              id->tree-ids (into {}
+                                 (map (fn [{:keys [id tree]}]
+                                        [id (collect-tree-ids (:root tree))]))
+                                 ok-results)
+              contained? (fn [id]
+                           (some (fn [[other-id tree-ids]]
+                                   (and (not= other-id id)
+                                        (contains? tree-ids id)))
+                                 id->tree-ids))
+              results (vec (remove (fn [{:keys [ok? id]}]
+                                     (and ok? (contained? id)))
+                                   results))
+              render-result (fn [{:keys [ok? tree id error]}]
+                              (if ok?
+                                (render-tree-text-with-properties cfg action tree)
+                                (multi-id-error-message id error)))]
+        (if (output-mode/structured? mode)
+          (structured-show-result mode (multi-id-structured-data results))
+          (p/let [messages (p/all (map render-result results))]
+            {:status :ok
+             :data {:message (string/join multi-id-delimiter messages)}})))
+      (p/let [tree-data (build-tree-data cfg action)]
+        (if (output-mode/structured? mode)
+          (structured-show-result mode (sanitize-structured-tree tree-data))
+          (p/let [message (render-tree-text-with-properties cfg action tree-data)]
+            {:status :ok
+             :data {:message message}}))))))
diff --git a/src/main/logseq/cli/command/skill.cljs b/src/main/logseq/cli/command/skill.cljs
new file mode 100644
index 0000000000..a6d3d312ed
--- /dev/null
+++ b/src/main/logseq/cli/command/skill.cljs
@@ -0,0 +1,157 @@
+(ns logseq.cli.command.skill
+  "Skill utility commands for exposing the built-in logseq-cli skill markdown."
+  (:require ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]
+            [clojure.string :as string]
+            [logseq.cli.command.core :as core]
+            [logseq.common.path :as path]))
+
+(def ^:private skill-dir-name "logseq-cli")
+(def ^:private skill-file-name "SKILL.md")
+(def ^:private relative-skill-path [".agents" "skills" skill-dir-name skill-file-name])
+
+(def ^:private install-spec
+  {:global {:desc "Install to ~/.agents/skills/logseq-cli"
+            :coerce :boolean}})
+
+(def entries
+  [(core/command-entry ["skill" "show"]
+                       :skill-show
+                       "Print built-in logseq-cli skill markdown"
+                       {})
+   (core/command-entry ["skill" "install"]
+                       :skill-install
+                       "Install built-in logseq-cli skill file"
+                       install-spec
+                       {:examples ["logseq skill install"
+                                   "logseq skill install --global"]})])
+
+(defn resolve-install-target
+  [{:keys [global? cwd home-dir]}]
+  (let [home-dir (some-> home-dir str string/trim)
+        cwd (or cwd (.cwd js/process))
+        base-dir (if global?
+                   (when (seq home-dir)
+                     home-dir)
+                   cwd)]
+    (if-not (seq base-dir)
+      {:ok? false
+       :error {:code :skill-home-dir-unavailable
+               :message "home directory is unavailable; cannot resolve --global install target"}}
+      (let [dir (path/path-join base-dir ".agents" "skills" skill-dir-name)]
+        {:ok? true
+         :dir dir
+         :file (path/path-join dir skill-file-name)}))))
+
+(defn resolve-skill-source-path
+  [candidates]
+  (let [candidates (->> (or candidates [])
+                        (filter string?)
+                        (filter #(seq (string/trim %)))
+                        vec)
+        path (some (fn [candidate]
+                     (when (fs/existsSync candidate)
+                       candidate))
+                   candidates)]
+    (if (seq path)
+      {:ok? true
+       :path path}
+      {:ok? false
+       :error {:code :skill-source-not-found
+               :message (str "skill source file not found. Checked paths: "
+                             (string/join ", " candidates))
+               :checked-paths candidates}})))
+
+(defn- source-path-candidates
+  []
+  (let [from-dir (fn [dir]
+                   (apply node-path/join dir relative-skill-path))]
+    [(from-dir js/__dirname)
+     (from-dir (node-path/join js/__dirname ".."))
+     (from-dir (node-path/join js/__dirname ".." ".."))
+     (from-dir (node-path/join js/__dirname ".." ".." ".."))]))
+
+(defn- resolve-action-source-path
+  [action]
+  (if-let [source-path (some-> (:source-path action) str string/trim not-empty)]
+    {:ok? true :path source-path}
+    (resolve-skill-source-path (source-path-candidates))))
+
+(defn build-show-action
+  [_options]
+  {:ok? true
+   :action {:type :skill-show}})
+
+(defn build-install-action
+  [options]
+  {:ok? true
+   :action {:type :skill-install
+            :global? (boolean (:global options))}})
+
+(defn execute-skill-show
+  [action _config]
+  (let [{:keys [ok? path error]} (resolve-action-source-path action)]
+    (if-not ok?
+      {:status :error
+       :error error}
+      (try
+        {:status :ok
+         :output-format :human
+         :data {:message (fs/readFileSync path "utf8")
+                :source-path path}}
+        (catch :default e
+          {:status :error
+           :error {:code :skill-show-failed
+                   :message (str "failed to read skill source: " (or (.-message e) e))
+                   :source-path path
+                   :cause (or (.-code e) (:code (ex-data e)))}})))))
+
+(defn- resolve-install-destination
+  [action]
+  (if (and (seq (some-> (:destination-dir action) str string/trim))
+           (seq (some-> (:destination-file action) str string/trim)))
+    {:ok? true
+     :dir (:destination-dir action)
+     :file (:destination-file action)}
+    (let [env-home (or (some-> js/process .-env .-HOME)
+                       (some-> js/process .-env .-USERPROFILE))]
+    (resolve-install-target {:global? (:global? action)
+                             :cwd (.cwd js/process)
+                             :home-dir (or env-home
+                                           (.homedir os))}))))
+
+(defn execute-skill-install
+  [action _config]
+  (let [{:keys [ok? path error]} (resolve-action-source-path action)]
+    (if-not ok?
+      {:status :error
+       :error error}
+      (let [{:keys [ok? dir file error]} (resolve-install-destination action)]
+        (if-not ok?
+          {:status :error
+           :error error}
+          (try
+            (when (and (fs/existsSync dir)
+                       (.isFile (fs/statSync dir)))
+              (throw (ex-info "destination path is a file"
+                              {:code :skill-install-invalid-destination
+                               :destination dir})))
+            (fs/mkdirSync dir #js {:recursive true})
+            (let [payload (fs/readFileSync path "utf8")]
+              (fs/writeFileSync file payload "utf8"))
+            {:status :ok
+             :data {:source-path path
+                    :installed-path file
+                    :message (str "Installed skill to " file)}}
+            (catch :default e
+              (let [data (ex-data e)
+                    code (or (:code data) (.-code e))]
+                {:status :error
+                 :error {:code (if (= :skill-install-invalid-destination code)
+                                 :skill-install-invalid-destination
+                                 :skill-install-failed)
+                         :message (str "failed to install skill: " (or (.-message e) e))
+                         :source-path path
+                         :destination file
+                         :cause code}}))))))))
diff --git a/src/main/logseq/cli/command/sync.cljs b/src/main/logseq/cli/command/sync.cljs
new file mode 100644
index 0000000000..ee76a3a0cb
--- /dev/null
+++ b/src/main/logseq/cli/command/sync.cljs
@@ -0,0 +1,838 @@
+(ns logseq.cli.command.sync
+  "Sync-related CLI commands."
+  (:require [clojure.string :as string]
+            [lambdaisland.glogi :as log]
+            [logseq.cli.auth :as cli-auth]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.common :as cli-common]
+            [logseq.cli.config :as cli-config]
+            [logseq.cli.output-mode :as output-mode]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.cognito-config :as cognito-config]
+            [promesa.core :as p]))
+
+(def ^:private sync-grant-access-spec
+  {:graph-id {:desc "Remote graph UUID"}
+   :email {:desc "Target user email"}})
+
+(def ^:private sync-start-spec
+  {:e2ee-password {:desc "Verify and persist E2EE password before sync"
+                   :coerce :string}})
+
+(def ^:private sync-upload-spec
+  {:e2ee-password {:desc "Verify and persist E2EE password before upload"
+                   :coerce :string}})
+
+(def ^:private sync-download-spec
+  {:progress {:desc "Stream realtime download progress to stdout"
+              :coerce :boolean}
+   :e2ee-password {:desc "Verify and persist E2EE password before download"
+                   :coerce :string}})
+
+(def ^:private sync-ensure-keys-spec
+  {:e2ee-password {:desc "Verify and persist E2EE password before ensuring user RSA keys"
+                   :coerce :string}
+   :upload-keys {:desc "Ensure local RSA keys are uploaded to server (checks server presence first)"
+                 :coerce :boolean}})
+
+(def entries
+  [(core/command-entry ["sync" "status"] :sync-status "Show db-sync runtime status" {}
+                       {:examples ["logseq sync status --graph my-graph"]})
+   (core/command-entry ["sync" "start"] :sync-start "Start db-sync client" sync-start-spec
+                       {:examples ["logseq sync start --graph my-graph"
+                                   "logseq sync start --graph my-graph --e2ee-password \"my-secret\""]})
+   (core/command-entry ["sync" "stop"] :sync-stop "Stop db-sync client" {}
+                       {:examples ["logseq sync stop --graph my-graph"]})
+   (core/command-entry ["sync" "upload"] :sync-upload "Upload current graph snapshot" sync-upload-spec
+                       {:examples ["logseq sync upload --graph my-graph"
+                                   "logseq sync upload --graph my-graph --e2ee-password \"my-secret\""]})
+   (core/command-entry ["sync" "download"] :sync-download "Download remote graph snapshot" sync-download-spec
+                       {:examples ["logseq sync download --graph my-graph"
+                                   "logseq sync download --graph my-graph --progress"
+                                   "logseq sync download --graph my-graph --e2ee-password \"my-secret\""]})
+   (core/command-entry ["sync" "remote-graphs"] :sync-remote-graphs "List remote graphs" {})
+   (core/command-entry ["sync" "ensure-keys"] :sync-ensure-keys "Ensure user RSA keys for sync/e2ee" sync-ensure-keys-spec
+                       {:examples ["logseq sync ensure-keys"
+                                   "logseq sync ensure-keys --upload-keys"
+                                   "logseq sync ensure-keys --e2ee-password \"my-secret\" --upload-keys"]})
+   (core/command-entry ["sync" "grant-access"] :sync-grant-access "Grant graph access to an email" sync-grant-access-spec
+                       {:examples ["logseq sync grant-access --graph my-graph --graph-id 8b6ecdd0-1fab-4a9f-b3fb-3069c5f76e95 --email teammate@example.com"]})
+   (core/command-entry ["sync" "config" "set"] :sync-config-set "Set sync config key" {}
+                       {:examples ["logseq sync config set ws-url wss://sync.logseq.com"
+                                   "logseq sync config set http-base https://api.logseq.com"
+                                   "logseq sync config set ws-url ws://localhost:12315"
+                                   "logseq sync config set http-base http://localhost:8080"
+                                   "logseq sync config set ws-url wss://example.com/socket"]})
+   (core/command-entry ["sync" "config" "get"] :sync-config-get "Get sync config key" {}
+                       {:examples ["logseq sync config get ws-url"]})
+   (core/command-entry ["sync" "config" "unset"] :sync-config-unset "Unset sync config key" {}
+                       {:examples ["logseq sync config unset ws-url"]})])
+
+(def ^:private config-key-map
+  {"ws-url" :ws-url
+   "http-base" :http-base})
+
+(def ^:private authenticated-sync-actions
+  #{:sync-start
+    :sync-upload
+    :sync-download
+    :sync-remote-graphs
+    :sync-ensure-keys
+    :sync-grant-access})
+
+(def ^:private sync-start-timeout-ms 10000)
+(def ^:private sync-start-poll-interval-ms 1000)
+(def ^:private sync-download-timeout-ms (* 30 60 1000))
+
+(def ^:private sync-start-skipped-states
+  #{:inactive :stopped})
+
+(def ^:private sync-config-defaults
+  {:ws-url "wss://api.logseq.io/sync/%s"
+   :http-base "https://api.logseq.io"})
+
+(def ^:private required-sync-config-keys-by-action
+  {:sync-start [:ws-url]
+   :sync-upload [:http-base]
+   :sync-download [:http-base]
+   :sync-grant-access [:http-base]})
+
+(defn- config-value-present?
+  [value]
+  (cond
+    (string? value) (not (string/blank? value))
+    :else (some? value)))
+
+(defn- effective-sync-config-value
+  [config key]
+  (let [sentinel ::missing
+        value (get config key sentinel)]
+    (if (= sentinel value)
+      (get sync-config-defaults key)
+      value)))
+
+(defn- missing-required-sync-config-keys
+  [action-type config]
+  (->> (get required-sync-config-keys-by-action action-type)
+       (remove (fn [key]
+                 (config-value-present? (effective-sync-config-value config key))))
+       vec))
+
+(defn- missing-sync-config-error
+  [action-type missing-keys]
+  {:status :error
+   :error {:code :missing-sync-config
+           :message (str "missing required sync config for " (name action-type)
+                         ": " (string/join ", " (map name missing-keys)))
+           :action action-type
+           :missing-keys missing-keys}})
+
+(defn- print-progress-line!
+  [line]
+  (when (seq (some-> line str string/trim))
+    (println line)))
+
+(defn- sync-download-invoke-config
+  [cfg]
+  (assoc cfg :timeout-ms (max 0 (or (:sync-download-timeout-ms cfg)
+                                    sync-download-timeout-ms))))
+
+(def ^:private sync-download-non-empty-query
+  '[:find (count ?e) .
+    :where
+    (or [?e :block/name]
+        [?e :block/page _]
+        [?e :block/parent _])
+    (not [?e :logseq.property/built-in? true])
+    (not [?e :db/ident])
+    (not [?e :file/path])])
+
+(def ^:private graph-e2ee-query
+  '[:find ?v .
+    :where
+    [?e :db/ident :logseq.kv/graph-rtc-e2ee?]
+    [?e :kv/value ?v]])
+
+(defn- missing-repo
+  [label]
+  {:ok? false
+   :error {:code :missing-repo
+           :message (str "repo is required for " label)}})
+
+(defn- invalid-options
+  [message]
+  {:ok? false
+   :error {:code :invalid-options
+           :message message}})
+
+(defn- ex-message->code
+  [message]
+  (when (and (string? message)
+             (re-matches #"[a-zA-Z0-9._/\-]+" message))
+    (keyword message)))
+
+(defn- exception->error
+  [error extra]
+  (let [data (or (ex-data error) {})
+        code (or (:code data)
+                 (ex-message->code (ex-message error))
+                 :exception)]
+    {:status :error
+     :error (merge {:code code
+                    :message (or (ex-message error) (str error))}
+                   (when (seq data) {:context data})
+                   extra)}))
+
+(defn- missing-e2ee-password-diagnostic?
+  [error]
+  (let [data (or (ex-data error) {})
+        code (:code data)
+        code' (or code (ex-message->code (ex-message error)))]
+    (contains? #{:db-sync/missing-e2ee-password
+                 :missing-e2ee-password
+                 :db-sync/invalid-e2ee-password-payload
+                 :invalid-e2ee-password-payload
+                 :decrypt-text-by-text-password}
+               code')))
+
+(defn- e2ee-password-not-found-error
+  [action-type repo]
+  {:status :error
+   :error {:code :e2ee-password-not-found
+           :message "e2ee-password not found"
+           :action action-type
+           :repo repo
+           :hint "Provide --e2ee-password to verify and persist it."}})
+
+(defn- ensure-refresh-token!
+  [config]
+  (if (seq (:refresh-token config))
+    (p/resolved (:refresh-token config))
+    (p/let [auth (cli-auth/resolve-auth! config)
+            refresh-token (:refresh-token auth)]
+      (if (seq refresh-token)
+        refresh-token
+        (p/rejected (ex-info "missing refresh token"
+                             {:code :missing-auth
+                              :hint "Run logseq login first."
+                              :auth-path (cli-auth/auth-path config)}))))))
+
+(defn- <ensure-e2ee-password-available!
+  [cfg config {:keys [type repo e2ee-password]} graph-e2ee?]
+  (if-not (true? graph-e2ee?)
+    (p/resolved nil)
+    (-> (p/let [refresh-token (ensure-refresh-token! config)
+                _ (if (seq e2ee-password)
+                    (transport/invoke cfg :thread-api/verify-and-save-e2ee-password false [refresh-token e2ee-password])
+                    (transport/invoke cfg :thread-api/get-e2ee-password false [refresh-token]))]
+          nil)
+        (p/catch (fn [error]
+                   (if (missing-e2ee-password-diagnostic? error)
+                     (p/rejected (ex-info "e2ee-password-not-found"
+                                          {:code :e2ee-password-not-found
+                                           :action type
+                                           :repo repo
+                                           :hint "Provide --e2ee-password to verify and persist it."}
+                                          error))
+                     (p/rejected error)))))))
+
+(declare invoke-global)
+
+(defn- <verify-and-save-e2ee-password-if-provided!
+  [config {:keys [e2ee-password]}]
+  (if (seq e2ee-password)
+    (p/let [refresh-token (ensure-refresh-token! config)
+            _ (invoke-global config :thread-api/verify-and-save-e2ee-password [refresh-token e2ee-password])]
+      nil)
+    (p/resolved nil)))
+
+(defn- parse-config-key
+  [raw-key]
+  (let [raw-key (some-> raw-key string/trim string/lower-case)
+        config-key (get config-key-map raw-key)]
+    (if config-key
+      {:ok? true
+       :key config-key}
+      (invalid-options (str "unknown config key: " raw-key)))))
+
+(defn- build-basic-repo-action
+  [command repo]
+  (if-not (seq repo)
+    (missing-repo (name command))
+    {:ok? true
+     :action {:type command
+              :repo repo
+              :graph (core/repo->graph repo)}}))
+
+(defn- build-sync-start-action
+  [options repo]
+  (if-not (seq repo)
+    (missing-repo "sync-start")
+    {:ok? true
+     :action {:type :sync-start
+              :repo repo
+              :graph (core/repo->graph repo)
+              :e2ee-password (:e2ee-password options)}}))
+
+(defn- build-sync-upload-action
+  [options repo]
+  (if-not (seq repo)
+    (missing-repo "sync-upload")
+    {:ok? true
+     :action {:type :sync-upload
+              :repo repo
+              :graph (core/repo->graph repo)
+              :e2ee-password (:e2ee-password options)}}))
+
+(defn- build-sync-download-action
+  [options repo]
+  (if-not (seq repo)
+    (missing-repo "sync-download")
+    {:ok? true
+     :action {:type :sync-download
+              :repo repo
+              :graph (core/repo->graph repo)
+              :allow-missing-graph true
+              :require-missing-graph true
+              :progress (:progress options)
+              :progress-explicit? (contains? options :progress)
+              :e2ee-password (:e2ee-password options)}}))
+
+(defn- build-sync-ensure-keys-action
+  [options]
+  {:ok? true
+   :action {:type :sync-ensure-keys
+            :e2ee-password (:e2ee-password options)
+            :upload-keys (:upload-keys options)}})
+
+(defn- build-sync-grant-access-action
+  [options repo]
+  (if-not (seq repo)
+    (missing-repo "sync grant-access")
+    (let [graph-id (some-> (:graph-id options) string/trim)
+          email (some-> (:email options) string/trim)]
+      (cond
+        (not (seq graph-id))
+        (invalid-options "--graph-id is required")
+
+        (not (seq email))
+        (invalid-options "--email is required")
+
+        :else
+        {:ok? true
+         :action {:type :sync-grant-access
+                  :repo repo
+                  :graph (core/repo->graph repo)
+                  :graph-id graph-id
+                  :email email}}))))
+
+(defn- build-sync-config-get-action
+  [args]
+  (let [[name] args
+        key-result (parse-config-key name)]
+    (if-not (seq (some-> name string/trim))
+      (invalid-options "config key is required")
+      (if-not (:ok? key-result)
+        key-result
+        {:ok? true
+         :action {:type :sync-config-get
+                  :config-key (:key key-result)}}))))
+
+(defn- build-sync-config-set-action
+  [args]
+  (let [[name value] args
+        key-result (parse-config-key name)]
+    (cond
+      (not (seq (some-> name string/trim)))
+      (invalid-options "config key is required")
+
+      (not (seq (some-> value str string/trim)))
+      (invalid-options "config value is required")
+
+      (not (:ok? key-result))
+      key-result
+
+      :else
+      {:ok? true
+       :action {:type :sync-config-set
+                :config-key (:key key-result)
+                :config-value value}})))
+
+(defn- build-sync-config-unset-action
+  [args]
+  (let [[name] args
+        key-result (parse-config-key name)]
+    (cond
+      (not (seq (some-> name string/trim)))
+      (invalid-options "config key is required")
+
+      (not (:ok? key-result))
+      key-result
+
+      :else
+      {:ok? true
+       :action {:type :sync-config-unset
+                :config-key (:key key-result)}})))
+
+(defn build-action
+  [command options args repo]
+  (case command
+    (:sync-status :sync-stop)
+    (build-basic-repo-action command repo)
+
+    :sync-upload
+    (build-sync-upload-action options repo)
+
+    :sync-start
+    (build-sync-start-action options repo)
+
+    :sync-download
+    (build-sync-download-action options repo)
+
+    :sync-remote-graphs
+    {:ok? true
+     :action {:type :sync-remote-graphs}}
+
+    :sync-ensure-keys
+    (build-sync-ensure-keys-action options)
+
+    :sync-grant-access
+    (build-sync-grant-access-action options repo)
+
+    :sync-config-get
+    (build-sync-config-get-action args)
+
+    :sync-config-set
+    (build-sync-config-set-action args)
+
+    :sync-config-unset
+    (build-sync-config-unset-action args)
+
+    {:ok? false
+     :error {:code :unknown-command
+             :message (str "unknown sync command: " command)}}))
+
+(defn- sync-config
+  [config]
+  {:ws-url (:ws-url config)
+   :http-base (:http-base config)})
+
+(defn- runtime-auth-present?
+  [config]
+  (or (seq (:id-token config))
+      (seq (:access-token config))
+      (seq (:refresh-token config))))
+
+(defn- merge-runtime-auth
+  [config auth]
+  (cond-> config
+    (seq (:id-token auth)) (assoc :id-token (:id-token auth))
+    (seq (:access-token auth)) (assoc :access-token (:access-token auth))
+    (seq (:refresh-token auth)) (assoc :refresh-token (:refresh-token auth))))
+
+(defn- resolve-runtime-config!
+  [action config]
+  (if (contains? authenticated-sync-actions (:type action))
+    (if (runtime-auth-present? config)
+      (p/resolved config)
+      (p/let [auth (cli-auth/resolve-auth! config)]
+        (merge-runtime-auth config auth)))
+    (p/resolved config)))
+
+(defn- worker-auth-state
+  [config]
+  (let [oauth-domain (or (:oauth-domain config)
+                         cognito-config/OAUTH-DOMAIN)
+        oauth-client-id (or (:oauth-client-id config)
+                            cognito-config/CLI-COGNITO-CLIENT-ID)
+        oauth-token-url (or (:oauth-token-url config)
+                            (when (seq oauth-domain)
+                              (str "https://" oauth-domain "/oauth2/token")))
+        id-token (:id-token config)
+        access-token (:access-token config)
+        refresh-token (:refresh-token config)
+        has-auth? (or (seq id-token)
+                      (seq access-token)
+                      (seq refresh-token))]
+    (cond-> {}
+      (seq id-token) (assoc :auth/id-token id-token)
+      (seq access-token) (assoc :auth/access-token access-token)
+      (seq refresh-token) (assoc :auth/refresh-token refresh-token)
+      (and has-auth? (seq oauth-token-url)) (assoc :auth/oauth-token-url oauth-token-url)
+      (and has-auth? (seq oauth-domain)) (assoc :auth/oauth-domain oauth-domain)
+      (and has-auth? (seq oauth-client-id)) (assoc :auth/oauth-client-id oauth-client-id))))
+
+(defn- <sync-worker-runtime!
+  [cfg config]
+  (let [auth-state (worker-auth-state config)]
+    (p/let [_ (when (seq auth-state)
+                (transport/invoke cfg :thread-api/sync-app-state false [auth-state]))
+            _ (transport/invoke cfg :thread-api/set-db-sync-config false [(sync-config config)])]
+      nil)))
+
+(defn- invoke-with-repo
+  [config repo method args]
+  (p/let [cfg (cli-server/ensure-server! config repo)
+          _ (<sync-worker-runtime! cfg config)
+          result (transport/invoke cfg method false args)]
+    result))
+
+(defn- invoke-global
+  [config method args]
+  (let [base-url (:base-url config)]
+    (if (seq base-url)
+      (p/let [_ (<sync-worker-runtime! config config)]
+        (transport/invoke config method false args))
+      (p/let [repo (or (core/resolve-repo (:graph config))
+                       (p/let [graphs (cli-server/list-graphs config)]
+                         (some-> graphs first core/resolve-repo)))
+              cfg (if (seq repo)
+                    (cli-server/ensure-server! config repo)
+                    (p/rejected (ex-info "graph name is required"
+                                         {:code :missing-graph})))
+              _ (<sync-worker-runtime! cfg config)]
+        (transport/invoke cfg method false args)))))
+
+(defn- download-config
+  [config]
+  (assoc config :create-empty-db? true))
+
+(defn- ensure-empty-download-db!
+  [cfg repo]
+  (p/let [non-empty-entity-count (transport/invoke cfg :thread-api/q false [repo [sync-download-non-empty-query]])]
+    (when (and (number? non-empty-entity-count)
+               (pos? non-empty-entity-count))
+      (throw (ex-info "graph db is not empty"
+                      {:code :graph-db-not-empty
+                       :repo repo
+                       :non-empty-entity-count non-empty-entity-count})))
+    nil))
+
+(defn- wait-sync-start-ready
+  [config repo action]
+  (let [timeout-ms (max 0 (or (:wait-timeout-ms action) sync-start-timeout-ms))
+        poll-interval-ms (max 0 (or (:wait-poll-interval-ms action) sync-start-poll-interval-ms))
+        deadline (+ (js/Date.now) timeout-ms)
+        config-skipped-hint "Run logseq login, set sync config keys (ws-url/http-base), and retry sync start."
+        graph-id-skipped-hint "Graph-id is missing locally. Run sync download first, then retry sync start."
+        runtime-error-hint "Run sync status to inspect last-error and fix sync runtime error before retrying."
+        timeout-hint "Run sync status to inspect ws-state and ensure sync endpoint/token are valid."]
+    (letfn [(poll! [initial?]
+              (p/let [status (invoke-with-repo config repo :thread-api/db-sync-status [repo])
+                      ws-state (:ws-state status)
+                      graph-id (:graph-id status)
+                      last-error (:last-error status)
+                      skipped-hint (if (seq graph-id)
+                                     config-skipped-hint
+                                     graph-id-skipped-hint)]
+                (cond
+                  (and (= :open ws-state) (some? last-error))
+                  {:status :error
+                   :error {:code :sync-start-runtime-error
+                           :message "sync start reached open websocket but runtime sync error is present"
+                           :repo repo
+                           :ws-state ws-state
+                           :status status
+                           :last-error last-error
+                           :hint runtime-error-hint}}
+
+                  (= :open ws-state)
+                  {:status :ok
+                   :data status}
+
+                  (and initial? (contains? sync-start-skipped-states ws-state))
+                  (p/let [_ (invoke-with-repo config repo :thread-api/db-sync-start [repo])
+                          _ (p/delay poll-interval-ms)]
+                    (poll! false))
+
+                  (contains? sync-start-skipped-states ws-state)
+                  {:status :error
+                   :error {:code :sync-start-skipped
+                           :message "sync start was skipped"
+                           :repo repo
+                           :ws-state ws-state
+                           :status status
+                           :hint skipped-hint}}
+
+                  (>= (js/Date.now) deadline)
+                  {:status :error
+                   :error {:code :sync-start-timeout
+                           :message "sync start timed out before websocket reached open state"
+                           :repo repo
+                           :ws-state ws-state
+                           :status status
+                           :hint timeout-hint}}
+
+                  :else
+                  (p/let [_ (p/delay poll-interval-ms)]
+                    (poll! false)))))]
+      (poll! true))))
+
+(defn- <verify-and-save-e2ee-password-on-worker-if-provided!
+  [cfg config {:keys [e2ee-password]}]
+  (if (seq e2ee-password)
+    (p/let [refresh-token (ensure-refresh-token! config)
+            _ (transport/invoke cfg :thread-api/verify-and-save-e2ee-password false [refresh-token e2ee-password])]
+      nil)
+    (p/resolved nil)))
+
+(defn- execute-sync-upload
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              _ (<sync-worker-runtime! cfg config)
+              _ (<verify-and-save-e2ee-password-on-worker-if-provided! cfg config action)
+              result (transport/invoke cfg :thread-api/db-sync-upload-graph false [(:repo action)])]
+        {:status :ok
+         :data (if (map? result)
+                 result
+                 {:result result})})
+      (p/catch (fn [error]
+                 (exception->error error {:repo (:repo action)})))))
+
+(defn- sync-download-progress-enabled?
+  [action config]
+  (if (:progress-explicit? action)
+    (true? (:progress action))
+    (not (output-mode/structured? (:output-format config)))))
+
+(defn- download-progress-message
+  [graph-id event-type payload]
+  (when (and (= :rtc-log event-type)
+             (map? payload)
+             (= :rtc.log/download (:type payload))
+             (= graph-id (:graph-uuid payload)))
+    (:message payload)))
+
+(defn- cleanup-error-details
+  [error]
+  (let [data (ex-data error)]
+    (cond-> {:code (or (:code data) :exception)
+             :message (or (ex-message error) (str error))}
+      (seq data) (assoc :context data))))
+
+(defn- <cleanup-created-download-graph!
+  [config repo]
+  (-> (p/let [stop-result (cli-server/stop-server! config repo)
+              _ (when-not (or (:ok? stop-result)
+                              (= :server-not-found (get-in stop-result [:error :code])))
+                  (throw (ex-info (get-in stop-result [:error :message] "failed to stop server")
+                                  {:code (get-in stop-result [:error :code])
+                                   :repo repo
+                                   :stage :stop-server
+                                   :stop-result stop-result})))
+              graphs-after-stop (cli-server/list-graphs config)
+              graph-exists? (some #(= (core/repo->graph repo) %) graphs-after-stop)
+              unlinked-dir (when graph-exists?
+                             (cli-common/unlink-graph! (cli-server/graphs-dir config) repo))
+              _ (when (and graph-exists? (not unlinked-dir))
+                  (throw (ex-info "unable to remove graph"
+                                  {:code :graph-not-removed
+                                   :repo repo
+                                   :stage :unlink-graph})))]
+        {:status :ok
+         :data {:repo repo
+                :unlinked-dir unlinked-dir}})
+      (p/catch (fn [error]
+                 (log/warn :cli-sync-download-cleanup-failed
+                           {:repo repo
+                            :error (cleanup-error-details error)})
+                 {:status :error
+                  :error (cleanup-error-details error)}))))
+
+(defn- execute-sync-download
+  [action config]
+  (let [config' (download-config config)
+        progress-enabled? (sync-download-progress-enabled? action config')]
+    (p/let [local-graphs-before (cli-server/list-graphs config')
+            graph-existed-before? (some #(= (:graph action) %) local-graphs-before)]
+      (-> (p/let [remote-graphs (invoke-global config'
+                                               :thread-api/db-sync-list-remote-graphs
+                                               [])
+                  remote-graph (some (fn [graph]
+                                       (when (= (:graph action) (:graph-name graph))
+                                         graph))
+                                     remote-graphs)]
+            (if-not remote-graph
+              {:status :error
+               :error {:code :remote-graph-not-found
+                       :message (str "remote graph not found: " (:graph action))
+                       :graph (:graph action)}}
+              (p/let [cfg (cli-server/ensure-server! config' (:repo action))
+                      _ (<sync-worker-runtime! cfg config')
+                      _ (<ensure-e2ee-password-available! cfg config' action (true? (:graph-e2ee? remote-graph)))
+                      _ (ensure-empty-download-db! cfg (:repo action))
+                      download-cfg (sync-download-invoke-config cfg)
+                      graph-id (:graph-id remote-graph)
+                      events-sub (when progress-enabled?
+                                   (transport/connect-events!
+                                    download-cfg
+                                    (fn [event-type payload]
+                                      (when-let [message (download-progress-message graph-id event-type payload)]
+                                        (print-progress-line! message)))))
+                      result (-> (transport/invoke download-cfg :thread-api/db-sync-download-graph-by-id false
+                                                   [(:repo action) graph-id (:graph-e2ee? remote-graph)])
+                                 (p/finally (fn []
+                                              (when-let [close! (:close! events-sub)]
+                                                (close!)))))]
+                {:status :ok
+                 :data (if (map? result)
+                         result
+                         {:result result})})))
+          (p/then (fn [result]
+                    (if (and (not graph-existed-before?)
+                             (= :error (:status result)))
+                      (p/let [_ (<cleanup-created-download-graph! config' (:repo action))]
+                        result)
+                      result)))
+          (p/catch (fn [error]
+                     (p/let [_ (when-not graph-existed-before?
+                                  (<cleanup-created-download-graph! config' (:repo action)))]
+                       (if (= :e2ee-password-not-found (:code (ex-data error)))
+                         (e2ee-password-not-found-error :sync-download (:repo action))
+                         (exception->error error {:repo (:repo action)
+                                                  :graph (:graph action)})))))))))
+
+(defn- run-sync-status
+  [action config]
+  (-> (p/let [config' (resolve-runtime-config! action config)
+              cfg (cli-server/ensure-server! config' (:repo action))
+              _ (<sync-worker-runtime! cfg config')
+              result (transport/invoke cfg :thread-api/db-sync-status false [(:repo action)])]
+        {:status :ok
+         :data result})
+      (p/catch (fn [error]
+                 (exception->error error {:repo (:repo action)})))))
+
+(defn- run-sync-start
+  [action config]
+  (-> (p/let [config' (resolve-runtime-config! action config)
+              missing-keys (missing-required-sync-config-keys (:type action) config')
+              start-config (assoc config' :ws-url (effective-sync-config-value config' :ws-url))]
+        (if (seq missing-keys)
+          (missing-sync-config-error (:type action) missing-keys)
+          (p/let [cfg (cli-server/ensure-server! start-config (:repo action))
+                  _ (<sync-worker-runtime! cfg start-config)
+                  graph-e2ee? (transport/invoke cfg :thread-api/q false [(:repo action) [graph-e2ee-query]])
+                  _ (<ensure-e2ee-password-available! cfg start-config action (true? graph-e2ee?))
+                  _ (transport/invoke cfg :thread-api/db-sync-start false [(:repo action)])
+                  result (wait-sync-start-ready start-config (:repo action) action)]
+            result)))
+      (p/catch (fn [error]
+                 (if (= :e2ee-password-not-found (:code (ex-data error)))
+                   (e2ee-password-not-found-error :sync-start (:repo action))
+                   (exception->error error {:repo (:repo action)}))))))
+
+(defn- run-sync-stop
+  [action config]
+  (p/let [result (invoke-with-repo config (:repo action)
+                                   :thread-api/db-sync-stop
+                                   [])]
+    {:status :ok
+     :data {:result result}}))
+
+(defn- run-sync-upload
+  [action config]
+  (-> (p/let [config' (resolve-runtime-config! action config)
+              missing-keys (missing-required-sync-config-keys (:type action) config')]
+        (if (seq missing-keys)
+          (missing-sync-config-error (:type action) missing-keys)
+          (execute-sync-upload action config')))
+      (p/catch (fn [error]
+                 (exception->error error {:repo (:repo action)})))))
+
+(defn- run-sync-download
+  [action config]
+  (-> (p/let [config' (resolve-runtime-config! action config)
+              missing-keys (missing-required-sync-config-keys (:type action) config')]
+        (if (seq missing-keys)
+          (missing-sync-config-error (:type action) missing-keys)
+          (execute-sync-download action config')))
+      (p/catch (fn [error]
+                 (exception->error error {:repo (:repo action)
+                                          :graph (:graph action)})))))
+
+(defn- run-sync-remote-graphs
+  [action config]
+  (-> (p/let [config' (resolve-runtime-config! action config)
+              graphs (invoke-global config' :thread-api/db-sync-list-remote-graphs [])]
+        {:status :ok
+         :data {:graphs (or graphs [])}})
+      (p/catch (fn [error]
+                 (exception->error error nil)))))
+
+(defn- sync-ensure-keys-upload-options
+  [{:keys [upload-keys e2ee-password]}]
+  (when (true? upload-keys)
+    (cond-> {:ensure-server? true}
+      (seq e2ee-password) (assoc :password e2ee-password))))
+
+(defn- run-sync-ensure-keys
+  [action config]
+  (-> (p/let [config' (resolve-runtime-config! action config)
+              upload-options (sync-ensure-keys-upload-options action)
+              _ (when-not upload-options
+                  (<verify-and-save-e2ee-password-if-provided! config' action))
+              result (invoke-global config'
+                                    :thread-api/db-sync-ensure-user-rsa-keys
+                                    (if upload-options [upload-options] []))
+              _ (when upload-options
+                  (<verify-and-save-e2ee-password-if-provided! config' action))]
+        {:status :ok
+         :data {:result result}})
+      (p/catch (fn [error]
+                 (exception->error error nil)))))
+
+(defn- run-sync-grant-access
+  [action config]
+  (-> (p/let [config' (resolve-runtime-config! action config)
+              missing-keys (missing-required-sync-config-keys (:type action) config')]
+        (if (seq missing-keys)
+          (missing-sync-config-error (:type action) missing-keys)
+          (p/let [result (invoke-with-repo config' (:repo action)
+                                           :thread-api/db-sync-grant-graph-access
+                                           [(:repo action) (:graph-id action) (:email action)])]
+            {:status :ok
+             :data {:result result}})))
+      (p/catch (fn [error]
+                 (exception->error error {:repo (:repo action)
+                                          :graph-id (:graph-id action)
+                                          :email (:email action)})))))
+
+(defn- run-sync-config-get
+  [action config]
+  (p/let [current config]
+    {:status :ok
+     :data {:key (:config-key action)
+            :value (get (or current {}) (:config-key action))}}))
+
+(defn- run-sync-config-set
+  [action config]
+  (p/let [_ (cli-config/update-config! config {(:config-key action) (:config-value action)})]
+    {:status :ok
+     :data {:key (:config-key action)
+            :value (:config-value action)}}))
+
+(defn- run-sync-config-unset
+  [action config]
+  (p/let [_ (cli-config/update-config! config {(:config-key action) nil})]
+    {:status :ok
+     :data {:key (:config-key action)}}))
+
+(defn execute
+  [action config]
+  (case (:type action)
+    :sync-status (run-sync-status action config)
+    :sync-start (run-sync-start action config)
+    :sync-stop (run-sync-stop action config)
+    :sync-upload (run-sync-upload action config)
+    :sync-download (run-sync-download action config)
+    :sync-remote-graphs (run-sync-remote-graphs action config)
+    :sync-ensure-keys (run-sync-ensure-keys action config)
+    :sync-grant-access (run-sync-grant-access action config)
+    :sync-config-get (run-sync-config-get action config)
+    :sync-config-set (run-sync-config-set action config)
+    :sync-config-unset (run-sync-config-unset action config)
+    (p/resolved {:status :error
+                 :error {:code :unknown-action
+                         :message "unknown sync action"}})))
diff --git a/src/main/logseq/cli/command/task_status.cljs b/src/main/logseq/cli/command/task_status.cljs
new file mode 100644
index 0000000000..172db38156
--- /dev/null
+++ b/src/main/logseq/cli/command/task_status.cljs
@@ -0,0 +1,71 @@
+(ns logseq.cli.command.task-status
+  "Runtime task status helpers for graph-derived validation."
+  (:require [clojure.string :as string]))
+
+(def status-closed-values-query
+  '[:find [?status-ident ...]
+    :where
+    [?property :db/ident :logseq.property/status]
+    [?value :block/closed-value-property ?property]
+    [?value :db/ident ?status-ident]])
+
+(defn- status-ident->value
+  [ident]
+  (when (keyword? ident)
+    (let [n (name ident)]
+      (when (string/starts-with? n "status.")
+        (subs n (count "status."))))))
+
+(defn- normalize-token
+  [value]
+  (some-> value
+          str
+          string/trim
+          string/lower-case
+          (string/replace #"^:+" "")
+          (string/replace #"^logseq\.property/status\." "")
+          (string/replace #"^status\." "")
+          (string/replace #"[\s_]+" "-")))
+
+(defn normalize-available-statuses
+  "Normalize db-worker status values into sorted maps of
+  `{:ident <kw> :value <string>}` for deterministic matching/output."
+  [statuses]
+  (->> statuses
+       (keep (fn [item]
+               (let [ident (cond
+                             (keyword? item) item
+                             (map? item) (:ident item)
+                             :else nil)
+                     value (or (when (map? item)
+                                 (some-> (:value item) normalize-token))
+                               (some-> ident status-ident->value normalize-token))]
+                 (when (and ident (seq value))
+                   {:ident ident :value value}))))
+       (sort-by (juxt :value (comp str :ident)))
+       distinct
+       vec))
+
+(defn resolve-status-ident
+  "Resolve user `status-input` to one of `available-statuses` idents.
+  Returns nil when unresolved."
+  [status-input available-statuses]
+  (let [available-statuses (normalize-available-statuses available-statuses)
+        available-idents (set (map :ident available-statuses))
+        by-value (into {} (map (juxt :value :ident) available-statuses))
+        token (normalize-token status-input)
+        ident-from-token (when (seq token)
+                           (keyword "logseq.property" (str "status." token)))]
+    (or (get by-value token)
+        (when (contains? available-idents ident-from-token)
+          ident-from-token))))
+
+(defn invalid-status-message
+  [status-input available-statuses]
+  (let [values (map :value (normalize-available-statuses available-statuses))
+        available-text (if (seq values)
+                         (string/join ", " values)
+                         "(none)")]
+    (str "Invalid value for option :status: " status-input
+         ". Available values: "
+         available-text)))
diff --git a/src/main/logseq/cli/command/update.cljs b/src/main/logseq/cli/command/update.cljs
new file mode 100644
index 0000000000..6bc17a75df
--- /dev/null
+++ b/src/main/logseq/cli/command/update.cljs
@@ -0,0 +1,292 @@
+(ns logseq.cli.command.update
+  "Update-related CLI commands."
+  (:require [clojure.string :as string]
+            [logseq.cli.command.add :as add-command]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.util :as common-util]
+            [promesa.core :as p]))
+
+(def ^:private update-positions
+  #{"first-child" "last-child" "sibling"})
+
+(defn invalid-options?
+  [opts]
+  (let [pos (some-> (:pos opts) string/trim string/lower-case)
+        source-selectors (filter some? [(:id opts) (some-> (:uuid opts) string/trim)])
+        target-selectors (filter some? [(:target-id opts)
+                                        (:target-uuid opts)
+                                        (some-> (:target-page opts) string/trim)])
+        has-update-tags? (seq (some-> (:update-tags opts) string/trim))
+        has-update-properties? (seq (some-> (:update-properties opts) string/trim))
+        has-remove-tags? (seq (some-> (:remove-tags opts) string/trim))
+        has-remove-properties? (seq (some-> (:remove-properties opts) string/trim))
+        has-status? (seq (some-> (:status opts) string/trim))
+        has-content? (contains? opts :content)
+        has-updates? (or has-update-tags?
+                         has-update-properties?
+                         has-remove-tags?
+                         has-remove-properties?
+                         has-status?
+                         has-content?)]
+    (cond
+      (and (seq pos) (not (contains? update-positions pos)))
+      (str "invalid pos: " (:pos opts))
+
+      (> (count source-selectors) 1)
+      "only one of --id or --uuid is allowed"
+
+      (> (count target-selectors) 1)
+      "only one of --target-id, --target-uuid, or --target-page is allowed"
+
+      (and (= pos "sibling") (seq (some-> (:target-page opts) string/trim)))
+      "--pos sibling is only valid for block targets"
+
+      (and (seq pos) (empty? target-selectors))
+      "--pos is only valid when a target option is provided"
+
+      (and (empty? target-selectors) (not has-updates?))
+      "target or update/remove options are required"
+
+      (or (:blocks opts) (:blocks-file opts))
+      "--blocks and --blocks-file are only for create mode"
+
+      :else
+      nil)))
+
+(def ^:private block-selector
+  [:db/id :block/uuid :block/name :block/title])
+
+(defn- fetch-entity-by-uuid
+  [config repo uuid-str]
+  (p/let [entity (transport/invoke config :thread-api/pull false
+                                   [repo block-selector [:block/uuid (uuid uuid-str)]])]
+    (if (:db/id entity)
+      entity
+      (transport/invoke config :thread-api/pull false
+                        [repo block-selector [:block/uuid uuid-str]]))))
+
+(defn- ensure-non-page
+  [entity message code]
+  (if (:block/name entity)
+    (throw (ex-info message {:code code}))
+    entity))
+
+(defn- resolve-source
+  [config repo {:keys [id uuid]}]
+  (cond
+    (some? id)
+    (p/let [entity (transport/invoke config :thread-api/pull false
+                                     [repo block-selector id])]
+      (if (:db/id entity)
+        (ensure-non-page entity "source must be a non-page block" :invalid-source)
+        (throw (ex-info "source block not found" {:code :source-not-found}))))
+
+    (seq uuid)
+    (p/let [entity (fetch-entity-by-uuid config repo uuid)]
+      (if (:db/id entity)
+        (ensure-non-page entity "source must be a non-page block" :invalid-source)
+        (throw (ex-info "source block not found" {:code :source-not-found}))))
+
+    :else
+    (p/rejected (ex-info "source is required" {:code :missing-source}))))
+
+(defn- resolve-target
+  [config repo {:keys [target-id target-uuid target-page]}]
+  (cond
+    (some? target-id)
+    (p/let [entity (transport/invoke config :thread-api/pull false
+                                     [repo block-selector target-id])]
+      (if (:db/id entity)
+        (ensure-non-page entity "target must be a block" :invalid-target)
+        (throw (ex-info "target block not found" {:code :target-not-found}))))
+
+    (seq target-uuid)
+    (p/let [entity (fetch-entity-by-uuid config repo target-uuid)]
+      (if (:db/id entity)
+        (ensure-non-page entity "target must be a block" :invalid-target)
+        (throw (ex-info "target block not found" {:code :target-not-found}))))
+
+    (seq target-page)
+    (let [page-name (common-util/page-name-sanity-lc target-page)]
+      (p/let [entity (transport/invoke config :thread-api/pull false
+                                       [repo [:db/id :block/uuid :block/name :block/title]
+                                        [:block/name page-name]])]
+        (if (:db/id entity)
+          entity
+          (throw (ex-info "page not found" {:code :page-not-found})))))
+
+    :else
+    (p/rejected (ex-info "target is required" {:code :missing-target}))))
+
+;; Position mapping for move-blocks opts.
+(defn- pos->opts
+  [pos]
+  (case pos
+    "last-child" {:sibling? false :bottom? true}
+    "sibling" {:sibling? true}
+    {:sibling? false}))
+
+(defn build-action
+  [options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for update"}}
+    (let [id (:id options)
+          uuid (some-> (:uuid options) string/trim)
+          target-id (:target-id options)
+          target-uuid (some-> (:target-uuid options) string/trim)
+          page-name (some-> (:target-page options) string/trim)
+          pos (some-> (:pos options) string/trim string/lower-case)
+          status-provided? (contains? options :status)
+          status-text (some-> (:status options) string/trim)
+          status (when (seq status-text)
+                   (add-command/normalize-status status-text))
+          content-provided? (contains? options :content)
+          content (:content options)
+          update-tags-result (add-command/parse-tags-option (:update-tags options))
+          update-properties-result (add-command/parse-properties-option
+                                    (:update-properties options)
+                                    {:allow-non-built-in? true})
+          remove-tags-result (add-command/parse-tags-vector-option (:remove-tags options))
+          remove-properties-result (add-command/parse-properties-vector-option
+                                    (:remove-properties options)
+                                    {:allow-non-built-in? true})
+          update-tags (:value update-tags-result)
+          update-properties (:value update-properties-result)
+          update-properties (merge (cond-> {}
+                                     status
+                                     (assoc :logseq.property/status status))
+                                   (or update-properties {}))
+          remove-tags (:value remove-tags-result)
+          remove-properties (:value remove-properties-result)
+          has-target? (or (some? target-id) (seq target-uuid) (seq page-name))
+          has-updates? (or (seq update-tags)
+                           (seq update-properties)
+                           (seq remove-tags)
+                           (seq remove-properties)
+                           status-provided?
+                           content-provided?)
+          source-label (cond
+                         (seq uuid) uuid
+                         (some? id) (str id)
+                         :else nil)
+          target-label (cond
+                         (seq page-name) (str "page:" page-name)
+                         (seq target-uuid) target-uuid
+                         (some? target-id) (str target-id)
+                         :else nil)]
+      (cond
+        (not (or (some? id) (seq uuid)))
+        {:ok? false
+         :error {:code :missing-source
+                 :message "source block is required"}}
+
+        (and status-provided? (not status))
+        {:ok? false
+         :error {:code :invalid-options
+                 :message (str "invalid status: " (:status options))}}
+
+        (not (:ok? update-tags-result))
+        update-tags-result
+
+        (not (:ok? update-properties-result))
+        update-properties-result
+
+        (not (:ok? remove-tags-result))
+        remove-tags-result
+
+        (not (:ok? remove-properties-result))
+        remove-properties-result
+
+        (and (not has-target?) (not has-updates?))
+        {:ok? false
+         :error {:code :invalid-options
+                 :message "target or update/remove options are required"}}
+
+        :else
+        {:ok? true
+         :action (cond-> {:type :update-block
+                          :repo repo
+                          :graph (core/repo->graph repo)
+                          :id id
+                          :uuid uuid
+                          :target-id target-id
+                          :target-uuid target-uuid
+                          :target-page page-name
+                          :pos (when has-target? (or pos "first-child"))
+                          :update-tags update-tags
+                          :update-properties update-properties
+                          :remove-tags remove-tags
+                          :remove-properties remove-properties
+                          :source source-label
+                          :target target-label}
+                   content-provided? (assoc :content content))}))))
+
+(defn- ensure-block-uuid!
+  [entity {:keys [code message]}]
+  (if-let [block-uuid (:block/uuid entity)]
+    block-uuid
+    (throw (ex-info message {:code code}))))
+
+(defn execute-update
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              source (resolve-source cfg (:repo action) action)
+              target (when (or (:target-id action)
+                               (:target-uuid action)
+                               (seq (:target-page action)))
+                       (resolve-target cfg (:repo action) action))
+              source-uuid (ensure-block-uuid! source
+                                              {:code :source-not-found
+                                               :message "source block uuid not found"})
+              target-uuid (when target
+                            (ensure-block-uuid! target
+                                                {:code :target-not-found
+                                                 :message "target block uuid not found"}))
+              block-uuids [source-uuid]
+              opts (when target (pos->opts (:pos action)))
+              update-tags (add-command/resolve-tags cfg (:repo action) (:update-tags action))
+              remove-tags (add-command/resolve-tags cfg (:repo action) (:remove-tags action))
+              update-properties (add-command/resolve-properties
+                                 cfg (:repo action) (:update-properties action)
+                                 {:allow-non-built-in? true})
+              remove-properties (add-command/resolve-property-identifiers
+                                 cfg (:repo action) (:remove-properties action)
+                                 {:allow-non-built-in? true})
+              content-provided? (contains? action :content)
+              content (:content action)
+              update-tag-ids (when (seq update-tags)
+                               (->> update-tags (map :db/id) (remove nil?) vec))
+              remove-tag-ids (when (seq remove-tags)
+                               (->> remove-tags (map :db/id) (remove nil?) vec))
+              ops (cond-> []
+                    content-provided?
+                    (conj [:save-block [{:block/uuid source-uuid :block/title content} {}]])
+                    target
+                    (conj [:move-blocks [block-uuids target-uuid opts]]))
+              ops (cond-> ops
+                    (seq remove-tag-ids)
+                    (into (map (fn [tag-id]
+                                 [:batch-delete-property-value [block-uuids :block/tags tag-id]])
+                               remove-tag-ids))
+                    (seq remove-properties)
+                    (into (map (fn [property-id]
+                                 [:batch-remove-property [block-uuids property-id]])
+                               remove-properties))
+                    (seq update-tag-ids)
+                    (into (map (fn [tag-id]
+                                 [:batch-set-property [block-uuids :block/tags tag-id {}]])
+                               update-tag-ids))
+                    (seq update-properties)
+                    (into (map (fn [[k v]]
+                                 [:batch-set-property [block-uuids k v {}]])
+                               update-properties)))
+              result (if (seq ops)
+                       (transport/invoke cfg :thread-api/apply-outliner-ops false
+                                         [(:repo action) ops {}])
+                       (p/resolved nil))]
+        {:status :ok
+         :data {:result result}})))
diff --git a/src/main/logseq/cli/command/upsert.cljs b/src/main/logseq/cli/command/upsert.cljs
new file mode 100644
index 0000000000..ddc2b2a39a
--- /dev/null
+++ b/src/main/logseq/cli/command/upsert.cljs
@@ -0,0 +1,1462 @@
+(ns logseq.cli.command.upsert
+  "Upsert-related CLI commands."
+  (:require ["crypto" :as crypto]
+            ["fs" :as fs]
+            ["path" :as node-path]
+            [clojure.string :as string]
+            [logseq.cli.command.add :as add-command]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.command.task-status :as task-status-command]
+            [logseq.cli.command.update :as update-command]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.graph :as common-graph]
+            [logseq.common.graph-dir :as graph-dir]
+            [logseq.common.util :as common-util]
+            [logseq.db :as ldb]
+            [logseq.db.frontend.asset :as db-asset]
+            [logseq.db.frontend.property :as db-property]
+            [logseq.db.frontend.property.type :as db-property-type]
+            [promesa.core :as p]))
+
+(def ^:private upsert-block-spec
+  {:id {:desc "Source block db/id (forces update mode) [update only]"
+        :coerce :long}
+   :uuid {:desc "Source block UUID (forces update mode) [update only]"
+          :validate {:pred (comp parse-uuid str)
+                     :ex-msg (constantly "Option uuid must be a valid UUID string")}}
+   :target-id {:desc "Target block db/id"
+               :coerce :long}
+   :target-uuid {:desc "Target block UUID"
+                 :validate {:pred (comp parse-uuid str)
+                            :ex-msg (constantly "Option target-uuid must be a valid UUID string")}}
+   :target-page {:desc "Target page name"
+                 :complete :pages}
+   :pos {:desc "Position. Default: create=last-child, update=first-child"
+         :validate #{"first-child" "last-child" "sibling"}}
+   :content {:alias :c
+             :desc "Block content (create inserts; update rewrites source block content)"}
+   :blocks {:desc "EDN vector of blocks [create only]"}
+   :blocks-file {:desc "EDN file of blocks [create only]"
+                 :coerce common-graph/expand-home
+                 :complete :file}
+   :update-tags {:desc "Tags to add/update (EDN vector)"}
+   :update-properties {:desc "Properties to add/update (EDN map)"}
+   :remove-tags {:desc "Tags to remove (EDN vector) [update only]"}
+   :remove-properties {:desc "Properties to remove (EDN vector) [update only]"}})
+
+(def ^:private upsert-page-spec
+  {:id {:desc "Target page db/id (forces update mode) [update only]"
+        :coerce :long}
+   :page {:desc "Page name"
+          :complete :pages}
+   :update-tags {:desc "Tags to add/update (EDN vector)"}
+   :update-properties {:desc "Properties to add/update (EDN map)"}
+   :remove-tags {:desc "Tags to remove (EDN vector) [update only]"}
+   :remove-properties {:desc "Properties to remove (EDN vector) [update only]"}})
+
+(def ^:private upsert-task-spec
+  {:id {:desc "Target node db/id (forces update mode) [update only]"
+        :coerce :long}
+   :uuid {:desc "Target node UUID (forces update mode) [update only]"
+          :validate {:pred (comp parse-uuid str)
+                     :ex-msg (constantly "Option uuid must be a valid UUID string")}}
+   :page {:desc "Task page name"
+          :complete :pages}
+   :content {:alias :c
+             :desc "Task block content (create mode)"}
+   :target-id {:desc "Target block db/id [create only]"
+               :coerce :long}
+   :target-uuid {:desc "Target block UUID [create only]"
+                 :validate {:pred (comp parse-uuid str)
+                            :ex-msg (constantly "Option target-uuid must be a valid UUID string")}}
+   :target-page {:desc "Target page name [create only]"
+                 :complete :pages}
+   :pos {:desc "Position. Default: last-child"
+         :validate #{"first-child" "last-child" "sibling"}}
+   :status {:desc "Set task status"
+            :values (mapv (comp string/lower-case :value)
+                          (db-property/built-in-closed-values :logseq.property/status))}
+   :priority {:desc "Set task priority"}
+   :scheduled {:desc "Set task scheduled datetime"}
+   :deadline {:desc "Set task deadline datetime"}
+   :no-status {:desc "Clear task status"
+               :coerce :boolean}
+   :no-priority {:desc "Clear task priority"
+                 :coerce :boolean}
+   :no-scheduled {:desc "Clear task scheduled datetime"
+                  :coerce :boolean}
+   :no-deadline {:desc "Clear task deadline datetime"
+                 :coerce :boolean}})
+
+(def ^:private upsert-asset-spec
+  {:id {:desc "Target asset node db/id (forces update mode) [update only]"
+        :coerce :long}
+   :uuid {:desc "Target asset node UUID (forces update mode) [update only]"
+          :validate {:pred (comp parse-uuid str)
+                     :ex-msg (constantly "Option uuid must be a valid UUID string")}}
+   :path {:desc "Asset file path [create only]"
+          :coerce common-graph/expand-home
+          :complete :file}
+   :target-id {:desc "Target block db/id [create only]"
+               :coerce :long}
+   :target-uuid {:desc "Target block UUID [create only]"
+                 :validate {:pred (comp parse-uuid str)
+                            :ex-msg (constantly "Option target-uuid must be a valid UUID string")}}
+   :target-page {:desc "Target page name [create only]"
+                 :complete :pages}
+   :pos {:desc "Position. Default: last-child"
+         :validate #{"first-child" "last-child" "sibling"}}
+   :content {:alias :c
+             :desc "Asset title (create/update)"}})
+
+(def ^:private upsert-tag-spec
+  {:id {:desc "Target tag db/id (forces update mode)"
+        :coerce :long}
+   :name {:desc "Tag name"
+          :complete :tags}})
+
+(def ^:private upsert-property-spec
+  {:id {:desc "Target property db/id (forces update mode)"
+        :coerce :long}
+   :name {:desc "Property name"
+          :complete :properties}
+   :type {:desc "Property type"
+          :validate (into (set (map name db-property-type/user-built-in-property-types))
+                          (set (map name db-property-type/user-allowed-internal-property-types)))}
+   :cardinality {:desc "Property cardinality"
+                 :validate #{"one" "many"}}
+   :hide {:desc "Hide property"
+          :coerce :boolean}
+   :public {:desc "Set property public visibility"
+            :coerce :boolean}})
+
+(def entries
+  [(core/command-entry ["upsert" "block"] :upsert-block "Upsert block" upsert-block-spec
+                       {:examples ["logseq upsert block --graph my-graph --target-page Home --content \"New block\""
+                                   "logseq upsert block --graph my-graph --id 123 --content \"Updated content\""
+                                   "logseq upsert block --graph my-graph --id 123 --target-page Home"
+                                   "logseq upsert block --graph my-graph --target-page Meeting Notes --content \"AI summary of the discussion\" --update-tags '[\"AI-GENERATED\"]'"
+                                   "logseq upsert block --graph my-graph --blocks '[{:block/title \"A\"} {:block/title \"B\"}]'"]})
+   (core/command-entry ["upsert" "page"] :upsert-page "Upsert page" upsert-page-spec
+                       {:examples ["logseq upsert page --graph my-graph --page Home --update-tags '[\"project\"]'"
+                                   "logseq upsert page --graph my-graph --id 999 --update-properties '{:logseq.property/description \"Example\"}'"]})
+   (core/command-entry ["upsert" "task"] :upsert-task "Upsert task" upsert-task-spec
+                       {:examples ["logseq upsert task --graph my-graph --content \"Ship release\" --target-page Home --status todo --priority high --scheduled \"2026-02-10T08:00:00.000Z\" --deadline \"2026-02-12T18:00:00.000Z\""
+                                   "logseq upsert task --graph my-graph --page Weekly Plan --status doing"
+                                   "logseq upsert task --graph my-graph --id 123 --no-status --no-priority"]})
+   (core/command-entry ["upsert" "asset"] :upsert-asset "Upsert asset" upsert-asset-spec
+                       {:examples ["logseq upsert asset --graph my-graph --path ./assets/logo.png --target-page Home"
+                                   "logseq upsert asset --graph my-graph --id 123 --content \"Updated asset title\""]})
+   (core/command-entry ["upsert" "tag"] :upsert-tag "Upsert tag" upsert-tag-spec
+                       {:examples ["logseq upsert tag --graph my-graph --name project"
+                                   "logseq upsert tag --graph my-graph --id 200 --name Project Renamed"]})
+   (core/command-entry ["upsert" "property"] :upsert-property "Upsert property" upsert-property-spec
+                       {:examples ["logseq upsert property --graph my-graph --name status --type default --cardinality one"
+                                   "logseq upsert property --graph my-graph --id 321 --hide true"]})])
+
+(defn- normalize-tag-name
+  [value]
+  (let [text (some-> value string/trim (string/replace #"^#+" ""))]
+    (when (seq text)
+      text)))
+
+(defn- normalize-property-name
+  [value]
+  (let [text (some-> value string/trim)]
+    (when (seq text)
+      text)))
+
+(defn- normalize-property-type
+  [value]
+  (some-> value string/trim string/lower-case))
+
+(defn- normalize-property-cardinality
+  [value]
+  (let [v (some-> value string/trim string/lower-case)]
+    (case v
+      "db.cardinality/one" "one"
+      "db.cardinality/many" "many"
+      v)))
+
+(def ^:private available-status-idents
+  (mapv :db-ident (db-property/built-in-closed-values :logseq.property/status)))
+
+(def ^:private available-priority-values
+  ["low" "medium" "high" "urgent"])
+
+(def ^:private priority-aliases
+  {"low" :logseq.property/priority.low
+   "medium" :logseq.property/priority.medium
+   "high" :logseq.property/priority.high
+   "urgent" :logseq.property/priority.urgent})
+
+(defn- normalize-priority
+  [value]
+  (let [text (some-> value string/trim string/lower-case)]
+    (when (seq text)
+      (get priority-aliases text))))
+
+(defn- invalid-priority-message
+  [priority-input]
+  (str "Invalid value for option :priority: " priority-input
+       ". Available values: "
+       (string/join ", " available-priority-values)))
+
+(defn ^:large-vars/cleanup-todo invalid-options?
+  [command opts]
+  (case command
+    :upsert-block
+    (let [opts (cond-> opts
+                 (seq (:target-page opts))
+                 (assoc :target-page-name (:target-page opts)))
+          update-mode? (or (some? (:id opts))
+                           (seq (some-> (:uuid opts) string/trim)))]
+      (if update-mode?
+        (update-command/invalid-options? opts)
+        (add-command/invalid-options? opts)))
+
+    :upsert-property
+    (let [name (normalize-property-name (:name opts))
+          selectors (filter some? [(:id opts) name])]
+      (when (> (count selectors) 1)
+        "only one of --id or --name is allowed"))
+
+    :upsert-page
+    (let [page (some-> (:page opts) string/trim)
+          selectors (filter some? [(:id opts) page])]
+      (when (> (count selectors) 1)
+        "only one of --id or --page is allowed"))
+
+    :upsert-task
+    (let [id (:id opts)
+          uuid (some-> (:uuid opts) string/trim)
+          page (some-> (:page opts) string/trim)
+          content (some-> (:content opts) string/trim)
+          status-text (some-> (:status opts) string/trim)
+          priority-text (some-> (:priority opts) string/trim)
+          scheduled-text (some-> (:scheduled opts) string/trim)
+          deadline-text (some-> (:deadline opts) string/trim)
+          selectors (filter some? [id uuid page])
+          target-selectors (filter some? [(:target-id opts)
+                                          (:target-uuid opts)
+                                          (some-> (:target-page opts) string/trim)])
+          pos (some-> (:pos opts) string/trim string/lower-case)
+          selector-mode? (or (some? id) (seq uuid) (seq page))
+          set-clear-conflict (cond
+                               (and (seq status-text) (:no-status opts))
+                               "--status and --no-status are mutually exclusive"
+
+                               (and (seq priority-text) (:no-priority opts))
+                               "--priority and --no-priority are mutually exclusive"
+
+                               (and (seq scheduled-text) (:no-scheduled opts))
+                               "--scheduled and --no-scheduled are mutually exclusive"
+
+                               (and (seq deadline-text) (:no-deadline opts))
+                               "--deadline and --no-deadline are mutually exclusive"
+
+                               :else
+                               nil)]
+      (cond
+        (> (count selectors) 1)
+        "only one of --id, --uuid, or --page is allowed"
+
+        (and (seq page) (seq content))
+        "--content and --page are mutually exclusive"
+
+        (and (or (some? id) (seq uuid)) (seq content))
+        "--content is only valid when creating a block task"
+
+        (> (count target-selectors) 1)
+        "only one of --target-id, --target-uuid, or --target-page is allowed"
+
+        (and selector-mode? (or (seq target-selectors) (seq pos)))
+        "--target-* and --pos are only valid when creating a block task with --content"
+
+        (and (seq pos) (empty? target-selectors))
+        "--pos is only valid when a target option is provided"
+
+        (and (= pos "sibling") (seq (some-> (:target-page opts) string/trim)))
+        "--pos sibling is only valid for block targets"
+
+        (seq set-clear-conflict)
+        set-clear-conflict
+
+        (and (seq priority-text) (not (normalize-priority priority-text)))
+        (invalid-priority-message priority-text)
+
+        :else
+        nil))
+
+    :upsert-asset
+    (let [id (:id opts)
+          uuid (some-> (:uuid opts) string/trim)
+          path (some-> (:path opts) str string/trim)
+          target-page (some-> (:target-page opts) string/trim)
+          selectors (filter some? [id uuid])
+          target-selectors (filter some? [(:target-id opts)
+                                          (:target-uuid opts)
+                                          target-page])
+          pos (some-> (:pos opts) string/trim string/lower-case)
+          update-mode? (or (some? id) (seq uuid))]
+      (cond
+        (> (count selectors) 1)
+        "only one of --id or --uuid is allowed"
+
+        (and update-mode? (seq path))
+        "--path is only valid in create mode"
+
+        (and (not update-mode?) (not (seq path)))
+        "--path is required in create mode"
+
+        (> (count target-selectors) 1)
+        "only one of --target-id, --target-uuid, or --target-page is allowed"
+
+        (and update-mode? (or (seq target-selectors) (seq pos)))
+        "--target-* and --pos are only valid in create mode"
+
+        (and (seq pos) (empty? target-selectors))
+        "--pos is only valid when a target option is provided"
+
+        (and (= pos "sibling") (seq target-page))
+        "--pos sibling is only valid for block targets"
+
+        :else
+        nil))
+
+    :upsert-tag
+    (let [name-provided? (contains? opts :name)
+          name (normalize-tag-name (:name opts))]
+      (cond
+        (and name-provided? (not (seq name)))
+        "tag name must not be blank"
+
+        :else
+        nil))
+
+    nil))
+
+(defn update-mode?
+  [opts]
+  (or (some? (:id opts))
+      (seq (some-> (:uuid opts) string/trim))))
+
+(defn build-block-action
+  [options args repo]
+  (let [update-mode* (update-mode? options)]
+    (if update-mode*
+      (let [options (cond-> options
+                      (seq (:target-page options))
+                      (assoc :target-page (:target-page options)))]
+        (-> (update-command/build-action options repo)
+            (update :action
+                    (fn [action]
+                      (when action
+                        (assoc action :type :upsert-block :mode :update))))))
+      (let [options (cond-> options
+                      (seq (:target-page options))
+                      (assoc :target-page-name (:target-page options))
+                      true
+                      (dissoc :target-page))
+            create-result (add-command/build-add-block-action options args repo)
+            update-tags-result (add-command/parse-tags-option (:update-tags options))
+            update-properties-result (add-command/parse-properties-option
+                                      (:update-properties options)
+                                      {:allow-non-built-in? true})]
+        (cond
+          (not (:ok? create-result))
+          create-result
+
+          (not (:ok? update-tags-result))
+          update-tags-result
+
+          (not (:ok? update-properties-result))
+          update-properties-result
+
+          :else
+          (-> create-result
+              (update :action
+                      (fn [action]
+                        (-> action
+                            (assoc :type :upsert-block
+                                   :mode :create
+                                   :update-tags (:value update-tags-result)
+                                   :update-properties (:value update-properties-result)))))))))))
+
+(defn build-page-action
+  [options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for upsert"}}
+    (let [id (:id options)
+          page (some-> (:page options) string/trim)
+          update-tags-result (add-command/parse-tags-option (:update-tags options))
+          update-properties-result (add-command/parse-properties-option
+                                    (:update-properties options)
+                                    {:allow-non-built-in? true})
+          remove-tags-result (add-command/parse-tags-vector-option (:remove-tags options))
+          remove-properties-result (add-command/parse-properties-vector-option
+                                    (:remove-properties options)
+                                    {:allow-non-built-in? true})
+          invalid-message (invalid-options? :upsert-page options)]
+      (cond
+        (seq invalid-message)
+        {:ok? false
+         :error {:code :invalid-options
+                 :message invalid-message}}
+
+        (and (not (some? id)) (not (seq page)))
+        {:ok? false
+         :error {:code :missing-page-name
+                 :message "page name is required"}}
+
+        (not (:ok? update-tags-result))
+        update-tags-result
+
+        (not (:ok? update-properties-result))
+        update-properties-result
+
+        (not (:ok? remove-tags-result))
+        remove-tags-result
+
+        (not (:ok? remove-properties-result))
+        remove-properties-result
+
+        :else
+        {:ok? true
+         :action (cond-> {:type :upsert-page
+                          :repo repo
+                          :graph (core/repo->graph repo)
+                          :mode (if (some? id) :update :create)
+                          :update-tags (:value update-tags-result)
+                          :update-properties (:value update-properties-result)
+                          :remove-tags (:value remove-tags-result)
+                          :remove-properties (:value remove-properties-result)}
+                   (some? id) (assoc :id id)
+                   (seq page) (assoc :page page))}))))
+
+(defn ^:large-vars/cleanup-todo build-task-action
+  [options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for upsert"}}
+    (let [id (:id options)
+          uuid (some-> (:uuid options) string/trim)
+          page (some-> (:page options) string/trim)
+          content (some-> (:content options) string/trim)
+          status-provided? (contains? options :status)
+          status-text (some-> (:status options) string/trim)
+          status (when (seq status-text)
+                   (add-command/normalize-status status-text))
+          priority-provided? (contains? options :priority)
+          priority-text (some-> (:priority options) string/trim)
+          priority (when (seq priority-text)
+                     (normalize-priority priority-text))
+          scheduled-provided? (contains? options :scheduled)
+          scheduled-text (some-> (:scheduled options) string/trim)
+          deadline-provided? (contains? options :deadline)
+          deadline-text (some-> (:deadline options) string/trim)
+          clear-properties (cond-> []
+                             (:no-status options) (conj :logseq.property/status)
+                             (:no-priority options) (conj :logseq.property/priority)
+                             (:no-scheduled options) (conj :logseq.property/scheduled)
+                             (:no-deadline options) (conj :logseq.property/deadline))
+          task-properties-input (cond-> {}
+                                  status (assoc :logseq.property/status status)
+                                  priority (assoc :logseq.property/priority priority)
+                                  (seq scheduled-text) (assoc :logseq.property/scheduled scheduled-text)
+                                  (seq deadline-text) (assoc :logseq.property/deadline deadline-text))
+          task-properties-result (if (seq task-properties-input)
+                                   (add-command/parse-properties-option (pr-str task-properties-input)
+                                                                        {:allow-non-built-in? true})
+                                   {:ok? true :value {}})
+          mode (cond
+                 (seq page) :page
+                 (or (some? id) (seq uuid)) :update
+                 :else :create)
+          create-options (cond-> options
+                           (seq (:target-page options))
+                           (assoc :target-page-name (:target-page options))
+                           true
+                           (dissoc :target-page
+                                   :status
+                                   :priority
+                                   :scheduled
+                                   :deadline
+                                   :no-status
+                                   :no-priority
+                                   :no-scheduled
+                                   :no-deadline))
+          create-result (when (= mode :create)
+                          (add-command/build-add-block-action create-options [] repo))
+          invalid-message (invalid-options? :upsert-task options)]
+      (cond
+        (seq invalid-message)
+        {:ok? false
+         :error {:code :invalid-options
+                 :message invalid-message}}
+
+        (and status-provided? (not (seq status-text)))
+        {:ok? false
+         :error {:code :invalid-options
+                 :message (task-status-command/invalid-status-message (:status options)
+                                                                      available-status-idents)}}
+
+        (and priority-provided? (not priority))
+        {:ok? false
+         :error {:code :invalid-options
+                 :message (invalid-priority-message (:priority options))}}
+
+        (and scheduled-provided? (not (seq scheduled-text)))
+        {:ok? false
+         :error {:code :invalid-options
+                 :message (str "invalid scheduled: " (:scheduled options))}}
+
+        (and deadline-provided? (not (seq deadline-text)))
+        {:ok? false
+         :error {:code :invalid-options
+                 :message (str "invalid deadline: " (:deadline options))}}
+
+        (not (:ok? task-properties-result))
+        task-properties-result
+
+        (and (not (some? id)) (not (seq uuid)) (not (seq page)) (not (seq content)))
+        {:ok? false
+         :error {:code :missing-target
+                 :message "block or page is required"}}
+
+        (and (= mode :create) (not (:ok? create-result)))
+        create-result
+
+        :else
+        {:ok? true
+         :action (cond-> (if (= mode :create)
+                           (-> (:action create-result)
+                               (assoc :type :upsert-task))
+                           {:type :upsert-task
+                            :repo repo
+                            :graph (core/repo->graph repo)})
+                   true (assoc :mode mode
+                               :update-properties (:value task-properties-result)
+                               :clear-properties (vec (distinct clear-properties)))
+                   (some? id) (assoc :id id)
+                   (seq uuid) (assoc :uuid uuid)
+                   (seq page) (assoc :page page)
+                   (seq status-text) (assoc :status-input status-text)
+                   (and (seq content) (not= mode :page)) (assoc :content content))}))))
+
+(defn build-asset-action
+  [options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for upsert"}}
+    (let [id (:id options)
+          uuid (some-> (:uuid options) string/trim)
+          content (some-> (:content options) string/trim)
+          path (some-> (:path options) str string/trim)
+          asset-update-mode? (or (some? id) (seq uuid))
+          invalid-message (invalid-options? :upsert-asset options)]
+      (cond
+        (seq invalid-message)
+        {:ok? false
+         :error {:code :invalid-options
+                 :message invalid-message}}
+
+        asset-update-mode?
+        {:ok? true
+         :action (cond-> {:type :upsert-asset
+                          :mode :update
+                          :repo repo
+                          :graph (core/repo->graph repo)}
+                   (some? id) (assoc :id id)
+                   (seq uuid) (assoc :uuid uuid)
+                   (seq content) (assoc :content content))}
+
+        :else
+        (let [default-title (db-asset/asset-name->title (node-path/basename path))
+              create-content (or content default-title)
+              create-options (cond-> (assoc options :content create-content)
+                               (seq (:target-page options))
+                               (assoc :target-page-name (:target-page options))
+                               true
+                               (dissoc :target-page :path))
+              create-result (add-command/build-add-block-action create-options [] repo)]
+          (if (:ok? create-result)
+            (-> create-result
+                (update :action
+                        (fn [action]
+                          (-> action
+                              (assoc :type :upsert-asset
+                                     :mode :create
+                                     :asset-path path)))))
+            create-result))))))
+
+(defn build-tag-action
+  [options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for upsert"}}
+    (let [id (:id options)
+          name (normalize-tag-name (:name options))
+          invalid-message (invalid-options? :upsert-tag options)]
+      (cond
+        (seq invalid-message)
+        {:ok? false
+         :error {:code :invalid-options
+                 :message invalid-message}}
+
+        (some? id)
+        {:ok? true
+         :action (cond-> {:type :upsert-tag
+                          :mode :update
+                          :id id
+                          :repo repo
+                          :graph (core/repo->graph repo)}
+                   (seq name) (assoc :name name))}
+
+        (seq name)
+        {:ok? true
+         :action {:type :upsert-tag
+                  :mode :create
+                  :repo repo
+                  :graph (core/repo->graph repo)
+                  :name name}}
+
+        :else
+        {:ok? false
+         :error {:code :missing-tag-name
+                 :message "tag name is required"}}))))
+
+(defn- cardinality->db
+  [value]
+  (when-let [v (normalize-property-cardinality value)]
+    (case v
+      "many" :db.cardinality/many
+      "one" :db.cardinality/one
+      nil)))
+
+(defn- property-schema
+  [options]
+  (cond-> {}
+    (seq (:type options))
+    (assoc :logseq.property/type (keyword (normalize-property-type (:type options))))
+
+    (seq (:cardinality options))
+    (assoc :db/cardinality (cardinality->db (:cardinality options)))
+
+    (contains? options :hide)
+    (assoc :logseq.property/hide? (boolean (:hide options)))
+
+    (contains? options :public)
+    (assoc :logseq.property/public? (boolean (:public options)))))
+
+(defn build-property-action
+  [options repo]
+  (if-not (seq repo)
+    {:ok? false
+     :error {:code :missing-repo
+             :message "repo is required for upsert"}}
+    (let [id (:id options)
+          name (normalize-property-name (:name options))
+          invalid-message (invalid-options? :upsert-property options)]
+      (cond
+        (and (not (some? id)) (not (seq name)))
+        {:ok? false
+         :error {:code :missing-property-name
+                 :message "property name is required"}}
+
+        (seq invalid-message)
+        {:ok? false
+         :error {:code :invalid-options
+                 :message invalid-message}}
+
+        :else
+        {:ok? true
+         :action (cond-> {:type :upsert-property
+                          :mode (if (some? id) :update :create)
+                          :repo repo
+                          :graph (core/repo->graph repo)
+                          :schema (property-schema options)}
+                   (some? id) (assoc :id id)
+                   (seq name) (assoc :name name))}))))
+
+(defn- pull-page-by-name
+  [config repo page-name selector]
+  (transport/invoke config :thread-api/pull false
+                    [repo selector [:block/name (common-util/page-name-sanity-lc page-name)]]))
+
+(def ^:private pull-tag-by-name add-command/pull-tag-by-name)
+(def ^:private pull-property-by-name add-command/pull-property-by-name)
+
+(defn- enrich-exception
+  [error context]
+  (let [message (or (ex-message error) (str error))
+        data (merge (or (ex-data error) {}) context)
+        cause (when (instance? js/Error error) error)]
+    (if cause
+      (ex-info message data cause)
+      (ex-info message data))))
+
+(defn- with-error-context
+  [promise context]
+  (-> promise
+      (p/catch (fn [error]
+                 (p/rejected (enrich-exception error context))))))
+
+(defn- with-option-error-context
+  [promise option phase context]
+  (with-error-context promise (merge {:option option
+                                      :phase phase}
+                                     context)))
+
+(defn- exception->error
+  [error]
+  (let [data (or (ex-data error) {})
+        code (or (:code data) :exception)
+        message (or (:message data)
+                    (ex-message error)
+                    (str error))]
+    (-> data
+        (dissoc :code :message)
+        (assoc :code code
+               :message message))))
+
+(defn- ensure-property-identifiers-exist!
+  [config repo property-idents]
+  (if (seq property-idents)
+    (p/all
+     (map (fn [property-ident]
+            (p/let [entity (transport/invoke config :thread-api/pull false
+                                             [repo [:db/id] [:db/ident property-ident]])]
+              (when-not (:db/id entity)
+                (throw (ex-info "property not found"
+                                {:code :property-not-found
+                                 :property property-ident})))))
+          (distinct property-idents)))
+    (p/resolved nil)))
+
+(defn- ensure-page-entity!
+  [config repo page-name]
+  (p/let [live (add-command/find-pages-by-name config repo page-name
+                                               [:db/id :block/uuid])
+          _ (when (> (count live) 1)
+              (add-command/throw-ambiguous-page-error! page-name live))
+          existing (first live)]
+    (if (:db/id existing)
+      existing
+      ;; Either no page exists, or only a recycled one does. Calling
+      ;; :create-page in both cases is correct: outliner-page/create has a
+      ;; (ldb/recycled? existing-page) branch that restores the recycled page
+      ;; instead of creating a duplicate.
+      (p/let [result (transport/invoke config :thread-api/apply-outliner-ops false
+                                       [repo [[:create-page [page-name {}]]] {}])
+              ;; create-page returns [title' page-uuid]; use uuid to find
+              ;; the page since the stored name may differ from the input
+              created (if-let [page-uuid (second result)]
+                        (transport/invoke config :thread-api/pull false
+                                          [repo [:db/id :block/uuid] [:block/uuid page-uuid]])
+                        (pull-page-by-name config repo page-name [:db/id :block/uuid]))]
+        (if (:db/id created)
+          created
+          (throw (ex-info "page not found after upsert"
+                          {:code :page-not-found
+                           :page page-name})))))))
+
+(def ^:private upsert-id-not-found-code
+  :upsert-id-not-found)
+
+(def ^:private upsert-id-type-mismatch-code
+  :upsert-id-type-mismatch)
+
+(def ^:private page-selector
+  [:db/id :block/uuid :block/name :block/title :logseq.property/deleted-at])
+
+(def ^:private tag-selector
+  [:db/id :block/uuid :block/name :block/title
+   {:block/tags [:db/ident]}])
+
+(def ^:private property-selector
+  [:db/id :db/ident :block/uuid :block/name :block/title :logseq.property/type])
+
+(defn- page-entity?
+  [entity]
+  (seq (:block/name entity)))
+
+(defn- tag-entity?
+  [entity]
+  (some #(= :logseq.class/Tag (:db/ident %))
+        (:block/tags entity)))
+
+(defn- property-entity?
+  [entity]
+  (some? (:logseq.property/type entity)))
+
+(defn- pull-entity-by-id
+  [config repo selector id]
+  (transport/invoke config :thread-api/pull false
+                    [repo selector id]))
+
+(defn- throw-upsert-id-not-found!
+  [entity-type id]
+  (throw (ex-info (str entity-type " not found for id")
+                  {:code upsert-id-not-found-code
+                   :entity-type entity-type
+                   :id id})))
+
+(defn- throw-upsert-id-type-mismatch!
+  [entity-type id]
+  (throw (ex-info (str "id must be a node tagged with #" entity-type)
+                  {:code upsert-id-type-mismatch-code
+                   :entity-type entity-type
+                   :id id})))
+
+(defn- ensure-page-by-id!
+  [config repo id]
+  (p/let [entity (pull-entity-by-id config repo page-selector id)]
+    (cond
+      (or (not (:db/id entity)) (ldb/recycled? entity))
+      (throw-upsert-id-not-found! "page" id)
+
+      (not (page-entity? entity))
+      (throw-upsert-id-type-mismatch! "Page" id)
+
+      :else
+      entity)))
+
+(defn- ensure-tag-by-id!
+  [config repo id]
+  (p/let [entity (pull-entity-by-id config repo tag-selector id)]
+    (cond
+      (not (:db/id entity))
+      (throw-upsert-id-not-found! "tag" id)
+
+      (not (tag-entity? entity))
+      (throw-upsert-id-type-mismatch! "Tag" id)
+
+      :else
+      entity)))
+
+(def ^:private tag-rename-conflict-code
+  :tag-rename-conflict)
+
+(defn- normalized-tag-lookup-name
+  [value]
+  (some-> value normalize-tag-name common-util/page-name-sanity-lc))
+
+(defn- rename-target-same-as-current?
+  [entity target-name]
+  (= (:block/name entity)
+     (normalized-tag-lookup-name target-name)))
+
+(defn- rename-target-conflict
+  [entity target]
+  (let [target-id (:db/id target)
+        current-id (:db/id entity)]
+    (cond
+      (or (nil? target-id)
+          (= target-id current-id))
+      nil
+
+      (not (tag-entity? target))
+      {:code :tag-name-conflict
+       :message "tag already exists as a page and is not a tag"}
+
+      :else
+      {:code tag-rename-conflict-code
+       :message "rename target already exists as a tag"})))
+
+(defn- ensure-property-by-id!
+  [config repo id]
+  (p/let [entity (pull-entity-by-id config repo property-selector id)]
+    (cond
+      (not (:db/id entity))
+      (throw-upsert-id-not-found! "property" id)
+
+      (not (property-entity? entity))
+      (throw-upsert-id-type-mismatch! "Property" id)
+
+      :else
+      entity)))
+
+(def ^:private task-selector
+  [:db/id :block/uuid :block/name :block/title])
+
+(def ^:private task-tag-ident
+  :logseq.class/Task)
+
+(def ^:private asset-selector
+  [:db/id :block/uuid :block/title :logseq.property/deleted-at
+   {:block/tags [:db/ident]}])
+
+(def ^:private asset-tag-ident
+  :logseq.class/Asset)
+
+(defn- normalize-lookup-uuid
+  [value]
+  (cond
+    (uuid? value) value
+    (and (string? value) (common-util/uuid-string? (string/trim value)))
+    (uuid (string/trim value))
+    :else nil))
+
+(defn- pull-entity-by-uuid
+  [config repo selector uuid-value]
+  (when-let [uuid* (normalize-lookup-uuid uuid-value)]
+    (transport/invoke config :thread-api/pull false
+                      [repo selector [:block/uuid uuid*]])))
+
+(defn- ensure-task-node!
+  [config repo {:keys [id uuid]}]
+  (p/let [entity (cond
+                   (some? id)
+                   (pull-entity-by-id config repo task-selector id)
+
+                   (seq uuid)
+                   (pull-entity-by-uuid config repo task-selector uuid)
+
+                   :else
+                   nil)]
+    (if (:db/id entity)
+      entity
+      (throw (ex-info "node not found for selector"
+                      {:code upsert-id-not-found-code
+                       :id id
+                       :uuid uuid})))))
+
+(defn- asset-entity?
+  [entity]
+  (some #(= asset-tag-ident (:db/ident %))
+        (:block/tags entity)))
+
+(defn- ensure-asset-node!
+  [config repo {:keys [id uuid]}]
+  (p/let [entity (cond
+                   (some? id)
+                   (pull-entity-by-id config repo asset-selector id)
+
+                   (seq uuid)
+                   (pull-entity-by-uuid config repo asset-selector uuid)
+
+                   :else
+                   nil)]
+    (cond
+      (or (not (:db/id entity)) (ldb/recycled? entity))
+      (throw (ex-info "asset not found for selector"
+                      {:code upsert-id-not-found-code
+                       :id id
+                       :uuid uuid}))
+
+      (not (asset-entity? entity))
+      (throw (ex-info "selector must be a node tagged with #Asset"
+                      {:code upsert-id-type-mismatch-code
+                       :id id
+                       :uuid uuid}))
+
+      :else
+      entity)))
+
+(defn- ensure-task-tag-id!
+  [config repo]
+  (p/let [entity (transport/invoke config :thread-api/pull false
+                                   [repo [:db/id] [:db/ident task-tag-ident]])]
+    (if-let [tag-id (:db/id entity)]
+      tag-id
+      (throw (ex-info "task tag not found"
+                      {:code :task-tag-not-found})))))
+
+(defn- task-property-overrides
+  [action]
+  (cond-> {}
+    (:status action) (assoc :logseq.property/status (:status action))
+    (:priority action) (assoc :logseq.property/priority (:priority action))
+    (:scheduled action) (assoc :logseq.property/scheduled (:scheduled action))
+    (:deadline action) (assoc :logseq.property/deadline (:deadline action))))
+
+(declare append-tag-and-property-ops)
+
+(def ^:private block-uuid-selector
+  [:db/id :block/uuid])
+
+(defn- ensure-block-uuid-by-id!
+  [config repo block-id]
+  (p/let [entity (pull-entity-by-id config repo block-uuid-selector block-id)
+          block-uuid (:block/uuid entity)]
+    (if block-uuid
+      block-uuid
+      (throw (ex-info "block uuid not found for id"
+                      {:code upsert-id-not-found-code
+                       :entity-type "block"
+                       :id block-id})))))
+
+(defn- resolve-block-uuids-by-id!
+  [config repo block-ids]
+  (if (seq block-ids)
+    (let [unique-block-ids (vec (distinct block-ids))
+          block-uuid-promises (mapv (fn [block-id]
+                                      (ensure-block-uuid-by-id! config repo block-id))
+                                    unique-block-ids)]
+      (-> (p/all block-uuid-promises)
+          (p/then vec)))
+    (p/resolved [])))
+
+(defn- execute-upsert-task-ops!
+  [repo cfg block-ids task-op-plan]
+  (if (seq block-ids)
+    (p/let [block-uuids (resolve-block-uuids-by-id! cfg repo block-ids)
+            ops (append-tag-and-property-ops []
+                                             block-uuids
+                                             task-op-plan)]
+      (if (seq ops)
+        (transport/invoke cfg :thread-api/apply-outliner-ops false
+                          [repo ops {}])
+        (p/resolved nil)))
+    (p/resolved nil)))
+
+(defn- append-tag-and-property-ops
+  [ops block-uuids {:keys [update-tag-ids remove-tag-ids update-properties remove-properties]}]
+  (cond-> ops
+    (seq remove-tag-ids)
+    (into (map (fn [tag-id]
+                 [:batch-delete-property-value [block-uuids :block/tags tag-id]])
+               remove-tag-ids))
+
+    (seq remove-properties)
+    (into (map (fn [property-id]
+                 [:batch-remove-property [block-uuids property-id]])
+               remove-properties))
+
+    (seq update-tag-ids)
+    (into (map (fn [tag-id]
+                 [:batch-set-property [block-uuids :block/tags tag-id {}]])
+               update-tag-ids))
+
+    (seq update-properties)
+    (into (map (fn [[k v]]
+                 [:batch-set-property [block-uuids k v {}]])
+               update-properties))))
+
+(defn execute-upsert-block
+  [action config]
+  (-> (if (= :update (:mode action))
+        (update-command/execute-update (assoc action :type :update-block) config)
+        (p/let [cfg (cli-server/ensure-server! config (:repo action))
+                update-tags (with-option-error-context
+                              (add-command/resolve-tags cfg (:repo action) (:update-tags action))
+                              "--update-tags"
+                              :resolve-options
+                              {:command :upsert-block})
+                update-properties (with-option-error-context
+                                    (add-command/resolve-properties cfg (:repo action) (:update-properties action)
+                                                                    {:allow-non-built-in? true})
+                                    "--update-properties"
+                                    :resolve-options
+                                    {:command :upsert-block})
+                _ (with-option-error-context
+                    (ensure-property-identifiers-exist! cfg (:repo action) (keys (or update-properties {})))
+                    "--update-properties"
+                    :resolve-options
+                    {:command :upsert-block})
+                result (add-command/execute-add-block (-> action
+                                                          (assoc :type :add-block
+                                                                 :resolved-tags update-tags
+                                                                 :resolved-properties update-properties))
+                                                      config)
+                created-ids (vec (or (get-in result [:data :result]) []))]
+          {:status :ok
+           :data {:result created-ids}}))
+      (p/catch (fn [error]
+                 {:status :error
+                  :error (exception->error error)}))))
+
+(defn execute-upsert-page
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              update-by-id? (= :update (:mode action))
+              update-tags (with-option-error-context
+                            (add-command/resolve-tags cfg (:repo action) (:update-tags action))
+                            "--update-tags"
+                            :resolve-options
+                            {:command :upsert-page})
+              remove-tags (with-option-error-context
+                            (add-command/resolve-tags cfg (:repo action) (:remove-tags action))
+                            "--remove-tags"
+                            :resolve-options
+                            {:command :upsert-page})
+              update-properties (with-option-error-context
+                                  (add-command/resolve-properties cfg (:repo action) (:update-properties action)
+                                                                  {:allow-non-built-in? true})
+                                  "--update-properties"
+                                  :resolve-options
+                                  {:command :upsert-page})
+              remove-properties (with-option-error-context
+                                  (add-command/resolve-property-identifiers cfg (:repo action)
+                                                                            (:remove-properties action)
+                                                                            {:allow-non-built-in? true})
+                                  "--remove-properties"
+                                  :resolve-options
+                                  {:command :upsert-page})
+              _ (with-option-error-context
+                  (ensure-property-identifiers-exist! cfg (:repo action) (keys (or update-properties {})))
+                  "--update-properties"
+                  :resolve-options
+                  {:command :upsert-page})
+              _ (with-option-error-context
+                  (ensure-property-identifiers-exist! cfg (:repo action) remove-properties)
+                  "--remove-properties"
+                  :resolve-options
+                  {:command :upsert-page})
+              page (if update-by-id?
+                     (ensure-page-by-id! cfg (:repo action) (:id action))
+                     (ensure-page-entity! cfg (:repo action) (:page action)))
+              page-id (:db/id page)
+              block-uuids (resolve-block-uuids-by-id! cfg (:repo action) [page-id])
+              update-tag-ids (->> (or update-tags [])
+                                  (map :db/id)
+                                  (remove nil?)
+                                  distinct
+                                  vec)
+              remove-tag-ids (->> remove-tags (map :db/id) (remove nil?) distinct vec)
+              ops (append-tag-and-property-ops []
+                                               block-uuids
+                                               {:update-tag-ids update-tag-ids
+                                                :remove-tag-ids remove-tag-ids
+                                                :update-properties update-properties
+                                                :remove-properties remove-properties})
+              _ (when (seq ops)
+                  (transport/invoke cfg :thread-api/apply-outliner-ops false
+                                    [(:repo action) ops {}]))]
+        {:status :ok
+         :data {:result [page-id]}})
+      (p/catch (fn [error]
+                 {:status :error
+                  :error (exception->error error)}))))
+
+(defn- normalize-status-input
+  [value]
+  (when (some? value)
+    (let [text (string/trim (if (string? value) value (str value)))]
+      (when (seq text)
+        text))))
+
+(defn- resolve-task-status-action
+  [action cfg]
+  (let [status-input (or (normalize-status-input (:status-input action))
+                         (normalize-status-input (:status action)))]
+    (if (seq status-input)
+      (p/let [available-statuses (transport/invoke cfg :thread-api/q false
+                                                   [(:repo action)
+                                                    [task-status-command/status-closed-values-query]])
+              resolved-status (task-status-command/resolve-status-ident status-input available-statuses)]
+        (if resolved-status
+          {:ok? true
+           :action (-> action
+                       (assoc :status resolved-status)
+                       (dissoc :status-input))}
+          {:ok? false
+           :error {:code :invalid-options
+                   :message (task-status-command/invalid-status-message status-input available-statuses)}}))
+      (p/resolved {:ok? true :action action}))))
+
+(defn execute-upsert-task
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              status-check (resolve-task-status-action action cfg)]
+        (if-not (:ok? status-check)
+          {:status :error
+           :error (merge (:error status-check)
+                         {:option "--status"
+                          :phase :validate-options
+                          :command :upsert-task})}
+          (p/let [action* (:action status-check)
+                  update-properties (merge (or (:update-properties action*) {})
+                                           (task-property-overrides action*))
+                  clear-properties (vec (distinct (or (:clear-properties action*) [])))
+                  _ (with-option-error-context
+                      (ensure-property-identifiers-exist! cfg (:repo action*) (keys update-properties))
+                      "--update-properties"
+                      :resolve-options
+                      {:command :upsert-task})
+                  _ (with-option-error-context
+                      (ensure-property-identifiers-exist! cfg (:repo action*) clear-properties)
+                      "--no-status/--no-priority/--no-scheduled/--no-deadline"
+                      :resolve-options
+                      {:command :upsert-task})
+                  task-tag-id (with-error-context
+                                (ensure-task-tag-id! cfg (:repo action*))
+                                {:phase :resolve-options
+                                 :context :task-tag
+                                 :command :upsert-task})
+                  task-op-plan {:update-tag-ids [task-tag-id]
+                                :update-properties update-properties
+                                :remove-properties clear-properties}]
+            (case (:mode action*)
+              :create
+              (p/let [result (add-command/execute-add-block
+                              (-> action*
+                                  (assoc :type :add-block
+                                         :resolved-tags [{:db/id task-tag-id}]
+                                         :resolved-properties update-properties
+                                         :resolved-remove-properties clear-properties)
+                                  (dissoc :status))
+                              config)
+                      created-ids (vec (or (get-in result [:data :result]) []))]
+                {:status :ok
+                 :data {:result created-ids}})
+
+              :page
+              (p/let [page (ensure-page-entity! cfg (:repo action*) (:page action*))
+                      page-id (:db/id page)
+                      _ (execute-upsert-task-ops! (:repo action*) cfg [page-id] task-op-plan)]
+                {:status :ok
+                 :data {:result [page-id]}})
+
+              :update
+              (p/let [entity (ensure-task-node! cfg (:repo action*) action*)
+                      node-id (:db/id entity)
+                      _ (execute-upsert-task-ops! (:repo action*) cfg [node-id] task-op-plan)]
+                {:status :ok
+                 :data {:result [node-id]}})
+
+              {:status :error
+               :error {:code :invalid-options
+                       :message "invalid upsert task mode"}}))))
+      (p/catch (fn [error]
+                 {:status :error
+                  :error (exception->error error)}))))
+
+(defn- asset-file-exists?
+  [path]
+  (and (seq path)
+       (fs/existsSync path)))
+
+(defn- asset-file-size-bytes
+  [path]
+  (let [stat (fs/statSync path)]
+    (.-size stat)))
+
+(defn- asset-file-checksum
+  [path]
+  (-> (.createHash crypto "sha256")
+      (.update (fs/readFileSync path))
+      (.digest "hex")))
+
+(defn- ensure-dir!
+  [path]
+  (fs/mkdirSync path #js {:recursive true}))
+
+(defn- copy-file!
+  [source destination]
+  (fs/copyFileSync source destination))
+
+(defn- graph-assets-dir-path
+  [config repo]
+  (if-let [graph-dir-name (graph-dir/repo->encoded-graph-dir-name repo)]
+    (node-path/join (cli-server/graphs-dir config)
+                    graph-dir-name
+                    "assets")
+    (throw (ex-info "invalid repo"
+                    {:code :invalid-repo
+                     :repo repo}))))
+
+(defn- ensure-asset-file-path!
+  [path]
+  (when-not (asset-file-exists? path)
+    (throw (ex-info "asset file not found"
+                    {:code :asset-file-not-found
+                     :path path}))))
+
+(defn- read-asset-file-metadata
+  [path]
+  (let [asset-type (db-asset/asset-path->type path)]
+    (when-not (seq asset-type)
+      (throw (ex-info "asset path must include a file extension"
+                      {:code :invalid-options
+                       :path path})))
+    {:asset/type asset-type
+     :asset/size (asset-file-size-bytes path)
+     :asset/checksum (asset-file-checksum path)}))
+
+(defn- ensure-asset-tag-id!
+  [config repo]
+  (p/let [entity (transport/invoke config :thread-api/pull false
+                                   [repo [:db/id] [:db/ident asset-tag-ident]])]
+    (if-let [tag-id (:db/id entity)]
+      tag-id
+      (throw (ex-info "asset tag not found"
+                      {:code :asset-tag-not-found})))))
+
+(defn- copy-asset-file-to-graph!
+  [config repo block-uuid asset-type source-path]
+  (let [assets-dir (graph-assets-dir-path config repo)
+        destination-path (node-path/join assets-dir (str block-uuid "." asset-type))]
+    (ensure-dir! assets-dir)
+    (copy-file! source-path destination-path)
+    destination-path))
+
+(defn execute-upsert-asset
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))]
+        (case (:mode action)
+          :create
+          (p/let [asset-path (:asset-path action)
+                  _ (ensure-asset-file-path! asset-path)
+                  metadata (read-asset-file-metadata asset-path)
+                  asset-tag-id (ensure-asset-tag-id! cfg (:repo action))
+                  action* (update action
+                                  :blocks
+                                  (fn [blocks]
+                                    (if (seq blocks)
+                                      (update blocks 0 merge
+                                              {:logseq.property.asset/type (:asset/type metadata)
+                                               :logseq.property.asset/size (:asset/size metadata)
+                                               :logseq.property.asset/checksum (:asset/checksum metadata)
+                                               :block/tags #{asset-tag-id}})
+                                      blocks)))
+                  create-result (add-command/execute-add-block (assoc action* :type :add-block) config)
+                  created-ids (vec (or (get-in create-result [:data :result]) []))
+                  created-id (first created-ids)
+                  _ (when-not (some? created-id)
+                      (throw (ex-info "asset block not created"
+                                      {:code :asset-create-failed})))
+                  created-entity (pull-entity-by-id cfg (:repo action) [:db/id :block/uuid] created-id)
+                  block-uuid (:block/uuid created-entity)
+                  _ (when-not (uuid? block-uuid)
+                      (throw (ex-info "created asset block missing uuid"
+                                      {:code :asset-create-failed
+                                       :id created-id})))
+                  _ (copy-asset-file-to-graph! config
+                                              (:repo action)
+                                              block-uuid
+                                              (:asset/type metadata)
+                                              asset-path)]
+            {:status :ok
+             :data {:result [created-id]}})
+
+          :update
+          (p/let [entity (ensure-asset-node! cfg (:repo action) action)
+                  node-id (:db/id entity)
+                  _ (when (seq (:content action))
+                      (update-command/execute-update (-> action
+                                                         (assoc :type :update-block
+                                                                :id node-id)
+                                                         (dissoc :uuid))
+                                                    config))]
+            {:status :ok
+             :data {:result [node-id]}})
+
+          {:status :error
+           :error {:code :invalid-options
+                   :message "invalid upsert asset mode"}}))
+      (p/catch (fn [e]
+                 {:status :error
+                  :error (merge {:code (or (:code (ex-data e)) :exception)
+                                 :message (or (ex-message e) (str e))}
+                                (when-let [candidates (:candidates (ex-data e))]
+                                  {:candidates candidates}))}))))
+
+(defn execute-upsert-tag
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              update-by-id? (= :update (:mode action))]
+        (if update-by-id?
+          (p/let [entity (ensure-tag-by-id! cfg (:repo action) (:id action))
+                  target-name (:name action)
+                  target (when (seq target-name)
+                           (pull-tag-by-name cfg (:repo action) target-name tag-selector))
+                  conflict (when (and (seq target-name)
+                                      (not (rename-target-same-as-current? entity target-name)))
+                             (rename-target-conflict entity target))
+                  _ (when (and (seq target-name)
+                               (not conflict)
+                               (not (rename-target-same-as-current? entity target-name)))
+                      (transport/invoke cfg :thread-api/apply-outliner-ops false
+                                        [(:repo action)
+                                         [[:rename-page [(:block/uuid entity) target-name]]]
+                                         {}]))]
+            (if conflict
+              {:status :error
+               :error conflict}
+              {:status :ok
+               :data {:result [(:db/id entity)]}}))
+          (p/let [existing (pull-tag-by-name cfg (:repo action) (:name action)
+                                             [:db/id :block/name :block/title
+                                              {:block/tags [:db/ident]}])
+                  existing-id (:db/id existing)]
+            (p/let [_ (when-not existing-id
+                        (transport/invoke cfg :thread-api/apply-outliner-ops false
+                                          [(:repo action)
+                                           [[:create-page [(:name action) {:class? true}]]]
+                                           {}]))
+                    page (or (when existing-id existing)
+                             (pull-tag-by-name cfg (:repo action) (:name action)
+                                               [:db/id :block/name :block/title
+                                                {:block/tags [:db/ident]}]))
+                    page-id (:db/id page)]
+              (cond
+                (not page-id)
+                {:status :error
+                 :error {:code :tag-not-found
+                         :message "tag not found after upsert"}}
+
+                (not (tag-entity? page))
+                {:status :error
+                 :error {:code :tag-create-not-tag
+                         :message "created entity is not tagged as :logseq.class/Tag"}}
+
+                :else
+                {:status :ok
+                 :data {:result [page-id]}})))))
+      (p/catch (fn [e]
+                 {:status :error
+                  :error (merge {:code (or (:code (ex-data e)) :exception)
+                                 :message (or (ex-message e) (str e))}
+                                (when-let [candidates (:candidates (ex-data e))]
+                                  {:candidates candidates}))}))))
+
+(defn execute-upsert-property
+  [action config]
+  (-> (p/let [cfg (cli-server/ensure-server! config (:repo action))
+              update-by-id? (= :update (:mode action))]
+        (if update-by-id?
+          (p/let [existing (ensure-property-by-id! cfg (:repo action) (:id action))
+                  property-ident (:db/ident existing)
+                  _ (when (seq (:schema action))
+                      (transport/invoke cfg :thread-api/apply-outliner-ops false
+                                        [(:repo action)
+                                         [[:upsert-property [property-ident
+                                                             (:schema action)
+                                                             {}]]]
+                                         {}]))]
+            {:status :ok
+             :data {:result [(:db/id existing)]}})
+          (p/let [existing (pull-property-by-name cfg (:repo action) (:name action) property-selector)
+                  existing-id (:db/id existing)]
+            (p/let [property-ident (when existing-id (:db/ident existing))
+                    property-opts (cond-> {}
+                                    (nil? property-ident)
+                                    (assoc :property-name (:name action)))
+                    _ (transport/invoke cfg :thread-api/apply-outliner-ops false
+                                        [(:repo action)
+                                         [[:upsert-property [property-ident
+                                                             (:schema action)
+                                                             property-opts]]]
+                                         {}])
+                    property (pull-property-by-name cfg (:repo action) (:name action) property-selector)
+                    property-id (:db/id property)]
+              (if property-id
+                {:status :ok
+                 :data {:result [property-id]}}
+                {:status :error
+                 :error {:code :property-not-found
+                         :message "property not found after upsert"}})))))
+      (p/catch (fn [e]
+                 {:status :error
+                  :error (merge {:code (or (:code (ex-data e)) :exception)
+                                 :message (or (ex-message e) (str e))}
+                                (when-let [candidates (:candidates (ex-data e))]
+                                  {:candidates candidates}))}))))
diff --git a/src/main/logseq/cli/commands.cljs b/src/main/logseq/cli/commands.cljs
new file mode 100644
index 0000000000..2d47dbf3f8
--- /dev/null
+++ b/src/main/logseq/cli/commands.cljs
@@ -0,0 +1,752 @@
+(ns logseq.cli.commands
+  "Command parsing and action building for the Logseq CLI."
+  (:require [babashka.cli :as cli]
+            [clojure.string :as string]
+            [logseq.cli.command.auth :as auth-command]
+            [logseq.cli.command.completion :as completion-command]
+            [logseq.cli.command.core :as command-core]
+            [logseq.cli.command.debug :as debug-command]
+            [logseq.cli.command.doctor :as doctor-command]
+            [logseq.cli.command.example :as example-command]
+            [logseq.cli.command.graph :as graph-command]
+            [logseq.cli.command.list :as list-command]
+            [logseq.cli.command.query :as query-command]
+            [logseq.cli.command.remove :as remove-command]
+            [logseq.cli.command.search :as search-command]
+            [logseq.cli.command.server :as server-command]
+            [logseq.cli.command.show :as show-command]
+            [logseq.cli.command.skill :as skill-command]
+            [logseq.cli.command.sync :as sync-command]
+            [logseq.cli.command.upsert :as upsert-command]
+            [logseq.cli.completion-generator :as completion-gen]
+            [logseq.cli.server :as cli-server]
+            [promesa.core :as p]))
+
+(def ^:private global-spec
+  (command-core/global-spec))
+
+;; Parsing helpers and summaries are in logseq.cli.command.core.
+
+(defn- missing-result
+  [summary code message]
+  {:ok? false
+   :error {:code code
+           :message message}
+   :summary summary})
+
+(defn- missing-graph-result
+  [summary]
+  (missing-result summary :missing-graph "graph name is required"))
+
+(defn- missing-content-result
+  [summary]
+  (missing-result summary :missing-content "content is required"))
+
+(defn- missing-target-result
+  [summary]
+  (missing-result summary :missing-target "block or page is required"))
+
+(defn- missing-page-name-result
+  [summary]
+  (missing-result summary :missing-page-name "page name is required"))
+
+(defn- missing-tag-name-result
+  [summary]
+  (missing-result summary :missing-tag-name "tag name is required"))
+
+(defn- missing-property-name-result
+  [summary]
+  (missing-result summary :missing-property-name "property name is required"))
+
+(defn- missing-type-result
+  [summary]
+  (missing-result summary :missing-type "type is required"))
+
+(defn- missing-input-result
+  [summary]
+  (missing-result summary :missing-input "input is required"))
+
+(defn- missing-file-result
+  [summary]
+  (missing-result summary :missing-file "file is required"))
+
+(defn- missing-src-result
+  [summary]
+  (missing-result summary :missing-src "src is required"))
+
+(defn- missing-dst-result
+  [summary]
+  (missing-result summary :missing-dst "dst is required"))
+
+(defn- missing-query-result
+  [summary]
+  (missing-result summary :missing-query "query is required"))
+
+(defn- missing-query-text-result
+  [summary]
+  (missing-result summary :missing-query-text "query text is required"))
+
+;; Error helpers are in logseq.cli.command.core.
+
+;; Command-specific validation and entries are in subcommand namespaces.
+
+(def ^:private base-table
+  (vec (concat graph-command/entries
+               server-command/entries
+               list-command/entries
+               upsert-command/entries
+               remove-command/entries
+               query-command/entries
+               search-command/entries
+               show-command/entries
+               doctor-command/entries
+               debug-command/entries
+               sync-command/entries
+               auth-command/entries
+               completion-command/entries
+               skill-command/entries)))
+
+(def ^:private table
+  (vec (concat base-table
+               (example-command/build-example-entries base-table))))
+
+;; Global option parsing lives in logseq.cli.command.core.
+
+(defn- index-of
+  [coll value]
+  (first (keep-indexed (fn [idx item]
+                         (when (= item value) idx))
+                       coll)))
+
+(defn- inject-stdin-id-arg
+  [args]
+  (if (and (seq args) (= "show" (first args)))
+    (if-let [idx (index-of args "--id")]
+      (let [next-token (nth args (inc idx) nil)
+            missing-value? (or (nil? next-token)
+                               (string/starts-with? next-token "-"))]
+        (if missing-value?
+          {:args (vec (concat (subvec args 0 (inc idx))
+                              [""]
+                              (subvec args (inc idx))))
+           :id-from-stdin? true}
+          {:args args :id-from-stdin? false}))
+      {:args args :id-from-stdin? false})
+    {:args args :id-from-stdin? false}))
+
+(defn- unknown-command-message
+  [{:keys [dispatch wrong-input]}]
+  (string/join " " (cond-> (vec dispatch)
+                     wrong-input (conj wrong-input))))
+
+(defn- legacy-upsert-option-guidance
+  [args message]
+  (let [subcommand (vec (take 2 args))
+        message (or message "")]
+    (cond
+      (and (= ["upsert" "block"] subcommand)
+           (re-find #"Unknown option:\s*:tags" message))
+      "unknown option: --tags; use --update-tags"
+
+      (and (= ["upsert" "block"] subcommand)
+           (re-find #"Unknown option:\s*:properties" message))
+      "unknown option: --properties; use --update-properties"
+
+      (and (= ["upsert" "block"] subcommand)
+           (re-find #"Unknown option:\s*:status" message))
+      "unknown option: --status; use upsert task --status"
+
+      (and (= ["upsert" "page"] subcommand)
+           (re-find #"Unknown option:\s*:tags" message))
+      "unknown option: --tags; use --update-tags"
+
+      (and (= ["upsert" "page"] subcommand)
+           (re-find #"Unknown option:\s*:properties" message))
+      "unknown option: --properties; use --update-properties"
+
+      (and (= ["upsert" "task"] subcommand)
+           (or (re-find #"Unknown option:\s*:update-tags" message)
+               (re-find #"Unknown option:\s*:update-properties" message)
+               (re-find #"Unknown option:\s*:remove-tags" message)
+               (re-find #"Unknown option:\s*:remove-properties" message)))
+      "unknown option: use upsert block for --update-tags/--update-properties/--remove-tags/--remove-properties"
+
+      :else
+      nil)))
+
+(defn- legacy-search-query-guidance
+  [cmds]
+  (let [scope (or (second cmds) "<scope>")]
+    (str "legacy positional search query is not supported; use --content, e.g. logseq search "
+         scope
+         " --content <query>")))
+
+(def ^:private graph-write-commands
+  #{:graph-create :graph-switch :graph-remove :graph-import})
+
+(def ^:private upsert-validation-commands
+  #{:upsert-block :upsert-page :upsert-task :upsert-tag :upsert-property :upsert-asset})
+
+(def ^:private search-validation-commands
+  #{:search-block :search-page :search-property :search-tag})
+
+(def ^:private list-validation-commands
+  #{:list-page :list-tag :list-property :list-task :list-node :list-asset})
+
+(def ^:private remove-validation-commands
+  #{:remove-block :remove-page :remove-tag :remove-property})
+
+(def ^:private server-graph-required-commands
+  #{:server-start :server-stop :server-restart})
+
+(def ^:private supported-completion-shells
+  #{"zsh" "bash"})
+
+(defn- completion-shell-error-message
+  [shell]
+  (when-not (supported-completion-shells shell)
+    (if (seq shell)
+      (str "unsupported shell: " shell "; expected zsh or bash")
+      "missing shell argument; usage: logseq completion <zsh|bash>")))
+
+(defn- validate-write-and-upsert
+  [summary {:keys [command opts graph has-content? upsert-update-mode?
+                   upsert-invalid-options-message]}]
+  (cond
+    ;; Require graphs when writing to graph
+    (and (graph-write-commands command)
+         (not (seq graph)))
+    (missing-graph-result summary)
+
+    (and (= command :upsert-block) (not upsert-update-mode?) (not has-content?))
+    (missing-content-result summary)
+
+    (and (= command :upsert-block) upsert-invalid-options-message)
+    (command-core/invalid-options-result summary upsert-invalid-options-message)
+
+    (and (= command :upsert-page) upsert-invalid-options-message)
+    (command-core/invalid-options-result summary upsert-invalid-options-message)
+
+    (and (= command :upsert-page)
+         (not (some? (:id opts)))
+         (not (seq (:page opts))))
+    (missing-page-name-result summary)
+
+    (and (= command :upsert-task) upsert-invalid-options-message)
+    (command-core/invalid-options-result summary upsert-invalid-options-message)
+
+    (and (= command :upsert-task)
+         (not (some? (:id opts)))
+         (not (seq (some-> (:uuid opts) string/trim)))
+         (not (seq (some-> (:page opts) string/trim)))
+         (not (seq (some-> (:content opts) string/trim))))
+    (missing-target-result summary)
+
+    (and (= command :upsert-tag) upsert-invalid-options-message)
+    (command-core/invalid-options-result summary upsert-invalid-options-message)
+
+    (and (= command :upsert-tag)
+         (not (some? (:id opts)))
+         (not (seq (some-> (:name opts) string/trim))))
+    (missing-tag-name-result summary)
+
+    (and (= command :upsert-property) upsert-invalid-options-message)
+    (command-core/invalid-options-result summary upsert-invalid-options-message)
+
+    (and (= command :upsert-property)
+         (not (some? (:id opts)))
+         (not (seq (some-> (:name opts) string/trim))))
+    (missing-property-name-result summary)
+
+    (and (= command :upsert-asset) upsert-invalid-options-message)
+    (command-core/invalid-options-result summary upsert-invalid-options-message)
+
+    :else
+    nil))
+
+(defn- validate-target-query-and-search
+  [summary {:keys [command opts args cmds show-targets]}]
+  (cond
+    (and (= command :remove-block) (empty? (filter some? [(:id opts) (some-> (:uuid opts) string/trim)])))
+    (missing-target-result summary)
+
+    (and (= command :remove-page)
+         (not (some? (:id opts)))
+         (not (seq (some-> (:page opts) string/trim))))
+    (missing-page-name-result summary)
+
+    (and (#{:remove-tag :remove-property} command)
+         (empty? (filter some? [(:id opts) (some-> (:name opts) string/trim)])))
+    (missing-target-result summary)
+
+    (and (= command :show) (empty? show-targets))
+    (missing-target-result summary)
+
+    (and (= command :show) (> (count show-targets) 1))
+    (command-core/invalid-options-result summary "only one of --id, --uuid, or --page is allowed")
+
+    (and (= command :query)
+         (not (seq (some-> (:query opts) string/trim)))
+         (not (seq (some-> (:name opts) string/trim))))
+    (missing-query-result summary)
+
+    (and (search-validation-commands command)
+         (seq args))
+    (command-core/invalid-options-result summary (legacy-search-query-guidance cmds))
+
+    (and (search-validation-commands command)
+         (not (seq (some-> (:content opts) str string/trim))))
+    (assoc (missing-query-text-result summary) :command command)
+
+    :else
+    nil))
+
+(defn- validate-option-contracts
+  [summary {:keys [command list-invalid-options-message remove-invalid-options-message
+                   show-invalid-options-message debug-invalid-options-message]}]
+  (cond
+    (and (list-validation-commands command)
+         list-invalid-options-message)
+    (command-core/invalid-options-result summary list-invalid-options-message)
+
+    (and (remove-validation-commands command)
+         remove-invalid-options-message)
+    (command-core/invalid-options-result summary remove-invalid-options-message)
+
+    (and (= command :show) show-invalid-options-message)
+    (command-core/invalid-options-result summary show-invalid-options-message)
+
+    (and (= command :debug-pull) debug-invalid-options-message)
+    (command-core/invalid-options-result summary debug-invalid-options-message)
+
+    :else
+    nil))
+
+(defn- validate-graph-sync-and-completion
+  [summary {:keys [command opts import-export-type completion-shell-error]}]
+  (cond
+    (and (= command :graph-export) (not (seq import-export-type)))
+    (missing-type-result summary)
+
+    (and (= command :graph-export) (not (seq (:file opts))))
+    (missing-file-result summary)
+
+    (and (= command :graph-import) (not (seq import-export-type)))
+    (missing-type-result summary)
+
+    (and (= command :graph-import) (not (seq (:input opts))))
+    (missing-input-result summary)
+
+    (and (= command :graph-backup-restore)
+         (not (seq (some-> (:src opts) string/trim))))
+    (missing-src-result summary)
+
+    (and (= command :graph-backup-restore)
+         (not (seq (some-> (:dst opts) string/trim))))
+    (missing-dst-result summary)
+
+    (and (= command :graph-backup-remove)
+         (not (seq (some-> (:src opts) string/trim))))
+    (missing-src-result summary)
+
+    (and (server-graph-required-commands command)
+         (not (seq (:graph opts))))
+    (missing-graph-result summary)
+
+    (and (= command :sync-download)
+         (not (seq (:graph opts))))
+    (missing-graph-result summary)
+
+    (and (= command :completion)
+         completion-shell-error)
+    (command-core/invalid-options-result summary completion-shell-error)
+
+    :else
+    nil))
+
+(defn- finalize-command-validation-result
+  [summary validation-context]
+  (or (validate-write-and-upsert summary validation-context)
+      (validate-target-query-and-search summary validation-context)
+      (validate-option-contracts summary validation-context)
+      (validate-graph-sync-and-completion summary validation-context)))
+
+(defn- command-has-content?
+  [args opts]
+  (or (seq (:content opts))
+      (seq (:blocks opts))
+      (seq (:blocks-file opts))
+      (seq args)))
+
+(defn- build-validation-context
+  [command opts args cmds]
+  (let [show-targets (filter some? [(:id opts) (:uuid opts) (:page opts)])
+        completion-shell (when (= command :completion)
+                           (or (:shell opts) (first args)))]
+    {:command command
+     :opts opts
+     :args args
+     :cmds cmds
+     :graph (:graph opts)
+     :has-content? (command-has-content? args opts)
+     :show-targets show-targets
+     :upsert-update-mode? (upsert-command/update-mode? opts)
+     :upsert-invalid-options-message (when (upsert-validation-commands command)
+                                       (upsert-command/invalid-options? command opts))
+     :list-invalid-options-message (when (list-validation-commands command)
+                                     (list-command/invalid-options? command opts))
+     :remove-invalid-options-message (when (remove-validation-commands command)
+                                       (remove-command/invalid-options? command opts))
+     :show-invalid-options-message (when (= command :show)
+                                     (show-command/invalid-options? opts))
+     :debug-invalid-options-message (when (= command :debug-pull)
+                                      (debug-command/invalid-options? opts))
+     :import-export-type (graph-command/normalize-import-export-type (:type opts))
+     :completion-shell-error (when (= command :completion)
+                               (completion-shell-error-message completion-shell))}))
+
+(defn- finalize-ok-result
+  [summary command opts args cmds]
+  (cond-> (command-core/ok-result command opts args summary)
+    (= command :example) (assoc :cmds cmds)))
+
+(defn- finalize-command
+  [summary {:keys [command opts args cmds spec long-desc examples]}]
+  (let [opts (-> opts
+                 command-core/normalize-opts
+                 (#(list-command/normalize-options command %)))
+        args (vec args)
+        cmd-summary (command-core/command-summary {:cmds cmds
+                                                   :spec spec
+                                                   :long-desc long-desc
+                                                   :examples (when (= command :example)
+                                                               examples)})
+        validation-context (build-validation-context command opts args cmds)]
+    (cond
+      (:help opts)
+      (command-core/help-result cmd-summary)
+
+      :else
+      (or (finalize-command-validation-result summary validation-context)
+          (finalize-ok-result summary command opts args cmds)))))
+
+;; CLI error handling is in logseq.cli.command.core.
+
+(defn- cmds-prefix?
+  [prefix cmds]
+  (and (<= (count prefix) (count cmds))
+       (= prefix (subvec cmds 0 (count prefix)))))
+
+(def ^:private group-command-paths
+  (->> table
+       (mapcat (fn [{:keys [cmds]}]
+                 (let [cmds (vec cmds)]
+                   (for [n (range 1 (count cmds))]
+                     (subvec cmds 0 n)))))
+       set))
+
+(def ^:private exact-command-paths
+  (->> table
+       (mapv (comp vec :cmds))
+       set))
+
+(def ^:private help-flags
+  #{"-h" "--help"})
+
+(defn- group-help-path
+  [args]
+  (let [args (vec args)
+        candidates (->> group-command-paths
+                        (filter #(cmds-prefix? % args))
+                        (sort-by count >))]
+    (some (fn [path]
+            (let [trailing-args (subvec args (count path))
+                  exact-command? (contains? exact-command-paths (vec path))
+                  help-requested? (and (seq trailing-args)
+                                       (every? help-flags trailing-args))]
+              (when (and (or (empty? trailing-args) help-requested?)
+                         (if exact-command?
+                           ;; When the path is both a group and an exact command:
+                           ;; - `query -h` → show command help (not group help)
+                           ;; - `example query` → execute command (not group help)
+                           ;; - `query` (alone, single-segment) → show group help
+                           ;;   for discoverability since cli/dispatch can't distinguish
+                           ;;   `query` from `query list` prefix
+                           (and (not help-requested?)
+                                (= 1 (count path))
+                                (empty? trailing-args))
+                           true))
+                path)))
+          candidates)))
+
+(defn parse-args
+  [raw-args]
+  (let [summary (command-core/top-level-summary table)
+        {:keys [opts args]} (command-core/parse-leading-global-opts raw-args)
+        {:keys [args id-from-stdin?]} (inject-stdin-id-arg (vec args))
+        group-path (group-help-path args)]
+    (cond
+      (:version opts)
+      (command-core/ok-result :version opts [] summary)
+
+      (empty? args)
+      (command-core/help-result summary)
+
+      group-path
+      (command-core/help-result (command-core/group-summary group-path table))
+
+      :else
+      (try
+        (let [result (cli/dispatch table args {:spec global-spec})]
+          (if (nil? result)
+            (command-core/unknown-command-result summary (str "unknown command: " (string/join " " args)))
+            (finalize-command summary
+                              (update result :opts #(cond-> (merge opts (or % {}))
+                                                      id-from-stdin? (assoc :id-from-stdin? true))))))
+        (catch :default e
+          (let [{:keys [cause] :as data} (ex-data e)]
+            (cond
+              (= cause :input-exhausted)
+              (if-let [path (group-help-path args)]
+                (command-core/help-result (command-core/group-summary path table))
+                (command-core/help-result summary))
+
+              (= cause :no-match)
+              (command-core/unknown-command-result summary (str "unknown command: " (unknown-command-message data)))
+
+              (and (map? data)
+                   (contains? data :msg))
+              (if-let [guided-message (legacy-upsert-option-guidance args (:msg data))]
+                (command-core/invalid-options-result summary guided-message)
+                (command-core/cli-error->result summary data))
+
+              :else
+              (throw e))))))))
+
+;; Repo/graph helpers live in logseq.cli.command.core.
+
+(defn- ensure-existing-graph
+  [action config]
+  (if (and (:repo action) (not (:allow-missing-graph action)))
+    (p/let [graphs (cli-server/list-graphs config)
+            graph (command-core/repo->graph (:repo action))]
+      (if (some #(= graph %) graphs)
+        {:ok? true}
+        {:ok? false
+         :error {:code :graph-not-exists
+                 :message "graph not exists"}}))
+    (p/resolved {:ok? true})))
+
+(defn- ensure-missing-graph
+  [action config]
+  (if (and (:repo action)
+           (:require-missing-graph action))
+    (p/let [graphs (cli-server/list-graphs config)
+            graph (command-core/repo->graph (:repo action))]
+      (if (some #(= graph %) graphs)
+        {:ok? false
+         :error {:code :graph-exists
+                 :message "graph already exists"}}
+        {:ok? true}))
+    (p/resolved {:ok? true})))
+
+;; Repo selection lives in logseq.cli.command.core.
+
+;; Block parsing lives in logseq.cli.command.add.
+
+;; Add/remove helpers live in logseq.cli.command.add/remove.
+
+;; Show helpers live in logseq.cli.command.show.
+
+;; Show helpers live in logseq.cli.command.show.
+
+;; Repo normalization lives in logseq.cli.command.core.
+
+;; Command-specific errors live in subcommand namespaces.
+
+(defn ^:large-vars/cleanup-todo build-action
+  [parsed config]
+  (if-not (:ok? parsed)
+    parsed
+    (let [{:keys [command options args cmds]} parsed
+          graph (command-core/pick-graph options args config)
+          repo (command-core/resolve-repo graph)
+          server-repo (command-core/resolve-repo (:graph options))]
+      (case command
+        (:graph-list :graph-create :graph-switch :graph-remove :graph-validate :graph-info)
+        (graph-command/build-graph-action command graph repo options)
+
+        :graph-backup-list
+        (graph-command/build-backup-list-action repo)
+
+        :graph-backup-create
+        (graph-command/build-backup-create-action repo (:name options))
+
+        :graph-backup-restore
+        (graph-command/build-backup-restore-action repo (:src options) (:dst options))
+
+        :graph-backup-remove
+        (graph-command/build-backup-remove-action repo (:src options))
+
+        :graph-export
+        (let [export-type (graph-command/normalize-import-export-type (:type options))]
+          (graph-command/build-export-action repo export-type (:file options)))
+
+        :graph-import
+        (let [import-repo (command-core/resolve-repo (:graph options))
+              import-type (graph-command/normalize-import-export-type (:type options))]
+          (graph-command/build-import-action import-repo import-type (:input options)))
+
+        (:server-list :server-cleanup :server-start :server-stop :server-restart)
+        (server-command/build-action command server-repo)
+
+        (:list-page :list-tag :list-property :list-task :list-node :list-asset)
+        (list-command/build-action command options repo)
+
+        (:search-block :search-page :search-property :search-tag)
+        (search-command/build-action command options repo)
+
+        :upsert-block
+        (upsert-command/build-block-action options args repo)
+
+        :upsert-page
+        (upsert-command/build-page-action options repo)
+
+        :upsert-task
+        (upsert-command/build-task-action options repo)
+
+        :upsert-asset
+        (upsert-command/build-asset-action options repo)
+
+        :upsert-tag
+        (upsert-command/build-tag-action options repo)
+
+        :upsert-property
+        (upsert-command/build-property-action options repo)
+
+        (:remove-block :remove-page :remove-tag :remove-property)
+        (remove-command/build-action command options repo)
+
+        :query
+        (query-command/build-action options repo config)
+
+        :query-list
+        (query-command/build-list-action options repo)
+
+        :show
+        (show-command/build-action options repo)
+
+        :debug-pull
+        (debug-command/build-action options repo)
+
+        :doctor
+        (doctor-command/build-action options)
+
+        (:sync-status :sync-start :sync-stop :sync-upload :sync-download
+         :sync-remote-graphs :sync-ensure-keys :sync-grant-access
+         :sync-config-set :sync-config-get :sync-config-unset)
+        (sync-command/build-action command options args repo)
+
+        (:login :logout)
+        (auth-command/build-action command)
+
+        :completion
+        {:ok? true
+         :action {:type :completion
+                  :shell (or (:shell options) (first args))}}
+
+        :skill-show
+        (skill-command/build-show-action options)
+
+        :skill-install
+        (skill-command/build-install-action options)
+
+        :example
+        (example-command/build-action base-table cmds)
+
+        {:ok? false
+         :error {:code :unknown-command
+                 :message (str "unknown command: " command)}}))))
+
+(defn execute
+  [action config]
+  (-> (p/let [missing-check (ensure-missing-graph action config)
+              check (ensure-existing-graph action config)
+              result (cond
+                       (not (:ok? missing-check))
+                       {:status :error
+                        :error (:error missing-check)}
+
+                       (not (:ok? check))
+                       {:status :error
+                        :error (:error check)}
+
+                       :else
+                       (case (:type action)
+                         :graph-list (graph-command/execute-graph-list action config)
+                         :graph-backup-list (graph-command/execute-graph-backup-list action config)
+                         :graph-backup-create (graph-command/execute-graph-backup-create action config)
+                         :graph-backup-restore (graph-command/execute-graph-backup-restore action config)
+                         :graph-backup-remove (graph-command/execute-graph-backup-remove action config)
+                         :invoke (graph-command/execute-invoke action config)
+                         :graph-remove (graph-command/execute-graph-remove action config)
+                         :graph-switch (graph-command/execute-graph-switch action config)
+                         :graph-info (graph-command/execute-graph-info action config)
+                         :graph-export (graph-command/execute-graph-export action config)
+                         :graph-import (graph-command/execute-graph-import action config)
+                         :list-page (list-command/execute-list-page action config)
+                         :list-tag (list-command/execute-list-tag action config)
+                         :list-property (list-command/execute-list-property action config)
+                         :list-task (list-command/execute-list-task action config)
+                         :list-node (list-command/execute-list-node action config)
+                         :list-asset (list-command/execute-list-asset action config)
+                         :search-block (search-command/execute-search-block action config)
+                         :search-page (search-command/execute-search-page action config)
+                         :search-property (search-command/execute-search-property action config)
+                         :search-tag (search-command/execute-search-tag action config)
+                         :upsert-block (upsert-command/execute-upsert-block action config)
+                         :upsert-page (upsert-command/execute-upsert-page action config)
+                         :upsert-task (upsert-command/execute-upsert-task action config)
+                         :upsert-asset (upsert-command/execute-upsert-asset action config)
+                         :upsert-tag (upsert-command/execute-upsert-tag action config)
+                         :upsert-property (upsert-command/execute-upsert-property action config)
+                         :remove-block (remove-command/execute-remove-block action config)
+                         :remove-page (remove-command/execute-remove-page action config)
+                         :remove-tag (remove-command/execute-remove-tag action config)
+                         :remove-property (remove-command/execute-remove-property action config)
+                         :query (query-command/execute-query action config)
+                         :query-list (query-command/execute-query-list action config)
+                         :show (show-command/execute-show action config)
+                         :debug-pull (debug-command/execute-debug-pull action config)
+                         :doctor (doctor-command/execute-doctor action config)
+                         :completion (p/resolved
+                                       {:status :ok
+                                        :data {:message (completion-gen/generate-completions
+                                                         (:shell action) table)}})
+                         :skill-show (skill-command/execute-skill-show action config)
+                         :skill-install (skill-command/execute-skill-install action config)
+                         :example (example-command/execute-example action config)
+                         :server-list (server-command/execute-list action config)
+                         :server-cleanup (server-command/execute-cleanup action config)
+                         :server-start (server-command/execute-start action config)
+                         :server-stop (server-command/execute-stop action config)
+                         :server-restart (server-command/execute-restart action config)
+                         (:sync-status :sync-start :sync-stop :sync-upload :sync-download
+                          :sync-remote-graphs :sync-ensure-keys :sync-grant-access
+                          :sync-config-set :sync-config-get :sync-config-unset)
+                         (sync-command/execute action config)
+                         (:login :logout)
+                         (auth-command/execute action config)
+                         {:status :error
+                          :error {:code :unknown-action
+                                  :message "unknown action"}}))]
+        (assoc result
+               :command (or (:command action) (:type action))
+               :context (select-keys action [:repo :graph :page :name :id :ids :uuid :block :blocks
+                                             :schema :query :lookup :selector
+                                             :source :target :update-tags :update-properties
+                                             :remove-tags :remove-properties
+                                             :status :priority
+                                             :src :dst :backup-name
+                                             :export-type :file :import-type :input
+                                             :graph-id :email :config-key :config-value])))))
diff --git a/src/main/logseq/cli/common.cljs b/src/main/logseq/cli/common.cljs
new file mode 100644
index 0000000000..34028c6da9
--- /dev/null
+++ b/src/main/logseq/cli/common.cljs
@@ -0,0 +1,27 @@
+(ns logseq.cli.common
+  "Common fns between CLI and electron"
+  (:require ["fs-extra" :as fs]
+            ["path" :as node-path]
+            [logseq.common.config :as common-config]
+            [logseq.common.graph :as common-graph]
+            [logseq.common.graph-dir :as graph-dir]))
+
+(defn unlink-graph!
+  "Unlinks the given repo by moving it to the 'Unlinked graphs' dir.
+   Returns path of unlinked dir if move is successful or nil if not"
+  ([repo]
+   (unlink-graph! (common-graph/expand-home (common-graph/get-default-graphs-dir)) repo))
+  ([graphs-dir repo]
+   (let [graph-dir-name (graph-dir/repo->encoded-graph-dir-name repo)
+         graphs-dir (common-graph/expand-home graphs-dir)
+         path (node-path/join graphs-dir graph-dir-name)
+         unlinked (node-path/join graphs-dir common-config/unlinked-graphs-dir)
+         new-path (node-path/join unlinked graph-dir-name)
+         new-path-exists? (fs/existsSync new-path)
+         new-path' (if new-path-exists?
+                     (node-path/join unlinked (str graph-dir-name "-" (random-uuid)))
+                     new-path)]
+     (when (fs/existsSync path)
+       (fs/ensureDirSync unlinked)
+       (fs/moveSync path new-path')
+       new-path'))))
diff --git a/src/main/logseq/cli/common/db_worker.cljs b/src/main/logseq/cli/common/db_worker.cljs
new file mode 100644
index 0000000000..4b10b6e6c6
--- /dev/null
+++ b/src/main/logseq/cli/common/db_worker.cljs
@@ -0,0 +1,217 @@
+(ns logseq.cli.common.db-worker
+  "Cli fns for use with db-worker"
+  (:require [clojure.string :as string]
+            [datascript.core :as d]
+            [logseq.db :as ldb]
+            [logseq.db.frontend.entity-util :as entity-util]
+            [logseq.db.frontend.property :as db-property]))
+
+(defn- minimal-list-item
+  [e]
+  (cond-> {:db/id (:db/id e)
+           :block/title (:block/title e)
+           :block/created-at (:block/created-at e)
+           :block/updated-at (:block/updated-at e)}
+    (:db/ident e) (assoc :db/ident (:db/ident e))
+    (:logseq.property/type e) (assoc :logseq.property/type (:logseq.property/type e))))
+
+(defn- normalize-cardinality
+  [value]
+  (or value :db.cardinality/one))
+
+(defn list-properties
+  "List properties for CLI"
+  [db {:keys [expand include-built-in] :as options}]
+  (let [include-built-in? (if (contains? options :include-built-in) include-built-in true)]
+    (->> (d/datoms db :avet :block/tags :logseq.class/Property)
+         (map #(d/entity db (:e %)))
+         (remove (fn [e]
+                   (and (not include-built-in?)
+                        (ldb/built-in? e))))
+         #_((fn [x] (prn :prop-keys (distinct (mapcat keys x))) x))
+         (map (fn [e]
+                (if expand
+                  (cond-> (assoc (into {} e) :db/id (:db/id e))
+                    true
+                    (dissoc :block/tags :block/order :block/refs :block/name :db/index
+                            :logseq.property.embedding/hnsw-label-updated-at :logseq.property/default-value)
+                    true
+                    (update :block/uuid str)
+                    (:logseq.property/classes e)
+                    (update :logseq.property/classes #(mapv :db/ident %))
+                    (:logseq.property/description e)
+                    (update :logseq.property/description db-property/property-value-content))
+                  ;; Keep property type and cardinality in default list output (without --expand).
+                  (assoc (minimal-list-item e)
+                         :logseq.property/type (:logseq.property/type e)
+                         :db/cardinality (normalize-cardinality (:db/cardinality e)))))))))
+
+(defn list-tags
+  "List tags for CLI"
+  [db {:keys [expand include-built-in] :as options}]
+  (let [include-built-in? (if (contains? options :include-built-in) include-built-in true)]
+    (->> (d/datoms db :avet :block/tags :logseq.class/Tag)
+         (map #(d/entity db (:e %)))
+         (remove (fn [e]
+                   (and (not include-built-in?)
+                        (ldb/built-in? e))))
+         (map (fn [e]
+                (if expand
+                  (cond-> (assoc (into {} e) :db/id (:db/id e))
+                    true
+                    (dissoc :block/tags :block/order :block/refs :block/name
+                            :logseq.property.embedding/hnsw-label-updated-at)
+                    true
+                    (update :block/uuid str)
+                    (:logseq.property.class/extends e)
+                    (update :logseq.property.class/extends #(mapv :db/ident %))
+                    (:logseq.property.class/properties e)
+                    (update :logseq.property.class/properties #(mapv :db/ident %))
+                    (:logseq.property.view/type e)
+                    (assoc :logseq.property.view/type (:db/ident (:logseq.property.view/type e)))
+                    (:logseq.property/description e)
+                    (update :logseq.property/description db-property/property-value-content))
+                  (minimal-list-item e)))))))
+
+(defn- ref->ident
+  [value]
+  (cond
+    (keyword? value) value
+    (map? value) (:db/ident value)
+    :else nil))
+
+(defn- minimal-task-item
+  [e]
+  (cond-> (minimal-list-item e)
+    true (assoc :logseq.property/status (ref->ident (:logseq.property/status e))
+                :logseq.property/priority (ref->ident (:logseq.property/priority e))
+                :logseq.property/scheduled (:logseq.property/scheduled e)
+                :logseq.property/deadline (:logseq.property/deadline e))))
+
+(defn list-tasks
+  "List task nodes (both pages and blocks) tagged with :logseq.class/Task."
+  [db {:keys [status priority content]}]
+  (let [status* (ref->ident status)
+        priority* (ref->ident priority)
+        content* (some-> content str string/lower-case)]
+    (->> (d/datoms db :avet :block/tags :logseq.class/Task)
+         (map #(d/entity db (:e %)))
+         (remove (fn [e]
+                   (and status*
+                        (not= status* (ref->ident (:logseq.property/status e))))))
+         (remove (fn [e]
+                   (and priority*
+                        (not= priority* (ref->ident (:logseq.property/priority e))))))
+         (remove (fn [e]
+                   (and (seq content*)
+                        (not (string/includes? (string/lower-case (or (:block/title e) ""))
+                                               content*)))))
+         (map minimal-task-item))))
+
+(defn- schema-definition-entity?
+  [entity]
+  (let [tag-idents (->> (:block/tags entity)
+                        (map :db/ident)
+                        set)]
+    (or (contains? tag-idents :logseq.class/Tag)
+        (contains? tag-idents :logseq.class/Property))))
+
+(defn- ordinary-node-entities
+  [db]
+  (let [pages (->> (d/datoms db :avet :block/name)
+                   (map #(d/entity db (:e %))))
+        blocks (->> (d/datoms db :avet :block/page)
+                    (map #(d/entity db (:e %))))]
+    (->> (concat pages blocks)
+         (remove schema-definition-entity?)
+         (reduce (fn [acc entity]
+                   (assoc acc (:db/id entity) entity))
+                 {})
+         vals)))
+
+(defn- has-all-tag-ids?
+  [entity tag-ids]
+  (if (seq tag-ids)
+    (let [node-tag-ids (->> (:block/tags entity)
+                            (map :db/id)
+                            set)]
+      (every? node-tag-ids tag-ids))
+    true))
+
+(defn- has-all-properties?
+  [entity property-idents]
+  (if (seq property-idents)
+    (every? #(contains? entity %) property-idents)
+    true))
+
+(defn- minimal-node-item
+  [entity]
+  (let [page (:block/page entity)
+        block? (some? page)
+        asset-type (:logseq.property.asset/type entity)
+        asset-size (:logseq.property.asset/size entity)]
+    (cond-> (assoc (minimal-list-item entity)
+                   :node/type (if block? "block" "page")
+                   :block/uuid (:block/uuid entity))
+      (:db/ident entity) (assoc :db/ident (:db/ident entity))
+      block? (assoc :block/page-id (:db/id page)
+                    :block/page-title (:block/title page))
+      (some? asset-type) (assoc :logseq.property.asset/type asset-type)
+      (some? asset-size) (assoc :logseq.property.asset/size asset-size))))
+
+(defn list-nodes
+  "List ordinary nodes (pages and blocks) filtered by tags/properties."
+  [db {:keys [tag-ids property-idents]}]
+  (let [tag-ids (->> tag-ids (remove nil?) vec)
+        property-idents (->> property-idents (remove nil?) vec)]
+    (->> (ordinary-node-entities db)
+         (filter #(has-all-tag-ids? % tag-ids))
+         (filter #(has-all-properties? % property-idents))
+         (map minimal-node-item))))
+
+(defn- parse-time
+  [value]
+  (cond
+    (number? value) value
+    (string? value) (let [ms (js/Date.parse value)]
+                      (when-not (js/isNaN ms) ms))
+    :else nil))
+
+(defn list-pages
+  "List pages for CLI"
+  [db {:keys [expand include-hidden include-built-in include-journal journal-only created-after updated-after] :as options}]
+  (let [include-hidden? (boolean include-hidden)
+        include-built-in? (if (contains? options :include-built-in) include-built-in true)
+        include-journal? (if (contains? options :include-journal) include-journal true)
+        journal-only? (boolean journal-only)
+        created-after-ms (parse-time created-after)
+        updated-after-ms (parse-time updated-after)]
+    (->> (d/datoms db :avet :block/name)
+         (map #(d/entity db (:e %)))
+         (remove (fn [e]
+                   (and (not include-hidden?)
+                        (entity-util/hidden? e))))
+         (remove (fn [e]
+                   (and (not include-built-in?)
+                        (ldb/built-in? e))))
+         (remove (fn [e]
+                   (let [is-journal? (ldb/journal? e)]
+                     (cond
+                       journal-only? (not is-journal?)
+                       (false? include-journal?) is-journal?
+                       :else false))))
+         (remove (fn [e]
+                   (and created-after-ms
+                        (<= (:block/created-at e 0) created-after-ms))))
+         (remove (fn [e]
+                   (and updated-after-ms
+                        (<= (:block/updated-at e 0) updated-after-ms))))
+         (map (fn [e]
+                (if expand
+                  ;; Until there are options to limit pages, return minimal info to avoid
+                  ;; exceeding max payload size
+                  (-> (select-keys e [:block/uuid :block/title :block/created-at :block/updated-at])
+                      (assoc :db/id (:db/id e))
+                      (cond-> (:db/ident e) (assoc :db/ident (:db/ident e)))
+                      (update :block/uuid str))
+                  (minimal-list-item e)))))))
diff --git a/src/main/logseq/cli/completion_generator.cljs b/src/main/logseq/cli/completion_generator.cljs
new file mode 100644
index 0000000000..5715eb2b79
--- /dev/null
+++ b/src/main/logseq/cli/completion_generator.cljs
@@ -0,0 +1,1197 @@
+(ns logseq.cli.completion-generator
+  "Pure function: (generate-completions shell table) → string.
+   Walks the CLI command table and emits zsh or bash completion scripts."
+  (:require [clojure.string :as string]))
+
+;; ---------------------------------------------------------------------------
+;; Table introspection utilities
+;; ---------------------------------------------------------------------------
+
+(defn extract-groups
+  "Given a table of entries, group by the first element of :cmds.
+   Returns a map of {group-name [entries...]}."
+  [table]
+  (reduce (fn [acc entry]
+            (let [cmds (:cmds entry)
+                  group (first cmds)]
+              (update acc group (fnil conj []) entry)))
+          {}
+          table))
+
+(defn leaf-commands
+  "Return entries that are leaf commands (single-element :cmds)."
+  [table]
+  (let [groups (extract-groups table)]
+    (->> groups
+         (filter (fn [[_ entries]]
+                   (and (= 1 (count entries))
+                        (= 1 (count (:cmds (first entries)))))))
+         (mapv (fn [[_ entries]] (first entries))))))
+
+(defn group-commands
+  "Return group names that have subcommands (multi-element :cmds entries)."
+  [table]
+  (let [groups (extract-groups table)]
+    (->> groups
+         (filter (fn [[_ entries]]
+                   (or (> (count entries) 1)
+                       (> (count (:cmds (first entries))) 1))))
+         (mapv first))))
+
+(defn spec->token
+  "Convert a single spec entry [key spec-map] to a token descriptor.
+   Returns {:key k :type t ...} with type being one of:
+   :flag, :enum, :multi, :dynamic, :file, :dir, :free"
+  [[k spec-map]]
+  (let [alias (:alias spec-map)
+        desc (or (:desc spec-map) "")
+        coerce (:coerce spec-map)
+        validate (:validate spec-map)
+        values (if (set? validate) validate (:values spec-map))
+        multiple-values (:multiple-values spec-map)
+        complete (:complete spec-map)]
+    (cond-> {:key k
+             :desc desc}
+      alias (assoc :alias alias)
+      (= coerce :boolean) (assoc :type :flag)
+      (and (not= coerce :boolean) (seq multiple-values)) (assoc :type :multi :values (sort multiple-values))
+      (and (not= coerce :boolean) (nil? multiple-values) (seq values)) (assoc :type :enum :values (sort values))
+      (and (not= coerce :boolean) (nil? multiple-values) (nil? values) (= complete :graphs)) (assoc :type :dynamic :complete :graphs)
+      (and (not= coerce :boolean) (nil? multiple-values) (nil? values) (= complete :pages)) (assoc :type :dynamic :complete :pages)
+      (and (not= coerce :boolean) (nil? multiple-values) (nil? values) (= complete :tags)) (assoc :type :dynamic :complete :tags)
+      (and (not= coerce :boolean) (nil? multiple-values) (nil? values) (= complete :properties)) (assoc :type :dynamic :complete :properties)
+      (and (not= coerce :boolean) (nil? multiple-values) (nil? values) (= complete :queries)) (assoc :type :dynamic :complete :queries)
+      (and (not= coerce :boolean) (nil? multiple-values) (nil? values) (= complete :file)) (assoc :type :file)
+      (and (not= coerce :boolean) (nil? multiple-values) (nil? values) (= complete :dir)) (assoc :type :dir)
+      (and (not= coerce :boolean) (nil? multiple-values) (nil? values) (nil? complete)) (assoc :type :free))))
+
+(defn spec->tokens
+  "Convert a full spec map to a vector of token descriptors."
+  [spec]
+  (mapv spec->token spec))
+
+;; ---------------------------------------------------------------------------
+;; Value-quoting helpers (handle whitespace in :values entries)
+;; ---------------------------------------------------------------------------
+
+(defn- contains-whitespace?
+  "Return true if any value in `values` contains whitespace."
+  [values]
+  (boolean (some #(re-find #"\s" %) values)))
+
+(defn- zsh-paren-value
+  "Backslash-escape whitespace in `v` so it stays a single token inside a zsh
+   `_arguments` parenthesized action like `(item1 item2 ...)`. Values without
+   whitespace are returned unchanged."
+  [v]
+  (string/replace v #"\s" #(str "\\" %)))
+
+(defn- zsh-shell-value
+  "Wrap `v` in double quotes if it contains whitespace, so the value survives
+   shell word-splitting inside a zsh `{shell-cmd}` action. Values without
+   whitespace are returned unchanged."
+  [v]
+  (if (re-find #"\s" v)
+    (str "\"" v "\"")
+    v))
+
+(defn- bash-quote-value
+  "Single-quote `v` for bash if it contains whitespace, escaping any embedded
+   single quotes via the standard `'\\''` idiom. Values without whitespace are
+   returned unchanged."
+  [v]
+  (if (re-find #"\s" v)
+    (str "'" (string/replace v "'" "'\\''") "'")
+    v))
+
+;; ---------------------------------------------------------------------------
+;; Zsh dynamic helpers (verbatim preamble)
+;; ---------------------------------------------------------------------------
+
+(def ^:private ^:large-vars/cleanup-todo zsh-preamble
+  "#compdef logseq
+# Auto-generated by `logseq completion zsh` — do not edit manually.
+
+# --- dynamic helpers ---
+
+_logseq_json_names() {
+  # Navigate a JSON path and print leaf strings.
+  # Usage: _logseq_json_names key1 key2 ... keyN
+  # Each key navigates into the JSON object. The final array is printed:
+  #   - strings are printed directly
+  #   - objects have the last key extracted as a field
+  python3 -c \"
+import sys, json
+keys = sys.argv[1:]
+try:
+    data = json.load(sys.stdin)
+    for key in keys:
+        if isinstance(data, dict):
+            data = data.get(key, [])
+        elif isinstance(data, list):
+            for item in data:
+                if isinstance(item, dict):
+                    v = item.get(key)
+                    if isinstance(v, str) and v:
+                        print(v)
+            sys.exit(0)
+    if isinstance(data, list):
+        for item in data:
+            if isinstance(item, str) and item:
+                print(item)
+except Exception:
+    pass
+\" \"$@\" 2>/dev/null
+}
+
+_logseq_current_graph() {
+  local i w
+  for (( i = 1; i < ${#words[@]}; i++ )); do
+    w=\"${words[i]}\"
+    if [[ \"$w\" == '--graph' || \"$w\" == '-g' ]] && [[ -n \"${words[i+1]}\" ]]; then
+      print -r -- \"${words[i+1]}\"
+      return
+    elif [[ \"$w\" == --graph=* ]]; then
+      print -r -- \"${w#--graph=}\"
+      return
+    fi
+  done
+  # Fall back to the current graph from 'logseq graph list' (marked with '* ')
+  logseq graph list 2>/dev/null | sed -n 's/^[*] //p'
+}
+
+_logseq_graphs() {
+  local -a graphs
+  graphs=( ${(f)\"$(logseq graph list --output json 2>/dev/null | _logseq_json_names data graphs)\"} )
+  compadd -a graphs
+}
+
+_logseq_pages() {
+  local graph
+  graph=$(_logseq_current_graph)
+  if [[ -n \"$graph\" ]]; then
+    local -a pages
+    pages=( ${(f)\"$(logseq list page --graph \"$graph\" --output json 2>/dev/null | _logseq_json_names data items block/title)\"} )
+    compadd -a pages
+  fi
+}
+
+_logseq_tags() {
+  local graph
+  graph=$(_logseq_current_graph)
+  if [[ -n \"$graph\" ]]; then
+    local -a tags
+    tags=( ${(f)\"$(logseq list tag --graph \"$graph\" --output json 2>/dev/null | _logseq_json_names data items block/title)\"} )
+    compadd -a tags
+  fi
+}
+
+_logseq_properties() {
+  local graph
+  graph=$(_logseq_current_graph)
+  if [[ -n \"$graph\" ]]; then
+    local -a properties
+    properties=( ${(f)\"$(logseq list property --graph \"$graph\" --output json 2>/dev/null | _logseq_json_names data items block/title)\"} )
+    compadd -a properties
+  fi
+}
+
+_logseq_queries() {
+  local graph
+  graph=$(_logseq_current_graph)
+  if [[ -n \"$graph\" ]]; then
+    local -a queries
+    queries=( ${(f)\"$(logseq query list --graph \"$graph\" --output json 2>/dev/null | _logseq_json_names data queries name)\"} )
+    compadd -a queries
+  fi
+}
+
+_logseq_multi_values() {
+  # Complete comma-delimited lists. Usage: _logseq_multi_values val1 val2 ...
+  local -a all_values=(\"$@\")
+  local cur=\"${PREFIX}${SUFFIX}\"
+  local prefix='' remaining=\"$cur\"
+
+  # Split on last comma to get prefix and partial token
+  if [[ \"$cur\" == *,* ]]; then
+    prefix=\"${cur%,*},\"
+    remaining=\"${cur##*,}\"
+  fi
+
+  # Filter out already-selected values
+  local -a already=(${(s:,:)cur})
+  local -a candidates=()
+  for v in \"${all_values[@]}\"; do
+    if [[ ! \" ${already[*]} \" == *\" $v \"* ]]; then
+      candidates+=(\"$v\")
+    fi
+  done
+
+  compadd -p \"$prefix\" -S ',' -- \"${candidates[@]}\"
+}
+")
+
+;; ---------------------------------------------------------------------------
+;; Zsh generation
+;; ---------------------------------------------------------------------------
+
+(defn- zsh-option-name
+  [k]
+  (str "--" (name k)))
+
+(defn- zsh-escape-desc
+  [desc]
+  (-> desc
+      (string/replace "[" "\\[")
+      (string/replace "]" "\\]")
+      (string/replace "'" "'\\''")))
+
+(defn zsh-token-for
+  "Generate zsh _arguments token strings for a spec token descriptor.
+   Returns a vector of one or two strings. Aliased value-taking options produce
+   separate long (--opt=) and short (-o+) specs so that -o=val is not suggested
+   (babashka.cli does not support = with short aliases).
+   no-prefix-keys: set of keys that get --no-<option> completions."
+  [{:keys [key type alias desc values complete]} no-prefix-keys]
+  (let [long-opt (zsh-option-name key)
+        desc* (zsh-escape-desc desc)
+        alias-short (when alias (str "-" (name alias)))
+        ;; Exclusion list shared by aliased value-option pairs
+        excl (when alias (str "(" alias-short " " long-opt ")"))]
+    (case type
+      :flag
+      (let [no-prefix? (contains? no-prefix-keys key)
+            no-opt (str "--no-" (name key))]
+        (if alias
+          [(str "'" "(" alias-short " " long-opt (when no-prefix? (str " " no-opt)) ")" "'"
+                "{" alias-short "," long-opt "}"
+                "'[" desc* "]'")]
+          [(if no-prefix?
+             (str "'(" long-opt " " no-opt ")" long-opt "[" desc* "]'")
+             (str "'" long-opt "[" desc* "]'"))]))
+
+      :enum
+      (let [vals-str (->> values (map zsh-paren-value) (string/join " "))]
+        (if alias
+          [(str "'" excl long-opt "=[" desc* "]:value:(" vals-str ")'")
+           (str "'" excl alias-short "[" desc* "]:value:(" vals-str ")'")]
+          [(str "'" long-opt "=[" desc* "]:value:(" vals-str ")'")]))
+
+      :multi
+      (let [vals-str (->> values (map zsh-shell-value) (string/join " "))]
+        (if alias
+          [(str "'" excl long-opt "=[" desc* "]:value:{_logseq_multi_values " vals-str "}'")
+           (str "'" excl alias-short "[" desc* "]:value:{_logseq_multi_values " vals-str "}'")]
+          [(str "'" long-opt "=[" desc* "]:value:{_logseq_multi_values " vals-str "}'")]))
+
+      :dynamic
+      (let [action (case complete
+                     :graphs "{_logseq_graphs}"
+                     :pages "{_logseq_pages}"
+                     :tags "{_logseq_tags}"
+                     :properties "{_logseq_properties}"
+                     :queries "{_logseq_queries}")]
+        (if alias
+          [(str "'" excl long-opt "=[" desc* "]:value:" action "'")
+           (str "'" excl alias-short "[" desc* "]:value:" action "'")]
+          [(str "'" long-opt "=[" desc* "]:value:" action "'")]))
+
+      :file
+      (if alias
+        [(str "'" excl long-opt "=[" desc* "]:file:_files'")
+         (str "'" excl alias-short "[" desc* "]:file:_files'")]
+        [(str "'" long-opt "=[" desc* "]:file:_files'")])
+
+      :dir
+      (if alias
+        [(str "'" excl long-opt "=[" desc* "]:dir:_files -/'")
+         (str "'" excl alias-short "[" desc* "]:dir:_files -/'")]
+        [(str "'" long-opt "=[" desc* "]:dir:_files -/'")])
+
+      :free
+      (if alias
+        [(str "'" excl long-opt "=[" desc* "]:value:'")
+         (str "'" excl alias-short "[" desc* "]:value:'")]
+        [(str "'" long-opt "=[" desc* "]:value:'")])
+
+      ;; default
+      [(str "'" long-opt "=[" desc* "]:value:'")])))
+
+(defn- zsh-no-token-for
+  "Generate a zsh _arguments token for the --no-<option> negation of a flag.
+   Only emits for keys in no-prefix-keys."
+  [{:keys [key type alias]} no-prefix-keys]
+  (when (and (= type :flag) (contains? no-prefix-keys key))
+    (let [long-opt (zsh-option-name key)
+          no-opt (str "--no-" (name key))
+          excl (if alias
+                 (str "(" "-" (name alias) " " long-opt " " no-opt ")")
+                 (str "(" long-opt " " no-opt ")"))]
+      (str "'" excl no-opt "[Negate " long-opt "]'"))))
+
+(defn- zsh-arguments-tokens
+  "Generate _arguments tokens for a spec map.
+   global-keys: set of keys that should NOT get --no- prefix completions."
+  [spec global-keys]
+  (let [tokens (spec->tokens spec)
+        no-prefix-keys (->> tokens
+                            (keep #(when (and (= :flag (:type %))
+                                              (not (contains? global-keys (:key %)))
+                                              (not (string/starts-with? (name (:key %)) "no-")))
+                                     (:key %)))
+                            set)]
+    (into (vec (mapcat #(zsh-token-for % no-prefix-keys) tokens))
+          (keep #(zsh-no-token-for % no-prefix-keys) tokens))))
+
+(defn- zsh-leaf-function
+  "Generate a _logseq_<command>() function for a leaf command."
+  [func-name spec global-keys]
+  (let [tokens (zsh-arguments-tokens spec global-keys)
+        token-lines (string/join " \\\n    " tokens)]
+    (str func-name "() {\n"
+         "  _arguments -s \\\n"
+         "    " token-lines "\n"
+         "}\n")))
+
+(defn- cmd->func-name
+  "Convert a cmds vector like [\"graph\" \"export\"] to \"_logseq_graph_export\"."
+  [cmds]
+  (str "_logseq_" (string/join "_" cmds)))
+
+(defn- zsh-subgroup-function
+  "Generate a dispatcher for a 3-level subgroup (e.g. graph backup)."
+  [parent-name subgroup-name sub-entries global-spec]
+  (let [func-name (str "_logseq_" parent-name "_" subgroup-name)
+        global-keys (set (keys global-spec))
+        tokens (zsh-arguments-tokens global-spec global-keys)
+        options-lines (string/join " \\\n    " tokens)
+        subcmds (->> sub-entries
+                     (mapv (fn [entry]
+                             (let [sub-subcmd (nth (:cmds entry) 2)
+                                   desc (or (:desc entry) "")]
+                               (str "        '" sub-subcmd ":" desc "'")))))
+        subcmd-lines (string/join "\n" subcmds)
+        dispatches (->> sub-entries
+                        (mapv (fn [entry]
+                                (let [sub-subcmd (nth (:cmds entry) 2)
+                                      leaf-func (cmd->func-name (:cmds entry))]
+                                  (str "        " sub-subcmd ") " leaf-func " ;;")))))]
+    (str func-name "() {\n"
+         "  local curcontext=\"$curcontext\" state line\n"
+         "  typeset -A opt_args\n"
+         "\n"
+         "  _arguments -C -s \\\n"
+         "    " options-lines " \\\n"
+         "    '1:subcommand:->subcmd' \\\n"
+         "    '*::args:->args'\n"
+         "\n"
+         "  case $state in\n"
+         "    subcmd)\n"
+         "      local -a subcmds\n"
+         "      subcmds=(\n"
+         subcmd-lines "\n"
+         "      )\n"
+         "      _describe 'subcommand' subcmds\n"
+         "      ;;\n"
+         "    args)\n"
+         "      case $line[1] in\n"
+         (string/join "\n" dispatches) "\n"
+         "      esac\n"
+         "      ;;\n"
+         "  esac\n"
+         "}\n")))
+
+(defn- zsh-group-function
+  "Generate a group dispatcher function.
+   Handles groups that have both a root command (e.g. [\"query\"]) and
+   subcommands (e.g. [\"query\" \"list\"]).
+   Also handles nested subgroups (e.g. [\"graph\" \"backup\" \"list\"])."
+  [group-name subentries global-spec]
+  (let [func-name (str "_logseq_" group-name)
+        ;; Separate root entry from subcommand entries
+        root-entry (first (filter #(= 1 (count (:cmds %))) subentries))
+        sub-entries (filter #(> (count (:cmds %)) 1) subentries)
+        ;; Partition into leaf subcmds (2 elements) and nested (3+ elements)
+        leaf-entries (filter #(= 2 (count (:cmds %))) sub-entries)
+        nested-entries (filter #(> (count (:cmds %)) 2) sub-entries)
+        ;; Group nested entries by their 2nd element to find subgroups
+        nested-groups (group-by #(second (:cmds %)) nested-entries)
+        ;; Generate subgroup dispatcher functions
+        subgroup-fns (when (seq nested-groups)
+                       (->> nested-groups
+                            (mapv (fn [[sg-name sg-entries]]
+                                    (zsh-subgroup-function group-name sg-name sg-entries global-spec)))
+                            (string/join "\n")))
+        ;; Root-level options (global + root command's own spec if present)
+        root-spec (if root-entry
+                    (:spec root-entry)
+                    global-spec)
+        global-keys (set (keys global-spec))
+        root-tokens (zsh-arguments-tokens root-spec global-keys)
+        root-lines (string/join " \\\n    " root-tokens)
+        ;; Build subcmd descriptions: leaf entries + subgroup names
+        leaf-subcmds (->> leaf-entries
+                          (mapv (fn [entry]
+                                  (let [subcmd (second (:cmds entry))
+                                        desc (or (:desc entry) "")]
+                                    (str "        '" subcmd ":" desc "'")))))
+        subgroup-subcmds (->> (keys nested-groups)
+                              sort
+                              (mapv (fn [sg-name]
+                                      (str "        '" sg-name ":" sg-name " commands'"))))
+        subcmd-lines (string/join "\n" (concat leaf-subcmds subgroup-subcmds))
+        ;; Build dispatch: leaf entries dispatch to leaf fns, subgroups to subgroup fns
+        leaf-dispatches (->> leaf-entries
+                             (mapv (fn [entry]
+                                     (let [subcmd (second (:cmds entry))
+                                           sub-func (cmd->func-name (:cmds entry))]
+                                       (str "        " subcmd ") " sub-func " ;;")))))
+        subgroup-dispatches (->> (keys nested-groups)
+                                 sort
+                                 (mapv (fn [sg-name]
+                                         (str "        " sg-name ") _logseq_" group-name "_" sg-name " ;;"))))
+        dispatch-lines (string/join "\n" (concat leaf-dispatches subgroup-dispatches))
+        group-fn (str func-name "() {\n"
+                      "  local curcontext=\"$curcontext\" state line\n"
+                      "  typeset -A opt_args\n"
+                      "\n"
+                      "  _arguments -C -s \\\n"
+                      "    " root-lines " \\\n"
+                      "    '1:subcommand:->subcmd' \\\n"
+                      "    '*::args:->args'\n"
+                      "\n"
+                      "  case $state in\n"
+                      "    subcmd)\n"
+                      "      local -a subcmds\n"
+                      "      subcmds=(\n"
+                      subcmd-lines "\n"
+                      "      )\n"
+                      "      _describe 'subcommand' subcmds\n"
+                      "      ;;\n"
+                      "    args)\n"
+                      "      case $line[1] in\n"
+                      dispatch-lines "\n"
+                      "      esac\n"
+                      "      ;;\n"
+                      "  esac\n"
+                      "}\n")]
+    (if subgroup-fns
+      (str subgroup-fns "\n" group-fn)
+      group-fn)))
+
+(defn- zsh-toplevel-function
+  "Generate the _logseq() root dispatcher."
+  [table global-spec]
+  (let [groups (extract-groups table)
+        group-names (sort (keys groups))
+        ;; Build command descriptions for top level
+        cmd-descs (->> group-names
+                       (mapv (fn [g]
+                               (let [entries (get groups g)
+                                     desc (if (and (= 1 (count entries))
+                                                   (= 1 (count (:cmds (first entries)))))
+                                            (or (:desc (first entries)) "")
+                                            (str g " commands"))]
+                                 (str "        '" g ":" desc "'")))))
+        cmd-desc-lines (string/join "\n" cmd-descs)
+        dispatches (->> group-names
+                        (mapv (fn [g]
+                                (let [entries (get groups g)
+                                      func (if (and (= 1 (count entries))
+                                                    (= 1 (count (:cmds (first entries)))))
+                                             (cmd->func-name (:cmds (first entries)))
+                                             (str "_logseq_" g))]
+                                  (str "        " g ") " func " ;;")))))
+        dispatch-lines (string/join "\n" dispatches)
+        global-keys (set (keys global-spec))
+        global-tokens (zsh-arguments-tokens global-spec global-keys)
+        global-lines (string/join " \\\n    " global-tokens)]
+    (str "_logseq() {\n"
+         "  local curcontext=\"$curcontext\" state line\n"
+         "  typeset -A opt_args\n"
+         "\n"
+         "  _arguments -C -s \\\n"
+         "    " global-lines " \\\n"
+         "    '1:command:->cmds' \\\n"
+         "    '*::args:->args'\n"
+         "\n"
+         "  case $state in\n"
+         "    cmds)\n"
+         "      local -a cmds\n"
+         "      cmds=(\n"
+         cmd-desc-lines "\n"
+         "      )\n"
+         "      _describe 'command' cmds\n"
+         "      ;;\n"
+         "    args)\n"
+         "      case $line[1] in\n"
+         dispatch-lines "\n"
+         "      esac\n"
+         "      ;;\n"
+         "  esac\n"
+         "}\n")))
+
+(defn generate-zsh
+  "Generate complete zsh completion script from the command table."
+  [table]
+  (let [groups (extract-groups table)
+        global-spec (-> table first :spec
+                        (select-keys [:help :version :config :graph :root-dir
+                                      :timeout-ms :output :verbose :profile]))
+        global-keys (set (keys global-spec))
+        ;; Collect group names that have subcommands (dispatchers own these)
+        group-set (set (group-commands table))
+        ;; Generate leaf command functions (skip group roots — dispatchers own those)
+        leaf-fns (->> groups
+                      (mapcat (fn [[group-name entries]]
+                                (->> entries
+                                     (remove (fn [entry]
+                                               (and (= 1 (count (:cmds entry)))
+                                                    (contains? group-set group-name))))
+                                     (mapv (fn [entry]
+                                             (zsh-leaf-function
+                                              (cmd->func-name (:cmds entry))
+                                              (:spec entry)
+                                              global-keys))))))
+                      (string/join "\n"))
+        ;; Generate group dispatchers
+        group-fns (->> groups
+                       (filter (fn [[_ entries]]
+                                 (or (> (count entries) 1)
+                                     (> (count (:cmds (first entries))) 1))))
+                       (mapv (fn [[group-name entries]]
+                               (zsh-group-function group-name entries global-spec)))
+                       (string/join "\n"))
+        ;; Generate top-level dispatcher
+        toplevel (zsh-toplevel-function table global-spec)]
+    (str zsh-preamble "\n"
+         "# --- per-command functions ---\n\n"
+         leaf-fns "\n"
+         "# --- group dispatchers ---\n\n"
+         group-fns "\n"
+         "# --- top-level dispatcher ---\n\n"
+         toplevel "\n"
+         "compdef _logseq logseq\n")))
+
+;; ---------------------------------------------------------------------------
+;; Bash dynamic helpers (verbatim preamble)
+;; ---------------------------------------------------------------------------
+
+(def ^:private ^:large-vars/cleanup-todo bash-preamble
+  "# Auto-generated by `logseq completion bash` — do not edit manually.
+
+# --- dynamic helpers ---
+
+_logseq_json_names_bash() {
+  # Navigate a JSON path and print leaf strings.
+  # Usage: _logseq_json_names_bash key1 key2 ... keyN
+  python3 -c \"
+import sys, json
+keys = sys.argv[1:]
+try:
+    data = json.load(sys.stdin)
+    for key in keys:
+        if isinstance(data, dict):
+            data = data.get(key, [])
+        elif isinstance(data, list):
+            for item in data:
+                if isinstance(item, dict):
+                    v = item.get(key)
+                    if isinstance(v, str) and v:
+                        print(v)
+            sys.exit(0)
+    if isinstance(data, list):
+        for item in data:
+            if isinstance(item, str) and item:
+                print(item)
+except Exception:
+    pass
+\" \"$@\" 2>/dev/null
+}
+
+_logseq_current_graph_bash() {
+  local i w
+  for (( i = 1; i < ${#COMP_WORDS[@]}; i++ )); do
+    w=\"${COMP_WORDS[i]}\"
+    if [[ \"$w\" == '--graph' || \"$w\" == '-g' ]] && [[ -n \"${COMP_WORDS[i+1]}\" ]]; then
+      printf '%s' \"${COMP_WORDS[i+1]}\"
+      return
+    elif [[ \"$w\" == --graph=* ]]; then
+      printf '%s' \"${w#--graph=}\"
+      return
+    fi
+  done
+  # Fall back to the current graph from 'logseq graph list' (marked with '* ')
+  logseq graph list 2>/dev/null | sed -n 's/^[*] //p'
+}
+
+_logseq_graphs_bash() {
+  logseq graph list --output json 2>/dev/null | _logseq_json_names_bash data graphs
+}
+
+_logseq_pages_bash() {
+  logseq list page --graph \"$1\" --output json 2>/dev/null | _logseq_json_names_bash data items block/title
+}
+
+_logseq_tags_bash() {
+  logseq list tag --graph \"$1\" --output json 2>/dev/null | _logseq_json_names_bash data items block/title
+}
+
+_logseq_properties_bash() {
+  logseq list property --graph \"$1\" --output json 2>/dev/null | _logseq_json_names_bash data items block/title
+}
+
+_logseq_queries_bash() {
+  logseq query list --graph \"$1\" --output json 2>/dev/null | _logseq_json_names_bash data queries name
+}
+
+_logseq_compadd_lines() {
+  local cur=\"$1\" source_fn=\"$2\"; shift 2
+  while IFS= read -r item; do
+    [[ \"$item\" == \"$cur\"* ]] && COMPREPLY+=( \"$item\" )
+  done < <(\"$source_fn\" \"$@\")
+}
+
+_logseq_enum_values_bash() {
+  # Complete a fixed value list, preserving values that contain whitespace.
+  # Usage: _logseq_enum_values_bash \"$cur\" val1 val2 ...
+  local cur=\"$1\"; shift
+  COMPREPLY=()
+  local v
+  for v in \"$@\"; do
+    if [[ \"$v\" == \"$cur\"* ]]; then
+      COMPREPLY+=( \"$v\" )
+    fi
+  done
+}
+
+_logseq_multi_values_bash() {
+  # Complete comma-delimited lists. Usage: _logseq_multi_values_bash \"$cur\" val1 val2 ...
+  local cur=\"$1\"; shift
+  local -a all_values=(\"$@\")
+  local prefix='' remaining=\"$cur\"
+
+  if [[ \"$cur\" == *,* ]]; then
+    prefix=\"${cur%,*},\"
+    remaining=\"${cur##*,}\"
+  fi
+
+  # Collect already-selected values
+  local IFS=','
+  local -a already=($cur)
+  unset IFS
+
+  local v
+  for v in \"${all_values[@]}\"; do
+    local found=0
+    local a
+    for a in \"${already[@]}\"; do
+      [[ \"$a\" == \"$v\" ]] && found=1 && break
+    done
+    if (( ! found )) && [[ \"$v\" == \"$remaining\"* ]]; then
+      COMPREPLY+=( \"${prefix}${v}\" )
+    fi
+  done
+  [[ ${#COMPREPLY[@]} -eq 1 ]] && COMPREPLY=( \"${COMPREPLY[0]},\" )
+  compopt -o nospace 2>/dev/null
+}
+")
+
+;; ---------------------------------------------------------------------------
+;; Bash generation
+;; ---------------------------------------------------------------------------
+
+(defn- bash-option-name
+  [k]
+  (str "--" (name k)))
+
+(defn- bash-option-names
+  "Return all completion option name strings for a spec entry key and spec-map.
+   Includes --no-<key> for boolean flags."
+  [k spec-map]
+  (let [long-opt (bash-option-name k)
+        base (if (:alias spec-map)
+               [long-opt (str "-" (name (:alias spec-map)))]
+               [long-opt])]
+    (if (and (= :boolean (:coerce spec-map))
+             (not (string/starts-with? (name k) "no-")))
+      (conj base (str "--no-" (name k)))
+      base)))
+
+(defn- bash-all-value-opts
+  "Collect all non-boolean option names (options that consume a value argument).
+   Includes both long (--opt) and short (-x) forms."
+  [table]
+  (let [all-specs (->> table (mapcat (fn [entry] (seq (:spec entry)))))
+        value-opts (->> all-specs
+                        (remove (fn [[_ spec-map]]
+                                  (= :boolean (:coerce spec-map))))
+                        (mapcat (fn [[k spec-map]]
+                                  (cond-> [(bash-option-name k)]
+                                    (:alias spec-map)
+                                    (conj (str "-" (name (:alias spec-map))))))))]
+    (-> (set value-opts)
+        sort
+        vec)))
+
+(defn- bash-is-value-opt
+  "Generate _logseq_is_value_opt function."
+  [table]
+  (let [opts (bash-all-value-opts table)
+        cases (string/join "|" opts)]
+    (str "_logseq_is_value_opt() {\n"
+         "  case \"$1\" in\n"
+         "    " cases ")\n"
+         "      return 0 ;;\n"
+         "    *) return 1 ;;\n"
+         "  esac\n"
+         "}\n")))
+
+(defn- bash-cmd-and-subcmd
+  "Generate _logseq_cmd_and_subcmd function."
+  []
+  "_logseq_cmd_and_subcmd() {
+  local i skip=0
+  __cmd='' __subcmd='' __subsubcmd=''
+  for (( i = 1; i < COMP_CWORD; i++ )); do
+    local w=\"${COMP_WORDS[i]}\"
+    if (( skip )); then skip=0; continue; fi
+    if [[ \"$w\" == -* ]]; then
+      _logseq_is_value_opt \"$w\" && skip=1
+      continue
+    fi
+    if [[ -z \"$__cmd\" ]]; then
+      __cmd=\"$w\"
+    elif [[ -z \"$__subcmd\" ]]; then
+      __subcmd=\"$w\"
+    elif [[ -z \"$__subsubcmd\" ]]; then
+      __subsubcmd=\"$w\"
+    fi
+  done
+}\n")
+
+(defn- bash-global-opts-string
+  "Generate the global opts wordlist string."
+  [global-spec]
+  (->> (keys global-spec)
+       (mapcat (fn [k]
+                 (let [long-opt (bash-option-name k)
+                       alias (:alias (get global-spec k))]
+                   (if alias
+                     [long-opt (str "-" (name alias))]
+                     [long-opt]))))
+       (string/join " ")))
+
+(defn- bash-opts-for
+  "Generate _logseq_opts_for function."
+  [table]
+  (let [groups (extract-groups table)
+        global-spec (-> table first :spec
+                        (select-keys [:help :version :config :graph :root-dir
+                                      :timeout-ms :output :verbose :profile]))
+        global-str (bash-global-opts-string global-spec)
+        ;; Build case branches
+        branches
+        (->> (sort-by first groups)
+             (mapv (fn [[group-name entries]]
+                     (if (and (= 1 (count entries))
+                              (= 1 (count (:cmds (first entries)))))
+                       ;; Leaf command
+                       (let [entry (first entries)
+                             cmd-spec (apply dissoc (:spec entry) (keys global-spec))
+                             cmd-opts (->> (keys cmd-spec)
+                                           (mapcat (fn [k] (bash-option-names k (get cmd-spec k))))
+                                           (string/join " "))]
+                         (str "    " group-name ") opts+=' " cmd-opts "' ;;"))
+                       ;; Group with subcommands
+                       (let [;; Root entry opts go at group level, sub-entries get case branches
+                             root-entry (first (filter #(= 1 (count (:cmds %))) entries))
+                             sub-entries (filter #(> (count (:cmds %)) 1) entries)
+                             leaf-subs (filter #(= 2 (count (:cmds %))) sub-entries)
+                             nested-subs (filter #(> (count (:cmds %)) 2) sub-entries)
+                             nested-groups (group-by #(second (:cmds %)) nested-subs)
+                             root-opts (when root-entry
+                                         (let [cmd-spec (apply dissoc (:spec root-entry) (keys global-spec))]
+                                           (->> (keys cmd-spec)
+                                                (mapcat (fn [k] (bash-option-names k (get cmd-spec k))))
+                                                (string/join " "))))
+                             leaf-branches
+                             (->> leaf-subs
+                                  (mapv (fn [entry]
+                                          (let [subcmd (second (:cmds entry))
+                                                cmd-spec (apply dissoc (:spec entry) (keys global-spec))
+                                                cmd-opts (->> (keys cmd-spec)
+                                                              (mapcat (fn [k] (bash-option-names k (get cmd-spec k))))
+                                                              (string/join " "))]
+                                            (str "        " subcmd ") opts+=' " cmd-opts "' ;;")))))
+                             ;; For nested subgroups, dispatch on subsubcmd
+                             nested-branches
+                             (->> (sort-by first nested-groups)
+                                  (mapv (fn [[sg-name sg-entries]]
+                                          (let [inner (->> sg-entries
+                                                           (mapv (fn [entry]
+                                                                   (let [sub-subcmd (nth (:cmds entry) 2)
+                                                                         cmd-spec (apply dissoc (:spec entry) (keys global-spec))
+                                                                         cmd-opts (->> (keys cmd-spec)
+                                                                                       (mapcat (fn [k] (bash-option-names k (get cmd-spec k))))
+                                                                                       (string/join " "))]
+                                                                     (str "            " sub-subcmd ") opts+=' " cmd-opts "' ;;"))))
+                                                           (string/join "\n"))]
+                                            (str "        " sg-name ")\n"
+                                                 "          case \"$subsubcmd\" in\n"
+                                                 inner "\n"
+                                                 "          esac\n"
+                                                 "          ;;")))))
+                             all-branches (concat leaf-branches nested-branches)
+                             sub-branches (string/join "\n" all-branches)]
+                         (str "    " group-name ")\n"
+                              (when (seq root-opts)
+                                (str "      opts+=' " root-opts "'\n"))
+                              "      case \"$subcmd\" in\n"
+                              sub-branches "\n"
+                              "      esac\n"
+                              "      ;;"))))))]
+    (str "_logseq_opts_for() {\n"
+         "  local cmd=\"$1\" subcmd=\"$2\" subsubcmd=\"$3\"\n"
+         "  local opts=\"" global-str "\"\n"
+         "\n"
+         "  case \"$cmd\" in\n"
+         (string/join "\n" branches) "\n"
+         "  esac\n"
+         "\n"
+         "  printf '%s' \"$opts\"\n"
+         "}\n")))
+
+(defn bash-prev-completion-case
+  "Generate a case branch for prev-word value completion."
+  [{:keys [key type alias values complete]}]
+  (let [long-opt (bash-option-name key)
+        pattern (if alias
+                  (str long-opt "|-" (name alias))
+                  long-opt)]
+    (case type
+      :enum
+      (if (contains-whitespace? values)
+        (str "    " pattern ")\n"
+             "      _logseq_enum_values_bash \"$cur\" "
+             (->> values (map bash-quote-value) (string/join " ")) "\n"
+             "      return ;;")
+        (str "    " pattern ")\n"
+             "      COMPREPLY=( $(compgen -W '" (string/join " " values) "' -- \"$cur\") )\n"
+             "      return ;;"))
+
+      :multi
+      (str "    " pattern ")\n"
+           "      _logseq_multi_values_bash \"$cur\" "
+           (->> values (map bash-quote-value) (string/join " ")) "\n"
+           "      return ;;")
+
+      :dynamic
+      (case complete
+        :graphs
+        (str "    " pattern ")\n"
+             "      _logseq_compadd_lines \"$cur\" _logseq_graphs_bash\n"
+             "      return ;;")
+        :pages
+        (str "    " pattern ")\n"
+             "      local graph\n"
+             "      graph=\"$(_logseq_current_graph_bash)\"\n"
+             "      [[ -n \"$graph\" ]] && _logseq_compadd_lines \"$cur\" _logseq_pages_bash \"$graph\"\n"
+             "      return ;;")
+        :tags
+        (str "    " pattern ")\n"
+             "      local graph\n"
+             "      graph=\"$(_logseq_current_graph_bash)\"\n"
+             "      [[ -n \"$graph\" ]] && _logseq_compadd_lines \"$cur\" _logseq_tags_bash \"$graph\"\n"
+             "      return ;;")
+        :properties
+        (str "    " pattern ")\n"
+             "      local graph\n"
+             "      graph=\"$(_logseq_current_graph_bash)\"\n"
+             "      [[ -n \"$graph\" ]] && _logseq_compadd_lines \"$cur\" _logseq_properties_bash \"$graph\"\n"
+             "      return ;;")
+        :queries
+        (str "    " pattern ")\n"
+             "      local graph\n"
+             "      graph=\"$(_logseq_current_graph_bash)\"\n"
+             "      [[ -n \"$graph\" ]] && _logseq_compadd_lines \"$cur\" _logseq_queries_bash \"$graph\"\n"
+             "      return ;;"))
+
+      :file
+      (str "    " pattern ")\n"
+           "      COMPREPLY=( $(compgen -f -- \"$cur\") )\n"
+           "      return ;;")
+
+      :dir
+      (str "    " pattern ")\n"
+           "      COMPREPLY=( $(compgen -d -- \"$cur\") )\n"
+           "      return ;;")
+
+      nil)))
+
+(defn- bash-subcommand-cases
+  "Generate subcommand completion for each group.
+   Deduplicates subcmd names so that 3-level commands like
+   [\"graph\" \"backup\" \"list\"] produce a single \"backup\" entry."
+  [table]
+  (let [groups (extract-groups table)
+        cases (->> (sort-by first groups)
+                   (keep (fn [[group-name entries]]
+                           (when (or (> (count entries) 1)
+                                     (> (count (:cmds (first entries))) 1))
+                             (let [subcmds (->> entries
+                                                (keep #(second (:cmds %)))
+                                                distinct
+                                                (string/join " "))]
+                               (when (seq subcmds)
+                                 (str "      " group-name ") COMPREPLY=( $(compgen -W '"
+                                      subcmds "' -- \"$cur\") ) ;;")))))))]
+    (string/join "\n" cases)))
+
+(defn- bash-sub-subcommand-cases
+  "Generate sub-subcommand completion for 3-level command groups.
+   Produces cases like: graph:backup) COMPREPLY=( $(compgen -W 'list create ...' ...) ) ;;"
+  [table]
+  (let [groups (extract-groups table)
+        cases (->> (sort-by first groups)
+                   (mapcat (fn [[group-name entries]]
+                             (let [nested (filter #(> (count (:cmds %)) 2) entries)
+                                   nested-groups (group-by #(second (:cmds %)) nested)]
+                               (->> (sort-by first nested-groups)
+                                    (mapv (fn [[sg-name sg-entries]]
+                                            (let [sub-subcmds (->> sg-entries
+                                                                   (map #(nth (:cmds %) 2))
+                                                                   distinct
+                                                                   (string/join " "))]
+                                              (str "      " group-name ":" sg-name
+                                                   ") COMPREPLY=( $(compgen -W '"
+                                                   sub-subcmds "' -- \"$cur\") ) ;;")))))))))
+        cases (remove nil? cases)]
+    (when (seq cases)
+      (string/join "\n" cases))))
+
+(defn- bash-toplevel-commands
+  "Get all top-level command names."
+  [table]
+  (let [groups (extract-groups table)]
+    (->> (keys groups) sort (string/join " "))))
+
+(defn- option-completion-sig
+  "Extract completion-relevant signature from a spec-map entry."
+  [{:keys [coerce validate values multiple-values complete]}]
+  {:flag? (= coerce :boolean)
+   :values (if (set? validate) validate values)
+   :multiple-values multiple-values
+   :complete complete})
+
+(defn find-varied-option-keys
+  "Find option keys that have different completion behaviors across commands.
+   Returns a set of keyword keys."
+  [table global-keys]
+  (->> table
+       (mapcat (fn [entry]
+                 (for [[k spec-map] (apply dissoc (:spec entry) global-keys)]
+                   [k (option-completion-sig spec-map)])))
+       (group-by first)
+       (keep (fn [[k entries]]
+               (let [sigs (map second entries)]
+                 (when (not (apply = sigs))
+                   k))))
+       set))
+
+(defn- bash-varied-context-branch
+  "Generate an if-branch for a single command context of a varied option."
+  [{:keys [cmds spec-map]}]
+  (let [token (spec->token [:_ spec-map])
+        cmd (first cmds)
+        subcmd (second cmds)
+        condition (if subcmd
+                    (str "[[ \"$__cmd\" == '" cmd "' && \"$__subcmd\" == '" subcmd "' ]]")
+                    (str "[[ \"$__cmd\" == '" cmd "' ]]"))]
+    (case (:type token)
+      :enum
+      (if (contains-whitespace? (:values token))
+        (str "      if " condition "; then\n"
+             "        _logseq_enum_values_bash \"$cur\" "
+             (->> (:values token) (map bash-quote-value) (string/join " ")) "\n"
+             "        return\n"
+             "      fi")
+        (str "      if " condition "; then\n"
+             "        COMPREPLY=( $(compgen -W '" (string/join " " (:values token)) "' -- \"$cur\") )\n"
+             "        return\n"
+             "      fi"))
+
+      :dynamic
+      (case (:complete token)
+        :graphs
+        (str "      if " condition "; then\n"
+             "        _logseq_compadd_lines \"$cur\" _logseq_graphs_bash\n"
+             "      fi")
+        :pages
+        (str "      if " condition "; then\n"
+             "        local graph\n"
+             "        graph=\"$(_logseq_current_graph_bash)\"\n"
+             "        [[ -n \"$graph\" ]] && _logseq_compadd_lines \"$cur\" _logseq_pages_bash \"$graph\"\n"
+             "      fi")
+        :tags
+        (str "      if " condition "; then\n"
+             "        local graph\n"
+             "        graph=\"$(_logseq_current_graph_bash)\"\n"
+             "        [[ -n \"$graph\" ]] && _logseq_compadd_lines \"$cur\" _logseq_tags_bash \"$graph\"\n"
+             "      fi")
+        :properties
+        (str "      if " condition "; then\n"
+             "        local graph\n"
+             "        graph=\"$(_logseq_current_graph_bash)\"\n"
+             "        [[ -n \"$graph\" ]] && _logseq_compadd_lines \"$cur\" _logseq_properties_bash \"$graph\"\n"
+             "      fi")
+        :queries
+        (str "      if " condition "; then\n"
+             "        local graph\n"
+             "        graph=\"$(_logseq_current_graph_bash)\"\n"
+             "        [[ -n \"$graph\" ]] && _logseq_compadd_lines \"$cur\" _logseq_queries_bash \"$graph\"\n"
+             "      fi")
+        nil)
+
+      :file
+      (str "      if " condition "; then\n"
+           "        COMPREPLY=( $(compgen -f -- \"$cur\") )\n"
+           "        return\n"
+           "      fi")
+
+      :dir
+      (str "      if " condition "; then\n"
+           "        COMPREPLY=( $(compgen -d -- \"$cur\") )\n"
+           "        return\n"
+           "      fi")
+
+      :multi
+      (str "      if " condition "; then\n"
+           "        _logseq_multi_values_bash \"$cur\" "
+           (->> (:values token) (map bash-quote-value) (string/join " ")) "\n"
+           "        return\n"
+           "      fi")
+
+      ;; :free and :flag don't need prev-word completion
+      nil)))
+
+(defn- bash-varied-prev-cases
+  "Generate context-dependent case branches for all varied options."
+  [table varied-keys global-keys]
+  (let [contexts
+        (->> table
+             (mapcat (fn [entry]
+                       (for [[k spec-map] (apply dissoc (:spec entry) global-keys)
+                             :when (contains? varied-keys k)]
+                         {:key k :cmds (:cmds entry) :spec-map spec-map})))
+             (group-by :key))]
+    (->> (sort-by first contexts)
+         (keep (fn [[k entries]]
+                 (let [long-opt (bash-option-name k)
+                       branches (->> entries
+                                     (keep bash-varied-context-branch))]
+                   (when (seq branches)
+                     (str "    " long-opt ")\n"
+                          (string/join "\n" branches) "\n"
+                          "      return ;;")))))
+         (string/join "\n\n"))))
+
+(defn- bash-main-function
+  "Generate the _logseq() main completion function."
+  [table]
+  (let [global-spec (-> table first :spec
+                        (select-keys [:help :version :config :graph :root-dir
+                                      :timeout-ms :output :verbose :profile]))
+        global-keys (set (keys global-spec))
+        ;; Find options with conflicting completions across commands
+        varied-keys (find-varied-option-keys table global-keys)
+        ;; Collect unique non-context-dependent prev-word cases
+        all-specs (->> table (mapcat (fn [entry] (seq (:spec entry)))))
+        unique-specs (into {} all-specs)
+        tokens (spec->tokens unique-specs)
+        context-free-tokens (remove #(contains? varied-keys (:key %)) tokens)
+        prev-cases (->> context-free-tokens
+                        (keep bash-prev-completion-case)
+                        (string/join "\n\n"))
+        ;; Context-dependent cases for varied options
+        varied-cases (bash-varied-prev-cases table varied-keys global-keys)
+        ;; Subcommand completion
+        subcmd-cases (bash-subcommand-cases table)
+        ;; Sub-subcommand completion for 3-level commands
+        sub-subcmd-cases (bash-sub-subcommand-cases table)
+        ;; Top-level commands
+        top-cmds (bash-toplevel-commands table)]
+    (str "_logseq() {\n"
+         "  local cur prev\n"
+         "  cur=\"${COMP_WORDS[COMP_CWORD]}\"\n"
+         "  prev=\"${COMP_WORDS[COMP_CWORD-1]}\"\n"
+         "  COMPREPLY=()\n"
+         "\n"
+         "  local __cmd __subcmd __subsubcmd\n"
+         "  _logseq_cmd_and_subcmd\n"
+         "\n"
+         "  # --- Option value completion ---\n"
+         "  case \"$prev\" in\n"
+         prev-cases "\n"
+         (when (seq varied-cases)
+           (str "\n" varied-cases "\n"))
+         "  esac\n"
+         "\n"
+         "  # --- Flag / positional completion ---\n"
+         "  if [[ \"$cur\" == -* ]]; then\n"
+         "    # shellcheck disable=SC2046\n"
+         "    COMPREPLY=( $(compgen -W \"$(_logseq_opts_for \"$__cmd\" \"$__subcmd\" \"$__subsubcmd\")\" -- \"$cur\") )\n"
+         "    return\n"
+         "  fi\n"
+         "\n"
+         "  if [[ -z \"$__cmd\" ]]; then\n"
+         "    COMPREPLY=( $(compgen -W '" top-cmds "' -- \"$cur\") )\n"
+         "    return\n"
+         "  fi\n"
+         "\n"
+         "  if [[ -z \"$__subcmd\" ]]; then\n"
+         "    case \"$__cmd\" in\n"
+         subcmd-cases "\n"
+         "    esac\n"
+         "    return\n"
+         "  fi\n"
+         "\n"
+         (when (seq sub-subcmd-cases)
+           (str "  if [[ -z \"$__subsubcmd\" ]]; then\n"
+                "    case \"$__cmd:$__subcmd\" in\n"
+                sub-subcmd-cases "\n"
+                "    esac\n"
+                "    return\n"
+                "  fi\n"))
+         "}\n")))
+
+(defn generate-bash
+  "Generate complete bash completion script from the command table."
+  [table]
+  (let [is-value-opt (bash-is-value-opt table)
+        cmd-and-subcmd (bash-cmd-and-subcmd)
+        opts-for (bash-opts-for table)
+        main-fn (bash-main-function table)]
+    (str bash-preamble "\n"
+         "# --- generated helpers ---\n\n"
+         is-value-opt "\n"
+         cmd-and-subcmd "\n"
+         "# --- option wordlists ---\n\n"
+         opts-for "\n"
+         "# --- main function ---\n\n"
+         main-fn "\n"
+         "complete -F _logseq logseq\n")))
+
+;; ---------------------------------------------------------------------------
+;; Public API
+;; ---------------------------------------------------------------------------
+
+(defn generate-completions
+  "Generate shell completions from the CLI command table.
+   shell: \"zsh\" or \"bash\"
+   table: vector of command entries"
+  [shell table]
+  (case shell
+    "zsh" (generate-zsh table)
+    "bash" (generate-bash table)
+    (throw (ex-info (str "unsupported shell: " shell) {:shell shell}))))
diff --git a/src/main/logseq/cli/config.cljs b/src/main/logseq/cli/config.cljs
new file mode 100644
index 0000000000..53c870f2bf
--- /dev/null
+++ b/src/main/logseq/cli/config.cljs
@@ -0,0 +1,144 @@
+(ns logseq.cli.config
+  "CLI configuration resolution and persistence."
+  (:require [cljs.reader :as reader]
+            [clojure.string :as string]
+            [goog.object :as gobj]
+            ["fs" :as fs]
+            ["path" :as node-path]
+            [logseq.cli.output-mode :as output-mode]
+            [logseq.cli.root-dir :as root-dir]
+            [logseq.db-worker.server-list :as server-list]))
+
+(defn- parse-int
+  [value]
+  (when (and (some? value) (not (string/blank? value)))
+    (js/parseInt value 10)))
+
+(def ^:private list-title-max-display-width-default 40)
+
+(defn- parse-positive-int
+  [value]
+  (cond
+    (and (number? value)
+         (integer? value)
+         (pos? value))
+    value
+
+    (string? value)
+    (let [trimmed (string/trim value)]
+      (when (re-matches #"[1-9]\d*" trimmed)
+        (js/parseInt trimmed 10)))
+
+    :else nil))
+
+(defn- default-config-path
+  ([]
+   (default-config-path (root-dir/default-root-dir)))
+  ([root-dir]
+   (node-path/join root-dir "cli.edn")))
+
+(defn server-list-path
+  [root-dir]
+  (server-list/path (or root-dir (root-dir/default-root-dir))))
+
+(def ^:private removed-config-keys
+  #{:auth-token :retries :e2ee-password})
+
+(defn- sanitize-file-config
+  [config]
+  (apply dissoc (or config {}) removed-config-keys))
+
+(defn- read-config-file
+  [config-path]
+  (when (and (some? config-path) (fs/existsSync config-path))
+    (let [contents (.toString (fs/readFileSync config-path) "utf8")]
+      (-> (reader/read-string contents)
+          sanitize-file-config))))
+
+(defn- ensure-config-dir!
+  [config-path]
+  (when (seq config-path)
+    (let [dir (node-path/dirname config-path)]
+      (when (and (seq dir) (not (fs/existsSync dir)))
+        (.mkdirSync fs dir #js {:recursive true})))))
+
+(defn update-config!
+  [{:keys [config-path root-dir]} updates]
+  (let [path (or config-path (default-config-path (root-dir/normalize-root-dir root-dir)))
+        current (or (read-config-file path) {})
+        filtered-current (sanitize-file-config current)
+        filtered-updates (sanitize-file-config updates)
+        nil-keys (->> filtered-updates
+                      (keep (fn [[k v]]
+                              (when (nil? v)
+                                k))))
+        merged (merge filtered-current filtered-updates)
+        next (if (seq nil-keys)
+               (apply dissoc merged nil-keys)
+               merged)]
+    (ensure-config-dir! path)
+    (.writeFileSync fs path (pr-str next))
+    next))
+
+(defn- env-config
+  []
+  (let [env (.-env js/process)]
+    (cond-> {}
+      (seq (gobj/get env "LOGSEQ_CLI_GRAPH"))
+      (assoc :graph (gobj/get env "LOGSEQ_CLI_GRAPH"))
+
+      (seq (gobj/get env "LOGSEQ_CLI_ROOT_DIR"))
+      (assoc :root-dir (gobj/get env "LOGSEQ_CLI_ROOT_DIR"))
+
+      (seq (gobj/get env "LOGSEQ_CLI_TIMEOUT_MS"))
+      (assoc :timeout-ms (parse-int (gobj/get env "LOGSEQ_CLI_TIMEOUT_MS")))
+
+      (seq (gobj/get env "LOGSEQ_CLI_LOGIN_TIMEOUT_MS"))
+      (assoc :login-timeout-ms (parse-int (gobj/get env "LOGSEQ_CLI_LOGIN_TIMEOUT_MS")))
+
+      (seq (gobj/get env "LOGSEQ_CLI_LOGOUT_TIMEOUT_MS"))
+      (assoc :logout-timeout-ms (parse-int (gobj/get env "LOGSEQ_CLI_LOGOUT_TIMEOUT_MS")))
+
+      (seq (gobj/get env "LOGSEQ_CLI_OUTPUT"))
+      (assoc :output-format (output-mode/parse (gobj/get env "LOGSEQ_CLI_OUTPUT")))
+
+      (seq (gobj/get env "LOGSEQ_CLI_CONFIG"))
+      (assoc :config-path (gobj/get env "LOGSEQ_CLI_CONFIG")))))
+
+(defn resolve-config
+  [opts]
+  (let [defaults {:timeout-ms 10000
+                  :login-timeout-ms 300000
+                  :logout-timeout-ms 120000
+                  :list-title-max-display-width list-title-max-display-width-default
+                  :output-format nil
+                  :root-dir (root-dir/default-root-dir)
+                  :ws-url "wss://api.logseq.io/sync/%s"
+                  :http-base "https://api.logseq.io"}
+        env (env-config)
+        root-dir (root-dir/normalize-root-dir
+                  (or (:root-dir opts)
+                      (:root-dir env)
+                      (:root-dir defaults)))
+        config-path (or (:config-path opts)
+                        (:config-path env)
+                        (default-config-path root-dir))
+        file-config (or (read-config-file config-path) {})
+        root-dir (root-dir/normalize-root-dir
+                  (or (:root-dir opts)
+                      (:root-dir env)
+                      (:root-dir file-config)
+                      root-dir))
+        output-format (or (output-mode/parse (:output-format opts))
+                          (output-mode/parse (:output opts))
+                          (output-mode/parse (:output-format env))
+                          (output-mode/parse (:output env))
+                          (output-mode/parse (:output-format file-config))
+                          (output-mode/parse (:output file-config)))
+        merged (merge defaults file-config env opts {:root-dir root-dir
+                                                     :config-path config-path})
+        list-title-max-display-width (or (parse-positive-int (:list-title-max-display-width merged))
+                                         list-title-max-display-width-default)]
+    (cond-> merged
+      output-format (assoc :output-format output-format)
+      true (assoc :list-title-max-display-width list-title-max-display-width))))
diff --git a/src/main/logseq/cli/format.cljs b/src/main/logseq/cli/format.cljs
new file mode 100644
index 0000000000..8c2069ac82
--- /dev/null
+++ b/src/main/logseq/cli/format.cljs
@@ -0,0 +1,1029 @@
+(ns logseq.cli.format
+  "Formatting helpers for CLI output."
+  (:require [cljs.pprint :as pprint]
+            [clojure.string :as string]
+            [clojure.walk :as walk]
+            [logseq.cli.command.core :as command-core]
+            [logseq.cli.humanize :as cli-humanize]
+            [logseq.cli.output-mode :as output-mode]
+            [logseq.cli.style :as style]
+            [logseq.common.util :as common-util]
+            ["string-width" :default string-width]))
+
+(defn- keyword->json-string
+  [kw]
+  (if-let [kw-ns (namespace kw)]
+    (str kw-ns "/" (name kw))
+    (name kw)))
+
+(defn- normalize-json-key
+  [entry-key]
+  (if (keyword? entry-key)
+    (keyword->json-string entry-key)
+    entry-key))
+
+(defn- normalize-json-value
+  [entry]
+  (cond
+    (uuid? entry) (str entry)
+    (keyword? entry) (keyword->json-string entry)
+    :else entry))
+
+(defn- normalize-json
+  [value]
+  (walk/postwalk (fn [entry]
+                   (cond
+                     (map? entry) (into {}
+                                        (map (fn [[k v]]
+                                               [(normalize-json-key k) v]))
+                                        entry)
+                     :else (normalize-json-value entry)))
+                 value))
+
+(defn- normalize-property-cardinality
+  [value]
+  (cond
+    (nil? value) "one"
+    (keyword? value) (let [normalized (name value)]
+                       (if (#{"one" "many"} normalized)
+                         normalized
+                         "-"))
+    (string? value) (if (#{"one" "many"} value) value "-")
+    :else "-"))
+
+(defn- ->json
+  [{:keys [status data error command]}]
+  (let [obj (js-obj)]
+    (set! (.-status obj) (name status))
+    (cond
+      (= status :ok)
+      (set! (.-data obj) (clj->js (normalize-json data)))
+
+      (= status :error)
+      (do
+        (set! (.-error obj) (clj->js (normalize-json (update error :code name))))
+        (when (and (= :doctor command) (some? data))
+          (set! (.-data obj) (clj->js (normalize-json data))))))
+    (js/JSON.stringify obj)))
+
+(def ^:private list-human-title-max-display-width-default 40)
+(def ^:private truncation-suffix "…")
+(def ^:private truncation-suffix-width (string-width truncation-suffix))
+
+(defn- normalize-cell
+  [value]
+  (cond
+    (nil? value) "-"
+    (keyword? value) (str value)
+    :else (str value)))
+
+(defn- display-width
+  [value]
+  (string-width (normalize-cell value)))
+
+(defn- pad-right
+  [value width]
+  (let [text (normalize-cell value)
+        missing (- width (display-width text))]
+    (if (pos? missing)
+      (str text (apply str (repeat missing " ")))
+      text)))
+
+(defn- take-to-display-width
+  [text max-width]
+  (loop [remaining-chars (seq (js/Array.from text))
+         acc ""]
+    (if-let [ch (first remaining-chars)]
+      (let [candidate (str acc ch)]
+        (if (<= (display-width candidate) max-width)
+          (recur (next remaining-chars) candidate)
+          acc))
+      acc)))
+
+(defn- truncate-line-to-display-width
+  [line max-width]
+  (if (<= (display-width line) max-width)
+    line
+    (if (<= max-width truncation-suffix-width)
+      (take-to-display-width truncation-suffix max-width)
+      (str (take-to-display-width line (- max-width truncation-suffix-width))
+           truncation-suffix))))
+
+(defn- truncate-title-to-display-width
+  [value max-width]
+  (let [max-width (max 1 max-width)]
+    (->> (string/split (normalize-cell value) #"\n" -1)
+         (map #(truncate-line-to-display-width % max-width))
+         (string/join "\n"))))
+
+(defn- resolve-list-title-max-display-width
+  [value]
+  (if (and (number? value)
+           (integer? value)
+           (pos? value))
+    value
+    list-human-title-max-display-width-default))
+
+(defn- render-table
+  [headers rows]
+  (let [split-lines (fn [value]
+                      (string/split (normalize-cell value) #"\n" -1))
+        normalized-rows (mapv (fn [row]
+                                (mapv split-lines row))
+                              rows)
+        trim-right (fn [value]
+                     (string/replace value #"\s+$" ""))
+        widths (mapv (fn [idx header]
+                       (reduce max
+                               (display-width header)
+                               (mapcat #(map display-width (nth % idx)) normalized-rows)))
+                     (range (count headers))
+                     headers)
+        render-row (fn [row]
+                     (->> (map pad-right row widths)
+                          (string/join "  ")
+                          (trim-right)))
+        render-multiline-row (fn [row]
+                               (let [line-count (reduce max 1 (map count row))]
+                                 (mapv (fn [line-idx]
+                                         (->> (map-indexed (fn [col-idx lines]
+                                                            (pad-right (get lines line-idx "")
+                                                                       (nth widths col-idx)))
+                                                          row)
+                                              (string/join "  ")
+                                              (trim-right)))
+                                       (range line-count))))
+        lines (cons (render-row headers)
+                    (mapcat render-multiline-row normalized-rows))]
+    (string/join "\n" lines)))
+
+(defn- format-counted-table
+  [headers rows]
+  (str (if headers
+         (str (render-table headers rows) "\n")
+         (str (string/join "\n" (map (comp string/trimr first) rows)) "\n"))
+       "Count: "
+       (cli-humanize/format-count (count rows))))
+
+(defn- missing-search-query-hint
+  [command]
+  (case command
+    :search-block "Use: logseq search block --content <query>"
+    :search-page "Use: logseq search page --content <query>"
+    :search-property "Use: logseq search property --content <query>"
+    :search-tag "Use: logseq search tag --content <query>"
+    "Use: logseq search <block|page|property|tag> --content <query>"))
+
+(defn- error-hint
+  [{:keys [code]} command]
+  (case code
+    :missing-graph "Use --graph <name>"
+    :missing-repo "Use --graph <name>"
+    :missing-content "Use --content or pass content as args"
+    :missing-tag-name "Use --name <tag-name>"
+    :missing-query "Use --query <edn>"
+    :missing-query-text (missing-search-query-hint command)
+    :unknown-query "Use `logseq query list` to see available queries"
+    :ambiguous-tag-name "Retry with --id <tag-id>"
+    :ambiguous-property-name "Retry with --id <property-id>"
+    :root-dir-permission "Check filesystem permissions or set LOGSEQ_CLI_ROOT_DIR"
+    :server-owned-by-other "Retry from the process owner that started the server"
+    :server-start-timeout-orphan "Check and stop lingering db-worker-node processes, then retry"
+    nil))
+
+(defn- format-candidates
+  [candidates]
+  (when (seq candidates)
+    (str "\nCandidates:\n"
+         (string/join "\n"
+                      (map (fn [{:keys [id name]}]
+                             (str "  " id "  " (or name "-")))
+                           candidates)))))
+
+(defn- format-error
+  [error command]
+  (let [{:keys [code message candidates context]} error
+        hint (or (error-hint error command) (:hint error) (:hint context))
+        message* (style/bold-keywords message ["option" "command" "argument"])
+        candidates* (format-candidates candidates)]
+    (if (= :graph-validation-failed code)
+      message*
+      (cond-> (str "Error (" (name (or code :error)) "): " message*)
+        candidates* (str candidates*)
+        hint (str "\nHint: " hint)))))
+
+(defn- parse-ts
+  [value]
+  (cond
+    (number? value) value
+    (string? value) (let [ms (js/Date.parse value)]
+                      (when-not (js/isNaN ms) ms))
+    :else nil))
+
+(defn- human-ago
+  [value now-ms]
+  (if-let [ts (parse-ts value)]
+    (cli-humanize/relative-datetime ts now-ms)
+    "-"))
+
+(defn- format-task-datetime
+  [value now-ms]
+  (if-let [ts (parse-ts value)]
+    (cli-humanize/relative-datetime ts now-ms)
+    (if (string? value)
+      (let [text (string/trim value)]
+        (if (seq text)
+          text
+          "-"))
+      "-")))
+
+(defn- items-have-key?
+  [items & ks]
+  (some (fn [item] (some #(contains? item %) ks)) items))
+
+(def ^:private list-page-columns
+  [["ID"         (fn [item _] (or (:db/id item) (:id item)))           [:db/id :id]]
+   ["TITLE"      (fn [item _] (or (:title item) (:block/title item) (:name item)))  [:title :block/title :name]]
+   ["UUID"       (fn [item _] (or (:block/uuid item) "-"))             [:block/uuid]]
+   ["IDENT"      (fn [item _] (:db/ident item))                       [:db/ident]]
+   ["UPDATED-AT" (fn [item now-ms] (human-ago (or (:updated-at item) (:block/updated-at item)) now-ms)) [:updated-at :block/updated-at]]
+   ["CREATED-AT" (fn [item now-ms] (human-ago (or (:created-at item) (:block/created-at item)) now-ms)) [:created-at :block/created-at]]])
+
+(defn- format-list-dynamic
+  [items now-ms columns {:keys [title-max-display-width]}]
+  (let [items (or items [])
+        active (filterv (fn [[_ _ ks always?]]
+                          (or always? (apply items-have-key? items ks)))
+                        columns)
+        headers (mapv first active)
+        rows (mapv (fn [item]
+                     (mapv (fn [[header extractor _]]
+                             (let [cell (extractor item now-ms)]
+                               (if (and (= header "TITLE")
+                                        (number? title-max-display-width))
+                                 (truncate-title-to-display-width cell title-max-display-width)
+                                 cell)))
+                           active))
+                   items)]
+    (format-counted-table headers rows)))
+
+(defn- format-list-page
+  ([items now-ms]
+   (format-list-page items now-ms nil))
+  ([items now-ms title-max-display-width]
+   (format-list-dynamic items now-ms list-page-columns {:title-max-display-width title-max-display-width})))
+
+(defn- format-extends
+  [classes]
+  (if (seq classes) (string/join ", " classes) "-"))
+
+(defn- format-properties
+  [properties]
+  (if (seq properties) (string/join ", " properties) "-"))
+
+(def ^:private list-tag-columns
+  [["ID"         (fn [item _] (or (:db/id item) (:id item)))           [:db/id :id]]
+   ["TITLE"      (fn [item _] (or (:title item) (:block/title item) (:name item)))  [:title :block/title :name]]
+   ["UUID"       (fn [item _] (or (:block/uuid item) "-"))             [:block/uuid]]
+   ["IDENT"      (fn [item _] (:db/ident item))                       [:db/ident]]
+   ["EXTENDS"    (fn [item _] (format-extends (:logseq.property.class/extends item)))       [:logseq.property.class/extends]]
+   ["PROPERTIES" (fn [item _] (format-properties (:logseq.property.class/properties item))) [:logseq.property.class/properties]]
+   ["DESCRIPTION" (fn [item _] (:logseq.property/description item))  [:logseq.property/description]]
+   ["UPDATED-AT" (fn [item now-ms] (human-ago (or (:updated-at item) (:block/updated-at item)) now-ms)) [:updated-at :block/updated-at]]
+   ["CREATED-AT" (fn [item now-ms] (human-ago (or (:created-at item) (:block/created-at item)) now-ms)) [:created-at :block/created-at]]])
+
+(defn- format-list-tag
+  ([items now-ms]
+   (format-list-tag items now-ms nil))
+  ([items now-ms title-max-display-width]
+   (format-list-dynamic items now-ms list-tag-columns {:title-max-display-width title-max-display-width})))
+
+(defn- normalize-property-type
+  [value]
+  (cond
+    (keyword? value) (name value)
+    (nil? value) "-"
+    :else (str value)))
+
+(defn- format-classes
+  [classes]
+  (if (seq classes) (string/join ", " classes) "-"))
+
+(def ^:private list-property-columns
+  [["ID"         (fn [item _] (or (:db/id item) (:id item)))           [:db/id :id]]
+   ["TITLE"      (fn [item _] (or (:title item) (:block/title item) (:name item)))  [:title :block/title :name]]
+   ["TYPE"       (fn [item _] (normalize-property-type (:logseq.property/type item))) [:logseq.property/type]]
+   ["CARDINALITY" (fn [item _] (normalize-property-cardinality (:db/cardinality item))) [:db/cardinality]]
+   ["CLASSES"    (fn [item _] (format-classes (:logseq.property/classes item)))       [:logseq.property/classes]]
+   ["UUID"       (fn [item _] (or (:block/uuid item) "-"))             [:block/uuid]]
+   ["IDENT"      (fn [item _] (:db/ident item))                       [:db/ident]]
+   ["DESCRIPTION" (fn [item _] (:logseq.property/description item))  [:logseq.property/description]]
+   ["UPDATED-AT" (fn [item now-ms] (human-ago (or (:updated-at item) (:block/updated-at item)) now-ms)) [:updated-at :block/updated-at]]
+   ["CREATED-AT" (fn [item now-ms] (human-ago (or (:created-at item) (:block/created-at item)) now-ms)) [:created-at :block/created-at]]])
+
+(defn- format-list-property
+  ([items now-ms]
+   (format-list-property items now-ms nil))
+  ([items now-ms title-max-display-width]
+   (format-list-dynamic items now-ms list-property-columns {:title-max-display-width title-max-display-width})))
+
+(defn- format-task-choice
+  [value prefix]
+  (let [ident (cond
+                (keyword? value) value
+                (map? value) (:db/ident value)
+                :else nil)]
+    (cond
+      ident (let [name' (name ident)]
+              (if (string/starts-with? name' prefix)
+                (subs name' (count prefix))
+                name'))
+      (string? value) value
+      :else "-")))
+
+(def ^:private list-task-columns
+  [["ID"         (fn [item _] (or (:db/id item) (:id item))) [:db/id :id]]
+   ["TITLE"      (fn [item _] (or (:title item) (:block/title item) (:name item))) [:title :block/title :name]]
+   ["STATUS"     (fn [item _] (format-task-choice (or (:status item) (:logseq.property/status item)) "status."))
+    [:status :logseq.property/status]]
+   ["PRIORITY"   (fn [item _] (format-task-choice (or (:priority item) (:logseq.property/priority item)) "priority."))
+    [:priority :logseq.property/priority]]
+   ["SCHEDULED"  (fn [item now-ms] (format-task-datetime (or (:scheduled item) (:logseq.property/scheduled item)) now-ms))
+    [:scheduled :logseq.property/scheduled]]
+   ["DEADLINE"   (fn [item now-ms] (format-task-datetime (or (:deadline item) (:logseq.property/deadline item)) now-ms))
+    [:deadline :logseq.property/deadline]]
+   ["UPDATED-AT" (fn [item now-ms] (human-ago (or (:updated-at item) (:block/updated-at item)) now-ms)) [:updated-at :block/updated-at]]
+   ["CREATED-AT" (fn [item now-ms] (human-ago (or (:created-at item) (:block/created-at item)) now-ms)) [:created-at :block/created-at]]])
+
+(defn- format-list-task
+  ([items now-ms]
+   (format-list-task items now-ms nil))
+  ([items now-ms title-max-display-width]
+   (format-list-dynamic items now-ms list-task-columns {:title-max-display-width title-max-display-width})))
+
+(defn- normalize-node-type
+  [value]
+  (cond
+    (keyword? value) (name value)
+    (string? value) value
+    :else "-"))
+
+(def ^:private list-node-columns
+  [["ID"         (fn [item _] (or (:db/id item) (:id item))) [:db/id :id]]
+   ["TITLE"      (fn [item _] (or (:title item) (:block/title item) (:name item))) [:title :block/title :name]]
+   ["TYPE"       (fn [item _] (normalize-node-type (:node/type item))) [:node/type] true]
+   ["PAGE-ID"    (fn [item _] (:block/page-id item)) [:block/page-id]]
+   ["PAGE-TITLE" (fn [item _] (:block/page-title item)) [:block/page-title]]
+   ["UPDATED-AT" (fn [item now-ms] (human-ago (or (:updated-at item) (:block/updated-at item)) now-ms)) [:updated-at :block/updated-at]]
+   ["CREATED-AT" (fn [item now-ms] (human-ago (or (:created-at item) (:block/created-at item)) now-ms)) [:created-at :block/created-at]]])
+
+(defn- format-list-node
+  ([items now-ms]
+   (format-list-node items now-ms nil))
+  ([items now-ms title-max-display-width]
+   (format-list-dynamic items now-ms list-node-columns {:title-max-display-width title-max-display-width})))
+
+(defn- normalize-asset-type
+  [value]
+  (cond
+    (keyword? value) (name value)
+    (string? value) value
+    :else "-"))
+
+(def ^:private list-asset-columns
+  [["ID"         (fn [item _] (or (:db/id item) (:id item))) [:db/id :id]]
+   ["TITLE"      (fn [item _] (or (:title item) (:block/title item) (:name item))) [:title :block/title :name]]
+   ["ASSET-TYPE" (fn [item _] (normalize-asset-type (:logseq.property.asset/type item))) [:logseq.property.asset/type]]
+   ["SIZE"       (fn [item _] (cli-humanize/format-filesize (:logseq.property.asset/size item))) [:logseq.property.asset/size]]
+   ["UPDATED-AT" (fn [item now-ms] (human-ago (or (:updated-at item) (:block/updated-at item)) now-ms)) [:updated-at :block/updated-at]]
+   ["CREATED-AT" (fn [item now-ms] (human-ago (or (:created-at item) (:block/created-at item)) now-ms)) [:created-at :block/created-at]]])
+
+(defn- format-list-asset
+  ([items now-ms]
+   (format-list-asset items now-ms nil))
+  ([items now-ms title-max-display-width]
+   (format-list-dynamic items now-ms list-asset-columns {:title-max-display-width title-max-display-width})))
+
+(defn- quote-posix-shell
+  [value]
+  (str "'" (string/replace (normalize-cell value) #"'" "'\"'\"'") "'"))
+
+(defn- posix-join
+  [base leaf]
+  (let [base (normalize-cell base)
+        leaf (normalize-cell leaf)
+        base (string/replace base #"/+$" "")
+        leaf (string/replace leaf #"^/+" "")]
+    (if (seq base)
+      (str base "/" leaf)
+      leaf)))
+
+(defn- graph-list-item->entry
+  [item]
+  (if (string? item)
+    {:kind :canonical
+     :graph-name item}
+    item))
+
+(defn- legacy-graph-item?
+  [{:keys [kind]}]
+  (contains? #{:legacy :legacy-undecodable} kind))
+
+(defn- format-legacy-warning-lines
+  [legacy-item graphs-dir]
+  (let [{:keys [kind legacy-dir legacy-graph-name target-graph-dir conflict?]} legacy-item
+        legacy-dir (or legacy-dir "-")]
+    (case kind
+      :legacy
+      (cond
+        conflict?
+        [(str "Warning: target directory already exists for legacy graph '"
+              (normalize-cell legacy-graph-name)
+              "'.")
+         "Please rename manually after resolving the conflict."]
+
+        (and (seq legacy-graph-name)
+             (seq target-graph-dir))
+        (let [source-path (if (seq graphs-dir)
+                            (posix-join graphs-dir legacy-dir)
+                            legacy-dir)
+              target-path (if (seq graphs-dir)
+                            (posix-join graphs-dir target-graph-dir)
+                            target-graph-dir)]
+          ["Rename suggestion:"
+           (str "  mv "
+                (quote-posix-shell source-path)
+                " "
+                (quote-posix-shell target-path))])
+
+        :else
+        [(str "Warning: cannot derive graph name for legacy dir '"
+              (normalize-cell legacy-dir)
+              "'; rename command is not available.")])
+
+      :legacy-undecodable
+      [(str "Warning: cannot derive graph name for legacy dir '"
+            (normalize-cell legacy-dir)
+            "'; rename command is not available.")]
+
+      [])))
+
+(defn- format-graph-list
+  [{:keys [graphs graph-items]} {:keys [current-graph graphs-dir]}]
+  (let [graph-items (->> (or graph-items graphs [])
+                         (mapv graph-list-item->entry))
+        graph-names (mapv (fn [{:keys [kind graph-name legacy-graph-name legacy-dir]}]
+                            (case kind
+                              :canonical graph-name
+                              :legacy (or legacy-graph-name legacy-dir)
+                              :legacy-undecodable legacy-dir
+                              (or graph-name legacy-graph-name legacy-dir)))
+                          graph-items)
+        has-current? (and (seq current-graph)
+                          (some #(= % current-graph) graph-names))
+        rows (mapv (fn [item graph-name]
+                     (let [legacy? (legacy-graph-item? item)
+                           display-name (str graph-name (when legacy? " [legacy]"))
+                           selected? (= graph-name current-graph)]
+                       [(if has-current?
+                          (if selected?
+                            (str "* " display-name)
+                            (str "  " display-name))
+                          display-name)]))
+                   graph-items
+                   graph-names)
+        base-output (format-counted-table nil rows)
+        legacy-items (filterv legacy-graph-item? graph-items)]
+    (if (seq legacy-items)
+      (let [legacy-count (count legacy-items)
+            warning-lines (vec (concat [(str "Warning: "
+                                             (cli-humanize/format-count legacy-count)
+                                             " legacy graph "
+                                             (cli-humanize/pluralize-noun legacy-count "directory")
+                                             " detected.")]
+                                       (mapcat #(format-legacy-warning-lines % graphs-dir) legacy-items)))]
+        (str base-output "\n\n" (string/join "\n" warning-lines)))
+      base-output)))
+
+(defn- format-server-list-warning
+  [{:keys [cli-revision servers]}]
+  (when (seq servers)
+    (str "Warning: server revision mismatch detected\n"
+         "Local CLI revision: " (normalize-cell cli-revision) "\n"
+         "Mismatched servers:\n"
+         (string/join "\n"
+                      (map (fn [{:keys [repo revision]}]
+                             (str "  - " (normalize-cell repo)
+                                  " (revision: "
+                                  (normalize-cell revision)
+                                  ")"))
+                           servers)))))
+
+(defn- format-server-list
+  [servers revision-mismatch]
+  (let [table (format-counted-table
+               ["GRAPH" "STATUS" "HOST" "PORT" "PID" "OWNER" "REVISION"]
+               (mapv (fn [server]
+                       [(:repo server)
+                        (:status server)
+                        (:host server)
+                        (:port server)
+                        (:pid server)
+                        (:owner-source server)
+                        (:revision server)])
+                     (or servers [])))]
+    (if-let [warning (format-server-list-warning revision-mismatch)]
+      (str table "\n\n" warning)
+      table)))
+
+(defn- format-query-results
+  [result]
+  (let [edn-str (pr-str result)
+        parsed (common-util/safe-read-string {:log-error? false} edn-str)
+        valid? (or (some? parsed) (= "nil" (string/trim edn-str)))]
+    (if valid?
+      edn-str
+      edn-str)))
+
+(defn- format-query-list
+  [queries]
+  (format-counted-table
+   ["NAME" "INPUTS" "SOURCE" "DOC"]
+   (mapv (fn [{:keys [name inputs source doc]}]
+           [name
+            (if (seq inputs) (string/join ", " inputs) "-")
+            (clojure.core/name (or source :custom))
+            (or doc "-")])
+         (or queries []))))
+
+(defn- format-debug-pull
+  [{:keys [entity lookup selector]}]
+  (let [header [(str "Selector: " (pr-str selector))
+                (str "Lookup: " (pr-str lookup))
+                "Entity:"]
+        entity* (-> (with-out-str (pprint/pprint entity))
+                    string/trimr)]
+    (string/join "\n" (conj header entity*))))
+
+(defn- format-example
+  [{:keys [selector matched-commands examples message]}]
+  (let [selector (or selector "-")
+        matched-commands (vec (or matched-commands []))
+        examples (vec (or examples []))
+        matched-lines (if (seq matched-commands)
+                        (mapv #(str "  - " %) matched-commands)
+                        ["  - (none)"])
+        example-lines (if (seq examples)
+                        (mapv #(str "  - " %) examples)
+                        ["  - (none)"])]
+    (string/join "\n"
+                 (concat (when (seq message) [message ""])
+                         [(str "Selector: " selector)
+                          "Matched commands:"]
+                         matched-lines
+                         ["Examples:"]
+                         example-lines))))
+
+(declare kv-key->string
+         graph-info-human-max-string-length
+         graph-info-truncated-suffix)
+
+(defn- format-graph-info
+  [{:keys [graph kv logseq.kv/graph-created-at logseq.kv/schema-version]} now-ms]
+  (let [summary-lines [(str "Graph: " (or graph "-"))
+                       (str "Created at: " (if (some? graph-created-at)
+                                             (human-ago graph-created-at now-ms)
+                                             "-"))
+                       (str "Schema version: " (or schema-version "-"))]
+        truncate-value (fn [value]
+                         (if (and (string? value)
+                                  (> (count value) graph-info-human-max-string-length))
+                           (str (subs value 0 graph-info-human-max-string-length)
+                                graph-info-truncated-suffix)
+                           value))
+        kv-lines (if (seq kv)
+                   (into ["KV:"]
+                         (->> kv
+                              (sort-by (comp kv-key->string key))
+                              (map (fn [[kv-key kv-value]]
+                                     (str "  " (kv-key->string kv-key) ": "
+                                          (pr-str (truncate-value kv-value)))))))
+                   ["KV:" "  (empty)"])]
+    (string/join "\n" (into summary-lines kv-lines))))
+
+(defn- format-server-cleanup-target
+  [{:keys [repo pid owner-source revision]}]
+  (str "  - " (normalize-cell repo)
+       " (pid: " (normalize-cell pid)
+       ", owner: " (normalize-cell owner-source)
+       ", revision: " (normalize-cell revision)
+       ")"))
+
+(defn- format-server-cleanup-failed-target
+  [{:keys [repo pid owner-source revision error]}]
+  (str "  - " (normalize-cell repo)
+       " (pid: " (normalize-cell pid)
+       ", owner: " (normalize-cell owner-source)
+       ", revision: " (normalize-cell revision)
+       ", error: " (normalize-cell (or (:code error) :unknown))
+       " - " (normalize-cell (:message error))
+       ")"))
+
+(defn- format-server-cleanup
+  [{:keys [cli-revision checked mismatched eligible skipped-owner skipped-owner-targets killed failed]}]
+  (let [failed (vec (or failed []))
+        skipped-owner-targets (vec (or skipped-owner-targets []))
+        header-lines ["Server cleanup summary"
+                      (str "CLI revision: " (normalize-cell cli-revision))
+                      (str "Checked: " (cli-humanize/format-count (or checked 0)))
+                      (str "Mismatched: " (cli-humanize/format-count (or mismatched 0)))
+                      (str "Eligible (:cli owner): " (cli-humanize/format-count (or eligible 0)))
+                      (str "Skipped owner mismatch: " (cli-humanize/format-count (or skipped-owner 0)))
+                      (str "Killed: " (cli-humanize/format-count (count (or killed []))))
+                      (str "Failed: " (cli-humanize/format-count (count failed)))]
+        skipped-lines (when (seq skipped-owner-targets)
+                        (into ["" "Skipped owner targets:"]
+                              (mapv format-server-cleanup-target skipped-owner-targets)))
+        failed-lines (when (seq failed)
+                       (into ["" "Failed targets:"]
+                             (mapv format-server-cleanup-failed-target failed)))]
+    (string/join "\n" (concat header-lines skipped-lines failed-lines))))
+
+(defn- format-server-action
+  [command {:keys [repo status host port]}]
+  (let [status (or status
+                   (case command
+                     :server-start :started
+                     :server-stop :stopped
+                     :server-restart :restarted
+                     :unknown))]
+    (string/join "\n"
+                 (cond-> [(str "Server " (name status) ": " repo)]
+                   (and host port) (conj (str "Host: " host "  Port: " port))))))
+
+(def ^:private redacted-token "[REDACTED]")
+(def ^:private graph-info-sensitive-kv-pattern #"(?i)(token|secret|password)")
+(def ^:private graph-info-human-max-string-length 120)
+(def ^:private graph-info-truncated-suffix "... [truncated]")
+
+(defn- kv-key->string
+  [kv-key]
+  (if (keyword? kv-key)
+    (if-let [kv-ns (namespace kv-key)]
+      (str kv-ns "/" (name kv-key))
+      (name kv-key))
+    (str kv-key)))
+
+(defn- sensitive-graph-kv-key?
+  [kv-key]
+  (boolean (re-find graph-info-sensitive-kv-pattern (kv-key->string kv-key))))
+
+(defn- redact-graph-kv
+  [kv]
+  (into {}
+        (map (fn [[kv-key kv-value]]
+               [kv-key
+                (if (sensitive-graph-kv-key? kv-key)
+                  redacted-token
+                  kv-value)]))
+        (or kv {})))
+
+(defn- sanitize-graph-info-data
+  [data]
+  (if (map? data)
+    (update data :kv redact-graph-kv)
+    data))
+
+(defn- sanitize-auth-data
+  [data]
+  (if (map? data)
+    (apply dissoc data [:id-token :access-token :refresh-token])
+    data))
+
+(defn- sanitize-result
+  [result]
+  (cond
+    (and (= :ok (:status result))
+         (= :graph-info (:command result)))
+    (update result :data sanitize-graph-info-data)
+
+    (= :login (:command result))
+    (update result :data sanitize-auth-data)
+
+    :else
+    result))
+
+(defn- format-sync-status
+  [{:keys [repo graph-id ws-state pending-local pending-asset pending-server local-tx remote-tx last-error]}]
+  (let [last-error-line (when (map? last-error)
+                          (str "last-error: "
+                               (or (:code last-error) :error)
+                               (when-let [message (:message last-error)]
+                                 (str " (" message ")"))))]
+    (string/join "\n"
+                 (cond-> ["Sync status"
+                          (str "repo: " (or repo "-"))
+                          (str "graph-id: " (or graph-id "-"))
+                          (str "ws-state: " (or ws-state :unknown))
+                          (str "pending-local: " (cli-humanize/format-count (or pending-local 0)))
+                          (str "pending-asset: " (cli-humanize/format-count (or pending-asset 0)))
+                          (str "pending-server: " (cli-humanize/format-count (or pending-server 0)))
+                          (str "local-tx: " (if (number? local-tx)
+                                               (cli-humanize/format-count local-tx)
+                                               "-"))
+                          (str "remote-tx: " (if (number? remote-tx)
+                                                (cli-humanize/format-count remote-tx)
+                                                "-"))]
+                   last-error-line (conj last-error-line)))))
+
+(defn- format-sync-remote-graphs
+  [graphs]
+  (format-counted-table
+   ["GRAPH-ID" "GRAPH-NAME" "ROLE" "E2EE"]
+   (mapv (fn [{:keys [graph-id graph-name role graph-e2ee?]}]
+           [graph-id
+            graph-name
+            (or role "-")
+            (if (nil? graph-e2ee?)
+              "-"
+              (if graph-e2ee? "true" "false"))])
+         (or graphs []))))
+
+(defn- format-sync-action
+  [command {:keys [repo email]}]
+  (case command
+    :sync-start (str "Sync started: " repo)
+    :sync-stop (str "Sync stopped: " repo)
+    :sync-upload (str "Sync upload requested: " repo)
+    :sync-download (str "Sync download requested: " repo)
+    :sync-ensure-keys "Sync keys ensured"
+    :sync-grant-access (str "Sync access granted: " email " (repo: " repo ")")
+    "Sync updated"))
+
+(defn- format-sync-config-get
+  [{:keys [key value]}]
+  (let [display-value (if (contains? #{:auth-token :e2ee-password} key)
+                        redacted-token
+                        (if (some? value) value "-"))]
+    (str "sync config " (name key) ": " display-value)))
+
+(defn- format-sync-config-set
+  [{:keys [key]}]
+  (str "sync config set: " (name key)))
+
+(defn- format-sync-config-unset
+  [{:keys [key]}]
+  (str "sync config unset: " (name key)))
+
+(defn- format-login
+  [{:keys [auth-path email sub]}]
+  (string/join "\n"
+               (cond-> ["Login successful"
+                        (str "Auth file: " (or auth-path "-"))]
+                 (seq email) (conj (str "Email: " email))
+                 (seq sub) (conj (str "User: " sub)))))
+
+(defn- format-logout
+  [{:keys [auth-path deleted? opened? logout-completed?]}]
+  (string/join "\n"
+               (cond-> [(str (if deleted?
+                               "Logged out"
+                               "Already logged out")
+                             ": "
+                             (or auth-path "-"))]
+                 logout-completed? (conj "Cognito logout: completed")
+                 (and (not logout-completed?) (true? opened?))
+                 (conj "Cognito logout: browser opened, completion not confirmed")
+                 (false? opened?)
+                 (conj "Cognito logout: could not open browser"))))
+
+(defn- format-upsert-block
+  [{:keys [repo source target update-tags update-properties remove-tags remove-properties]} result]
+  (if (vector? result)
+    (str "Upserted blocks:\n" (pr-str (vec (or result []))))
+    (let [change-parts (cond-> []
+                         (seq update-tags) (conj (str "tags:+" (cli-humanize/format-count (count update-tags))))
+                         (seq update-properties) (conj (str "properties:+" (cli-humanize/format-count (count update-properties))))
+                         (seq remove-tags) (conj (str "remove-tags:+" (cli-humanize/format-count (count remove-tags))))
+                         (seq remove-properties) (conj (str "remove-properties:+" (cli-humanize/format-count (count remove-properties)))))
+          changes (when (seq change-parts)
+                    (str ", " (string/join ", " change-parts)))
+          move-fragment (when (seq target)
+                          (str " -> " target))]
+      (str "Upserted block: " source (or move-fragment "") " (repo: " repo (or changes "") ")"))))
+
+(defn- format-upsert-page
+  [_context ids]
+  (str "Upserted page:\n" (pr-str (vec (or ids [])))))
+
+(defn- format-upsert-task
+  [_context ids]
+  (str "Upserted task:\n" (pr-str (vec (or ids [])))))
+
+(defn- format-upsert-tag
+  [_context ids]
+  (str "Upserted tag:\n" (pr-str (vec (or ids [])))))
+
+(defn- format-upsert-property
+  [_context ids]
+  (str "Upserted property:\n" (pr-str (vec (or ids [])))))
+
+(defn- format-upsert-asset
+  [_context ids]
+  (str "Upserted asset:\n" (pr-str (vec (or ids [])))))
+
+(defn- format-remove-block
+  [{:keys [repo uuid id ids]}]
+  (cond
+    (seq uuid) (str "Removed block: " uuid " (repo: " repo ")")
+    (seq ids) (str "Removed blocks: " (cli-humanize/format-count (count ids)) " (repo: " repo ")")
+    (some? id) (str "Removed block: " id " (repo: " repo ")")
+    :else (str "Removed block (repo: " repo ")")))
+
+(defn- format-remove-page
+  [{:keys [repo page]}]
+  (str "Removed page: " page " (repo: " repo ")"))
+
+(defn- format-remove-tag
+  [{:keys [repo name id]}]
+  (if (seq name)
+    (str "Removed tag: " name " (repo: " repo ")")
+    (str "Removed tag: " id " (repo: " repo ")")))
+
+(defn- format-remove-property
+  [{:keys [repo name id]}]
+  (if (seq name)
+    (str "Removed property: " name " (repo: " repo ")")
+    (str "Removed property: " id " (repo: " repo ")")))
+
+(defn- format-graph-export
+  [{:keys [export-type file]}]
+  (str "Exported " export-type " to " file))
+
+(defn- format-graph-import
+  [_context {:keys [message]}]
+  message)
+
+(defn- format-graph-backup-list
+  [backups now-ms]
+  (format-counted-table
+   ["NAME" "CREATED-AT" "SIZE-BYTES"]
+   (mapv (fn [{:keys [name created-at size-bytes]}]
+           [(or name "-")
+            (human-ago created-at now-ms)
+            (or size-bytes 0)])
+         (or backups []))))
+
+(defn- format-graph-backup-create
+  [context data]
+  (let [backup-name (or (:backup-name data) (:backup-name context) "-")
+        graph (or (:graph context) "-")]
+    (str "Created backup: " backup-name " (graph: " graph ")")))
+
+(defn- format-graph-backup-restore
+  [{:keys [src dst]}]
+  (str "Restored backup " (or src "-") " -> " (or dst "-")))
+
+(defn- format-graph-backup-remove
+  [{:keys [src]}]
+  (str "Removed backup: " (or src "-")))
+
+(defn- format-graph-action
+  [command {:keys [graph]}]
+  (let [verb (case command
+               :graph-create "Created"
+               :graph-switch "Switched to"
+               :graph-remove "Removed"
+               :graph-validate "Validated"
+               "Updated")]
+    (str verb " graph " (pr-str graph))))
+
+(defn- quote-cli-arg
+  [value]
+  (let [value (normalize-cell value)]
+    (if (re-find #"\s" value)
+      (str "\"" (string/replace value #"\"" "\\\"") "\"")
+      value)))
+
+(defn- format-doctor-check
+  [{:keys [id status message servers]}]
+  (let [check-line (str "[" (name (or status :unknown))
+                        "] "
+                        (name (or id :unknown))
+                        (when (seq message)
+                          (str " - " message)))]
+    (if (= :server-revision-mismatch id)
+      (let [guidance-lines (mapv (fn [{:keys [graph repo]}]
+                                   (str "  Run: logseq server restart --graph "
+                                        (quote-cli-arg (or graph repo))))
+                                 (or servers []))]
+        (into [check-line] guidance-lines))
+      [check-line])))
+
+(defn- format-doctor
+  [status checks]
+  (let [header (str "Doctor: " (name (or status :unknown)))
+        check-lines (mapcat format-doctor-check (or checks []))]
+    (string/join "\n" (into [header] check-lines))))
+
+(defn- ->human
+  [{:keys [status data error command context human]}
+   {:keys [now-ms graph graphs-dir list-title-max-display-width]}]
+  (let [now-ms (or now-ms (js/Date.now))
+        list-title-max-display-width (resolve-list-title-max-display-width list-title-max-display-width)]
+    (case status
+      :ok
+      (case command
+        :graph-list (format-graph-list data {:current-graph graph
+                                             :graphs-dir graphs-dir})
+        :graph-backup-list (format-graph-backup-list (:backups data) now-ms)
+        :graph-backup-create (format-graph-backup-create context data)
+        :graph-backup-restore (format-graph-backup-restore context)
+        :graph-backup-remove (format-graph-backup-remove context)
+        :graph-info (format-graph-info data now-ms)
+        (:graph-create :graph-switch :graph-remove :graph-validate)
+        (format-graph-action command context)
+        :server-list (format-server-list (:servers data)
+                                         (get-in human [:server-list :revision-mismatch]))
+        :server-cleanup (format-server-cleanup data)
+        (:server-start :server-stop :server-restart)
+        (format-server-action command data)
+        :sync-status (format-sync-status data)
+        :sync-remote-graphs (format-sync-remote-graphs (:graphs data))
+        (:sync-start :sync-stop :sync-upload :sync-download :sync-ensure-keys :sync-grant-access)
+        (format-sync-action command context)
+        :sync-config-get (format-sync-config-get data)
+        :sync-config-set (format-sync-config-set data)
+        :sync-config-unset (format-sync-config-unset data)
+        :login (format-login data)
+        :logout (format-logout data)
+        :list-page (format-list-page (:items data) now-ms list-title-max-display-width)
+        :list-tag (format-list-tag (:items data) now-ms list-title-max-display-width)
+        :list-property (format-list-property (:items data) now-ms list-title-max-display-width)
+        :list-task (format-list-task (:items data) now-ms list-title-max-display-width)
+        :list-node (format-list-node (:items data) now-ms list-title-max-display-width)
+        :list-asset (format-list-asset (:items data) now-ms list-title-max-display-width)
+        (:search-block :search-page :search-property :search-tag)
+        (format-list-page (:items data) now-ms)
+        :upsert-block (format-upsert-block context (:result data))
+        :upsert-page (format-upsert-page context (:result data))
+        :upsert-task (format-upsert-task context (:result data))
+        :upsert-asset (format-upsert-asset context (:result data))
+        :upsert-tag (format-upsert-tag context (:result data))
+        :upsert-property (format-upsert-property context (:result data))
+        :remove-block (format-remove-block context)
+        :remove-page (format-remove-page context)
+        :remove-tag (format-remove-tag context)
+        :remove-property (format-remove-property context)
+        :graph-export (format-graph-export context)
+        :graph-import (format-graph-import context data)
+        :query (format-query-results (:result data))
+        :query-list (format-query-list (:queries data))
+        :example (format-example data)
+        :show (or (:message data) (pr-str data))
+        :debug-pull (format-debug-pull data)
+        :doctor (format-doctor (:status data) (:checks data))
+        (if (and (map? data) (contains? data :message))
+          (:message data)
+          (pr-str data)))
+
+      :error
+      (if (= :doctor command)
+        (format-doctor (or (get-in data [:status]) :error)
+                       (or (get-in data [:checks])
+                           (get-in error [:checks])))
+        (format-error error command))
+
+      (pr-str {:status status :data data :error error}))))
+
+(defn- ->edn
+  [{:keys [status data error command]}]
+  (pr-str (cond-> {:status status}
+            (= status :ok) (assoc :data data)
+            (= status :error) (assoc :error error)
+            (and (= status :error) (= :doctor command) (some? data))
+            (assoc :data data))))
+
+(defn- normalize-graph-result
+  [result]
+  (walk/postwalk
+   (fn [entry]
+     (if (map? entry)
+       (cond-> entry
+         (string? (:repo entry)) (update :repo command-core/repo->graph)
+         (string? (:graph entry)) (update :graph command-core/repo->graph)
+         (seq (:graphs entry)) (update :graphs (fn [graphs]
+                                                 (mapv command-core/repo->graph graphs))))
+       entry))
+   result))
+
+(defn format-result
+  [result {:keys [output-format] :as opts}]
+  (let [result (-> result
+                   normalize-graph-result
+                   sanitize-result)
+        mode (or (output-mode/parse output-format) :human)]
+    (case mode
+      :json (->json result)
+      :edn (->edn result)
+      (->human result opts))))
diff --git a/src/main/logseq/cli/humanize.cljs b/src/main/logseq/cli/humanize.cljs
new file mode 100644
index 0000000000..5d6bc87ef7
--- /dev/null
+++ b/src/main/logseq/cli/humanize.cljs
@@ -0,0 +1,37 @@
+(ns logseq.cli.humanize
+  "CLI-local wrappers around clj-commons humanize helpers."
+  (:require [clj-commons.humanize :as humanize]
+            [clj-commons.humanize.inflect :as humanize-inflect]))
+
+(defn format-count
+  [value]
+  (let [n (if (number? value) value 0)]
+    (humanize/intcomma (js/Math.floor n))))
+
+(defn pluralize-noun
+  [count noun]
+  (humanize-inflect/pluralize-noun (or count 0) noun))
+
+(defn format-count-with-noun
+  [count noun]
+  (str (format-count count)
+       " "
+       (pluralize-noun count noun)))
+
+(defn format-filesize
+  [byte-count]
+  (if (number? byte-count)
+    (humanize/filesize byte-count :binary true :format "%.1f")
+    "-"))
+
+(defn relative-datetime
+  [then-ms now-ms]
+  (cond
+    (not (number? then-ms)) "-"
+    (not (number? now-ms)) "-"
+    (<= then-ms 0) "-"
+    :else
+    (humanize/relative-datetime (js/Date. then-ms)
+                                :now-dt (js/Date. now-ms)
+                                :max-terms 1
+                                :number-format str)))
diff --git a/src/main/logseq/cli/log.cljs b/src/main/logseq/cli/log.cljs
new file mode 100644
index 0000000000..b14fba8357
--- /dev/null
+++ b/src/main/logseq/cli/log.cljs
@@ -0,0 +1,53 @@
+(ns logseq.cli.log
+  "CLI logging helpers for verbose debug output."
+  (:require [lambdaisland.glogi :as log]))
+
+(def ^:private default-preview-limit 400)
+
+(defonce ^:private handler-installed? (atom false))
+
+(defn truncate-preview
+  "Returns a preview map with `:preview`, `:length`, and `:truncated?` for `value`.
+
+  Example:
+
+  ```clojure
+  (truncate-preview {:a 1} 10)
+  ```"
+  ([value]
+   (truncate-preview value default-preview-limit))
+  ([value max-len]
+   (let [text (if (string? value) value (pr-str value))
+         length (count text)
+         limit (max 0 (or max-len 0))
+         truncated? (> length limit)
+         preview (if truncated?
+                   (subs text 0 limit)
+                   text)]
+     {:preview preview
+      :length length
+      :truncated? truncated?})))
+
+(defn- format-record
+  [{:keys [level logger-name message exception time]}]
+  (cond-> {:time time
+           :level level
+           :logger logger-name
+           :message message}
+    exception (assoc :exception (str exception))))
+
+(defn- stderr-handler
+  [record]
+  (.write (.-stderr js/process)
+          (str (pr-str (format-record record)) "\n")))
+
+(defn install-stderr-handler!
+  []
+  (when-not @handler-installed?
+    (log/add-handler stderr-handler)
+    (reset! handler-installed? true)))
+
+(defn set-verbose!
+  [verbose?]
+  (install-stderr-handler!)
+  (log/set-levels {:glogi/root (if verbose? :debug :info)}))
diff --git a/src/main/logseq/cli/main.cljs b/src/main/logseq/cli/main.cljs
new file mode 100644
index 0000000000..c50325ddbe
--- /dev/null
+++ b/src/main/logseq/cli/main.cljs
@@ -0,0 +1,212 @@
+(ns logseq.cli.main
+  "CLI entrypoint for invoking db-worker-node."
+  (:refer-clojure :exclude [run!])
+  (:require [lambdaisland.glogi :as log]
+            [logseq.cli.command.core :as command-core]
+            [logseq.cli.commands :as commands]
+            [logseq.cli.config :as config]
+            [logseq.cli.format :as format]
+            [logseq.cli.log :as cli-log]
+            [logseq.cli.output-mode :as output-mode]
+            [logseq.cli.profile :as profile]
+            [logseq.cli.root-dir :as root-dir]
+            [logseq.cli.version :as version]
+            [promesa.core :as p]))
+
+(defn- result->exit-code
+  [result]
+  (or (:exit-code result)
+      (if (= :error (:status result)) 1 0)))
+
+(defn- profile-enabled-argv?
+  [args]
+  (boolean (some #{"--profile"} args)))
+
+(defn- profile-command
+  [parsed]
+  (cond
+    (:help? parsed) "help"
+    (keyword? (:command parsed)) (name (:command parsed))
+    (string? (:command parsed)) (:command parsed)
+    :else "unknown"))
+
+(defn- attach-profile-lines
+  [profile-session parsed result]
+  (if profile-session
+    (assoc result
+           :profile-lines
+           (profile/render-lines
+            (profile/report profile-session
+                            {:command (profile-command parsed)
+                             :status (if (zero? (:exit-code result)) :ok :error)})))
+    result))
+
+(defn- parse-argv-output-format
+  [args]
+  (let [{:keys [opts]} (command-core/parse-leading-global-opts args)]
+    (or (output-mode/parse (:output-format opts))
+        (output-mode/parse (:output opts)))))
+
+(defn- parsed-output-format
+  [parsed]
+  (or (output-mode/parse (get-in parsed [:options :output-format]))
+      (output-mode/parse (get-in parsed [:options :output]))))
+
+(defn- resolve-output-format
+  [args parsed cfg result]
+  (or (output-mode/parse (:output-format result))
+      (output-mode/parse (:output-format cfg))
+      (parsed-output-format parsed)
+      (parse-argv-output-format args)))
+
+(defn- format-opts
+  [args parsed cfg result]
+  (if-let [mode (resolve-output-format args parsed cfg result)]
+    {:output-format mode}
+    {}))
+
+(defn- handle-unexpected-error
+  [profile-session parsed cfg error]
+  (let [data (ex-data error)
+        message (or (.-message error) (:message error) (str error))]
+    (if (= :root-dir-permission (:code data))
+      (p/resolved
+       (attach-profile-lines
+        profile-session
+        parsed
+        {:exit-code 1
+         :output (profile/time! profile-session "cli.format-result"
+                                (fn []
+                                  (format/format-result {:status :error
+                                                         :error {:code :root-dir-permission
+                                                                 :message message
+                                                                 :path (:path data)}}
+                                                        cfg)))}))
+      (attach-profile-lines
+       profile-session
+       parsed
+       {:exit-code 1
+        :output (profile/time! profile-session "cli.format-result"
+                               (fn []
+                                 (format/format-result {:status :error
+                                                        :error {:code (or (:code data) :exception)
+                                                                :message (str message
+                                                                              (when (get-in parsed [:options :verbose])
+                                                                                (str "\nStacktrace:\n"
+                                                                                     (.-stack error))))}}
+                                                       cfg)))}))))
+
+(defn run!
+  ([args] (run! args {}))
+  ([args _opts]
+   (let [profile-session (profile/create-session (profile-enabled-argv? args))
+         parsed (profile/time! profile-session "cli.parse-args"
+                               (fn []
+                                 (commands/parse-args args)))]
+     (cond
+       (:help? parsed)
+       (p/resolved
+        (let [mode (resolve-output-format args parsed nil nil)]
+          (attach-profile-lines
+           profile-session
+           parsed
+           {:exit-code 0
+            :output (if (output-mode/structured? mode)
+                      (profile/time! profile-session "cli.format-result"
+                                     (fn []
+                                       (format/format-result {:status :ok
+                                                              :data {:message (:summary parsed)}}
+                                                             {:output-format mode})))
+                      (:summary parsed))})))
+
+       (not (:ok? parsed))
+       (p/resolved
+        (attach-profile-lines
+         profile-session
+         parsed
+         {:exit-code 1
+          :output (profile/time! profile-session "cli.format-result"
+                                 (fn []
+                                   (format/format-result {:status :error
+                                                          :error (:error parsed)
+                                                          :command (:command parsed)}
+                                                         (format-opts args parsed nil nil))))}))
+
+       (= :version (:command parsed))
+       (p/resolved
+        (attach-profile-lines profile-session parsed
+                              {:exit-code 0
+                               :output (version/format-version)}))
+
+       :else
+       (let [cfg* (profile/time! profile-session "cli.resolve-config"
+                                 (fn []
+                                   (config/resolve-config (:options parsed))))
+             cfg (cond-> cfg*
+                   profile-session (assoc :profile-session profile-session))]
+         (cli-log/set-verbose! (:verbose cfg))
+         (log/debug :event :cli/parsed-options
+                    :command (:command parsed)
+                    :args (cli-log/truncate-preview (:args parsed))
+                    :options (into {}
+                                   (map (fn [[k v]]
+                                          [k (cli-log/truncate-preview v)])
+                                        (:options parsed)))
+                    :config (into {}
+                                  (map (fn [[k v]]
+                                         [k (cli-log/truncate-preview v)])
+                                       (dissoc cfg :auth-token))))
+         (try
+           (let [cfg (assoc cfg
+                            :root-dir
+                            (profile/time! profile-session "cli.ensure-root-dir"
+                                           (fn []
+                                             (root-dir/ensure-root-dir! (:root-dir cfg)))))
+                 action-result (profile/time! profile-session "cli.build-action"
+                                              (fn []
+                                                (commands/build-action parsed cfg)))]
+             (if-not (:ok? action-result)
+               (p/resolved
+                (attach-profile-lines
+                 profile-session
+                 parsed
+                 {:exit-code 1
+                  :output (profile/time! profile-session "cli.format-result"
+                                         (fn []
+                                           (format/format-result {:status :error
+                                                                  :error (:error action-result)
+                                                                  :command (:command parsed)
+                                                                  :context (select-keys (:options parsed)
+                                                                                        [:repo :graph :page :block])}
+                                                                 cfg)))}))
+               (-> (profile/time! profile-session "cli.execute-action"
+                                  (fn []
+                                    (commands/execute (:action action-result) cfg)))
+                   (p/then (fn [result]
+                             (let [opts (merge cfg (format-opts args parsed cfg result))]
+                               (attach-profile-lines
+                                profile-session
+                                parsed
+                                {:exit-code (result->exit-code result)
+                                 :output (profile/time! profile-session "cli.format-result"
+                                                        (fn []
+                                                          (format/format-result result opts)))}))))
+                   (p/catch (partial handle-unexpected-error profile-session parsed cfg)))))
+           (catch :default error
+             (handle-unexpected-error profile-session parsed cfg error))))))))
+
+(defn- print-profile-lines!
+  [profile-lines]
+  (doseq [line profile-lines]
+    (.write (.-stderr js/process) (str line "\n"))))
+
+(defn main
+  [& args]
+  (-> (run! args)
+      (p/then (fn [{:keys [exit-code output profile-lines]}]
+                (when (seq output)
+                  (println output))
+                (when (seq profile-lines)
+                  (print-profile-lines! profile-lines))
+                (when-not (zero? exit-code)
+                  (.exit js/process exit-code))))))
diff --git a/src/main/logseq/cli/output_mode.cljs b/src/main/logseq/cli/output_mode.cljs
new file mode 100644
index 0000000000..0b6be4b36f
--- /dev/null
+++ b/src/main/logseq/cli/output_mode.cljs
@@ -0,0 +1,29 @@
+(ns logseq.cli.output-mode
+  "Shared output mode utilities for CLI human/json/edn output handling."
+  (:require [clojure.string :as string]))
+
+(def allowed-keywords
+  #{:human :json :edn})
+
+(def allowed-values
+  (into #{} (map name) allowed-keywords))
+
+(def ^:private structured-keywords
+  #{:json :edn})
+
+(defn parse
+  [value]
+  (let [mode (cond
+               (keyword? value) value
+               (string? value) (some-> value string/trim string/lower-case keyword)
+               :else nil)]
+    (when (contains? allowed-keywords mode)
+      mode)))
+
+(defn string-value
+  [value]
+  (some-> (parse value) name))
+
+(defn structured?
+  [value]
+  (contains? structured-keywords (parse value)))
diff --git a/src/main/logseq/cli/profile.cljs b/src/main/logseq/cli/profile.cljs
new file mode 100644
index 0000000000..6034b3d8f8
--- /dev/null
+++ b/src/main/logseq/cli/profile.cljs
@@ -0,0 +1,231 @@
+(ns logseq.cli.profile
+  "Stage timing profiler for logseq CLI runtime."
+  (:require [promesa.core :as p]))
+
+(defn create-session
+  [enabled?]
+  (when enabled?
+    {:enabled? true
+     :started-ms (js/Date.now)
+     :spans (atom [])
+     :next-span-id (atom 0)}))
+
+(defn- next-span-id
+  [session]
+  (swap! (:next-span-id session) inc))
+
+(defn- record-span!
+  [session {:keys [stage span-id started-ms ended-ms]}]
+  (when session
+    (let [started-ms (or started-ms ended-ms 0)
+          ended-ms (or ended-ms started-ms)
+          elapsed-ms (max 0 (- ended-ms started-ms))]
+      (swap! (:spans session) conj {:stage stage
+                                    :span-id span-id
+                                    :started-ms started-ms
+                                    :ended-ms ended-ms
+                                    :elapsed-ms elapsed-ms}))))
+
+(defn- thenable?
+  [value]
+  (and (some? value)
+       (fn? (.-then value))))
+
+(defn time!
+  [session stage f]
+  (if-not session
+    (f)
+    (let [start-ms (js/Date.now)
+          span-id (next-span-id session)]
+      (try
+        (let [result (f)]
+          (if (thenable? result)
+            (-> result
+                (p/finally (fn []
+                             (record-span! session {:stage stage
+                                                    :span-id span-id
+                                                    :started-ms start-ms
+                                                    :ended-ms (js/Date.now)}))))
+            (do
+              (record-span! session {:stage stage
+                                     :span-id span-id
+                                     :started-ms start-ms
+                                     :ended-ms (js/Date.now)})
+              result)))
+        (catch :default e
+          (record-span! session {:stage stage
+                                 :span-id span-id
+                                 :started-ms start-ms
+                                 :ended-ms (js/Date.now)})
+          (throw e))))))
+
+(defn- summarize-stages
+  [spans]
+  (let [aggregated (reduce (fn [acc {:keys [stage elapsed-ms]}]
+                             (update acc stage
+                                     (fn [{:keys [count total-ms] :as current}]
+                                       (if current
+                                         (assoc current
+                                                :count (inc count)
+                                                :total-ms (+ total-ms elapsed-ms))
+                                         {:stage stage
+                                          :count 1
+                                          :total-ms elapsed-ms}))))
+                           {}
+                           spans)
+        order (distinct (map :stage spans))]
+    (mapv (fn [stage]
+            (let [{:keys [count total-ms]} (get aggregated stage)
+                  avg-ms (if (pos? count)
+                           (js/Math.round (/ total-ms count))
+                           0)]
+              {:stage stage
+               :count count
+               :total-ms total-ms
+               :avg-ms avg-ms}))
+          order)))
+
+(defn report
+  [session {:keys [command status]}]
+  (let [started-ms (or (:started-ms session) (js/Date.now))
+        now-ms (js/Date.now)
+        total-ms (max 0 (- now-ms started-ms))
+        spans (vec (or @(some-> session :spans) []))
+        spans (if (some #(= "cli.total" (:stage %)) spans)
+                spans
+                (conj spans {:stage "cli.total"
+                             :span-id 0
+                             :started-ms started-ms
+                             :ended-ms now-ms
+                             :elapsed-ms total-ms}))]
+    {:command command
+     :status status
+     :total-ms total-ms
+     :spans spans
+     :stages (summarize-stages spans)}))
+
+(defn- span-node
+  [span]
+  (let [elapsed-ms (max 0 (or (:elapsed-ms span) 0))]
+    {:label (:stage span)
+     :span span
+     :elapsed-ms elapsed-ms
+     :children (atom [])}))
+
+(defn- span-contains?
+  [outer inner]
+  (let [outer-start (:started-ms outer)
+        outer-end (:ended-ms outer)
+        inner-start (:started-ms inner)
+        inner-end (:ended-ms inner)]
+    (and (number? outer-start)
+         (number? outer-end)
+         (number? inner-start)
+         (number? inner-end)
+         (<= outer-start inner-start)
+         (>= outer-end inner-end))))
+
+(defn- sort-spans-for-tree
+  [spans]
+  (sort-by (fn [{:keys [started-ms ended-ms span-id]}]
+             (let [start (or started-ms 0)
+                   end (or ended-ms start)
+                   duration (max 0 (- end start))]
+               [start (- duration) (or span-id 0)]))
+           spans))
+
+(defn- freeze-node
+  [node]
+  (let [children @(:children node)]
+    (-> node
+        (dissoc :span)
+        (assoc :children (mapv freeze-node children)))))
+
+(defn- build-stage-tree-from-spans
+  [spans]
+  (let [ordered (sort-spans-for-tree spans)
+        roots (atom [])
+        stack (atom [])
+        trim-stack (fn [current-stack span]
+                     (loop [items current-stack]
+                       (if (and (seq items)
+                                (not (span-contains? (:span (peek items)) span)))
+                         (recur (pop items))
+                         items)))
+        push-node! (fn [parent child]
+                     (if parent
+                       (swap! (:children parent) conj child)
+                       (swap! roots conj child)))]
+    (doseq [span ordered]
+      (let [node (span-node span)
+            trimmed (trim-stack @stack span)
+            parent (peek trimmed)]
+        (push-node! parent node)
+        (reset! stack (conj trimmed node))))
+    {:label "stages"
+     :children (mapv freeze-node @roots)}))
+
+(defn- build-stage-tree-from-stages
+  [stages]
+  {:label "stages"
+   :children (mapv (fn [stage-data]
+                     {:label (:stage stage-data)
+                      :elapsed-ms (max 0 (or (:elapsed-ms stage-data)
+                                             (:total-ms stage-data)
+                                             0))
+                      :children []})
+                   stages)})
+
+(defn- stage-node->text
+  [{:keys [label]}]
+  label)
+
+(defn- render-stage-tree-rows
+  [stage-tree]
+  (let [rows (atom [{:elapsed-ms nil
+                     :text (:label stage-tree)}])
+        walk (fn walk [node prefix]
+               (let [children (:children node)
+                     total (count children)]
+                 (doseq [[idx child] (map-indexed vector children)]
+                   (let [last-child? (= idx (dec total))
+                         branch (if last-child? "└── " "├── ")
+                         next-prefix (str prefix (if last-child? "    " "│   "))]
+                     (swap! rows conj {:elapsed-ms (:elapsed-ms child)
+                                       :text (str prefix
+                                                  branch
+                                                  (stage-node->text child))})
+                     (walk child next-prefix)))))]
+    (walk stage-tree "")
+    @rows))
+
+(defn- pad-right
+  [value width]
+  (let [padding (max 0 (- width (count value)))]
+    (str value (apply str (repeat padding " ")))))
+
+(defn- format-profile-lines
+  [rows]
+  (let [duration-strs (mapv (fn [{:keys [elapsed-ms]}]
+                              (when (number? elapsed-ms)
+                                (str elapsed-ms "ms")))
+                            rows)
+        duration-width (apply max 0 (map #(count (or % "")) duration-strs))]
+    (mapv (fn [{:keys [text]} duration-str]
+            (str (pad-right (or duration-str "") duration-width)
+                 " "
+                 text))
+          rows
+          duration-strs)))
+
+(defn render-lines
+  [{:keys [command status total-ms spans stages]}]
+  (let [status-str (if (keyword? status) (name status) (str status))
+        header-row {:elapsed-ms total-ms
+                    :text (str "command=" command
+                               " status=" status-str)}
+        stage-tree (if (seq spans)
+                     (build-stage-tree-from-spans spans)
+                     (build-stage-tree-from-stages stages))
+        stage-rows (render-stage-tree-rows stage-tree)]
+    (format-profile-lines (vec (cons header-row stage-rows)))))
\ No newline at end of file
diff --git a/src/main/logseq/cli/root_dir.cljs b/src/main/logseq/cli/root_dir.cljs
new file mode 100644
index 0000000000..b78dc0a6d7
--- /dev/null
+++ b/src/main/logseq/cli/root_dir.cljs
@@ -0,0 +1,42 @@
+(ns logseq.cli.root-dir
+  "Root-dir validation and path derivation for the CLI and db-worker-node."
+  (:require ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]
+            [logseq.common.graph :as common-graph]))
+
+(defn default-root-dir
+  []
+  (node-path/join (.homedir os) "logseq"))
+
+(defn normalize-root-dir
+  [path]
+  (node-path/resolve (common-graph/expand-home (or path (default-root-dir)))))
+
+(defn graphs-dir
+  [root-dir]
+  (node-path/join (normalize-root-dir root-dir) "graphs"))
+
+(defn ensure-root-dir!
+  [path]
+  (let [path (normalize-root-dir path)]
+    (try
+      (when-not (fs/existsSync path)
+        (fs/mkdirSync path #js {:recursive true}))
+      (let [stat (fs/statSync path)]
+        (when-not (.isDirectory stat)
+          (throw (ex-info (str "root-dir is not a directory: " path)
+                          {:code :root-dir-permission
+                           :path path
+                           :cause "ENOTDIR"}))))
+      (let [constants (.-constants fs)
+            mode (bit-or (.-R_OK constants) (.-W_OK constants))]
+        (fs/accessSync path mode))
+      path
+      (catch :default e
+        (if (= :root-dir-permission (:code (ex-data e)))
+          (throw e)
+          (throw (ex-info (str "root-dir is not readable/writable: " path)
+                          {:code :root-dir-permission
+                           :path path
+                           :cause (.-code e)})))))))
diff --git a/src/main/logseq/cli/server.cljs b/src/main/logseq/cli/server.cljs
new file mode 100644
index 0000000000..861723b427
--- /dev/null
+++ b/src/main/logseq/cli/server.cljs
@@ -0,0 +1,526 @@
+(ns logseq.cli.server
+  "db-worker-node lifecycle orchestration for logseq. Used by CLI and electron"
+  (:require ["fs" :as fs]
+            ["path" :as node-path]
+            [clojure.string :as string]
+            [frontend.worker.db-worker-node-lock :as db-lock]
+            [lambdaisland.glogi :as log]
+            [logseq.cli.profile :as profile]
+            [logseq.cli.root-dir :as root-dir]
+            [logseq.common.config :as common-config]
+            [logseq.common.graph :as common-graph]
+            [logseq.common.graph-dir :as graph-dir]
+            [logseq.db-worker.daemon :as daemon]
+            [logseq.db-worker.server-list :as server-list]
+            [promesa.core :as p]))
+
+(defn resolve-root-dir
+  [config]
+  (common-graph/expand-home (or (:root-dir config) "~/logseq")))
+
+(defn graphs-dir
+  [config]
+  (root-dir/graphs-dir (resolve-root-dir config)))
+
+(defn- repo-dir
+  [root-dir repo]
+  (db-lock/repo-dir (root-dir/graphs-dir root-dir) repo))
+
+(defn- ensure-repo-dir!
+  [root-dir repo]
+  (let [path (repo-dir root-dir repo)]
+    (try
+      (when-not (fs/existsSync path)
+        (fs/mkdirSync path #js {:recursive true}))
+      (let [stat (fs/statSync path)]
+        (when-not (.isDirectory stat)
+          (throw (ex-info (str "graph-dir is not a directory: " path)
+                          {:code :root-dir-permission
+                           :path path
+                           :cause "ENOTDIR"}))))
+      (let [constants (.-constants fs)
+            mode (bit-or (.-R_OK constants) (.-W_OK constants))]
+        (fs/accessSync path mode))
+      path
+      (catch :default e
+        (throw (ex-info (str "graph-dir is not readable/writable: " path)
+                        {:code :root-dir-permission
+                         :path path
+                         :cause (.-code e)}))))))
+
+(defn lock-path
+  [root-dir repo]
+  (db-lock/lock-path root-dir repo))
+
+(defn- server-list-path
+  [config]
+  (server-list/path (resolve-root-dir config)))
+
+(defn db-worker-dev-script-path
+  []
+  (node-path/join js/__dirname "../static/db-worker-node.js"))
+
+(defn db-worker-script-path
+  []
+  (if goog.DEBUG
+    (db-worker-dev-script-path)
+    (node-path/join js/__dirname "../dist/db-worker-node.js")))
+
+(defn db-worker-runtime-script-path
+  []
+  (db-worker-script-path))
+
+(defn- base-url
+  [{:keys [host port]}]
+  (str "http://" host ":" port))
+
+(defn- normalize-owner-source
+  [owner-source]
+  (daemon/normalize-owner-source owner-source))
+
+(defn- requester-owner-source
+  [config]
+  (normalize-owner-source (or (:owner-source config) :cli)))
+
+(defn- lock-owner-source
+  [lock]
+  (normalize-owner-source (:owner-source lock)))
+
+(defn- owner-manageable?
+  [requester-owner lock-owner]
+  (or (= requester-owner lock-owner)
+      (and (= requester-owner :cli)
+           (= lock-owner :unknown))))
+
+(defn- owner-mismatch-error
+  [repo requester-owner lock-owner]
+  {:ok? false
+   :error {:code :server-owned-by-other
+           :message "server is owned by another process"
+           :repo repo
+           :owner-source lock-owner
+           :requester-owner-source requester-owner}})
+
+(defn- pid-status
+  [pid]
+  (daemon/pid-status pid))
+
+(defn- read-lock
+  [path]
+  (daemon/read-lock path))
+
+(defn- remove-lock!
+  [path]
+  (daemon/remove-lock! path))
+
+(defn- http-request
+  [opts]
+  (daemon/http-request opts))
+
+(defn- cleanup-stale-lock!
+  [path lock]
+  (daemon/cleanup-stale-lock! path lock))
+
+(defn- wait-for
+  [pred-fn opts]
+  (daemon/wait-for pred-fn opts))
+
+(defn- wait-for-lock
+  [path]
+  (daemon/wait-for-lock path))
+
+(defn- wait-for-ready
+  [lock]
+  (daemon/wait-for-ready lock))
+
+(defn- fetch-healthz
+  [{:keys [host port]}]
+  (p/let [{:keys [status body]} (http-request {:method "GET"
+                                               :host host
+                                               :port port
+                                               :path "/healthz"
+                                               :timeout-ms 1000})
+          payload (js->clj (js/JSON.parse body) :keywordize-keys true)]
+    (assoc payload :http-status status)))
+
+(defn- spawn-server!
+  [{:keys [repo root-dir owner-source create-empty-db?]}]
+  (daemon/spawn-server! {:script (db-worker-script-path)
+                         :repo repo
+                         :root-dir root-dir
+                         :owner-source owner-source
+                         :create-empty-db? create-empty-db?}))
+
+(defn- rewrite-lock-owner-source!
+  [path lock owner-source]
+  (let [lock' (assoc lock :owner-source (normalize-owner-source owner-source))]
+    (fs/writeFileSync path (js/JSON.stringify (clj->js lock')))
+    lock'))
+
+(defn- canonical-path
+  [path]
+  (when (seq path)
+    (let [path (common-graph/expand-home path)]
+      (try
+        (fs/realpathSync path)
+        (catch :default _
+          (node-path/resolve path))))))
+
+(defn- current-root-dir
+  [config]
+  (canonical-path (resolve-root-dir config)))
+
+(defn- same-root-dir?
+  [config server]
+  (let [server-root-dir (:root-dir server)]
+    (or (not (seq server-root-dir))
+        (= (current-root-dir config)
+           (canonical-path server-root-dir)))))
+
+(defn- servers-for-config
+  [config servers]
+  (->> (or servers [])
+       (filter #(same-root-dir? config %))
+       vec))
+
+(defn- repo-server
+  [config servers repo]
+  (first (filter #(= repo (:repo %))
+                 (servers-for-config config servers))))
+
+(defn discover-servers
+  [config]
+  (let [path (server-list-path config)
+        entries (server-list/read-entries path)]
+    (p/let [results (p/all
+                     (for [{:keys [pid port] :as entry} entries]
+                       (p/let [pid-state (pid-status pid)]
+                         (if-not (contains? #{:alive :no-permission} pid-state)
+                           {:entry entry :retain? false}
+                           (-> (fetch-healthz {:host "127.0.0.1" :port port})
+                               (p/then (fn [payload]
+                                         {:entry entry
+                                          :retain? true
+                                          :server (-> payload
+                                                      (update :status keyword)
+                                                      (update :owner-source normalize-owner-source))}))
+                               (p/catch (fn [_]
+                                          {:entry entry :retain? true})))))))
+            retained-results (filter :retain? results)
+            cleaned-entries (mapv :entry retained-results)
+            _ (server-list/rewrite-entries! path cleaned-entries)]
+      (->> retained-results
+           (keep :server)
+           vec))))
+
+(defn- wait-for-discovered-server
+  [config repo]
+  (let [server* (atom nil)]
+    (-> (wait-for (fn []
+                    (p/let [servers (discover-servers config)
+                            server (repo-server config servers repo)]
+                      (reset! server* server)
+                      (some? server)))
+                  {:timeout-ms 8000
+                   :interval-ms 50})
+        (p/then (fn [_] @server*)))))
+
+(defn- ensure-server-started!
+  [config repo]
+  (let [root-dir (resolve-root-dir config)
+        path (lock-path root-dir repo)
+        requester-owner (requester-owner-source config)
+        profile-session (:profile-session config)]
+    (profile/time! profile-session "server.ensure-started"
+                   (fn []
+                     (ensure-repo-dir! root-dir repo)
+                     (p/let [existing (read-lock path)
+                             _ (cleanup-stale-lock! path existing)
+                             discovered (discover-servers config)
+                             discovered-repo-server (repo-server config discovered repo)
+                             _ (when (and (not discovered-repo-server) (not (fs/existsSync path)))
+                                 (profile/time! profile-session
+                                                "server.spawn-daemon"
+                                                (fn []
+                                                  (spawn-server! {:repo repo
+                                                                  :root-dir root-dir
+                                                                  :owner-source requester-owner
+                                                                  :create-empty-db? (:create-empty-db? config)})))
+                                 (-> (profile/time! profile-session
+                                                    "server.wait-lock"
+                                                    (fn []
+                                                      (wait-for-lock path)))
+                                     (p/catch (fn [e]
+                                                (if (= :timeout (:code (ex-data e)))
+                                                  (throw (ex-info "db-worker-node failed to create lock"
+                                                                  {:code :server-start-timeout-orphan
+                                                                   :repo repo}))
+                                                  (throw e))))))
+                             lock (read-lock path)
+                             lock (if (and lock
+                                           (= :cli requester-owner)
+                                           (= :unknown (lock-owner-source lock)))
+                                    (rewrite-lock-owner-source! path lock :cli)
+                                    lock)
+                             repo-server' (if discovered-repo-server
+                                            discovered-repo-server
+                                            (-> (profile/time! profile-session
+                                                               "server.wait-publish"
+                                                               (fn []
+                                                                 (wait-for-discovered-server config repo)))
+                                                (p/catch (fn [e]
+                                                           (if (= :timeout (:code (ex-data e)))
+                                                             (throw (ex-info "db-worker-node failed to publish health"
+                                                                             {:code :server-start-failed
+                                                                              :repo repo}))
+                                                             (throw e))))))]
+                       (when-not lock
+                         (throw (ex-info "db-worker-node failed to start" {:code :server-start-failed})))
+                       (p/let [_ (profile/time! profile-session
+                                                "server.wait-ready"
+                                                (fn []
+                                                  (wait-for-ready repo-server')))]
+                         (let [lock-owner (lock-owner-source lock)]
+                           (assoc repo-server'
+                                  :owner-source lock-owner
+                                  :owned? (owner-manageable? requester-owner lock-owner)))))))))
+
+(defn ensure-server!
+  [config repo]
+  (p/let [lock (ensure-server-started! config repo)]
+    (assoc config
+           :base-url (base-url lock)
+           :owner-source (:owner-source lock)
+           :owned? (:owned? lock))))
+
+(defn- shutdown!
+  [{:keys [host port]}]
+  (p/let [{:keys [status]} (http-request {:method "POST"
+                                          :host host
+                                          :port port
+                                          :path "/v1/shutdown"
+                                          :headers {"Content-Type" "application/json"}
+                                          :timeout-ms 1000})]
+    (= 200 status)))
+
+(defn stop-server!
+  [config repo]
+  (let [requester-owner (requester-owner-source config)
+        root-dir (resolve-root-dir config)
+        path (lock-path root-dir repo)
+        lock (read-lock path)]
+    (if-not lock
+      (p/resolved {:ok? false
+                   :error {:code :server-not-found
+                           :message "server is not running"}})
+      (let [lock-owner (lock-owner-source lock)]
+        (if-not (owner-manageable? requester-owner lock-owner)
+          (p/resolved (owner-mismatch-error repo requester-owner lock-owner))
+          (p/let [servers (discover-servers config)
+                  server (repo-server config servers repo)]
+            (if-not server
+              {:ok? false
+               :error {:code :server-not-found
+                       :message "server is not running"}}
+              (-> (p/let [_ (shutdown! server)]
+                    (wait-for (fn []
+                                (p/resolved (not (fs/existsSync path))))
+                              {:timeout-ms 5000
+                               :interval-ms 200})
+                    {:ok? true
+                     :data {:repo repo}})
+                  (p/catch
+                   (fn [_]
+                     (when (and (= :alive (pid-status (:pid server)))
+                                (not= (:pid server) (.-pid js/process)))
+                       (try
+                         (.kill js/process (:pid server) "SIGTERM")
+                         (catch :default e
+                           (log/warn :cli-server-stop-sigterm-failed e))))
+                     (when (= :not-found (pid-status (:pid server)))
+                       (remove-lock! path))
+                     (if (fs/existsSync path)
+                       {:ok? false
+                        :error {:code :server-stop-timeout
+                                :message "timed out stopping server"}}
+                       {:ok? true
+                        :data {:repo repo}})))))))))))
+
+(defn start-server!
+  [config repo]
+  (-> (p/let [lock (ensure-server-started! config repo)]
+        {:ok? true
+         :data {:repo repo
+                :owner-source (:owner-source lock)
+                :owned? (:owned? lock)}})
+      (p/catch (fn [e]
+                 (let [data (ex-data e)
+                       code (or (:code data) :server-start-failed)]
+                   {:ok? false
+                    :error (cond-> {:code code
+                                    :message (or (.-message e) "failed to start server")}
+                             (:lock data) (assoc :lock (:lock data))
+                             (:pids data) (assoc :pids (:pids data))
+                             (:repo data) (assoc :repo (:repo data)))})))))
+
+(defn restart-server!
+  [config repo]
+  (p/let [stop-result (stop-server! config repo)]
+    (if (:ok? stop-result)
+      (start-server! config repo)
+      (if (= :server-not-found (get-in stop-result [:error :code]))
+        (start-server! config repo)
+        stop-result))))
+
+(defn list-servers
+  [config]
+  (p/let [servers (discover-servers config)]
+    (servers-for-config config servers)))
+
+(defn compute-revision-mismatches
+  [cli-revision servers]
+  (let [mismatch-servers (->> (or servers [])
+                              (filter (fn [{:keys [revision]}]
+                                        (not= cli-revision revision)))
+                              (mapv (fn [{:keys [repo revision]}]
+                                      {:repo repo
+                                       :revision revision})))]
+    (when (seq mismatch-servers)
+      {:cli-revision cli-revision
+       :servers mismatch-servers})))
+
+(defn- cleanup-target
+  [{:keys [repo pid owner-source revision]}]
+  {:repo repo
+   :pid pid
+   :owner-source owner-source
+   :revision revision})
+
+(defn cleanup-revision-mismatched-servers!
+  [config cli-revision]
+  (p/let [servers (list-servers config)
+          mismatched (->> (or servers [])
+                          (filter (fn [{:keys [revision]}]
+                                    (not= cli-revision revision)))
+                          (vec))
+          eligible (->> mismatched
+                        (filter (fn [{:keys [owner-source]}]
+                                  (= :cli owner-source)))
+                        (vec))
+          skipped-owner-targets (->> mismatched
+                                     (remove (fn [{:keys [owner-source]}]
+                                               (= :cli owner-source)))
+                                     (mapv cleanup-target))
+          stop-results (p/all
+                        (for [server eligible]
+                          (p/let [target (cleanup-target server)
+                                  result (stop-server! (assoc config :owner-source :cli) (:repo server))]
+                            (cond
+                              (:ok? result)
+                              {:status :killed
+                               :target target}
+
+                              (= :server-not-found (get-in result [:error :code]))
+                              {:status :killed
+                               :target target}
+
+                              :else
+                              {:status :failed
+                               :target target
+                               :error (:error result)}))))
+          killed (->> stop-results
+                      (filter (fn [{:keys [status]}] (= :killed status)))
+                      (mapv :target))
+          failed (->> stop-results
+                      (filter (fn [{:keys [status]}] (= :failed status)))
+                      (mapv (fn [{:keys [target error]}]
+                              (assoc target :error error))))]
+    {:ok? true
+     :data {:cli-revision cli-revision
+            :checked (count (or servers []))
+            :mismatched (count mismatched)
+            :eligible (count eligible)
+            :skipped-owner (count skipped-owner-targets)
+            :skipped-owner-targets skipped-owner-targets
+            :killed killed
+            :failed failed}}))
+
+(def ^:private legacy-token-pattern #"(?:\+\+|\+3A\+|%)")
+
+(def ^:private backup-root-dir-name "backup")
+
+(defn- ignored-graph-dir?
+  [graph-name]
+  (or (= graph-name common-config/unlinked-graphs-dir)
+      (= graph-name backup-root-dir-name)
+      (string/starts-with? graph-name common-config/file-version-prefix)))
+
+(defn- legacy-derivation-signal?
+  [dir-name]
+  (and (string? dir-name)
+       (re-find legacy-token-pattern dir-name)))
+
+(defn- decode-legacy-graph-name
+  [legacy-dir]
+  (some-> (graph-dir/decode-legacy-graph-dir-name legacy-dir)
+          (#(when-not (ignored-graph-dir? %) %))))
+
+(defn- canonical-dir-name?
+  [dir-name graph-name]
+  (= dir-name (graph-dir/graph-dir-key->encoded-dir-name graph-name)))
+
+(defn- classify-graph-dir
+  [graphs-root dir-name]
+  (when-not (ignored-graph-dir? dir-name)
+    (let [decoded-canonical (db-lock/decode-canonical-graph-dir-key dir-name)
+          canonical? (and (seq decoded-canonical)
+                          (not (ignored-graph-dir? decoded-canonical))
+                          (canonical-dir-name? dir-name decoded-canonical))
+          legacy-graph-name (or (when (and (seq decoded-canonical)
+                                           (not canonical?))
+                                  decoded-canonical)
+                                (decode-legacy-graph-name dir-name))]
+      (cond
+        canonical?
+        {:kind :canonical
+         :graph-name decoded-canonical
+         :graph-dir dir-name}
+
+        (seq legacy-graph-name)
+        (let [target-graph-dir (graph-dir/graph-dir-key->encoded-dir-name legacy-graph-name)
+              conflict? (and (seq target-graph-dir)
+                             (not= target-graph-dir dir-name)
+                             (fs/existsSync (node-path/join graphs-root target-graph-dir)))]
+          {:kind :legacy
+           :legacy-dir dir-name
+           :legacy-graph-name legacy-graph-name
+           :target-graph-dir target-graph-dir
+           :conflict? conflict?})
+
+        (legacy-derivation-signal? dir-name)
+        {:kind :legacy-undecodable
+         :legacy-dir dir-name
+         :reason :graph-name-not-derivable}
+
+        :else
+        nil))))
+
+(defn list-graph-items
+  [config]
+  (let [graphs-root (graphs-dir config)
+        entries (when (fs/existsSync graphs-root)
+                  (fs/readdirSync graphs-root #js {:withFileTypes true}))]
+    (->> entries
+         (filter #(.isDirectory ^js %))
+         (map (fn [^js dirent]
+                (classify-graph-dir graphs-root (.-name dirent))))
+         (filter some?)
+         (vec))))
+
+(defn list-graphs
+  [config]
+  (->> (list-graph-items config)
+       (keep (fn [{:keys [kind graph-name]}]
+               (when (= :canonical kind)
+                 graph-name)))
+       (vec)))
diff --git a/src/main/logseq/cli/style.cljs b/src/main/logseq/cli/style.cljs
new file mode 100644
index 0000000000..239880285b
--- /dev/null
+++ b/src/main/logseq/cli/style.cljs
@@ -0,0 +1,78 @@
+(ns logseq.cli.style
+  "CLI styling helpers based on picocolors."
+  (:require ["picocolors" :as pc]
+            [clojure.string :as string]))
+
+(def ansi-pattern
+  #"\u001b\[[0-9;]*m")
+
+(def ^:private option-pattern
+  #"--[A-Za-z0-9][A-Za-z0-9-]*")
+
+(def ^:dynamic *color-enabled?*
+  nil)
+
+(defn- term-dumb?
+  []
+  (= "dumb" (some-> js/process .-env (aget "TERM"))))
+
+(defn- color-supported?
+  []
+  (and (some-> js/process .-stdout .-isTTY)
+       (.-isColorSupported pc)
+       (not (term-dumb?))))
+
+(defn- color-enabled?
+  []
+  (if (some? *color-enabled?*)
+    (boolean *color-enabled?*)
+    (color-supported?)))
+
+(defn- ->text
+  [value]
+  (if (nil? value)
+    ""
+    (str value)))
+
+(defn strip-ansi
+  [value]
+  (string/replace (or value "") ansi-pattern ""))
+
+(defn- colors
+  []
+  (.createColors pc (color-enabled?)))
+
+(defn- apply-style
+  [style-key value]
+  (let [text (->text value)]
+    (if (seq text)
+      (let [palette (colors)
+            style-fn (aget palette style-key)]
+        (if (fn? style-fn)
+          (style-fn text)
+          text))
+      text)))
+
+(defn bold [value] (apply-style "bold" value))
+(defn dim [value] (apply-style "dim" value))
+(defn red [value] (apply-style "red" value))
+(defn green [value] (apply-style "green" value))
+(defn yellow [value] (apply-style "yellow" value))
+(defn blue [value] (apply-style "blue" value))
+(defn magenta [value] (apply-style "magenta" value))
+(defn cyan [value] (apply-style "cyan" value))
+
+(defn bold-keywords
+  [value keywords]
+  (reduce (fn [acc word]
+            (let [pattern (js/RegExp. (str "\\b" word "\\b") "gi")]
+              (string/replace acc pattern (fn [match]
+                                            (bold match)))))
+          (->text value)
+          keywords))
+
+(defn bold-options
+  [value]
+  (let [text (->text value)]
+    (string/replace text option-pattern (fn [match]
+                                          (bold match)))))
diff --git a/src/main/logseq/cli/transport.cljs b/src/main/logseq/cli/transport.cljs
new file mode 100644
index 0000000000..fa7167729c
--- /dev/null
+++ b/src/main/logseq/cli/transport.cljs
@@ -0,0 +1,305 @@
+(ns logseq.cli.transport
+  "HTTP transport for communicating with db-worker-node."
+  (:require ["fs" :as fs]
+            ["http" :as http]
+            ["https" :as https]
+            [cljs.reader :as reader]
+            [clojure.string :as string]
+            [lambdaisland.glogi :as log]
+            [logseq.cli.log :as cli-log]
+            [logseq.cli.profile :as profile]
+            [logseq.db :as ldb]
+            [promesa.core :as p]))
+
+(defn- request-module
+  [^js parsed]
+  (if (= "https:" (.-protocol parsed))
+    https
+    http))
+
+(defn- base-headers
+  []
+  {"Content-Type" "application/json"
+   "Accept" "application/json"})
+
+(defn- request-port
+  [^js parsed]
+  (let [port (.-port parsed)]
+    (if (seq port)
+      port
+      (if (= "https:" (.-protocol parsed)) 443 80))))
+
+(defn- normalize-base-url
+  [base-url]
+  (let [base-url (some-> base-url str string/trim)]
+    (when-not (seq base-url)
+      (throw (ex-info "base-url is required" {:code :missing-base-url})))
+    (string/replace base-url #"/$" "")))
+
+(defn- <raw-request
+  [{:keys [method url headers body timeout-ms]}]
+  (p/create
+   (fn [resolve reject]
+     (let [parsed (js/URL. url)
+           module (request-module parsed)
+           timeout-ms (or timeout-ms 10000)
+           req (.request
+                module
+                #js {:method method
+                     :hostname (.-hostname parsed)
+                     :port (request-port parsed)
+                     :path (str (.-pathname parsed) (.-search parsed))
+                     :headers (clj->js headers)}
+                (fn [^js res]
+                  (let [chunks (array)]
+                    (.on res "data" (fn [chunk] (.push chunks chunk)))
+                    (.on res "end" (fn []
+                                     (let [buf (js/Buffer.concat chunks)]
+                                       (resolve {:status (.-statusCode res)
+                                                 :body (.toString buf "utf8")}))))
+                    (.on res "error" reject))))
+           timeout-id (js/setTimeout
+                       (fn []
+                         (.destroy req)
+                         (reject (ex-info "request timeout" {:code :timeout})))
+                       timeout-ms)]
+       (.on req "error" (fn [err]
+                          (js/clearTimeout timeout-id)
+                          (reject err)))
+       (when body
+         (.write req body))
+       (.end req)
+       (.on req "response" (fn [_]
+                             (js/clearTimeout timeout-id)))))))
+
+(defn- parse-json-body
+  [body]
+  (when (seq body)
+    (try
+      (js->clj (js/JSON.parse body) :keywordize-keys true)
+      (catch :default e
+        (if (instance? js/SyntaxError e)
+          nil
+          (throw e))))))
+
+(defn- normalize-error-code
+  [error-code]
+  (cond
+    (keyword? error-code) error-code
+    (string? error-code) (let [text (string/trim error-code)]
+                           (when (seq text)
+                             (keyword text)))
+    :else nil))
+
+(defn request
+  [{:keys [method url headers body timeout-ms]}]
+  (p/let [{:keys [body status] :as response}
+          (<raw-request {:method method
+                         :url url
+                         :headers headers
+                         :body body
+                         :timeout-ms timeout-ms})]
+    (if (<= 200 status 299)
+      response
+      (let [parsed (parse-json-body body)
+            api-message (get-in parsed [:error :message])
+            api-code (normalize-error-code (get-in parsed [:error :code]))
+            message (cond
+                      (seq api-message) api-message
+                      (seq body) (str "http request failed (" status ")\nhttp response: " body)
+                      :else (str "http request failed (" status ")"))]
+        (throw (ex-info message
+                        {:code (or api-code :http-error)
+                         :status status
+                         :body body}))))))
+
+(defn invoke
+  [{:keys [base-url timeout-ms profile-session]}
+   method direct-pass? args]
+  (let [base-url (normalize-base-url base-url)
+        method* (cond
+                  (keyword? method) (subs (str method) 1)
+                  (string? method) method
+                  (nil? method) nil
+                  :else (str method))]
+    (when-not (seq method*)
+      (throw (ex-info "invoke method is required" {:code :missing-invoke-method})))
+    (let [url (str base-url "/v1/invoke")
+          stage-key (str "transport.invoke:" method*)
+          start-ms (js/Date.now)
+          args-preview (cli-log/truncate-preview args)
+          payload (if direct-pass?
+                    {:method method*
+                     :directPass true
+                     :args args}
+                    {:method method*
+                     :directPass false
+                     :argsTransit (ldb/write-transit-str args)})
+          body (js/JSON.stringify (clj->js payload))]
+      (profile/time! profile-session stage-key
+                   (fn []
+                     (log/debug :event :cli.transport/invoke
+                                :method method*
+                                :direct-pass? direct-pass?
+                                :args args-preview
+                                :url url)
+                     (p/let [{:keys [body]} (request {:method "POST"
+                                                      :url url
+                                                      :headers (base-headers)
+                                                      :body body
+                                                      :timeout-ms timeout-ms})
+                             {:keys [result resultTransit]} (js->clj (js/JSON.parse body) :keywordize-keys true)]
+                       (if direct-pass?
+                         (let [response-preview (cli-log/truncate-preview result)]
+                           (log/debug :event :cli.transport/response
+                                      :method method*
+                                      :direct-pass? direct-pass?
+                                      :elapsed-ms (- (js/Date.now) start-ms)
+                                      :response response-preview)
+                           result)
+                         (let [decoded (ldb/read-transit-str resultTransit)
+                               response-preview (cli-log/truncate-preview decoded)]
+                           (log/debug :event :cli.transport/response
+                                      :method method*
+                                      :direct-pass? direct-pass?
+                                      :elapsed-ms (- (js/Date.now) start-ms)
+                                      :response response-preview)
+                           decoded))))))))
+
+(defn- decode-event
+  [{:keys [type payload]}]
+  (let [decoded (when (some? payload)
+                  (try
+                    (ldb/read-transit-str payload)
+                    (catch :default _
+                      payload)))]
+    (if (and (vector? decoded)
+             (= 2 (count decoded))
+             (keyword? (first decoded)))
+      [(first decoded) (second decoded)]
+      [(when type (keyword type)) decoded])))
+
+(defn- data-line
+  [event-text]
+  (some (fn [line]
+          (when (string/starts-with? line "data: ")
+            (subs line 6)))
+        (string/split-lines event-text)))
+
+(defn- ensure-event-handler
+  [on-event]
+  (when-not (fn? on-event)
+    (throw (ex-info "connect-events! handler must be a function"
+                    {:code :invalid-events-handler
+                     :handler-type (type on-event)})))
+  on-event)
+
+(defn- destroy-resource!
+  [^js resource label]
+  (when resource
+    (try
+      (.destroy resource)
+      (catch :default e
+        (log/debug :event :cli.transport/resource-destroy-failed
+                   :resource label
+                   :error e)))))
+
+(defn connect-events!
+  [{:keys [base-url]} on-event]
+  (let [handler (ensure-event-handler on-event)
+        url (js/URL. (str (normalize-base-url base-url) "/v1/events"))
+        buffer (atom "")
+        *req (atom nil)
+        *res (atom nil)
+        *closed? (atom false)
+        dispatch! (fn [event-text]
+                    (when-let [line (data-line event-text)]
+                      (try
+                        (let [event-map (js->clj (js/JSON.parse line) :keywordize-keys true)
+                              [event-type payload] (decode-event event-map)]
+                          (when (some? event-type)
+                            (handler event-type payload)))
+                        (catch :default e
+                          (log/debug :event :cli.transport/events-parse-failed
+                                     :error e
+                                     :line line)))))
+        consume-chunk! (fn [chunk]
+                         (swap! buffer str (.toString chunk "utf8"))
+                         (loop []
+                           (let [current @buffer
+                                 idx (string/index-of current "\n\n")]
+                             (when (some? idx)
+                               (let [event-text (subs current 0 idx)
+                                     rest-text (subs current (+ idx 2))]
+                                 (reset! buffer rest-text)
+                                 (dispatch! event-text)
+                                 (recur))))))
+        close! (fn []
+                 (reset! *closed? true)
+                 (destroy-resource! @*res :response)
+                 (destroy-resource! @*req :request)
+                 nil)]
+    (try
+      (let [req (.request
+                 (request-module url)
+                 #js {:method "GET"
+                      :hostname (.-hostname url)
+                      :port (request-port url)
+                      :path (str (.-pathname url) (.-search url))
+                      :headers (clj->js {"Accept" "text/event-stream"})}
+                 (fn [^js res]
+                   (reset! *res res)
+                   (.on res "data"
+                        (fn [chunk]
+                          (when-not @*closed?
+                            (consume-chunk! chunk))))
+                   (.on res "error"
+                        (fn [e]
+                          (when-not @*closed?
+                            (log/debug :event :cli.transport/events-stream-error
+                                       :error e))))))]
+        (reset! *req req)
+        (.on req "error"
+             (fn [e]
+               (when-not @*closed?
+                 (log/debug :event :cli.transport/events-request-error
+                            :error e))))
+        (.end req))
+      (catch :default e
+        (log/debug :event :cli.transport/events-connect-failed
+                   :error e)))
+    {:close! close!}))
+
+(defn write-output
+  [{:keys [format path data]}]
+  (case format
+    :edn
+    (fs/writeFileSync path (pr-str data))
+
+    :db
+    (let [buffer (if (instance? js/Buffer data)
+                   data
+                   (js/Buffer.from data))]
+      (fs/writeFileSync path buffer))
+
+    :sqlite
+    (let [buffer (if (instance? js/Buffer data)
+                   data
+                   (js/Buffer.from data))]
+      (fs/writeFileSync path buffer))
+
+    (throw (ex-info "unsupported output format" {:format format}))))
+
+(defn read-input
+  [{:keys [format path]}]
+  (case format
+    :edn
+    (reader/read-string (.toString (fs/readFileSync path) "utf8"))
+
+    :db
+    (fs/readFileSync path)
+
+    :sqlite
+    (fs/readFileSync path)
+
+    (throw (ex-info "unsupported input format" {:format format}))))
diff --git a/src/main/logseq/cli/version.cljs b/src/main/logseq/cli/version.cljs
new file mode 100644
index 0000000000..669de1dbf0
--- /dev/null
+++ b/src/main/logseq/cli/version.cljs
@@ -0,0 +1,18 @@
+(ns logseq.cli.version
+  "Build metadata for logseq-cli.")
+
+(goog-define BUILD_TIME "unknown")
+(goog-define REVISION "dev")
+
+(defn build-time
+  []
+  BUILD_TIME)
+
+(defn revision
+  []
+  REVISION)
+
+(defn format-version
+  []
+  (str "Build time: " (build-time) "\n"
+       "Revision: " (revision)))
diff --git a/src/main/logseq/db_worker/daemon.cljs b/src/main/logseq/db_worker/daemon.cljs
new file mode 100644
index 0000000000..1c56785e63
--- /dev/null
+++ b/src/main/logseq/db_worker/daemon.cljs
@@ -0,0 +1,241 @@
+(ns logseq.db-worker.daemon
+  "Shared db-worker-node lifecycle helpers for CLI and Electron."
+  (:require ["child_process" :as child-process]
+            ["fs" :as fs]
+            ["http" :as http]
+            [clojure.string :as string]
+            [lambdaisland.glogi :as log]
+            [promesa.core :as p]))
+
+(def ^:private valid-owner-sources
+  #{:cli :electron :unknown})
+
+(defn normalize-owner-source
+  [owner-source]
+  (let [owner-source (cond
+                       (keyword? owner-source) owner-source
+                       (string? owner-source) (keyword (string/trim owner-source))
+                       :else :unknown)]
+    (if (contains? valid-owner-sources owner-source)
+      owner-source
+      :unknown)))
+
+(defn pid-status
+  [pid]
+  (when (number? pid)
+    (try
+      (.kill js/process pid 0)
+      :alive
+      (catch :default e
+        (case (.-code e)
+          "ESRCH" :not-found
+          "EPERM" :no-permission
+          :error)))))
+
+(defn read-lock
+  [path]
+  (when (and (seq path) (fs/existsSync path))
+    (let [lock (js->clj (js/JSON.parse (.toString (fs/readFileSync path) "utf8"))
+                        :keywordize-keys true)]
+      (assoc lock :owner-source (normalize-owner-source (:owner-source lock))))))
+
+(defn remove-lock!
+  [path]
+  (when (and (seq path) (fs/existsSync path))
+    (fs/unlinkSync path)))
+
+(defn http-request
+  [{:keys [method host port path headers body timeout-ms]}]
+  (p/create
+   (fn [resolve reject]
+     (let [timeout-ms (or timeout-ms 5000)
+           start-ms (js/Date.now)
+           req (.request
+                http
+                #js {:method method
+                     :hostname host
+                     :port port
+                     :path path
+                     :headers (clj->js (or headers {}))}
+                (fn [^js res]
+                  (let [chunks (array)]
+                    (.on res "data" (fn [chunk] (.push chunks chunk)))
+                    (.on res "end" (fn []
+                                     (let [buf (js/Buffer.concat chunks)]
+                                       (resolve {:status (.-statusCode res)
+                                                 :body (.toString buf "utf8")
+                                                 :elapsed-ms (- (js/Date.now) start-ms)}))))
+                    (.on res "error" reject))))
+           timeout-id (js/setTimeout
+                       (fn []
+                         (.destroy req)
+                         (reject (ex-info "request timeout" {:code :timeout})))
+                       timeout-ms)]
+       (.on req "error" (fn [err]
+                          (js/clearTimeout timeout-id)
+                          (reject err)))
+       (when body
+         (.write req body))
+       (.end req)
+       (.on req "response" (fn [_]
+                             (js/clearTimeout timeout-id)))))))
+
+(defn ready?
+  [{:keys [host port]}]
+  (-> (p/let [{:keys [status]} (http-request {:method "GET"
+                                              :host host
+                                              :port port
+                                              :path "/healthz"
+                                              :timeout-ms 1000})]
+        (= 200 status))
+      (p/catch (fn [_] false))))
+
+(defn healthy?
+  [{:keys [host port]}]
+  (-> (p/let [{:keys [status]} (http-request {:method "GET"
+                                              :host host
+                                              :port port
+                                              :path "/healthz"
+                                              :timeout-ms 1000})]
+        (contains? #{200 503} status))
+      (p/catch (fn [_] false))))
+
+(defn valid-lock?
+  [lock]
+  (and (seq (:repo lock))
+       (number? (:pid lock))
+       (seq (:lock-id lock))))
+
+(declare wait-for)
+
+(defn- process-stopped?
+  [pid]
+  (not (contains? #{:alive :no-permission} (pid-status pid))))
+
+(defn- terminate-process!
+  [pid force?]
+  (if (= "win32" (.-platform js/process))
+    (let [args (cond-> ["/PID" (str pid) "/T"]
+                 force? (conj "/F"))]
+      (try
+        (let [result (.spawnSync child-process "taskkill" (clj->js args)
+                                 #js {:windowsHide true
+                                      :stdio "ignore"})]
+          (if (or (= 0 (.-status result))
+                  (process-stopped? pid))
+            (p/resolved nil)
+            (p/rejected (ex-info "taskkill failed"
+                                 {:code :taskkill-failed
+                                  :pid pid
+                                  :force? force?}))))
+        (catch :default e
+          (p/rejected e))))
+    (try
+      (.kill js/process pid (if force? "SIGKILL" "SIGTERM"))
+      (p/resolved nil)
+      (catch :default e
+        (p/rejected e)))))
+
+(defn- wait-for-process-stop!
+  [pid timeout-ms]
+  (wait-for (fn [] (p/resolved (process-stopped? pid)))
+            {:timeout-ms timeout-ms
+             :interval-ms 100}))
+
+(defn- stop-stale-process!
+  [{:keys [pid]}]
+  (cond
+    (not (number? pid))
+    (p/resolved nil)
+
+    (= pid (.-pid js/process))
+    (p/resolved nil)
+
+    (process-stopped? pid)
+    (p/resolved nil)
+
+    :else
+    (-> (p/do!
+         (-> (terminate-process! pid false)
+             (p/catch (fn [e]
+                        (log/warn :db-worker-daemon/stale-process-stop-failed
+                                  {:pid pid :force? false :error e})
+                        (p/resolved nil))))
+         (wait-for-process-stop! pid 5000))
+        (p/catch (fn [_]
+                   (-> (terminate-process! pid true)
+                       (p/catch (fn [e]
+                                  (log/warn :db-worker-daemon/stale-process-stop-failed
+                                            {:pid pid :force? true :error e})
+                                  (p/resolved nil))))
+                   (-> (wait-for-process-stop! pid 1000)
+                       (p/catch (fn [_] nil))))))))
+
+(defn cleanup-stale-lock!
+  [path lock]
+  (cond
+    (nil? lock)
+    (p/resolved nil)
+
+    (= :not-found (pid-status (:pid lock)))
+    (do
+      (remove-lock! path)
+      (p/resolved nil))
+
+    (not (valid-lock? lock))
+    (-> (stop-stale-process! lock)
+        (p/then (fn [_]
+                  (remove-lock! path)
+                  nil)))
+
+    :else
+    (p/resolved nil)))
+
+(defn wait-for
+  [pred-fn {:keys [timeout-ms interval-ms]
+            :or {timeout-ms 8000
+                 interval-ms 50}}]
+  (p/create
+   (fn [resolve reject]
+     (let [start (js/Date.now)
+           tick (fn tick []
+                  (p/let [ok? (pred-fn)]
+                    (if ok?
+                      (resolve true)
+                      (if (> (- (js/Date.now) start) timeout-ms)
+                        (reject (ex-info "timeout" {:code :timeout}))
+                        (js/setTimeout tick interval-ms)))))]
+       (tick)))))
+
+(defn wait-for-lock
+  [path]
+  (wait-for (fn []
+              (p/resolved (fs/existsSync path)))
+            {:timeout-ms 8000
+             :interval-ms 50}))
+
+(defn wait-for-ready
+  [lock]
+  (wait-for (fn [] (ready? lock))
+            {:timeout-ms 8000
+             :interval-ms 50}))
+
+(defn spawn-server!
+  [{:keys [script repo root-dir owner-source create-empty-db?]}]
+  (let [owner-source (normalize-owner-source owner-source)
+        detached? (not= owner-source :electron)
+        args (clj->js (cond-> [script "--repo" repo "--root-dir" root-dir "--owner-source" (name owner-source)]
+                        create-empty-db? (conj "--create-empty-db")))
+        env (js/Object.assign #js {} (.-env js/process) #js {:ELECTRON_RUN_AS_NODE "1"})]
+    (if-not script
+      (do
+        (log/warn :db-worker-daemon/missing-script {:repo repo :root-dir root-dir})
+        nil)
+      (let [child (.spawn child-process (.-execPath js/process) args #js {:detached detached?
+                                                                          :stdio (if detached?
+                                                                                   "ignore"
+                                                                                   "inherit")
+                                                                          :env env})]
+        (when detached?
+          (.unref child))
+        child))))
diff --git a/src/main/logseq/db_worker/server_list.cljs b/src/main/logseq/db_worker/server_list.cljs
new file mode 100644
index 0000000000..c4cbd0bb18
--- /dev/null
+++ b/src/main/logseq/db_worker/server_list.cljs
@@ -0,0 +1,65 @@
+(ns logseq.db-worker.server-list
+  "Helpers for the centralized db-worker-node server-list file."
+  (:require [clojure.string :as string]
+            ["fs" :as fs]
+            ["path" :as node-path]))
+
+(defn path
+  [root-dir-path]
+  (when-not (seq root-dir-path)
+    (throw (js/Error. "root-dir is required")))
+  (node-path/join root-dir-path "server-list"))
+
+(defn- parse-int
+  [value]
+  (when (re-matches #"\d+" value)
+    (js/parseInt value 10)))
+
+(defn parse-line
+  [line]
+  (when (string? line)
+    (let [trimmed (string/trim line)]
+      (when-let [[_ pid-str port-str] (re-matches #"(\d+)\s+(\d+)" trimmed)]
+        (let [pid (parse-int pid-str)
+              port (parse-int port-str)]
+          (when (and (pos-int? pid) (pos-int? port))
+            {:pid pid
+             :port port}))))))
+
+(defn read-entries
+  [file-path]
+  (if (and (seq file-path) (fs/existsSync file-path))
+    (->> (.toString (fs/readFileSync file-path) "utf8")
+         string/split-lines
+         (keep parse-line)
+         vec)
+    []))
+
+(defn rewrite-entries!
+  [file-path entries]
+  (when (seq file-path)
+    (fs/mkdirSync (node-path/dirname file-path) #js {:recursive true})
+    (let [payload (if (seq entries)
+                    (str (string/join "\n" (map (fn [{:keys [pid port]}]
+                                                     (str pid " " port))
+                                                   entries))
+                         "\n")
+                    "")]
+      (fs/writeFileSync file-path payload "utf8"))))
+
+(defn append-entry!
+  [file-path {:keys [pid port] :as entry}]
+  (when (and (seq file-path) (pos-int? pid) (pos-int? port))
+    (fs/mkdirSync (node-path/dirname file-path) #js {:recursive true})
+    (fs/appendFileSync file-path (str pid " " port "\n") "utf8")
+    entry))
+
+(defn remove-entry!
+  [file-path {:keys [pid port]}]
+  (when (seq file-path)
+    (let [entries (->> (read-entries file-path)
+                       (remove (fn [entry]
+                                 (and (= pid (:pid entry))
+                                      (= port (:port entry)))))
+                       vec)]
+      (rewrite-entries! file-path entries))))
diff --git a/src/test/electron/db_test.cljs b/src/test/electron/db_test.cljs
new file mode 100644
index 0000000000..3e0fed732e
--- /dev/null
+++ b/src/test/electron/db_test.cljs
@@ -0,0 +1,149 @@
+(ns electron.db-test
+  (:require ["node:sqlite" :as node-sqlite]
+            [cljs.test :refer [async deftest is]]
+            [electron.backup-file :as backup-file]
+            [electron.db :as electron-db]
+            [frontend.test.node-helper :as node-helper]
+            [goog.object :as gobj]
+            [logseq.cli.common.graph :as cli-common-graph]
+            [logseq.db.common.sqlite :as common-sqlite]
+            [logseq.db.sqlite.backup :as sqlite-backup]
+            [promesa.core :as p]
+            ["fs-extra" :as fs]
+            ["path" :as node-path]))
+
+(defn- resolve-database-sync-ctor
+  []
+  (or (gobj/get node-sqlite "DatabaseSync")
+      (some-> (gobj/get node-sqlite "default")
+              (gobj/get "DatabaseSync"))
+      (let [default-export (gobj/get node-sqlite "default")]
+        (when (fn? default-export)
+          default-export))))
+
+(deftest ensure-graph-dir-uses-encoded-directory-name
+  (let [graphs-dir (node-helper/create-tmp-dir "electron-db-graph-dir")]
+    (with-redefs [cli-common-graph/get-db-graphs-dir (fn [] graphs-dir)]
+      (let [graph-dir (electron-db/ensure-graph-dir! "logseq_db_foo/bar")]
+        (is (= (node-path/join graphs-dir "foo~2Fbar") graph-dir))
+        (is (fs/existsSync graph-dir))))))
+
+(deftest read-db-uses-encoded-directory-name
+  (let [graphs-dir (node-helper/create-tmp-dir "electron-db-save")
+        payload (.from js/Buffer "db-data")
+        db-name "logseq_db_foo/bar"]
+    (with-redefs [cli-common-graph/get-db-graphs-dir (fn [] graphs-dir)]
+      (let [[_ db-path] (common-sqlite/get-db-full-path graphs-dir db-name)]
+        (fs/ensureDirSync (node-path/dirname db-path))
+        (fs/writeFileSync db-path payload))
+      (is (fs/existsSync (node-path/join graphs-dir "foo~2Fbar" "db.sqlite")))
+      (is (= "db-data"
+             (.toString (electron-db/get-db db-name)))))))
+
+(deftest backup-db-creates-sqlite-copy-from-existing-disk-db
+  (async done
+    (let [graphs-dir (node-helper/create-tmp-dir "electron-db-backup")
+          db-name "logseq_db_foo/bar"
+          DatabaseSync (resolve-database-sync-ctor)
+          original-get-db-graphs-dir cli-common-graph/get-db-graphs-dir]
+      (set! cli-common-graph/get-db-graphs-dir (fn [] graphs-dir))
+      (let [[_ db-path] (common-sqlite/get-db-full-path graphs-dir db-name)
+            backups-path (common-sqlite/get-db-backups-path graphs-dir db-name)]
+        (fs/ensureDirSync (node-path/dirname db-path))
+        (let [source-db (new DatabaseSync db-path)]
+          (.exec source-db "create table kvs (addr text primary key, content text);")
+          (.exec source-db "insert into kvs (addr, content) values ('a', 'alpha')")
+          (.close source-db))
+        (-> (p/with-redefs [backup-file/backup-file (fn [_repo _dir _relative-path _ext content & {:keys [backups-dir]}]
+                                                      (fs/ensureDirSync backups-dir)
+                                                      (fs/writeFileSync (node-path/join backups-dir "copy.sqlite") content))]
+              (p/let [_ (electron-db/backup-db! db-name nil)
+                    backup-files (vec (fs/readdirSync backups-path))
+                    backup-path (node-path/join backups-path (first backup-files))
+                    backup-db (new DatabaseSync backup-path)
+                    stmt (.prepare ^js backup-db "select addr, content from kvs order by addr")
+                    rows (.all stmt)
+                    _ (.close backup-db)]
+                (is (= 1 (count backup-files)))
+                (is (= "a" (gobj/get (first rows) "addr")))
+                (is (= "alpha" (gobj/get (first rows) "content")))))
+            (p/catch (fn [e]
+                       (is false (str "unexpected error: " e))))
+            (p/finally (fn []
+                         (set! cli-common-graph/get-db-graphs-dir original-get-db-graphs-dir)
+                         (done))))))))
+
+(deftest backup-db-uses-backup-file-rules
+  (async done
+    (let [graphs-dir (node-helper/create-tmp-dir "electron-db-backup-rules")
+          db-name "logseq_db_demo"
+          [_ db-path] (common-sqlite/get-db-full-path graphs-dir db-name)
+          backups-path (common-sqlite/get-db-backups-path graphs-dir db-name)
+          sqlite-calls (atom [])
+          backup-calls (atom [])]
+      (fs/ensureDirSync (node-path/dirname db-path))
+      (fs/writeFileSync db-path "seed")
+      (-> (p/with-redefs [cli-common-graph/get-db-graphs-dir (fn [] graphs-dir)
+                          sqlite-backup/backup-db-file! (fn [src dst]
+                                                          (swap! sqlite-calls conj [src dst])
+                                                          (fs/writeFileSync dst "copied")
+                                                          (p/resolved nil))
+                          backup-file/backup-file (fn [repo dir relative-path ext content & {:as opts}]
+                                                    (swap! backup-calls conj {:repo repo
+                                                                              :dir dir
+                                                                              :relative-path relative-path
+                                                                              :ext ext
+                                                                              :content (.toString content)
+                                                                              :opts opts})
+                                                    nil)]
+            (p/let [_ (electron-db/backup-db! db-name nil)]
+              (is (= 1 (count @sqlite-calls)))
+              (is (= db-path (first (first @sqlite-calls))))
+              (is (= 1 (count @backup-calls)))
+              (let [{:keys [repo dir relative-path ext content opts]} (first @backup-calls)]
+                (is (= db-name repo))
+                (is (= nil dir))
+                (is (= nil relative-path))
+                (is (= ".sqlite" ext))
+                (is (= "copied" content))
+                (is (= backups-path (:backups-dir opts)))
+                (is (= 12 (:keep-versions opts)))
+                (is (contains? opts :force-backup?))
+                (is (nil? (:force-backup? opts))))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest auto-backup-tracker-runs-hourly-for-active-repos
+  (async done
+    (let [set-interval-calls (atom [])
+          clear-interval-calls (atom [])
+          backup-calls (atom [])
+          timer-id #js {:id 1}
+          original-set-interval js/setInterval
+          original-clear-interval js/clearInterval]
+      (electron-db/reset-auto-backup!)
+      (set! js/setInterval (fn [f ms]
+                             (swap! set-interval-calls conj [f ms])
+                             timer-id))
+      (set! js/clearInterval (fn [id]
+                               (swap! clear-interval-calls conj id)))
+      (-> (p/with-redefs [electron-db/backup-db! (fn [repo _]
+                                                   (swap! backup-calls conj repo)
+                                                   (p/resolved nil))]
+            (p/let [_ (electron-db/sync-auto-backup-repo! 1 "logseq_db_demo")
+                    _ (electron-db/sync-auto-backup-repo! 2 "logseq_db_demo")
+                    _ ((ffirst @set-interval-calls))
+                    _ (electron-db/sync-auto-backup-repo! 1 nil)
+                    _ (electron-db/sync-auto-backup-repo! 2 nil)]
+              (is (= 1 (count @set-interval-calls)))
+              (is (= [timer-id] @clear-interval-calls))
+              (is (= [3600000] (mapv second @set-interval-calls)))
+              (is (= ["logseq_db_demo"] @backup-calls))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (set! js/setInterval original-set-interval)
+                       (set! js/clearInterval original-clear-interval)
+                       (electron-db/reset-auto-backup!)
+                       (done)))))))
diff --git a/src/test/electron/db_worker_manager_test.cljs b/src/test/electron/db_worker_manager_test.cljs
new file mode 100644
index 0000000000..5d4d37acad
--- /dev/null
+++ b/src/test/electron/db_worker_manager_test.cljs
@@ -0,0 +1,260 @@
+(ns electron.db-worker-manager-test
+  (:require [cljs.test :refer [async deftest is]]
+            [electron.db-worker :as db-worker]
+            [logseq.cli.server :as cli-server]
+            [promesa.core :as p]))
+
+(defn- runtime
+  [repo]
+  {:repo repo
+   :base-url (str "http://127.0.0.1/" repo)
+   :auth-token (str "token-" repo)})
+
+(deftest ensure-started-is-idempotent-for-same-window
+  (async done
+    (let [start-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo]
+                                     (swap! start-calls conj repo)
+                                     (p/resolved (runtime repo)))
+                    :stop-daemon! (fn [_] (p/resolved true))})]
+      (-> (p/let [a (db-worker/ensure-started! manager "graph-a" :window-1)
+                  b (db-worker/ensure-started! manager "graph-a" :window-1)]
+            (is (= 1 (count @start-calls)))
+            (is (= a b)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-started-reuses-daemon-across-windows
+  (async done
+    (let [start-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo]
+                                     (swap! start-calls conj repo)
+                                     (p/resolved (runtime repo)))
+                    :stop-daemon! (fn [_] (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-started! manager "graph-a" :window-2)]
+            (is (= ["graph-a"] @start-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-started-switches-window-repo-and-stops-previous-daemon
+  (async done
+    (let [start-calls (atom [])
+          stop-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo]
+                                     (swap! start-calls conj repo)
+                                     (p/resolved (runtime repo)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:repo rt))
+                                    (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-started! manager "graph-b" :window-1)]
+            (is (= ["graph-a" "graph-b"] @start-calls))
+            (is (= ["graph-a"] @stop-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-stopped-stops-only-on-last-window
+  (async done
+    (let [stop-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo] (p/resolved (runtime repo)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:repo rt))
+                                    (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-started! manager "graph-a" :window-2)
+                  _ (db-worker/ensure-stopped! manager "graph-a" :window-1)
+                  _ (is (empty? @stop-calls))
+                  _ (db-worker/ensure-stopped! manager "graph-a" :window-2)]
+            (is (= ["graph-a"] @stop-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-stopped-stale-repo-does-not-clear-new-window-mapping
+  (async done
+    (let [stop-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo] (p/resolved (runtime repo)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:repo rt))
+                                    (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-started! manager "graph-a" :window-2)
+                  _ (db-worker/ensure-started! manager "graph-b" :window-1)
+                  ;; simulate late/stale release for previous repo after window-1 already moved to graph-b
+                  _ (db-worker/ensure-stopped! manager "graph-a" :window-1)
+                  manager-state @(:state manager)]
+            (is (= "graph-b" (get-in manager-state [:window->repo :window-1])))
+            (is (= #{:window-2} (get-in manager-state [:repos "graph-a" :windows])))
+            (is (= #{:window-1} (get-in manager-state [:repos "graph-b" :windows])))
+            (is (empty? @stop-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-stopped-stale-intermediate-repo-after-switch-back-keeps-current-repo
+  (async done
+    (let [stop-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo] (p/resolved (runtime repo)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:repo rt))
+                                    (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-started! manager "graph-b" :window-1)
+                  _ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  ;; stale cleanup for graph-b arrives after the window is already back on graph-a
+                  _ (db-worker/ensure-stopped! manager "graph-b" :window-1)
+                  manager-state @(:state manager)]
+            (is (= "graph-a" (get-in manager-state [:window->repo :window-1])))
+            (is (= #{:window-1} (get-in manager-state [:repos "graph-a" :windows])))
+            (is (nil? (get-in manager-state [:repos "graph-b"])))
+            (is (= ["graph-a" "graph-b"] @stop-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-window-stopped-releases-active-runtime-by-window
+  (async done
+    (let [stop-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo] (p/resolved (runtime repo)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:repo rt))
+                                    (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-started! manager "graph-a" :window-2)
+                  _ (db-worker/ensure-window-stopped! manager :window-1)
+                  _ (is (empty? @stop-calls))
+                  _ (db-worker/ensure-window-stopped! manager :window-2)]
+            (is (= ["graph-a"] @stop-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest stop-all-stops-every-active-graph
+  (async done
+    (let [stop-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo] (p/resolved (runtime repo)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:repo rt))
+                                    (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-started! manager "graph-b" :window-2)
+                  _ (db-worker/stop-all! manager)]
+            (is (= #{"graph-a" "graph-b"} (set @stop-calls))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-started-restarts-unhealthy-cached-runtime
+  (async done
+    (let [start-count (atom 0)
+          stop-calls (atom [])
+          created-runtimes (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo]
+                                     (let [idx (swap! start-count inc)
+                                           rt {:repo repo
+                                               :base-url (str "http://127.0.0.1:910" idx)
+                                               :auth-token (str "token-" idx)}]
+                                       (swap! created-runtimes conj rt)
+                                       (p/resolved rt)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:base-url rt))
+                                    (p/resolved true))
+                    :runtime-ready? (fn [rt]
+                                      ;; first runtime reported unhealthy, restarted runtime healthy
+                                      (p/resolved (not= (:base-url rt) "http://127.0.0.1:9101")))})]
+      (-> (p/let [rt1 (db-worker/ensure-started! manager "graph-a" :window-1)
+                  rt2 (db-worker/ensure-started! manager "graph-a" :window-1)]
+            (is (= "http://127.0.0.1:9101" (:base-url rt1)))
+            (is (= "http://127.0.0.1:9102" (:base-url rt2)))
+            (is (= 2 @start-count))
+            (is (= ["http://127.0.0.1:9101"] @stop-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-window-stopped-does-not-stop-external-runtime
+  (async done
+    (let [stop-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo]
+                                     (p/resolved (assoc (runtime repo) :owned? false)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:repo rt))
+                                    (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-window-stopped! manager :window-1)]
+            (is (empty? @stop-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-repo-stopped-detaches-all-windows-and-stops-runtime-once
+  (async done
+    (let [stop-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo] (p/resolved (runtime repo)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:repo rt))
+                                    (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-started! manager "graph-a" :window-2)
+                  _ (db-worker/ensure-repo-stopped! manager "graph-a")
+                  state @(:state manager)]
+            (is (= ["graph-a"] @stop-calls))
+            (is (nil? (get-in state [:repos "graph-a"])))
+            (is (nil? (get-in state [:window->repo :window-1])))
+            (is (nil? (get-in state [:window->repo :window-2]))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest ensure-repo-stopped-skips-stop-for-external-runtime
+  (async done
+    (let [stop-calls (atom [])
+          manager (db-worker/create-manager
+                   {:start-daemon! (fn [repo]
+                                     (p/resolved (assoc (runtime repo) :owned? false)))
+                    :stop-daemon! (fn [rt]
+                                    (swap! stop-calls conj (:repo rt))
+                                    (p/resolved true))})]
+      (-> (p/let [_ (db-worker/ensure-started! manager "graph-a" :window-1)
+                  _ (db-worker/ensure-repo-stopped! manager "graph-a")
+                  state @(:state manager)]
+            (is (empty? @stop-calls))
+            (is (nil? (get-in state [:repos "graph-a"])))
+            (is (nil? (get-in state [:window->repo :window-1]))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest managed-daemon-start-uses-cli-shared-server-path-with-electron-owner
+  (async done
+    (let [captured (atom nil)]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                      (reset! captured {:config config
+                                                                        :repo repo})
+                                                      (p/resolved {:base-url "http://127.0.0.1:9300"
+                                                                   :owned? true}))]
+            ((get db-worker/manager :start-daemon!) "graph-a"))
+          (p/then (fn [runtime-info]
+                    (is (= "graph-a" (:repo @captured)))
+                    (is (= :electron (get-in @captured [:config :owner-source])))
+                    (is (nil? (get-in @captured [:config :server-list-file])))
+                    (is (= "http://127.0.0.1:9300" (:base-url runtime-info)))
+                    (is (= true (:owned? runtime-info)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
diff --git a/src/test/electron/graph_switch_flow_test.cljs b/src/test/electron/graph_switch_flow_test.cljs
new file mode 100644
index 0000000000..eebeb437ac
--- /dev/null
+++ b/src/test/electron/graph_switch_flow_test.cljs
@@ -0,0 +1,15 @@
+(ns electron.graph-switch-flow-test
+  (:require [cljs.test :refer [deftest is]]
+            [electron.graph-switch-flow :as graph-switch-flow]))
+
+(deftest set-current-graph-switch-does-not-release-runtime
+  (is (false?
+       (graph-switch-flow/release-runtime-on-set-current-graph?
+        {:previous-graph-path "graph-a"
+         :next-graph-path "graph-b"}))))
+
+(deftest set-current-graph-reselect-does-not-release-runtime
+  (is (false?
+       (graph-switch-flow/release-runtime-on-set-current-graph?
+        {:previous-graph-path "graph-a"
+         :next-graph-path "graph-a"}))))
diff --git a/src/test/electron/utils_test.cljs b/src/test/electron/utils_test.cljs
new file mode 100644
index 0000000000..0b2b778c5f
--- /dev/null
+++ b/src/test/electron/utils_test.cljs
@@ -0,0 +1 @@
+(ns electron.utils-test)
diff --git a/src/test/frontend/components/repo_test.cljs b/src/test/frontend/components/repo_test.cljs
index 66936f165d..bbc58f9ea6 100644
--- a/src/test/frontend/components/repo_test.cljs
+++ b/src/test/frontend/components/repo_test.cljs
@@ -12,16 +12,18 @@
 (deftest ensure-rsa-key-does-not-create-graph-test
   (async done
          (let [ensure-fn (ensure-rsa-key-fn)
-               db-worker-ops (atom [])
+               db-worker-calls (atom [])
                create-calls (atom 0)
                ensured-values (atom [])]
            (if-not ensure-fn
              (do
                (is false "missing ensure-e2ee-rsa-key-for-cloud!")
                (done))
-             (-> (p/with-redefs [state/<invoke-db-worker
-                                 (fn [op & _]
-                                   (swap! db-worker-ops conj op)
+             (-> (p/with-redefs [state/pub-event! (fn [_event]
+                                                    (p/resolved nil))
+                                 state/<invoke-db-worker
+                                 (fn [op & args]
+                                   (swap! db-worker-calls conj (into [op] args))
                                    (if (= op :thread-api/db-sync-ensure-user-rsa-keys)
                                      (p/resolved {:public-key "pk"})
                                      (p/resolved nil)))
@@ -38,9 +40,15 @@
                               (fn [value]
                                 (swap! ensured-values conj value))))
                  (p/then (fn [_]
-                           (is (= [:thread-api/set-db-sync-config
-                                   :thread-api/db-sync-ensure-user-rsa-keys]
-                                  @db-worker-ops))
+                           (let [[set-config-call ensure-call] @db-worker-calls
+                                 set-config (second set-config-call)]
+                             (is (= :thread-api/set-db-sync-config (first set-config-call)))
+                             (is (= :thread-api/db-sync-ensure-user-rsa-keys (first ensure-call)))
+                             (is (= true (:enabled? set-config)))
+                             (is (contains? set-config :ws-url))
+                             (is (contains? set-config :http-base))
+                             (is (not (contains? set-config :oauth-domain)))
+                             (is (not (contains? set-config :oauth-client-id))))
                            (is (= [true] @ensured-values))
                            (is (zero? @create-calls))
                            (done)))
@@ -51,16 +59,18 @@
 (deftest ensure-rsa-key-nil-result-does-not-create-graph-test
   (async done
          (let [ensure-fn (ensure-rsa-key-fn)
-               db-worker-ops (atom [])
+               db-worker-calls (atom [])
                create-calls (atom 0)
                ensured-values (atom [])]
            (if-not ensure-fn
              (do
                (is false "missing ensure-e2ee-rsa-key-for-cloud!")
                (done))
-             (-> (p/with-redefs [state/<invoke-db-worker
-                                 (fn [op & _]
-                                   (swap! db-worker-ops conj op)
+             (-> (p/with-redefs [state/pub-event! (fn [_event]
+                                                    (p/resolved nil))
+                                 state/<invoke-db-worker
+                                 (fn [op & args]
+                                   (swap! db-worker-calls conj (into [op] args))
                                    (p/resolved nil))
                                  repo-handler/new-db!
                                  (fn [& _]
@@ -75,9 +85,15 @@
                               (fn [value]
                                 (swap! ensured-values conj value))))
                  (p/then (fn [_]
-                           (is (= [:thread-api/set-db-sync-config
-                                   :thread-api/db-sync-ensure-user-rsa-keys]
-                                  @db-worker-ops))
+                           (let [[set-config-call ensure-call] @db-worker-calls
+                                 set-config (second set-config-call)]
+                             (is (= :thread-api/set-db-sync-config (first set-config-call)))
+                             (is (= :thread-api/db-sync-ensure-user-rsa-keys (first ensure-call)))
+                             (is (= true (:enabled? set-config)))
+                             (is (contains? set-config :ws-url))
+                             (is (contains? set-config :http-base))
+                             (is (not (contains? set-config :oauth-domain)))
+                             (is (not (contains? set-config :oauth-client-id))))
                            (is (= [false] @ensured-values))
                            (is (zero? @create-calls))
                            (done)))
diff --git a/src/test/frontend/config_test.cljs b/src/test/frontend/config_test.cljs
index cb140631ae..d1746f67f2 100644
--- a/src/test/frontend/config_test.cljs
+++ b/src/test/frontend/config_test.cljs
@@ -1,6 +1,13 @@
 (ns frontend.config-test
   (:require [cljs.test :refer [deftest is testing]]
-            [frontend.config :as config]))
+            [frontend.config :as config]
+            [frontend.state :as state]
+            [logseq.common.config :as common-config]))
+
+(deftest get-local-dir-uses-encoded-directory-name
+  (with-redefs [state/state (atom {:system/info {:home-dir "/tmp/home"}})]
+    (is (= "/tmp/home/logseq/graphs/foo~2Fbar"
+           (config/get-local-dir (str common-config/db-version-prefix "foo/bar"))))))
 
 (deftest custom-url->ws-url-test
   (testing "https URL becomes wss"
diff --git a/src/test/frontend/db/persist_test.cljs b/src/test/frontend/db/persist_test.cljs
new file mode 100644
index 0000000000..3be12d5d48
--- /dev/null
+++ b/src/test/frontend/db/persist_test.cljs
@@ -0,0 +1,54 @@
+(ns frontend.db.persist-test
+  (:require [cljs.test :refer [async deftest is]]
+            [electron.ipc :as ipc]
+            [frontend.db.persist :as db-persist]
+            [frontend.persist-db :as persist-db]
+            [frontend.util :as util]
+            [promesa.core :as p]))
+
+(deftest get-all-graphs-canonicalizes-db-prefixes-from-all-sources
+  (async done
+    (-> (p/with-redefs [persist-db/<list-db (fn []
+                                              (p/resolved [{:name "demo"}
+                                                           {:name "logseq_db_prefixed"}
+                                                           {:name "logseq_db_logseq_db_legacy"}
+                                                           {:name "logseq_db_logseq_local_local-only"}]))
+                        util/electron? (constantly true)
+                        ipc/ipc (fn [_channel]
+                                  (p/resolved #js ["logseq_db_remote"
+                                                   "logseq_db_logseq_db_remote-legacy"]))]
+          (p/let [graphs (db-persist/get-all-graphs)
+                  names (mapv :name graphs)]
+            (is (= #{"logseq_db_demo"
+                     "logseq_db_prefixed"
+                     "logseq_db_legacy"
+                     "logseq_db_remote"
+                     "logseq_db_remote-legacy"}
+                   (set names)))
+            (is (not-any? #(re-find #"^logseq_db_logseq_db_" %) names))
+            (is (not-any? #(re-find #"logseq_local_" %) names))))
+        (p/catch (fn [error]
+                   (is false (str error))))
+        (p/finally done))))
+
+(deftest delete-graph-on-electron-closes-db-before-ipc-and-skips-unsafe-delete
+  (async done
+    (let [call-log (atom [])]
+      (-> (p/with-redefs [util/electron? (constantly true)
+                          persist-db/<close-db (fn [graph]
+                                                 (swap! call-log conj [:close-db graph])
+                                                 (p/resolved nil))
+                          persist-db/<unsafe-delete (fn [graph]
+                                                      (swap! call-log conj [:unsafe-delete graph])
+                                                      (p/resolved nil))
+                          ipc/ipc (fn [channel graph]
+                                    (swap! call-log conj [:ipc channel graph])
+                                    (p/resolved nil))]
+            (p/let [_ (db-persist/delete-graph! "logseq_db_test")]
+              (is (= [[:close-db "logseq_db_test"]
+                      [:ipc "deleteGraph" "logseq_db_test"]]
+                     @call-log)
+                  "Should call <close-db then deleteGraph IPC, and never call <unsafe-delete")))
+          (p/catch (fn [error]
+                     (is false (str error))))
+          (p/finally done)))))
diff --git a/src/test/frontend/electron/ipc_test.cljs b/src/test/frontend/electron/ipc_test.cljs
new file mode 100644
index 0000000000..0163e86d4f
--- /dev/null
+++ b/src/test/frontend/electron/ipc_test.cljs
@@ -0,0 +1,46 @@
+(ns frontend.electron.ipc-test
+  (:require [cljs.test :refer [async deftest is]]
+            [electron.ipc :as ipc]
+            [frontend.util :as util]
+            [logseq.db.sqlite.util :as sqlite-util]
+            [promesa.core :as p]))
+
+(deftest ipc-uses-transit-json-for-main-channel
+  (async done
+    (let [payloads (atom [])
+          original-electron? util/electron?
+          original-apis (.-apis js/window)]
+      (set! util/electron? (constantly true))
+      (set! (.-apis js/window)
+            #js {:doAction (fn [payload]
+                             (swap! payloads conj payload)
+                             (js/Promise.resolve (sqlite-util/write-transit-str {:ok true})))})
+      (-> (p/let [result (ipc/ipc :db-worker-runtime "logseq_db_graph_a")]
+            (is (= 1 (count @payloads)))
+            (is (string? (first @payloads)))
+            (is (= [:db-worker-runtime "logseq_db_graph_a"]
+                   (vec (sqlite-util/read-transit-str (first @payloads)))))
+            (is (= {:ok true} result)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (set! util/electron? original-electron?)
+                       (set! (.-apis js/window) original-apis)
+                       (done)))))))
+
+(deftest ipc-keeps-non-string-response-unchanged
+  (async done
+    (let [original-electron? util/electron?
+          original-apis (.-apis js/window)]
+      (set! util/electron? (constantly true))
+      (set! (.-apis js/window)
+            #js {:doAction (fn [_payload]
+                             (js/Promise.resolve #js {:legacy true}))})
+      (-> (p/let [result (ipc/ipc :system/info)]
+            (is (= true (aget result "legacy"))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (set! util/electron? original-electron?)
+                       (set! (.-apis js/window) original-apis)
+                       (done)))))))
diff --git a/src/test/frontend/fs_test.cljs b/src/test/frontend/fs_test.cljs
index 7874cfecde..e5fe292f94 100644
--- a/src/test/frontend/fs_test.cljs
+++ b/src/test/frontend/fs_test.cljs
@@ -1,7 +1,7 @@
 (ns frontend.fs-test
   (:require ["fs" :as fs-node]
             ["path" :as node-path]
-            [clojure.test :refer [is]]
+            [cljs.test :refer [is]]
             [frontend.fs :as fs]
             [frontend.test.helper :as test-helper :include-macros true :refer [deftest-async]]
             [frontend.test.node-fixtures :as node-fixtures]
diff --git a/src/test/frontend/handler/db_based/sync_test.cljs b/src/test/frontend/handler/db_based/sync_test.cljs
index e9aa5d76df..ddb4aa8b03 100644
--- a/src/test/frontend/handler/db_based/sync_test.cljs
+++ b/src/test/frontend/handler/db_based/sync_test.cljs
@@ -1,12 +1,13 @@
 (ns frontend.handler.db-based.sync-test
   (:require [cljs.test :refer [deftest is async]]
             [clojure.string :as string]
-            [frontend.db :as db]
+            [frontend.config :as config]
             [frontend.handler.db-based.sync :as db-sync]
+            [frontend.persist-db :as persist-db]
             [frontend.handler.repo :as repo-handler]
             [frontend.handler.user :as user-handler]
             [frontend.state :as state]
-            [logseq.db :as ldb]
+            [frontend.util :as util]
             [promesa.core :as p]))
 
 (deftest remove-member-request-test
@@ -59,43 +60,24 @@
 
 (deftest rtc-create-graph-persists-disabled-e2ee-flag-test
   (async done
-         (let [fetch-called (atom nil)
-               tx-called (atom nil)
-               ensure-calls (atom [])]
+         (let [worker-calls (atom [])]
            (-> (p/with-redefs [db-sync/http-base (fn [] "http://base")
                                user-handler/task--ensure-id&access-token (fn [resolve _reject]
                                                                            (resolve true))
-                               db/get-db (fn [] :db)
-                               ldb/get-graph-schema-version (fn [_] {:major 65})
                                state/<invoke-db-worker (fn [& args]
-                                                         (when (= :thread-api/db-sync-ensure-user-rsa-keys
-                                                                  (first args))
-                                                           (swap! ensure-calls conj args))
-                                                         (p/resolved {:public-key "pk"}))
-                               db-sync/fetch-json (fn [url opts _]
-                                                    (reset! fetch-called {:url url :opts opts})
-                                                    (p/resolved {:graph-id "graph-1"
-                                                                 :graph-e2ee? false}))
-                               ldb/transact! (fn [repo tx-data]
-                                               (reset! tx-called {:repo repo :tx-data tx-data})
-                                               nil)]
+                                                         (swap! worker-calls conj args)
+                                                         (p/resolved {:graph-id "graph-1"
+                                                                      :graph-e2ee? false}))]
                  (db-sync/<rtc-create-graph! "logseq_db_demo" false))
-               (p/then (fn [graph-id]
-                         (let [request-body (-> @fetch-called
-                                                (get-in [:opts :body])
-                                                js/JSON.parse
-                                                (js->clj :keywordize-keys true))
-                               tx-data (:tx-data @tx-called)]
-                           (is (= "graph-1" graph-id))
-                           (is (= "http://base/graphs" (:url @fetch-called)))
-                           (is (= false (:graph-e2ee? request-body)))
-                           (is (= [[:thread-api/db-sync-ensure-user-rsa-keys
-                                    {:ensure-server? true}]]
-                                  @ensure-calls))
-                           (is (= :logseq.kv/graph-rtc-e2ee?
-                                  (get-in tx-data [2 :db/ident])))
-                           (is (= false
-                                  (get-in tx-data [2 :kv/value]))))
+               (p/then (fn [result]
+                         (is (= {:graph-id "graph-1"
+                                 :graph-e2ee? false}
+                                result))
+                         (is (= [[:thread-api/db-sync-create-remote-graph
+                                  "logseq_db_demo"
+                                  false
+                                  true]]
+                                @worker-calls))
                          (done)))
                (p/catch (fn [e]
                           (is false (str e))
@@ -103,43 +85,24 @@
 
 (deftest rtc-create-graph-defaults-e2ee-enabled-test
   (async done
-         (let [fetch-called (atom nil)
-               tx-called (atom nil)
-               ensure-calls (atom [])]
+         (let [worker-calls (atom [])]
            (-> (p/with-redefs [db-sync/http-base (fn [] "http://base")
                                user-handler/task--ensure-id&access-token (fn [resolve _reject]
                                                                            (resolve true))
-                               db/get-db (fn [] :db)
-                               ldb/get-graph-schema-version (fn [_] {:major 65})
                                state/<invoke-db-worker (fn [& args]
-                                                         (when (= :thread-api/db-sync-ensure-user-rsa-keys
-                                                                  (first args))
-                                                           (swap! ensure-calls conj args))
-                                                         (p/resolved {:public-key "pk"}))
-                               db-sync/fetch-json (fn [url opts _]
-                                                    (reset! fetch-called {:url url :opts opts})
-                                                    (p/resolved {:graph-id "graph-2"}))
-                               ldb/transact! (fn [repo tx-data]
-                                               (reset! tx-called {:repo repo :tx-data tx-data})
-                                               nil)]
+                                                         (swap! worker-calls conj args)
+                                                         (p/resolved {:graph-id "graph-2"
+                                                                      :graph-e2ee? true}))]
                  (db-sync/<rtc-create-graph! "logseq_db_demo"))
-               (p/then (fn [graph-id]
-                         (let [request-body (-> @fetch-called
-                                                (get-in [:opts :body])
-                                                js/JSON.parse
-                                                (js->clj :keywordize-keys true))
-                               tx-data (:tx-data @tx-called)]
-                           (is (= "graph-2" graph-id))
-                           (is (= "http://base/graphs" (:url @fetch-called)))
-                           (is (= true (:graph-e2ee? request-body)))
-                           (is (= true (:graph-ready-for-use? request-body)))
-                           (is (= [[:thread-api/db-sync-ensure-user-rsa-keys
-                                    {:ensure-server? true}]]
-                                  @ensure-calls))
-                           (is (= :logseq.kv/graph-rtc-e2ee?
-                                  (get-in tx-data [2 :db/ident])))
-                           (is (= true
-                                  (get-in tx-data [2 :kv/value]))))
+               (p/then (fn [result]
+                         (is (= {:graph-id "graph-2"
+                                 :graph-e2ee? true}
+                                result))
+                         (is (= [[:thread-api/db-sync-create-remote-graph
+                                  "logseq_db_demo"
+                                  true
+                                  true]]
+                                @worker-calls))
                          (done)))
                (p/catch (fn [e]
                           (is false (str e))
@@ -147,23 +110,12 @@
 
 (deftest rtc-upload-graph-creates-remote-graph-as-not-ready-test
   (async done
-         (let [fetch-called (atom nil)
-               tx-called (atom nil)
-               upload-calls (atom [])
+         (let [upload-calls (atom [])
                refresh-calls (atom 0)
                start-calls (atom [])]
            (-> (p/with-redefs [db-sync/http-base (fn [] "http://base")
                                user-handler/task--ensure-id&access-token (fn [resolve _reject]
                                                                            (resolve true))
-                               db/get-db (fn [] :db)
-                               ldb/get-graph-schema-version (fn [_] {:major 65})
-                               db-sync/fetch-json (fn [url opts _]
-                                                    (reset! fetch-called {:url url :opts opts})
-                                                    (p/resolved {:graph-id "graph-3"
-                                                                 :graph-e2ee? false}))
-                               ldb/transact! (fn [repo tx-data]
-                                               (reset! tx-called {:repo repo :tx-data tx-data})
-                                               nil)
                                state/<invoke-db-worker (fn [& args]
                                                          (swap! upload-calls conj args)
                                                          (p/resolved :ok))
@@ -175,19 +127,10 @@
                                                      (p/resolved :ok))]
                  (db-sync/<rtc-upload-graph! "logseq_db_demo" false))
                (p/then (fn [_]
-                         (let [request-body (-> @fetch-called
-                                                (get-in [:opts :body])
-                                                js/JSON.parse
-                                                (js->clj :keywordize-keys true))]
-                           (is (= false (:graph-ready-for-use? request-body)))
-                           (is (= [[:thread-api/db-sync-ensure-user-rsa-keys
-                                    {:ensure-server? true}]
-                                   [:thread-api/db-sync-upload-graph "logseq_db_demo"]]
-                                  @upload-calls))
-                           (is (= 1 @refresh-calls))
-                           (is (= ["logseq_db_demo"] @start-calls))
-                           (is (= :logseq.kv/graph-rtc-e2ee?
-                                  (get-in (:tx-data @tx-called) [2 :db/ident]))))
+                         (is (= [[:thread-api/db-sync-upload-graph "logseq_db_demo"]]
+                                @upload-calls))
+                         (is (= 1 @refresh-calls))
+                         (is (= ["logseq_db_demo"] @start-calls))
                          (done)))
                (p/catch (fn [e]
                           (is false (str e))
@@ -273,6 +216,53 @@
                             (reset! state/*db-worker worker-prev)
                             (reset! state/state state-prev)))))))
 
+(deftest rtc-start-syncs-auth-state-before-db-sync-start-test
+  (async done
+         (let [worker-prev @state/*db-worker
+               state-prev @state/state
+               calls (atom [])]
+           (reset! state/*db-worker :worker)
+           (reset! state/state (assoc state-prev
+                                      :git/current-repo "demo-graph"
+                                      :auth/id-token "id-token"
+                                      :auth/access-token "access-token"
+                                      :auth/refresh-token "refresh-token"
+                                      :user/info {:sub "user-1"}
+                                      :config {:a 1}
+                                      :rtc/uploading? false
+                                      :rtc/loading-graphs? false))
+           (-> (p/with-redefs [user-handler/task--ensure-id&access-token (fn [resolve _reject]
+                                                                           (resolve true))
+                               state/get-rtc-graphs (fn [] [{:url "demo-graph"
+                                                             :graph-ready-for-use? true}])
+                               state/<invoke-db-worker (fn [& args]
+                                                         (swap! calls conj args)
+                                                         (p/resolved :ok))]
+                 (db-sync/<rtc-start! "demo-graph"))
+               (p/then (fn [_]
+                         (is (= :thread-api/sync-app-state (ffirst @calls)))
+                         (is (= (cond-> {:git/current-repo "demo-graph"
+                                          :config {:a 1}
+                                          :auth/id-token "id-token"
+                                          :auth/access-token "access-token"
+                                          :auth/refresh-token "refresh-token"
+                                          :user/info {:sub "user-1"}}
+                                   (seq config/OAUTH-DOMAIN)
+                                   (assoc :auth/oauth-domain config/OAUTH-DOMAIN)
+
+                                   (seq config/COGNITO-CLIENT-ID)
+                                   (assoc :auth/oauth-client-id config/COGNITO-CLIENT-ID))
+                                (second (first @calls))))
+                         (is (= [:thread-api/db-sync-start "demo-graph"]
+                                (second @calls)))
+                         (done)))
+               (p/catch (fn [error]
+                          (is false (str error))
+                          (done)))
+               (p/finally (fn []
+                            (reset! state/*db-worker worker-prev)
+                            (reset! state/state state-prev)))))))
+
 (deftest rtc-download-graph-emits-feedback-before-snapshot-fetch-test
   (let [trace (atom [])
         log-events (atom [])]
@@ -386,7 +376,7 @@
                (p/then (fn [_]
                          (is (= 1 (count @worker-calls)))
                          (let [[op graph graph-uuid graph-e2ee?] (first @worker-calls)]
-                           (is (= :thread-api/db-sync-download-graph op))
+                           (is (= :thread-api/db-sync-download-graph-by-id op))
                            (is (string/ends-with? graph "demo-graph"))
                            (is (= "graph-1" graph-uuid))
                            (is (= false graph-e2ee?)))
@@ -420,3 +410,102 @@
                           (done)))
                (p/finally (fn []
                             (reset! state/*db-worker worker-prev)))))))
+
+(deftest rtc-download-graph-rebinds-desktop-runtime-before-download-test
+  (async done
+         (let [runtime-bound-repo (atom "logseq_db_d")
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [db-sync/http-base (fn [] "http://base")
+                               user-handler/task--ensure-id&access-token (fn [resolve _reject]
+                                                                           (resolve true))
+                               util/electron? (fn [] true)
+                               persist-db/<fetch-init-data (fn [repo _opts]
+                                                             (reset! runtime-bound-repo repo)
+                                                             (p/resolved {:schema {}
+                                                                          :initial-data []}))
+                               state/<invoke-db-worker (fn [& args]
+                                                         (swap! invoke-calls conj args)
+                                                         (let [[op repo] args]
+                                                           (case op
+                                                             :thread-api/sync-app-state
+                                                             (p/resolved :ok)
+
+                                                             :thread-api/db-sync-download-graph-by-id
+                                                             (if (= repo @runtime-bound-repo)
+                                                               (p/resolved :ok)
+                                                               (p/rejected
+                                                                (ex-info "repo does not match bound repo"
+                                                                         {:status 409
+                                                                          :code :repo-mismatch
+                                                                          :error {:code "repo-mismatch"
+                                                                                  :message "repo does not match bound repo"
+                                                                                  :repo repo
+                                                                                  :bound-repo @runtime-bound-repo}})))
+
+                                                             (p/resolved :ok))))
+                               state/pub-event! (fn [& _] nil)
+                               state/set-state! (fn [& _] nil)]
+                 (db-sync/<rtc-download-graph! "db1" "graph-1" false))
+               (p/then (fn [_]
+                         (is (= "logseq_db_db1" @runtime-bound-repo))
+                         (is (= :thread-api/sync-app-state
+                                (ffirst @invoke-calls)))
+                         (is (= :thread-api/db-sync-download-graph-by-id
+                                (first (second @invoke-calls))))
+                         (done)))
+               (p/catch (fn [error]
+                          (is false (str error))
+                          (done)))))))
+
+(deftest rtc-download-graph-skips-runtime-rebind-outside-electron-test
+  (async done
+         (let [runtime-rebind-calls (atom [])
+               worker-calls (atom [])]
+           (-> (p/with-redefs [db-sync/http-base (fn [] "http://base")
+                               user-handler/task--ensure-id&access-token (fn [resolve _reject]
+                                                                           (resolve true))
+                               util/electron? (fn [] false)
+                               persist-db/<fetch-init-data (fn [& args]
+                                                             (swap! runtime-rebind-calls conj args)
+                                                             (p/resolved {:schema {}
+                                                                          :initial-data []}))
+                               state/<invoke-db-worker (fn [& args]
+                                                         (swap! worker-calls conj args)
+                                                         (p/resolved :ok))
+                               state/pub-event! (fn [& _] nil)
+                               state/set-state! (fn [& _] nil)]
+                 (db-sync/<rtc-download-graph! "db1" "graph-1" true))
+               (p/then (fn [_]
+                         (is (empty? @runtime-rebind-calls))
+                         (is (= :thread-api/db-sync-download-graph-by-id
+                                (ffirst @worker-calls)))
+                         (done)))
+               (p/catch (fn [error]
+                          (is false (str error))
+                          (done)))))))
+
+(deftest rtc-download-graph-syncs-auth-state-after-runtime-rebind-test
+  (async done
+         (let [worker-calls (atom [])]
+           (-> (p/with-redefs [db-sync/http-base (fn [] "http://base")
+                               user-handler/task--ensure-id&access-token (fn [resolve _reject]
+                                                                           (resolve true))
+                               util/electron? (fn [] true)
+                               persist-db/<fetch-init-data (fn [_repo _opts]
+                                                             (p/resolved {:schema {}
+                                                                          :initial-data []}))
+                               state/<invoke-db-worker (fn [& args]
+                                                         (swap! worker-calls conj args)
+                                                         (p/resolved :ok))
+                               state/pub-event! (fn [& _] nil)
+                               state/set-state! (fn [& _] nil)]
+                 (db-sync/<rtc-download-graph! "db1" "graph-1" true))
+               (p/then (fn [_]
+                         (is (= :thread-api/sync-app-state
+                                (ffirst @worker-calls)))
+                         (is (= :thread-api/db-sync-download-graph-by-id
+                                (first (second @worker-calls))))
+                         (done)))
+               (p/catch (fn [error]
+                          (is false (str error))
+                          (done)))))))
diff --git a/src/test/frontend/handler/user_test.cljs b/src/test/frontend/handler/user_test.cljs
index 02090b6b33..4cb4f9485c 100644
--- a/src/test/frontend/handler/user_test.cljs
+++ b/src/test/frontend/handler/user_test.cljs
@@ -1,7 +1,9 @@
 (ns frontend.handler.user-test
   (:require [cljs.test :refer [deftest is testing]]
+            [electron.ipc :as ipc]
             [frontend.handler.user :as user-handler]
             [frontend.state :as state]
+            [frontend.util :as util]
             [promesa.core :as p]))
 
 (defn- with-mocked-local-storage
@@ -31,6 +33,56 @@
                                          :writable true})
           (js/Reflect.deleteProperty js/globalThis "localStorage"))))))
 
+(deftest set-tokens-persists-auth-json-with-latest-token-values-test
+  (let [writes* (atom [])
+        old-state @state/state]
+    (reset! state/state (assoc-in old-state [:system/info :home-dir] "/tmp/home"))
+    (try
+      (with-mocked-local-storage
+        (fn []
+          (with-redefs [util/electron? (constantly true)
+                        ipc/ipc (fn [op _repo path content]
+                                  (is (= "writeFile" op))
+                                  (swap! writes* conj {:path path
+                                                       :content content})
+                                  (p/resolved nil))]
+            (#'user-handler/set-tokens! "id-token-v1" "access-token-v1" "refresh-token-v1")
+            (is (= 1 (count @writes*)))
+            (is (= "/tmp/home/logseq/auth.json" (:path (first @writes*))))
+            (is (= {:id-token "id-token-v1"
+                    :access-token "access-token-v1"
+                    :refresh-token "refresh-token-v1"}
+                   (select-keys (js->clj (js/JSON.parse (:content (first @writes*))) :keywordize-keys true)
+                                [:id-token :access-token :refresh-token]))))))
+      (finally
+        (reset! state/state old-state)))))
+
+(deftest set-tokens-without-refresh-token-persists-existing-refresh-token-test
+  (let [writes* (atom [])
+        old-state @state/state]
+    (reset! state/state (-> old-state
+                            (assoc :auth/refresh-token "refresh-token-existing")
+                            (assoc-in [:system/info :home-dir] "/tmp/home")))
+    (try
+      (with-mocked-local-storage
+        (fn []
+          (with-redefs [util/electron? (constantly true)
+                        ipc/ipc (fn [op _repo path content]
+                                  (is (= "writeFile" op))
+                                  (swap! writes* conj {:path path
+                                                       :content content})
+                                  (p/resolved nil))]
+            (#'user-handler/set-tokens! "id-token-v2" "access-token-v2")
+            (is (= 1 (count @writes*)))
+            (is (= "/tmp/home/logseq/auth.json" (:path (first @writes*))))
+            (is (= {:id-token "id-token-v2"
+                    :access-token "access-token-v2"
+                    :refresh-token "refresh-token-existing"}
+                   (select-keys (js->clj (js/JSON.parse (:content (first @writes*))) :keywordize-keys true)
+                                [:id-token :access-token :refresh-token]))))))
+      (finally
+        (reset! state/state old-state)))))
+
 (deftest logout-clears-e2ee-password-when-db-worker-ready-test
   (testing "logout should request db-worker to clear persisted e2ee password"
     (let [ops* (atom [])
diff --git a/src/test/frontend/modules/shortcut/config_test.cljs b/src/test/frontend/modules/shortcut/config_test.cljs
new file mode 100644
index 0000000000..912c2d9fe8
--- /dev/null
+++ b/src/test/frontend/modules/shortcut/config_test.cljs
@@ -0,0 +1,28 @@
+(ns frontend.modules.shortcut.config-test
+  (:require ["fs" :as fs]
+            ["path" :as node-path]
+            [cljs.test :refer [deftest is testing]]
+            [frontend.modules.shortcut.config :as shortcut-config]
+            [frontend.state :as state]))
+
+(deftest graph-db-save-shortcut-does-not-trigger-legacy-save-event
+  (testing "mod+s in db graph sends new save-info event"
+    (let [events* (atom [])]
+      (with-redefs [state/pub-event! (fn [event]
+                                       (swap! events* conj event))]
+        ((get-in shortcut-config/all-built-in-keyboard-shortcuts
+                 [:graph/db-save :fn]))
+        (is (= [[:graph/db-save-shortcut]]
+               @events*))))))
+
+(deftest graph-db-save-shortcut-electron-uses-backup-flow
+  (let [events-source-path (node-path/join (.cwd js/process)
+                                           "src"
+                                           "main"
+                                           "frontend"
+                                           "handler"
+                                           "events.cljs")
+        source (.toString (fs/readFileSync events-source-path) "utf8")]
+    (is (not (.includes source "Manual save is no longer required.")))
+    (is (.includes source "(persist-db/export-current-graph!"))
+    (is (.includes source ":succ-notification? true"))))
diff --git a/src/test/frontend/persist_db/remote_test.cljs b/src/test/frontend/persist_db/remote_test.cljs
new file mode 100644
index 0000000000..20eb48c9cd
--- /dev/null
+++ b/src/test/frontend/persist_db/remote_test.cljs
@@ -0,0 +1,100 @@
+(ns frontend.persist-db.remote-test
+  (:require [cljs.test :refer [async deftest is]]
+            [frontend.persist-db.remote :as remote]
+            [logseq.db :as ldb]
+            [promesa.core :as p]))
+
+(deftest invoke-success-returns-decoded-transit-result
+  (async done
+    (let [captured (atom nil)
+          client (remote/create-client
+                  {:base-url "http://127.0.0.1:9101"
+                   :auth-token "token-1"
+                   :fetch-fn (fn [req]
+                               (reset! captured req)
+                               (p/resolved {:status 200
+                                            :body (js/JSON.stringify
+                                                   #js {:ok true
+                                                        :resultTransit (ldb/write-transit-str [{:repo "graph-a"}])})}))})]
+      (-> (p/let [result (remote/invoke! client "thread-api/list-db" false [])
+                  headers (:headers @captured)]
+            (is (= [{:repo "graph-a"}] result))
+            (is (= "Bearer token-1" (get headers "Authorization"))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest invoke-error-propagates-status-and-error-code
+  (async done
+    (let [client (remote/create-client
+                  {:base-url "http://127.0.0.1:9101"
+                   :fetch-fn (fn [_req]
+                               (p/resolved {:status 409
+                                            :body (js/JSON.stringify
+                                                   #js {:ok false
+                                                        :error #js {:code "repo-locked"
+                                                                    :message "graph already locked"}})}))})]
+      (-> (remote/invoke! client "thread-api/transact" false ["graph-a" [] {}])
+          (p/then (fn [_]
+                    (is false "expected invoke! to reject on non-2xx status")))
+          (p/catch (fn [e]
+                     (let [data (ex-data e)]
+                       (is (= 409 (:status data)))
+                       (is (= :repo-locked (:code data))))))
+          (p/finally (fn [] (done)))))))
+
+(deftest connect-events-parses-sse-and-reconnects
+  (async done
+    (let [events (atom [])
+          open-count (atom 0)
+          scheduled (atom nil)
+          latest-handlers (atom nil)
+          wrapped-worker (fn [& _] nil)
+          client (remote/create-client
+                  {:base-url "http://127.0.0.1:9101"
+                   :auth-token "token-1"
+                   :event-handler (fn [event-type wrapped-worker' payload]
+                                    (swap! events conj [event-type wrapped-worker' payload]))
+                   :open-sse-fn (fn [{:keys [on-message on-error]}]
+                                  (swap! open-count inc)
+                                  (reset! latest-handlers {:on-message on-message
+                                                           :on-error on-error})
+                                  {:close! (fn [] nil)})
+                   :schedule-fn (fn [f _delay-ms]
+                                  (reset! scheduled f)
+                                  :scheduled)
+                   :reconnect-delay-ms 1})
+          sub (remote/connect-events! client wrapped-worker)
+          payload (ldb/write-transit-str [:thread-api/persist-db {:repo "graph-a"}])]
+      (-> (p/let [_ ((:on-message @latest-handlers)
+                     (str "data: " (js/JSON.stringify #js {:type "thread-api/persist-db"
+                                                           :payload payload})
+                          "\n\n"))
+                  _ (is (= [[:thread-api/persist-db wrapped-worker {:repo "graph-a"}]] @events))
+                  _ ((:on-error @latest-handlers) (js/Error. "disconnect"))
+                  scheduled-fn @scheduled
+                  _ (is (fn? scheduled-fn))
+                  _ (when (fn? scheduled-fn)
+                      (scheduled-fn))]
+            (is (= 2 @open-count))
+            ((:disconnect! sub)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest invoke-without-auth-token-omits-authorization-header
+  (async done
+    (let [captured (atom nil)
+          client (remote/create-client
+                  {:base-url "http://127.0.0.1:9101"
+                   :fetch-fn (fn [req]
+                               (reset! captured req)
+                               (p/resolved {:status 200
+                                            :body (js/JSON.stringify
+                                                   #js {:ok true
+                                                        :resultTransit (ldb/write-transit-str [])})}))})]
+      (-> (p/let [_ (remote/invoke! client "thread-api/list-db" false [])]
+            (is (nil? (get (:headers @captured) "Authorization"))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
diff --git a/src/test/frontend/persist_db_test.cljs b/src/test/frontend/persist_db_test.cljs
new file mode 100644
index 0000000000..0c15333de4
--- /dev/null
+++ b/src/test/frontend/persist_db_test.cljs
@@ -0,0 +1,378 @@
+(ns frontend.persist-db-test
+  (:require [cljs.test :refer [async deftest is use-fixtures]]
+            [electron.ipc :as ipc]
+            [frontend.config :as config]
+            [frontend.persist-db.browser :as browser]
+            [frontend.persist-db :as persist-db]
+            [frontend.persist-db.protocol :as protocol]
+            [frontend.persist-db.remote :as remote]
+            [frontend.storage :as storage]
+            [frontend.state :as state]
+            [frontend.util :as util]
+            [logseq.db :as ldb]
+            [promesa.core :as p]))
+
+(defrecord FakeRemote [repo wrapped-worker]
+  protocol/PersistentDB
+  (<list-db [_]
+    (p/resolved [{:name repo}]))
+
+  (<new [_ _repo _opts]
+    (p/resolved true))
+
+  (<unsafe-delete [_ _repo]
+    (p/resolved true))
+
+  (<release-access-handles [_ _repo]
+    (p/resolved true))
+
+  (<fetch-initial-data [_ repo _opts]
+    (p/resolved {:schema {:repo repo}
+                 :initial-data []}))
+
+  (<export-db [_ _repo _opts]
+    (p/resolved nil))
+
+  (<import-db [_ _repo _data]
+    (p/resolved true)))
+
+(defonce ^:private *previous-runtime-state (atom nil))
+
+(defn- save-runtime-state!
+  []
+  (reset! *previous-runtime-state
+          {:remote-db @persist-db/remote-db
+           :remote-repo @persist-db/remote-repo
+           :db-worker @state/*db-worker
+           :transact-fn @ldb/*transact-fn}))
+
+(defn- restore-runtime-state!
+  []
+  (let [{:keys [remote-db remote-repo db-worker transact-fn]} @*previous-runtime-state]
+    (reset! persist-db/remote-db remote-db)
+    (reset! persist-db/remote-repo remote-repo)
+    (reset! state/*db-worker db-worker)
+    (reset! ldb/*transact-fn transact-fn)
+    (reset! *previous-runtime-state nil)))
+
+(use-fixtures :each {:before save-runtime-state!
+                     :after restore-runtime-state!})
+
+(defn- reset-runtime-state!
+  []
+  (reset! persist-db/remote-db nil)
+  (reset! persist-db/remote-repo nil)
+  (reset! state/*db-worker nil)
+  (reset! ldb/*transact-fn nil))
+
+(deftest electron-fetch-init-data-starts-remote-runtime
+  (async done
+    (let [ipc-calls (atom [])
+          start-calls (atom [])
+          wrapped-worker (fn [& _] nil)
+          original-electron? util/electron?
+          original-ipc ipc/ipc
+          original-start! remote/start!
+          original-stop! remote/stop!]
+      (reset-runtime-state!)
+      (set! util/electron? (constantly true))
+      (set! ipc/ipc (fn [channel repo]
+                      (swap! ipc-calls conj [channel repo])
+                      (p/resolved {:base-url "http://127.0.0.1:9101"
+                                   :auth-token nil
+                                   :repo repo})))
+      (set! remote/start! (fn [{:keys [repo]}]
+                            (swap! start-calls conj repo)
+                            (->FakeRemote repo wrapped-worker)))
+      (set! remote/stop! (fn [_] (p/resolved true)))
+      (-> (p/let [result (persist-db/<fetch-init-data "logseq_db_graph_a" {})]
+            (is (= {:schema {:repo "logseq_db_graph_a"}
+                    :initial-data []}
+                   result))
+            (is (= [["db-worker-runtime" "logseq_db_graph_a"]] @ipc-calls))
+            (is (= ["logseq_db_graph_a"] @start-calls))
+            (is (= wrapped-worker @state/*db-worker)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (set! util/electron? original-electron?)
+                       (set! ipc/ipc original-ipc)
+                       (set! remote/start! original-start!)
+                       (set! remote/stop! original-stop!)
+                       (done)))))))
+
+(deftest electron-fetch-init-data-reuses-runtime-for-same-repo-and-restarts-for-new-repo
+  (async done
+    (let [ipc-calls (atom [])
+          start-calls (atom [])
+          stop-calls (atom [])
+          ensure-remote! #'persist-db/<ensure-remote!
+          original-ipc ipc/ipc
+          original-start! remote/start!
+          original-stop! remote/stop!]
+      (reset-runtime-state!)
+      (set! ipc/ipc (fn [channel repo]
+                      (swap! ipc-calls conj [channel repo])
+                      (p/resolved {:base-url "http://127.0.0.1:9101"
+                                   :auth-token nil
+                                   :repo repo})))
+      (set! remote/start! (fn [{:keys [repo]}]
+                            (swap! start-calls conj repo)
+                            (->FakeRemote repo (fn [& _] nil))))
+      (set! remote/stop! (fn [client]
+                           (swap! stop-calls conj (:repo client))
+                           (p/resolved true)))
+      (-> (p/let [_ (ensure-remote! "logseq_db_graph_a")
+                  _ (ensure-remote! "logseq_db_graph_a")
+                  _ (ensure-remote! "logseq_db_graph_b")]
+            (is (= [["db-worker-runtime" "logseq_db_graph_a"]
+                    ["db-worker-runtime" "logseq_db_graph_b"]]
+                   @ipc-calls))
+            (is (= ["logseq_db_graph_a" "logseq_db_graph_b"] @start-calls))
+            (is (= ["logseq_db_graph_a"] @stop-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (set! ipc/ipc original-ipc)
+                       (set! remote/start! original-start!)
+                       (set! remote/stop! original-stop!)
+                       (done)))))))
+
+(deftest electron-fetch-init-data-then-set-current-repo-does-not-rebind-runtime
+  (async done
+    (let [ipc-calls (atom [])
+          start-calls (atom [])
+          stop-calls (atom [])
+          wrapped-worker (fn [& _] nil)
+          original-state @state/state
+          original-electron? util/electron?
+          original-ipc ipc/ipc
+          original-start! remote/start!
+          original-stop! remote/stop!
+          original-storage-set storage/set
+          original-storage-remove storage/remove]
+      (reset-runtime-state!)
+      (set! util/electron? (constantly true))
+      (set! ipc/ipc (fn [channel repo]
+                      (swap! ipc-calls conj [channel repo])
+                      (p/resolved nil)))
+      (set! remote/start! (fn [{:keys [repo]}]
+                            (swap! start-calls conj repo)
+                            (->FakeRemote repo wrapped-worker)))
+      (set! remote/stop! (fn [client]
+                           (swap! stop-calls conj (:repo client))
+                           (p/resolved true)))
+      (set! storage/set (fn [& _] nil))
+      (set! storage/remove (fn [& _] nil))
+      (-> (p/let [repo "logseq_db_graph_a"
+                  _ (persist-db/<fetch-init-data repo {})
+                  _ (state/set-current-repo! repo)]
+            (is (= [["db-worker-runtime" "logseq_db_graph_a"]
+                    ["setCurrentGraph" "logseq_db_graph_a"]]
+                   @ipc-calls))
+            (is (= ["logseq_db_graph_a"] @start-calls))
+            (is (empty? @stop-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (reset! state/state original-state)
+                       (set! util/electron? original-electron?)
+                       (set! ipc/ipc original-ipc)
+                       (set! remote/start! original-start!)
+                       (set! remote/stop! original-stop!)
+                       (set! storage/set original-storage-set)
+                       (set! storage/remove original-storage-remove)
+                       (done)))))))
+
+(deftest electron-ensure-remote-pushes-db-sync-config-on-start-test
+  (async done
+         (let [worker-calls (atom [])
+               ensure-remote! #'persist-db/<ensure-remote!
+               original-ipc ipc/ipc
+               original-start! remote/start!
+               original-stop! remote/stop!
+               original-ws config/db-sync-ws-url
+               original-http config/db-sync-http-base]
+           (reset-runtime-state!)
+           (set! ipc/ipc (fn [channel repo]
+                           (is (= "db-worker-runtime" channel))
+                           (p/resolved {:base-url "http://127.0.0.1:9101"
+                                        :auth-token nil
+                                        :repo repo})))
+           (set! config/db-sync-ws-url (fn [] "wss://sync.example.test/sync/%s"))
+           (set! config/db-sync-http-base (fn [] "https://sync.example.test"))
+           (set! remote/start! (fn [{:keys [repo]}]
+                                 (->FakeRemote repo
+                                               (fn [qkw direct-pass? & args]
+                                                 (swap! worker-calls conj [qkw direct-pass? args])
+                                                 (p/resolved nil)))))
+           (set! remote/stop! (fn [_] (p/resolved true)))
+           (-> (p/let [_ (ensure-remote! "logseq_db_graph_a")]
+                 (let [set-config-call (first (filter #(= :thread-api/set-db-sync-config (first %))
+                                                      @worker-calls))]
+                   (is (= [:thread-api/set-db-sync-config
+                           false
+                           [{:enabled? true
+                             :ws-url "wss://sync.example.test/sync/%s"
+                             :http-base "https://sync.example.test"}]]
+                          set-config-call))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (set! ipc/ipc original-ipc)
+                            (set! remote/start! original-start!)
+                            (set! remote/stop! original-stop!)
+                            (set! config/db-sync-ws-url original-ws)
+                            (set! config/db-sync-http-base original-http)
+                            (done)))))))
+
+(deftest electron-list-db-without-current-repo-does-not-bootstrap-runtime
+  (async done
+    (let [ipc-calls (atom [])
+          start-calls (atom [])
+          original-electron? util/electron?
+          original-current-repo state/get-current-repo
+          original-ipc ipc/ipc
+          original-start! remote/start!
+          original-stop! remote/stop!]
+      (reset-runtime-state!)
+      (set! util/electron? (constantly true))
+      (set! state/get-current-repo (constantly nil))
+      (set! ipc/ipc (fn [& args]
+                      (swap! ipc-calls conj args)
+                      (p/resolved {:base-url "http://127.0.0.1:9101"
+                                   :auth-token nil
+                                   :repo "logseq_db_unused"})))
+      (set! remote/start! (fn [_]
+                            (swap! start-calls conj :start)
+                            (->FakeRemote "logseq_db_unused" (fn [& _] nil))))
+      (set! remote/stop! (fn [_] (p/resolved true)))
+      (-> (p/let [repos (persist-db/<list-db)]
+            (is (= [] repos))
+            (is (= [] @ipc-calls))
+            (is (= [] @start-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (set! util/electron? original-electron?)
+                       (set! state/get-current-repo original-current-repo)
+                       (set! ipc/ipc original-ipc)
+                       (set! remote/start! original-start!)
+                       (set! remote/stop! original-stop!)
+                       (done)))))))
+
+(deftest electron-close-db-disconnects-current-remote-runtime
+  (async done
+    (let [invoke-calls (atom [])
+          stop-calls (atom [])
+          fake-client {:repo "logseq_db_graph_a"
+                       :client {:base-url "http://127.0.0.1:9101"}}
+          original-electron? util/electron?
+          original-invoke! remote/invoke!
+          original-stop! remote/stop!]
+      (reset-runtime-state!)
+      (reset! persist-db/remote-db fake-client)
+      (reset! persist-db/remote-repo "logseq_db_graph_a")
+      (set! util/electron? (constantly true))
+      (set! remote/invoke! (fn [client method direct-pass? args]
+                             (swap! invoke-calls conj [client method direct-pass? args])
+                             (p/resolved nil)))
+      (set! remote/stop! (fn [client]
+                           (swap! stop-calls conj client)
+                           (p/resolved true)))
+      (-> (p/let [_ (persist-db/<close-db "logseq_db_graph_a")]
+            (is (= [[(:client fake-client) "thread-api/close-db" false ["logseq_db_graph_a"]]]
+                   @invoke-calls))
+            (is (= [fake-client] @stop-calls))
+            (is (nil? @persist-db/remote-db))
+            (is (nil? @persist-db/remote-repo)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (set! util/electron? original-electron?)
+                       (set! remote/invoke! original-invoke!)
+                       (set! remote/stop! original-stop!)
+                       (done)))))))
+
+(deftest electron-close-db-for-other-repo-does-not-bootstrap-runtime
+  (async done
+    (let [invoke-calls (atom [])
+          stop-calls (atom [])
+          fake-client {:repo "logseq_db_graph_a"
+                       :client {:base-url "http://127.0.0.1:9101"}}
+          original-electron? util/electron?
+          original-invoke! remote/invoke!
+          original-stop! remote/stop!]
+      (reset-runtime-state!)
+      (reset! persist-db/remote-db fake-client)
+      (reset! persist-db/remote-repo "logseq_db_graph_a")
+      (set! util/electron? (constantly true))
+      (set! remote/invoke! (fn [client method direct-pass? args]
+                             (swap! invoke-calls conj [client method direct-pass? args])
+                             (p/resolved nil)))
+      (set! remote/stop! (fn [client]
+                           (swap! stop-calls conj client)
+                           (p/resolved true)))
+      (-> (p/let [_ (persist-db/<close-db "logseq_db_graph_b")]
+            (is (empty? @invoke-calls))
+            (is (empty? @stop-calls))
+            (is (= fake-client @persist-db/remote-db))
+            (is (= "logseq_db_graph_a" @persist-db/remote-repo)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (set! util/electron? original-electron?)
+                       (set! remote/invoke! original-invoke!)
+                       (set! remote/stop! original-stop!)
+                       (done)))))))
+
+(deftest start-db-worker-skips-in-node-test-runtime
+  (async done
+    (let [invoke-calls (atom [])
+          original-node-test? util/node-test?
+          original-invoke state/<invoke-db-worker]
+      (set! util/node-test? true)
+      (set! state/<invoke-db-worker (fn [& args]
+                                      (swap! invoke-calls conj args)
+                                      (p/resolved :ok)))
+      (-> (p/let [_ (browser/start-db-worker!)]
+            (is (= [] @invoke-calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally
+           (fn []
+             (set! util/node-test? original-node-test?)
+             (set! state/<invoke-db-worker original-invoke)
+             (done)))))))
+
+(deftest browser-export-db-on-electron-triggers-worker-export-then-local-backup
+  (async done
+    (let [ipc-calls (atom [])
+          worker-export-calls (atom [])
+          original-electron? util/electron?
+          original-ipc ipc/ipc
+          original-invoke state/<invoke-db-worker-direct-pass]
+      (set! util/electron? (constantly true))
+      (set! ipc/ipc (fn [& args]
+                      (swap! ipc-calls conj args)
+                      (p/resolved :ok)))
+      (set! state/<invoke-db-worker-direct-pass
+            (fn [qkw & _]
+              (swap! worker-export-calls conj qkw)
+              (case qkw
+                :thread-api/export-db (p/resolved (.from js/Buffer "sqlite-bytes"))
+                (p/rejected (ex-info "unexpected worker call" {:qkw qkw})))))
+      (-> (protocol/<export-db (browser/->InBrowser) "logseq_db_graph_a" {})
+          (p/then (fn [_]
+                    (is (= [[:db-export "logseq_db_graph_a" false]]
+                           @ipc-calls))
+                    (is (= [:thread-api/export-db]
+                           @worker-export-calls))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally
+           (fn []
+             (set! util/electron? original-electron?)
+             (set! ipc/ipc original-ipc)
+             (set! state/<invoke-db-worker-direct-pass original-invoke)
+             (done)))))))
diff --git a/src/test/frontend/util/text_test.cljs b/src/test/frontend/util/text_test.cljs
index dc19f2ec25..f8ac05797f 100644
--- a/src/test/frontend/util/text_test.cljs
+++ b/src/test/frontend/util/text_test.cljs
@@ -34,4 +34,10 @@
     (map #(text-util/wrapped-by? "prop::value" % "" "::") (take 12 (range)))
 
     '(false false false false false false true true true true true true)
-    (map #(text-util/wrapped-by? "prop::value" % "::" "") (take 12 (range)))))
\ No newline at end of file
+    (map #(text-util/wrapped-by? "prop::value" % "::" "") (take 12 (range)))))
+
+(deftest get-graph-name-from-path-strips-only-one-leading-db-prefix
+  (are [input expected] (= expected (text-util/get-graph-name-from-path input))
+    "logseq_db_demo" "demo"
+    "logseq_db_logseq_db_demo" "logseq_db_demo"
+    "my_logseq_db_notes" "my_logseq_db_notes"))
diff --git a/src/test/frontend/worker/commands_test.cljs b/src/test/frontend/worker/commands_test.cljs
index dc5bfc73c9..e4eabd65ae 100644
--- a/src/test/frontend/worker/commands_test.cljs
+++ b/src/test/frontend/worker/commands_test.cljs
@@ -12,7 +12,7 @@
 (def month-unit {:db/ident :logseq.property.repeat/recur-unit.month})
 (def year-unit {:db/ident :logseq.property.repeat/recur-unit.year})
 
-(deftest ^:large-vars/cleanup-todo get-next-time-test
+(deftest ^:large-vars/cleanup-todo ^:fix-me get-next-time-test
   (let [now (t/now)
         one-minute-ago (t/minus now (t/minutes 1))
         one-hour-ago (t/minus now (t/hours 1))
diff --git a/src/test/frontend/worker/db_core_test.cljs b/src/test/frontend/worker/db_core_test.cljs
new file mode 100644
index 0000000000..26bd1f621f
--- /dev/null
+++ b/src/test/frontend/worker/db_core_test.cljs
@@ -0,0 +1,319 @@
+(ns frontend.worker.db-core-test
+  (:require [cljs.test :refer [async deftest is]]
+            [datascript.core :as d]
+            [frontend.common.thread-api :as thread-api]
+            [frontend.worker.db-core :as db-core]
+            [frontend.worker.platform :as platform]
+            [frontend.worker.search :as search]
+            [frontend.worker.shared-service :as shared-service]
+            [frontend.worker.state :as worker-state]
+            [frontend.worker.sync.download :as sync-download]
+            [goog.object :as gobj]
+            [logseq.db.frontend.schema :as db-schema]
+            [promesa.core :as p]))
+
+(def ^:private test-repo "db-core-test-repo")
+
+(defn- build-test-platform
+  ([]
+   (build-test-platform {}))
+  ([{:keys [post-message! remove-vfs! runtime import-db]
+     :or {post-message! (fn [& _] nil)
+          remove-vfs! (fn [_] nil)
+          runtime :browser}}]
+   {:env {:publishing? false
+          :runtime runtime}
+    :storage {:install-opfs-pool (fn [_sqlite _pool-name]
+                                   (p/resolved #js {:pauseVfs (fn [] nil)
+                                                    :unpauseVfs (fn [] nil)}))
+              :list-graphs (fn [] (p/resolved []))
+              :db-exists? (fn [_] (p/resolved false))
+              :resolve-db-path (fn [_repo _pool path] path)
+              :export-file (fn [_pool _path] (p/resolved (js/Uint8Array. 0)))
+              :import-db (or import-db (fn [_pool _path _data] (p/resolved nil)))
+              :remove-vfs! remove-vfs!
+              :read-text! (fn [_path] (p/resolved ""))
+              :write-text! (fn [_path _text] (p/resolved nil))
+              :transfer (fn [data _transferables] data)}
+    :kv {:get (fn [_] nil)
+         :set! (fn [_ _] nil)}
+    :broadcast {:post-message! post-message!}
+    :websocket {:connect (fn [_] #js {})}
+    :sqlite {:init! (fn [] nil)
+             :open-db (fn [_opts] #js {})
+             :close-db (fn [db] (.close db))
+             :exec (fn [db sql-or-opts] (.exec db sql-or-opts))
+             :transaction (fn [db f] (.transaction db f))}
+    :crypto {}
+    :timers {:set-interval! (fn [_ _] nil)}}))
+
+(defn- restoring-worker-state
+  [f]
+  (let [state-prev @worker-state/*state
+        config-prev @worker-state/*db-sync-config
+        sqlite-prev @worker-state/*sqlite
+        sqlite-conns-prev @worker-state/*sqlite-conns
+        datascript-prev @worker-state/*datascript-conns
+        client-ops-prev @worker-state/*client-ops-conns
+        opfs-prev @worker-state/*opfs-pools
+        main-thread-prev @worker-state/*main-thread
+        platform-prev @@#'platform/*platform
+        search-build-prev @(deref #'db-core/*search-index-build-ids)
+        cleanup (fn []
+                  (reset! worker-state/*state state-prev)
+                  (reset! worker-state/*db-sync-config config-prev)
+                  (reset! worker-state/*sqlite sqlite-prev)
+                  (reset! worker-state/*sqlite-conns sqlite-conns-prev)
+                  (reset! worker-state/*datascript-conns datascript-prev)
+                  (reset! worker-state/*client-ops-conns client-ops-prev)
+                  (reset! worker-state/*opfs-pools opfs-prev)
+                  (reset! worker-state/*main-thread main-thread-prev)
+                  (reset! (deref #'db-core/*search-index-build-ids) search-build-prev)
+                  (reset! @#'platform/*platform platform-prev))]
+    (platform/set-platform! (build-test-platform))
+    (reset! worker-state/*sqlite #js {})
+    (reset! worker-state/*sqlite-conns {})
+    (reset! worker-state/*datascript-conns {})
+    (reset! worker-state/*client-ops-conns {})
+    (reset! worker-state/*opfs-pools {})
+    (reset! worker-state/*main-thread nil)
+    (reset! (deref #'db-core/*search-index-build-ids) {})
+    (let [result (f)]
+      (if (p/promise? result)
+        (p/finally result cleanup)
+        (do
+          (cleanup)
+          result)))))
+
+(defn- fake-db
+  ([]
+   (fake-db {}))
+  ([{:keys [user-version sql-calls close-calls close-label]
+     :or {user-version 0}}]
+   #js {:exec (fn [sql-or-opts]
+                (let [sql (if (string? sql-or-opts)
+                            sql-or-opts
+                            (gobj/get sql-or-opts "sql"))]
+                  (when sql-calls
+                    (swap! sql-calls conj sql))
+                  (if (= sql "PRAGMA user_version")
+                    #js [#js [user-version]]
+                    #js [])))
+        :close (fn []
+                 (when close-calls
+                   (swap! close-calls conj close-label)))}))
+
+(deftest db-core-registers-db-sync-thread-apis
+  (let [api-map @thread-api/*thread-apis]
+    (is (contains? api-map :thread-api/set-db-sync-config))
+    (is (contains? api-map :thread-api/db-sync-start))
+    (is (contains? api-map :thread-api/db-sync-stop))
+    (is (contains? api-map :thread-api/db-sync-update-presence))
+    (is (contains? api-map :thread-api/db-sync-request-asset-download))
+    (is (contains? api-map :thread-api/db-sync-grant-graph-access))
+    (is (contains? api-map :thread-api/db-sync-ensure-user-rsa-keys))
+    (is (contains? api-map :thread-api/db-sync-upload-graph))))
+
+(deftest import-db-rejects-non-sqlite-payload
+  (async done
+    (restoring-worker-state
+     (fn []
+       (let [import-db! (get @thread-api/*thread-apis :thread-api/import-db)
+             imports (atom [])
+             invalid-payload (.encode (js/TextEncoder.) "[\"~#js/Error\",[\"^ \",\"~:message\",\"File not found: /db.sqlite\"]]")]
+         (platform/set-platform!
+          (build-test-platform
+           {:import-db (fn [_pool _path data]
+                         (swap! imports conj data)
+                         (p/resolved nil))}))
+         (-> (import-db! test-repo invalid-payload)
+             (p/then (fn [_]
+                       (is false "expected import-db to reject invalid payload")))
+             (p/catch (fn [error]
+                        (is (= :invalid-sqlite-import-data (:code (ex-data error))))))
+             (p/finally (fn []
+                          (is (empty? @imports))
+                          (done)))))))))
+
+(deftest set-db-sync-config-keeps-only-non-auth-fields-test
+  (let [set-config! (get @thread-api/*thread-apis :thread-api/set-db-sync-config)
+        get-config (get @thread-api/*thread-apis :thread-api/get-db-sync-config)
+        state-prev @worker-state/*state
+        config-prev @worker-state/*db-sync-config]
+    (try
+      (reset! worker-state/*state (assoc state-prev
+                                         :auth/id-token "existing-id-token"
+                                         :auth/oauth-token-url "https://existing.example.com/oauth2/token"
+                                         :auth/oauth-domain "existing.example.com"
+                                         :auth/oauth-client-id "existing-client-id"))
+      (set-config! {:ws-url "wss://example.com/sync/%s"
+                    :http-base "https://example.com"
+                    :enabled? true
+                    :auth-token "id-token-from-config"
+                    :oauth-token-url "https://auth.example.com/oauth2/token"
+                    :oauth-domain "auth.example.com"
+                    :oauth-client-id "worker-client-id"})
+      (is (= {:ws-url "wss://example.com/sync/%s"
+              :http-base "https://example.com"
+              :enabled? true}
+             @worker-state/*db-sync-config))
+      (is (= {:ws-url "wss://example.com/sync/%s"
+              :http-base "https://example.com"
+              :enabled? true}
+             (get-config)))
+      (is (= "existing-id-token" (:auth/id-token @worker-state/*state)))
+      (is (= "https://existing.example.com/oauth2/token"
+             (:auth/oauth-token-url @worker-state/*state)))
+      (is (= "existing.example.com" (:auth/oauth-domain @worker-state/*state)))
+      (is (= "existing-client-id" (:auth/oauth-client-id @worker-state/*state)))
+      (finally
+        (reset! worker-state/*state state-prev)
+        (reset! worker-state/*db-sync-config config-prev)))))
+
+(deftest get-db-sync-config-strips-auth-fields-test
+  (let [get-config (get @thread-api/*thread-apis :thread-api/get-db-sync-config)
+        config-prev @worker-state/*db-sync-config]
+    (try
+      (reset! worker-state/*db-sync-config {:ws-url "wss://example.com/sync/%s"
+                                            :auth-token "leaked-token"
+                                            :oauth-client-id "leaked-client"})
+      (is (= {:ws-url "wss://example.com/sync/%s"}
+             (get-config)))
+      (finally
+        (reset! worker-state/*db-sync-config config-prev)))))
+
+(deftest init-service-does-not-close-db-when-graph-unchanged
+  (async done
+         (let [service {:status {:ready (p/resolved true)}
+                        :proxy #js {}}
+               close-calls (atom [])
+               create-calls (atom 0)
+               *service @#'db-core/*service
+               old-service @*service]
+           (reset! *service ["graph-a" service])
+           (with-redefs [db-core/close-db! (fn [repo]
+                                             (swap! close-calls conj repo)
+                                             nil)
+                         shared-service/<create-service (fn [& _]
+                                                          (swap! create-calls inc)
+                                                          (p/resolved service))]
+             (-> (#'db-core/<init-service! "graph-a" {})
+                 (p/then (fn [result]
+                           (is (= service result))
+                           (is (= [] @close-calls))
+                           (is (zero? @create-calls))))
+                 (p/catch (fn [e]
+                            (is false (str "unexpected error: " e))))
+                 (p/finally (fn []
+                              (reset! *service old-service)
+                              (done))))))))
+
+(deftest search-build-blocks-indice-in-worker-reports-progress-to-main-thread-test
+  (async done
+         (restoring-worker-state
+          (fn []
+            (let [build-index! (get @thread-api/*thread-apis :thread-api/search-build-blocks-indice-in-worker)
+                  conn (d/create-conn db-schema/schema)
+                  search-db (fake-db)
+                  progress-calls (atom [])
+                  idle-status-atom (:thread-atom/search-input-idle-status @worker-state/*state)]
+              (d/transact! conn [{:block/uuid (random-uuid)}])
+              (reset! worker-state/*sqlite-conns {test-repo {:search search-db}})
+              (reset! worker-state/*datascript-conns {test-repo conn})
+              (reset! idle-status-atom {test-repo {:idle? true
+                                                   :ts (.now js/Date)}})
+              (reset! worker-state/*main-thread
+                      (fn [qkw direct-pass? & args]
+                        (when (= qkw :thread-api/search-index-build-progress)
+                          (let [[repo payload] args]
+                            (swap! progress-calls conj {:qkw qkw
+                                                        :direct-pass? direct-pass?
+                                                        :repo repo
+                                                        :payload payload})))
+                        (p/resolved nil)))
+              (with-redefs [search/truncate-table! (fn [_db] nil)
+                            search/upsert-blocks! (fn [_db _blocks] nil)
+                            search/hidden-entity? (constantly false)
+                            search/block->index (fn [_entity]
+                                                  {:id "block-1"
+                                                   :page "page-1"
+                                                   :title "Hello"})]
+                (-> (build-index! test-repo true)
+                    (p/then (fn [_]
+                              (let [statuses (map (comp :status :payload) @progress-calls)
+                                    completed (some #(when (= :completed (get-in % [:payload :status]))
+                                                       %)
+                                                    @progress-calls)]
+                                (is (= false (:direct-pass? (first @progress-calls))))
+                                (is (= test-repo (:repo (first @progress-calls))))
+                                (is (= :running (first statuses)))
+                                (is (some #{:completed} statuses))
+                                (is (= :idle (last statuses)))
+                                (is (= 1 (get-in completed [:payload :processed])))
+                                (is (= 1 (get-in completed [:payload :total]))))))
+                    (p/catch (fn [error]
+                               (is false (str error))))
+                    (p/finally done))))))))
+
+(deftest release-access-handles-clears-active-import-state-test
+  (restoring-worker-state
+   (fn []
+     (let [release-access-handles! (get @thread-api/*thread-apis :thread-api/release-access-handles)
+           *import-state @#'sync-download/*import-state
+           import-state-prev @*import-state
+           closed (atom [])
+           removed-pools (atom [])
+           pause-calls (atom 0)]
+       (try
+         (platform/set-platform! (build-test-platform {:remove-vfs! (fn [pool]
+                                                                      (swap! removed-pools conj pool)
+                                                                      (p/resolved nil))}))
+         (reset! worker-state/*opfs-pools {test-repo #js {:pauseVfs (fn [] (swap! pause-calls inc))}})
+         (reset! *import-state {:repo test-repo
+                                :graph-id "graph-1"
+                                :import-id "import-1"
+                                :rows-db #js {:close (fn [] (swap! closed conj :rows-db))}
+                                :rows-pool :rows-pool})
+
+         (release-access-handles! test-repo)
+
+         (is (nil? @*import-state))
+         (is (= [:rows-db] @closed))
+         (is (= [:rows-pool] @removed-pools))
+         (is (= 1 @pause-calls))
+         (finally
+           (reset! *import-state import-state-prev)))))))
+
+(deftest close-db-clears-active-import-state-test
+  (restoring-worker-state
+   (fn []
+     (let [*import-state @#'sync-download/*import-state
+           import-state-prev @*import-state
+           closed (atom [])
+           removed-pools (atom [])
+           pause-calls (atom 0)]
+       (try
+         (platform/set-platform! (build-test-platform {:remove-vfs! (fn [pool]
+                                                                      (swap! removed-pools conj pool)
+                                                                      (p/resolved nil))}))
+         (reset! worker-state/*sqlite-conns
+                 {test-repo {:db (fake-db {:close-calls closed :close-label :db})
+                             :search (fake-db {:close-calls closed :close-label :search})
+                             :client-ops (fake-db {:close-calls closed :close-label :client-ops})}})
+         (reset! worker-state/*datascript-conns {test-repo :datascript})
+         (reset! worker-state/*client-ops-conns {test-repo :client-ops})
+         (reset! worker-state/*opfs-pools {test-repo #js {:pauseVfs (fn [] (swap! pause-calls inc))}})
+         (reset! *import-state {:repo test-repo
+                                :graph-id "graph-1"
+                                :import-id "import-1"
+                                :rows-db #js {:close (fn [] (swap! closed conj :rows-db))}
+                                :rows-pool :rows-pool})
+
+         (db-core/close-db! test-repo)
+
+         (is (nil? @*import-state))
+         (is (= #{:rows-db :db :search :client-ops} (set @closed)))
+         (is (= [:rows-pool] @removed-pools))
+         (is (= 1 @pause-calls))
+         (finally
+           (reset! *import-state import-state-prev)))))))
diff --git a/src/test/frontend/worker/db_sync_test.cljs b/src/test/frontend/worker/db_sync_test.cljs
index bec77f424e..ea3e751b4d 100644
--- a/src/test/frontend/worker/db_sync_test.cljs
+++ b/src/test/frontend/worker/db_sync_test.cljs
@@ -8,11 +8,13 @@
    [frontend.worker-common.util :as worker-util]
    [frontend.worker.handler.page :as worker-page]
    [frontend.worker.pipeline :as worker-pipeline]
+   [frontend.worker.platform :as platform]
    [frontend.worker.shared-service :as shared-service]
    [frontend.worker.state :as worker-state]
    [frontend.worker.sync :as db-sync]
    [frontend.worker.sync.apply-txs :as sync-apply]
    [frontend.worker.sync.assets :as sync-assets]
+   [frontend.worker.sync.auth :as sync-auth]
    [frontend.worker.sync.client-op :as client-op]
    [frontend.worker.sync.crypt :as sync-crypt]
    [frontend.worker.sync.handle-message :as sync-handle-message]
@@ -21,7 +23,7 @@
    [frontend.worker.sync.presence :as sync-presence]
    [frontend.worker.sync.temp-sqlite :as sync-temp-sqlite]
    [frontend.worker.sync.transport :as sync-transport]
-   [frontend.worker.sync.upload :as sync-upload]
+   [frontend.worker.sync.util :as sync-util]
    [frontend.test.noise :as test-noise]
    [frontend.worker.undo-redo :as undo-redo]
    [logseq.common.config :as common-config]
@@ -33,7 +35,6 @@
    [logseq.db-sync.worker.handler.sync :as sync-handler]
    [logseq.db-sync.worker.ws :as ws]
    [logseq.db.common.normalize :as db-normalize]
-   [logseq.db.common.sqlite :as common-sqlite]
    [logseq.db.frontend.validate :as db-validate]
    [logseq.db.sqlite.util :as sqlite-util]
    [logseq.db.test.helper :as db-test]
@@ -396,54 +397,97 @@
 
 (deftest resolve-ws-token-refreshes-when-token-expired-test
   (async done
-         (let [refresh-calls (atom 0)
+         (let [fetch-calls (atom [])
+               main-thread-calls (atom 0)
                main-thread-prev @worker-state/*main-thread
-               worker-state-prev @worker-state/*state]
-           (reset! worker-state/*state (assoc worker-state-prev :auth/id-token "expired-token"))
-           (reset! worker-state/*main-thread
-                   (fn [qkw _direct-pass? _args-list]
-                     (if (= qkw :thread-api/ensure-id&access-token)
-                       (do
-                         (swap! refresh-calls inc)
-                         (p/resolved {:id-token "fresh-token"}))
-                       (p/resolved nil))))
-           (with-redefs [db-sync/auth-token (fn [] "expired-token")
-                         db-sync/id-token-expired? (fn [_token] true)]
-             (-> (#'db-sync/<resolve-ws-token)
-                 (p/then (fn [token]
-                           (is (= 1 @refresh-calls))
-                           (is (= "fresh-token" token))
-                           (is (= "fresh-token" (worker-state/get-id-token)))
-                           (reset! worker-state/*main-thread main-thread-prev)
-                           (reset! worker-state/*state worker-state-prev)
-                           (done)))
-                 (p/catch (fn [error]
-                            (reset! worker-state/*main-thread main-thread-prev)
-                            (reset! worker-state/*state worker-state-prev)
-                            (is nil (str error))
-                            (done))))))))
-
-(deftest resolve-ws-token-skips-refresh-when-token-not-expired-test
-  (async done
-         (let [refresh-calls (atom 0)
-               main-thread-prev @worker-state/*main-thread]
+               worker-state-prev @worker-state/*state
+               sync-config-prev @worker-state/*db-sync-config
+               fetch-prev js/fetch]
+           (reset! worker-state/*db-sync-config {:feature-flags {:worker-auth-refresh? true}})
+           (reset! worker-state/*state (assoc worker-state-prev
+                                              :auth/id-token "expired-token"
+                                              :auth/refresh-token "refresh-token"
+                                              :auth/oauth-token-url "https://auth.example.com/oauth2/token"
+                                              :auth/oauth-client-id "worker-client-id"))
            (reset! worker-state/*main-thread
                    (fn [qkw _direct-pass? _args-list]
                      (when (= qkw :thread-api/ensure-id&access-token)
-                       (swap! refresh-calls inc))
-                     (p/resolved {:id-token "fresh-token"})))
-           (with-redefs [db-sync/auth-token (fn [] "valid-token")
-                         db-sync/id-token-expired? (fn [_token] false)]
+                       (swap! main-thread-calls inc))
+                     (p/resolved {:id-token "legacy-token"})))
+           (set! js/fetch
+                 (fn [url opts]
+                   (swap! fetch-calls conj {:url url :opts opts})
+                   (let [resp (js-obj)]
+                     (aset resp "ok" true)
+                     (aset resp "status" 200)
+                     (aset resp "text"
+                           (fn []
+                             (p/resolved "{\"id_token\":\"fresh-worker-token\",\"access_token\":\"fresh-worker-access-token\"}")))
+                     (p/resolved resp))))
+           (with-redefs [sync-util/auth-token (fn [] "expired-token")
+                         sync-auth/id-token-expired? (fn [_token] true)]
              (-> (#'db-sync/<resolve-ws-token)
                  (p/then (fn [token]
-                           (reset! worker-state/*main-thread main-thread-prev)
-                           (is (= 0 @refresh-calls))
-                           (is (= "valid-token" token))
-                           (done)))
+                           (is (= 1 (count @fetch-calls)))
+                           (is (= 0 @main-thread-calls))
+                           (is (= "fresh-worker-token" token))
+                           (is (= "fresh-worker-token" (worker-state/get-id-token)))
+                           (is (= "fresh-worker-access-token"
+                                  (:auth/access-token @worker-state/*state)))))
                  (p/catch (fn [error]
-                            (reset! worker-state/*main-thread main-thread-prev)
-                            (is nil (str error))
-                            (done))))))))
+                            (is nil (str error))))
+                 (p/finally (fn []
+                              (set! js/fetch fetch-prev)
+                              (reset! worker-state/*main-thread main-thread-prev)
+                              (reset! worker-state/*state worker-state-prev)
+                              (reset! worker-state/*db-sync-config sync-config-prev)
+                              (done))))))))
+
+(deftest resolve-ws-token-does-not-fallback-to-main-thread-when-feature-flag-disabled-test
+  (async done
+         (let [fetch-calls (atom 0)
+               main-thread-calls (atom 0)
+               main-thread-prev @worker-state/*main-thread
+               worker-state-prev @worker-state/*state
+               sync-config-prev @worker-state/*db-sync-config
+               fetch-prev js/fetch]
+           (reset! worker-state/*db-sync-config {:feature-flags {:worker-auth-refresh? false}})
+           (reset! worker-state/*state (assoc worker-state-prev
+                                              :auth/id-token "expired-token"
+                                              :auth/refresh-token "refresh-token"
+                                              :auth/oauth-token-url "https://auth.example.com/oauth2/token"
+                                              :auth/oauth-client-id "worker-client-id"))
+           (reset! worker-state/*main-thread
+                   (fn [qkw _direct-pass? _args-list]
+                     (when (= qkw :thread-api/ensure-id&access-token)
+                       (swap! main-thread-calls inc))
+                     (p/resolved {:id-token "fresh-legacy-token"})))
+           (set! js/fetch
+                 (fn [_url _opts]
+                   (swap! fetch-calls inc)
+                   (let [resp (js-obj)]
+                     (aset resp "ok" true)
+                     (aset resp "status" 200)
+                     (aset resp "text"
+                           (fn []
+                             (p/resolved "{\"id_token\":\"fresh-worker-token-2\",\"access_token\":\"fresh-worker-access-token-2\"}")))
+                     (p/resolved resp))))
+           (with-redefs [sync-util/auth-token (fn [] "expired-token")
+                         sync-auth/id-token-expired? (fn [_token] true)]
+             (-> (#'db-sync/<resolve-ws-token)
+                 (p/then (fn [token]
+                           (is (= 1 @fetch-calls))
+                           (is (= 0 @main-thread-calls))
+                           (is (= "fresh-worker-token-2" token))
+                           (is (= "fresh-worker-token-2" (worker-state/get-id-token)))))
+                 (p/catch (fn [error]
+                            (is nil (str error))))
+                 (p/finally (fn []
+                              (set! js/fetch fetch-prev)
+                              (reset! worker-state/*main-thread main-thread-prev)
+                              (reset! worker-state/*state worker-state-prev)
+                              (reset! worker-state/*db-sync-config sync-config-prev)
+                              (done))))))))
 
 (deftest update-online-users-dedupes-identical-messages-test
   (let [client {:repo test-repo
@@ -634,23 +678,6 @@
                         test-repo)]
             (is (= 1 (:pending-local counts)))))))))
 
-(deftest upload-graph-metadata-write-is-not-persisted-as-local-sync-tx-test
-  (let [captured (atom nil)
-        fake-conn (atom :db)]
-    (with-redefs [worker-state/get-datascript-conn (fn [_repo] fake-conn)
-                  ldb/transact! (fn [conn tx-data tx-meta]
-                                  (reset! captured {:conn conn
-                                                    :tx-data tx-data
-                                                    :tx-meta tx-meta})
-                                  nil)]
-      (sync-upload/set-graph-sync-metadata! test-repo true))
-    (is (= fake-conn (:conn @captured)))
-    (is (= [{:db/ident :logseq.kv/graph-remote? :kv/value true}
-            {:db/ident :logseq.kv/graph-rtc-e2ee? :kv/value true}]
-           (:tx-data @captured)))
-    (is (= {:persist-op? false}
-           (:tx-meta @captured)))))
-
 (deftest pull-ok-with-older-remote-tx-is-ignored-test
   (testing "pull/ok with remote tx behind local tx does not apply stale tx data"
     (let [{:keys [conn client-ops-conn parent]} (setup-parent-child)
@@ -1674,8 +1701,8 @@
                                                                :keep-uuid? true}]]]]
              :db-sync/normalized-tx-data []
              :db-sync/reversed-tx-data []}])
-          (with-redefs [sync-apply/fail-fast (fn [_tag data]
-                                               (throw (ex-info "fail-fast-called" data)))]
+          (with-redefs [sync-util/fail-fast (fn [_tag data]
+                                              (throw (ex-info "fail-fast-called" data)))]
             (let [result (#'sync-apply/apply-history-action! test-repo tx-id false {})]
               (is (= false (:applied? result)))
               (is (= :invalid-history-action-ops
@@ -4529,40 +4556,55 @@
 (deftest create-temp-sqlite-db-uses-opfs-pool-test
   (testing "temp upload db should use an OPFS-backed sqlite db instead of :memory:"
     (async done
-           (let [opened-paths (atom [])]
-             (with-redefs [sync-temp-sqlite/<get-upload-temp-sqlite-pool
-                           (fn []
-                             (p/resolved
-                              #js {:OpfsSAHPoolDb
-                                   (fn [path]
-                                     (swap! opened-paths conj path)
-                                     #js {:close (fn [] nil)})}))
-                           common-sqlite/create-kvs-table! (fn [_] nil)]
-               (-> (p/let [{:keys [db path]} (sync-temp-sqlite/<create-temp-sqlite-db!
-                                              {:get-pool-f sync-temp-sqlite/<get-upload-temp-sqlite-pool
-                                               :upload-path-f sync-temp-sqlite/upload-temp-sqlite-path})]
-                     (is (some? db))
-                     (is (= [path] @opened-paths))
-                     (is (string/includes? path "upload-"))
-                     (is (string/ends-with? path ".sqlite")))
-                   (p/finally done)))))))
-
-(deftest cleanup-temp-sqlite-removes-opfs-file-test
-  (testing "temp upload db cleanup should close the db and remove the temp OPFS file"
-    (async done
-           (let [closed? (atom false)
-                 removed-paths (atom [])]
-             (with-redefs [sync-temp-sqlite/<remove-upload-temp-sqlite-db-file!
-                           (fn [path]
-                             (swap! removed-paths conj path)
-                             (p/resolved nil))]
-               (-> (p/let [_ (sync-temp-sqlite/cleanup-temp-sqlite!
-                              {:db #js {:close (fn [] (reset! closed? true))}
-                               :path "/upload-temp.sqlite"}
-                              sync-temp-sqlite/<remove-upload-temp-sqlite-db-file!)]
-                     (is @closed?)
-                     (is (= ["/upload-temp.sqlite"] @removed-paths)))
-                   (p/finally done)))))))
+           (let [sqlite-prev @worker-state/*sqlite
+                 platform-prev (try
+                                 (platform/current)
+                                 (catch :default _ nil))
+                 sqlite #js {:sqlite? true}
+                 pool #js {:pool? true}
+                 opened-opts (atom [])
+                 installed-pools (atom [])
+                 test-platform {:env {:runtime :node
+                                      :owner-source :test}
+                                :storage {:install-opfs-pool (fn [sqlite* pool-name]
+                                                               (swap! installed-pools conj {:sqlite sqlite*
+                                                                                            :pool-name pool-name})
+                                                               pool)
+                                          :resolve-db-path (fn [repo _pool suffix]
+                                                             (str "/tmp/" repo suffix))
+                                          :remove-vfs! (fn [_pool] nil)}
+                                :kv {:get (fn [_] nil)
+                                     :set! (fn [_ _] nil)}
+                                :broadcast {:post-message! (fn [_ _] nil)}
+                                :websocket {:connect (fn [_] nil)}
+                                :crypto {}
+                                :timers {}
+                                :sqlite {:init! (fn [] nil)
+                                         :open-db (fn [opts]
+                                                    (swap! opened-opts conj opts)
+                                                    #js {:close (fn [] nil)
+                                                         :exec (fn [& _] nil)})}}]
+             (platform/set-platform! test-platform)
+             (reset! worker-state/*sqlite sqlite)
+             (-> (p/let [{:keys [db path]} (sync-temp-sqlite/<create-temp-sqlite-db!)]
+                   (is (some? db))
+                   (is (= [{:sqlite sqlite
+                            :pool-name sync-temp-sqlite/upload-temp-pool-name}]
+                          @installed-pools))
+                   (is (= [{:sqlite sqlite
+                            :pool pool
+                            :path path
+                            :mode "c"}]
+                          @opened-opts))
+                   (is (string/includes? path "upload-"))
+                   (is (string/ends-with? path ".sqlite")))
+                 (p/catch (fn [e]
+                            (is false (str e))))
+                 (p/finally (fn []
+                              (reset! worker-state/*sqlite sqlite-prev)
+                              (when platform-prev
+                                (platform/set-platform! platform-prev))
+                              (done))))))))
 
 (deftest upload-large-title-encrypts-transit-payload-test
   (testing "encrypted large title uploads transit-encoded payload"
@@ -4673,9 +4715,6 @@
                                       :download-fn download-fn
                                       :aes-key nil
                                       :get-conn-f worker-state/get-datascript-conn
-                                      :get-graph-id-f (fn [repo]
-                                                        (sync-large-title/get-graph-id
-                                                         worker-state/get-datascript-conn repo))
                                       :graph-e2ee?-f sync-crypt/graph-e2ee?
                                       :ensure-graph-aes-key-f sync-crypt/<ensure-graph-aes-key
                                       :fail-fast-f db-sync/fail-fast})
diff --git a/src/test/frontend/worker/db_worker_node_lock_test.cljs b/src/test/frontend/worker/db_worker_node_lock_test.cljs
new file mode 100644
index 0000000000..7b81171312
--- /dev/null
+++ b/src/test/frontend/worker/db_worker_node_lock_test.cljs
@@ -0,0 +1,116 @@
+(ns frontend.worker.db-worker-node-lock-test
+  (:require ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]
+            [cljs.test :refer [async deftest is testing]]
+            [frontend.test.node-helper :as node-helper]
+            [frontend.worker.db-worker-node-lock :as db-lock]
+            [promesa.core :as p]))
+
+(deftest repo-dir-canonicalizes-db-prefixed-repo
+  (testing "db-prefixed repo name resolves to prefix-free graph directory key"
+    (let [graphs-dir "/tmp/logseq-db-worker-node-lock/graphs"
+          expected (node-path/join graphs-dir "demo")]
+      (is (= expected (db-lock/repo-dir graphs-dir "logseq_db_demo"))))))
+
+(deftest repo-dir-canonicalizes-prefix-free-repo
+  (testing "prefix-free repo name resolves to same graph directory key"
+    (let [graphs-dir "/tmp/logseq-db-worker-node-lock/graphs"
+          expected (node-path/join graphs-dir "demo")]
+      (is (= expected (db-lock/repo-dir graphs-dir "demo"))))))
+
+(deftest repo-dir-does-not-migrate-legacy-prefixed-dir
+  (testing "canonical resolution does not rename legacy prefixed directories"
+    (let [root-dir (node-helper/create-tmp-dir "db-worker-node-lock")
+          graphs-dir (node-path/join root-dir "graphs")
+          legacy-dir (node-path/join graphs-dir "logseq_db_demo")
+          canonical-dir (node-path/join graphs-dir "demo")]
+      (fs/mkdirSync legacy-dir #js {:recursive true})
+      (is (= canonical-dir (db-lock/repo-dir graphs-dir "logseq_db_demo")))
+      (is (fs/existsSync legacy-dir))
+      (is (not (fs/existsSync canonical-dir))))))
+
+(deftest lock-path-default-root-dir-uses-canonical-graph-dir
+  (testing "default root-dir lock path is built under <root-dir>/graphs with canonical <graph> directory naming"
+    (let [default-root-dir (db-lock/resolve-root-dir nil)
+          expected-root-dir (node-path/join (.homedir os) "logseq")
+          expected-graphs-dir (node-path/join expected-root-dir "graphs")
+          expected-lock-path (node-path/join expected-graphs-dir "demo" "db-worker.lock")]
+      (is (= expected-root-dir default-root-dir))
+      (is (= expected-lock-path (db-lock/lock-path default-root-dir "logseq_db_demo"))))))
+
+(deftest create-lock-persists-owner-source
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "db-worker-node-lock-owner")
+          repo (str "logseq_db_lock_owner_" (subs (str (random-uuid)) 0 8))
+          path (db-lock/lock-path root-dir repo)]
+      (-> (p/let [_ (db-lock/create-lock! {:root-dir root-dir
+                                           :repo repo
+                                           :owner-source :cli})
+                  lock (db-lock/read-lock path)]
+            (is (= :cli (:owner-source lock))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (db-lock/remove-lock! path)
+                       (done)))))))
+
+(deftest create-lock-does-not-persist-server-discovery-fields
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "db-worker-node-lock-minimal")
+          repo (str "logseq_db_lock_minimal_" (subs (str (random-uuid)) 0 8))
+          path (db-lock/lock-path root-dir repo)]
+      (-> (p/let [_ (db-lock/create-lock! {:root-dir root-dir
+                                           :repo repo
+                                           :owner-source :cli})
+                  lock (db-lock/read-lock path)]
+            (is (= repo (:repo lock)))
+            (is (integer? (:pid lock)))
+            (is (string? (:lock-id lock)))
+            (is (= :cli (:owner-source lock)))
+            (is (nil? (:host lock)))
+            (is (nil? (:port lock)))
+            (is (nil? (:revision lock)))
+            (is (nil? (:startedAt lock))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (db-lock/remove-lock! path)
+                       (done)))))))
+
+(deftest read-lock-normalizes-missing-owner-source-to-unknown
+  (let [root-dir (node-helper/create-tmp-dir "db-worker-node-lock-legacy-owner")
+        repo (str "logseq_db_lock_legacy_" (subs (str (random-uuid)) 0 8))
+        path (db-lock/lock-path root-dir repo)
+        legacy-lock {:repo repo
+                     :pid (.-pid js/process)
+                     :lock-id (str (random-uuid))}]
+    (fs/mkdirSync (node-path/dirname path) #js {:recursive true})
+    (fs/writeFileSync path (js/JSON.stringify (clj->js legacy-lock)))
+    (is (= :unknown (:owner-source (db-lock/read-lock path))))))
+
+(deftest update-lock-preserves-existing-owner-source-and-does-not-add-discovery-fields
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "db-worker-node-lock-update-owner")
+          repo (str "logseq_db_lock_update_owner_" (subs (str (random-uuid)) 0 8))
+          path (db-lock/lock-path root-dir repo)]
+      (-> (p/let [{:keys [lock]} (db-lock/ensure-lock! {:root-dir root-dir
+                                                        :repo repo
+                                                        :owner-source :cli})
+                  _ (db-lock/update-lock! path (assoc lock
+                                                      :owner-source :electron
+                                                      :host "127.0.0.1"
+                                                      :port 9200
+                                                      :revision "attempted-new-revision"
+                                                      :startedAt "2024-01-01T00:00:00.000Z"))
+                  updated (db-lock/read-lock path)]
+            (is (= :cli (:owner-source updated)))
+            (is (nil? (:host updated)))
+            (is (nil? (:port updated)))
+            (is (nil? (:revision updated)))
+            (is (nil? (:startedAt updated))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (db-lock/remove-lock! path)
+                       (done)))))))
diff --git a/src/test/frontend/worker/db_worker_node_test.cljs b/src/test/frontend/worker/db_worker_node_test.cljs
new file mode 100644
index 0000000000..621e7beed4
--- /dev/null
+++ b/src/test/frontend/worker/db_worker_node_test.cljs
@@ -0,0 +1,1367 @@
+(ns frontend.worker.db-worker-node-test
+  (:require ["fs" :as fs]
+            ["http" :as http]
+            ["path" :as node-path]
+            [cljs.test :refer [async deftest is use-fixtures]]
+            [clojure.string :as string]
+            [frontend.test.node-helper :as node-helper]
+            [frontend.worker.db-core :as db-core]
+            [frontend.worker.db-worker-node :as db-worker-node]
+            [frontend.worker.db-worker-node-lock :as db-lock]
+            [frontend.worker.platform.node :as platform-node]
+            [goog.object :as gobj]
+            [logseq.cli.config :as cli-config]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.style :as style]
+            [logseq.cli.test-helper :as test-helper]
+            [logseq.common.config :as common-config]
+            [logseq.db :as ldb]
+            [promesa.core :as p]))
+
+(defn- http-request
+  [opts body]
+  (p/create
+   (fn [resolve reject]
+     (let [req (.request http (clj->js opts)
+                         (fn [^js res]
+                           (let [chunks (array)]
+                             (.on res "data" (fn [chunk] (.push chunks chunk)))
+                             (.on res "end" (fn []
+                                              (resolve {:status (.-statusCode res)
+                                                        :body (.toString (js/Buffer.concat chunks) "utf8")}))))))
+           finish! (fn []
+                     (when body (.write req body))
+                     (.end req))]
+       (.on req "error" reject)
+       (finish!)))))
+
+(defn- escape-regex
+  [value]
+  (let [pattern (js/RegExp. "[.*+?^${}()|[\\]\\\\]" "g")]
+    (string/replace value pattern "\\\\$&")))
+
+(defn- contains-bold?
+  [value token]
+  (let [token (escape-regex token)
+        pattern (re-pattern (str "\\u001b\\[[0-9;]*m" token "\\u001b\\[[0-9;]*m"))]
+    (boolean (re-find pattern value))))
+
+(defn- http-get
+  [host port path]
+  (http-request {:hostname host
+                 :port port
+                 :path path
+                 :method "GET"}
+                nil))
+
+(defn- invoke
+  [host port method args]
+  (let [payload (js/JSON.stringify
+                 (clj->js {:method method
+                           :directPass false
+                           :argsTransit (ldb/write-transit-str args)}))]
+    (p/let [{:keys [status body]}
+            (http-request {:hostname host
+                           :port port
+                           :path "/v1/invoke"
+                           :method "POST"
+                           :headers {"Content-Type" "application/json"}}
+                          payload)
+            parsed (js->clj (js/JSON.parse body) :keywordize-keys true)]
+      (when (not= 200 status)
+        (println "[db-worker-node-test] invoke failed"
+                 {:method method
+                  :status status
+                  :body body}))
+      (is (= 200 status))
+      (is (:ok parsed))
+      (ldb/read-transit-str (:resultTransit parsed)))))
+
+(defn- invoke-raw
+  [host port method args]
+  (let [payload (js/JSON.stringify
+                 (clj->js {:method method
+                           :directPass false
+                           :argsTransit (ldb/write-transit-str args)}))]
+    (http-request {:hostname host
+                   :port port
+                   :path "/v1/invoke"
+                   :method "POST"
+                   :headers {"Content-Type" "application/json"}}
+                  payload)))
+
+(defn- lock-path
+  [root-dir repo]
+  (db-lock/lock-path root-dir repo))
+
+(defn- pad2
+  [value]
+  (if (< value 10)
+    (str "0" value)
+    (str value)))
+
+(defn- yyyymmdd
+  [^js date]
+  (str (.getFullYear date)
+       (pad2 (inc (.getMonth date)))
+       (pad2 (.getDate date))))
+
+(defn- log-path
+  [root-dir repo]
+  (let [repo-dir (db-lock/repo-dir (db-lock/graphs-dir root-dir) repo)
+        date-str (yyyymmdd (js/Date.))]
+    (node-path/join repo-dir (str "db-worker-node-" date-str ".log"))))
+
+(defn- start-daemon!
+  "Start daemon with quiet logging by default"
+  [opts]
+  (db-worker-node/start-daemon! (update opts :log-level #(or % "error"))))
+
+(defn- noisy-debug-line?
+  [line]
+  (or (string/includes? line ":listen-db-changes!")
+      (string/includes? line ":debug :db-gc")))
+
+(defonce ^:private *orig-print-fn (atom nil))
+
+(defn- quiet-debug-output-before
+  []
+  (when-not @*orig-print-fn
+    (reset! *orig-print-fn *print-fn*))
+  (set-print-fn!
+   (fn [line]
+     (when-not (and (string? line) (noisy-debug-line? line))
+       (when-let [orig @*orig-print-fn]
+         (orig line))))))
+
+(defn- quiet-debug-output-after
+  []
+  (when-let [orig @*orig-print-fn]
+    (set-print-fn! orig)))
+
+(defn- reset-daemon-state!
+  []
+  (reset! @#'db-worker-node/*ready? false)
+  (reset! @#'db-worker-node/*sse-clients #{})
+  (reset! @#'db-worker-node/*lock-info nil)
+  (reset! @#'db-worker-node/*file-handler nil))
+
+(defn- normalize-db-worker-state-before
+  []
+  (quiet-debug-output-before)
+  (reset-daemon-state!))
+
+(defn- normalize-db-worker-state-after
+  []
+  (reset-daemon-state!)
+  (quiet-debug-output-after))
+
+(defn- run-main-with-overrides
+  [{:keys [argv on-exit on-log on-error start-daemon-fn]}]
+  (test-helper/with-js-property-override
+    js/process
+    "argv"
+    argv
+    (fn []
+      (test-helper/with-js-property-override
+        js/process
+        "exit"
+        on-exit
+        (fn []
+          (test-helper/with-js-property-override
+            js/console
+            "log"
+            on-log
+            (fn []
+              (test-helper/with-js-property-override
+                js/console
+                "error"
+                on-error
+                (fn []
+                  (p/with-redefs [db-worker-node/start-daemon! start-daemon-fn]
+                    (p/resolved
+                     (try
+                       (db-worker-node/main)
+                       (catch :default e
+                         (when-not (= "process-exit" (.-message e))
+                           (throw e)))))))))))))))
+
+(use-fixtures :each {:before normalize-db-worker-state-before
+                     :after normalize-db-worker-state-after})
+
+(deftest db-worker-node-root-dir-permission-error
+  (async done
+         (if (= "win32" (.-platform js/process))
+           (done)
+           (let [data-dir (node-helper/create-tmp-dir "db-worker-readonly")
+                 repo (str "logseq_db_perm_" (subs (str (random-uuid)) 0 8))]
+             (fs/chmodSync data-dir 365)
+             (-> (start-daemon! {:root-dir data-dir
+                                 :repo repo})
+                 (p/then (fn [_]
+                           (is false "expected root-dir permission error")))
+                 (p/catch (fn [e]
+                            (let [data (ex-data e)]
+                              (is (= :root-dir-permission (:code data)))
+                              (is (= (node-path/resolve data-dir) (:path data))))))
+                 (p/finally (fn [] (done))))))))
+
+(deftest db-worker-node-creates-log-file
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-log")
+               repo (str "logseq_db_log_" (subs (str (random-uuid)) 0 8))
+               log-file (log-path data-dir repo)]
+           (-> (p/let [{:keys [stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       _ (p/delay 50)]
+                 (is (fs/existsSync log-file)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-log-file-has-entries
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-log-entries")
+               repo (str "logseq_db_log_entries_" (subs (str (random-uuid)) 0 8))
+               log-file (log-path data-dir repo)]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       {:keys [status]} (invoke-raw host port "thread-api/not-found" [repo nil])
+                       _ (p/delay 50)
+                       contents (when (fs/existsSync log-file)
+                                  (.toString (fs/readFileSync log-file) "utf8"))]
+                 (is (= 500 status))
+                 (is (fs/existsSync log-file))
+                 (is (pos? (count contents))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-log-retention
+  (let [enforce-log-retention! #'db-worker-node/enforce-log-retention!
+        data-dir (node-helper/create-tmp-dir "db-worker-log-retention")
+        repo (str "logseq_db_log_retention_" (subs (str (random-uuid)) 0 8))
+        repo-dir (db-lock/repo-dir data-dir repo)
+        days ["20240101" "20240102" "20240103" "20240104" "20240105"
+              "20240106" "20240107" "20240108" "20240109"]
+        make-log (fn [day]
+                   (node-path/join repo-dir (str "db-worker-node-" day ".log")))]
+    (fs/mkdirSync repo-dir #js {:recursive true})
+    (doseq [day days]
+      (fs/writeFileSync (make-log day) "log\n"))
+    (enforce-log-retention! repo-dir)
+    (let [remaining (->> (fs/readdirSync repo-dir)
+                         (filter (fn [^js name]
+                                   (re-matches #"db-worker-node-\d{8}\.log" name)))
+                         (sort))]
+      (is (= 7 (count remaining)))
+      (is (= ["db-worker-node-20240103.log"
+              "db-worker-node-20240104.log"
+              "db-worker-node-20240105.log"
+              "db-worker-node-20240106.log"
+              "db-worker-node-20240107.log"
+              "db-worker-node-20240108.log"
+              "db-worker-node-20240109.log"]
+             remaining)))))
+
+(deftest db-worker-node-parse-args-ignores-host-and-port
+  (let [parse-args #'db-worker-node/parse-args
+        result (parse-args #js ["node" "dist/db-worker-node.js"
+                                "--host" "0.0.0.0"
+                                "--port" "1234"
+                                "--repo" "logseq_db_parse_args"
+                                "--root-dir" "/tmp/logseq-root"])]
+    (is (nil? (:host result)))
+    (is (nil? (:port result)))
+    (is (= "logseq_db_parse_args" (:repo result)))
+    (is (= "/tmp/logseq-root" (:root-dir result)))))
+
+(deftest db-worker-node-parse-args-ignores-auth-token
+  (let [parse-args #'db-worker-node/parse-args
+        result (parse-args #js ["node" "dist/db-worker-node.js"
+                                "--auth-token" "secret"
+                                "--root-dir" "/tmp/logseq-root"])]
+    (is (nil? (:auth-token result)))
+    (is (= "/tmp/logseq-root" (:root-dir result)))))
+
+(deftest db-worker-node-parse-args-ignores-rtc-ws-url
+  (let [parse-args #'db-worker-node/parse-args
+        result (parse-args #js ["node" "dist/db-worker-node.js"
+                                "--rtc-ws-url" "ws://example.com"
+                                "--repo" "logseq_db_parse_args"])]
+    (is (nil? (:rtc-ws-url result)))
+    (is (= "logseq_db_parse_args" (:repo result)))))
+
+(deftest db-worker-node-parse-args-recognizes-create-empty-db
+  (let [parse-args #'db-worker-node/parse-args
+        result (parse-args #js ["node" "dist/db-worker-node.js"
+                                "--repo" "logseq_db_parse_args"
+                                "--create-empty-db"])]
+    (is (= "logseq_db_parse_args" (:repo result)))
+    (is (= true (:create-empty-db? result)))))
+
+(deftest db-worker-node-parse-args-ignores-server-list-file
+  (let [parse-args #'db-worker-node/parse-args
+        result (parse-args #js ["node" "dist/db-worker-node.js"
+                                "--repo" "logseq_db_parse_args"
+                                "--root-dir" "/tmp/logseq-root"
+                                "--server-list-file" "/tmp/server-list"])]
+    (is (= "logseq_db_parse_args" (:repo result)))
+    (is (= "/tmp/logseq-root" (:root-dir result)))
+    (is (nil? (:server-list-file result)))))
+
+(deftest db-worker-node-parse-args-recognizes-version
+  (let [parse-args #'db-worker-node/parse-args
+        result (parse-args #js ["node" "dist/db-worker-node.js"
+                                "--version"])]
+    (is (= true (:version? result)))
+    (is (nil? (:repo result)))))
+
+(deftest db-worker-node-main-version-exits-early-without-repo
+  (async done
+         (let [exit-code* (atom nil)
+               start-called? (atom false)]
+           (-> (test-helper/with-js-property-override
+                 js/process
+                 "argv"
+                 #js ["node" "dist/db-worker-node.js" "--version"]
+                 (fn []
+                   (test-helper/with-js-property-override
+                     js/process
+                     "exit"
+                     (fn [code]
+                       (reset! exit-code* code)
+                       (throw (ex-info "process-exit" {:code code})))
+                     (fn []
+                       (p/with-redefs [db-worker-node/start-daemon! (fn [_]
+                                                                      (reset! start-called? true)
+                                                                      (p/rejected (ex-info "should-not-start-daemon" {})))]
+                         (p/resolved
+                          (let [output (with-out-str
+                                         (try
+                                           (db-worker-node/main)
+                                           (catch :default e
+                                             (when-not (= "process-exit" (.-message e))
+                                               (throw e)))))]
+                            (is (= 0 @exit-code*))
+                            (is (= false @start-called?))
+                            (is (string/includes? output "Revision:")))))))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest db-worker-node-main-missing-root-dir-prints-error-and-exits-1
+  (async done
+         (let [exit-code* (atom nil)
+               stdout* (atom [])
+               stderr* (atom [])
+               start-called? (atom false)]
+           (-> (run-main-with-overrides
+                {:argv #js ["node" "dist/db-worker-node.js" "--repo" "logseq_db_missing_root"]
+                 :on-exit (fn [code]
+                            (reset! exit-code* code)
+                            (throw (ex-info "process-exit" {:code code})))
+                 :on-log (fn [& args]
+                           (swap! stdout* conj (string/join " " args)))
+                 :on-error (fn [& args]
+                             (swap! stderr* conj (string/join " " args)))
+                 :start-daemon-fn (fn [_]
+                                    (reset! start-called? true)
+                                    (p/rejected (ex-info "should-not-start-daemon" {})))})
+               (p/then (fn [_]
+                         (is (= 1 @exit-code*))
+                         (is (= false @start-called?))
+                         (is (empty? @stdout*))
+                         (is (some #(string/includes? % "root-dir is required")
+                                   @stderr*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest db-worker-node-main-missing-repo-prints-error-and-exits-1
+  (async done
+         (let [exit-code* (atom nil)
+               stdout* (atom [])
+               stderr* (atom [])
+               start-called? (atom false)]
+           (-> (run-main-with-overrides
+                {:argv #js ["node" "dist/db-worker-node.js" "--root-dir" "/tmp/logseq-root"]
+                 :on-exit (fn [code]
+                            (reset! exit-code* code)
+                            (throw (ex-info "process-exit" {:code code})))
+                 :on-log (fn [& args]
+                           (swap! stdout* conj (string/join " " args)))
+                 :on-error (fn [& args]
+                             (swap! stderr* conj (string/join " " args)))
+                 :start-daemon-fn (fn [_]
+                                    (reset! start-called? true)
+                                    (p/rejected (ex-info "should-not-start-daemon" {})))})
+               (p/then (fn [_]
+                         (is (= 1 @exit-code*))
+                         (is (= false @start-called?))
+                         (is (empty? @stdout*))
+                         (is (some #(string/includes? % "repo is required")
+                                   @stderr*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest db-worker-node-owner-source-cli-is-written-into-lock
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-owner-source-cli")
+               repo (str "logseq_db_owner_cli_" (subs (str (random-uuid)) 0 8))
+               lock-file (lock-path data-dir repo)]
+           (-> (p/let [{:keys [stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo
+                                       :owner-source :cli})
+                       _ (reset! daemon {:stop! stop!})
+                       lock-json (js/JSON.parse (.toString (fs/readFileSync lock-file) "utf8"))]
+                 (is (= "cli" (gobj/get lock-json "owner-source"))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-owner-source-electron-is-written-into-lock
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-owner-source-electron")
+               repo (str "logseq_db_owner_electron_" (subs (str (random-uuid)) 0 8))
+               lock-file (lock-path data-dir repo)]
+           (-> (p/let [{:keys [stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo
+                                       :owner-source :electron})
+                       _ (reset! daemon {:stop! stop!})
+                       lock-json (js/JSON.parse (.toString (fs/readFileSync lock-file) "utf8"))]
+                 (is (= "electron" (gobj/get lock-json "owner-source"))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-handle-event-encodes-sse-json-payload
+  (let [handle-event! #'db-worker-node/handle-event!
+        *sse-clients @#'db-worker-node/*sse-clients
+        writes (atom [])
+        fake-res #js {:write (fn [message]
+                               (swap! writes conj message))}]
+    (reset! *sse-clients #{fake-res})
+    (handle-event! "sync-db-changes" {:repo "graph-a"})
+    (is (= 1 (count @writes)))
+    (let [raw-message (first @writes)
+          event-json (-> raw-message
+                         (string/replace-first #"^data: " "")
+                         (string/replace #"\n\n$" ""))
+          parsed (js->clj (js/JSON.parse event-json) :keywordize-keys true)]
+      (is (= "sync-db-changes" (:type parsed)))
+      (is (= {:repo "graph-a"}
+             (ldb/read-transit-str (:payload parsed)))))))
+
+(deftest db-worker-node-handle-event-preserves-namespaced-type
+  (let [handle-event! #'db-worker-node/handle-event!
+        *sse-clients @#'db-worker-node/*sse-clients
+        writes (atom [])
+        fake-res #js {:write (fn [message]
+                               (swap! writes conj message))}]
+    (reset! *sse-clients #{fake-res})
+    (handle-event! :db-worker/ui-request {:request-id "r1"})
+    (is (= 1 (count @writes)))
+    (let [raw-message (first @writes)
+          event-json (-> raw-message
+                         (string/replace-first #"^data: " "")
+                         (string/replace #"\n\n$" ""))
+          parsed (js->clj (js/JSON.parse event-json) :keywordize-keys true)]
+      (is (= "db-worker/ui-request" (:type parsed)))
+      (is (= {:request-id "r1"}
+             (ldb/read-transit-str (:payload parsed)))))))
+
+(deftest db-worker-node-help-documents-required-root-dir-and-omits-server-list-file
+  (let [show-help! #'db-worker-node/show-help!
+        output (binding [style/*color-enabled?* true]
+                 (with-out-str (show-help!)))
+        plain-output (style/strip-ansi output)]
+    (is (not (string/includes? (style/strip-ansi output) "--auth-token")))
+    (is (not (string/includes? plain-output "--rtc-ws-url")))
+    (is (not (string/includes? plain-output "--server-list-file")))
+    (is (not (string/includes? plain-output "(default ~/logseq)")))
+    (is (re-find #"\u001b\[[0-9;]*moptions\u001b\[[0-9;]*m:" output))
+    (is (contains-bold? output "db-worker-node"))
+    (is (contains-bold? output "--root-dir"))
+    (is (contains-bold? output "--repo"))
+    (is (string/includes? plain-output "--root-dir"))
+    (is (string/includes? plain-output "(required)"))
+    (is (string/includes? plain-output "--create-empty-db"))
+    (is (contains-bold? output "--create-empty-db"))
+    (is (not (contains-bold? output "--rtc-ws-url")))
+    (is (contains-bold? output "--log-level"))))
+
+(deftest db-worker-node-start-daemon-uses-empty-datoms-when-create-empty-enabled
+  (async done
+         (let [data-dir (node-helper/create-tmp-dir "db-worker-create-empty-start")
+               repo (str "logseq_db_create_empty_start_" (subs (str (random-uuid)) 0 8))
+               lock-file-path (lock-path data-dir repo)
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [platform-node/node-platform (fn [_opts] #js {})
+                               db-core/init-core! (fn [_platform]
+                                                    #js {:remoteInvoke (fn [method direct-pass? args]
+                                                                         (swap! invoke-calls conj
+                                                                                [method
+                                                                                 direct-pass?
+                                                                                 (if direct-pass?
+                                                                                   (vec (js->clj args))
+                                                                                   (ldb/read-transit-str args))])
+                                                                         (p/resolved nil))})
+                               db-lock/ensure-lock! (fn [_]
+                                                      (p/resolved {:path lock-file-path
+                                                                   :lock {:repo repo
+                                                                          :pid (.-pid js/process)
+                                                                          :host "127.0.0.1"
+                                                                          :port 0
+                                                                          :lock-id "create-empty-lock"}}))
+                               db-lock/update-lock! (fn [_path lock] lock)]
+                 (p/let [{:keys [stop!]} (db-worker-node/start-daemon! {:root-dir data-dir
+                                                                        :repo repo
+                                                                        :create-empty-db? true
+                                                                        :log-level "error"})
+                         _ (is (= ["thread-api/init" true []]
+                                  (first @invoke-calls)))
+                         _ (is (= ["thread-api/create-or-open-db" false [repo {:datoms []
+                                                                               :sync-download-graph? true}]]
+                                  (second @invoke-calls)))
+                         _ (stop!)]
+                   true))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest db-worker-node-start-daemon-uses-default-startup-opts-without-create-empty
+  (async done
+         (let [data-dir (node-helper/create-tmp-dir "db-worker-default-start")
+               repo (str "logseq_db_default_start_" (subs (str (random-uuid)) 0 8))
+               lock-file-path (lock-path data-dir repo)
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [platform-node/node-platform (fn [_opts] #js {})
+                               db-core/init-core! (fn [_platform]
+                                                    #js {:remoteInvoke (fn [method direct-pass? args]
+                                                                         (swap! invoke-calls conj
+                                                                                [method
+                                                                                 direct-pass?
+                                                                                 (if direct-pass?
+                                                                                   (vec (js->clj args))
+                                                                                   (ldb/read-transit-str args))])
+                                                                         (p/resolved nil))})
+                               db-lock/ensure-lock! (fn [_]
+                                                      (p/resolved {:path lock-file-path
+                                                                   :lock {:repo repo
+                                                                          :pid (.-pid js/process)
+                                                                          :host "127.0.0.1"
+                                                                          :port 0
+                                                                          :lock-id "default-lock"}}))
+                               db-lock/update-lock! (fn [_path lock] lock)]
+                 (p/let [{:keys [stop!]} (db-worker-node/start-daemon! {:root-dir data-dir
+                                                                        :repo repo
+                                                                        :log-level "error"})
+                         _ (is (= ["thread-api/init" true []]
+                                  (first @invoke-calls)))
+                         _ (is (= ["thread-api/create-or-open-db" false [repo {}]]
+                                  (second @invoke-calls)))
+                         _ (stop!)]
+                   true))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest db-worker-node-stop-closes-bound-repo
+  (async done
+         (let [data-dir (node-helper/create-tmp-dir "db-worker-stop-close-db")
+               repo (str "logseq_db_stop_close_" (subs (str (random-uuid)) 0 8))
+               lock-file-path (lock-path data-dir repo)
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [platform-node/node-platform (fn [_opts] #js {})
+                               db-core/init-core! (fn [_platform]
+                                                    #js {:remoteInvoke (fn [method direct-pass? args]
+                                                                         (swap! invoke-calls conj
+                                                                                [method
+                                                                                 direct-pass?
+                                                                                 (if direct-pass?
+                                                                                   (vec (js->clj args))
+                                                                                   (ldb/read-transit-str args))])
+                                                                         (p/resolved nil))})
+                               db-lock/ensure-lock! (fn [_]
+                                                      (p/resolved {:path lock-file-path
+                                                                   :lock {:repo repo
+                                                                          :pid (.-pid js/process)
+                                                                          :host "127.0.0.1"
+                                                                          :port 0
+                                                                          :lock-id "stop-close-lock"}}))
+                               db-lock/update-lock! (fn [_path lock] lock)]
+                 (p/let [{:keys [stop!]} (db-worker-node/start-daemon! {:root-dir data-dir
+                                                                        :repo repo
+                                                                        :log-level "error"})
+                         _ (stop!)]
+                   (is (= ["thread-api/init" true []]
+                          (first @invoke-calls)))
+                   (is (= ["thread-api/create-or-open-db" false [repo {}]]
+                          (second @invoke-calls)))
+                   (is (= ["thread-api/close-db" false [repo]]
+                          (nth @invoke-calls 2)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest db-worker-node-start-daemon-registers-and-unregisters-derived-server-list-entry
+  (async done
+         (let [data-dir (node-helper/create-tmp-dir "db-worker-server-list")
+               repo (str "logseq_db_server_list_" (subs (str (random-uuid)) 0 8))
+               lock-file-path (lock-path data-dir repo)
+               server-list-file (cli-config/server-list-path data-dir)]
+           (-> (p/with-redefs [platform-node/node-platform (fn [_opts] #js {})
+                               db-core/init-core! (fn [_platform]
+                                                    #js {:remoteInvoke (fn [_method _direct-pass? _args]
+                                                                         (p/resolved nil))})
+                               db-lock/ensure-lock! (fn [_]
+                                                      (p/resolved {:path lock-file-path
+                                                                   :lock {:repo repo
+                                                                          :pid (.-pid js/process)
+                                                                          :lock-id "server-list-lock"
+                                                                          :owner-source :cli}}))
+                               db-lock/update-lock! (fn [_path lock] lock)]
+                 (p/let [{:keys [port stop!]} (db-worker-node/start-daemon! {:root-dir data-dir
+                                                                             :repo repo
+                                                                             :log-level "error"})
+                         contents-after-start (.toString (fs/readFileSync server-list-file) "utf8")
+                         _ (is (string/includes? contents-after-start (str (.-pid js/process) " " port)))
+                         _ (stop!)
+                         contents-after-stop (when (fs/existsSync server-list-file)
+                                               (.toString (fs/readFileSync server-list-file) "utf8"))]
+                   (is (or (nil? contents-after-stop)
+                           (not (string/includes? contents-after-stop (str (.-pid js/process) " " port)))))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest db-worker-node-repo-error-handles-keyword-methods
+  (let [repo-error #'db-worker-node/repo-error
+        bound-repo "logseq_db_bound"]
+    (is (nil? (repo-error :thread-api/list-db [] bound-repo)))
+    (is (nil? (repo-error :thread-api/get-db-sync-config [] bound-repo)))
+    (is (nil? (repo-error :thread-api/sync-app-state [{:auth/id-token "token"}] bound-repo)))
+    (is (nil? (repo-error :thread-api/db-sync-list-remote-graphs [] bound-repo)))
+    (is (nil? (repo-error "thread-api/list-db" [] bound-repo)))
+    (is (nil? (repo-error :thread-api/rtc-get-graphs ["token"] bound-repo)))
+    (is (nil? (repo-error :thread-api/set-context [{:repo "not-a-repo-arg"}] bound-repo)))
+    (is (nil? (repo-error :thread-api/resolve-ui-request ["req-id" {:password "pw"}] bound-repo)))
+    (is (nil? (repo-error :thread-api/reject-ui-request ["req-id" {:code :cancelled}] bound-repo)))
+    (is (nil? (repo-error :thread-api/cancel-ui-requests [{:context :logout}] bound-repo)))
+    (is (= {:status 400
+            :error {:code :missing-repo
+                    :message "repo is required"}}
+           (repo-error :thread-api/create-or-open-db [] bound-repo)))
+    (is (= {:status 400
+            :error {:code :missing-repo
+                    :message "repo is required"}}
+           (repo-error :thread-api/create-or-open-db [:public-key] bound-repo)))
+    (is (= {:status 409
+            :error {:code :repo-mismatch
+                    :message "repo does not match bound repo"
+                    :repo "other"
+                    :bound-repo bound-repo}}
+           (repo-error :thread-api/create-or-open-db ["other"] bound-repo)))))
+
+(deftest db-worker-node-set-context-does-not-trigger-repo-mismatch
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-set-context")
+               repo (str "logseq_db_set_context_" (subs (str (random-uuid)) 0 8))]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:host host :port port :stop! stop!})
+                       _ (invoke host port "thread-api/set-db-sync-config"
+                                 [{:ws-url "wss://example.com/sync/%s"}])
+                       _ (invoke host port "thread-api/sync-app-state"
+                                 [{:auth/id-token "token-value"}])
+                       config (invoke host port "thread-api/get-db-sync-config" [])
+                       _ (is (= "wss://example.com/sync/%s" (:ws-url config)))
+                       _ (is (not (contains? config :auth-token)))
+                       result (invoke host port "thread-api/set-context" [{:app "desktop"}])]
+                 (is (nil? result)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-create-empty-startup-skips-built-in-initial-data
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-empty-initial-data")
+               repo (str "logseq_db_empty_initial_" (subs (str (random-uuid)) 0 8))]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo
+                                       :create-empty-db? true})
+                       _ (reset! daemon {:stop! stop!})
+                       library-result (invoke host port "thread-api/q"
+                                              [repo
+                                               ['[:find ?e
+                                                  :in $ ?title
+                                                  :where [?e :block/title ?title]]
+                                                common-config/library-page-name]])]
+                 (is (empty? library-result)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-sync-status-requires-repo-and-returns-structured-status
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-sync-status")
+               repo (str "logseq_db_sync_status_" (subs (str (random-uuid)) 0 8))]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:host host :port port :stop! stop!})
+                       {:keys [status body]} (invoke-raw host port "thread-api/db-sync-status" [])
+                       parsed (js->clj (js/JSON.parse body) :keywordize-keys true)
+                       _ (is (= 400 status))
+                       _ (is (= false (:ok parsed)))
+                       _ (is (= "missing-repo" (get-in parsed [:error :code])))
+                       _ (invoke host port "thread-api/create-or-open-db" [repo {}])
+                       status-result (invoke host port "thread-api/db-sync-status" [repo])]
+                 (is (= repo (:repo status-result)))
+                 (is (contains? status-result :ws-state))
+                 (is (contains? status-result :pending-local))
+                 (is (contains? status-result :pending-asset))
+                 (is (contains? status-result :pending-server))
+                 (is (contains? status-result :local-tx))
+                 (is (contains? status-result :remote-tx))
+                 (is (contains? status-result :graph-id)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-sync-start-and-status-invoke-path
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-sync-start")
+               repo (str "logseq_db_sync_start_" (subs (str (random-uuid)) 0 8))]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:host host :port port :stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo {}])
+                       _ (invoke host port "thread-api/set-db-sync-config"
+                                 [{:ws-url nil
+                                   :http-base "https://example.com"}])
+                       start-result (invoke host port "thread-api/db-sync-start" [repo])
+                       status-result (invoke host port "thread-api/db-sync-status" [repo])]
+                 (is (nil? start-result))
+                 (is (= repo (:repo status-result)))
+                 (is (= :inactive (:ws-state status-result)))
+                 (is (contains? status-result :pending-local))
+                 (is (contains? status-result :pending-server)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-daemon-smoke-test
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-daemon")
+               repo (str "logseq_db_smoke_" (subs (str (random-uuid)) 0 8))
+               server-list-file (cli-config/server-list-path data-dir)
+               now (js/Date.now)
+               page-uuid (random-uuid)
+               block-uuid (random-uuid)]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon!  {:root-dir data-dir
+                                        :repo repo})
+                       health (http-get host port "/healthz")
+                       missing-readyz (http-get host port "/readyz")
+                       health-body (js->clj (js/JSON.parse (:body health)) :keywordize-keys true)
+                       server-list-contents (.toString (fs/readFileSync server-list-file) "utf8")
+                       _ (do
+                           (reset! daemon {:host host :port port :stop! stop!})
+                           (is (= 200 (:status health)))
+                           (is (= 404 (:status missing-readyz)))
+                           (is (= repo (:repo health-body)))
+                           (is (= "ready" (:status health-body)))
+                           (is (= host (:host health-body)))
+                           (is (= port (:port health-body)))
+                           (is (= (.-pid js/process) (:pid health-body)))
+                           (is (= (node-path/resolve data-dir) (:root-dir health-body)))
+                           (is (contains? health-body :owner-source))
+                           (is (contains? health-body :revision))
+                           (is (string/includes? server-list-contents (str (.-pid js/process) " " port))))
+                       _ (invoke host port "thread-api/create-or-open-db" [repo {}])
+                       dbs (invoke host port "thread-api/list-db" [])
+                       _ (is (some #(= repo (:name %)) dbs))
+                       lock-file (lock-path data-dir repo)
+                       _ (is (fs/existsSync lock-file))
+                       lock-contents (js/JSON.parse (.toString (fs/readFileSync lock-file) "utf8"))
+                       _ (is (= repo (gobj/get lock-contents "repo")))
+                       _ (is (nil? (gobj/get lock-contents "host")))
+                       _ (is (nil? (gobj/get lock-contents "port")))
+                       _ (invoke host port "thread-api/transact"
+                                 [repo
+                                  [{:block/uuid page-uuid
+                                    :block/title "Smoke Page"
+                                    :block/name "smoke-page"
+                                    :block/tags #{:logseq.class/Page}
+                                    :block/created-at now
+                                    :block/updated-at now}
+                                   {:block/uuid block-uuid
+                                    :block/title "Smoke Test"
+                                    :block/page [:block/uuid page-uuid]
+                                    :block/parent [:block/uuid page-uuid]
+                                    :block/order "a0"
+                                    :block/created-at now
+                                    :block/updated-at now}]
+                                  {}
+                                  nil])
+                       result (invoke host port "thread-api/q"
+                                      [repo
+                                       ['[:find ?e
+                                          :in $ ?uuid
+                                          :where [?e :block/uuid ?uuid]]
+                                        block-uuid]])]
+                 (is (seq result)))
+               (p/catch (fn [e]
+                          (println "[db-worker-node-test] e:" e)
+                          (is false (str e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!)
+                                  (p/finally (fn []
+                                               (is (not (fs/existsSync (lock-path data-dir repo))))
+                                               (let [contents (when (fs/existsSync server-list-file)
+                                                                (.toString (fs/readFileSync server-list-file) "utf8"))]
+                                                 (is (or (nil? contents)
+                                                         (not (string/includes? contents (str (.-pid js/process) " ")))))
+                                                 (done)))))
+                              (done))))))))
+
+(deftest db-worker-node-import-edn
+  (async done
+         (let [daemon-a (atom nil)
+               daemon-b (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-import-edn")
+               repo-a (str "logseq_db_import_edn_a_" (subs (str (random-uuid)) 0 8))
+               repo-b (str "logseq_db_import_edn_b_" (subs (str (random-uuid)) 0 8))
+               now (js/Date.now)
+               page-uuid (random-uuid)]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo-a})
+                       _ (reset! daemon-a {:stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo-a {}])
+                       _ (invoke host port "thread-api/transact"
+                                 [repo-a
+                                  [{:block/uuid page-uuid
+                                    :block/title "Import Page"
+                                    :block/name "import-page"
+                                    :block/tags #{:logseq.class/Page}
+                                    :block/created-at now
+                                    :block/updated-at now}]
+                                  {}
+                                  nil])
+                       export-edn (invoke host port "thread-api/export-edn" [repo-a {:export-type :graph}])]
+                 (is (map? export-edn))
+                 (p/let [_ ((:stop! @daemon-a))
+                         {:keys [host port stop!]}
+                         (start-daemon! {:root-dir data-dir
+                                         :repo repo-b})
+                         _ (reset! daemon-b {:stop! stop!})
+                         _ (invoke host port "thread-api/create-or-open-db" [repo-b {}])
+                         _ (invoke host port "thread-api/import-edn" [repo-b export-edn])
+                         result (invoke host port "thread-api/q"
+                                        [repo-b
+                                         ['[:find ?e
+                                            :in $ ?title
+                                            :where [?e :block/title ?title]]
+                                          "Import Page"]])]
+                   (is (seq result))))
+               (p/catch (fn [e]
+                          (println "[db-worker-node-test] import-edn error:" e)
+                          (is false (str e))))
+               (p/finally (fn []
+                            (let [stop-a (:stop! @daemon-a)
+                                  stop-b (:stop! @daemon-b)]
+                              (cond
+                                (and stop-a stop-b)
+                                (-> (stop-a)
+                                    (p/finally (fn [] (-> (stop-b) (p/finally (fn [] (done)))))))
+
+                                stop-a
+                                (-> (stop-a) (p/finally (fn [] (done))))
+
+                                stop-b
+                                (-> (stop-b) (p/finally (fn [] (done))))
+
+                                :else
+                                (done)))))))))
+
+(deftest db-worker-node-import-db-base64
+  (async done
+         (let [daemon-a (atom nil)
+               daemon-b (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-import-sqlite")
+               repo-a (str "logseq_db_import_sqlite_a_" (subs (str (random-uuid)) 0 8))
+               repo-b (str "logseq_db_import_sqlite_b_" (subs (str (random-uuid)) 0 8))
+               now (js/Date.now)
+               page-uuid (random-uuid)]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo-a})
+                       _ (reset! daemon-a {:stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo-a {}])
+                       _ (invoke host port "thread-api/transact"
+                                 [repo-a
+                                  [{:block/uuid page-uuid
+                                    :block/title "SQLite Import Page"
+                                    :block/name "sqlite-import-page"
+                                    :block/tags #{:logseq.class/Page}
+                                    :block/created-at now
+                                    :block/updated-at now}]
+                                  {}
+                                  nil])
+                       export-base64 (invoke host port "thread-api/export-db-base64" [repo-a])]
+                 (is (string? export-base64))
+                 (is (pos? (count export-base64)))
+                 (p/let [_ ((:stop! @daemon-a))
+                         {:keys [host port stop!]}
+                         (start-daemon! {:root-dir data-dir
+                                         :repo repo-b})
+                         _ (reset! daemon-b {:stop! stop!})
+                         _ (invoke host port "thread-api/import-db-base64" [repo-b export-base64])
+                         _ (invoke host port "thread-api/create-or-open-db" [repo-b {}])
+                         result (invoke host port "thread-api/q"
+                                        [repo-b
+                                         ['[:find ?e
+                                            :in $ ?title
+                                            :where [?e :block/title ?title]]
+                                          "SQLite Import Page"]])]
+                   (is (seq result))))
+               (p/catch (fn [e]
+                          (println "[db-worker-node-test] import-sqlite error:" e)
+                          (is false (str e))))
+               (p/finally (fn []
+                            (let [stop-a (:stop! @daemon-a)
+                                  stop-b (:stop! @daemon-b)]
+                              (cond
+                                (and stop-a stop-b)
+                                (-> (stop-a)
+                                    (p/finally (fn [] (-> (stop-b) (p/finally (fn [] (done)))))))
+
+                                stop-a
+                                (-> (stop-a) (p/finally (fn [] (done))))
+
+                                stop-b
+                                (-> (stop-b) (p/finally (fn [] (done))))
+
+                                :else
+                                (done)))))))))
+
+(deftest db-worker-node-backup-db-sqlite
+  (async done
+         (let [daemon-a (atom nil)
+               daemon-b (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-backup-sqlite")
+               repo-a (str "logseq_db_backup_sqlite_a_" (subs (str (random-uuid)) 0 8))
+               repo-b (str "logseq_db_backup_sqlite_b_" (subs (str (random-uuid)) 0 8))
+               backup-path (node-path/join data-dir "backup" "snapshot.sqlite")
+               now (js/Date.now)
+               page-uuid (random-uuid)]
+           (-> (p/let [{:keys [host port stop!]} (start-daemon! {:root-dir data-dir
+                                                                 :repo repo-a})
+                       _ (reset! daemon-a {:stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo-a {}])
+                       _ (invoke host port "thread-api/transact"
+                                 [repo-a
+                                  [{:block/uuid page-uuid
+                                    :block/title "Backup Source Page"
+                                    :block/name "backup-source-page"
+                                    :block/tags #{:logseq.class/Page}
+                                    :block/created-at now
+                                    :block/updated-at now}]
+                                  {}
+                                  nil])
+                       backup-result (invoke host port "thread-api/backup-db-sqlite" [repo-a backup-path])
+                       _ (is (= backup-path (:path backup-result)))
+                       _ (is (fs/existsSync backup-path))
+                       backup-base64 (.toString (fs/readFileSync backup-path) "base64")]
+                 (is (string? backup-base64))
+                 (is (pos? (count backup-base64)))
+                 (p/let [_ ((:stop! @daemon-a))
+                         {:keys [host port stop!]} (start-daemon! {:root-dir data-dir
+                                                                   :repo repo-b})
+                         _ (reset! daemon-b {:stop! stop!})
+                         _ (invoke host port "thread-api/import-db-base64" [repo-b backup-base64])
+                         _ (invoke host port "thread-api/create-or-open-db" [repo-b {}])
+                         result (invoke host port "thread-api/q"
+                                        [repo-b
+                                         ['[:find ?e
+                                            :in $ ?title
+                                            :where [?e :block/title ?title]]
+                                          "Backup Source Page"]])]
+                   (is (seq result))))
+               (p/catch (fn [e]
+                          (println "[db-worker-node-test] backup-sqlite error:" e)
+                          (is false (str e))))
+               (p/finally (fn []
+                            (let [stop-a (:stop! @daemon-a)
+                                  stop-b (:stop! @daemon-b)]
+                              (cond
+                                (and stop-a stop-b)
+                                (-> (stop-a)
+                                    (p/finally (fn [] (-> (stop-b) (p/finally (fn [] (done)))))))
+
+                                stop-a
+                                (-> (stop-a) (p/finally (fn [] (done))))
+
+                                stop-b
+                                (-> (stop-b) (p/finally (fn [] (done))))
+
+                                :else
+                                (done)))))))))
+
+(deftest db-worker-node-repo-mismatch-test
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-repo-mismatch")
+               repo (str "logseq_db_mismatch_" (subs (str (random-uuid)) 0 8))
+               other-repo (str repo "_other")]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:host host :port port :stop! stop!})
+                       {:keys [status body]} (invoke-raw host port "thread-api/create-or-open-db" [other-repo {}])
+                       parsed (js->clj (js/JSON.parse body) :keywordize-keys true)]
+                 (is (= 409 status))
+                 (is (= false (:ok parsed)))
+                 (is (= "repo-mismatch" (get-in parsed [:error :code]))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-lock-prevents-multiple-daemons
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-lock")
+               repo (str "logseq_db_lock_" (subs (str (random-uuid)) 0 8))]
+           (-> (p/let [{:keys [stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:stop! stop!})]
+                 (-> (start-daemon! {:root-dir data-dir
+                                     :repo repo})
+                     (p/then (fn [_]
+                               (is false "expected lock error")))
+                     (p/catch (fn [e]
+                                (is (= :repo-locked (-> (ex-data e) :code)))))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-write-mutation-fails-for-non-owner-pid
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-write-lease-pid")
+               repo (str "logseq_db_write_lease_pid_" (subs (str (random-uuid)) 0 8))
+               lock-file (lock-path data-dir repo)]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo {}])
+                       export-base64 (invoke host port "thread-api/export-db-base64" [repo])
+                       lock-contents (js->clj (js/JSON.parse (.toString (fs/readFileSync lock-file) "utf8"))
+                                              :keywordize-keys true)
+                       tampered-lock (assoc lock-contents
+                                            :pid (inc (:pid lock-contents))
+                                            :lock-id "non-owner-lock")
+                       _ (fs/writeFileSync lock-file (js/JSON.stringify (clj->js tampered-lock)))
+                       {:keys [status body]} (invoke-raw host port "thread-api/import-db-base64" [repo export-base64])
+                       parsed (js->clj (js/JSON.parse body) :keywordize-keys true)]
+                 (is (= 409 status))
+                 (is (= false (:ok parsed)))
+                 (is (= "repo-locked" (get-in parsed [:error :code]))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-backup-write-mutation-fails-for-non-owner-pid
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-backup-write-lease-pid")
+               repo (str "logseq_db_backup_write_lease_pid_" (subs (str (random-uuid)) 0 8))
+               lock-file (lock-path data-dir repo)
+               backup-path (node-path/join data-dir "backup" "non-owner.sqlite")]
+           (-> (p/let [{:keys [host port stop!]} (start-daemon! {:root-dir data-dir
+                                                                 :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo {}])
+                       lock-contents (js->clj (js/JSON.parse (.toString (fs/readFileSync lock-file) "utf8"))
+                                              :keywordize-keys true)
+                       tampered-lock (assoc lock-contents
+                                            :pid (inc (:pid lock-contents))
+                                            :lock-id "non-owner-lock")
+                       _ (fs/writeFileSync lock-file (js/JSON.stringify (clj->js tampered-lock)))
+                       {:keys [status body]} (invoke-raw host port "thread-api/backup-db-sqlite" [repo backup-path])
+                       parsed (js->clj (js/JSON.parse body) :keywordize-keys true)]
+                 (is (= 409 status))
+                 (is (= false (:ok parsed)))
+                 (is (= "repo-locked" (get-in parsed [:error :code]))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-write-mutation-succeeds-for-active-owner
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-write-lease-owner")
+               repo (str "logseq_db_write_lease_owner_" (subs (str (random-uuid)) 0 8))
+               lock-file (lock-path data-dir repo)]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo {}])
+                       lock-contents (js/JSON.parse (.toString (fs/readFileSync lock-file) "utf8"))
+                       lock-id (gobj/get lock-contents "lock-id")
+                       _ (is (string? lock-id))
+                       export-base64 (invoke host port "thread-api/export-db-base64" [repo])
+                       {:keys [status body]} (invoke-raw host port "thread-api/import-db-base64" [repo export-base64])
+                       parsed (js->clj (js/JSON.parse body) :keywordize-keys true)]
+                 (is (= 200 status))
+                 (is (= true (:ok parsed))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-write-mutation-rejects-stale-lock-after-replacement
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-write-lease-replaced")
+               repo (str "logseq_db_write_lease_replaced_" (subs (str (random-uuid)) 0 8))
+               lock-file (lock-path data-dir repo)]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo {}])
+                       export-base64 (invoke host port "thread-api/export-db-base64" [repo])
+                       lock-contents (js->clj (js/JSON.parse (.toString (fs/readFileSync lock-file) "utf8"))
+                                              :keywordize-keys true)
+                       replaced-lock (assoc lock-contents :lock-id "replaced-lock-id")
+                       _ (fs/writeFileSync lock-file (js/JSON.stringify (clj->js replaced-lock)))
+                       {:keys [status body]} (invoke-raw host port "thread-api/import-db-base64" [repo export-base64])
+                       parsed (js->clj (js/JSON.parse body) :keywordize-keys true)]
+                 (is (= 409 status))
+                 (is (= false (:ok parsed)))
+                 (is (= "repo-locked" (get-in parsed [:error :code]))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-start-recovers-stale-lock-before-acquire
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-stale-lock-recover")
+               repo (str "logseq_db_stale_lock_" (subs (str (random-uuid)) 0 8))
+               lock-file (lock-path data-dir repo)
+               stale-lock {:repo repo
+                           :pid 999999
+                           :host "127.0.0.1"
+                           :port 6553
+                           :lock-id "stale-lock-id"}]
+           (fs/mkdirSync (node-path/dirname lock-file) #js {:recursive true})
+           (fs/writeFileSync lock-file (js/JSON.stringify (clj->js stale-lock)))
+           (-> (p/let [{:keys [stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       lock' (js->clj (js/JSON.parse (.toString (fs/readFileSync lock-file) "utf8"))
+                                      :keywordize-keys true)]
+                 (is (not= 999999 (:pid lock')))
+                 (is (not= "stale-lock-id" (:lock-id lock'))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!)
+                                  (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-desktop-and-cli-share-same-graph-daemon
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-desktop-cli")
+               config-path (node-path/join data-dir "cli.edn")
+               server-list-file (cli-config/server-list-path data-dir)
+               repo (str "logseq_db_desktop_cli_" (subs (str (random-uuid)) 0 8))
+               now (js/Date.now)
+               page-uuid (random-uuid)]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir
+                                       :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo {}])
+                       _ (invoke host port "thread-api/transact"
+                                 [repo
+                                  [{:block/uuid page-uuid
+                                    :block/title "Desktop+CLI Shared"
+                                    :block/name "desktop-cli-shared"
+                                    :block/tags #{:logseq.class/Page}
+                                    :block/created-at now
+                                    :block/updated-at now}]
+                                  {}
+                                  nil])
+                       _ (is (fs/existsSync server-list-file))
+                       _ (is (string/includes? (.toString (fs/readFileSync server-list-file) "utf8")
+                                               (str (.-pid js/process) " " port)))
+                       ensured (cli-server/ensure-server! {:root-dir data-dir
+                                                           :config-path config-path}
+                                                          repo)
+                       url (js/URL. (:base-url ensured))
+                       cli-host (.-hostname url)
+                       cli-port (js/parseInt (.-port url) 10)
+                       result (invoke cli-host cli-port "thread-api/q"
+                                      [repo
+                                       ['[:find ?e
+                                          :in $ ?title
+                                          :where [?e :block/title ?title]]
+                                        "Desktop+CLI Shared"]])]
+                 (is (seq result)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!)
+                                  (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-validation-error-returns-400
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-validation-error")
+               repo (str "logseq_db_validation_" (subs (str (random-uuid)) 0 8))]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       ;; Build a deterministic block to use as target and fetch Journal tag db/id
+                       journal (invoke host port "thread-api/pull"
+                                       [repo [:db/id] [:db/ident :logseq.class/Journal]])
+                       journal-id (:db/id journal)
+                       now (js/Date.now)
+                       page-uuid (random-uuid)
+                       block-uuid (random-uuid)
+                       _ (invoke host port "thread-api/transact"
+                                 [repo
+                                  [{:block/uuid page-uuid
+                                    :block/title "Validation Target Page"
+                                    :block/name "validation-target-page"
+                                    :block/tags #{:logseq.class/Page}
+                                    :block/created-at now
+                                    :block/updated-at now}
+                                   {:block/uuid block-uuid
+                                    :block/title "Validation Target Block"
+                                    :block/page [:block/uuid page-uuid]
+                                    :block/parent [:block/uuid page-uuid]
+                                    :block/order "a0"
+                                    :block/created-at now
+                                    :block/updated-at now}]
+                                  {}
+                                  nil])
+                       ;; Try to set the built-in Journal tag on the block
+                       {:keys [status body]}
+                       (invoke-raw host port "thread-api/apply-outliner-ops"
+                                   [repo [[:batch-set-property [[block-uuid] :block/tags journal-id {}]]] {}])
+                       parsed (js->clj (js/JSON.parse body) :keywordize-keys true)]
+                 (is (= 400 status)
+                     "validation errors should return 400, not 500")
+                 (is (false? (:ok parsed)))
+                 (is (string/includes? (get-in parsed [:error :message]) "Can't set tag")
+                     "error message should describe the validation failure"))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
+
+(deftest db-worker-node-query-validate-error-returns-400-with-invalid-query-code
+  (async done
+         (let [daemon (atom nil)
+               data-dir (node-helper/create-tmp-dir "db-worker-query-validate-error")
+               repo (str "logseq_db_query_validate_" (subs (str (random-uuid)) 0 8))]
+           (-> (p/let [{:keys [host port stop!]}
+                       (start-daemon! {:root-dir data-dir :repo repo})
+                       _ (reset! daemon {:stop! stop!})
+                       _ (invoke host port "thread-api/create-or-open-db" [repo {}])
+                       {:keys [status body]}
+                       (invoke-raw host port "thread-api/q"
+                                   [repo
+                                    ['[:find (pull ?e ...)
+                                       :where
+                                       [?e :block/title "Status"]]]])
+                       parsed (js->clj (js/JSON.parse body) :keywordize-keys true)]
+                 (is (= 400 status)
+                     "query validation errors should return 400, not 500")
+                 (is (false? (:ok parsed)))
+                 (is (= "invalid-query" (get-in parsed [:error :code])))
+                 (is (string/includes? (get-in parsed [:error :message]) "Query for unknown vars")))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (if-let [stop! (:stop! @daemon)]
+                              (-> (stop!) (p/finally (fn [] (done))))
+                              (done))))))))
diff --git a/src/test/frontend/worker/db_worker_test.cljs b/src/test/frontend/worker/db_worker_test.cljs
index 34d4a8acca..c71ef78e23 100644
--- a/src/test/frontend/worker/db_worker_test.cljs
+++ b/src/test/frontend/worker/db_worker_test.cljs
@@ -1,21 +1,22 @@
 (ns frontend.worker.db-worker-test
-  (:require
-   [cljs.test :refer [async deftest is]]
-   [datascript.core :as d]
-   [frontend.common.thread-api :as thread-api]
-   [frontend.worker.a-test-env]
-   [frontend.worker.db-worker :as db-worker]
-   [frontend.worker.db.validate :as worker-db-validate]
-   [frontend.worker.search :as search]
-   [frontend.worker.shared-service :as shared-service]
-   [frontend.worker.state :as worker-state]
-   [frontend.worker.sync :as db-sync]
-   [frontend.worker.sync.client-op :as client-op]
-   [frontend.worker.sync.crypt :as sync-crypt]
-   [frontend.worker.sync.download :as sync-download]
-   [frontend.worker.sync.log-and-state :as rtc-log-and-state]
-   [logseq.db.frontend.schema :as db-schema]
-   [promesa.core :as p]))
+  (:require [cljs.test :refer [async deftest is]]
+            [clojure.string :as string]
+            [datascript.core :as d]
+            [frontend.common.thread-api :as thread-api]
+            [frontend.worker.a-test-env]
+            [frontend.worker.db-core :as db-worker]
+            [frontend.worker.platform :as platform]
+            [frontend.worker.db.validate :as worker-db-validate]
+            [frontend.worker.search :as search]
+            [frontend.worker.shared-service :as shared-service]
+            [frontend.worker.state :as worker-state]
+            [frontend.worker.sync :as db-sync]
+            [frontend.worker.sync.client-op :as client-op]
+            [frontend.worker.sync.crypt :as sync-crypt]
+            [frontend.worker.sync.download :as sync-download]
+            [frontend.worker.sync.log-and-state :as rtc-log-and-state]
+            [logseq.db.frontend.schema :as db-schema]
+            [promesa.core :as p]))
 
 (def ^:private test-repo "test-db-worker-repo")
 (def ^:private close-db!-orig db-worker/close-db!)
@@ -26,13 +27,52 @@
 (def ^:private update-local-tx-orig client-op/update-local-tx)
 (def ^:private broadcast-to-clients-orig shared-service/broadcast-to-clients!)
 
+(defn- fake-db
+  [label closed]
+  (let [tx #js {:exec (fn [_] nil)}]
+    #js {:exec (fn [_] #js [])
+         :transaction (fn [f] (f tx))
+         :close (fn []
+                  (when (and label closed)
+                    (swap! closed conj label)))}))
+
+(defn- build-test-platform
+  []
+  {:env {:publishing? false
+         :runtime :browser}
+   :storage {:install-opfs-pool (fn [_sqlite _pool-name]
+                                  (p/resolved #js {:pauseVfs (fn [] nil)
+                                                   :unpauseVfs (fn [] nil)}))
+             :list-graphs (fn [] (p/resolved []))
+             :db-exists? (fn [_] (p/resolved false))
+             :resolve-db-path (fn [_repo _pool path] path)
+             :export-file (fn [_ _] (p/resolved (js/Uint8Array. 0)))
+             :import-db (fn [_ _ _] (p/resolved nil))
+             :remove-vfs! (fn [_] nil)
+             :read-text! (fn [_] (p/resolved ""))
+             :write-text! (fn [_ _] (p/resolved nil))
+             :transfer (fn [data _transferables] data)}
+   :kv {:get (fn [_] nil)
+        :set! (fn [_ _] nil)}
+   :broadcast {:post-message! (fn [& _] nil)}
+   :websocket {:connect (fn [_] #js {})}
+   :sqlite {:init! (fn [] nil)
+            :open-db (fn [_opts] (fake-db nil nil))
+            :close-db (fn [db] (.close db))
+            :exec (fn [db sql-or-opts] (.exec db sql-or-opts))
+            :transaction (fn [db f] (.transaction db f))}
+   :crypto {}
+   :timers {:set-interval! (fn [_ _] nil)}})
+
 (defn- restoring-worker-state
   [f]
-  (let [sqlite-prev @worker-state/*sqlite-conns
+  (let [sqlite-conns-prev @worker-state/*sqlite-conns
         datascript-prev @worker-state/*datascript-conns
         client-ops-prev @worker-state/*client-ops-conns
         opfs-prev @worker-state/*opfs-pools
         fuzzy-prev @search/fuzzy-search-indices
+        sqlite-prev @worker-state/*sqlite
+        platform-prev @@#'platform/*platform
         cleanup (fn []
                   (set! db-worker/close-db! close-db!-orig)
                   (set! sync-crypt/<decrypt-snapshot-datoms-batch decrypt-snapshot-datoms-batch-orig)
@@ -41,11 +81,13 @@
                   (set! rtc-log-and-state/rtc-log rtc-log-orig)
                   (set! client-op/update-local-tx update-local-tx-orig)
                   (set! shared-service/broadcast-to-clients! broadcast-to-clients-orig)
-                  (reset! worker-state/*sqlite-conns sqlite-prev)
+                  (reset! worker-state/*sqlite-conns sqlite-conns-prev)
                   (reset! worker-state/*datascript-conns datascript-prev)
                   (reset! worker-state/*client-ops-conns client-ops-prev)
                   (reset! worker-state/*opfs-pools opfs-prev)
-                  (reset! search/fuzzy-search-indices fuzzy-prev))]
+                  (reset! search/fuzzy-search-indices fuzzy-prev)
+                  (reset! worker-state/*sqlite sqlite-prev)
+                  (reset! @#'platform/*platform platform-prev))]
     (set! db-worker/close-db! close-db!-orig)
     (set! sync-crypt/<decrypt-snapshot-datoms-batch decrypt-snapshot-datoms-batch-orig)
     (set! sync-crypt/<fetch-graph-aes-key-for-download fetch-graph-aes-key-for-download-orig)
@@ -53,6 +95,8 @@
     (set! rtc-log-and-state/rtc-log rtc-log-orig)
     (set! client-op/update-local-tx update-local-tx-orig)
     (set! shared-service/broadcast-to-clients! broadcast-to-clients-orig)
+    (platform/set-platform! (build-test-platform))
+    (reset! worker-state/*sqlite #js {})
     (let [result (f)]
       (if (p/promise? result)
         (p/finally result cleanup)
@@ -86,6 +130,29 @@
        (is (nil? (get @client-op/*repo->pending-local-tx-count test-repo)))
        (is (nil? (get @worker-state/*sqlite-conns test-repo)))))))
 
+(deftest close-db-checkpoints-wal-before-closing-test
+  (restoring-worker-state
+   (fn []
+     (let [sql-calls (atom [])
+           closed (atom [])
+           mk-db (fn [label]
+                   #js {:exec (fn [sql]
+                                (swap! sql-calls conj [label sql]))
+                        :close (fn []
+                                 (swap! closed conj label))})]
+       (reset! worker-state/*sqlite-conns
+               {test-repo {:db (mk-db :db)
+                           :search (mk-db :search)
+                           :client-ops (mk-db :client-ops)}})
+
+       (db-worker/close-db! test-repo)
+
+       (is (= [[:db "PRAGMA wal_checkpoint(TRUNCATE)"]
+               [:search "PRAGMA wal_checkpoint(TRUNCATE)"]
+               [:client-ops "PRAGMA wal_checkpoint(TRUNCATE)"]]
+              @sql-calls))
+       (is (= [:db :search :client-ops] @closed))))))
+
 (deftest client-ops-cleanup-timer-starts-once-and-clears-on-close-test
   (restoring-worker-state
    (fn []
@@ -93,7 +160,7 @@
            cleared (atom [])
            original-set-interval js/setInterval
            original-clear-interval js/clearInterval
-           fake-db #js {:close (fn [] nil)}
+           fake-db' #js {:close (fn [] nil)}
            timer-id #js {:id "timer-1"}]
        (set! js/setInterval
              (fn [f interval-ms]
@@ -104,9 +171,9 @@
                (swap! cleared conj id)))
        (try
          (reset! worker-state/*sqlite-conns
-                 {test-repo {:db fake-db
-                             :search fake-db
-                             :client-ops fake-db}})
+                 {test-repo {:db fake-db'
+                             :search fake-db'
+                             :client-ops fake-db'}})
          (reset! worker-state/*datascript-conns {test-repo :datascript})
          (reset! worker-state/*client-ops-conns {test-repo :client-ops})
          (reset! (deref #'db-worker/*client-ops-cleanup-timers) {})
@@ -133,10 +200,11 @@
             (let [thread-apis-prev @thread-api/*thread-apis]
               (vreset! thread-api/*thread-apis
                        (assoc thread-apis-prev
-                              :thread-api/create-or-open-db (fn [_repo _opts] (p/resolved nil))))
-              (-> (p/with-redefs [db-sync/rehydrate-large-titles-from-db! (fn [_repo _graph-id] (p/resolved nil))
-                                  rtc-log-and-state/rtc-log (fn [& _] nil)
-                                  worker-state/get-sqlite-conn (fn [_repo _type] nil)
+                              :thread-api/create-or-open-db (fn [_repo _opts] (p/resolved nil))
+                              :thread-api/export-db (fn [_repo] (p/resolved nil))
+                              :thread-api/db-sync-rehydrate-large-titles (fn [_repo _graph-id] (p/resolved nil))))
+              (-> (p/with-redefs [rtc-log-and-state/rtc-log (fn [& _] nil)
+                                  client-op/update-graph-uuid (fn [& _] nil)
                                   client-op/update-local-tx (fn [& _] nil)
                                   shared-service/broadcast-to-clients! (fn [& _] nil)]
                     (sync-download/complete-datoms-import! test-repo "graph-1" 42))
@@ -162,7 +230,7 @@
   ([repo conn f]
    (with-fake-create-or-open-db repo conn {} f))
   ([repo conn
-    {:keys [create-or-open-db-f close-db-f invalidate-search-db-f unlink-db-f]}
+    {:keys [create-or-open-db-f close-db-f invalidate-search-db-f unlink-db-f recreate-lock-f]}
     f]
    (let [thread-apis-prev @thread-api/*thread-apis
          create-or-open-db-f (or create-or-open-db-f
@@ -171,13 +239,15 @@
                                    (p/resolved nil)))
          close-db-f (or close-db-f (fn [_repo] nil))
          invalidate-search-db-f (or invalidate-search-db-f (fn [_repo] (p/resolved nil)))
-         unlink-db-f (or unlink-db-f (fn [_repo] nil))]
+         unlink-db-f (or unlink-db-f (fn [_repo] nil))
+         recreate-lock-f (or recreate-lock-f (fn [_repo] (p/resolved nil)))]
      (vreset! thread-api/*thread-apis
               (assoc thread-apis-prev
                      :thread-api/create-or-open-db create-or-open-db-f
                      :thread-api/db-sync-close-db close-db-f
                      :thread-api/db-sync-invalidate-search-db invalidate-search-db-f
-                     :thread-api/unsafe-unlink-db unlink-db-f))
+                     :thread-api/unsafe-unlink-db unlink-db-f
+                     :thread-api/db-sync-recreate-lock recreate-lock-f))
      (-> (f)
          (p/finally (fn []
                       (vreset! thread-api/*thread-apis thread-apis-prev)))))))
@@ -192,8 +262,7 @@
               (with-fake-create-or-open-db
                 test-repo conn-a
                 (fn []
-                  (-> (p/with-redefs [db-worker/close-db! (fn [_] nil)
-                                      db-worker/<invalidate-search-db! (fn [_] (p/resolved nil))]
+                  (-> (p/with-redefs [db-worker/close-db! (fn [_] nil)]
                         (p/let [first-import (prepare test-repo true "graph-1" false)
                                 _ (swap! worker-state/*datascript-conns assoc test-repo conn-b)
                                 second-import (prepare test-repo true "graph-1" false)]
@@ -220,6 +289,9 @@
             :unlink-db-f (fn [repo]
                            (swap! calls conj [:unlink repo])
                            nil)
+            :recreate-lock-f (fn [repo]
+                               (swap! calls conj [:recreate-lock repo])
+                               (p/resolved nil))
             :invalidate-search-db-f (fn [repo]
                                       (swap! calls conj [:invalidate-search repo])
                                       (p/resolved nil))
@@ -237,10 +309,12 @@
                                                             ops)))]
                              (is (some? (idx :close)))
                              (is (some? (idx :unlink)))
+                             (is (some? (idx :recreate-lock)))
                              (is (some? (idx :invalidate-search)))
                              (is (some? (idx :create-or-open)))
                              (is (< (idx :close) (idx :unlink)))
-                             (is (< (idx :unlink) (idx :invalidate-search)))
+                             (is (< (idx :unlink) (idx :recreate-lock)))
+                             (is (< (idx :recreate-lock) (idx :invalidate-search)))
                              (is (< (idx :invalidate-search) (idx :create-or-open))))
                            (done)))
                  (p/catch (fn [error]
@@ -257,10 +331,7 @@
               (with-fake-create-or-open-db
                 test-repo conn
                 (fn []
-                  (-> (p/with-redefs [db-worker/close-db! (fn [_] nil)
-                                      db-worker/<invalidate-search-db! (fn [_] (p/resolved nil))
-                                      db-sync/rehydrate-large-titles-from-db! (fn [& _] (p/resolved nil))
-                                      rtc-log-and-state/rtc-log (fn [& _] nil)
+                  (-> (p/with-redefs [rtc-log-and-state/rtc-log (fn [& _] nil)
                                       client-op/update-local-tx (fn [& _] nil)
                                       shared-service/broadcast-to-clients! (fn [& _] nil)]
                         (p/let [first-import (prepare test-repo true "graph-1" false)
@@ -275,6 +346,99 @@
                                  (is false (str error))
                                  (done)))))))))))
 
+(deftest db-sync-import-finalize-cleans-temp-pool-on-success-test
+  (async done
+         (restoring-worker-state
+          (fn []
+            (let [import-id "import-success-1"
+                  graph-id "graph-success-1"
+                  remote-tx 42
+                  rows-db-closed* (atom 0)
+                  removed-pools* (atom [])
+                  rows-pool #js {:name "temp-download-pool"}
+                  rows-db #js {:close (fn []
+                                        (swap! rows-db-closed* inc))}]
+              (reset! @#'sync-download/*import-state
+                      {:import-id import-id
+                       :repo test-repo
+                       :graph-id graph-id
+                       :rows-db rows-db
+                       :rows-pool rows-pool
+                       :rows-path "/download-import.sqlite"
+                       :rows-imported? false})
+              (-> (p/with-redefs [sync-download/complete-datoms-import! (fn [_repo _graph-id _remote-tx]
+                                                                          (p/resolved :ok))
+                                  platform/remove-storage-pool! (fn [_platform pool]
+                                                                  (swap! removed-pools* conj pool)
+                                                                  (p/resolved true))]
+                    (sync-download/finalize-import! test-repo graph-id remote-tx import-id))
+                  (p/then (fn [result]
+                            (is (= :ok result))
+                            (is (= 1 @rows-db-closed*))
+                            (is (= [rows-pool] @removed-pools*))
+                            (is (nil? @@#'sync-download/*import-state))
+                            (done)))
+                  (p/catch (fn [error]
+                             (is false (str error))
+                             (done)))))))))
+
+(deftest db-sync-download-graph-by-id-cleans-temp-pool-on-failure-test
+  (async done
+         (restoring-worker-state
+          (fn []
+            (let [original-fetch js/fetch
+                  import-id "import-failure-1"
+                  graph-id "graph-failure-1"
+                  rows-db-closed* (atom 0)
+                  removed-pools* (atom [])
+                  finalize-calls* (atom 0)
+                  rows-pool #js {:name "temp-download-pool"}
+                  rows-db #js {:close (fn []
+                                        (swap! rows-db-closed* inc))}]
+              (reset! worker-state/*db-sync-config {:http-base "https://sync.example.test"})
+              (set! js/fetch (fn [_url _opts]
+                               (p/resolved #js {:ok true})))
+              (-> (p/with-redefs [rtc-log-and-state/rtc-log (fn [& _] nil)
+                                  sync-download/fetch-json (fn [_url _opts schema]
+                                                             (case schema
+                                                               :sync/pull (p/resolved {:t 77})
+                                                               :sync/snapshot-download (p/resolved {:url "https://snapshot.example.test"})
+                                                               (p/rejected (ex-info "unexpected schema" {:schema schema}))))
+                                  sync-download/prepare-import! (fn [repo _reset? gid _graph-e2ee? & _]
+                                                                  (reset! @#'sync-download/*import-state
+                                                                          {:import-id import-id
+                                                                           :repo repo
+                                                                           :graph-id gid
+                                                                           :rows-db rows-db
+                                                                           :rows-pool rows-pool
+                                                                           :rows-path "/download-import.sqlite"
+                                                                           :rows-imported? false})
+                                                                  (p/resolved {:import-id import-id}))
+                                  sync-download/import-rows-chunk! (fn [_rows _graph-id _import-id]
+                                                                     (p/resolved true))
+                                  sync-download/finalize-import! (fn [& _]
+                                                                   (swap! finalize-calls* inc)
+                                                                   (p/resolved nil))
+                                  sync-download/<stream-snapshot-row-batches! (fn [_resp _batch-size on-batch]
+                                                                                (p/let [_ (on-batch [[1 "content" nil]])]
+                                                                                  (p/rejected (ex-info "stream failed" {:code :stream-failed}))))
+                                  platform/remove-storage-pool! (fn [_platform pool]
+                                                                  (swap! removed-pools* conj pool)
+                                                                  (p/resolved true))]
+                    (sync-download/download-graph-by-id! test-repo graph-id false))
+                  (p/then (fn [_]
+                            (is false "expected download failure")
+                            (done)))
+                  (p/catch (fn [error]
+                             (is (string/includes? (or (ex-message error) "") "db-sync download failed"))
+                             (is (= 1 @rows-db-closed*))
+                             (is (= [rows-pool] @removed-pools*))
+                             (is (= 0 @finalize-calls*))
+                             (is (nil? @@#'sync-download/*import-state))
+                             (done)))
+                  (p/finally (fn []
+                               (set! js/fetch original-fetch)))))))))
+
 (deftest db-sync-import-rows-chunk-calls-import-rows-batch-test
   (async done
          (restoring-worker-state
@@ -376,16 +540,10 @@
                                                         (reset! captured args)
                                                         {:ok true})]
            (validate test-repo)
-           (is (= [test-repo
-                   conn
-                   {:local-tx 7
-                    :remote-tx 11
-                    :local-checksum "local-checksum"
-                    :remote-checksum nil}]
+           (is (= [conn nil]
                   @captured)))
          (finally
            (reset! db-sync/*repo->latest-remote-tx latest-prev)))))))
-
 (deftest thread-api-recompute-checksum-diagnostics-passes-sync-diagnostics-test
   (restoring-worker-state
    (fn []
@@ -410,9 +568,7 @@
                   (recompute test-repo)))
            (is (= [test-repo
                    conn
-                   {:local-tx 10
-                    :remote-tx 22
-                    :local-checksum "local-checksum"
+                   {:local-checksum "local-checksum"
                     :remote-checksum "remote-checksum"}]
                   @captured)))
          (finally
@@ -428,9 +584,13 @@
              export-calls (atom [])
              expected-data (js/Uint8Array. #js [1 2 3])
              expected-buffer (.-buffer expected-data)
-             fake-pool #js {:exportFile (fn [path]
-                                          (swap! export-calls conj path)
-                                          expected-buffer)}]
+             fake-pool #js {}
+             platform' (assoc-in (build-test-platform)
+                                 [:storage :export-file]
+                                 (fn [_pool path]
+                                   (swap! export-calls conj path)
+                                   (p/resolved expected-buffer)))]
+         (platform/set-platform! platform')
          (reset! worker-state/*opfs-pools {test-repo fake-pool})
          (with-redefs [worker-state/get-sqlite-conn (fn [_repo which-db]
                                                       (when (= :client-ops which-db)
@@ -438,8 +598,11 @@
                                                                      (swap! sql-calls conj sql))}))]
            (-> (export-client-ops-db test-repo)
                (p/then (fn [result]
-                         (is (= ["PRAGMA wal_checkpoint(2)"] @sql-calls))
-                         (is (= ["client-ops/db.sqlite"] @export-calls))
+                         (is (= ["PRAGMA wal_checkpoint(TRUNCATE)"] @sql-calls))
+                         (is (= 1 (count @export-calls)))
+                         (is (contains? #{"client-ops/db.sqlite"
+                                          "client-ops-/db.sqlite"}
+                                        (first @export-calls)))
                          (is (instance? js/Uint8Array result))
                          (is (= [1 2 3] (vec result)))
                          (done)))
diff --git a/src/test/frontend/worker/graph_dir_test.cljs b/src/test/frontend/worker/graph_dir_test.cljs
new file mode 100644
index 0000000000..34d8ae8d1f
--- /dev/null
+++ b/src/test/frontend/worker/graph_dir_test.cljs
@@ -0,0 +1,39 @@
+(ns frontend.worker.graph-dir-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [frontend.worker.graph-dir :as graph-dir]))
+
+(deftest repo->graph-dir-key-strips-db-prefix
+  (testing "db-prefixed repo is mapped to prefix-free graph dir key"
+    (is (= "demo" (graph-dir/repo->graph-dir-key "logseq_db_demo")))))
+
+(deftest repo->graph-dir-key-keeps-prefix-free-name
+  (testing "prefix-free repo remains unchanged"
+    (is (= "demo" (graph-dir/repo->graph-dir-key "demo")))))
+
+(deftest repo->encoded-graph-dir-name-encodes-special-characters
+  (testing "db-prefixed repos resolve to the encoded on-disk graph dir name"
+    (is (= "foo~2Fbar"
+           (graph-dir/repo->encoded-graph-dir-name "logseq_db_foo/bar")))
+    (is (= "space name"
+           (graph-dir/repo->encoded-graph-dir-name "logseq_db_space name")))))
+
+(deftest decode-graph-dir-name-decodes-only-canonical-encoded-names
+  (testing "encoded graph dirs decode back to the logical graph dir key"
+    (is (= "foo/bar"
+           (graph-dir/decode-graph-dir-name "foo~2Fbar"))))
+  (testing "legacy graph-dir encodings are not accepted"
+    (is (nil? (graph-dir/decode-graph-dir-name "foo++bar")))
+    (is (nil? (graph-dir/decode-graph-dir-name "a+3A+b")))))
+
+(deftest decode-legacy-graph-dir-name-derives-only-legacy-compatible-names
+  (testing "legacy token encoding decodes into graph name"
+    (is (= "foo/bar"
+           (graph-dir/decode-legacy-graph-dir-name "foo++bar")))
+    (is (= "a:b"
+           (graph-dir/decode-legacy-graph-dir-name "a+3A+b"))))
+  (testing "legacy uri-encoded names decode when valid"
+    (is (= "space name"
+           (graph-dir/decode-legacy-graph-dir-name "space%20name"))))
+  (testing "invalid or canonical names are ignored"
+    (is (nil? (graph-dir/decode-legacy-graph-dir-name "foo~2Fbar")))
+    (is (nil? (graph-dir/decode-legacy-graph-dir-name "bad%ZZname")))))
diff --git a/src/test/frontend/worker/node_sync_test.cljs b/src/test/frontend/worker/node_sync_test.cljs
new file mode 100644
index 0000000000..b781441a22
--- /dev/null
+++ b/src/test/frontend/worker/node_sync_test.cljs
@@ -0,0 +1,69 @@
+(ns frontend.worker.node-sync-test
+  (:require
+   [cljs.test :refer [async deftest is]]
+   [frontend.worker.platform :as platform]
+   [frontend.worker.state :as worker-state]
+   [frontend.worker.sync :as db-sync]
+   [promesa.core :as p]))
+
+(def ^:private test-repo "test-db-sync-repo")
+
+(deftest resolve-ws-token-cli-owner-source-reads-state-token-test
+  (async done
+         (let [refresh-calls (atom 0)
+               config-prev @worker-state/*db-sync-config
+               state-prev @worker-state/*state
+               main-thread-prev @worker-state/*main-thread]
+           (reset! worker-state/*db-sync-config {:ws-url "wss://example.com/sync/%s"})
+           (reset! worker-state/*state (assoc state-prev :auth/id-token "state-token"))
+           (reset! worker-state/*main-thread
+                   (fn [qkw _direct-pass? _args-list]
+                     (when (= qkw :thread-api/ensure-id&access-token)
+                       (swap! refresh-calls inc))
+                     (p/resolved {:id-token "refreshed-token"})))
+           (with-redefs [platform/current (fn [] {:env {:runtime :node
+                                                        :owner-source :cli}})
+                         db-sync/id-token-expired? (fn [_token] true)]
+             (-> (#'db-sync/<resolve-ws-token)
+                 (p/then (fn [token]
+                           (is (= 0 @refresh-calls))
+                           (is (= "state-token" token))
+                           (is (= "state-token" (worker-state/get-id-token)))
+                           (reset! worker-state/*main-thread main-thread-prev)
+                           (reset! worker-state/*db-sync-config config-prev)
+                           (reset! worker-state/*state state-prev)
+                           (done)))
+                 (p/catch (fn [error]
+                            (reset! worker-state/*main-thread main-thread-prev)
+                            (reset! worker-state/*db-sync-config config-prev)
+                            (reset! worker-state/*state state-prev)
+                            (is nil (str error))
+                            (done))))))))
+
+(deftest connect-uses-platform-websocket-adapter-test
+  (let [ws-ctor-prev js/WebSocket
+        state-prev @worker-state/*state
+        platform-map {:runtime :test}
+        ws-calls (atom [])
+        attach-calls (atom [])]
+    (set! js/WebSocket (js* "(function(_url){ this.readyState = 1; })"))
+    (reset! worker-state/*state (assoc state-prev :auth/id-token "token-123"))
+    (try
+      (with-redefs [platform/current (fn [] platform-map)
+                    platform/websocket-connect (fn [platform' url]
+                                                 (swap! ws-calls conj {:platform platform' :url url})
+                                                 (js-obj))
+                    db-sync/attach-ws-handlers! (fn [repo _client ws url]
+                                                  (swap! attach-calls conj {:repo repo :ws ws :url url}))]
+        (let [connected (#'db-sync/connect! test-repo {:repo test-repo} "wss://example.com/sync/graph-1")
+              ws (:ws connected)]
+          (is (= [{:platform platform-map
+                   :url "wss://example.com/sync/graph-1?token=token-123"}]
+                 @ws-calls))
+          (is (= [{:repo test-repo
+                   :ws ws
+                   :url "wss://example.com/sync/graph-1"}]
+                 @attach-calls))))
+      (finally
+        (reset! worker-state/*state state-prev)
+        (set! js/WebSocket ws-ctor-prev)))))
diff --git a/src/test/frontend/worker/platform_node_test.cljs b/src/test/frontend/worker/platform_node_test.cljs
new file mode 100644
index 0000000000..871412ee6c
--- /dev/null
+++ b/src/test/frontend/worker/platform_node_test.cljs
@@ -0,0 +1,371 @@
+(ns frontend.worker.platform-node-test
+  (:require ["fs" :as fs]
+            ["keytar" :as keytar]
+            ["path" :as node-path]
+            [cljs.test :refer [async deftest is testing]]
+            [clojure.string :as string]
+            [frontend.test.node-helper :as node-helper]
+            [frontend.worker.platform.node :as platform-node]
+            [goog.object :as gobj]
+            [promesa.core :as p]))
+
+(defn- node-platform-source
+  []
+  (let [source-path (node-path/join (.cwd js/process)
+                                    "src"
+                                    "main"
+                                    "frontend"
+                                    "worker"
+                                    "platform"
+                                    "node.cljs")]
+    (.toString (fs/readFileSync source-path) "utf8")))
+
+(defn- js-bind
+  [pairs]
+  (let [bind (js-obj)]
+    (doseq [[k v] pairs]
+      (gobj/set bind k v))
+    bind))
+
+(defn- <open-test-db
+  []
+  (let [root-dir (node-helper/create-tmp-dir "platform-node")
+        db-path (node-path/join root-dir "db.sqlite")]
+    (p/let [platform (platform-node/node-platform {:root-dir root-dir})
+            sqlite (:sqlite platform)
+            db ((:open-db sqlite) {:path db-path})]
+      {:sqlite sqlite
+       :db db})))
+
+(defn- close-db!
+  [{:keys [sqlite db]}]
+  (when (and sqlite db)
+    (try
+      ((:close-db sqlite) db)
+      (catch :default _ nil))))
+
+(defn- exec!
+  ([sqlite db sql]
+   ((:exec sqlite) db sql))
+  ([sqlite db sql bind row-mode]
+   (let [opts (js-obj "sql" sql)]
+     (when (some? bind)
+       (gobj/set opts "bind" bind))
+     (when (some? row-mode)
+       (gobj/set opts "rowMode" row-mode))
+     ((:exec sqlite) db opts))))
+
+(deftest node-platform-runtime-dependency-is-node-sqlite
+  (let [source (node-platform-source)]
+    (is (string/includes? source "\"node:sqlite\""))
+    (is (not (string/includes? source "\"better-sqlite3\"")))))
+
+(deftest node-platform-backup-uses-shared-sqlite-backup-implementation
+  (let [source (node-platform-source)]
+    (is (string/includes? source "logseq.db.sqlite.backup"))
+    (is (string/includes? source "sqlite-backup/backup-connection!"))))
+
+(deftest node-platform-env-owner-source-is-propagated
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "platform-node-owner-source")]
+      (-> (p/let [platform-cli (platform-node/node-platform {:root-dir root-dir
+                                                              :owner-source :cli})
+                  platform-default (platform-node/node-platform {:root-dir root-dir})]
+            (is (= :cli (get-in platform-cli [:env :owner-source])))
+            (is (= :unknown (get-in platform-default [:env :owner-source]))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest node-platform-cli-owner-bypasses-keychain-in-cli-e2e-test
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "platform-node-cli-secrets")
+          process-env (.-env js/process)
+          original-cli-e2e-test (gobj/get process-env "CLI_E2E_TEST")
+          calls (atom {:save 0 :read 0 :delete 0})
+          original-save (gobj/get keytar "setPassword")
+          original-read (gobj/get keytar "getPassword")
+          original-delete (gobj/get keytar "deletePassword")]
+      (gobj/set process-env "CLI_E2E_TEST" "1")
+      (gobj/set keytar "setPassword" (fn [& _]
+                                        (swap! calls update :save inc)
+                                        (js/Promise.resolve true)))
+      (gobj/set keytar "getPassword" (fn [& _]
+                                        (swap! calls update :read inc)
+                                        (js/Promise.resolve nil)))
+      (gobj/set keytar "deletePassword" (fn [& _]
+                                           (swap! calls update :delete inc)
+                                           (js/Promise.resolve true)))
+      (-> (p/let [platform (platform-node/node-platform {:root-dir root-dir
+                                                         :owner-source :cli})
+                  crypto (:crypto platform)
+                  kv (:kv platform)
+                  _ ((:save-secret-text! crypto) "secret-key" "secret-value")
+                  kv-value ((:get kv) "secret-key")
+                  secret-value ((:read-secret-text crypto) "secret-key")
+                  _ ((:delete-secret-text! crypto) "secret-key")
+                  kv-cleared ((:get kv) "secret-key")]
+            (is (= "secret-value" kv-value))
+            (is (= "secret-value" secret-value))
+            (is (nil? kv-cleared))
+            (is (= {:save 0 :read 0 :delete 0} @calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (gobj/set keytar "setPassword" original-save)
+                       (gobj/set keytar "getPassword" original-read)
+                       (gobj/set keytar "deletePassword" original-delete)
+                       (if (some? original-cli-e2e-test)
+                         (gobj/set process-env "CLI_E2E_TEST" original-cli-e2e-test)
+                         (gobj/remove process-env "CLI_E2E_TEST"))
+                       (done)))))))
+
+(deftest node-platform-cli-owner-uses-keychain-when-keychain-present
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "platform-node-cli-secrets-keychain")
+          process-env (.-env js/process)
+          original-cli-e2e-test (gobj/get process-env "CLI_E2E_TEST")
+          calls (atom {:save 0 :read 0 :delete 0})
+          secrets (atom {})
+          original-save (gobj/get keytar "setPassword")
+          original-read (gobj/get keytar "getPassword")
+          original-delete (gobj/get keytar "deletePassword")]
+      (gobj/remove process-env "CLI_E2E_TEST")
+      (gobj/set keytar "setPassword" (fn [_service key value]
+                                        (swap! calls update :save inc)
+                                        (swap! secrets assoc key value)
+                                        (js/Promise.resolve true)))
+      (gobj/set keytar "getPassword" (fn [_service key]
+                                        (swap! calls update :read inc)
+                                        (js/Promise.resolve (get @secrets key))))
+      (gobj/set keytar "deletePassword" (fn [_service key]
+                                           (swap! calls update :delete inc)
+                                           (swap! secrets dissoc key)
+                                           (js/Promise.resolve true)))
+      (-> (p/let [platform (platform-node/node-platform {:root-dir root-dir
+                                                         :owner-source :cli})
+                  crypto (:crypto platform)
+                  kv (:kv platform)
+                  _ ((:save-secret-text! crypto) "secret-key" "secret-value")
+                  kv-value ((:get kv) "secret-key")
+                  secret-value ((:read-secret-text crypto) "secret-key")
+                  _ ((:delete-secret-text! crypto) "secret-key")
+                  deleted-value ((:read-secret-text crypto) "secret-key")]
+            (is (nil? kv-value))
+            (is (= "secret-value" secret-value))
+            (is (nil? deleted-value))
+            (is (= {:save 1 :read 2 :delete 1} @calls)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (gobj/set keytar "setPassword" original-save)
+                       (gobj/set keytar "getPassword" original-read)
+                       (gobj/set keytar "deletePassword" original-delete)
+                       (if (some? original-cli-e2e-test)
+                         (gobj/set process-env "CLI_E2E_TEST" original-cli-e2e-test)
+                         (gobj/remove process-env "CLI_E2E_TEST"))
+                       (done)))))))
+
+(deftest kv-store-preserves-uint8array-values-across-reloads-test
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "platform-node-kv-store")
+          key "rtc-encrypted-aes-key###graph-1"
+          value (js/Uint8Array. #js [1 2 3 255])]
+      (-> (p/let [platform-a (platform-node/node-platform {:root-dir root-dir})
+                  kv-a (:kv platform-a)
+                  _ ((:set! kv-a) key value)
+                  loaded-a ((:get kv-a) key)
+                  platform-b (platform-node/node-platform {:root-dir root-dir})
+                  kv-b (:kv platform-b)
+                  loaded-b ((:get kv-b) key)]
+            (is (instance? js/Uint8Array loaded-a))
+            (is (= [1 2 3 255] (vec (js->clj loaded-a))))
+            (is (instance? js/Uint8Array loaded-b))
+            (is (= [1 2 3 255] (vec (js->clj loaded-b)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest exec-sql-string-creates-schema-and-writes-data
+  (async done
+    (let [conn* (atom nil)]
+      (-> (p/let [{:keys [sqlite db] :as conn} (<open-test-db)
+                  _ (reset! conn* conn)
+                  _ (exec! sqlite db "create table kvs (addr text primary key, content text);")
+                  _ (exec! sqlite db "insert into kvs (addr, content) values ('a', 'payload');")
+                  rows (exec! sqlite db "select addr, content from kvs order by addr" nil "array")]
+            (is (= [["a" "payload"]]
+                   (mapv vec (js->clj rows)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (close-db! @conn*)
+                       (done)))))))
+
+(deftest exec-row-mode-array-returns-index-addressable-rows
+  (async done
+    (let [conn* (atom nil)]
+      (-> (p/let [{:keys [sqlite db] :as conn} (<open-test-db)
+                  _ (reset! conn* conn)
+                  _ (exec! sqlite db "create table kvs (addr text primary key, content text, addresses text);")
+                  _ (exec! sqlite db "insert into kvs (addr, content, addresses) values (?, ?, ?)"
+                           #js ["a" "alpha" "[\"x\",\"y\"]"] nil)
+                  rows (exec! sqlite db "select content, addresses from kvs where addr = ?"
+                             #js ["a"] "array")]
+            (is (array? (first rows)))
+            (is (= [["alpha" "[\"x\",\"y\"]"]]
+                   (mapv vec (js->clj rows)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (close-db! @conn*)
+                       (done)))))))
+
+(deftest exec-accepts-dollar-and-colon-bind-key-styles
+  (async done
+    (let [conn* (atom nil)]
+      (-> (p/let [{:keys [sqlite db] :as conn} (<open-test-db)
+                  _ (reset! conn* conn)
+                  _ (exec! sqlite db "create table kvs (addr text primary key, content text);")
+                  _ (exec! sqlite db "insert into kvs (addr, content) values ($addr, $content)"
+                           (js-bind [["$addr" "a"] ["$content" "dollar"]]) nil)
+                  _ (exec! sqlite db "insert into kvs (addr, content) values ($addr, $content)"
+                           (js-bind [[":addr" "b"] [":content" "colon"]]) nil)
+                  rows (exec! sqlite db "select addr, content from kvs order by addr" nil "array")]
+            (is (= [["a" "dollar"] ["b" "colon"]]
+                   (mapv vec (js->clj rows)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (close-db! @conn*)
+                       (done)))))))
+
+(deftest transaction-commits-on-success
+  (async done
+    (let [conn* (atom nil)]
+      (-> (p/let [{:keys [sqlite db] :as conn} (<open-test-db)
+                  _ (reset! conn* conn)
+                  _ (exec! sqlite db "create table tx_log (value integer);")
+                  _ ((:transaction sqlite) db
+                     (fn [tx]
+                       (.exec tx #js {:sql "insert into tx_log (value) values (?)"
+                                      :bind #js [1]})))
+                  rows (exec! sqlite db "select value from tx_log order by value" nil "array")]
+            (is (= [[1]]
+                   (mapv vec (js->clj rows)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (close-db! @conn*)
+                       (done)))))))
+
+(deftest transaction-rolls-back-when-callback-throws
+  (async done
+    (let [conn* (atom nil)]
+      (-> (p/let [{:keys [sqlite db] :as conn} (<open-test-db)
+                  _ (reset! conn* conn)
+                  _ (exec! sqlite db "create table tx_log (value integer);")
+                  _ (try
+                      ((:transaction sqlite) db
+                       (fn [tx]
+                         (.exec tx #js {:sql "insert into tx_log (value) values (?)"
+                                        :bind #js [1]})
+                         (throw (ex-info "rollback" {}))))
+                      (catch :default _ nil))
+                  rows (exec! sqlite db "select count(*) from tx_log" nil "array")]
+            (is (= [[0]]
+                   (mapv vec (js->clj rows)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (close-db! @conn*)
+                       (done)))))))
+
+(deftest nested-transactions-keep-outer-writes-after-inner-rollback
+  (async done
+    (let [conn* (atom nil)]
+      (-> (p/let [{:keys [sqlite db] :as conn} (<open-test-db)
+                  _ (reset! conn* conn)
+                  _ (exec! sqlite db "create table tx_log (value integer);")
+                  _ ((:transaction sqlite) db
+                     (fn [outer]
+                       (.exec outer #js {:sql "insert into tx_log (value) values (?)"
+                                         :bind #js [1]})
+                       (try
+                         (.transaction outer
+                                       (fn [inner]
+                                         (.exec inner #js {:sql "insert into tx_log (value) values (?)"
+                                                           :bind #js [2]})
+                                         (throw (ex-info "inner rollback" {}))))
+                         (catch :default _ nil))
+                       (.exec outer #js {:sql "insert into tx_log (value) values (?)"
+                                         :bind #js [3]})))
+                  rows (exec! sqlite db "select value from tx_log order by value" nil "array")]
+            (testing "inner failure does not commit partial write"
+              (is (= [[1] [3]]
+                     (mapv vec (js->clj rows))))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (close-db! @conn*)
+                       (done)))))))
+
+(deftest sqlite-backup-db-creates-importable-copy
+  (async done
+    (let [conn* (atom nil)
+          root-dir (node-helper/create-tmp-dir "platform-node-backup")
+          backup-path (node-path/join root-dir "backup" "copy.sqlite")]
+      (-> (p/let [platform (platform-node/node-platform {:root-dir root-dir})
+                  sqlite (:sqlite platform)
+                  db-path (node-path/join root-dir "source.sqlite")
+                  db ((:open-db sqlite) {:path db-path})
+                  _ (reset! conn* {:sqlite sqlite :db db})
+                  _ (exec! sqlite db "create table kvs (addr text primary key, content text);")
+                  _ (exec! sqlite db "insert into kvs (addr, content) values (?, ?)" #js ["a" "alpha"] nil)
+                  _ ((:backup-db sqlite) db backup-path)
+                  backup-db ((:open-db sqlite) {:path backup-path})
+                  rows (exec! sqlite backup-db "select addr, content from kvs order by addr" nil "array")
+                  _ ((:close-db sqlite) backup-db)]
+            (is (= [["a" "alpha"]]
+                   (mapv vec (js->clj rows)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (close-db! @conn*)
+                       (done)))))))
+
+(deftest storage-list-graphs-ignores-backup-root
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "platform-node-list-graphs")
+          graphs-dir (node-path/join root-dir "graphs")]
+      (fs/mkdirSync (node-path/join graphs-dir "alpha") #js {:recursive true})
+      (fs/mkdirSync (node-path/join graphs-dir "backup") #js {:recursive true})
+      (-> (p/let [platform (platform-node/node-platform {:root-dir root-dir})
+                  graphs ((get-in platform [:storage :list-graphs]))]
+            (is (= ["alpha"] graphs)))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest remove-vfs-removes-lock-file
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "platform-node-remove-vfs")
+          lock-json "{\"repo\":\"logseq_db_demo\",\"pid\":1,\"host\":\"127.0.0.1\",\"port\":9001}"]
+      (-> (p/let [platform (platform-node/node-platform {:root-dir root-dir})
+                  storage (:storage platform)
+                  pool ((:install-opfs-pool storage) nil "logseq_db_demo")
+                  repo-dir (gobj/get pool "repoDir")
+                  lock-path (node-path/join repo-dir "db-worker.lock")
+                  db-path (node-path/join repo-dir "db.sqlite")
+                  nested-path (node-path/join repo-dir "assets" "file.bin")
+                  _ (fs/mkdirSync (node-path/dirname nested-path) #js {:recursive true})
+                  _ (fs/writeFileSync lock-path lock-json "utf8")
+                  _ (fs/writeFileSync db-path "db-bytes" "utf8")
+                  _ (fs/writeFileSync nested-path "asset-bytes" "utf8")
+                  _ ((:remove-vfs! storage) pool)]
+            (is (not (fs/existsSync lock-path)))
+            (is (not (fs/existsSync db-path)))
+            (is (not (fs/existsSync nested-path))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
diff --git a/src/test/frontend/worker/platform_test.cljs b/src/test/frontend/worker/platform_test.cljs
new file mode 100644
index 0000000000..6d121fe86b
--- /dev/null
+++ b/src/test/frontend/worker/platform_test.cljs
@@ -0,0 +1,28 @@
+(ns frontend.worker.platform-test
+  (:require [cljs.test :refer [async deftest is]]
+            [frontend.worker.platform :as platform]
+            [promesa.core :as p]))
+
+(deftest kv-get-normalizes-undefined-to-nil-test
+  (async done
+         (-> (platform/kv-get {:kv {:get (fn [_k]
+                                           (p/resolved js/undefined))}}
+                              "key")
+             (p/then (fn [value]
+                       (is (nil? value))
+                       (is (not (identical? js/undefined value)))))
+             (p/catch (fn [e]
+                        (is false (str e))))
+             (p/finally done))))
+
+(deftest read-secret-text-normalizes-undefined-to-nil-test
+  (async done
+         (-> (platform/read-secret-text {:crypto {:read-secret-text (fn [_key]
+                                                                      (p/resolved js/undefined))}}
+                                        "secret")
+             (p/then (fn [value]
+                       (is (nil? value))
+                       (is (not (identical? js/undefined value)))))
+             (p/catch (fn [e]
+                        (is false (str e))))
+             (p/finally done))))
diff --git a/src/test/frontend/worker/shared_service_test.cljs b/src/test/frontend/worker/shared_service_test.cljs
new file mode 100644
index 0000000000..0b74b9117e
--- /dev/null
+++ b/src/test/frontend/worker/shared_service_test.cljs
@@ -0,0 +1,46 @@
+(ns frontend.worker.shared-service-test
+  (:require [cljs.test :refer [deftest is async]]
+            [frontend.worker.platform :as platform]
+            [frontend.worker.shared-service :as shared-service]
+            [promesa.core :as p]))
+
+(defn- test-platform
+  [runtime]
+  {:env {:runtime runtime}
+   :storage {}
+   :kv {}
+   :broadcast {}
+   :websocket {}
+   :crypto {}
+   :timers {}
+   :sqlite {}})
+
+(deftest node-proxy-remote-invoke-applies-args
+  (async done
+    (let [prev-platform (try
+                          (platform/current)
+                          (catch :default _ nil))
+          received (atom nil)
+          target #js {"remoteInvoke" (fn [& args]
+                                       (reset! received args)
+                                       :ok)}]
+      (platform/set-platform! (test-platform :node))
+      (-> (p/let [service (shared-service/<create-service
+                           "test-service"
+                           target
+                           (fn [_] (p/resolved nil))
+                           #{}
+                           {:import? false})
+                  args (list "thread-api/foo" true #js [1 2])
+                  remote-invoke (aget (:proxy service) "remoteInvoke")]
+            (is (fn? remote-invoke))
+            (when (fn? remote-invoke)
+              (remote-invoke args))
+            (let [[method direct-pass? payload] @received]
+              (is (= "thread-api/foo" method))
+              (is (= true direct-pass?))
+              (is (= [1 2] (js->clj payload)))))
+          (p/finally (fn []
+                       (when prev-platform
+                         (platform/set-platform! prev-platform))))
+          (p/then (fn [] (done)))))))
diff --git a/src/test/frontend/worker/state_test.cljs b/src/test/frontend/worker/state_test.cljs
new file mode 100644
index 0000000000..f056df8a64
--- /dev/null
+++ b/src/test/frontend/worker/state_test.cljs
@@ -0,0 +1,32 @@
+(ns frontend.worker.state-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [frontend.worker.platform :as platform]
+            [frontend.worker.state :as worker-state]))
+
+(defn- with-online-event
+  [value]
+  (assoc @worker-state/*state :thread-atom/online-event (atom value)))
+
+(deftest online?-uses-thread-atom-in-non-node-runtime
+  (let [state-prev @worker-state/*state]
+    (try
+      (with-redefs [platform/current (fn []
+                                       {:env {:runtime :web}})]
+        (reset! worker-state/*state (with-online-event true))
+        (testing "web runtime stays compatible with main-thread online-event"
+          (is (true? (worker-state/online?))))
+        (reset! worker-state/*state (with-online-event false))
+        (is (false? (worker-state/online?))))
+      (finally
+        (reset! worker-state/*state state-prev)))))
+
+(deftest online?-node-runtime-does-not-require-main-thread-online-event
+  (let [state-prev @worker-state/*state]
+    (try
+      (with-redefs [platform/current (fn []
+                                       {:env {:runtime :node}})]
+        (reset! worker-state/*state (with-online-event nil))
+        (testing "node runtime should provide its own online detection"
+          (is (true? (worker-state/online?)))))
+      (finally
+        (reset! worker-state/*state state-prev)))))
diff --git a/src/test/frontend/worker/sync/crypt_test.cljs b/src/test/frontend/worker/sync/crypt_test.cljs
index 25e0e20d27..c72e586301 100644
--- a/src/test/frontend/worker/sync/crypt_test.cljs
+++ b/src/test/frontend/worker/sync/crypt_test.cljs
@@ -1,7 +1,14 @@
 (ns frontend.worker.sync.crypt-test
   (:require [cljs.test :refer [deftest is async]]
+            [clojure.string :as string]
             [frontend.common.crypt :as crypt]
+            [frontend.worker-common.util :as worker-util]
+            [frontend.worker.platform :as platform]
+            [frontend.worker.state :as worker-state]
+            [frontend.worker.sync.auth :as sync-auth]
             [frontend.worker.sync.crypt :as sync-crypt]
+            [frontend.worker.sync.util :as sync-util]
+            [frontend.worker.ui-request :as ui-request]
             [logseq.db :as ldb]
             [promesa.core :as p]))
 
@@ -12,6 +19,738 @@
   (p/let [encrypted (crypt/<encrypt-text aes-key (ldb/write-transit-str value))]
     (ldb/write-transit-str encrypted)))
 
+(deftest cli-node-auth-token-reads-state-test
+  (let [config-prev @worker-state/*db-sync-config
+        state-prev @worker-state/*state]
+    (reset! worker-state/*db-sync-config {:ws-url "wss://example.com/sync/%s"})
+    (reset! worker-state/*state (assoc state-prev :auth/id-token "state-token"))
+    (try
+      (with-redefs [platform/current (fn [] {:env {:runtime :node
+                                                   :owner-source :cli}})]
+        (is (= "state-token" (sync-util/auth-token))))
+      (finally
+        (reset! worker-state/*db-sync-config config-prev)
+        (reset! worker-state/*state state-prev)))))
+
+(deftest cli-node-get-user-uuid-reads-state-token-test
+  (let [config-prev @worker-state/*db-sync-config
+        state-prev @worker-state/*state]
+    (reset! worker-state/*db-sync-config {:ws-url "wss://example.com/sync/%s"})
+    (reset! worker-state/*state (assoc state-prev :auth/id-token "state-token"))
+    (try
+      (with-redefs [platform/current (fn [] {:env {:runtime :node
+                                                   :owner-source :cli}})
+                    worker-util/parse-jwt (fn [token]
+                                            (if (= token "state-token")
+                                              {:sub "state-user-id"}
+                                              {}))]
+        (is (= "state-user-id" (#'sync-crypt/get-user-uuid))))
+      (finally
+        (reset! worker-state/*db-sync-config config-prev)
+        (reset! worker-state/*state state-prev)))))
+
+(deftest desktop-token-path-keeps-id-token-behavior-test
+  (let [config-prev @worker-state/*db-sync-config
+        state-prev @worker-state/*state]
+    (reset! worker-state/*db-sync-config {:ws-url "wss://example.com/sync/%s"})
+    (reset! worker-state/*state (assoc state-prev :auth/id-token "state-token"))
+    (try
+      (with-redefs [platform/current (fn [] {:env {:runtime :node
+                                                   :owner-source :electron}})
+                    worker-util/parse-jwt (fn [token]
+                                            (if (= token "state-token")
+                                              {:sub "state-user-id"}
+                                              {}))]
+        (is (= "state-token" (sync-util/auth-token)))
+        (is (= "state-user-id" (#'sync-crypt/get-user-uuid))))
+      (finally
+        (reset! worker-state/*db-sync-config config-prev)
+        (reset! worker-state/*state state-prev)))))
+
+(deftest resolve-user-uuid-falls-back-to-resolved-token-test
+  (async done
+         (-> (p/with-redefs [sync-crypt/get-user-uuid (fn [] nil)
+                             sync-auth/<resolve-ws-token (fn [] (p/resolved "fresh-token"))
+                             worker-util/parse-jwt (fn [token]
+                                                     (if (= token "fresh-token")
+                                                       {:sub "fresh-user-id"}
+                                                       {}))]
+               (#'sync-crypt/<resolve-user-uuid))
+             (p/then (fn [user-id]
+                       (is (= "fresh-user-id" user-id))))
+             (p/catch (fn [e]
+                        (is false (str e))))
+             (p/finally done))))
+
+(deftest get-item-preserves-uint8array-type-test
+  (async done
+         (let [expected (js/Uint8Array. #js [9 8 7])]
+           (-> (p/with-redefs [platform/current (fn [] {:runtime :test})
+                               platform/kv-get (fn [_platform' _k]
+                                                 (p/resolved expected))]
+                 (#'sync-crypt/<get-item "rtc-encrypted-aes-key###graph-1"))
+               (p/then (fn [result]
+                         (is (instance? js/Uint8Array result))
+                         (is (= [9 8 7] (vec (js->clj result))))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally done)))))
+
+(deftest graph-e2ee-preserves-nil-kv-value-test
+  (with-redefs [worker-state/get-datascript-conn (fn [_repo]
+                                                    (atom {}))
+                ldb/get-graph-rtc-e2ee? (fn [_db]
+                                          nil)]
+    (is (nil? (sync-crypt/graph-e2ee? "logseq_db_demo")))))
+
+(deftest graph-e2ee-preserves-false-kv-value-test
+  (with-redefs [worker-state/get-datascript-conn (fn [_repo]
+                                                    (atom {}))
+                ldb/get-graph-rtc-e2ee? (fn [_db]
+                                          false)]
+    (is (= false (sync-crypt/graph-e2ee? "logseq_db_demo")))))
+
+(deftest save-e2ee-password-uses-secret-storage-in-browser-runtime-test
+  (async done
+         (let [platform-map {:env {:runtime :browser}}
+               state-prev @worker-state/*state
+               secret-calls (atom [])
+               file-calls (atom [])
+               auth-read-calls (atom [])
+               encrypt-calls (atom [])]
+           (reset! worker-state/*state (assoc state-prev :auth/refresh-token "refresh-from-state"))
+           (-> (p/with-redefs [crypt/<encrypt-text-by-text-password (fn [refresh-token password]
+                                                                      (swap! encrypt-calls conj [refresh-token password])
+                                                                      {:cipher "payload"})
+                               platform/current (fn [] platform-map)
+                               platform/read-text! (fn [platform' path]
+                                                     (swap! auth-read-calls conj {:platform platform'
+                                                                                  :path path})
+                                                     (p/resolved "{\"refresh-token\":\"refresh-from-auth-file\"}"))
+                               platform/save-secret-text! (fn [platform' key text]
+                                                            (swap! secret-calls conj {:platform platform'
+                                                                                      :key key
+                                                                                      :text text})
+                                                            (p/resolved nil))
+                               platform/write-text! (fn [platform' path text]
+                                                      (swap! file-calls conj {:platform platform'
+                                                                              :path path
+                                                                              :text text})
+                                                      (p/resolved nil))]
+                 (#'sync-crypt/<save-e2ee-password "password"))
+               (p/then (fn [_]
+                         (is (empty? @auth-read-calls))
+                         (is (= [["refresh-from-state" "password"]] @encrypt-calls))
+                         (is (= 1 (count @secret-calls)))
+                         (is (= platform-map (:platform (first @secret-calls))))
+                         (is (= "logseq-encrypted-password" (:key (first @secret-calls))))
+                         (is (string? (:text (first @secret-calls))))
+                         (is (empty? @file-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally (fn []
+                            (reset! worker-state/*state state-prev)
+                            (done)))))))
+
+(deftest save-e2ee-password-uses-native-storage-in-capacitor-runtime-test
+  (async done
+         (let [platform-map {:env {:runtime :browser
+                                   :owner-source :capacitor}}
+               state-prev @worker-state/*state
+               native-calls (atom [])
+               secret-calls (atom [])
+               file-calls (atom [])
+               encrypt-calls (atom [])]
+           (reset! worker-state/*state (assoc state-prev :auth/refresh-token "refresh-from-state"))
+           (-> (p/with-redefs [crypt/<encrypt-text-by-text-password (fn [refresh-token password]
+                                                                      (swap! encrypt-calls conj [refresh-token password])
+                                                                      {:cipher "payload"})
+                               platform/current (fn [] platform-map)
+                               ui-request/<request (fn [action payload _opts]
+                                                     (swap! native-calls conj {:action action
+                                                                               :payload payload})
+                                                     (p/resolved {:supported? true}))
+                               platform/save-secret-text! (fn [platform' key text]
+                                                            (swap! secret-calls conj {:platform platform'
+                                                                                      :key key
+                                                                                      :text text})
+                                                            (p/resolved nil))
+                               platform/write-text! (fn [platform' path text]
+                                                      (swap! file-calls conj {:platform platform'
+                                                                              :path path
+                                                                              :text text})
+                                                      (p/resolved nil))]
+                 (#'sync-crypt/<save-e2ee-password "password"))
+               (p/then (fn [_]
+                         (is (= [["refresh-from-state" "password"]] @encrypt-calls))
+                         (is (= 1 (count @native-calls)))
+                         (is (= :native-save-e2ee-password (:action (first @native-calls))))
+                         (is (= "logseq-encrypted-password"
+                                (get-in (first @native-calls) [:payload :key])))
+                         (is (string? (get-in (first @native-calls) [:payload :encrypted-text])))
+                         (is (empty? @secret-calls))
+                         (is (empty? @file-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally (fn []
+                            (reset! worker-state/*state state-prev)
+                            (done)))))))
+
+(deftest save-e2ee-password-uses-secret-storage-in-node-runtime-test
+  (async done
+         (let [platform-map {:env {:runtime :node
+                                   :owner-source :cli}}
+               secret-calls (atom [])
+               file-calls (atom [])
+               auth-read-calls (atom [])
+               encrypt-calls (atom [])]
+           (-> (p/with-redefs [crypt/<encrypt-text-by-text-password (fn [refresh-token password]
+                                                                      (swap! encrypt-calls conj [refresh-token password])
+                                                                      {:cipher "payload"})
+                               platform/current (fn [] platform-map)
+                               platform/read-text! (fn [platform' path]
+                                                     (swap! auth-read-calls conj {:platform platform'
+                                                                                  :path path})
+                                                     (p/resolved "{\"refresh-token\":\"refresh-from-auth-file\"}"))
+                               platform/save-secret-text! (fn [platform' key text]
+                                                            (swap! secret-calls conj {:platform platform'
+                                                                                      :key key
+                                                                                      :text text})
+                                                            (p/resolved nil))
+                               platform/write-text! (fn [platform' path text]
+                                                      (swap! file-calls conj {:platform platform'
+                                                                              :path path
+                                                                              :text text})
+                                                      (p/resolved nil))]
+                 (#'sync-crypt/<save-e2ee-password "password"))
+               (p/then (fn [_]
+                         (is (= 1 (count @auth-read-calls)))
+                         (is (= "~/logseq/auth.json" (:path (first @auth-read-calls))))
+                         (is (= [["refresh-from-auth-file" "password"]] @encrypt-calls))
+                         (is (= 1 (count @secret-calls)))
+                         (is (= platform-map (:platform (first @secret-calls))))
+                         (is (= "logseq-encrypted-password" (:key (first @secret-calls))))
+                         (is (string? (:text (first @secret-calls))))
+                         (is (empty? @file-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally done)))))
+
+(deftest save-e2ee-password-uses-secret-storage-in-electron-runtime-test
+  (async done
+         (let [platform-map {:env {:runtime :node
+                                   :owner-source :electron}}
+               secret-calls (atom [])
+               file-calls (atom [])
+               auth-read-calls (atom [])
+               encrypt-calls (atom [])]
+           (-> (p/with-redefs [crypt/<encrypt-text-by-text-password (fn [refresh-token password]
+                                                                      (swap! encrypt-calls conj [refresh-token password])
+                                                                      {:cipher "payload"})
+                               platform/current (fn [] platform-map)
+                               platform/read-text! (fn [platform' path]
+                                                     (swap! auth-read-calls conj {:platform platform'
+                                                                                  :path path})
+                                                     (p/resolved "{\"refresh-token\":\"refresh-from-auth-file\"}"))
+                               platform/save-secret-text! (fn [platform' key text]
+                                                            (swap! secret-calls conj {:platform platform'
+                                                                                      :key key
+                                                                                      :text text})
+                                                            (p/resolved nil))
+                               platform/write-text! (fn [platform' path text]
+                                                      (swap! file-calls conj {:platform platform'
+                                                                              :path path
+                                                                              :text text})
+                                                      (p/resolved nil))]
+                 (#'sync-crypt/<save-e2ee-password "password"))
+               (p/then (fn [_]
+                         (is (= 1 (count @auth-read-calls)))
+                         (is (= "~/logseq/auth.json" (:path (first @auth-read-calls))))
+                         (is (= [["refresh-from-auth-file" "password"]] @encrypt-calls))
+                         (is (= 1 (count @secret-calls)))
+                         (is (= platform-map (:platform (first @secret-calls))))
+                         (is (= "logseq-encrypted-password" (:key (first @secret-calls))))
+                         (is (string? (:text (first @secret-calls))))
+                         (is (empty? @file-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally done)))))
+
+(deftest save-e2ee-password-missing-refresh-token-in-auth-file-test
+  (async done
+         (let [platform-map {:env {:runtime :node
+                                   :owner-source :cli}}
+               encrypt-calls (atom 0)]
+           (-> (p/with-redefs [platform/current (fn [] platform-map)
+                               platform/read-text! (fn [_platform' _path]
+                                                     (p/resolved "{\"refresh-token\":\"\"}"))
+                               crypt/<encrypt-text-by-text-password (fn [_refresh-token _password]
+                                                                      (swap! encrypt-calls inc)
+                                                                      (p/rejected (ex-info "should-not-encrypt" {})))]
+                 (#'sync-crypt/<save-e2ee-password "password"))
+               (p/then (fn [_]
+                         (is false "expected missing refresh-token failure")))
+               (p/catch (fn [e]
+                          (is (contains? #{:db-sync/missing-e2ee-password
+                                           :missing-e2ee-password}
+                                         (or (:code (ex-data e))
+                                             (keyword (ex-message e)))))
+                          (is (zero? @encrypt-calls))))
+               (p/finally done)))))
+
+(deftest read-e2ee-password-uses-secret-storage-in-browser-runtime-test
+  (async done
+         (let [platform-map {:env {:runtime :browser}}
+               secret-calls (atom [])
+               file-calls (atom [])]
+           (-> (p/with-redefs [platform/current (fn [] platform-map)
+                               platform/read-secret-text (fn [platform' key]
+                                                           (swap! secret-calls conj {:platform platform'
+                                                                                     :key key})
+                                                           (p/resolved (ldb/write-transit-str {:cipher "payload"})))
+                               platform/read-text! (fn [platform' path]
+                                                     (swap! file-calls conj {:platform platform'
+                                                                             :path path})
+                                                     (p/resolved (ldb/write-transit-str {:cipher "legacy"})))
+                               crypt/<decrypt-text-by-text-password (fn [_refresh-token _data]
+                                                                      (p/resolved "decrypted-password"))]
+                 (#'sync-crypt/<read-e2ee-password "refresh-token"))
+               (p/then (fn [password]
+                         (is (= "decrypted-password" password))
+                         (is (= 1 (count @secret-calls)))
+                         (is (= "logseq-encrypted-password" (:key (first @secret-calls))))
+                         (is (empty? @file-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally done)))))
+
+(deftest read-e2ee-password-uses-native-storage-in-capacitor-runtime-test
+  (async done
+         (let [platform-map {:env {:runtime :browser
+                                   :owner-source :capacitor}}
+               native-calls (atom [])
+               secret-calls (atom [])
+               file-calls (atom [])]
+           (-> (p/with-redefs [platform/current (fn [] platform-map)
+                               ui-request/<request (fn [action payload _opts]
+                                                     (swap! native-calls conj {:action action
+                                                                               :payload payload})
+                                                     (p/resolved {:supported? true
+                                                                  :encrypted-text (ldb/write-transit-str {:cipher "payload"})}))
+                               platform/read-secret-text (fn [platform' key]
+                                                           (swap! secret-calls conj {:platform platform'
+                                                                                     :key key})
+                                                           (p/resolved (ldb/write-transit-str {:cipher "legacy"})))
+                               platform/read-text! (fn [platform' path]
+                                                     (swap! file-calls conj {:platform platform'
+                                                                             :path path})
+                                                     (p/resolved (ldb/write-transit-str {:cipher "legacy"})))
+                               crypt/<decrypt-text-by-text-password (fn [_refresh-token _data]
+                                                                      (p/resolved "decrypted-password"))]
+                 (#'sync-crypt/<read-e2ee-password "refresh-token"))
+               (p/then (fn [password]
+                         (is (= "decrypted-password" password))
+                         (is (= [{:action :native-get-e2ee-password
+                                  :payload {:key "logseq-encrypted-password"}}]
+                                @native-calls))
+                         (is (empty? @secret-calls))
+                         (is (empty? @file-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally done)))))
+
+(deftest read-e2ee-password-uses-secret-storage-in-node-runtime-test
+  (async done
+         (let [platform-map {:env {:runtime :node
+                                   :owner-source :cli}}
+               secret-calls (atom [])
+               file-calls (atom [])]
+           (-> (p/with-redefs [platform/current (fn [] platform-map)
+                               platform/read-secret-text (fn [platform' key]
+                                                           (swap! secret-calls conj {:platform platform'
+                                                                                     :key key})
+                                                           (p/resolved (ldb/write-transit-str {:cipher "payload"})))
+                               platform/read-text! (fn [platform' path]
+                                                     (swap! file-calls conj {:platform platform'
+                                                                             :path path})
+                                                     (p/resolved (ldb/write-transit-str {:cipher "legacy"})))
+                               crypt/<decrypt-text-by-text-password (fn [_refresh-token _data]
+                                                                      (p/resolved "decrypted-password"))]
+                 (#'sync-crypt/<read-e2ee-password "refresh-token"))
+               (p/then (fn [password]
+                         (is (= "decrypted-password" password))
+                         (is (= 1 (count @secret-calls)))
+                         (is (= "logseq-encrypted-password" (:key (first @secret-calls))))
+                         (is (empty? @file-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally done)))))
+
+(deftest read-e2ee-password-uses-secret-storage-in-electron-runtime-test
+  (async done
+         (let [platform-map {:env {:runtime :node
+                                   :owner-source :electron}}
+               secret-calls (atom [])
+               file-calls (atom [])]
+           (-> (p/with-redefs [platform/current (fn [] platform-map)
+                               platform/read-secret-text (fn [platform' key]
+                                                           (swap! secret-calls conj {:platform platform'
+                                                                                     :key key})
+                                                           (p/resolved (ldb/write-transit-str {:cipher "payload"})))
+                               platform/read-text! (fn [platform' path]
+                                                     (swap! file-calls conj {:platform platform'
+                                                                             :path path})
+                                                     (p/resolved (ldb/write-transit-str {:cipher "legacy"})))
+                               crypt/<decrypt-text-by-text-password (fn [_refresh-token _data]
+                                                                      (p/resolved "decrypted-password"))]
+                 (#'sync-crypt/<read-e2ee-password "refresh-token"))
+               (p/then (fn [password]
+                         (is (= "decrypted-password" password))
+                         (is (= 1 (count @secret-calls)))
+                         (is (= "logseq-encrypted-password" (:key (first @secret-calls))))
+                         (is (empty? @file-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally done)))))
+
+(deftest read-e2ee-password-browser-missing-secret-does-not-fallback-to-file-test
+  (async done
+         (let [platform-map {:env {:runtime :browser}}
+               secret-read-calls (atom 0)
+               file-read-calls (atom 0)]
+           (-> (p/with-redefs [platform/current (fn [] platform-map)
+                               platform/read-secret-text (fn [_platform' _key]
+                                                           (swap! secret-read-calls inc)
+                                                           (p/resolved nil))
+                               platform/read-text! (fn [_platform' _path]
+                                                     (swap! file-read-calls inc)
+                                                     (p/resolved (ldb/write-transit-str {:cipher "legacy"})))
+                               crypt/<decrypt-text-by-text-password (fn [_refresh-token _data]
+                                                                      (p/rejected (ex-info "should-not-decrypt" {})))]
+                 (#'sync-crypt/<read-e2ee-password "refresh-token"))
+               (p/then (fn [_]
+                         (is false "expected missing e2ee password failure")))
+               (p/catch (fn [e]
+                          (is (= 1 @secret-read-calls))
+                          (is (zero? @file-read-calls))
+                          (is (contains? #{:db-sync/missing-e2ee-password
+                                           :missing-e2ee-password}
+                                         (or (:code (ex-data e))
+                                             (keyword (ex-message e)))))))
+               (p/finally done)))))
+
+(deftest read-e2ee-password-capacitor-missing-native-secret-does-not-fallback-to-worker-storage-test
+  (async done
+         (let [platform-map {:env {:runtime :browser
+                                   :owner-source :capacitor}}
+               native-read-calls (atom 0)
+               secret-read-calls (atom 0)
+               file-read-calls (atom 0)]
+           (-> (p/with-redefs [platform/current (fn [] platform-map)
+                               ui-request/<request (fn [action payload _opts]
+                                                     (swap! native-read-calls inc)
+                                                     (is (= :native-get-e2ee-password action))
+                                                     (is (= {:key "logseq-encrypted-password"} payload))
+                                                     (p/resolved {:supported? true
+                                                                  :encrypted-text nil}))
+                               platform/read-secret-text (fn [_platform' _key]
+                                                           (swap! secret-read-calls inc)
+                                                           (p/resolved (ldb/write-transit-str {:cipher "legacy"})))
+                               platform/read-text! (fn [_platform' _path]
+                                                     (swap! file-read-calls inc)
+                                                     (p/resolved (ldb/write-transit-str {:cipher "legacy-file"})))
+                               crypt/<decrypt-text-by-text-password (fn [_refresh-token _data]
+                                                                      (p/rejected (ex-info "should-not-decrypt" {})))]
+                 (#'sync-crypt/<read-e2ee-password "refresh-token"))
+               (p/then (fn [_]
+                         (is false "expected missing e2ee password failure")))
+               (p/catch (fn [e]
+                          (is (= 1 @native-read-calls))
+                          (is (zero? @secret-read-calls))
+                          (is (zero? @file-read-calls))
+                          (is (contains? #{:db-sync/missing-e2ee-password
+                                           :missing-e2ee-password}
+                                         (or (:code (ex-data e))
+                                             (keyword (ex-message e)))))))
+               (p/finally done)))))
+
+(deftest verify-and-save-e2ee-password-verifies-before-write-test
+  (async done
+         (let [save-calls (atom [])
+               decrypt-calls (atom [])]
+           (-> (p/with-redefs [platform/current (fn [] {:env {:runtime :node
+                                                              :owner-source :cli}})
+                               ldb/read-transit-str (fn [value]
+                                                      (if (= value "encrypted-private-key")
+                                                        :encrypted-private-key-payload
+                                                        value))
+                               crypt/<decrypt-private-key (fn [password encrypted-private-key]
+                                                            (swap! decrypt-calls conj [password encrypted-private-key])
+                                                            (p/resolved :private-key))
+                               platform/read-text! (fn [_platform' _path]
+                                                     (p/resolved "{\"refresh-token\":\"refresh-token\"}"))
+                               crypt/<encrypt-text-by-text-password (fn [_refresh-token _password]
+                                                                      {:cipher "password-payload"})
+                               platform/save-secret-text! (fn [_platform' key text]
+                                                            (swap! save-calls conj {:key key
+                                                                                    :text text})
+                                                            (p/resolved nil))
+                               platform/write-text! (fn [& _]
+                                                      (p/rejected (ex-info "should not use node file storage" {})))]
+                 (#'sync-crypt/<verify-and-save-e2ee-password! "new-password"
+                                                               "encrypted-private-key"))
+               (p/then (fn [_]
+                         (is (= [["new-password" :encrypted-private-key-payload]] @decrypt-calls))
+                         (is (= 1 (count @save-calls)))
+                         (is (= "logseq-encrypted-password" (:key (first @save-calls))))
+                         (is (string? (:text (first @save-calls))))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally done)))))
+
+(deftest verify-and-save-e2ee-password-invalid-password-does-not-overwrite-test
+  (async done
+         (let [save-calls (atom 0)]
+           (-> (p/with-redefs [platform/current (fn [] {:env {:runtime :node
+                                                              :owner-source :cli}})
+                               ldb/read-transit-str (fn [_] :encrypted-private-key-payload)
+                               crypt/<decrypt-private-key (fn [_password _encrypted-private-key]
+                                                            (p/rejected (ex-info "decrypt-private-key" {:code :invalid-password})))
+                               platform/save-secret-text! (fn [_platform' _key _text]
+                                                            (swap! save-calls inc)
+                                                            (p/resolved nil))]
+                 (#'sync-crypt/<verify-and-save-e2ee-password! "wrong-password"
+                                                               "encrypted-private-key"))
+               (p/then (fn [_]
+                         (is false "expected verify failure")))
+               (p/catch (fn [e]
+                          (is (= "decrypt-private-key" (ex-message e)))
+                          (is (zero? @save-calls))))
+               (p/finally done)))))
+
+(deftest verify-and-save-e2ee-password-invalid-server-user-keys-shape-test
+  (async done
+         (-> (p/with-redefs [platform/current (fn [] {:env {:runtime :node
+                                                            :owner-source :cli}})
+                             sync-crypt/e2ee-base (fn [] "https://example.com")
+                             sync-crypt/<resolve-user-uuid (fn [] (p/resolved "user-1"))
+                             sync-crypt/<get-item (fn [_k] (p/resolved nil))
+                             sync-crypt/<fetch-user-rsa-key-pair-raw (fn [_base]
+                                                                       (p/resolved :public-key))
+                             crypt/<decrypt-private-key (fn [_password _encrypted-private-key]
+                                                          (p/rejected (ex-info "should-not-decrypt" {})))]
+               (#'sync-crypt/<verify-and-save-e2ee-password-from-server! "password"))
+             (p/then (fn [_]
+                       (is false "expected missing-field failure")))
+             (p/catch (fn [e]
+                        (let [data (ex-data e)]
+                          (is (contains? #{:db-sync/missing-field :missing-field}
+                                         (or (:code data)
+                                             (keyword (ex-message e)))))
+                          (is (= :encrypted-private-key (:field data)))
+                          (is (not= ":public-key is not ISeqable" (ex-message e))))))
+             (p/finally done))))
+
+(deftest decrypt-private-key-headless-ignores-config-e2ee-password-test
+  (async done
+         (let [old-sync-config @worker-state/*db-sync-config
+               old-state @worker-state/*state]
+           (reset! worker-state/*db-sync-config {:e2ee-password "legacy-config-password"
+                                                 :auth-token "legacy-auth-token"})
+           (swap! worker-state/*state assoc :auth/refresh-token nil)
+           (-> (p/with-redefs [platform/current (fn [] {:env {:runtime :node
+                                                              :owner-source :cli}})
+                               ldb/read-transit-str (fn [_] :encrypted-private-key)
+                               crypt/<decrypt-private-key (fn [_password _encrypted-private-key]
+                                                            (p/rejected (ex-info "should-not-use-config-password" {})))
+                               ui-request/<request (fn [_action _payload _opts]
+                                                     (p/rejected (ex-info "should-not-request-ui-in-headless" {})))]
+                 (#'sync-crypt/<decrypt-private-key "encrypted-private-key-str"))
+               (p/then (fn [_]
+                         (is false "expected missing e2ee password failure")))
+               (p/catch (fn [e]
+                          (is (contains? #{:db-sync/missing-e2ee-password
+                                           :missing-e2ee-password}
+                                         (or (:code (ex-data e))
+                                             (keyword (ex-message e)))))))
+               (p/finally (fn []
+                            (reset! worker-state/*db-sync-config old-sync-config)
+                            (reset! worker-state/*state old-state)
+                            (done)))))))
+
+(deftest decrypt-private-key-browser-fallback-does-not-log-missing-persisted-password-test
+  (async done
+         (let [old-state @worker-state/*state
+               fail-calls (atom [])
+               decrypt-calls (atom [])
+               save-calls (atom [])]
+           (reset! worker-state/*state (assoc old-state :auth/refresh-token "refresh-token"))
+           (-> (p/with-redefs [platform/current (fn [] {:env {:runtime :browser}})
+                               platform/read-secret-text (fn [_platform' _key]
+                                                           (p/resolved nil))
+                               platform/read-text! (fn [_platform' _path]
+                                                     (p/rejected (ex-info "should-not-read-browser-file" {})))
+                               ui-request/<request (fn [_action payload _opts]
+                                                     (is (= {:reason :decrypt-user-rsa-private-key} payload))
+                                                     (p/resolved {:password "ui-password"}))
+                               sync-crypt/fail-missing-e2ee-password! (fn [data]
+                                                                       (swap! fail-calls conj data)
+                                                                       (throw (ex-info "missing-e2ee-password" data)))
+                               ldb/read-transit-str (fn [_] :encrypted-private-key)
+                               crypt/<decrypt-private-key (fn [password encrypted-private-key]
+                                                            (swap! decrypt-calls conj [password encrypted-private-key])
+                                                            (p/resolved :private-key))
+                               crypt/<encrypt-text-by-text-password (fn [refresh-token password]
+                                                                      (swap! save-calls conj [:encrypt refresh-token password])
+                                                                      {:cipher "password-payload"})
+                               platform/save-secret-text! (fn [_platform' key text]
+                                                            (swap! save-calls conj [:save key text])
+                                                            (p/resolved nil))]
+                 (#'sync-crypt/<decrypt-private-key "encrypted-private-key-str"))
+               (p/then (fn [private-key]
+                         (is (= :private-key private-key))
+                         (is (= [["ui-password" :encrypted-private-key]] @decrypt-calls))
+                         (is (= 2 (count @save-calls)))
+                         (is (empty? @fail-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally (fn []
+                            (reset! worker-state/*state old-state)
+                            (done)))))))
+
+(deftest ensure-graph-aes-key-uses-platform-kv-adapters-test
+  (async done
+         (let [fetch-prev js/fetch
+               state-prev @worker-state/*state
+               graph-id (str (random-uuid))
+               expected-key (str "rtc-encrypted-aes-key###" graph-id)
+               platform-map {:runtime :test}
+               current-calls (atom 0)
+               kv-get-calls (atom [])
+               kv-set-calls (atom [])]
+           (reset! worker-state/*state (assoc state-prev :auth/id-token "token"))
+           (set! js/fetch
+                 (fn [url _opts]
+                   (cond
+                     (string/includes? url "/e2ee/user-keys")
+                     (js/Promise.resolve
+                      #js {:ok true
+                           :text (fn []
+                                   (js/Promise.resolve
+                                    "{\"public-key\":\"public-key\",\"encrypted-private-key\":\"encrypted-private-key\"}"))})
+
+                     (string/includes? url (str "/e2ee/graphs/" graph-id "/aes-key"))
+                     (js/Promise.resolve
+                      #js {:ok true
+                           :text (fn []
+                                   (js/Promise.resolve
+                                    "{\"encrypted-aes-key\":\"remote-encrypted\"}"))})
+
+                     :else
+                     (js/Promise.resolve
+                      #js {:ok false
+                           :status 404
+                           :text (fn [] (js/Promise.resolve "{\"message\":\"not-found\"}"))}))))
+           (-> (p/with-redefs [sync-crypt/graph-e2ee? (fn [_repo] true)
+                               sync-crypt/e2ee-base (fn [] "https://example.com")
+                               worker-state/get-id-token (fn [] "token")
+                               worker-util/parse-jwt (fn [_] {:sub "user-1"})
+                               sync-crypt/<decrypt-private-key (fn [_]
+                                                                 (p/resolved :private-key))
+                               crypt/<import-public-key (fn [_]
+                                                          (p/resolved :public-key))
+                               crypt/<decrypt-aes-key (fn [_private-key encrypted]
+                                                        (p/resolved (str "aes:" encrypted)))
+                               ldb/read-transit-str (fn [value] value)
+                               platform/current (fn []
+                                                  (swap! current-calls inc)
+                                                  platform-map)
+                               platform/kv-get (fn [platform' k]
+                                                 (swap! kv-get-calls conj {:platform platform' :key k})
+                                                 (p/resolved nil))
+                               platform/kv-set! (fn [platform' k value]
+                                                  (swap! kv-set-calls conj {:platform platform' :key k :value value})
+                                                  (p/resolved nil))]
+                 (sync-crypt/<ensure-graph-aes-key "repo-1" graph-id))
+               (p/then (fn [aes-key]
+                         (is (= "aes:remote-encrypted" aes-key))
+                         (is (some #(= {:platform platform-map
+                                        :key expected-key}
+                                       %)
+                                   @kv-get-calls))
+                         (is (some #(= {:platform platform-map
+                                        :key expected-key
+                                        :value "remote-encrypted"}
+                                       %)
+                                   @kv-set-calls))
+                         (is (pos? @current-calls))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally (fn []
+                            (set! js/fetch fetch-prev)
+                            (reset! worker-state/*state state-prev)
+                            (done)))))))
+
+(deftest fetch-graph-aes-key-for-download-uses-platform-kv-clear-test
+  (async done
+         (let [fetch-prev js/fetch
+               state-prev @worker-state/*state
+               graph-id (str (random-uuid))
+               expected-key (str "rtc-encrypted-aes-key###" graph-id)
+               platform-map {:runtime :test}
+               kv-set-calls (atom [])]
+           (reset! worker-state/*state (assoc state-prev :auth/id-token "token"))
+           (set! js/fetch
+                 (fn [url _opts]
+                   (cond
+                     (string/includes? url "/e2ee/user-keys")
+                     (js/Promise.resolve
+                      #js {:ok true
+                           :text (fn []
+                                   (js/Promise.resolve
+                                    "{\"public-key\":\"public-key\",\"encrypted-private-key\":\"encrypted-private-key\"}"))})
+
+                     (string/includes? url (str "/e2ee/graphs/" graph-id "/aes-key"))
+                     (js/Promise.resolve
+                      #js {:ok true
+                           :text (fn []
+                                   (js/Promise.resolve
+                                    "{\"encrypted-aes-key\":\"remote-encrypted\"}"))})
+
+                     :else
+                     (js/Promise.resolve
+                      #js {:ok false
+                           :status 404
+                           :text (fn [] (js/Promise.resolve "{\"message\":\"not-found\"}"))}))))
+           (-> (p/with-redefs [sync-crypt/e2ee-base (fn [] "https://example.com")
+                               worker-state/get-id-token (fn [] "token")
+                               worker-util/parse-jwt (fn [_] {:sub "user-1"})
+                               sync-crypt/<decrypt-private-key (fn [_]
+                                                                 (p/resolved :private-key))
+                               crypt/<decrypt-aes-key (fn [_private-key encrypted]
+                                                        (p/resolved (str "aes:" encrypted)))
+                               ldb/read-transit-str (fn [value] value)
+                               platform/current (fn [] platform-map)
+                               platform/kv-get (fn [_platform' _k]
+                                                 (p/resolved nil))
+                               platform/kv-set! (fn [platform' k value]
+                                                  (swap! kv-set-calls conj {:platform platform'
+                                                                            :key k
+                                                                            :value value})
+                                                  (p/resolved nil))]
+                 (sync-crypt/<fetch-graph-aes-key-for-download graph-id))
+               (p/then (fn [aes-key]
+                         (is (= "aes:remote-encrypted" aes-key))
+                         (is (= [{:platform platform-map :key expected-key :value nil}
+                                 {:platform platform-map :key expected-key :value "remote-encrypted"}]
+                                (filterv #(= expected-key (:key %)) @kv-set-calls)))))
+               (p/catch (fn [e]
+                          (is false (str e))))
+               (p/finally (fn []
+                            (set! js/fetch fetch-prev)
+                            (reset! worker-state/*state state-prev)
+                            (done)))))))
+
 ;; bb dev:test -v frontend.worker.sync.crypt-test works, however bb dev:lint-and-test failed
 (deftest decrypt-snapshot-datoms-test
   (async done
diff --git a/src/test/frontend/worker/sync/upload_test.cljs b/src/test/frontend/worker/sync/upload_test.cljs
index f002c37441..7ba86a5af4 100644
--- a/src/test/frontend/worker/sync/upload_test.cljs
+++ b/src/test/frontend/worker/sync/upload_test.cljs
@@ -1,5 +1,6 @@
 (ns frontend.worker.sync.upload-test
   (:require [cljs.test :refer [async deftest is]]
+            [frontend.worker.sync.crypt :as sync-crypt]
             [frontend.worker.sync.upload :as sync-upload]
             [promesa.core :as p]
             [clojure.string :as string]))
@@ -91,3 +92,96 @@
                 :e 3
                 :bytes 1500000}
                (first dropped)))))))
+
+(deftest create-remote-graph-creates-new-remote-graph-when-no-remote-match-test
+  (async done
+         (let [calls* (atom [])]
+           (-> (p/with-redefs [sync-crypt/<preflight-upload-e2ee! (fn [_repo graph-e2ee?]
+                                                                    (swap! calls* conj [:preflight graph-e2ee?])
+                                                                    (p/resolved nil))
+                               sync-upload/list-remote-graphs! (fn []
+                                                                  (swap! calls* conj [:list-remote-graphs])
+                                                                  (p/resolved []))
+                               sync-upload/<create-remote-graph-aux! (fn [repo opts]
+                                                                       (swap! calls* conj [:create-aux repo opts])
+                                                                       (p/resolved {:graph-id "new-graph-id"
+                                                                                    :graph-e2ee? (:graph-e2ee? opts)}))]
+                 (sync-upload/create-remote-graph! "repo-1" {:graph-e2ee? true
+                                                              :graph-ready-for-use? false}))
+               (p/then (fn [identity]
+                         (is (= {:graph-id "new-graph-id" :graph-e2ee? true}
+                                identity))
+                         (is (= [[:list-remote-graphs]
+                                 [:preflight true]
+                                 [:create-aux "repo-1" {:graph-e2ee? true
+                                                        :graph-ready-for-use? false}]]
+                                @calls*))))
+               (p/catch (fn [error]
+                          (is false (str "unexpected error: " error))))
+               (p/finally done)))))
+
+(deftest create-remote-graph-rejects-matching-remote-graph-test
+  (async done
+         (let [create-aux-called? (atom false)]
+           (-> (p/with-redefs [sync-crypt/<preflight-upload-e2ee! (fn [_repo _graph-e2ee?]
+                                                                    (p/resolved nil))
+                               sync-upload/list-remote-graphs! (fn []
+                                                                  (p/resolved [{:graph-name "repo-1"}]))
+                               sync-upload/<create-remote-graph-aux! (fn [_repo _opts]
+                                                                       (reset! create-aux-called? true)
+                                                                       (p/resolved {:graph-id "new-graph-id"}))]
+                 (sync-upload/create-remote-graph! "repo-1" {:graph-e2ee? true
+                                                              :graph-ready-for-use? false}))
+               (p/then (fn [_]
+                         (is false "expected graph-already-exists error")))
+               (p/catch (fn [error]
+                          (is (= "remote graph already exists; delete it before uploading again"
+                                 (ex-message error)))
+                          (is (= :db-sync/graph-already-exists (:code (ex-data error))))
+                          (is (= "repo-1" (:graph-name (ex-data error))))
+                          (is (false? @create-aux-called?))))
+               (p/finally done)))))
+
+(deftest create-remote-graph-missing-e2ee-password-does-not-create-remote-graph-test
+  (async done
+         (let [calls* (atom [])]
+           (-> (p/with-redefs [sync-upload/list-remote-graphs! (fn []
+                                                                  (swap! calls* conj :list-remote-graphs)
+                                                                  (p/resolved []))
+                               sync-crypt/<preflight-upload-e2ee! (fn [_repo _graph-e2ee?]
+                                                                    (swap! calls* conj :preflight)
+                                                                    (p/rejected (ex-info "missing-e2ee-password"
+                                                                                         {:code :db-sync/missing-e2ee-password
+                                                                                          :field :e2ee-password
+                                                                                          :reason :missing-persisted-password
+                                                                                          :hint "Provide --e2ee-password to persist it."})))
+                               sync-upload/<create-remote-graph-aux! (fn [_repo _opts]
+                                                                       (swap! calls* conj :create-remote-graph)
+                                                                       (p/resolved {:graph-id "new-graph-id"}))]
+                 (sync-upload/create-remote-graph! "repo-1" {:graph-e2ee? true
+                                                              :graph-ready-for-use? false}))
+               (p/then (fn [_]
+                         (is false "expected missing e2ee password error")))
+               (p/catch (fn [error]
+                          (is (= "missing-e2ee-password" (ex-message error)))
+                          (is (= :db-sync/missing-e2ee-password (:code (ex-data error))))
+                          (is (= [:list-remote-graphs :preflight] @calls*))))
+               (p/finally done)))))
+
+(deftest create-remote-graph-missing-e2ee-password-does-not-run-create-aux-test
+  (async done
+         (let [create-aux-called? (atom false)]
+           (-> (p/with-redefs [sync-upload/list-remote-graphs! (fn [] (p/resolved []))
+                               sync-crypt/<preflight-upload-e2ee! (fn [_repo _graph-e2ee?]
+                                                                    (p/rejected (ex-info "missing-e2ee-password"
+                                                                                         {:code :db-sync/missing-e2ee-password})))
+                               sync-upload/<create-remote-graph-aux! (fn [_repo _opts]
+                                                                       (reset! create-aux-called? true)
+                                                                       (p/resolved {:graph-id "new-graph-id"}))]
+                 (sync-upload/create-remote-graph! "repo-1" {:graph-e2ee? true
+                                                              :graph-ready-for-use? false}))
+               (p/then (fn [_]
+                         (is false "expected missing e2ee password error")))
+               (p/catch (fn [_error]
+                          (is (false? @create-aux-called?))))
+               (p/finally done)))))
diff --git a/src/test/frontend/worker/worker_common_util_test.cljs b/src/test/frontend/worker/worker_common_util_test.cljs
new file mode 100644
index 0000000000..39027771a8
--- /dev/null
+++ b/src/test/frontend/worker/worker_common_util_test.cljs
@@ -0,0 +1,22 @@
+(ns frontend.worker.worker-common-util-test
+  (:require [cljs.test :refer [deftest is]]
+            [clojure.string :as string]
+            [frontend.worker-common.util :as worker-util]))
+
+(deftest encode-decode-graph-dir-name-roundtrip
+  (let [cases [["Demo" "Demo"]
+               ["foo/bar" "foo~2Fbar"]
+               ["a:b" "a~3Ab"]
+               ["space name" "space name"]
+               ["100% legit" "100~25 legit"]
+               ["til~de" "til~7Ede"]
+               ["A B/C:D%~E" "A B~2FC~3AD~25~7EE"]]]
+    (doseq [[name expected-encoded] cases]
+      (let [encoded (worker-util/encode-graph-dir-name name)]
+        (is (= expected-encoded encoded))
+        (is (= name (worker-util/decode-graph-dir-name encoded)))
+        (is (not (string/includes? encoded "/")))
+        (is (not (string/includes? encoded "\\")))))
+    (is (= "space name" (worker-util/decode-graph-dir-name "space~20name")))
+    (is (= "space name" (worker-util/decode-graph-dir-name "space%20name"))))
+  (is (nil? (worker-util/decode-graph-dir-name nil))))
diff --git a/src/test/logseq/cli/auth_test.cljs b/src/test/logseq/cli/auth_test.cljs
new file mode 100644
index 0000000000..e1003ff1d8
--- /dev/null
+++ b/src/test/logseq/cli/auth_test.cljs
@@ -0,0 +1,205 @@
+(ns logseq.cli.auth-test
+  (:require [cljs.test :refer [async deftest is]]
+            [frontend.test.node-helper :as node-helper]
+            [logseq.cli.auth :as auth]
+            [logseq.cli.test-helper :as test-helper]
+            [promesa.core :as p]
+            ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]))
+
+(defn- sample-auth
+  ([]
+   (sample-auth {}))
+  ([overrides]
+   (merge {:provider "cognito"
+           :id-token "id-token-1"
+           :access-token "access-token-1"
+           :refresh-token "refresh-token-1"
+           :expires-at (+ (js/Date.now) 3600000)
+           :sub "user-123"
+           :email "user@example.com"
+           :updated-at 1735686000000}
+          overrides)))
+
+(defn- read-json-file
+  [path]
+  (-> (fs/readFileSync path)
+      (.toString "utf8")
+      js/JSON.parse
+      (js->clj :keywordize-keys true)))
+
+(defn- call-private
+  [sym & args]
+  (when-let [v (get (ns-interns 'logseq.cli.auth) sym)]
+    (apply @v args)))
+
+(defn- jwt-with-claims
+  [claims]
+  (let [encode (fn [value]
+                 (.toString (js/Buffer.from (js/JSON.stringify (clj->js value)) "utf8")
+                            "base64url"))]
+    (str (encode {:alg "none"
+                  :typ "JWT"})
+         "."
+         (encode claims)
+         ".signature")))
+
+(deftest test-default-auth-path
+  (is (= (node-path/join (.homedir os) "logseq" "auth.json")
+         (auth/default-auth-path))))
+
+(deftest test-write-auth-file-creates-parent-dir
+  (let [dir (node-helper/create-tmp-dir "cli-auth")
+        auth-dir (node-path/join dir "nested" "tokens")
+        auth-path (node-path/join auth-dir "auth.json")
+        payload (sample-auth)]
+    (is (not (fs/existsSync auth-dir)))
+    (auth/write-auth-file! {:auth-path auth-path} payload)
+    (is (fs/existsSync auth-dir))
+    (is (fs/existsSync auth-path))
+    (when (fs/existsSync auth-path)
+      (is (= payload (read-json-file auth-path))))))
+
+(deftest test-read-auth-file-returns-nil-when-missing
+  (let [dir (node-helper/create-tmp-dir "cli-auth")
+        auth-path (node-path/join dir "missing" "auth.json")]
+    (is (nil? (auth/read-auth-file {:auth-path auth-path})))))
+
+(deftest test-delete-auth-file-is-idempotent
+  (let [dir (node-helper/create-tmp-dir "cli-auth")
+        auth-path (node-path/join dir "auth.json")]
+    (auth/delete-auth-file! {:auth-path auth-path})
+    (is (not (fs/existsSync auth-path)))
+    (auth/write-auth-file! {:auth-path auth-path} (sample-auth))
+    (is (fs/existsSync auth-path))
+    (auth/delete-auth-file! {:auth-path auth-path})
+    (is (not (fs/existsSync auth-path)))))
+
+(deftest test-read-auth-file-invalid-json
+  (let [dir (node-helper/create-tmp-dir "cli-auth")
+        auth-path (node-path/join dir "auth.json")]
+    (fs/writeFileSync auth-path "{\"provider\":")
+    (try
+      (auth/read-auth-file {:auth-path auth-path})
+      (is false "expected invalid-auth-file error")
+      (catch :default e
+        (is (= :invalid-auth-file (-> e ex-data :code)))
+        (is (= auth-path (-> e ex-data :auth-path)))))))
+
+(deftest test-resolve-auth-token-refreshes-expired-token
+  (async done
+    (let [dir (node-helper/create-tmp-dir "cli-auth")
+          auth-path (node-path/join dir "auth.json")
+          refresh-calls (atom [])
+          expired-auth (sample-auth {:id-token "expired-id-token"
+                                     :access-token "expired-access-token"
+                                     :expires-at 0})
+          refreshed-auth (sample-auth {:id-token "fresh-id-token"
+                                       :access-token "fresh-access-token"
+                                       :refresh-token "refresh-token-1"
+                                       :expires-at (+ (js/Date.now) 7200000)
+                                       :updated-at 1735689600000})]
+      (auth/write-auth-file! {:auth-path auth-path} expired-auth)
+      (let [result-promise
+            (p/with-redefs [auth/refresh-auth! (fn [opts auth-data]
+                                                 (swap! refresh-calls conj [opts auth-data])
+                                                 (p/resolved refreshed-auth))]
+              (p/let [token (auth/resolve-auth-token! {:auth-path auth-path})
+                      stored (auth/read-auth-file {:auth-path auth-path})]
+                (is (= [[{:auth-path auth-path} expired-auth]] @refresh-calls))
+                (is (= "fresh-id-token" token))
+                (is (= refreshed-auth stored))
+                (when (fs/existsSync auth-path)
+                  (is (= refreshed-auth (read-json-file auth-path))))))]
+        (-> result-promise
+            (p/catch (fn [e]
+                       (is false (str "unexpected error: " e))))
+            (p/finally (fn []
+                         (done))))))))
+
+(deftest test-open-browser-fails-when-spawn-throws
+  (async done
+    (let [child-process (js/require "child_process")]
+      (-> (test-helper/with-js-property-override
+            child-process
+            "spawn"
+            (fn [& _]
+              (throw (js/Error. "spawn failed")))
+            (fn []
+              (-> (auth/open-browser! "https://example.com")
+                  (p/then (fn [_]
+                            (is false "expected browser spawn failure")))
+                  (p/catch (fn [e]
+                             (is (= :browser-open-failed (-> e ex-data :code))))))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn []
+                       (done)))))))
+
+(deftest test-open-browser-uses-cmd-start-on-windows
+  (let [open-command (fn [platform url]
+                       (call-private 'browser-open-command platform url))
+        [command args] (open-command "win32"
+                                     "https://example.com/oauth2/authorize?response_type=code&client_id=abc&redirect_uri=http%3A%2F%2Flocalhost%3A8765%2Fauth%2Fcallback")]
+    (is (= "cmd.exe" command))
+    (is (= ["/d" "/c"
+            "start \"\" \"https://example.com/oauth2/authorize?response_type=code&client_id=abc&redirect_uri=http%3A%2F%2Flocalhost%3A8765%2Fauth%2Fcallback\""]
+           args))))
+
+(deftest test-open-browser-normalizes-prequoted-windows-url
+  (let [open-command (fn [platform url]
+                       (call-private 'browser-open-command platform url))
+        [command args] (open-command "win32"
+                                     "\"https://example.com/oauth2/authorize?response_type=code&client_id=abc&redirect_uri=http%3A%2F%2Flocalhost%3A8765%2Fauth%2Fcallback\"")]
+    (is (= "cmd.exe" command))
+    (is (= ["/d" "/c"
+            "start \"\" \"https://example.com/oauth2/authorize?response_type=code&client_id=abc&redirect_uri=http%3A%2F%2Flocalhost%3A8765%2Fauth%2Fcallback\""]
+           args))))
+
+(deftest test-open-browser-uses-verbatim-windows-cmd-arguments
+  (let [spawn-options (fn [platform]
+                        (call-private 'browser-open-spawn-options platform))]
+    (is (= {:detached true
+            :stdio "ignore"
+            :shell false
+            :windowsVerbatimArguments true}
+           (spawn-options "win32")))
+    (is (= {:detached true
+            :stdio "ignore"
+            :shell false}
+           (spawn-options "linux")))))
+
+(deftest test-parse-jwt-fails-fast-on-invalid-token
+  (let [parse-jwt (fn [jwt]
+                    (call-private 'parse-jwt jwt))]
+    (is (= {:sub "user-123"
+            :email "user@example.com"
+            :exp 1735689600}
+           (parse-jwt (jwt-with-claims {:sub "user-123"
+                                        :email "user@example.com"
+                                        :exp 1735689600}))))
+    (try
+      (parse-jwt "not-a-jwt")
+      (is false "expected invalid token to throw")
+      (catch :default e
+        (is (= :invalid-auth-token (-> e ex-data :code)))
+        (is (= "not-a-jwt" (-> e ex-data :token)))))))
+
+(deftest test-refresh-auth-fails-when-token-response-misses-id-token
+  (async done
+    (-> (p/with-redefs [auth/oauth-token-request! (fn [_params]
+                                                    (p/resolved {:access_token "access-token-only"
+                                                                 :refresh_token "refresh-token-1"}))]
+          (-> (auth/refresh-auth! {:auth-path "/tmp/auth.json"}
+                                  (sample-auth {:refresh-token "refresh-token-1"}))
+              (p/then (fn [_]
+                        (is false "expected refresh-auth! to reject when id_token is missing")))
+              (p/catch (fn [e]
+                         (is (= :auth-refresh-failed (-> e ex-data :code)))
+                         (is (= :missing-id-token
+                                (get-in (ex-data e) [:context :code])))))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))))
+        (p/finally (fn []
+                     (done))))))
diff --git a/src/test/logseq/cli/command/add_test.cljs b/src/test/logseq/cli/command/add_test.cljs
new file mode 100644
index 0000000000..af53b204d3
--- /dev/null
+++ b/src/test/logseq/cli/command/add_test.cljs
@@ -0,0 +1,304 @@
+(ns logseq.cli.command.add-test
+  (:require [cljs-time.coerce :as tc]
+            [cljs-time.core :as t]
+            [cljs.test :refer [async deftest is testing]]
+            [clojure.string :as string]
+            [logseq.cli.command.add :as add-command]
+            [logseq.common.util.date-time :as date-time-util]
+            [logseq.cli.transport :as transport]
+            [promesa.core :as p]))
+
+(deftest test-today-page-title-uses-default-time-zone
+  (async done
+    (let [formatted-args* (atom nil)]
+      (-> (p/with-redefs [transport/invoke (fn [_ method _ _args]
+                                             (if (= method :thread-api/pull)
+                                               (p/resolved {:logseq.property.journal/title-format "yyyy-MM-dd"})
+                                               (p/rejected (ex-info "unexpected method" {:method method}))))
+                          tc/from-date (fn [_] :utc-now)
+                          t/to-default-time-zone (fn [date-time]
+                                                   (if (= date-time :utc-now)
+                                                     :local-now
+                                                     :unexpected-time))
+                          date-time-util/format (fn [date-time formatter]
+                                                  (reset! formatted-args* [date-time formatter])
+                                                  "2026-05-01")]
+            (p/let [title (#'add-command/today-page-title {} "demo")]
+              (is (= "2026-05-01" title))
+              (is (= [:local-now "yyyy-MM-dd"] @formatted-args*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-collect-created-block-uuids
+  (testing "collects uuids depth-first and removes duplicates"
+    (let [root-uuid (random-uuid)
+          child-uuid (random-uuid)
+          grandchild-uuid (random-uuid)
+          sibling-uuid (random-uuid)
+          blocks [{:block/uuid root-uuid
+                   :block/children [{:block/uuid child-uuid}
+                                    {:block/title "without uuid"
+                                     :block/children [{:block/uuid grandchild-uuid}]}]}
+                  {:block/uuid sibling-uuid}
+                  {:block/uuid child-uuid}]]
+      (is (= [root-uuid child-uuid grandchild-uuid sibling-uuid]
+             (#'add-command/collect-created-block-uuids blocks))))))
+
+(deftest test-created-ids-in-order
+  (testing "normalizes created ids in deterministic uuid order"
+    (let [uuid-a (random-uuid)
+          uuid-b (random-uuid)
+          uuid-c (random-uuid)
+          ordered-uuids [uuid-c uuid-a uuid-b]
+          entities [{:block/uuid uuid-a :db/id 101}
+                    {:block/uuid uuid-b :db/id 202}
+                    {:block/uuid uuid-c :db/id 303}]]
+      (is (= [303 101 202]
+             (#'add-command/created-ids-in-order ordered-uuids entities :block))))))
+
+(deftest test-created-ids-in-order-errors-on-missing-entity
+  (testing "throws when any created uuid cannot be resolved to db/id"
+    (let [uuid-a (random-uuid)
+          uuid-b (random-uuid)
+          error (try
+                  (#'add-command/created-ids-in-order
+                   [uuid-a uuid-b]
+                   [{:block/uuid uuid-a :db/id 11}]
+                   :block)
+                  nil
+                  (catch :default e e))]
+      (is (some? error))
+      (is (= :add-id-resolution-failed (-> error ex-data :code)))
+      (is (= [uuid-b] (-> error ex-data :missing-uuids))))))
+
+(deftest test-partition-ref-values
+  (testing "partitions uuid, integer id, and page-name refs"
+    (let [result (#'add-command/partition-ref-values
+                  ["some page"
+                   "550e8400-e29b-41d4-a716-446655440000"
+                   "101"
+                   " 42 "
+                   "another page"
+                   ""
+                   "  "])]
+      (is (= ["550e8400-e29b-41d4-a716-446655440000"] (:uuid-refs result)))
+      (is (= ["101" "42"] (:id-refs result)))
+      (is (= ["some page" "another page"] (:page-refs result)))))
+
+  (testing "negative integers are recognized as id refs"
+    (let [result (#'add-command/partition-ref-values ["-5"])]
+      (is (= ["-5"] (:id-refs result)))
+      (is (empty? (:page-refs result)))))
+
+  (testing "non-integer numbers stay as page refs"
+    (let [result (#'add-command/partition-ref-values ["3.14" "1e5"])]
+      (is (empty? (:id-refs result)))
+      (is (= ["3.14" "1e5"] (:page-refs result))))))
+
+(def ^:private mock-transport-invoke
+  (fn [_ method _ args]
+    (case method
+      ;; pull-tag-by-name uses :thread-api/q
+      :thread-api/q
+      (let [[_ [_ name-arg]] args]
+        (p/resolved
+         (cond
+           (= name-arg "realtag")
+           [{:db/id 99 :block/name "realtag" :block/title "RealTag"
+             :block/tags [{:db/ident :logseq.class/Tag}]}]
+           :else [])))
+
+      ;; pull-entity uses :thread-api/pull
+      :thread-api/pull
+      (let [[_ _ lookup] args]
+        (p/resolved
+         (cond
+           (= lookup [:block/name "plainpage"])
+           {:db/id 42 :block/name "plainpage" :block/title "PlainPage"
+            :block/tags [{:db/ident :logseq.class/Page}]}
+
+           (= lookup [:block/name "realtag"])
+           {:db/id 99 :block/name "realtag" :block/title "RealTag"
+            :block/tags [{:db/ident :logseq.class/Tag}]}
+
+           :else {})))
+
+      (p/rejected (ex-info "unexpected method" {:method method :args args})))))
+
+(deftest test-resolve-id-ref-entities
+  (testing "resolves integer id refs to uuid+title maps"
+    (async done
+           (let [page-uuid (random-uuid)
+                 mock-invoke (fn [_ _ _ args]
+                               (let [[_ _ lookup] args]
+                                 (p/resolved
+                                  (cond
+                                    (= lookup 101)
+                                    {:db/id 101 :block/uuid page-uuid :block/title "My Page"}
+                                    :else {}))))]
+             (-> (p/with-redefs [transport/invoke mock-invoke]
+                   (p/let [result (#'add-command/resolve-id-ref-entities {} "demo" ["101"])]
+                     (is (= 1 (count result)))
+                     (is (= page-uuid (:block/uuid (first result))))
+                     (is (= "101" (:block/title (first result)))
+                         "title is the original id string for title-ref->id-ref replacement")))
+                 (p/catch (fn [e] (is false (str "unexpected error: " e))))
+                 (p/finally done))))))
+
+(deftest test-resolve-tags-accepts-valid-tag
+  (async done
+         (-> (p/with-redefs [transport/invoke mock-transport-invoke]
+               (p/let [result (add-command/resolve-tags {} "demo" ["RealTag"])]
+                 (is (= [99] (mapv :db/id result)))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-resolve-tags-rejects-non-tag-page
+  (async done
+         (-> (p/with-redefs [transport/invoke mock-transport-invoke]
+               (-> (add-command/resolve-tags {} "demo" ["PlainPage"])
+                   (p/then (fn [_] (is false "expected error for non-tag page")))
+                   (p/catch (fn [e]
+                              ;; String lookup uses pull-tag-by-name which only finds tags,
+                              ;; so a non-tag page results in :tag-not-found
+                              (is (= :tag-not-found (-> e ex-data :code)))
+                              (is (string/includes? (ex-message e) "PlainPage"))))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-resolve-tags-rejects-missing-tag
+  (async done
+         (-> (p/with-redefs [transport/invoke mock-transport-invoke]
+               (-> (add-command/resolve-tags {} "demo" ["NoSuchTag"])
+                   (p/then (fn [_] (is false "expected error for missing tag")))
+                   (p/catch (fn [e]
+                              (is (= :tag-not-found (-> e ex-data :code)))
+                              (is (string/includes? (ex-message e) "NoSuchTag"))))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-coerce-default-property-rejects-non-string
+  (testing "default property type rejects number value"
+    (let [property {:schema {:type :default :cardinality :one}}
+          result (#'add-command/coerce-property-value-basic property 4)]
+      (is (not (:ok? result)))
+      (is (= "default property expects a string value or keyword" (:message result)))))
+
+  (testing "default property type accepts string value"
+    (let [property {:schema {:type :default :cardinality :one}}
+          result (#'add-command/coerce-property-value-basic property "hello")]
+      (is (:ok? result))
+      (is (= "hello" (:value result)))))
+
+  (testing "default property type rejects boolean value"
+    (let [property {:schema {:type :default :cardinality :one}}
+          result (#'add-command/coerce-property-value-basic property true)]
+      (is (not (:ok? result))))))
+
+(deftest test-resolve-date-page-id-rejects-invalid-date
+  (async done
+         (let [mock-invoke (fn [_ _ _ args]
+                             (let [[_ _ lookup] args]
+                               (p/resolved
+                                (if (= lookup :logseq.class/Journal)
+                                  {}
+                                  {}))))]
+           (-> (p/with-redefs [transport/invoke mock-invoke]
+                 (-> (#'add-command/resolve-date-page-id {} "demo" "not a date")
+                     (p/then (fn [_] (is false "expected error for invalid date")))
+                     (p/catch (fn [e]
+                                (is (= :invalid-date (-> e ex-data :code)))
+                                (is (string/includes? (ex-message e) "not a date"))))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(def ^:private selector-tag-uuid (uuid "11111111-1111-1111-1111-111111111111"))
+(def ^:private selector-property-uuid (uuid "22222222-2222-2222-2222-222222222222"))
+
+(def ^:private selector-tag-entity
+  {:db/id 701
+   :block/name "projecttag"
+   :block/title "ProjectTag"
+   :block/uuid selector-tag-uuid
+   :block/tags [{:db/ident :logseq.class/Tag}]
+   :logseq.property/public? true
+   :logseq.property/built-in? false})
+
+(def ^:private selector-property-entity
+  {:db/id 801
+   :db/ident :demo/custom-priority
+   :block/name "custompriority"
+   :block/title "CustomPriority"
+   :block/uuid selector-property-uuid
+   :logseq.property/type :default
+   :db/cardinality :db.cardinality/one
+   :logseq.property/public? true})
+
+(def ^:private selector-mock-transport-invoke
+  (fn [_ method _ args]
+    (case method
+      :thread-api/q
+      (let [[_ [_ name-arg]] args]
+        (p/resolved
+         (cond
+           (= name-arg "projecttag") [selector-tag-entity]
+           (= name-arg "custompriority") [selector-property-entity]
+           :else [])))
+
+      :thread-api/pull
+      (let [[_ _ lookup] args]
+        (p/resolved
+         (cond
+           (or (= lookup 701)
+               (= lookup [:db/ident :demo/project-tag])
+               (= lookup [:block/uuid selector-tag-uuid]))
+           selector-tag-entity
+
+           (or (= lookup 801)
+               (= lookup [:db/ident :demo/custom-priority])
+               (= lookup [:block/uuid selector-property-uuid]))
+           selector-property-entity
+
+           :else {})))
+
+      (p/rejected (ex-info "unexpected method" {:method method :args args})))))
+
+(deftest test-resolve-tags-supports-id-uuid-ident-and-name-selectors
+  (async done
+         (-> (p/with-redefs [transport/invoke selector-mock-transport-invoke]
+               (p/let [result (add-command/resolve-tags
+                               {}
+                               "demo"
+                               [701
+                                selector-tag-uuid
+                                (str selector-tag-uuid)
+                                :demo/project-tag
+                                "ProjectTag"])]
+                 (is (= [701 701 701 701 701]
+                        (mapv :db/id result)))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-resolve-property-identifiers-supports-id-uuid-ident-and-name-selectors
+  (async done
+         (-> (p/with-redefs [transport/invoke selector-mock-transport-invoke]
+               (p/let [result (add-command/resolve-property-identifiers
+                               {}
+                               "demo"
+                               [801
+                                selector-property-uuid
+                                (str selector-property-uuid)
+                                :demo/custom-priority
+                                "CustomPriority"]
+                               {:allow-non-built-in? true})]
+                 (is (= [:demo/custom-priority
+                         :demo/custom-priority
+                         :demo/custom-priority
+                         :demo/custom-priority
+                         :demo/custom-priority]
+                        result))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
diff --git a/src/test/logseq/cli/command/auth_test.cljs b/src/test/logseq/cli/command/auth_test.cljs
new file mode 100644
index 0000000000..62b928d2e9
--- /dev/null
+++ b/src/test/logseq/cli/command/auth_test.cljs
@@ -0,0 +1,242 @@
+(ns logseq.cli.command.auth-test
+  (:require [cljs.test :refer [async deftest is]]
+            [frontend.test.node-helper :as node-helper]
+            [logseq.cli.auth :as cli-auth]
+            [logseq.cli.command.auth :as auth-command]
+            [logseq.common.cognito-config :as cognito-config]
+            [promesa.core :as p]
+            ["fs" :as fs]
+            ["path" :as node-path]))
+
+(defn- sample-auth
+  ([]
+   (sample-auth {}))
+  ([overrides]
+   (merge {:provider "cognito"
+           :id-token "id-token-1"
+           :access-token "access-token-1"
+           :refresh-token "refresh-token-1"
+           :expires-at (+ (js/Date.now) 3600000)
+           :sub "user-123"
+           :email "user@example.com"
+           :updated-at 1735686000000}
+          overrides)))
+
+(deftest test-login-opens-browser-with-authorize-url-and-persists-auth
+  (async done
+    (let [dir (node-helper/create-tmp-dir "cli-auth")
+          auth-path (node-path/join dir "auth.json")
+          open-calls (atom [])
+          exchange-calls (atom [])
+          write-calls (atom [])
+          auth-data (sample-auth)
+          callback-server {:port 8765
+                           :redirect-uri "http://localhost:8765/auth/callback"
+                           :wait! (fn [] (p/resolved {:code "oauth-code"}))
+                           :stop! (fn [] (p/resolved true))}]
+      (-> (p/with-redefs [cognito-config/CLI-COGNITO-CLIENT-ID "69cs1lgme7p8kbgld8n5kseii6"
+                          cli-auth/start-login-callback-server! (fn [_opts]
+                                                                  (p/resolved callback-server))
+                          cli-auth/open-browser! (fn [url]
+                                                   (swap! open-calls conj url)
+                                                   (p/resolved {:opened? true}))
+                          cli-auth/exchange-code-for-auth! (fn [opts payload]
+                                                             (swap! exchange-calls conj [opts payload])
+                                                             (p/resolved auth-data))
+                          cli-auth/write-auth-file! (fn [opts payload]
+                                                      (swap! write-calls conj [opts payload])
+                                                      payload)]
+            (p/let [result (cli-auth/login! {:auth-path auth-path})
+                    authorize-url (first @open-calls)]
+              (is (= 1 (count @open-calls)))
+              (is (string? authorize-url))
+              (is (re-find #"/oauth2/authorize" authorize-url))
+              (is (re-find #"response_type=code" authorize-url))
+              (is (re-find #"client_id=69cs1lgme7p8kbgld8n5kseii6" authorize-url))
+              (is (re-find #"redirect_uri=http%3A%2F%2Flocalhost%3A8765%2Fauth%2Fcallback" authorize-url))
+              (is (re-find #"state=" authorize-url))
+              (is (re-find #"code_challenge=" authorize-url))
+              (is (= 1 (count @exchange-calls)))
+              (let [[exchange-opts exchange-payload] (first @exchange-calls)]
+                (is (= {:auth-path auth-path} exchange-opts))
+                (is (= "oauth-code" (:code exchange-payload)))
+                (is (= "http://localhost:8765/auth/callback" (:redirect-uri exchange-payload)))
+                (is (string? (:code-verifier exchange-payload))))
+              (is (= [[{:auth-path auth-path} auth-data]] @write-calls))
+              (is (= auth-path (:auth-path result)))
+              (is (= "user@example.com" (:email result)))
+              (is (= "user-123" (:sub result)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest test-login-validates-state-before-code-exchange
+  (async done
+    (let [exchange-calls (atom [])]
+      (-> (p/with-redefs [cli-auth/open-browser! (fn [authorize-url]
+                                                   (let [parsed (js/URL. authorize-url)
+                                                         redirect-uri (.get (.-searchParams parsed) "redirect_uri")]
+                                                     (-> (js/fetch (str redirect-uri "?code=oauth-code&state=wrong-state"))
+                                                         (p/then (fn [_]
+                                                                   {:opened? true})))) )
+                          cli-auth/exchange-code-for-auth! (fn [opts payload]
+                                                             (swap! exchange-calls conj [opts payload])
+                                                             (p/resolved (sample-auth)))]
+            (-> (cli-auth/login! {:timeout-ms 200})
+                (p/then (fn [_]
+                          (is false "expected invalid callback state error")))
+                (p/catch (fn [e]
+                           (is (= :invalid-callback-state (-> e ex-data :code)))
+                           (is (= [] @exchange-calls))))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest test-login-timeout-when-no-browser-callback-arrives
+  (async done
+    (let [exchange-calls (atom [])]
+      (-> (p/with-redefs [cli-auth/open-browser! (fn [_authorize-url]
+                                                   (p/resolved {:opened? false}))
+                          cli-auth/exchange-code-for-auth! (fn [opts payload]
+                                                             (swap! exchange-calls conj [opts payload])
+                                                             (p/resolved (sample-auth)))]
+            (-> (cli-auth/login! {:login-timeout-ms 10})
+                (p/then (fn [_]
+                          (is false "expected login timeout error")))
+                (p/catch (fn [e]
+                           (is (= :login-timeout (-> e ex-data :code)))
+                           (is (= [] @exchange-calls))))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest test-login-ignores-global-request-timeout-for-callback-wait
+  (async done
+    (let [exchange-calls (atom [])]
+      (-> (p/with-redefs [cli-auth/open-browser! (fn [_authorize-url]
+                                                   (p/resolved {:opened? false}))
+                          cli-auth/exchange-code-for-auth! (fn [opts payload]
+                                                             (swap! exchange-calls conj [opts payload])
+                                                             (p/resolved (sample-auth)))]
+            (-> (cli-auth/login! {:timeout-ms 10
+                                  :login-timeout-ms 200})
+                (p/then (fn [_]
+                          (is false "expected login timeout error")))
+                (p/catch (fn [e]
+                           (is (= :login-timeout (-> e ex-data :code)))
+                           (is (= [] @exchange-calls))))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest test-logout-removes-auth-file-and-completes-cognito-logout-when-file-existed
+  (async done
+    (let [dir (node-helper/create-tmp-dir "cli-auth")
+          auth-path (node-path/join dir "auth.json")
+          open-calls (atom [])]
+      (cli-auth/write-auth-file! {:auth-path auth-path} (sample-auth))
+      (is (fs/existsSync auth-path))
+      (-> (p/with-redefs [cognito-config/CLI-COGNITO-CLIENT-ID "69cs1lgme7p8kbgld8n5kseii6"
+                          cli-auth/open-browser! (fn [url]
+                                                   (swap! open-calls conj url)
+                                                   (let [parsed (js/URL. url)
+                                                         logout-uri (.get (.-searchParams parsed) "logout_uri")]
+                                                     (-> (js/fetch logout-uri)
+                                                         (p/then (fn [_]
+                                                                   {:opened? true})))))]
+            (p/let [result (cli-auth/logout! {:auth-path auth-path})
+                    logout-url (first @open-calls)]
+              (is (= 1 (count @open-calls)))
+              (is (= auth-path (:auth-path result)))
+              (is (true? (:deleted? result)))
+              (is (true? (:opened? result)))
+              (is (true? (:logout-completed? result)))
+              (is (not (fs/existsSync auth-path)))
+              (is (string? logout-url))
+              (when (string? logout-url)
+                (is (re-find #"/logout\?" logout-url))
+                (is (re-find #"client_id=69cs1lgme7p8kbgld8n5kseii6" logout-url))
+                (is (re-find #"logout_uri=http%3A%2F%2Flocalhost%3A8765%2Flogout-complete" logout-url)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest test-logout-completes-cognito-logout-when-auth-file-is-already-absent
+  (async done
+    (let [dir (node-helper/create-tmp-dir "cli-auth")
+          auth-path (node-path/join dir "auth.json")
+          open-calls (atom [])]
+      (-> (p/with-redefs [cognito-config/CLI-COGNITO-CLIENT-ID "69cs1lgme7p8kbgld8n5kseii6"
+                          cli-auth/open-browser! (fn [url]
+                                                   (swap! open-calls conj url)
+                                                   (let [parsed (js/URL. url)
+                                                         logout-uri (.get (.-searchParams parsed) "logout_uri")]
+                                                     (-> (js/fetch logout-uri)
+                                                         (p/then (fn [_]
+                                                                   {:opened? true})))))]
+            (p/let [result (cli-auth/logout! {:auth-path auth-path})
+                    logout-url (first @open-calls)]
+              (is (= 1 (count @open-calls)))
+              (is (= auth-path (:auth-path result)))
+              (is (false? (:deleted? result)))
+              (is (true? (:opened? result)))
+              (is (true? (:logout-completed? result)))
+              (is (not (fs/existsSync auth-path)))
+              (is (string? logout-url))
+              (when (string? logout-url)
+                (is (re-find #"logout_uri=http%3A%2F%2Flocalhost%3A8765%2Flogout-complete" logout-url)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest test-logout-fails-when-browser-cannot-open
+  (async done
+    (let [dir (node-helper/create-tmp-dir "cli-auth")
+          auth-path (node-path/join dir "auth.json")]
+      (-> (p/with-redefs [cli-auth/open-browser! (fn [_url]
+                                                   (p/resolved {:opened? false}))]
+            (-> (cli-auth/logout! {:auth-path auth-path})
+                (p/then (fn [_]
+                          (is false "expected logout browser-open failure")))
+                (p/catch (fn [e]
+                           (is (= :logout-browser-open-failed (-> e ex-data :code)))))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest test-command-execute-login-and-logout
+  (async done
+    (let [login-calls (atom [])
+          logout-calls (atom [])]
+      (-> (p/with-redefs [cli-auth/login! (fn [config]
+                                            (swap! login-calls conj config)
+                                            (p/resolved {:auth-path "/tmp/auth.json"
+                                                         :email "user@example.com"
+                                                         :sub "user-123"}))
+                          cli-auth/logout! (fn [config]
+                                             (swap! logout-calls conj config)
+                                             {:auth-path "/tmp/auth.json"
+                                              :deleted? true})]
+            (p/let [login-result (auth-command/execute {:type :login} {:auth-path "/tmp/auth.json"})
+                    logout-result (auth-command/execute {:type :logout} {:auth-path "/tmp/auth.json"})]
+              (is (= [{:auth-path "/tmp/auth.json"}] @login-calls))
+              (is (= [{:auth-path "/tmp/auth.json"}] @logout-calls))
+              (is (= :ok (:status login-result)))
+              (is (= "user@example.com" (get-in login-result [:data :email])))
+              (is (= :ok (:status logout-result)))
+              (is (true? (get-in logout-result [:data :deleted?])))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally (fn [] (done)))))))
+
+(deftest test-auth-execute-does-not-infer-code-from-error-message
+  (async done
+    (-> (p/with-redefs [cli-auth/login! (fn [_]
+                                          (p/rejected (ex-info "missing-auth" {})))]
+          (p/let [result (auth-command/execute {:type :login} {:auth-path "/tmp/auth.json"})]
+            (is (= :error (:status result)))
+            (is (= :exception (get-in result [:error :code])))
+            (is (= "missing-auth" (get-in result [:error :message])))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))))
+        (p/finally (fn [] (done))))))
diff --git a/src/test/logseq/cli/command/completion_test.cljs b/src/test/logseq/cli/command/completion_test.cljs
new file mode 100644
index 0000000000..a7a213c076
--- /dev/null
+++ b/src/test/logseq/cli/command/completion_test.cljs
@@ -0,0 +1,61 @@
+(ns logseq.cli.command.completion-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [clojure.string :as string]
+            [logseq.cli.command.completion :as completion-command]
+            [logseq.cli.commands :as commands]))
+
+(deftest test-completion-command-registration
+  (testing "completion entry has correct structure"
+    (let [entry (first completion-command/entries)]
+      (is (= ["completion"] (:cmds entry)))
+      (is (= :completion (:command entry)))
+      (is (= #{"zsh" "bash"} (get-in entry [:spec :shell :validate])))))
+  (testing "completion entry has long-desc with setup instructions"
+    (let [entry (first completion-command/entries)]
+      (is (some? (:long-desc entry)))
+      (is (string/includes? (:long-desc entry) "autoload -Uz compinit"))
+      (is (string/includes? (:long-desc entry) "eval \"$(logseq completion zsh)\""))))
+  (testing "completion entry has examples metadata"
+    (let [entry (first completion-command/entries)]
+      (is (= ["logseq completion zsh"
+              "logseq completion bash"]
+             (:examples entry))))))
+
+(deftest test-parse-args-completion-shell
+  (testing "parse-args recognizes completion --shell zsh"
+    (let [result (commands/parse-args ["completion" "--shell" "zsh"])]
+      (is (true? (:ok? result)))
+      (is (= :completion (:command result)))))
+  (testing "parse-args recognizes completion with positional arg"
+    (let [result (commands/parse-args ["completion" "zsh"])]
+      (is (true? (:ok? result)))
+      (is (= :completion (:command result))))))
+
+(deftest test-build-action-completion
+  (testing "build-action for :completion returns correct action"
+    (let [parsed {:ok? true
+                  :command :completion
+                  :options {:shell "zsh"}
+                  :args []}
+          action (commands/build-action parsed {})]
+      (is (true? (:ok? action)))
+      (is (= :completion (get-in action [:action :type])))
+      (is (= "zsh" (get-in action [:action :shell])))))
+  (testing "build-action with positional arg"
+    (let [parsed {:ok? true
+                  :command :completion
+                  :options {}
+                  :args ["bash"]}
+          action (commands/build-action parsed {})]
+      (is (true? (:ok? action)))
+      (is (= "bash" (get-in action [:action :shell]))))))
+
+(deftest test-parse-args-completion-validation
+  (testing "completion with no shell arg returns invalid-options error"
+    (let [result (commands/parse-args ["completion"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+  (testing "completion with unsupported shell returns invalid-options error"
+    (let [result (commands/parse-args ["completion" "fish"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code]))))))
diff --git a/src/test/logseq/cli/command/debug_test.cljs b/src/test/logseq/cli/command/debug_test.cljs
new file mode 100644
index 0000000000..6631b7a4ab
--- /dev/null
+++ b/src/test/logseq/cli/command/debug_test.cljs
@@ -0,0 +1,82 @@
+(ns logseq.cli.command.debug-test
+  (:require [cljs.test :refer [async deftest is testing]]
+            [logseq.cli.command.debug :as debug-command]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [promesa.core :as p]))
+
+(deftest test-build-action
+  (testing "builds action from --id selector"
+    (let [result (debug-command/build-action {:id 42} "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= :debug-pull (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))
+      (is (= 42 (get-in result [:action :lookup])))
+      (is (= '[*] (get-in result [:action :selector])))))
+
+  (testing "builds action from --uuid selector"
+    (let [result (debug-command/build-action {:uuid "11111111-1111-1111-1111-111111111111"}
+                                             "logseq_db_demo")
+          lookup (get-in result [:action :lookup])]
+      (is (true? (:ok? result)))
+      (is (= :block/uuid (first lookup)))
+      (is (uuid? (second lookup)))
+      (is (= "11111111-1111-1111-1111-111111111111" (str (second lookup))))))
+
+  (testing "builds action from --ident selector"
+    (let [result (debug-command/build-action {:ident ":logseq.class/Tag"}
+                                             "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= [:db/ident :logseq.class/Tag]
+             (get-in result [:action :lookup])))))
+
+  (testing "rejects invalid ident"
+    (let [result (debug-command/build-action {:ident "logseq.class/Tag"}
+                                             "logseq_db_demo")]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "requires repo"
+    (let [result (debug-command/build-action {:id 1} nil)]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code]))))))
+
+(deftest test-execute-debug-pull-success
+  (async done
+         (let [invoke-calls* (atom [])
+               action {:type :debug-pull
+                       :repo "logseq_db_demo"
+                       :lookup 42
+                       :selector '[*]}]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo] config)
+                               transport/invoke (fn [_ method _ args]
+                                                  (swap! invoke-calls* conj {:method method :args args})
+                                                  (p/resolved {:db/id 42 :block/title "Debug Home"}))]
+                 (p/let [result (debug-command/execute-debug-pull action {:base-url "http://example"})]
+                   (is (= :ok (:status result)))
+                   (is (= {:db/id 42 :block/title "Debug Home"}
+                          (get-in result [:data :entity])))
+                   (is (= 42 (get-in result [:data :lookup])))
+                   (is (= '[*] (get-in result [:data :selector])))
+                   (is (= [{:method :thread-api/pull
+                            :args ["logseq_db_demo" '[*] 42]}]
+                          @invoke-calls*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-debug-pull-entity-not-found
+  (async done
+         (let [action {:type :debug-pull
+                       :repo "logseq_db_demo"
+                       :lookup [:db/ident :missing/ident]
+                       :selector '[*]}]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo] config)
+                               transport/invoke (fn [_ _method _ _args]
+                                                  (p/resolved nil))]
+                 (p/let [result (debug-command/execute-debug-pull action {:base-url "http://example"})]
+                   (is (= :error (:status result)))
+                   (is (= :entity-not-found (get-in result [:error :code])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
diff --git a/src/test/logseq/cli/command/doctor_test.cljs b/src/test/logseq/cli/command/doctor_test.cljs
new file mode 100644
index 0000000000..386db0f187
--- /dev/null
+++ b/src/test/logseq/cli/command/doctor_test.cljs
@@ -0,0 +1,205 @@
+(ns logseq.cli.command.doctor-test
+  (:require [cljs.test :refer [async deftest is]]
+            [clojure.string :as string]
+            [logseq.cli.commands :as commands]
+            [logseq.cli.root-dir :as root-dir]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.version :as cli-version]
+            [promesa.core :as p]
+            [logseq.cli.command.doctor :as doctor-command]))
+
+(deftest test-execute-doctor-script-missing
+  (async done
+    (let [ensure-root-dir-called? (atom false)
+          list-servers-called? (atom false)]
+      (-> (p/with-redefs [root-dir/ensure-root-dir! (fn [_]
+                                                      (reset! ensure-root-dir-called? true)
+                                                      "/tmp/logseq-doctor")
+                          cli-server/list-servers (fn [_]
+                                                    (reset! list-servers-called? true)
+                                                    (p/resolved []))]
+            (p/let [result (commands/execute {:type :doctor
+                                              :script-path "/tmp/logseq-cli-missing-db-worker-node.js"}
+                                             {})]
+              (is (= :error (:status result)))
+              (is (= :doctor-script-missing (get-in result [:error :code])))
+              (is (= :db-worker-script
+                     (get-in result [:error :checks 0 :id])))
+              (is (= :error
+                     (get-in result [:error :checks 0 :status])))
+              (is (false? @ensure-root-dir-called?))
+              (is (false? @list-servers-called?))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-doctor-root-dir-permission
+  (async done
+    (let [list-servers-called? (atom false)]
+      (-> (p/with-redefs [root-dir/ensure-root-dir! (fn [_]
+                                                      (throw (ex-info "root-dir is not readable/writable: /tmp/nope"
+                                                                      {:code :root-dir-permission
+                                                                       :path "/tmp/nope"
+                                                                       :cause "EACCES"})))
+                          cli-server/list-servers (fn [_]
+                                                    (reset! list-servers-called? true)
+                                                    (p/resolved []))]
+            (p/let [result (commands/execute {:type :doctor
+                                              :script-path "src/main/logseq/cli/commands.cljs"}
+                                             {:root-dir "/tmp/nope"})]
+              (is (= :error (:status result)))
+              (is (= :root-dir-permission (get-in result [:error :code])))
+              (is (= [:db-worker-script :root-dir]
+                     (mapv :id (get-in result [:error :checks]))))
+              (is (= [:ok :error]
+                     (mapv :status (get-in result [:error :checks]))))
+              (is (false? @list-servers-called?))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-doctor-all-checks-pass
+  (async done
+    (-> (p/with-redefs [root-dir/ensure-root-dir! (fn [_] "/tmp/logseq-doctor")
+                        cli-version/revision (fn [] "cli-rev")
+                        cli-server/list-servers (fn [_] (p/resolved []))]
+          (p/let [result (commands/execute {:type :doctor
+                                            :script-path "src/main/logseq/cli/commands.cljs"}
+                                           {:root-dir "/tmp/logseq-doctor"})]
+            (is (= :ok (:status result)))
+            (is (= :ok (get-in result [:data :status])))
+            (is (= [:db-worker-script :root-dir :running-servers :server-revision-mismatch]
+                   (mapv :id (get-in result [:data :checks]))))
+            (is (= [:ok :ok :ok :ok]
+                   (mapv :status (get-in result [:data :checks]))))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))))
+        (p/finally done))))
+
+(deftest test-execute-doctor-starting-server-warning
+  (async done
+    (-> (p/with-redefs [root-dir/ensure-root-dir! (fn [_] "/tmp/logseq-doctor")
+                        cli-version/revision (fn [] "cli-rev")
+                        cli-server/list-servers (fn [_]
+                                                  (p/resolved [{:repo "logseq_db_demo"
+                                                                :status :starting
+                                                                :host "127.0.0.1"
+                                                                :port 9010
+                                                                :revision "cli-rev"}]))]
+          (p/let [result (commands/execute {:type :doctor
+                                            :script-path "src/main/logseq/cli/commands.cljs"}
+                                           {:root-dir "/tmp/logseq-doctor"})]
+            (is (= :ok (:status result)))
+            (is (= :warning (get-in result [:data :status])))
+            (is (= :running-servers
+                   (get-in result [:data :checks 2 :id])))
+            (is (= :warning
+                   (get-in result [:data :checks 2 :status])))
+            (is (= :doctor-server-not-ready
+                   (get-in result [:data :checks 2 :code])))
+            (is (= :server-revision-mismatch
+                   (get-in result [:data :checks 3 :id])))
+            (is (= :ok
+                   (get-in result [:data :checks 3 :status])))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))))
+        (p/finally done))))
+
+(deftest test-execute-doctor-server-revision-mismatch-warning
+  (async done
+    (-> (p/with-redefs [root-dir/ensure-root-dir! (fn [_] "/tmp/logseq-doctor")
+                        cli-version/revision (fn [] "cli-rev")
+                        cli-server/list-servers (fn [_]
+                                                  (p/resolved [{:repo "logseq_db_graph-a"
+                                                                :status :ready
+                                                                :revision "cli-rev"}
+                                                               {:repo "logseq_db_graph-b"
+                                                                :status :ready
+                                                                :revision "worker-rev"}]))]
+          (p/let [result (commands/execute {:type :doctor
+                                            :script-path "src/main/logseq/cli/commands.cljs"}
+                                           {:root-dir "/tmp/logseq-doctor"})]
+            (is (= :ok (:status result)))
+            (is (= :warning (get-in result [:data :status])))
+            (is (= :server-revision-mismatch
+                   (get-in result [:data :checks 3 :id])))
+            (is (= :warning
+                   (get-in result [:data :checks 3 :status])))
+            (is (= :doctor-server-revision-mismatch
+                   (get-in result [:data :checks 3 :code])))
+            (is (= "cli-rev"
+                   (get-in result [:data :checks 3 :cli-revision])))
+            (is (= ["logseq_db_graph-b"]
+                   (mapv :repo (get-in result [:data :checks 3 :servers]))))
+            (is (= ["graph-b"]
+                   (mapv :graph (get-in result [:data :checks 3 :servers]))))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))))
+        (p/finally done))))
+
+(deftest test-execute-doctor-missing-server-revision-is-mismatch
+  (async done
+    (-> (p/with-redefs [root-dir/ensure-root-dir! (fn [_] "/tmp/logseq-doctor")
+                        cli-version/revision (fn [] "cli-rev")
+                        cli-server/list-servers (fn [_]
+                                                  (p/resolved [{:repo "logseq_db_graph-a"
+                                                                :status :ready}]))]
+          (p/let [result (commands/execute {:type :doctor
+                                            :script-path "src/main/logseq/cli/commands.cljs"}
+                                           {:root-dir "/tmp/logseq-doctor"})]
+            (is (= :ok (:status result)))
+            (is (= :warning (get-in result [:data :status])))
+            (is (= :warning
+                   (get-in result [:data :checks 3 :status])))
+            (is (nil? (get-in result [:data :checks 3 :servers 0 :revision])))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))))
+        (p/finally done))))
+
+(deftest test-execute-doctor-default-script-checks-packaged-runtime-target
+  (async done
+         (-> (p/with-redefs [root-dir/ensure-root-dir! (fn [_] "/tmp/logseq-doctor")
+                             cli-server/list-servers (fn [_] (p/resolved []))
+                             doctor-command/check-db-worker-script
+                             (fn [_]
+                               {:ok? true
+                                :check {:id :db-worker-script
+                                        :status :ok
+                                        :path "/dist/db-worker-node.js"
+                                        :message (str "Found readable file: " "/dist/db-worker-node.js")}})]
+               (p/let [result (commands/execute {:type :doctor}
+                                                {:root-dir "/tmp/logseq-doctor"})
+                       checked-path (get-in result [:data :checks 0 :path])]
+                 (is (= :ok (:status result)))
+                 (is (string/ends-with? checked-path "/dist/db-worker-node.js"))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-check-running-servers-formats-large-count
+  (async done
+         (let [servers (mapv (fn [idx]
+                               {:repo (str "logseq_db_graph-" idx)
+                                :status :starting})
+                             (range 1234))]
+           (-> (p/with-redefs [cli-server/list-servers (fn [_] (p/resolved servers))]
+                 (p/let [result (#'doctor-command/check-running-servers {})
+                         message (get-in result [:check :message])]
+                   (is (= true (:warning? result)))
+                   (is (string/includes? message "1,234 servers still starting:"))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-check-server-revision-mismatch-formats-large-count
+  (let [mismatch-servers (mapv (fn [idx]
+                                 {:repo (str "logseq_db_graph-" idx)
+                                  :revision "worker-rev"})
+                               (range 1234))
+        result (with-redefs [cli-server/compute-revision-mismatches
+                             (fn [_ _]
+                               {:servers mismatch-servers})]
+                 (#'doctor-command/check-server-revision-mismatch "cli-rev" []))]
+    (is (= true (:warning? result)))
+    (is (string/includes? (get-in result [:check :message])
+                          "1,234 servers use a different revision than this CLI"))))
diff --git a/src/test/logseq/cli/command/example_test.cljs b/src/test/logseq/cli/command/example_test.cljs
new file mode 100644
index 0000000000..58aad91018
--- /dev/null
+++ b/src/test/logseq/cli/command/example_test.cljs
@@ -0,0 +1,92 @@
+(ns logseq.cli.command.example-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [logseq.cli.command.example :as example-command]
+            [logseq.cli.command.graph :as graph-command]
+            [logseq.cli.command.list :as list-command]
+            [logseq.cli.command.query :as query-command]
+            [logseq.cli.command.remove :as remove-command]
+            [logseq.cli.command.search :as search-command]
+            [logseq.cli.command.show :as show-command]
+            [logseq.cli.command.upsert :as upsert-command]))
+
+(def ^:private phase1-base-table
+  (vec (concat graph-command/entries
+               list-command/entries
+               upsert-command/entries
+               remove-command/entries
+               query-command/entries
+               search-command/entries
+               show-command/entries)))
+
+(deftest test-phase1-target-filter
+  (let [targets (example-command/phase1-target-entries phase1-base-table)
+        groups (set (map (comp first :cmds) targets))]
+    (testing "phase1 includes inspect/edit groups"
+      (is (contains? groups "list"))
+      (is (contains? groups "upsert"))
+      (is (contains? groups "remove"))
+      (is (contains? groups "query"))
+      (is (contains? groups "search"))
+      (is (contains? groups "show")))
+
+    (testing "phase1 excludes graph management commands"
+      (is (not (contains? groups "graph"))))))
+
+(deftest test-build-example-entries
+  (let [entries (example-command/build-example-entries phase1-base-table)
+        cmds-set (set (map :cmds entries))]
+    (testing "builds prefix selectors"
+      (is (contains? cmds-set ["example" "upsert"]))
+      (is (contains? cmds-set ["example" "query"]))
+      (is (contains? cmds-set ["example" "show"])))
+
+    (testing "builds exact selectors"
+      (is (contains? cmds-set ["example" "upsert" "page"]))
+      (is (contains? cmds-set ["example" "search" "block"]))
+      (is (contains? cmds-set ["example" "query" "list"])))
+
+    (testing "does not build uncovered selectors"
+      (is (not (contains? cmds-set ["example" "graph"])))))
+
+  (testing "all generated entries use :example command keyword"
+    (is (every? #(= :example (:command %))
+                (example-command/build-example-entries phase1-base-table)))))
+
+(deftest test-build-action
+  (testing "builds exact selector action"
+    (let [result (example-command/build-action phase1-base-table ["example" "upsert" "page"])]
+      (is (true? (:ok? result)))
+      (is (= :example (get-in result [:action :type])))
+      (is (= "upsert page" (get-in result [:action :selector])))
+      (is (= ["upsert page"] (get-in result [:action :matched-commands])))
+      (is (seq (get-in result [:action :examples])))))
+
+  (testing "builds prefix selector action"
+    (let [result (example-command/build-action phase1-base-table ["example" "upsert"])]
+      (is (true? (:ok? result)))
+      (is (= "upsert" (get-in result [:action :selector])))
+      (is (<= 2 (count (get-in result [:action :matched-commands]))))))
+
+  (testing "rejects unknown selector"
+    (let [result (example-command/build-action phase1-base-table ["example" "graph"])]
+      (is (false? (:ok? result)))
+      (is (= :unknown-command (get-in result [:error :code])))))
+
+  (testing "rejects matched commands with missing examples metadata"
+    (let [mock-base-table [{:cmds ["upsert" "page"]
+                            :examples ["logseq upsert page --graph my-graph --page Home"]}
+                           {:cmds ["upsert" "tag"]
+                            :examples []}]
+          result (example-command/build-action mock-base-table ["example" "upsert"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-examples (get-in result [:error :code]))))))
+
+(deftest test-build-action-formats-large-example-count
+  (let [mock-base-table [{:cmds ["upsert" "page"]
+                          :examples (mapv (fn [idx]
+                                            (str "logseq upsert page --graph demo --page Page-" idx))
+                                          (range 1234))}]
+        result (example-command/build-action mock-base-table ["example" "upsert" "page"])]
+    (is (true? (:ok? result)))
+    (is (= "Found 1,234 examples for selector upsert page"
+           (get-in result [:action :message])))))
diff --git a/src/test/logseq/cli/command/graph_test.cljs b/src/test/logseq/cli/command/graph_test.cljs
new file mode 100644
index 0000000000..54d73dd406
--- /dev/null
+++ b/src/test/logseq/cli/command/graph_test.cljs
@@ -0,0 +1,263 @@
+(ns logseq.cli.command.graph-test
+  (:require ["fs" :as fs]
+            ["path" :as node-path]
+            [cljs.test :refer [async deftest is]]
+            [clojure.string :as string]
+            [frontend.test.node-helper :as node-helper]
+            [logseq.cli.command.graph :as graph-command]
+            [logseq.cli.commands :as commands]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [logseq.common.graph-dir :as graph-dir]
+            [promesa.core :as p]))
+
+(deftest test-graph-validate-result
+  (let [graph-validate-result #'graph-command/graph-validate-result
+        invalid-result (graph-validate-result {:errors [{:entity {:db/id 1}
+                                                         :errors {:foo ["bad"]}}]})
+        valid-result (graph-validate-result {:errors nil :datom-count 10})]
+    (is (= :error (:status invalid-result)))
+    (is (= :graph-validation-failed (get-in invalid-result [:error :code])))
+    (is (string/includes? (get-in invalid-result [:error :message])
+                          "Found 1 entity with errors:"))
+    (is (= :ok (:status valid-result)))))
+
+(deftest test-graph-validate-result-formats-large-error-count
+  (let [graph-validate-result #'graph-command/graph-validate-result
+        errors (mapv (fn [idx]
+                       {:entity {:db/id idx}
+                        :errors {:foo ["bad"]}})
+                     (range 1234))
+        invalid-result (graph-validate-result {:errors errors})]
+    (is (= :error (:status invalid-result)))
+    (is (string/includes? (get-in invalid-result [:error :message])
+                          "Found 1,234 entities with errors:"))))
+
+(deftest test-execute-graph-info-queries-kv-rows-with-thread-api-q
+  (async done
+         (let [invoke-calls* (atom [])
+               action {:repo "demo-repo"
+                       :graph "demo-graph"}]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _]
+                                                           (p/resolved {:base-url "http://example"}))
+                               transport/invoke (fn [_ method _ args]
+                                                  (swap! invoke-calls* conj [method args])
+                                                  (p/resolved [[:logseq.kv/schema-version 7]
+                                                               [:logseq.kv/graph-created-at 40000]
+                                                               [:logseq.kv/db-type :sqlite]]))]
+                 (p/let [result (graph-command/execute-graph-info action {})]
+                   (is (= :ok (:status result)))
+                   (is (= 1 (count @invoke-calls*)))
+                   (let [[method [repo query-args]] (first @invoke-calls*)]
+                     (is (= :thread-api/q method))
+                     (is (= "demo-repo" repo))
+                     (is (= 1 (count query-args)))
+                     (is (string/includes? (pr-str (first query-args)) "logseq.kv")))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-backup-create-invokes-worker-backup-api
+  (async done
+         (let [invoke-calls (atom [])
+               root-dir (node-helper/create-tmp-dir "cli-backup-create-path")]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:path (second args)}))]
+                 (p/let [result (commands/execute {:type :graph-backup-create
+                                                   :repo "logseq_db_demo"
+                                                   :graph "demo"
+                                                   :backup-name "demo-nightly-20260101T000000Z"}
+                                                  {:root-dir root-dir})]
+                   (is (= :ok (:status result)))
+                   (is (= 1 (count @invoke-calls)))
+                   (let [[method _ [repo backup-db-path]] (first @invoke-calls)
+                         expected-segment (node-path/join
+                                           (graph-dir/repo->encoded-graph-dir-name repo)
+                                           "backup"
+                                           (graph-dir/graph-dir-key->encoded-dir-name "demo-nightly-20260101T000000Z")
+                                           "db.sqlite")]
+                     (is (= :thread-api/backup-db-sqlite method))
+                     (is (= "logseq_db_demo" repo))
+                     (is (and (string? backup-db-path)
+                              (string/includes? backup-db-path expected-segment))))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-backup-list-only-returns-current-graph-backups
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-backup-list-scope")
+               demo-repo "logseq_db_demo"
+               other-repo "logseq_db_other"
+               demo-backup "demo-nightly"
+               other-backup "other-nightly"
+               demo-db-path (node-path/join root-dir
+                                            "graphs"
+                                            (graph-dir/repo->encoded-graph-dir-name demo-repo)
+                                            "backup"
+                                            (graph-dir/graph-dir-key->encoded-dir-name demo-backup)
+                                            "db.sqlite")
+               other-db-path (node-path/join root-dir
+                                             "graphs"
+                                             (graph-dir/repo->encoded-graph-dir-name other-repo)
+                                             "backup"
+                                             (graph-dir/graph-dir-key->encoded-dir-name other-backup)
+                                             "db.sqlite")]
+           (fs/mkdirSync (node-path/dirname demo-db-path) #js {:recursive true})
+           (fs/mkdirSync (node-path/dirname other-db-path) #js {:recursive true})
+           (fs/writeFileSync demo-db-path "demo")
+           (fs/writeFileSync other-db-path "other")
+           (-> (p/let [result (commands/execute {:type :graph-backup-list
+                                                 :repo demo-repo
+                                                 :graph "demo"}
+                                                {:root-dir root-dir})
+                       backup-names (mapv :name (get-in result [:data :backups]))]
+                 (is (= :ok (:status result)))
+                 (is (= [demo-backup] backup-names)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-backup-restore-fails-when-source-backup-missing
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-backup-restore-missing")]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] [])]
+                 (p/let [result (commands/execute {:type :graph-backup-restore
+                                                   :repo "logseq_db_demo-restored"
+                                                   :graph "demo-restored"
+                                                   :source-repo "logseq_db_demo"
+                                                   :source-graph "demo"
+                                                   :src "demo-nightly"
+                                                   :dst "demo-restored"
+                                                   :allow-missing-graph true
+                                                   :require-missing-graph true}
+                                                  {:root-dir root-dir})]
+                   (is (= :error (:status result)))
+                   (is (= :backup-not-found (get-in result [:error :code])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-backup-restore-fails-when-destination-graph-exists
+  (async done
+         (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo-restored"])]
+               (p/let [result (commands/execute {:type :graph-backup-restore
+                                                 :repo "logseq_db_demo-restored"
+                                                 :graph "demo-restored"
+                                                 :source-repo "logseq_db_demo"
+                                                 :source-graph "demo"
+                                                 :src "demo-nightly"
+                                                 :dst "demo-restored"
+                                                 :allow-missing-graph true
+                                                 :require-missing-graph true}
+                                                {:root-dir "/tmp/graphs"})]
+                 (is (= :error (:status result)))
+                 (is (= :graph-exists (get-in result [:error :code])))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-graph-backup-restore-reuses-sqlite-import-flow
+  (async done
+         (let [invoke-calls (atom [])
+               read-calls (atom [])
+               stop-calls (atom [])
+               restart-calls (atom [])
+               root-dir (node-helper/create-tmp-dir "cli-backup-restore-flow")
+               backup-db-path (node-path/join root-dir
+                                              "graphs"
+                                              (graph-dir/repo->encoded-graph-dir-name "logseq_db_demo")
+                                              "backup"
+                                              (graph-dir/graph-dir-key->encoded-dir-name "demo-nightly")
+                                              "db.sqlite")]
+           (fs/mkdirSync (node-path/dirname backup-db-path) #js {:recursive true})
+           (fs/writeFileSync backup-db-path "seed")
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] [])
+                               cli-server/stop-server! (fn [_ repo]
+                                                         (swap! stop-calls conj repo)
+                                                         (p/resolved {:ok? true}))
+                               cli-server/restart-server! (fn [_ repo]
+                                                            (swap! restart-calls conj repo)
+                                                            (p/resolved {:ok? true}))
+                               cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/read-input (fn [{:keys [format path]}]
+                                                      (swap! read-calls conj [format path])
+                                                      (js/Buffer.from "sqlite" "utf8"))
+                               transport/invoke (fn [_ method _ args]
+                                                  (swap! invoke-calls conj [method args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [result (commands/execute {:type :graph-backup-restore
+                                                   :repo "logseq_db_demo-restored"
+                                                   :graph "demo-restored"
+                                                   :source-repo "logseq_db_demo"
+                                                   :source-graph "demo"
+                                                   :src "demo-nightly"
+                                                   :dst "demo-restored"
+                                                   :allow-missing-graph true
+                                                   :require-missing-graph true}
+                                                  {:root-dir root-dir})]
+                   (is (= :ok (:status result)))
+                   (is (= true (get-in result [:data :new-graph?])))
+                   (is (= ["logseq_db_demo-restored"] @stop-calls))
+                   (is (= ["logseq_db_demo-restored"] @restart-calls))
+                   (is (= 1 (count @read-calls)))
+                   (let [[read-format read-path] (first @read-calls)
+                         expected-segment (node-path/join
+                                           (graph-dir/repo->encoded-graph-dir-name "logseq_db_demo")
+                                           "backup"
+                                           (graph-dir/graph-dir-key->encoded-dir-name "demo-nightly")
+                                           "db.sqlite")]
+                     (is (= :sqlite read-format))
+                     (is (and (string? read-path)
+                              (string/includes? read-path expected-segment))))
+                   (is (= [[:thread-api/import-db-base64 ["logseq_db_demo-restored" "c3FsaXRl"]]]
+                          @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-backup-remove-fails-when-source-backup-missing
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-backup-remove-missing")]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])]
+                 (p/let [result (commands/execute {:type :graph-backup-remove
+                                                   :repo "logseq_db_demo"
+                                                   :graph "demo"
+                                                   :src "demo-nightly"}
+                                                  {:root-dir root-dir})]
+                   (is (= :error (:status result)))
+                   (is (= :backup-not-found (get-in result [:error :code])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-info-preserves-summary-fields-and-builds-kv-map
+  (async done
+         (let [action {:repo "demo-repo"
+                       :graph "demo-graph"}]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _]
+                                                           (p/resolved {:base-url "http://example"}))
+                               transport/invoke (fn [_ method _ _]
+                                                  (case method
+                                                    :thread-api/q
+                                                    (p/resolved [[:logseq.kv/db-type :sqlite]
+                                                                 [:logseq.kv/graph-created-at 40000]
+                                                                 [:logseq.kv/schema-version 7]])
+                                                    (throw (ex-info "unexpected invoke method" {:method method}))))]
+                 (p/let [result (graph-command/execute-graph-info action {})]
+                   (is (= :ok (:status result)))
+                   (is (= "demo-graph" (get-in result [:data :graph])))
+                   (is (= 40000 (get-in result [:data :logseq.kv/graph-created-at])))
+                   (is (= 7 (get-in result [:data :logseq.kv/schema-version])))
+                   (is (= {"logseq.kv/db-type" :sqlite
+                           "logseq.kv/graph-created-at" 40000
+                           "logseq.kv/schema-version" 7}
+                          (get-in result [:data :kv])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
diff --git a/src/test/logseq/cli/command/query_test.cljs b/src/test/logseq/cli/command/query_test.cljs
new file mode 100644
index 0000000000..3699e27993
--- /dev/null
+++ b/src/test/logseq/cli/command/query_test.cljs
@@ -0,0 +1,177 @@
+(ns logseq.cli.command.query-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [clojure.string :as string]
+            [logseq.cli.command.query :as query-command]))
+
+(deftest test-query-entries-examples
+  (let [query-entry (first (filter #(= :query (:command %)) query-command/entries))
+        query-list-entry (first (filter #(= :query-list (:command %)) query-command/entries))]
+    (testing "query command has examples metadata"
+      (is (seq (:examples query-entry))))
+    (testing "query list command has examples metadata"
+      (is (seq (:examples query-list-entry))))))
+
+(deftest test-build-action-parses-query
+  (testing "query parses query and inputs"
+    (let [result (query-command/build-action {:query "[:find ?e :in $ ?title :where [?e :block/title ?title]]"
+                                              :inputs "[\"Hello\"]"}
+                                             "logseq_db_demo"
+                                             {})]
+      (is (true? (:ok? result)))
+      (is (= :query (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))
+      (is (= '[:find ?e :in $ ?title :where [?e :block/title ?title]]
+             (get-in result [:action :query])))
+      (is (= ["Hello"] (get-in result [:action :inputs]))))))
+
+(deftest test-build-action-invalid-edn
+  (testing "invalid query edn returns invalid-options"
+    (let [result (query-command/build-action {:query "[:find ?e"}
+                                             "logseq_db_demo"
+                                             {})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? (get-in result [:error :message]) "query"))))
+
+  (testing "invalid inputs edn returns invalid-options"
+    (let [result (query-command/build-action {:query "[:find ?e :where [?e :block/title \"Hello\"]]"
+                                              :inputs "[\"Hello"}
+                                             "logseq_db_demo"
+                                             {})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? (get-in result [:error :message]) "inputs")))))
+
+(deftest test-build-action-named-query
+  (testing "named query resolves from config"
+    (let [config {:custom-queries {"my-query"
+                                   {:doc "Custom query"
+                                    :inputs ["title"]
+                                    :query '[:find ?e
+                                             :in $ ?title
+                                             :where
+                                             [?e :block/title ?title]]}}}
+          result (query-command/build-action {:name "my-query"
+                                              :inputs "[\"Alpha\"]"}
+                                             "logseq_db_demo"
+                                             config)]
+      (is (true? (:ok? result)))
+      (is (= '[:find ?e :in $ ?title :where [?e :block/title ?title]]
+             (get-in result [:action :query])))
+      (is (= ["Alpha"] (get-in result [:action :inputs])))))
+
+  (testing "unknown named query returns unknown-query error"
+    (let [result (query-command/build-action {:name "missing"}
+                                             "logseq_db_demo"
+                                             {:custom-queries {}})]
+      (is (false? (:ok? result)))
+      (is (= :unknown-query (get-in result [:error :code])))))
+
+  (testing "rejects both name and query"
+    (let [result (query-command/build-action {:name "my-query"
+                                              :query "[:find ?e :where [?e :block/title ?title]]"}
+                                             "logseq_db_demo"
+                                             {:custom-queries {"my-query" {:query '[:find ?e]}}})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "optional inputs are padded with nils"
+    (let [config {:custom-queries {"task-search"
+                                   {:inputs ["search-status" "?search-title" "?recent-days"]
+                                    :query '[:find [?e ...]
+                                             :in $ ?search-status ?search-title ?recent-days
+                                             :where
+                                             [?e :block/title ?title]]}}}
+          result (query-command/build-action {:name "task-search"
+                                              :inputs "[\"doing\"]"}
+                                             "logseq_db_demo"
+                                             config)]
+      (is (true? (:ok? result)))
+      (is (= [:logseq.property/status.doing nil nil] (get-in result [:action :inputs])))))
+
+  (testing "missing required inputs returns invalid-options"
+    (let [config {:custom-queries {"task-search"
+                                   {:inputs ["search-status" "?search-title"]
+                                    :query '[:find [?e ...]
+                                             :in $ ?search-status ?search-title
+                                             :where
+                                             [?e :block/title ?title]]}}}
+          result (query-command/build-action {:name "task-search"
+                                              :inputs "[]"}
+                                             "logseq_db_demo"
+                                             config)]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "optional inputs can define defaults in cli.edn"
+    (let [config {:custom-queries {"task-search"
+                                   {:inputs [{:name "search-status"}
+                                             {:name "?search-title" :default "fallback-title"}
+                                             {:name "?recent-days" :default 7}]
+                                    :query '[:find [?e ...]
+                                             :in $ ?search-status ?search-title ?recent-days
+                                             :where
+                                             [?e :block/title ?title]]}}}
+          result (query-command/build-action {:name "task-search"
+                                              :inputs "[\"doing\"]"}
+                                             "logseq_db_demo"
+                                             config)]
+      (is (true? (:ok? result)))
+      (is (= [:logseq.property/status.doing "fallback-title" 7] (get-in result [:action :inputs])))))
+
+  (testing "built-in task-search uses defaults for optional inputs"
+    (let [result (query-command/build-action {:name "task-search"
+                                              :inputs "[\"doing\"]"}
+                                             "logseq_db_demo"
+                                             {})]
+      (is (true? (:ok? result)))
+      (let [inputs (get-in result [:action :inputs])]
+        (is (= [:logseq.property/status.doing "" 0] (subvec inputs 0 3)))
+        (is (number? (nth inputs 3)))))))
+
+(deftest test-build-action-closed-value-queries
+  (testing "list-status builds standard query action"
+    (let [result (query-command/build-action {:name "list-status"}
+                                             "logseq_db_demo"
+                                             {})]
+      (is (true? (:ok? result)))
+      (is (= :query (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))
+      (is (= '[:find [(pull ?value [:db/id :db/ident :block/order]) ...]
+               :where
+               [?property :db/ident :logseq.property/status]
+               [?value :block/closed-value-property ?property]]
+             (get-in result [:action :query])))))
+
+  (testing "list-priority builds standard query action"
+    (let [result (query-command/build-action {:name "list-priority"}
+                                             "logseq_db_demo"
+                                             {})]
+      (is (true? (:ok? result)))
+      (is (= :query (get-in result [:action :type])))
+      (is (= :logseq.property/priority (get-in result [:action :query 3 2])))
+      (is (= '[:find [(pull ?value [:db/id :db/ident :block/order]) ...]
+               :where
+               [?property :db/ident :logseq.property/priority]
+               [?value :block/closed-value-property ?property]]
+             (get-in result [:action :query]))))))
+
+(deftest test-query-list-merges-built-in-and-custom
+  (testing "built-in and custom queries are both listed"
+    (let [queries (query-command/list-queries {:custom-queries {"custom-q" {:query '[:find ?e]}}})
+          names (set (map :name queries))]
+      (is (contains? names "task-search"))
+      (is (contains? names "list-status"))
+      (is (contains? names "list-priority"))
+      (is (contains? names "custom-q"))))
+
+  (testing "custom query overrides built-in name"
+    (let [queries (query-command/list-queries {:custom-queries {"block-search" {:query '[:find ?e]}}})
+          block-search (first (filter #(= "block-search" (:name %)) queries))]
+      (is (= :custom (:source block-search)))))
+
+  (testing "list-status and list-priority have empty inputs"
+    (let [queries (query-command/list-queries {})
+          by-name (into {} (map (fn [entry] [(:name entry) entry]) queries))]
+      (is (= [] (get-in by-name ["list-status" :inputs])))
+      (is (= [] (get-in by-name ["list-priority" :inputs]))))))
diff --git a/src/test/logseq/cli/command/remove_test.cljs b/src/test/logseq/cli/command/remove_test.cljs
new file mode 100644
index 0000000000..8aea7c6c14
--- /dev/null
+++ b/src/test/logseq/cli/command/remove_test.cljs
@@ -0,0 +1,126 @@
+(ns logseq.cli.command.remove-test
+  (:require [cljs.test :refer [async deftest is]]
+            [logseq.cli.command.remove :as remove-command]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [promesa.core :as p]))
+
+(deftest test-execute-remove-block-rejects-page-entity
+  (async done
+    (let [delete-called?* (atom false)
+          action {:type :remove-block
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :ids [190]
+                  :multi-id? false}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/pull
+                                               (p/resolved {:db/id 190
+                                                            :block/uuid (random-uuid)
+                                                            :block/name "some-page"})
+
+                                               :thread-api/apply-outliner-ops
+                                               (do (reset! delete-called?* true)
+                                                   (p/resolved nil))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method :args args}))))]
+            (p/let [result (remove-command/execute-remove-block action {})]
+              (is (= :error (:status result))
+                  "should return error for page entity")
+              (is (= :invalid-target (get-in result [:error :code])))
+              (is (false? @delete-called?*)
+                  "delete must not be called for page entity")))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-remove-block-multi-id-all-pages-returns-error
+  (async done
+    (let [delete-called?* (atom false)
+          action {:type :remove-block
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :ids [190]
+                  :multi-id? true}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ _]
+                                             (case method
+                                               :thread-api/pull
+                                               (p/resolved {:db/id 190
+                                                            :block/uuid (random-uuid)
+                                                            :block/name "some-page"})
+
+                                               :thread-api/apply-outliner-ops
+                                               (do (reset! delete-called?* true)
+                                                   (p/resolved nil))
+
+                                               (throw (ex-info "unexpected invoke" {:method method}))))]
+            (p/let [result (remove-command/execute-remove-block action {})]
+              (is (= :error (:status result)))
+              (is (= :invalid-target (get-in result [:error :code])))
+              (is (false? @delete-called?*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-remove-block-by-id-uses-uuid-in-delete-op
+  (async done
+    (let [captured-ops* (atom nil)
+          block-uuid (uuid "00000000-0000-0000-0000-000000000190")
+          action {:type :remove-block
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :ids [190]
+                  :multi-id? false}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/pull
+                                               (p/resolved {:db/id 190
+                                                            :block/uuid block-uuid})
+
+                                               :thread-api/apply-outliner-ops
+                                               (let [[_repo ops _opts] args]
+                                                 (reset! captured-ops* ops)
+                                                 (p/resolved nil))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method :args args}))))]
+            (p/let [result (remove-command/execute-remove-block action {})]
+              (is (= :ok (:status result)))
+              (is (= [[:delete-blocks [[block-uuid] {}]]]
+                     @captured-ops*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-remove-block-rethrows-unexpected-errors
+  (async done
+    (let [action {:type :remove-block
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :ids [190]
+                  :multi-id? false}
+          boom (js/Error. "transport exploded")]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ _args]
+                                             (case method
+                                               :thread-api/pull
+                                               (p/rejected boom)
+                                               (p/resolved nil)))]
+            (-> (remove-command/execute-remove-block action {})
+                (p/then (fn [_]
+                          (is false "expected unexpected error to reject")))
+                (p/catch (fn [error]
+                           (is (= "transport exploded"
+                                  (or (ex-message error) (.-message error))))))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
diff --git a/src/test/logseq/cli/command/search_test.cljs b/src/test/logseq/cli/command/search_test.cljs
new file mode 100644
index 0000000000..68cc1f6de6
--- /dev/null
+++ b/src/test/logseq/cli/command/search_test.cljs
@@ -0,0 +1,137 @@
+(ns logseq.cli.command.search-test
+  (:require [cljs.test :refer [async deftest is testing]]
+            [logseq.cli.command.search :as search-command]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [promesa.core :as p]))
+
+(deftest test-search-command-entries
+  (let [entries search-command/entries
+        by-command (into {} (map (juxt :command identity) entries))]
+    (is (= #{:search-block :search-page :search-property :search-tag}
+           (set (keys by-command))))
+    (is (= ["search" "block"] (:cmds (:search-block by-command))))
+    (is (= ["search" "page"] (:cmds (:search-page by-command))))
+    (is (= ["search" "property"] (:cmds (:search-property by-command))))
+    (is (= ["search" "tag"] (:cmds (:search-tag by-command))))
+    (doseq [command [:search-block :search-page :search-property :search-tag]]
+      (is (contains? (get-in by-command [command :spec]) :content))
+      (is (= :c (get-in by-command [command :spec :content :alias])))
+      (is (= "Search content text" (get-in by-command [command :spec :content :desc]))))))
+
+(deftest test-build-action
+  (testing "build-action reads query text from options"
+    (let [result (search-command/build-action :search-block {:content "Alpha Beta"} "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= {:type :search-block
+              :repo "logseq_db_demo"
+              :graph "demo"
+              :query "Alpha Beta"}
+             (:action result)))))
+
+  (testing "build-action requires repo"
+    (let [result (search-command/build-action :search-page {:content "Home"} nil)]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+  (testing "build-action rejects blank --content"
+    (let [result (search-command/build-action :search-tag {:content "   "} "logseq_db_demo")]
+      (is (false? (:ok? result)))
+      (is (= :missing-query-text (get-in result [:error :code])))))
+
+  (testing "build-action ignores unrelated options"
+    (let [result (search-command/build-action :search-page {:content "home" :output "json"} "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= "home" (get-in result [:action :query]))))))
+
+(deftest test-execute-search
+  (async done
+         (let [calls* (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ [repo [query-text query-input]]]
+                                                  (swap! calls* conj {:method method
+                                                                      :repo repo
+                                                                      :query-text (pr-str query-text)
+                                                                      :query-input query-input})
+                                                  [{:db/id 9 :block/title "beta" :unused true}
+                                                   {:db/id 7 :block/title "Alpha"}])]
+                 (p/let [block-result (search-command/execute-search-block {:type :search-block :repo "demo" :query "alpha"} {})
+                         page-result (search-command/execute-search-page {:type :search-page :repo "demo" :query "home"} {})
+                         property-result (search-command/execute-search-property {:type :search-property :repo "demo" :query "owner"} {})
+                         tag-result (search-command/execute-search-tag {:type :search-tag :repo "demo" :query "quote"} {})]
+                   (is (= :ok (:status block-result)))
+                   (is (= :ok (:status page-result)))
+                   (is (= :ok (:status property-result)))
+                   (is (= :ok (:status tag-result)))
+                   (is (= [{:db/id 7 :block/title "Alpha"}
+                           {:db/id 9 :block/title "beta"}]
+                          (get-in block-result [:data :items])))
+                   (is (= [:thread-api/q :thread-api/q :thread-api/q :thread-api/q]
+                          (mapv :method @calls*)))
+                   (is (= ["demo" "demo" "demo" "demo"] (mapv :repo @calls*)))
+                   (is (= ["alpha" "home" "owner" "quote"] (mapv :query-input @calls*)))
+                   (is (re-find #":block/title" (:query-text (nth @calls* 0))))
+                   (is (re-find #":block/name" (:query-text (nth @calls* 1))))
+                   (is (re-find #":logseq.class/Property" (:query-text (nth @calls* 2))))
+                   (is (re-find #":logseq.class/Tag" (:query-text (nth @calls* 3))))
+                   (is (re-find #":logseq.property/deleted-at" (:query-text (nth @calls* 1)))
+                       "search-page query pulls :logseq.property/deleted-at to support recycle filtering")
+                   (is (re-find #":logseq.property/deleted-at" (:query-text (nth @calls* 0)))
+                       "search-block query pulls :logseq.property/deleted-at to support recycle filtering")
+                   (is (re-find #"\{:block/parent \.\.\.\}" (:query-text (nth @calls* 0)))
+                       "search-block query pulls :block/parent recursively so ldb/recycled? can walk to the page")))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-search-block-skips-block-on-recycled-page
+  ;; Recycled pages get :block/parent set to the Recycle page id and
+  ;; :logseq.property/deleted-at stamped on themselves. The recursive
+  ;; {:block/parent ...} pull lets ldb/recycled? walk from a child block up
+  ;; through its parent chain until it lands on the recycled page's
+  ;; :logseq.property/deleted-at.
+  (async done
+         (let [recycled-page-parent {:db/id 50
+                                     :block/title "Old Page"
+                                     :logseq.property/deleted-at 1712000000000
+                                     :block/parent {:db/id 999 :block/title "Recycle"}}
+               live-page-parent {:db/id 51
+                                 :block/title "Live Page"}]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ _ _ _]
+                                                  [{:db/id 1 :block/title "alpha live"
+                                                    :block/parent live-page-parent}
+                                                   {:db/id 2 :block/title "alpha orphan"
+                                                    :block/parent {:db/id 10
+                                                                   :block/title "intermediate"
+                                                                   :block/parent recycled-page-parent}}
+                                                   {:db/id 3 :block/title "alpha tombstone"
+                                                    :block/parent recycled-page-parent}])]
+                 (p/let [result (search-command/execute-search-block
+                                 {:type :search-block :repo "demo" :query "alpha"}
+                                 {})]
+                   (is (= :ok (:status result)))
+                   (is (= [{:db/id 1 :block/title "alpha live"}]
+                          (get-in result [:data :items]))
+                       "blocks under a recycled page are filtered, even through an intermediate parent block")))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-search-page-skips-recycled-pages
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ _ _ _]
+                                                [{:db/id 1 :block/title "Home"}
+                                                 {:db/id 2 :block/title "Recycled Home"
+                                                  :logseq.property/deleted-at 1712000000000}
+                                                 {:db/id 3 :block/title "Homework"}])]
+               (p/let [result (search-command/execute-search-page
+                               {:type :search-page :repo "demo" :query "home"}
+                               {})]
+                 (is (= :ok (:status result)))
+                 (is (= [{:db/id 1 :block/title "Home"}
+                         {:db/id 3 :block/title "Homework"}]
+                        (get-in result [:data :items]))
+                     "recycled page is filtered out and :logseq.property/deleted-at is stripped from output")))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
\ No newline at end of file
diff --git a/src/test/logseq/cli/command/server_test.cljs b/src/test/logseq/cli/command/server_test.cljs
new file mode 100644
index 0000000000..f301280e2b
--- /dev/null
+++ b/src/test/logseq/cli/command/server_test.cljs
@@ -0,0 +1,76 @@
+(ns logseq.cli.command.server-test
+  (:require [cljs.test :refer [async deftest is]]
+            [logseq.cli.command.server :as server-command]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.version :as cli-version]
+            [promesa.core :as p]))
+
+(deftest compute-revision-mismatches-uses-exact-string-compare
+  (let [mismatch (cli-server/compute-revision-mismatches
+                  "cli-rev"
+                  [{:repo "graph-a" :revision "cli-rev"}
+                   {:repo "graph-b" :revision "cli-rev-dirty"}])]
+    (is (= "cli-rev" (:cli-revision mismatch)))
+    (is (= ["graph-b"]
+           (mapv :repo (:servers mismatch))))))
+
+(deftest execute-list-attaches-human-mismatch-metadata
+  (async done
+         (-> (p/with-redefs [cli-version/revision (fn [] "cli-rev")
+                             cli-server/list-servers (fn [_]
+                                                       (p/resolved [{:repo "graph-a"
+                                                                     :revision "cli-rev"}
+                                                                    {:repo "graph-b"
+                                                                     :revision "worker-rev"}]))]
+               (server-command/execute-list {:type :server-list} {}))
+             (p/then (fn [result]
+                       (is (= :ok (:status result)))
+                       (is (= 2 (count (get-in result [:data :servers]))))
+                       (is (= "cli-rev"
+                              (get-in result [:human :server-list :revision-mismatch :cli-revision])))
+                       (is (= ["graph-b"]
+                              (mapv :repo (get-in result [:human :server-list :revision-mismatch :servers]))))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest execute-list-omits-mismatch-when-revisions-match
+  (async done
+         (-> (p/with-redefs [cli-version/revision (fn [] "cli-rev")
+                             cli-server/list-servers (fn [_]
+                                                       (p/resolved [{:repo "graph-a"
+                                                                     :revision "cli-rev"}]))]
+               (server-command/execute-list {:type :server-list} {}))
+             (p/then (fn [result]
+                       (is (= :ok (:status result)))
+                       (is (nil? (get-in result [:human :server-list :revision-mismatch])))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest build-action-server-cleanup-does-not-require-repo
+  (let [result (server-command/build-action :server-cleanup nil)]
+    (is (true? (:ok? result)))
+    (is (= :server-cleanup (get-in result [:action :type])))))
+
+(deftest execute-cleanup-uses-cli-revision-and-server-cleanup
+  (async done
+         (-> (p/with-redefs [cli-version/revision (fn [] "cli-rev")
+                             cli-server/cleanup-revision-mismatched-servers! (fn [config revision]
+                                                                               (is (= {:root-dir "/tmp/demo"} config))
+                                                                               (is (= "cli-rev" revision))
+                                                                               (p/resolved {:ok? true
+                                                                                            :data {:checked 2
+                                                                                                   :mismatched 1
+                                                                                                   :eligible 1
+                                                                                                   :skipped-owner 0
+                                                                                                   :killed [{:repo "graph-a" :pid 11}]
+                                                                                                   :failed []}}))]
+               (server-command/execute-cleanup {:type :server-cleanup} {:root-dir "/tmp/demo"}))
+             (p/then (fn [result]
+                       (is (= :ok (:status result)))
+                       (is (= 2 (get-in result [:data :checked])))
+                       (is (= 1 (get-in result [:data :mismatched])))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
diff --git a/src/test/logseq/cli/command/show_test.cljs b/src/test/logseq/cli/command/show_test.cljs
new file mode 100644
index 0000000000..0fe9bbc128
--- /dev/null
+++ b/src/test/logseq/cli/command/show_test.cljs
@@ -0,0 +1,723 @@
+(ns logseq.cli.command.show-test
+  (:require ["fs" :as fs]
+            [cljs.test :refer [async deftest is testing]]
+            [clojure.string :as string]
+            [logseq.cli.command.show :as show-command]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.style :as style]
+            [logseq.cli.transport :as transport]
+            [promesa.core :as p]))
+
+(deftest test-build-action-stdin-id
+  (testing "reads id from stdin when id flag is present without a value"
+    (let [result (show-command/build-action {:id ""
+                                             :id-from-stdin? true
+                                             :stdin "42"}
+                                            "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= 42 (get-in result [:action :id])))
+      (is (= [42] (get-in result [:action :ids])))
+      (is (false? (get-in result [:action :multi-id?])))))
+
+  (testing "reads multi-id vector from stdin"
+    (let [result (show-command/build-action {:id ""
+                                             :id-from-stdin? true
+                                             :stdin "[1 2 3]"}
+                                            "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= [1 2 3] (get-in result [:action :ids])))
+      (is (true? (get-in result [:action :multi-id?])))))
+
+  (testing "explicit stdin still overrides id when provided in options"
+    (let [result (show-command/build-action {:id "99"
+                                             :stdin "[1 2]"}
+                                            "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= [1 2] (get-in result [:action :ids])))
+      (is (true? (get-in result [:action :multi-id?])))))
+
+  (testing "pipe stdin does not override explicit id unless stdin mode is requested"
+    (let [orig-fstat-sync (.-fstatSync fs)
+          orig-read-file-sync (.-readFileSync fs)
+          read-count* (atom 0)]
+      (set! (.-fstatSync fs)
+            (fn [_]
+              #js {:isFIFO (fn [] true)
+                   :isFile (fn [] false)}))
+      (set! (.-readFileSync fs)
+            (fn [fd]
+              (when (= fd 0)
+                (swap! read-count* inc)
+                "[1 2]")))
+      (try
+        (let [result (show-command/build-action {:id "99"}
+                                                "logseq_db_demo")]
+          (is (true? (:ok? result)))
+          (is (= 99 (get-in result [:action :id])))
+          (is (= [99] (get-in result [:action :ids])))
+          (is (zero? @read-count*)))
+        (finally
+          (set! (.-fstatSync fs) orig-fstat-sync)
+          (set! (.-readFileSync fs) orig-read-file-sync)))))
+
+  (testing "blank stdin falls back to explicit id"
+    (let [result (show-command/build-action {:id "99"
+                                             :stdin "   "}
+                                            "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= 99 (get-in result [:action :id])))
+      (is (= [99] (get-in result [:action :ids])))))
+
+  (testing "blank stdin returns invalid options when id is missing"
+    (let [result (show-command/build-action {:id ""
+                                             :id-from-stdin? true
+                                             :stdin "   "}
+                                            "logseq_db_demo")]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? (get-in result [:error :message]) "id"))))
+
+  (testing "extracts id from upsert blocks output"
+    (let [result (show-command/build-action {:id ""
+                                             :id-from-stdin? true
+                                             :stdin "Upserted blocks:\n[10 20 30]"}
+                                            "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= [10 20 30] (get-in result [:action :ids])))
+      (is (true? (get-in result [:action :multi-id?]))))))
+
+(deftest test-merge-fetched-property-value
+  (let [merge-value #'show-command/merge-fetched-property-value]
+    (testing "first value is kept as scalar"
+      (is (= "Step 1" (merge-value nil "Step 1"))))
+
+    (testing "second distinct value upgrades scalar to vector"
+      (is (= ["Step 1" "Step 2"]
+             (merge-value "Step 1" "Step 2"))))
+
+    (testing "additional values are appended"
+      (is (= ["Step 1" "Step 2" "Step 3"]
+             (merge-value ["Step 1" "Step 2"] "Step 3"))))
+
+    (testing "duplicate values are deduplicated"
+      (is (= ["Step 1" "Step 2"]
+             (merge-value ["Step 1" "Step 2"] "Step 2"))))))
+
+(deftest test-fetch-user-properties-formats-datetime
+  (let [fetch #'show-command/fetch-user-properties
+        call-count (atom 0)
+        mock-invoke (fn [_ _method _ _args]
+                      (let [call-idx (swap! call-count inc)]
+                        (p/resolved
+                         (case call-idx
+                           ;; First call: user idents-query returns property idents with types
+                           1 [[:user.property/title :default]
+                              [:user.property/due :datetime]
+                              [:user.property/count :number]]
+                           ;; Second call: built-in idents-query returns built-in property types
+                           2 []
+                           ;; Third call: props-query returns raw values
+                           3 [[10 :user.property/title "hello"]
+                              [10 :user.property/due 1774267200000]
+                              [10 :user.property/count 42]]
+                           []))))]
+    (async done
+           (-> (p/with-redefs [transport/invoke mock-invoke]
+                 (p/let [result (fetch {} "demo" [10])]
+                   (testing "datetime value is converted to ISO string"
+                     (is (string? (get-in result [10 :user.property/due])))
+                     (is (string/includes? (get-in result [10 :user.property/due]) "2026-03-23")))
+                   (testing "non-datetime number is left as-is"
+                     (is (= 42 (get-in result [10 :user.property/count]))))
+                   (testing "string value is left as-is"
+                     (is (= "hello" (get-in result [10 :user.property/title]))))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-fetch-user-properties-includes-built-in-datetime
+  (let [fetch #'show-command/fetch-user-properties
+        call-count (atom 0)
+        mock-invoke (fn [_ _method _ _args]
+                      (let [call-idx (swap! call-count inc)]
+                        (p/resolved
+                         (case call-idx
+                           ;; First call: user idents-query
+                           1 [[:user.property/status :default]]
+                           ;; Second call: built-in idents-query returns deadline and scheduled
+                           2 [[:logseq.property/deadline :datetime]
+                              [:logseq.property/scheduled :datetime]]
+                           ;; Third call: props-query returns raw values
+                           3 [[10 :user.property/status "todo"]
+                              [10 :logseq.property/deadline 1774267200000]
+                              [10 :logseq.property/scheduled 1774180800000]]
+                           []))))]
+    (async done
+           (-> (p/with-redefs [transport/invoke mock-invoke]
+                 (p/let [result (fetch {} "demo" [10])]
+                   (testing "built-in deadline is converted to ISO string"
+                     (is (string? (get-in result [10 :logseq.property/deadline])))
+                     (is (string/includes? (get-in result [10 :logseq.property/deadline]) "2026")))
+                   (testing "built-in scheduled is converted to ISO string"
+                     (is (string? (get-in result [10 :logseq.property/scheduled])))
+                     (is (string/includes? (get-in result [10 :logseq.property/scheduled]) "2026")))
+                   (testing "user property is unaffected"
+                     (is (= "todo" (get-in result [10 :user.property/status]))))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(defn- call-private
+  [sym & args]
+  (when-let [v (get (ns-interns 'logseq.cli.command.show) sym)]
+    (apply @v args)))
+
+(defn- make-show-invoke-mock
+  [{:keys [entities-by-id
+           entities-by-page-name
+           children-by-page-id
+           uuid-entities
+           linked-refs-by-root-id
+           parents-by-block-id]}]
+  (fn [_ method _ args]
+    (case method
+      :thread-api/pull
+      (let [[_repo _selector target] args]
+        (cond
+          (number? target)
+          (p/resolved (get entities-by-id target))
+
+          (and (vector? target) (= :block/uuid (first target)))
+          (let [uuid-str (some-> (second target) str string/lower-case)]
+            (p/resolved (get uuid-entities uuid-str)))
+
+          (and (vector? target) (= :block/name (first target)))
+          (p/resolved (get entities-by-page-name (second target)))
+
+          :else
+          (p/resolved nil)))
+
+      :thread-api/q
+      (let [[_repo query-args] args
+            [_query & inputs] query-args]
+        (if (= 1 (count inputs))
+          (let [page-id (first inputs)
+                blocks (get children-by-page-id page-id [])]
+            (p/resolved (mapv vector blocks)))
+          (p/resolved [])))
+
+      :thread-api/get-block-refs
+      (let [[_repo root-id] args]
+        (p/resolved (get linked-refs-by-root-id root-id [])))
+
+      :thread-api/get-block-parents
+      (let [[_repo block-id] args]
+        (p/resolved (get parents-by-block-id block-id [])))
+
+      (p/resolved nil))))
+
+(defn- contains-block-uuid?
+  [value]
+  (cond
+    (map? value) (or (contains? value :block/uuid)
+                     (some contains-block-uuid? (vals value)))
+    (sequential? value) (some contains-block-uuid? value)
+    :else false))
+
+(deftest test-truncate-breadcrumb-segment
+  (let [truncate (fn [value]
+                   (call-private 'truncate-breadcrumb-segment value))
+        exact-cjk (apply str (repeat 12 "界"))
+        one-over-cjk (str exact-cjk "界")]
+    (testing "keeps short ASCII segments unchanged"
+      (is (= "Project Alpha"
+             (truncate "Project Alpha"))))
+
+    (testing "keeps exact-width segment unchanged"
+      (is (= "123456789012345678901234"
+             (truncate "123456789012345678901234"))))
+
+    (testing "truncates one-over-width ASCII segment with ellipsis"
+      (is (= "12345678901234567890123…"
+             (truncate "1234567890123456789012345"))))
+
+    (testing "truncates CJK by display width"
+      (is (= exact-cjk
+             (truncate exact-cjk)))
+      (is (= (str (apply str (repeat 11 "界")) "…")
+             (truncate one-over-cjk))))))
+
+(deftest test-ordinary-block-root-classification
+  (let [ordinary-root? (fn [root]
+                         (call-private 'ordinary-block-root? root))]
+    (testing "ordinary block root returns true"
+      (is (true? (ordinary-root? {:db/id 1
+                                  :block/title "Task"
+                                  :block/page {:db/id 10}
+                                  :block/tags [{:db/ident :user.class/Task}]}))))
+
+    (testing "page root returns false"
+      (is (false? (ordinary-root? {:db/id 10
+                                   :db/ident :block/name
+                                   :block/title "Home"}))))
+
+    (testing "property-value pseudo block returns false"
+      (is (false? (ordinary-root? {:db/id 2
+                                   :block/title "Property value"
+                                   :block/page {:db/id 10}
+                                   :logseq.property/created-from-property {:db/id 999}}))))
+
+    (testing "tag/property schema roots return false"
+      (is (false? (ordinary-root? {:db/id 3
+                                   :block/title "Tag schema"
+                                   :block/page {:db/id 10}
+                                   :block/tags [{:db/ident :logseq.class/Tag}]})))
+      (is (false? (ordinary-root? {:db/id 4
+                                   :block/title "Property schema"
+                                   :block/page {:db/id 10}
+                                   :block/tags [{:db/ident :logseq.class/Property}]}))))))
+
+(deftest test-render-breadcrumb-line
+  (let [render-line (fn [parents]
+                      (call-private 'render-breadcrumb-line parents))]
+    (testing "renders parent chain as multi-line tree rows"
+      (is (= (str "100 > Project Alpha\n"
+                  "101   > Milestone 2026\n"
+                  "102     > API rollout")
+             (style/strip-ansi
+              (render-line [{:db/id 100 :block/title "Project Alpha"}
+                            {:db/id 101 :block/title "Milestone 2026"}
+                            {:db/id 102 :block/title "API rollout"}])))))
+
+    (testing "dims breadcrumb id column like normal block ids"
+      (let [output (binding [style/*color-enabled?* true]
+                     (render-line [{:db/id 100 :block/title "Project Alpha"}
+                                   {:db/id 101 :block/title "Milestone 2026"}]))
+            plain-lines (-> output style/strip-ansi string/split-lines)
+            first-column-id (fn [line]
+                              (some-> line
+                                      string/trim
+                                      (string/split #"\s+" 2)
+                                      first))]
+        (is (re-find style/ansi-pattern output))
+        (is (= ["100" "101"]
+               (mapv first-column-id plain-lines)))
+        (is (= (str "100 > Project Alpha\n"
+                    "101   > Milestone 2026")
+               (string/join "\n" plain-lines)))))
+
+    (testing "falls back to db/id when title and name are absent"
+      (is (= "42 > 42"
+             (style/strip-ansi (render-line [{:db/id 42}])))))))
+
+(deftest test-execute-show-human-adds-breadcrumb-for-ordinary-block
+  (async done
+         (let [invoke-mock (make-show-invoke-mock
+                            {:entities-by-id {1 {:db/id 1
+                                                 :block/title "Implement retry policy"
+                                                 :block/page {:db/id 100}}}
+                             :children-by-page-id {100 [{:db/id 2
+                                                         :block/title "Add deterministic retry test"
+                                                         :block/order 0
+                                                         :block/parent {:db/id 1}}]}
+                             :parents-by-block-id {1 [{:db/id 100 :block/title "Project Alpha"}
+                                                      {:db/id 101 :block/title "Milestone 2026"}
+                                                      {:db/id 102 :block/title "API rollout"}]}})]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                               transport/invoke invoke-mock]
+                 (p/let [result (show-command/execute-show {:type :show
+                                                           :repo "demo"
+                                                           :id 1
+                                                           :linked-references? false
+                                                           :ref-id-footer? false}
+                                                          {:output-format nil})
+                         plain (-> result :data :message style/strip-ansi)
+                         lines (string/split-lines plain)]
+                   (is (= :ok (:status result)))
+                   (is (= "100 > Project Alpha"
+                          (first lines)))
+                   (is (= "101   > Milestone 2026"
+                          (second lines)))
+                   (is (= "102     > API rollout"
+                          (nth lines 2)))
+                   (is (string/includes? (nth lines 3) "Implement retry policy"))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-show-human-skips-breadcrumb-for-page-target
+  (async done
+         (let [method-calls (atom [])
+               base-invoke (make-show-invoke-mock
+                            {:entities-by-page-name {"Home" {:db/id 100
+                                                              :db/ident :block/name
+                                                              :block/title "Home"}}
+                             :children-by-page-id {100 [{:db/id 101
+                                                         :block/title "Welcome"
+                                                         :block/order 0
+                                                         :block/parent {:db/id 100}}]}
+                             :parents-by-block-id {100 [{:block/title "Should not be used"}]}})
+               invoke-mock (fn [config method silent? args]
+                             (swap! method-calls conj method)
+                             (base-invoke config method silent? args))
+               task (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                                    transport/invoke invoke-mock]
+                      (p/let [result (show-command/execute-show {:type :show
+                                                                :repo "demo"
+                                                                :page "Home"
+                                                                :linked-references? false
+                                                                :ref-id-footer? false}
+                                                               {:output-format nil})
+                              plain (-> result :data :message style/strip-ansi)
+                              lines (string/split-lines plain)]
+                        (is (= :ok (:status result)))
+                        (is (not (string/includes? (first lines) " > ")))
+                        (is (string/includes? (first lines) "Home"))
+                        (is (not (some #{:thread-api/get-block-parents} @method-calls)))))]
+           (-> task
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-show-human-skips-breadcrumb-for-non-ordinary-block-targets
+  (async done
+         (let [method-calls (atom [])
+               base-invoke (make-show-invoke-mock
+                            {:entities-by-id {2 {:db/id 2
+                                                 :block/title "Tag schema"
+                                                 :block/page {:db/id 100}
+                                                 :block/tags [{:db/ident :logseq.class/Tag}]}
+                                              3 {:db/id 3
+                                                 :block/title "Property value"
+                                                 :block/page {:db/id 100}
+                                                 :logseq.property/created-from-property {:db/id 999}}}
+                             :children-by-page-id {100 []}
+                             :parents-by-block-id {2 [{:block/title "Should not be used"}]
+                                                   3 [{:block/title "Should not be used"}]}})
+               invoke-mock (fn [config method silent? args]
+                             (swap! method-calls conj method)
+                             (base-invoke config method silent? args))
+               task (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                                    transport/invoke invoke-mock]
+                      (p/let [tag-result (show-command/execute-show {:type :show
+                                                                    :repo "demo"
+                                                                    :id 2
+                                                                    :linked-references? false
+                                                                    :ref-id-footer? false}
+                                                                   {:output-format nil})
+                              property-result (show-command/execute-show {:type :show
+                                                                         :repo "demo"
+                                                                         :id 3
+                                                                         :linked-references? false
+                                                                         :ref-id-footer? false}
+                                                                        {:output-format nil})
+                              tag-plain (-> tag-result :data :message style/strip-ansi)
+                              property-plain (-> property-result :data :message style/strip-ansi)]
+                        (is (= :ok (:status tag-result)))
+                        (is (= :ok (:status property-result)))
+                        (is (not (string/includes? (first (string/split-lines tag-plain)) " > ")))
+                        (is (not (string/includes? (first (string/split-lines property-plain)) " > ")))
+                        (is (not (some #{:thread-api/get-block-parents} @method-calls)))))]
+           (-> task
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-show-human-multi-id-renders-breadcrumb-per-ordinary-block
+  (async done
+         (let [invoke-mock (make-show-invoke-mock
+                            {:entities-by-id {1 {:db/id 1
+                                                 :block/title "Root A"
+                                                 :block/page {:db/id 100}}
+                                              2 {:db/id 2
+                                                 :block/title "Root B"
+                                                 :block/page {:db/id 200}}}
+                             :children-by-page-id {100 []
+                                                   200 []}
+                             :parents-by-block-id {1 [{:db/id 100 :block/title "Project Alpha"}
+                                                      {:db/id 101 :block/title "Milestone 2026"}]
+                                                   2 [{:db/id 200 :block/title "Project Beta"}
+                                                      {:db/id 201 :block/title "Initiative Z"}]}})
+               task (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                                    transport/invoke invoke-mock]
+                      (p/let [result (show-command/execute-show {:type :show
+                                                                :repo "demo"
+                                                                :ids [1 2]
+                                                                :multi-id? true
+                                                                :linked-references? false
+                                                                :ref-id-footer? false}
+                                                               {:output-format nil})
+                              plain (-> result :data :message style/strip-ansi)]
+                        (is (= :ok (:status result)))
+                        (is (string/includes? plain (str "100 > Project Alpha\n"
+                                                         "101   > Milestone 2026")))
+                        (is (string/includes? plain (str "200 > Project Beta\n"
+                                                         "201   > Initiative Z")))
+                        (is (< (.indexOf plain "100 > Project Alpha")
+                               (.indexOf plain "Root A")))
+                        (is (< (.indexOf plain "200 > Project Beta")
+                               (.indexOf plain "Root B")))))]
+           (-> task
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-show-fails-when-breadcrumb-fetch-fails
+  (async done
+         (let [invoke-mock (fn [_ method _ args]
+                             (case method
+                               :thread-api/pull
+                               (let [[_repo _selector target] args]
+                                 (cond
+                                   (= target 1)
+                                   (p/resolved {:db/id 1
+                                                :block/title "Root A"
+                                                :block/page {:db/id 100}})
+
+                                   (= target 100)
+                                   (p/resolved {:db/id 100
+                                                :db/ident :block/name
+                                                :block/title "Home"})
+
+                                   :else
+                                   (p/resolved nil)))
+
+                               :thread-api/q
+                               (p/resolved [])
+
+                               :thread-api/get-block-refs
+                               (p/resolved [])
+
+                               :thread-api/get-block-parents
+                               (p/rejected (ex-info "parents query failed"
+                                                    {:code :breadcrumb-fetch-failed}))
+
+                               (p/resolved nil)))]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                               transport/invoke invoke-mock]
+                 (-> (show-command/execute-show {:type :show
+                                                :repo "demo"
+                                                :id 1
+                                                :linked-references? false
+                                                :ref-id-footer? false}
+                                               {:output-format nil})
+                     (p/then (fn [_]
+                               (is false "expected execute-show to reject on breadcrumb fetch failure")))
+                     (p/catch (fn [error]
+                                (is (= :breadcrumb-fetch-failed (-> error ex-data :code)))
+                                (is (string/includes? (or (ex-message error) (str error))
+                                                      "parents query failed"))))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-render-referenced-entities-footer
+  (let [render-footer (fn [ordered-uuids uuid->entity]
+                        (call-private 'render-referenced-entities-footer ordered-uuids uuid->entity))
+        u1 "11111111-1111-1111-1111-111111111111"
+        u2 "22222222-2222-2222-2222-222222222222"
+        u3 "33333333-3333-3333-3333-333333333333"]
+    (testing "returns nil when no refs"
+      (is (nil? (render-footer [] {}))))
+
+    (testing "renders ordered refs with id and label"
+      (is (= (str "Referenced Entities (2)\n"
+                  "181 -> First child\n"
+                  "179 -> Root task")
+             (render-footer [u1 u2]
+                            {(string/lower-case u1) {:id 181 :label "First child"}
+                             (string/lower-case u2) {:id 179 :label "Root task"}}))))
+
+    (testing "renders fallback rows for missing id/label and unresolved refs"
+      (is (= (str "Referenced Entities (3)\n"
+                  "- -> Broken ref\n"
+                  "88 -> " u2 "\n"
+                  "- -> " u3)
+             (render-footer [u1 u2 u3]
+                            {(string/lower-case u1) {:label "Broken ref"}
+                             (string/lower-case u2) {:id 88}}))))))
+
+(deftest test-render-referenced-entities-footer-formats-large-count
+  (let [render-footer (fn [ordered-uuids uuid->entity]
+                        (call-private 'render-referenced-entities-footer ordered-uuids uuid->entity))
+        ordered-uuids (mapv (fn [idx]
+                              (str "uuid-" idx))
+                            (range 1234))
+        uuid->entity {}
+        output (render-footer ordered-uuids uuid->entity)]
+    (is (string/includes? output "Referenced Entities (1,234)"))))
+
+(deftest test-build-action-ref-id-footer
+  (testing "ref-id-footer defaults to true"
+    (let [result (show-command/build-action {:id "42"}
+                                            "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (true? (get-in result [:action :ref-id-footer?])))))
+
+  (testing "ref-id-footer false is threaded into action"
+    (let [result (show-command/build-action {:id "42"
+                                             :ref-id-footer false}
+                                            "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (false? (get-in result [:action :ref-id-footer?]))))))
+
+(deftest test-execute-show-human-ref-id-footer-default-enabled
+  (async done
+         (let [resolved-uuid "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+               missing-uuid "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
+               invoke-mock (make-show-invoke-mock
+                            {:entities-by-id {1 {:db/id 1
+                                                 :block/title (str "Root [[" resolved-uuid "]] [[" missing-uuid "]]")
+                                                 :block/page {:db/id 100}}}
+                             :children-by-page-id {100 [{:db/id 2
+                                                         :block/title "Child"
+                                                         :block/order 0
+                                                         :block/parent {:db/id 1}}]}
+                             :uuid-entities {(string/lower-case resolved-uuid)
+                                             {:db/id 179
+                                              :block/uuid (uuid resolved-uuid)
+                                              :block/title "Root task"}}})]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                               transport/invoke invoke-mock]
+                 (p/let [result (show-command/execute-show {:type :show
+                                                           :repo "demo"
+                                                           :id 1
+                                                           :linked-references? false}
+                                                          {:output-format nil})
+                         plain (-> result :data :message style/strip-ansi)]
+                   (is (= :ok (:status result)))
+                   (is (string/includes? plain "Referenced Entities (2)"))
+                   (is (string/includes? plain "179 -> Root task"))
+                   (is (string/includes? plain (str "- -> " missing-uuid)))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-show-human-ref-id-footer-multi-id
+  (async done
+         (let [uuid-a "cccccccc-cccc-cccc-cccc-cccccccccccc"
+               uuid-b "dddddddd-dddd-dddd-dddd-dddddddddddd"
+               invoke-mock (make-show-invoke-mock
+                            {:entities-by-id {1 {:db/id 1
+                                                 :block/title "Root A"
+                                                 :block/page {:db/id 101}}
+                                              2 {:db/id 2
+                                                 :block/title "Root B"
+                                                 :block/page {:db/id 102}}}
+                             :children-by-page-id {101 [{:db/id 11
+                                                         :block/title (str "Child A [[" uuid-a "]]")
+                                                         :block/order 0
+                                                         :block/parent {:db/id 1}}]
+                                                   102 [{:db/id 22
+                                                         :block/title (str "Child B [[" uuid-b "]]")
+                                                         :block/order 0
+                                                         :block/parent {:db/id 2}}]}
+                             :uuid-entities {(string/lower-case uuid-a)
+                                             {:db/id 501
+                                              :block/uuid (uuid uuid-a)
+                                              :block/title "Ref A"}
+                                             (string/lower-case uuid-b)
+                                             {:db/id 502
+                                              :block/uuid (uuid uuid-b)
+                                              :block/title "Ref B"}}})]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                               transport/invoke invoke-mock]
+                 (p/let [result (show-command/execute-show {:type :show
+                                                           :repo "demo"
+                                                           :ids [1 2]
+                                                           :multi-id? true
+                                                           :linked-references? false}
+                                                          {:output-format nil})
+                         plain (-> result :data :message style/strip-ansi)
+                         footer-count (count (re-seq #"Referenced Entities \(1\)" plain))]
+                   (is (= :ok (:status result)))
+                   (is (= 2 footer-count))
+                   (is (string/includes? plain "501 -> Ref A"))
+                   (is (string/includes? plain "502 -> Ref B"))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-show-human-ref-id-footer-disabled
+  (async done
+         (let [uuid-a "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee"
+               invoke-mock (make-show-invoke-mock
+                            {:entities-by-id {1 {:db/id 1
+                                                 :block/title "Root"
+                                                 :block/page {:db/id 201}}}
+                             :children-by-page-id {201 [{:db/id 12
+                                                         :block/title (str "Child [[" uuid-a "]]" )
+                                                         :block/order 0
+                                                         :block/parent {:db/id 1}}]}
+                             :uuid-entities {(string/lower-case uuid-a)
+                                             {:db/id 601
+                                              :block/uuid (uuid uuid-a)
+                                              :block/title "Ref A"}}})]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                               transport/invoke invoke-mock]
+                 (p/let [result (show-command/execute-show {:type :show
+                                                           :repo "demo"
+                                                           :id 1
+                                                           :linked-references? false
+                                                           :ref-id-footer? false}
+                                                          {:output-format nil})
+                         plain (-> result :data :message style/strip-ansi)]
+                   (is (= :ok (:status result)))
+                   (is (not (string/includes? plain "Referenced Entities (")))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-show-structured-output-single-and-multi-id
+  (async done
+         (let [invoke-mock (make-show-invoke-mock
+                            {:entities-by-id {1 {:db/id 1
+                                                 :block/uuid (uuid "11111111-1111-1111-1111-111111111111")
+                                                 :block/title "Root A"
+                                                 :block/page {:db/id 101}}
+                                              2 {:db/id 2
+                                                 :block/uuid (uuid "22222222-2222-2222-2222-222222222222")
+                                                 :block/title "Root B"
+                                                 :block/page {:db/id 102}}}
+                             :children-by-page-id {101 [{:db/id 11
+                                                         :block/uuid (uuid "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
+                                                         :block/title "Child A"
+                                                         :block/order 0
+                                                         :block/parent {:db/id 1}}]
+                                                   102 [{:db/id 22
+                                                         :block/uuid (uuid "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb")
+                                                         :block/title "Child B"
+                                                         :block/order 0
+                                                         :block/parent {:db/id 2}}]}})]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                               transport/invoke invoke-mock]
+                 (p/let [single-json (show-command/execute-show {:type :show
+                                                                :repo "demo"
+                                                                :id 1
+                                                                :linked-references? false}
+                                                               {:output-format :json})
+                         single-edn (show-command/execute-show {:type :show
+                                                               :repo "demo"
+                                                               :id 1
+                                                               :linked-references? false}
+                                                              {:output-format :edn})
+                         multi-json (show-command/execute-show {:type :show
+                                                               :repo "demo"
+                                                               :ids [1 2]
+                                                               :multi-id? true
+                                                               :linked-references? false}
+                                                              {:output-format :json})
+                         multi-edn (show-command/execute-show {:type :show
+                                                              :repo "demo"
+                                                              :ids [1 2]
+                                                              :multi-id? true
+                                                              :linked-references? false}
+                                                             {:output-format :edn})]
+                   (doseq [result [single-json single-edn multi-json multi-edn]]
+                     (is (= :ok (:status result)))
+                     (is (not (contains-block-uuid? (:data result)))))
+
+                   (is (= :json (:output-format single-json)))
+                   (is (= :edn (:output-format single-edn)))
+                   (is (= 1 (get-in single-json [:data :root :db/id])))
+                   (is (= 1 (get-in single-edn [:data :root :db/id])))
+
+                   (is (= :json (:output-format multi-json)))
+                   (is (= :edn (:output-format multi-edn)))
+                   (is (= [1 2]
+                          (mapv #(get-in % [:root :db/id]) (:data multi-json))))
+                   (is (= [1 2]
+                          (mapv #(get-in % [:root :db/id]) (:data multi-edn))))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
diff --git a/src/test/logseq/cli/command/skill_test.cljs b/src/test/logseq/cli/command/skill_test.cljs
new file mode 100644
index 0000000000..3ae07ab354
--- /dev/null
+++ b/src/test/logseq/cli/command/skill_test.cljs
@@ -0,0 +1,185 @@
+(ns logseq.cli.command.skill-test
+  (:require ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]
+            [cljs.test :refer [deftest is testing]]
+            [clojure.string :as string]
+            [logseq.cli.command.skill :as skill-command]
+            [logseq.common.path :as path]))
+
+(deftest test-skill-command-entries
+  (let [entries skill-command/entries
+        by-cmds (group-by :cmds entries)]
+    (testing "registers skill show and skill install entries"
+      (is (= 2 (count entries)))
+      (is (= :skill-show (:command (first (get by-cmds ["skill" "show"])))))
+      (is (= :skill-install (:command (first (get by-cmds ["skill" "install"])))))
+      (is (contains? (get-in (first (get by-cmds ["skill" "install"])) [:spec]) :global)))))
+
+(deftest test-resolve-install-target
+  (testing "resolves local install path under cwd"
+    (let [result (skill-command/resolve-install-target {:global? false
+                                                        :cwd "/tmp/work"
+                                                        :home-dir "/Users/demo"})]
+      (is (true? (:ok? result)))
+      (is (= "/tmp/work/.agents/skills/logseq-cli" (:dir result)))
+      (is (= "/tmp/work/.agents/skills/logseq-cli/SKILL.md" (:file result)))))
+
+  (testing "resolves global install path under home dir"
+    (let [result (skill-command/resolve-install-target {:global? true
+                                                        :cwd "/tmp/work"
+                                                        :home-dir "/Users/demo"})]
+      (is (true? (:ok? result)))
+      (is (= "/Users/demo/.agents/skills/logseq-cli" (:dir result)))
+      (is (= "/Users/demo/.agents/skills/logseq-cli/SKILL.md" (:file result)))))
+
+  (testing "returns typed error when home dir is missing for global install"
+    (let [result (skill-command/resolve-install-target {:global? true
+                                                        :cwd "/tmp/work"
+                                                        :home-dir ""})]
+      (is (false? (:ok? result)))
+      (is (= :skill-home-dir-unavailable (get-in result [:error :code]))))))
+
+(deftest test-resolve-skill-source-path
+  (let [exists-sync (.-existsSync fs)]
+    (testing "picks first existing candidate path"
+      (set! (.-existsSync fs)
+            (fn [path]
+              (= path "/opt/logseq/.agents/skills/logseq-cli/SKILL.md")))
+      (try
+        (let [result (skill-command/resolve-skill-source-path
+                      ["/opt/logseq/.agents/skills/logseq-cli/SKILL.md"
+                       "/fallback/.agents/skills/logseq-cli/SKILL.md"])]
+          (is (true? (:ok? result)))
+          (is (= "/opt/logseq/.agents/skills/logseq-cli/SKILL.md" (:path result))))
+        (finally
+          (set! (.-existsSync fs) exists-sync))))
+
+    (testing "returns typed error when no candidates exist"
+      (set! (.-existsSync fs) (fn [_] false))
+      (try
+        (let [result (skill-command/resolve-skill-source-path
+                      ["/missing/a.md" "/missing/b.md"])]
+          (is (false? (:ok? result)))
+          (is (= :skill-source-not-found (get-in result [:error :code])))
+          (is (string/includes? (get-in result [:error :message]) "/missing/a.md"))
+          (is (string/includes? (get-in result [:error :message]) "/missing/b.md")))
+        (finally
+          (set! (.-existsSync fs) exists-sync))))))
+
+(deftest test-execute-skill-show
+  (let [read-file-sync (.-readFileSync fs)]
+    (set! (.-readFileSync fs)
+          (fn [path encoding]
+            (is (= "/tmp/skill/SKILL.md" path))
+            (is (= "utf8" encoding))
+            "# skill\ncontent"))
+    (try
+      (let [result (skill-command/execute-skill-show {:type :skill-show
+                                                      :source-path "/tmp/skill/SKILL.md"}
+                                                     {})]
+        (is (= :ok (:status result)))
+        (is (= :human (:output-format result)))
+        (is (= "# skill\ncontent" (get-in result [:data :message]))))
+      (finally
+        (set! (.-readFileSync fs) read-file-sync)))))
+
+(deftest test-execute-skill-install
+  (let [mkdir-sync (.-mkdirSync fs)
+        write-file-sync (.-writeFileSync fs)
+        read-file-sync (.-readFileSync fs)
+        captured (atom [])]
+    (set! (.-mkdirSync fs)
+          (fn [path opts]
+            (swap! captured conj [:mkdir path (js->clj opts :keywordize-keys true)])))
+    (set! (.-readFileSync fs)
+          (fn [path encoding]
+            (swap! captured conj [:read path encoding])
+            "# skill\nfrom source"))
+    (set! (.-writeFileSync fs)
+          (fn [path payload encoding]
+            (swap! captured conj [:write path payload encoding])))
+    (try
+      (let [result (skill-command/execute-skill-install {:type :skill-install
+                                                         :source-path "/opt/logseq/.agents/skills/logseq-cli/SKILL.md"
+                                                         :destination-dir "/tmp/work/.agents/skills/logseq-cli"
+                                                         :destination-file "/tmp/work/.agents/skills/logseq-cli/SKILL.md"
+                                                         :global? false}
+                                                        {})]
+        (is (= :ok (:status result)))
+        (is (= "/tmp/work/.agents/skills/logseq-cli/SKILL.md" (get-in result [:data :installed-path])))
+        (is (= "/opt/logseq/.agents/skills/logseq-cli/SKILL.md" (get-in result [:data :source-path])))
+        (is (= [[:mkdir "/tmp/work/.agents/skills/logseq-cli" {:recursive true}]
+                [:read "/opt/logseq/.agents/skills/logseq-cli/SKILL.md" "utf8"]
+                [:write "/tmp/work/.agents/skills/logseq-cli/SKILL.md" "# skill\nfrom source" "utf8"]]
+               @captured)))
+      (finally
+        (set! (.-mkdirSync fs) mkdir-sync)
+        (set! (.-readFileSync fs) read-file-sync)
+        (set! (.-writeFileSync fs) write-file-sync)))))
+
+(deftest test-execute-skill-install-preserves-other-skills
+  (let [tmp-root (.mkdtempSync fs (node-path/join (.tmpdir os) "logseq-skill-test-"))
+        source-path (node-path/join tmp-root "source-skill.md")
+        destination-dir (node-path/join tmp-root ".agents" "skills" "logseq-cli")
+        destination-file (node-path/join destination-dir "SKILL.md")
+        existing-file (node-path/join tmp-root ".agents" "skills" "existing-skill" "SKILL.md")]
+    (try
+      (fs/mkdirSync (node-path/join tmp-root ".agents" "skills" "existing-skill") #js {:recursive true})
+      (fs/writeFileSync source-path "# installed\ncontent" "utf8")
+      (fs/writeFileSync existing-file "keep me" "utf8")
+      (let [result (skill-command/execute-skill-install {:type :skill-install
+                                                         :source-path source-path
+                                                         :destination-dir destination-dir
+                                                         :destination-file destination-file
+                                                         :global? false}
+                                                        {})]
+        (is (= :ok (:status result)))
+        (is (= "# installed\ncontent" (fs/readFileSync destination-file "utf8")))
+        (is (= "keep me" (fs/readFileSync existing-file "utf8"))))
+      (finally
+        (fs/rmSync tmp-root #js {:recursive true :force true})))))
+
+(deftest test-execute-skill-install-global-prefers-home-env
+  (let [tmp-root (.mkdtempSync fs (node-path/join (.tmpdir os) "logseq-skill-home-"))
+        source-path (node-path/join tmp-root "source-skill.md")
+        installed-file (path/path-join tmp-root ".agents" "skills" "logseq-cli" "SKILL.md")
+        previous-home (.. js/process -env -HOME)]
+    (try
+      (fs/writeFileSync source-path "# installed\ncontent" "utf8")
+      (set! (.. js/process -env -HOME) tmp-root)
+      (let [result (skill-command/execute-skill-install {:type :skill-install
+                                                         :source-path source-path
+                                                         :global? true}
+                                                        {})]
+        (is (= :ok (:status result)))
+        (is (= installed-file (get-in result [:data :installed-path])))
+        (is (= "# installed\ncontent" (fs/readFileSync installed-file "utf8"))))
+      (finally
+        (if (some? previous-home)
+          (set! (.. js/process -env -HOME) previous-home)
+          (js-delete (.-env js/process) "HOME"))
+        (fs/rmSync tmp-root #js {:recursive true :force true})))))
+
+(deftest test-execute-skill-install-write-error
+  (let [mkdir-sync (.-mkdirSync fs)
+        write-file-sync (.-writeFileSync fs)
+        read-file-sync (.-readFileSync fs)]
+    (set! (.-mkdirSync fs) (fn [_ _] nil))
+    (set! (.-readFileSync fs) (fn [_ _] "# skill"))
+    (set! (.-writeFileSync fs)
+          (fn [_ _ _]
+            (throw (ex-info "write failed" {:code "EACCES"}))))
+    (try
+      (let [result (skill-command/execute-skill-install {:type :skill-install
+                                                         :source-path "/opt/logseq/.agents/skills/logseq-cli/SKILL.md"
+                                                         :destination-dir "/tmp/work/.agents/skills/logseq-cli"
+                                                         :destination-file "/tmp/work/.agents/skills/logseq-cli/SKILL.md"
+                                                         :global? false}
+                                                        {})]
+        (is (= :error (:status result)))
+        (is (= :skill-install-failed (get-in result [:error :code]))))
+      (finally
+        (set! (.-mkdirSync fs) mkdir-sync)
+        (set! (.-readFileSync fs) read-file-sync)
+        (set! (.-writeFileSync fs) write-file-sync)))))
diff --git a/src/test/logseq/cli/command/sync_test.cljs b/src/test/logseq/cli/command/sync_test.cljs
new file mode 100644
index 0000000000..ead623fc16
--- /dev/null
+++ b/src/test/logseq/cli/command/sync_test.cljs
@@ -0,0 +1,1412 @@
+(ns logseq.cli.command.sync-test
+  (:require [cljs.test :refer [async deftest is testing]]
+            [logseq.cli.auth :as cli-auth]
+            [logseq.cli.command.sync :as sync-command]
+            [logseq.cli.common :as cli-common]
+            [logseq.cli.config :as cli-config]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [promesa.core :as p]))
+
+(defn- execute-with-runtime-auth
+  [action config]
+  (sync-command/execute action (assoc config :id-token "runtime-token")))
+
+(deftest test-build-action-validation
+  (testing "sync status requires repo"
+    (let [result (sync-command/build-action :sync-status {} [] nil)]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+  (testing "sync download requires repo"
+    (let [result (sync-command/build-action :sync-download {} [] nil)]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+  (testing "sync download action requires missing local graph"
+    (let [result (sync-command/build-action :sync-download {} [] "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (true? (get-in result [:action :allow-missing-graph])))
+      (is (true? (get-in result [:action :require-missing-graph])))))
+
+  (testing "sync download action keeps progress option and explicit flag"
+    (let [default-result (sync-command/build-action :sync-download {} [] "logseq_db_demo")
+          explicit-result (sync-command/build-action :sync-download {:progress false} [] "logseq_db_demo")]
+      (is (true? (:ok? default-result)))
+      (is (= false (get-in default-result [:action :progress-explicit?])))
+      (is (true? (:ok? explicit-result)))
+      (is (= false (get-in explicit-result [:action :progress])))
+      (is (= true (get-in explicit-result [:action :progress-explicit?])))))
+
+  (testing "sync config set requires name and value"
+    (let [missing-both (sync-command/build-action :sync-config-set {} [] nil)
+          missing-value (sync-command/build-action :sync-config-set {} ["ws-url"] nil)]
+      (is (false? (:ok? missing-both)))
+      (is (= :invalid-options (get-in missing-both [:error :code])))
+      (is (false? (:ok? missing-value)))
+      (is (= :invalid-options (get-in missing-value [:error :code])))))
+
+  (testing "sync config rejects auth-token key"
+    (let [set-result (sync-command/build-action :sync-config-set {} ["auth-token" "secret"] nil)
+          get-result (sync-command/build-action :sync-config-get {} ["auth-token"] nil)
+          unset-result (sync-command/build-action :sync-config-unset {} ["auth-token"] nil)]
+      (is (false? (:ok? set-result)))
+      (is (= :invalid-options (get-in set-result [:error :code])))
+      (is (false? (:ok? get-result)))
+      (is (= :invalid-options (get-in get-result [:error :code])))
+      (is (false? (:ok? unset-result)))
+      (is (= :invalid-options (get-in unset-result [:error :code])))))
+
+  (testing "sync config rejects e2ee-password key"
+    (let [set-result (sync-command/build-action :sync-config-set {} ["e2ee-password" "pw"] nil)
+          get-result (sync-command/build-action :sync-config-get {} ["e2ee-password"] nil)
+          unset-result (sync-command/build-action :sync-config-unset {} ["e2ee-password"] nil)]
+      (is (false? (:ok? set-result)))
+      (is (= :invalid-options (get-in set-result [:error :code])))
+      (is (false? (:ok? get-result)))
+      (is (= :invalid-options (get-in get-result [:error :code])))
+      (is (false? (:ok? unset-result)))
+      (is (= :invalid-options (get-in unset-result [:error :code])))))
+
+  (testing "sync start, upload, download and ensure-keys actions carry e2ee-password option"
+    (let [start-result (sync-command/build-action :sync-start {:e2ee-password "pw"} [] "logseq_db_demo")
+          upload-result (sync-command/build-action :sync-upload {:e2ee-password "pw"} [] "logseq_db_demo")
+          download-result (sync-command/build-action :sync-download {:e2ee-password "pw"} [] "logseq_db_demo")
+          ensure-keys-result (sync-command/build-action :sync-ensure-keys {:e2ee-password "pw"
+                                                                            :upload-keys true} [] nil)]
+      (is (true? (:ok? start-result)))
+      (is (= "pw" (get-in start-result [:action :e2ee-password])))
+      (is (true? (:ok? upload-result)))
+      (is (= "pw" (get-in upload-result [:action :e2ee-password])))
+      (is (true? (:ok? download-result)))
+      (is (= "pw" (get-in download-result [:action :e2ee-password])))
+      (is (true? (:ok? ensure-keys-result)))
+      (is (= "pw" (get-in ensure-keys-result [:action :e2ee-password])))
+      (is (= true (get-in ensure-keys-result [:action :upload-keys])))))
+
+  (testing "sync grant-access requires graph-id and email"
+    (let [missing-graph-id (sync-command/build-action :sync-grant-access {:email "user@example.com"} [] "logseq_db_demo")
+          missing-email (sync-command/build-action :sync-grant-access {:graph-id "123"} [] "logseq_db_demo")]
+      (is (false? (:ok? missing-graph-id)))
+      (is (= :invalid-options (get-in missing-graph-id [:error :code])))
+      (is (false? (:ok? missing-email)))
+      (is (= :invalid-options (get-in missing-email [:error :code]))))))
+
+(deftest test-execute-sync-start
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])
+               status-calls (atom 0)]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/db-sync-status
+                                                    (let [idx (swap! status-calls inc)]
+                                                      (p/resolved {:repo "logseq_db_demo"
+                                                                   :ws-state (if (= idx 1) :connecting :open)
+                                                                   :pending-local 0
+                                                                   :pending-asset 0
+                                                                   :pending-server 0}))
+                                                    (p/resolved {:ok true})))]
+                 (p/let [result (execute-with-runtime-auth {:type :sync-start
+                                                       :repo "logseq_db_demo"}
+                                                      {:root-dir "/tmp"})
+                         invoked-methods (map first @invoke-calls)]
+                   (is (= :ok (:status result)))
+                   (is (= :open (get-in result [:data :ws-state])))
+                   (is (<= 1 (count @ensure-calls)))
+                   (is (every? (fn [[_ repo]] (= "logseq_db_demo" repo)) @ensure-calls))
+                   (is (= 1 (count (filter #(= :thread-api/db-sync-start %) invoked-methods))))
+                   (is (<= 2 (count (filter #(= :thread-api/db-sync-status %) invoked-methods))))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-start-uses-default-ws-url-when-config-missing
+  (async done
+         (let [invoke-calls (atom [])
+               worker-sync-config (atom {:ws-url nil})]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/set-db-sync-config
+                                                    (let [cfg (first args)]
+                                                      (reset! worker-sync-config cfg)
+                                                      (p/resolved nil))
+
+                                                    :thread-api/db-sync-start
+                                                    (p/resolved nil)
+
+                                                    :thread-api/db-sync-status
+                                                    (p/resolved {:repo "logseq_db_demo"
+                                                                 :ws-state (if (seq (:ws-url @worker-sync-config)) :open :stopped)
+                                                                 :pending-local 0
+                                                                 :pending-asset 0
+                                                                 :pending-server 0})
+
+                                                    (p/resolved {:ok true})))]
+                 (p/let [result (execute-with-runtime-auth {:type :sync-start
+                                                            :repo "logseq_db_demo"
+                                                            :wait-timeout-ms 20
+                                                            :wait-poll-interval-ms 0}
+                                                           {:root-dir "/tmp"})
+                         set-config-calls (filter #(= :thread-api/set-db-sync-config (first %)) @invoke-calls)]
+                   (is (= :ok (:status result)))
+                   (is (seq set-config-calls))
+                   (is (every? #(= "wss://api.logseq.io/sync/%s"
+                                   (get-in % [2 0 :ws-url]))
+                               set-config-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-start-verifies-and-persists-e2ee-password-when-provided
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/get-db-sync-config (p/resolved {:auth-token "worker-token"})
+                                                    :thread-api/q (p/resolved true)
+                                                    :thread-api/verify-and-save-e2ee-password (p/resolved nil)
+                                                    :thread-api/db-sync-status (p/resolved {:repo "logseq_db_demo"
+                                                                                            :ws-state :open
+                                                                                            :pending-local 0
+                                                                                            :pending-asset 0
+                                                                                            :pending-server 0})
+                                                    (p/resolved {:ok true})))]
+                 (p/let [result (sync-command/execute {:type :sync-start
+                                                       :repo "logseq_db_demo"
+                                                       :e2ee-password "pw"
+                                                       :wait-timeout-ms 50
+                                                       :wait-poll-interval-ms 0}
+                                                      {:root-dir "/tmp"
+                                                       :refresh-token "refresh-token"
+                                                       :id-token "runtime-token"})]
+                   (is (= :ok (:status result)))
+                   (is (some #(= [:thread-api/verify-and-save-e2ee-password false ["refresh-token" "pw"]]
+                                 %)
+                             @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-start-timeout
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/db-sync-status
+                                                    (p/resolved {:repo "logseq_db_demo"
+                                                                 :ws-state :connecting
+                                                                 :pending-local 0
+                                                                 :pending-asset 0
+                                                                 :pending-server 0})
+                                                    (p/resolved {:ok true})))]
+                 (p/let [result (execute-with-runtime-auth {:type :sync-start
+                                                       :repo "logseq_db_demo"
+                                                       :wait-timeout-ms 20
+                                                       :wait-poll-interval-ms 0}
+                                                      {:root-dir "/tmp"})]
+                   (is (= :error (:status result)))
+                   (is (= :sync-start-timeout (get-in result [:error :code])))
+                   (is (= "logseq_db_demo" (get-in result [:error :repo])))
+                   (is (= :connecting (get-in result [:error :ws-state])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-start-retries-transient-stopped-state
+  (async done
+         (let [status-calls (atom 0)
+               start-calls (atom 0)]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method _direct-pass? _args]
+                                                  (case method
+                                                    :thread-api/db-sync-start
+                                                    (do
+                                                      (swap! start-calls inc)
+                                                      (p/resolved nil))
+
+                                                    :thread-api/db-sync-status
+                                                    (let [idx (swap! status-calls inc)]
+                                                      (p/resolved (if (= idx 1)
+                                                                    {:repo "logseq_db_demo"
+                                                                     :graph-id "graph-uuid"
+                                                                     :ws-state :stopped
+                                                                     :pending-local 0
+                                                                     :pending-asset 0
+                                                                     :pending-server 0}
+                                                                    {:repo "logseq_db_demo"
+                                                                     :graph-id "graph-uuid"
+                                                                     :ws-state :open
+                                                                     :pending-local 0
+                                                                     :pending-asset 0
+                                                                     :pending-server 0})))
+                                                    (p/resolved {:ok true})))]
+                 (p/let [result (execute-with-runtime-auth {:type :sync-start
+                                                            :repo "logseq_db_demo"
+                                                            :wait-timeout-ms 200
+                                                            :wait-poll-interval-ms 0}
+                                                           {:root-dir "/tmp"})]
+                   (is (= :ok (:status result)))
+                   (is (= :open (get-in result [:data :ws-state])))
+                   (is (= 2 @status-calls))
+                   (is (= 2 @start-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-start-missing-ws-url-is-error
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [result (sync-command/execute {:type :sync-start
+                                                       :repo "logseq_db_demo"}
+                                                      {:root-dir "/tmp"
+                                                       :ws-url ""
+                                                       :id-token "runtime-token"})]
+                   (is (= :error (:status result)))
+                   (is (= :missing-sync-config (get-in result [:error :code])))
+                   (is (= :sync-start (get-in result [:error :action])))
+                   (is (= [:ws-url] (get-in result [:error :missing-keys])))
+                   (is (= [] @ensure-calls))
+                   (is (= [] @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-upload-missing-http-base-is-error
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [result (sync-command/execute {:type :sync-upload
+                                                       :repo "logseq_db_demo"}
+                                                      {:root-dir "/tmp"
+                                                       :http-base ""
+                                                       :id-token "runtime-token"})]
+                   (is (= :error (:status result)))
+                   (is (= :missing-sync-config (get-in result [:error :code])))
+                   (is (= :sync-upload (get-in result [:error :action])))
+                   (is (= [:http-base] (get-in result [:error :missing-keys])))
+                   (is (= [] @ensure-calls))
+                   (is (= [] @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-missing-http-base-is-error
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved []))]
+                 (p/let [result (sync-command/execute {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :http-base ""
+                                                       :id-token "runtime-token"})]
+                   (is (= :error (:status result)))
+                   (is (= :missing-sync-config (get-in result [:error :code])))
+                   (is (= :sync-download (get-in result [:error :action])))
+                   (is (= [:http-base] (get-in result [:error :missing-keys])))
+                   (is (= [] @ensure-calls))
+                   (is (= [] @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-missing-e2ee-password-for-e2ee-graph-is-error
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])
+               stop-calls (atom [])
+               unlink-calls (atom [])
+               list-graphs-calls (atom 0)]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_config]
+                                                        (let [idx (swap! list-graphs-calls inc)]
+                                                          (if (= idx 1)
+                                                            []
+                                                            ["demo"])))
+                               cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               cli-server/stop-server! (fn [config repo]
+                                                         (swap! stop-calls conj [config repo])
+                                                         (p/resolved {:ok? true}))
+                               cli-common/unlink-graph! (fn [& args]
+                                                          (swap! unlink-calls conj args)
+                                                          "/tmp/unlinked-demo")
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/set-db-sync-config
+                                                    (p/resolved nil)
+
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "remote-graph-id"
+                                                                  :graph-name "demo"
+                                                                  :graph-e2ee? true}])
+
+                                                    :thread-api/get-e2ee-password
+                                                    (p/rejected (ex-info "missing-e2ee-password"
+                                                                         {:code :db-sync/missing-e2ee-password
+                                                                          :field :e2ee-password}))
+
+                                                    :thread-api/db-sync-download-graph-by-id
+                                                    (p/resolved {:ok true})
+
+                                                    (p/resolved nil)))]
+                 (p/let [result (sync-command/execute {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :http-base "https://api.logseq.io"
+                                                       :id-token "runtime-token"
+                                                       :refresh-token "refresh-token"})]
+                   (is (= :error (:status result)))
+                   (is (= :e2ee-password-not-found (get-in result [:error :code])))
+                   (is (= "logseq_db_demo" (get-in result [:error :repo])))
+                   (is (= ["logseq_db_demo"] (mapv second @stop-calls)))
+                   (is (= ["logseq_db_demo"] (mapv last @unlink-calls)))
+                   (is (not-any? (fn [[method _ _]]
+                                   (= :thread-api/db-sync-download-graph-by-id method))
+                                 @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-preserves-e2ee-error-when-cleanup-fails
+  (async done
+         (let [stop-calls (atom [])
+               unlink-calls (atom [])]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_config]
+                                                        [])
+                               cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               cli-server/stop-server! (fn [config repo]
+                                                         (swap! stop-calls conj [config repo])
+                                                         (p/rejected (ex-info "stop failed"
+                                                                              {:code :stop-failed})))
+                               cli-common/unlink-graph! (fn [& args]
+                                                          (swap! unlink-calls conj args)
+                                                          "/tmp/unlinked-demo")
+                               transport/invoke (fn [_ method _direct-pass? _args]
+                                                  (case method
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "remote-graph-id"
+                                                                  :graph-name "demo"
+                                                                  :graph-e2ee? true}])
+
+                                                    :thread-api/get-e2ee-password
+                                                    (p/rejected (ex-info "missing-e2ee-password"
+                                                                         {:code :db-sync/missing-e2ee-password}))
+
+                                                    :thread-api/db-sync-download-graph-by-id
+                                                    (p/resolved {:ok true})
+
+                                                    (p/resolved nil)))]
+                 (p/let [result (sync-command/execute {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :http-base "https://api.logseq.io"
+                                                       :id-token "runtime-token"
+                                                       :refresh-token "refresh-token"})]
+                   (is (= :error (:status result)))
+                   (is (= :e2ee-password-not-found (get-in result [:error :code])))
+                   (is (= ["logseq_db_demo"] (mapv second @stop-calls)))
+                   (is (= [] @unlink-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-uses-persisted-e2ee-password-when-option-missing
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_config]
+                                                        [])
+                               cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "remote-graph-id"
+                                                                  :graph-name "demo"
+                                                                  :graph-e2ee? true}])
+                                                    :thread-api/get-e2ee-password
+                                                    (p/resolved "persisted-password")
+                                                    :thread-api/q
+                                                    (p/resolved 0)
+                                                    :thread-api/db-sync-download-graph-by-id
+                                                    (p/resolved {:graph-id "remote-graph-id"
+                                                                 :remote-tx 22})
+                                                    (p/resolved nil)))]
+                 (p/let [result (sync-command/execute {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :http-base "https://api.logseq.io"
+                                                       :id-token "runtime-token"
+                                                       :refresh-token "refresh-token"})]
+                   (is (= :ok (:status result)))
+                   (is (= "remote-graph-id" (get-in result [:data :graph-id])))
+                   (is (some #(= [:thread-api/get-e2ee-password false ["refresh-token"]]
+                                 %)
+                             @invoke-calls))
+                   (is (not-any? #(= :thread-api/verify-and-save-e2ee-password (first %))
+                                 @invoke-calls))
+                   (is (some #(= [:thread-api/db-sync-download-graph-by-id false ["logseq_db_demo" "remote-graph-id" true]]
+                                 %)
+                             @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-skips-cleanup-for-preexisting-graph
+  (async done
+         (let [stop-calls (atom [])
+               unlink-calls (atom [])]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_config]
+                                                        ["demo"])
+                               cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               cli-server/stop-server! (fn [config repo]
+                                                         (swap! stop-calls conj [config repo])
+                                                         (p/resolved {:ok? true}))
+                               cli-common/unlink-graph! (fn [& args]
+                                                          (swap! unlink-calls conj args)
+                                                          "/tmp/unlinked-demo")
+                               transport/invoke (fn [_ method _direct-pass? _args]
+                                                  (case method
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "remote-graph-id"
+                                                                  :graph-name "demo"
+                                                                  :graph-e2ee? true}])
+
+                                                    :thread-api/get-e2ee-password
+                                                    (p/rejected (ex-info "missing-e2ee-password"
+                                                                         {:code :db-sync/missing-e2ee-password}))
+
+                                                    (p/resolved nil)))]
+                 (p/let [result (sync-command/execute {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :http-base "https://api.logseq.io"
+                                                       :id-token "runtime-token"
+                                                       :refresh-token "refresh-token"})]
+                   (is (= :error (:status result)))
+                   (is (= :e2ee-password-not-found (get-in result [:error :code])))
+                   (is (= [] @stop-calls))
+                   (is (= [] @unlink-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-start-runtime-error-after-open
+  (async done
+         (let [status-calls (atom 0)]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method _direct-pass? _args]
+                                                  (case method
+                                                    :thread-api/db-sync-status
+                                                    (let [idx (swap! status-calls inc)]
+                                                      (p/resolved (if (= idx 1)
+                                                                    {:repo "logseq_db_demo"
+                                                                     :ws-state :connecting
+                                                                     :pending-local 0
+                                                                     :pending-asset 0
+                                                                     :pending-server 0}
+                                                                    {:repo "logseq_db_demo"
+                                                                     :ws-state :open
+                                                                     :pending-local 1
+                                                                     :pending-asset 0
+                                                                     :pending-server 2
+                                                                     :last-error {:code :decrypt-aes-key
+                                                                                  :message "decrypt-aes-key"}})))
+                                                    (p/resolved {:ok true})))]
+                 (p/let [result (execute-with-runtime-auth {:type :sync-start
+                                                       :repo "logseq_db_demo"
+                                                       :wait-timeout-ms 200
+                                                       :wait-poll-interval-ms 0}
+                                                      {:root-dir "/tmp"})]
+                   (is (= :error (:status result)))
+                   (is (= :sync-start-runtime-error (get-in result [:error :code])))
+                   (is (= :decrypt-aes-key (get-in result [:error :last-error :code])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-stop-syncs-non-auth-config-only
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/db-sync-stop (p/resolved {:ok true})
+                                                    (p/resolved nil)))]
+                 (p/let [_ (sync-command/execute {:type :sync-stop
+                                                  :repo "logseq_db_demo"}
+                                                 {:root-dir "/tmp"})]
+                   (is (= [[{:root-dir "/tmp"}
+                            "logseq_db_demo"]]
+                          @ensure-calls))
+                   (is (= [[:thread-api/set-db-sync-config false [{:ws-url nil
+                                                                   :http-base nil}]]
+                           [:thread-api/db-sync-stop false []]]
+                          @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-status-syncs-non-auth-config-only
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/db-sync-status (p/resolved {:repo "logseq_db_demo"
+                                                                                            :ws-state :open
+                                                                                            :pending-local 0
+                                                                                            :pending-asset 0
+                                                                                            :pending-server 0})
+                                                    (p/resolved nil)))]
+                 (p/let [result (sync-command/execute {:type :sync-status
+                                                       :repo "logseq_db_demo"}
+                                                      {:root-dir "/tmp"})]
+                   (is (= :ok (:status result)))
+                   (is (= :open (get-in result [:data :ws-state])))
+                   (is (= [[{:root-dir "/tmp"}
+                            "logseq_db_demo"]]
+                          @ensure-calls))
+                   (is (= [:thread-api/set-db-sync-config
+                           :thread-api/db-sync-status]
+                          (mapv first @invoke-calls)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-upload
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [_ (execute-with-runtime-auth {:type :sync-upload
+                                                  :repo "logseq_db_demo"}
+                                                 {:root-dir "/tmp"})]
+                   (is (= [[{:root-dir "/tmp"
+                             :id-token "runtime-token"}
+                            "logseq_db_demo"]]
+                          @ensure-calls))
+                   (is (= :thread-api/sync-app-state (ffirst @invoke-calls)))
+                   (is (= "runtime-token"
+                          (get-in (first @invoke-calls) [2 0 :auth/id-token])))
+                   (is (= [:thread-api/set-db-sync-config false [{:ws-url nil
+                                                                   :http-base nil}]]
+                          (second @invoke-calls)))
+                   (is (= [:thread-api/db-sync-upload-graph false ["logseq_db_demo"]]
+                          (nth @invoke-calls 2)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-upload-verifies-and-persists-e2ee-password-when-provided
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/verify-and-save-e2ee-password
+                                                    (p/resolved nil)
+
+                                                    :thread-api/db-sync-upload-graph
+                                                    (p/resolved {:graph-id "graph-1"})
+
+                                                    (p/resolved nil)))]
+                 (p/let [result (sync-command/execute {:type :sync-upload
+                                                       :repo "logseq_db_demo"
+                                                       :e2ee-password "pw"}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :refresh-token "refresh-token"
+                                                       :id-token "runtime-token"})]
+                   (is (= :ok (:status result)))
+                   (is (some #(= [:thread-api/verify-and-save-e2ee-password false ["refresh-token" "pw"]]
+                                 %)
+                             @invoke-calls))
+                   (is (some #(= [:thread-api/db-sync-upload-graph false ["logseq_db_demo"]]
+                                 %)
+                             @invoke-calls))
+                   (let [method-index (fn [method]
+                                        (first (keep-indexed (fn [idx [method' _direct-pass? _args]]
+                                                              (when (= method method')
+                                                                idx))
+                                                            @invoke-calls)))]
+                     (is (< (method-index :thread-api/verify-and-save-e2ee-password)
+                            (method-index :thread-api/db-sync-upload-graph))))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-upload-propagates-worker-error
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                         (p/resolved (assoc config :base-url "http://example")))
+                             transport/invoke (fn [_ method _direct-pass? _args]
+                                                (case method
+                                                  :thread-api/set-db-sync-config
+                                                  (p/resolved nil)
+
+                                                  :thread-api/db-sync-upload-graph
+                                                  (p/rejected (ex-info "snapshot upload failed"
+                                                                       {:code :snapshot-upload-failed
+                                                                        :status 500
+                                                                        :graph-id "graph-1"}))
+
+                                                  (p/resolved nil)))]
+               (p/let [result (execute-with-runtime-auth {:type :sync-upload
+                                                     :repo "logseq_db_demo"}
+                                                    {:root-dir "/tmp"})]
+                 (is (= :error (:status result)))
+                 (is (= :snapshot-upload-failed (get-in result [:error :code])))
+                 (is (= 500 (get-in result [:error :context :status])))
+                 (is (= "graph-1" (get-in result [:error :context :graph-id])))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-sync-upload-surfaces-missing-e2ee-password-hint
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                         (p/resolved (assoc config :base-url "http://example")))
+                             transport/invoke (fn [_ method _direct-pass? _args]
+                                                (case method
+                                                  :thread-api/set-db-sync-config
+                                                  (p/resolved nil)
+
+                                                  :thread-api/db-sync-upload-graph
+                                                  (p/rejected (ex-info "missing-e2ee-password"
+                                                                       {:code :db-sync/missing-e2ee-password
+                                                                        :field :e2ee-password
+                                                                        :reason :missing-persisted-password
+                                                                        :hint "Provide --e2ee-password to persist it."}))
+
+                                                  (p/resolved nil)))]
+               (p/let [result (execute-with-runtime-auth {:type :sync-upload
+                                                         :repo "logseq_db_demo"}
+                                                        {:root-dir "/tmp"})]
+                 (is (= :error (:status result)))
+                 (is (= :db-sync/missing-e2ee-password (get-in result [:error :code])))
+                 (is (= "missing-e2ee-password" (get-in result [:error :message])))
+                 (is (= "Provide --e2ee-password to persist it."
+                        (get-in result [:error :context :hint])))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-sync-upload-surfaces-graph-already-exists-error
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                         (p/resolved (assoc config :base-url "http://example")))
+                             transport/invoke (fn [_ method _direct-pass? _args]
+                                                (case method
+                                                  :thread-api/set-db-sync-config
+                                                  (p/resolved nil)
+
+                                                  :thread-api/db-sync-upload-graph
+                                                  (p/rejected (ex-info "remote graph already exists; delete it before uploading again"
+                                                                       {:code :db-sync/graph-already-exists
+                                                                        :graph-id "graph-1"
+                                                                        :graph-name "demo"}))
+
+                                                  (p/resolved nil)))]
+               (p/let [result (execute-with-runtime-auth {:type :sync-upload
+                                                         :repo "logseq_db_demo"}
+                                                        {:root-dir "/tmp"})]
+                 (is (= :error (:status result)))
+                 (is (= :db-sync/graph-already-exists (get-in result [:error :code])))
+                 (is (= "remote graph already exists; delete it before uploading again"
+                        (get-in result [:error :message])))
+                 (is (= "graph-1" (get-in result [:error :context :graph-id])))
+                 (is (= "demo" (get-in result [:error :context :graph-name])))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-sync-download
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "remote-graph-id"
+                                                                  :graph-name "demo"
+                                                                  :graph-e2ee? true}])
+                                                    :thread-api/q
+                                                    (p/resolved 0)
+                                                    :thread-api/db-sync-download-graph-by-id
+                                                    (p/resolved {:ok true})
+                                                    (p/resolved nil)))]
+                 (p/let [_ (execute-with-runtime-auth {:type :sync-download
+                                                  :repo "logseq_db_demo"
+                                                  :graph "demo"
+                                                  :e2ee-password "pw"}
+                                                 {:base-url "http://example"
+                                                  :root-dir "/tmp"
+                                                  :refresh-token "refresh-token"})]
+                   (is (= [[{:base-url "http://example"
+                             :create-empty-db? true
+                             :root-dir "/tmp"
+                             :refresh-token "refresh-token"
+                             :id-token "runtime-token"}
+                            "logseq_db_demo"]]
+                          @ensure-calls))
+                   (is (= :thread-api/sync-app-state (get-in @invoke-calls [0 0])))
+                   (is (= "runtime-token" (get-in @invoke-calls [0 2 0 :auth/id-token])))
+                   (is (= [:thread-api/set-db-sync-config false [{:ws-url nil
+                                                                  :http-base nil}]]
+                          (nth @invoke-calls 1)))
+                   (is (= [:thread-api/db-sync-list-remote-graphs false []]
+                          (nth @invoke-calls 2)))
+                   (is (= :thread-api/sync-app-state (get-in @invoke-calls [3 0])))
+                   (is (= "runtime-token" (get-in @invoke-calls [3 2 0 :auth/id-token])))
+                   (is (= [:thread-api/set-db-sync-config false [{:ws-url nil
+                                                                  :http-base nil}]]
+                          (nth @invoke-calls 4)))
+                   (is (= [:thread-api/verify-and-save-e2ee-password false ["refresh-token" "pw"]]
+                          (nth @invoke-calls 5)))
+                   (let [[method direct-pass? args] (nth @invoke-calls 6)]
+                     (is (= :thread-api/q method))
+                     (is (= false direct-pass?))
+                     (is (= "logseq_db_demo" (first args))))
+                   (is (= [:thread-api/db-sync-download-graph-by-id false ["logseq_db_demo" "remote-graph-id" true]]
+                          (nth @invoke-calls 7)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-uses-long-timeout-only-for-download-invoke
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [cfg method direct-pass? args]
+                                                  (swap! invoke-calls conj {:method method
+                                                                            :direct-pass? direct-pass?
+                                                                            :args args
+                                                                            :timeout-ms (:timeout-ms cfg)})
+                                                  (case method
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "remote-graph-id"
+                                                                  :graph-name "demo"
+                                                                  :graph-e2ee? false}])
+                                                    :thread-api/q
+                                                    (p/resolved 0)
+                                                    :thread-api/db-sync-download-graph-by-id
+                                                    (p/resolved {:ok true})
+                                                    (p/resolved nil)))]
+                 (p/let [result (execute-with-runtime-auth {:type :sync-download
+                                                            :repo "logseq_db_demo"
+                                                            :graph "demo"}
+                                                           {:base-url "http://example"
+                                                            :root-dir "/tmp"
+                                                            :timeout-ms 10000})
+                         [sync-app-state-before set-config-before list-remote-graphs sync-app-state-after set-config-after check-empty-db download]
+                         @invoke-calls]
+                   (is (= :ok (:status result)))
+                   (is (= :thread-api/sync-app-state (:method sync-app-state-before)))
+                   (is (= :thread-api/set-db-sync-config (:method set-config-before)))
+                   (is (= :thread-api/db-sync-list-remote-graphs (:method list-remote-graphs)))
+                   (is (= :thread-api/sync-app-state (:method sync-app-state-after)))
+                   (is (= :thread-api/set-db-sync-config (:method set-config-after)))
+                   (is (= :thread-api/q (:method check-empty-db)))
+                   (is (= :thread-api/db-sync-download-graph-by-id (:method download)))
+                   (is (= 10000 (:timeout-ms sync-app-state-before)))
+                   (is (= 10000 (:timeout-ms set-config-before)))
+                   (is (= 10000 (:timeout-ms list-remote-graphs)))
+                   (is (= 10000 (:timeout-ms sync-app-state-after)))
+                   (is (= 10000 (:timeout-ms set-config-after)))
+                   (is (= 10000 (:timeout-ms check-empty-db)))
+                   (is (= 1800000 (:timeout-ms download)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-progress-mode-behavior
+  (async done
+         (let [subscribe-calls (atom [])
+               close-calls (atom 0)
+               printed-lines (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/connect-events! (fn [cfg on-event]
+                                                          (swap! subscribe-calls conj {:base-url (:base-url cfg)
+                                                                                       :timeout-ms (:timeout-ms cfg)})
+                                                          (on-event :rtc-log {:type :rtc.log/download
+                                                                              :graph-uuid "remote-graph-id"
+                                                                              :message "Preparing graph snapshot download"})
+                                                          (on-event :rtc-log {:type :rtc.log/download
+                                                                              :graph-uuid "other-graph-id"
+                                                                              :message "should be filtered"})
+                                                          {:close! (fn []
+                                                                     (swap! close-calls inc))})
+                               sync-command/print-progress-line! (fn [line]
+                                                                   (swap! printed-lines conj line)
+                                                                   nil)
+                               transport/invoke (fn [_ method _direct-pass? _args]
+                                                  (case method
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "remote-graph-id"
+                                                                  :graph-name "demo"
+                                                                  :graph-e2ee? false}])
+                                                    :thread-api/q
+                                                    (p/resolved 0)
+                                                    :thread-api/db-sync-download-graph-by-id
+                                                    (p/resolved {:ok true})
+                                                    (p/resolved nil)))]
+                 (p/let [_ (execute-with-runtime-auth {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"
+                                                       :progress-explicit? false}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :output-format nil})
+                         _ (is (= 1 (count @subscribe-calls)))
+                         _ (is (= ["Preparing graph snapshot download"] @printed-lines))
+                         _ (is (= 1 @close-calls))
+                         _ (reset! subscribe-calls [])
+                         _ (reset! printed-lines [])
+                         _ (reset! close-calls 0)
+                         _ (execute-with-runtime-auth {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"
+                                                       :progress-explicit? false}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :output-format :json})
+                         _ (is (= [] @subscribe-calls))
+                         _ (is (= [] @printed-lines))
+                         _ (is (= 0 @close-calls))
+                         _ (execute-with-runtime-auth {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"
+                                                       :progress-explicit? false}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :output-format :edn})
+                         _ (is (= [] @subscribe-calls))
+                         _ (is (= [] @printed-lines))
+                         _ (is (= 0 @close-calls))
+                         _ (execute-with-runtime-auth {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"
+                                                       :progress true
+                                                       :progress-explicit? true}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :output-format :json})
+                         _ (is (= 1 (count @subscribe-calls)))
+                         _ (is (= ["Preparing graph snapshot download"] @printed-lines))
+                         _ (is (= 1 @close-calls))
+                         _ (reset! subscribe-calls [])
+                         _ (reset! printed-lines [])
+                         _ (reset! close-calls 0)
+                         _ (execute-with-runtime-auth {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"
+                                                       :progress false
+                                                       :progress-explicit? true}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :output-format nil})]
+                   (is (= [] @subscribe-calls))
+                   (is (= [] @printed-lines))
+                   (is (= 0 @close-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-uses-graph-config-when-base-url-missing
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "remote-graph-id"
+                                                                  :graph-name "demo"
+                                                                  :graph-e2ee? false}])
+                                                    :thread-api/q
+                                                    (p/resolved 0)
+                                                    :thread-api/db-sync-download-graph-by-id
+                                                    (p/resolved {:ok true})
+                                                    (p/resolved nil)))]
+                 (p/let [_ (execute-with-runtime-auth {:type :sync-download
+                                                  :repo "logseq_db_demo"
+                                                  :graph "demo"}
+                                                 {:graph "demo"
+                                                  :root-dir "/tmp"})]
+                   (is (= [[{:graph "demo"
+                             :create-empty-db? true
+                             :root-dir "/tmp"
+                             :id-token "runtime-token"}
+                            "logseq_db_demo"]
+                           [{:graph "demo"
+                             :create-empty-db? true
+                             :root-dir "/tmp"
+                             :id-token "runtime-token"}
+                            "logseq_db_demo"]]
+                          @ensure-calls))
+                   (is (= :thread-api/sync-app-state (get-in @invoke-calls [0 0])))
+                   (is (= "runtime-token" (get-in @invoke-calls [0 2 0 :auth/id-token])))
+                   (is (= [:thread-api/set-db-sync-config false [{:ws-url nil
+                                                                  :http-base nil}]]
+                          (nth @invoke-calls 1)))
+                   (is (= [:thread-api/db-sync-list-remote-graphs false []]
+                          (nth @invoke-calls 2)))
+                   (is (= :thread-api/sync-app-state (get-in @invoke-calls [3 0])))
+                   (is (= "runtime-token" (get-in @invoke-calls [3 2 0 :auth/id-token])))
+                   (is (= [:thread-api/set-db-sync-config false [{:ws-url nil
+                                                                  :http-base nil}]]
+                          (nth @invoke-calls 4)))
+                   (let [[method direct-pass? args] (nth @invoke-calls 5)]
+                     (is (= :thread-api/q method))
+                     (is (= false direct-pass?))
+                     (is (= "logseq_db_demo" (first args))))
+                   (is (= [:thread-api/db-sync-download-graph-by-id false ["logseq_db_demo" "remote-graph-id" false]]
+                          (nth @invoke-calls 6)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-remote-graph-not-found
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "other-id"
+                                                                  :graph-name "other-graph"}])
+                                                    :thread-api/db-sync-download-graph-by-id
+                                                    (p/resolved {:ok true})
+                                                    (p/resolved nil)))]
+                 (p/let [result (execute-with-runtime-auth {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"})]
+                   (is (= :error (:status result)))
+                   (is (= :remote-graph-not-found (get-in result [:error :code])))
+                   (is (= :thread-api/sync-app-state (get-in @invoke-calls [0 0])))
+                   (is (= "runtime-token" (get-in @invoke-calls [0 2 0 :auth/id-token])))
+                   (is (= [:thread-api/set-db-sync-config false [{:ws-url nil
+                                                                   :http-base nil}]]
+                          (nth @invoke-calls 1)))
+                   (is (= [:thread-api/db-sync-list-remote-graphs false []]
+                          (nth @invoke-calls 2)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-propagates-worker-error-code
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                         (p/resolved (assoc config :base-url "http://example")))
+                             transport/invoke (fn [_ method _direct-pass? _args]
+                                                (case method
+                                                  :thread-api/db-sync-list-remote-graphs
+                                                  (p/resolved [{:graph-id "remote-graph-id"
+                                                                :graph-name "demo"
+                                                                :graph-e2ee? true}])
+                                                  :thread-api/q
+                                                  (p/resolved 0)
+                                                  :thread-api/db-sync-download-graph-by-id
+                                                  (p/rejected (ex-info "db-sync/snapshot-download-failed"
+                                                                       {:code :db-sync/snapshot-download-failed
+                                                                        :graph-id "remote-graph-id"
+                                                                        :status 500}))
+                                                  (p/resolved nil)))]
+               (p/let [result (execute-with-runtime-auth {:type :sync-download
+                                                     :repo "logseq_db_demo"
+                                                     :graph "demo"
+                                                     :e2ee-password "pw"}
+                                                    {:base-url "http://example"
+                                                     :root-dir "/tmp"
+                                                     :refresh-token "refresh-token"})]
+                 (is (= :error (:status result)))
+                 (is (= :db-sync/snapshot-download-failed (get-in result [:error :code])))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-sync-download-fails-fast-when-db-is-not-empty
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (p/resolved (assoc config
+                                                                              :repo repo
+                                                                              :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (case method
+                                                    :thread-api/db-sync-list-remote-graphs
+                                                    (p/resolved [{:graph-id "remote-graph-id"
+                                                                  :graph-name "demo"
+                                                                  :graph-e2ee? true}])
+                                                    :thread-api/q
+                                                    (p/resolved 2)
+                                                    :thread-api/db-sync-download-graph-by-id
+                                                    (p/resolved {:ok true})
+                                                    (p/resolved nil)))]
+                 (p/let [result (execute-with-runtime-auth {:type :sync-download
+                                                       :repo "logseq_db_demo"
+                                                       :graph "demo"
+                                                       :e2ee-password "pw"}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"
+                                                       :refresh-token "refresh-token"})]
+                   (is (= :error (:status result)))
+                   (is (= :graph-db-not-empty (get-in result [:error :code])))
+                   (is (= "logseq_db_demo" (get-in result [:error :repo])))
+                   (is (= 2 (get-in result [:error :context :non-empty-entity-count])))
+                   (is (not-any? (fn [[method _ _]]
+                                   (= :thread-api/db-sync-download-graph-by-id method))
+                                 @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-remote-graphs
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])
+               auth-calls (atom [])]
+           (-> (p/with-redefs [cli-auth/resolve-auth! (fn [config]
+                                                        (swap! auth-calls conj config)
+                                                        (p/resolved {:id-token "resolved-token"
+                                                                     :refresh-token "refresh-token"}))
+                               cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved []))]
+                 (p/let [_ (sync-command/execute {:type :sync-remote-graphs}
+                                                 {:base-url "http://example"
+                                                  :http-base "https://sync.example.com"
+                                                  :ws-url "wss://sync.example.com/sync/%s"
+                                                  :e2ee-password "pw"
+                                                  :root-dir "/tmp"})]
+                   (is (= [] @ensure-calls))
+                   (is (= [{:base-url "http://example"
+                            :http-base "https://sync.example.com"
+                            :ws-url "wss://sync.example.com/sync/%s"
+                            :e2ee-password "pw"
+                            :root-dir "/tmp"}]
+                          @auth-calls))
+                   (is (= :thread-api/sync-app-state (get-in @invoke-calls [0 0])))
+                   (is (= "resolved-token" (get-in @invoke-calls [0 2 0 :auth/id-token])))
+                   (is (= [:thread-api/set-db-sync-config false [{:ws-url "wss://sync.example.com/sync/%s"
+                                                                   :http-base "https://sync.example.com"}]]
+                          (nth @invoke-calls 1)))
+                   (is (= [:thread-api/db-sync-list-remote-graphs false []]
+                          (nth @invoke-calls 2)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-remote-graphs-missing-auth
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-auth/resolve-auth! (fn [_config]
+                                                         (p/rejected (ex-info "missing auth"
+                                                                              {:code :missing-auth
+                                                                               :hint "Run logseq login first."})))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved []))]
+                 (p/let [result (sync-command/execute {:type :sync-remote-graphs}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"})]
+                   (is (= :error (:status result)))
+                   (is (= :missing-auth (get-in result [:error :code])))
+                   (is (= "Run logseq login first." (get-in result [:error :context :hint])))
+                   (is (= [] @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-ensure-keys
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [_ (execute-with-runtime-auth {:type :sync-ensure-keys}
+                                                      {:base-url "http://example"
+                                                       :root-dir "/tmp"})]
+                   (is (= [] @ensure-calls))
+                   (is (= :thread-api/sync-app-state (get-in @invoke-calls [0 0])))
+                   (is (= "runtime-token" (get-in @invoke-calls [0 2 0 :auth/id-token])))
+                   (is (= [:thread-api/set-db-sync-config false [{:ws-url nil
+                                                                   :http-base nil}]]
+                          (nth @invoke-calls 1)))
+                   (is (= [:thread-api/db-sync-ensure-user-rsa-keys false []]
+                          (nth @invoke-calls 2)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-ensure-keys-verifies-and-persists-e2ee-password-when-provided
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [_ (sync-command/execute {:type :sync-ensure-keys
+                                                  :e2ee-password "pw"}
+                                                 {:base-url "http://example"
+                                                  :root-dir "/tmp"
+                                                  :refresh-token "refresh-token"
+                                                  :id-token "runtime-token"})]
+                   (is (= [:thread-api/sync-app-state
+                           :thread-api/set-db-sync-config
+                           :thread-api/verify-and-save-e2ee-password
+                           :thread-api/sync-app-state
+                           :thread-api/set-db-sync-config
+                           :thread-api/db-sync-ensure-user-rsa-keys]
+                          (mapv first @invoke-calls)))
+                   (is (some #(= [:thread-api/verify-and-save-e2ee-password false ["refresh-token" "pw"]]
+                                 %)
+                             @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-ensure-keys-upload-keys-enables-server-upload-flow
+  (async done
+         (let [invoke-calls (atom [])]
+           (-> (p/with-redefs [transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [_ (sync-command/execute {:type :sync-ensure-keys
+                                                  :upload-keys true
+                                                  :e2ee-password "pw"}
+                                                 {:base-url "http://example"
+                                                  :root-dir "/tmp"
+                                                  :refresh-token "refresh-token"
+                                                  :id-token "runtime-token"})]
+                   (is (= [:thread-api/sync-app-state
+                           :thread-api/set-db-sync-config
+                           :thread-api/db-sync-ensure-user-rsa-keys
+                           :thread-api/sync-app-state
+                           :thread-api/set-db-sync-config
+                           :thread-api/verify-and-save-e2ee-password]
+                          (mapv first @invoke-calls)))
+                   (is (some #(= [:thread-api/db-sync-ensure-user-rsa-keys false [{:ensure-server? true
+                                                                                     :password "pw"}]]
+                                 %)
+                             @invoke-calls))
+                   (is (some #(= [:thread-api/verify-and-save-e2ee-password false ["refresh-token" "pw"]]
+                                 %)
+                             @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-grant-access-missing-http-base-is-error
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [result (sync-command/execute {:type :sync-grant-access
+                                                       :repo "logseq_db_demo"
+                                                       :graph-id "graph-uuid"
+                                                       :email "user@example.com"}
+                                                      {:root-dir "/tmp"
+                                                       :http-base ""
+                                                       :id-token "runtime-token"})]
+                   (is (= :error (:status result)))
+                   (is (= :missing-sync-config (get-in result [:error :code])))
+                   (is (= :sync-grant-access (get-in result [:error :action])))
+                   (is (= [:http-base] (get-in result [:error :missing-keys])))
+                   (is (= [] @ensure-calls))
+                   (is (= [] @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-grant-access
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [_ (execute-with-runtime-auth {:type :sync-grant-access
+                                                  :repo "logseq_db_demo"
+                                                  :graph-id "graph-uuid"
+                                                  :email "user@example.com"}
+                                                 {:root-dir "/tmp"})]
+                   (is (= [[{:root-dir "/tmp"
+                             :id-token "runtime-token"}
+                            "logseq_db_demo"]]
+                          @ensure-calls))
+                   (is (= :thread-api/sync-app-state (get-in @invoke-calls [0 0])))
+                   (is (= "runtime-token" (get-in @invoke-calls [0 2 0 :auth/id-token])))
+                   (is (= [:thread-api/set-db-sync-config false [{:ws-url nil
+                                                                   :http-base nil}]]
+                          (nth @invoke-calls 1)))
+                   (is (= [:thread-api/db-sync-grant-graph-access false ["logseq_db_demo" "graph-uuid" "user@example.com"]]
+                          (nth @invoke-calls 2)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-config-get
+  (async done
+         (let [ensure-calls (atom [])
+               invoke-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config repo]
+                                                           (swap! ensure-calls conj [config repo])
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved {:ok true}))]
+                 (p/let [_ (sync-command/execute {:type :sync-config-get
+                                                  :config-key :ws-url}
+                                                 {:base-url "http://example"
+                                                  :ws-url "wss://sync.example.com/sync/%s"
+                                                  :root-dir "/tmp"})]
+                   (is (= [] @ensure-calls))
+                   (is (= [] @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-config-set
+  (async done
+         (let [invoke-calls (atom [])
+               update-calls (atom [])]
+           (-> (p/with-redefs [transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved nil))
+                               cli-config/update-config! (fn [config updates]
+                                                           (swap! update-calls conj [config updates])
+                                                           (merge {:ws-url "wss://old.example/sync/%s"} updates))]
+                 (p/let [_ (sync-command/execute {:type :sync-config-set
+                                                  :config-key :ws-url
+                                                  :config-value "wss://sync.example.com/sync/%s"}
+                                                 {:base-url "http://example"
+                                                  :config-path "/tmp/cli.edn"
+                                                  :root-dir "/tmp"})]
+                   (is (= [[{:base-url "http://example"
+                             :config-path "/tmp/cli.edn"
+                             :root-dir "/tmp"}
+                            {:ws-url "wss://sync.example.com/sync/%s"}]]
+                          @update-calls))
+                   (is (= [] @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-config-unset
+  (async done
+         (let [invoke-calls (atom [])
+               update-calls (atom [])]
+           (-> (p/with-redefs [transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (p/resolved nil))
+                               cli-config/update-config! (fn [config updates]
+                                                           (swap! update-calls conj [config updates])
+                                                           (dissoc {:ws-url "wss://old.example/sync/%s"}
+                                                                   :ws-url))]
+                 (p/let [_ (sync-command/execute {:type :sync-config-unset
+                                                  :config-key :ws-url}
+                                                 {:base-url "http://example"
+                                                  :config-path "/tmp/cli.edn"
+                                                  :root-dir "/tmp"})]
+                   (is (= [[{:base-url "http://example"
+                             :config-path "/tmp/cli.edn"
+                             :root-dir "/tmp"}
+                            {:ws-url nil}]]
+                          @update-calls))
+                   (is (= [] @invoke-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
diff --git a/src/test/logseq/cli/command/update_test.cljs b/src/test/logseq/cli/command/update_test.cljs
new file mode 100644
index 0000000000..d59447c6af
--- /dev/null
+++ b/src/test/logseq/cli/command/update_test.cljs
@@ -0,0 +1,25 @@
+(ns logseq.cli.command.update-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [logseq.cli.command.update :as update-command]))
+
+(deftest test-build-action-invalid-update-properties
+  (testing "returns parse error when update-properties is not a map"
+    (let [result (update-command/build-action
+                  {:id 207 :update-properties "[\"p1\"]"}
+                  "test-repo")]
+      (is (not (:ok? result)))
+      (is (= "properties must be a map"
+             (get-in result [:error :message])))))
+
+  (testing "returns parse error when update-tags is not a vector"
+    (let [result (update-command/build-action
+                  {:id 207 :update-tags "{\"t1\" true}"}
+                  "test-repo")]
+      (is (not (:ok? result)))
+      (is (string? (get-in result [:error :message])))))
+
+  (testing "valid update-properties map succeeds"
+    (let [result (update-command/build-action
+                  {:id 207 :update-properties "{\"p1\" \"val\"}"}
+                  "test-repo")]
+      (is (:ok? result)))))
diff --git a/src/test/logseq/cli/command/upsert_test.cljs b/src/test/logseq/cli/command/upsert_test.cljs
new file mode 100644
index 0000000000..c33637aa30
--- /dev/null
+++ b/src/test/logseq/cli/command/upsert_test.cljs
@@ -0,0 +1,711 @@
+(ns logseq.cli.command.upsert-test
+  (:require [clojure.string :as string]
+            [cljs.test :refer [async deftest is testing]]
+            [logseq.cli.command.add :as add-command]
+            [logseq.cli.command.update :as update-command]
+            [logseq.cli.command.upsert :as upsert-command]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [promesa.core :as p]))
+
+(deftest test-execute-upsert-tag-create-creates-tag-when-missing
+  (async done
+    (let [q-calls* (atom 0)
+          create-called?* (atom false)
+          action {:type :upsert-tag
+                  :mode :create
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :name "TagOne"}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/q
+                                               (let [[_ [query _]] args
+                                                     where (:where query)
+                                                     malformed-where? (and (= 1 (count where))
+                                                                           (vector? (first where))
+                                                                           (> (count (first where)) 3))]
+                                                 (if malformed-where?
+                                                   (throw (ex-info "Index out of bounds" {:code :http-error}))
+                                                   (do
+                                                     (swap! q-calls* inc)
+                                                     (if (= 1 @q-calls*)
+                                                       (p/resolved [])
+                                                       (p/resolved [{:db/id 42
+                                                                     :block/name "tagone"
+                                                                     :block/title "TagOne"
+                                                                     :block/tags [{:db/ident :logseq.class/Tag}]}])))))
+
+                                               :thread-api/apply-outliner-ops
+                                               (do
+                                                 (reset! create-called?* true)
+                                                 (p/resolved nil))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method
+                                                                :args args}))))]
+            (p/let [result (upsert-command/execute-upsert-tag action {})]
+              (is (= :ok (:status result)))
+              (is (= [42] (get-in result [:data :result])))
+              (is @create-called?*)
+              (is (= 2 @q-calls*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-build-asset-action
+  (testing "upsert asset create mode derives default title from path"
+    (let [result (upsert-command/build-asset-action {:path "/tmp/team-logo.png"}
+                                                    "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= :upsert-asset (get-in result [:action :type])))
+      (is (= :create (get-in result [:action :mode])))
+      (is (= "/tmp/team-logo.png" (get-in result [:action :asset-path])))
+      (is (= "team-logo" (get-in result [:action :blocks 0 :block/title])))))
+
+  (testing "upsert asset update mode preserves selector and content"
+    (let [result (upsert-command/build-asset-action {:id 42 :content "New title"}
+                                                    "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= :upsert-asset (get-in result [:action :type])))
+      (is (= :update (get-in result [:action :mode])))
+      (is (= 42 (get-in result [:action :id])))
+      (is (= "New title" (get-in result [:action :content]))))))
+
+(deftest test-execute-upsert-asset-create-applies-metadata-and-copies-file
+  (async done
+    (let [add-actions* (atom [])
+          copy-calls* (atom [])
+          action {:type :upsert-asset
+                  :mode :create
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :asset-path "/tmp/logo.png"
+                  :content "Logo"
+                  :blocks [{:block/title "Logo"}] }]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          upsert-command/asset-file-exists? (fn [_] true)
+                          upsert-command/asset-file-size-bytes (fn [_] 123)
+                          upsert-command/asset-file-checksum (fn [_] "sha-256-value")
+                          upsert-command/copy-asset-file-to-graph! (fn [_ repo block-uuid asset-type source-path]
+                                                                     (swap! copy-calls* conj [repo block-uuid asset-type source-path])
+                                                                     "/tmp/copied/logo.png")
+                          add-command/execute-add-block (fn [add-action _]
+                                                          (swap! add-actions* conj add-action)
+                                                          (p/resolved {:status :ok
+                                                                       :data {:result [101]}}))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/pull
+                                               (let [[_ _ lookup] args]
+                                                 (cond
+                                                   (= lookup 101)
+                                                   (p/resolved {:db/id 101
+                                                                :block/uuid (uuid "00000000-0000-0000-0000-000000000101")})
+
+                                                   (= lookup [:db/ident :logseq.class/Asset])
+                                                   (p/resolved {:db/id 900})
+
+                                                   :else
+                                                   (p/resolved {})))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method
+                                                                :args args}))))]
+            (p/let [result (upsert-command/execute-upsert-asset action {})
+                    block (get-in (first @add-actions*) [:blocks 0])]
+              (is (= :ok (:status result)))
+              (is (= [101] (get-in result [:data :result])))
+              (is (= "png" (:logseq.property.asset/type block)))
+              (is (= 123 (:logseq.property.asset/size block)))
+              (is (= "sha-256-value" (:logseq.property.asset/checksum block)))
+              (is (= #{900} (:block/tags block)))
+              (is (= [["demo-repo"
+                       (uuid "00000000-0000-0000-0000-000000000101")
+                       "png"
+                       "/tmp/logo.png"]]
+                     @copy-calls*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-asset-update
+  (async done
+    (let [update-calls* (atom [])
+          action {:type :upsert-asset
+                  :mode :update
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :id 42
+                  :content "Updated title"}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          update-command/execute-update (fn [update-action _]
+                                                          (swap! update-calls* conj update-action)
+                                                          (p/resolved {:status :ok :data {:result nil}}))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/pull
+                                               (let [[_ _ lookup] args]
+                                                 (if (= lookup 42)
+                                                   (p/resolved {:db/id 42
+                                                                :block/uuid (uuid "00000000-0000-0000-0000-000000000042")
+                                                                :block/tags [{:db/ident :logseq.class/Asset}]})
+                                                   (p/resolved {})))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method
+                                                                :args args}))))]
+            (p/let [result (upsert-command/execute-upsert-asset action {})]
+              (is (= :ok (:status result)))
+              (is (= [42] (get-in result [:data :result])))
+              (is (= :update-block (get-in (first @update-calls*) [:type])))
+              (is (= 42 (get-in (first @update-calls*) [:id])))
+              (is (= "Updated title" (get-in (first @update-calls*) [:content])))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-asset-update-rejects-non-asset-node
+  (async done
+    (let [action {:type :upsert-asset
+                  :mode :update
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :id 42}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/pull
+                                               (let [[_ _ lookup] args]
+                                                 (if (= lookup 42)
+                                                   (p/resolved {:db/id 42
+                                                                :block/uuid (uuid "00000000-0000-0000-0000-000000000042")
+                                                                :block/tags [{:db/ident :logseq.class/Task}]})
+                                                   (p/resolved {})))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method
+                                                                :args args}))))]
+            (p/let [result (upsert-command/execute-upsert-asset action {})
+                    message (or (get-in result [:error :message]) "")]
+              (is (= :error (:status result)))
+              (is (= :upsert-id-type-mismatch (get-in result [:error :code])))
+              (is (string/includes? message "#Asset"))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-block-create-does-not-insert-when-tag-missing
+  (async done
+         (let [mutation-called?* (atom false)
+               action {:type :upsert-block
+                       :mode :create
+                       :repo "demo-repo"
+                       :graph "demo-graph"
+                       :target-page-name "TestPage"
+                       :blocks [{:block/title "b2" :block/uuid (random-uuid)}]
+                       :update-tags ["c2"]
+                       :pos "last-child"}]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                           (p/resolved (assoc config :base-url "http://example")))
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    ;; resolve-tags queries for the tag by name
+                                                    :thread-api/q
+                                                    (p/resolved [])
+
+                                                    :thread-api/pull
+                                                    (p/resolved {:db/id 10 :block/uuid (random-uuid)
+                                                                 :block/name "testpage" :block/title "TestPage"})
+
+                                                    :thread-api/apply-outliner-ops
+                                                    (let [[_ _ops _] args]
+                                                      (reset! mutation-called?* true)
+                                                      (p/resolved nil))
+
+                                                    (throw (ex-info "unexpected invoke"
+                                                                    {:method method :args args}))))]
+                 (p/let [result (upsert-command/execute-upsert-block action {})]
+                   (is (= :error (:status result))
+                       "should return error when tag does not exist")
+                   (is (= :tag-not-found (get-in result [:error :code])))
+                   (is (false? @mutation-called?*)
+                       "block insert must not be called when tag resolution fails")))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-build-task-action-validation
+  (testing "upsert task requires target selector or content/page"
+    (let [result (upsert-command/build-task-action {} "logseq_db_demo")]
+      (is (false? (:ok? result)))
+      (is (= :missing-target (get-in result [:error :code])))))
+
+  (testing "upsert task rejects page and content combination"
+    (let [result (upsert-command/build-task-action {:page "Home" :content "Task"} "logseq_db_demo")]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert task build create mode supports set semantics"
+    (let [scheduled-ms (.getTime (js/Date. "2026-02-10T08:00:00.000Z"))
+          deadline-ms (.getTime (js/Date. "2026-02-12T18:00:00.000Z"))
+          result (upsert-command/build-task-action {:content "Task from CLI"
+                                                    :status "todo"
+                                                    :priority "high"
+                                                    :scheduled "2026-02-10T08:00:00.000Z"
+                                                    :deadline "2026-02-12T18:00:00.000Z"}
+                                                   "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= :upsert-task (get-in result [:action :type])))
+      (is (= :create (get-in result [:action :mode])))
+      (is (= :logseq.property/status.todo (get-in result [:action :update-properties :logseq.property/status])))
+      (is (= :logseq.property/priority.high (get-in result [:action :update-properties :logseq.property/priority])))
+      (is (= scheduled-ms (get-in result [:action :update-properties :logseq.property/scheduled])))
+      (is (= deadline-ms (get-in result [:action :update-properties :logseq.property/deadline])))))
+
+  (testing "upsert task build update mode supports explicit clear semantics"
+    (let [result (upsert-command/build-task-action {:id 42
+                                                    :no-status true
+                                                    :no-priority true
+                                                    :no-scheduled true
+                                                    :no-deadline true}
+                                                   "logseq_db_demo")
+          clear-properties (set (get-in result [:action :clear-properties]))]
+      (is (true? (:ok? result)))
+      (is (= :upsert-task (get-in result [:action :type])))
+      (is (= :update (get-in result [:action :mode])))
+      (is (= #{:logseq.property/status
+               :logseq.property/priority
+               :logseq.property/scheduled
+               :logseq.property/deadline}
+             clear-properties))))
+
+  (testing "upsert task rejects set/no conflicts for the same field"
+    (doseq [opts [{:id 42 :status "todo" :no-status true}
+                  {:id 42 :priority "high" :no-priority true}
+                  {:id 42 :scheduled "2026-02-10T08:00:00.000Z" :no-scheduled true}
+                  {:id 42 :deadline "2026-02-12T18:00:00.000Z" :no-deadline true}]]
+      (let [result (upsert-command/build-task-action opts "logseq_db_demo")]
+        (is (false? (:ok? result)))
+        (is (= :invalid-options (get-in result [:error :code]))))))
+
+  (testing "upsert task create defers unknown status to runtime validation"
+    (let [result (upsert-command/build-task-action {:content "Task from CLI"
+                                                    :status "wat"}
+                                                   "logseq_db_demo")]
+      (is (true? (:ok? result)))
+      (is (= :upsert-task (get-in result [:action :type])))
+      (is (= :create (get-in result [:action :mode])))
+      (is (= "wat" (get-in result [:action :status-input])))))
+
+  (testing "upsert task rejects invalid priority with available values"
+    (let [result (upsert-command/build-task-action {:content "Task from CLI"
+                                                    :priority "wat"}
+                                                   "logseq_db_demo")
+          message (get-in result [:error :message])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "Invalid value for option :priority: wat"))
+      (is (string/includes? message "Available values: low, medium, high, urgent")))))
+
+(deftest test-execute-upsert-task-create-invalid-status-includes-available-values
+  (async done
+    (let [calls* (atom [])
+          action {:type :upsert-task
+                  :mode :create
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :status-input "invalid-status"}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ _]
+                                             (swap! calls* conj method)
+                                             (case method
+                                               :thread-api/q
+                                               (p/resolved [:logseq.property/status.todo
+                                                            :logseq.property/status.doing
+                                                            :logseq.property/status.done])
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method}))))]
+            (p/let [result (upsert-command/execute-upsert-task action {})
+                    message (or (get-in result [:error :message]) "")]
+              (is (= :error (:status result)))
+              (is (= :invalid-options (get-in result [:error :code])))
+              (is (string/includes? message "Invalid value for option :status: invalid-status"))
+              (is (string/includes? message "Available values:"))
+              (is (= [:thread-api/q] @calls*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-task-page-applies-task-ops
+  (async done
+    (let [ops* (atom nil)
+          page-uuid (uuid "00000000-0000-0000-0000-000000000042")
+          block-uuids [page-uuid]
+          scheduled-ms (.getTime (js/Date. "2026-02-10T08:00:00.000Z"))
+          deadline-ms (.getTime (js/Date. "2026-02-12T18:00:00.000Z"))
+          action {:type :upsert-task
+                  :mode :page
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :page "TaskHome"
+                  :status :logseq.property/status.todo
+                  :priority :logseq.property/priority.high
+                  :scheduled scheduled-ms
+                  :deadline deadline-ms}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/q
+                                               (let [[_ [_query input]] args]
+                                                 (if (= input "taskhome")
+                                                   (p/resolved [{:db/id 42 :block/uuid page-uuid}])
+                                                   (p/resolved [:logseq.property/status.todo
+                                                                :logseq.property/status.doing
+                                                                :logseq.property/status.done])))
+
+                                               :thread-api/pull
+                                               (let [[_ selector lookup] args]
+                                                 (cond
+                                                   (= lookup [:block/name "taskhome"])
+                                                   (p/resolved {:db/id 42 :block/uuid page-uuid})
+
+                                                   (and (= selector [:db/id :block/uuid])
+                                                        (= lookup 42))
+                                                   (p/resolved {:db/id 42 :block/uuid page-uuid})
+
+                                                   (= lookup [:db/ident :logseq.class/Task])
+                                                   (p/resolved {:db/id 900})
+
+                                                   (and (vector? selector) (= selector [:db/id]))
+                                                   (p/resolved {:db/id 1})
+
+                                                   :else
+                                                   (p/resolved {})))
+
+                                               :thread-api/apply-outliner-ops
+                                               (let [[_ ops _] args]
+                                                 (reset! ops* ops)
+                                                 (p/resolved nil))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method
+                                                                :args args}))))]
+            (p/let [result (upsert-command/execute-upsert-task action {})]
+              (is (= :ok (:status result)))
+              (is (= [42] (get-in result [:data :result])))
+              (is (= [[:batch-set-property [block-uuids :block/tags 900 {}]]
+                      [:batch-set-property [block-uuids :logseq.property/status :logseq.property/status.todo {}]]
+                      [:batch-set-property [block-uuids :logseq.property/priority :logseq.property/priority.high {}]]
+                      [:batch-set-property [block-uuids :logseq.property/scheduled scheduled-ms {}]]
+                      [:batch-set-property [block-uuids :logseq.property/deadline deadline-ms {}]]]
+                     @ops*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-task-page-applies-update-properties-map
+  (async done
+    (let [ops* (atom nil)
+          page-uuid (uuid "00000000-0000-0000-0000-000000000042")
+          block-uuids [page-uuid]
+          scheduled-ms (.getTime (js/Date. "2026-02-10T08:00:00.000Z"))
+          deadline-ms (.getTime (js/Date. "2026-02-12T18:00:00.000Z"))
+          action {:type :upsert-task
+                  :mode :page
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :page "TaskHome"
+                  :update-properties {:logseq.property/status :logseq.property/status.todo
+                                      :logseq.property/priority :logseq.property/priority.high
+                                      :logseq.property/scheduled scheduled-ms
+                                      :logseq.property/deadline deadline-ms}}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/q
+                                               (let [[_ [_query input]] args]
+                                                 (if (= input "taskhome")
+                                                   (p/resolved [{:db/id 42 :block/uuid page-uuid}])
+                                                   (p/resolved [])))
+
+                                               :thread-api/pull
+                                               (let [[_ selector lookup] args]
+                                                 (cond
+                                                   (= lookup [:block/name "taskhome"])
+                                                   (p/resolved {:db/id 42 :block/uuid page-uuid})
+
+                                                   (and (= selector [:db/id :block/uuid])
+                                                        (= lookup 42))
+                                                   (p/resolved {:db/id 42 :block/uuid page-uuid})
+
+                                                   (= lookup [:db/ident :logseq.class/Task])
+                                                   (p/resolved {:db/id 900})
+
+                                                   (and (vector? selector) (= selector [:db/id])
+                                                        (vector? lookup) (= :db/ident (first lookup)))
+                                                   (p/resolved {:db/id 1})
+
+                                                   :else
+                                                   (p/resolved {})))
+
+                                               :thread-api/apply-outliner-ops
+                                               (let [[_ ops _] args]
+                                                 (reset! ops* ops)
+                                                 (p/resolved nil))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method
+                                                                :args args}))))]
+            (p/let [result (upsert-command/execute-upsert-task action {})]
+              (is (= :ok (:status result)))
+              (is (= [42] (get-in result [:data :result])))
+              (is (= [[:batch-set-property [block-uuids :block/tags 900 {}]]
+                      [:batch-set-property [block-uuids :logseq.property/status :logseq.property/status.todo {}]]
+                      [:batch-set-property [block-uuids :logseq.property/priority :logseq.property/priority.high {}]]
+                      [:batch-set-property [block-uuids :logseq.property/scheduled scheduled-ms {}]]
+                      [:batch-set-property [block-uuids :logseq.property/deadline deadline-ms {}]]]
+                     @ops*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-task-page-clears-task-properties
+  (async done
+    (let [ops* (atom nil)
+          page-uuid (uuid "00000000-0000-0000-0000-000000000042")
+          block-uuids [page-uuid]
+          action {:type :upsert-task
+                  :mode :page
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :page "TaskHome"
+                  :clear-properties [:logseq.property/status
+                                     :logseq.property/priority
+                                     :logseq.property/scheduled
+                                     :logseq.property/deadline]}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/q
+                                               (let [[_ [_query input]] args]
+                                                 (if (= input "taskhome")
+                                                   (p/resolved [{:db/id 42 :block/uuid page-uuid}])
+                                                   (p/resolved [])))
+
+                                               :thread-api/pull
+                                               (let [[_ selector lookup] args]
+                                                 (cond
+                                                   (= lookup [:block/name "taskhome"])
+                                                   (p/resolved {:db/id 42 :block/uuid page-uuid})
+
+                                                   (and (= selector [:db/id :block/uuid])
+                                                        (= lookup 42))
+                                                   (p/resolved {:db/id 42 :block/uuid page-uuid})
+
+                                                   (= lookup [:db/ident :logseq.class/Task])
+                                                   (p/resolved {:db/id 900})
+
+                                                   (and (vector? selector) (= selector [:db/id])
+                                                        (vector? lookup) (= :db/ident (first lookup)))
+                                                   (p/resolved {:db/id 1})
+
+                                                   :else
+                                                   (p/resolved {})))
+
+                                               :thread-api/apply-outliner-ops
+                                               (let [[_ ops _] args]
+                                                 (reset! ops* ops)
+                                                 (p/resolved nil))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method
+                                                                :args args}))))]
+            (p/let [result (upsert-command/execute-upsert-task action {})]
+              (is (= :ok (:status result)))
+              (is (= [42] (get-in result [:data :result])))
+              (is (= [[:batch-remove-property [block-uuids :logseq.property/status]]
+                      [:batch-remove-property [block-uuids :logseq.property/priority]]
+                      [:batch-remove-property [block-uuids :logseq.property/scheduled]]
+                      [:batch-remove-property [block-uuids :logseq.property/deadline]]
+                      [:batch-set-property [block-uuids :block/tags 900 {}]]]
+                     @ops*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-task-update-applies-task-ops
+  (async done
+    (let [ops* (atom nil)
+          node-uuid (uuid "00000000-0000-0000-0000-000000000243")
+          block-uuids [node-uuid]
+          action {:type :upsert-task
+                  :mode :update
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :id 243
+                  :status :logseq.property/status.todo
+                  :priority :logseq.property/priority.high}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ args]
+                                             (case method
+                                               :thread-api/q
+                                               (p/resolved [:logseq.property/status.todo
+                                                            :logseq.property/status.doing
+                                                            :logseq.property/status.done])
+
+                                               :thread-api/pull
+                                               (let [[_ selector lookup] args]
+                                                 (cond
+                                                   (= lookup 243)
+                                                   (p/resolved {:db/id 243 :block/uuid node-uuid})
+
+                                                   (= lookup [:db/ident :logseq.class/Task])
+                                                   (p/resolved {:db/id 900})
+
+                                                   (and (vector? selector) (= selector [:db/id])
+                                                        (vector? lookup) (= :db/ident (first lookup)))
+                                                   (p/resolved {:db/id 1})
+
+                                                   :else
+                                                   (p/resolved {})))
+
+                                               :thread-api/apply-outliner-ops
+                                               (let [[_ ops _] args]
+                                                 (reset! ops* ops)
+                                                 (p/resolved nil))
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method
+                                                                :args args}))))]
+            (p/let [result (upsert-command/execute-upsert-task action {})]
+              (is (= :ok (:status result)))
+              (is (= [243] (get-in result [:data :result])))
+              (is (= [[:batch-set-property [block-uuids :block/tags 900 {}]]
+                      [:batch-set-property [block-uuids :logseq.property/status :logseq.property/status.todo {}]]
+                      [:batch-set-property [block-uuids :logseq.property/priority :logseq.property/priority.high {}]]]
+                     @ops*))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-block-create-invalid-update-properties-is-atomic
+  (async done
+    (let [mutation-called?* (atom false)
+          action {:type :upsert-block
+                  :mode :create
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :target-page-name "Home"
+                  :blocks [{:block/title "Atomic block" :block/uuid (random-uuid)}]
+                  :update-tags ["TagOne"]
+                  :update-properties {:missing-prop "value"}
+                  :pos "last-child"}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          add-command/resolve-tags (fn [_ _ _]
+                                                     (p/resolved [{:db/id 100}]))
+                          add-command/resolve-properties (fn [_ _ _ _]
+                                                           (p/rejected (ex-info "property not found"
+                                                                                {:code :property-not-found
+                                                                                 :property :missing-prop})))
+                          add-command/execute-add-block (fn [_ _]
+                                                          (reset! mutation-called?* true)
+                                                          (p/resolved {:status :ok
+                                                                       :data {:result [1001]}}))]
+            (p/let [result (upsert-command/execute-upsert-block action {})]
+              (is (= :error (:status result)))
+              (is (= :property-not-found (get-in result [:error :code])))
+              (is (= "--update-properties" (get-in result [:error :option])))
+              (is (= :resolve-options (get-in result [:error :phase])))
+              (is (= :missing-prop (get-in result [:error :property])))
+              (is (false? @mutation-called?*)
+                  "must not mutate when one option fails")))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-page-create-invalid-update-properties-is-atomic
+  (async done
+    (let [mutation-called?* (atom false)
+          action {:type :upsert-page
+                  :mode :create
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :page "AtomicPage"
+                  :update-tags ["TagOne"]
+                  :update-properties {:missing-prop "value"}}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          add-command/resolve-tags (fn [_ _ tags]
+                                                     (if (seq tags)
+                                                       (p/resolved [{:db/id 100}])
+                                                       (p/resolved nil)))
+                          add-command/resolve-properties (fn [_ _ _ _]
+                                                           (p/rejected (ex-info "property not found"
+                                                                                {:code :property-not-found
+                                                                                 :property :missing-prop})))
+                          transport/invoke (fn [_ method _ _]
+                                             (when (= :thread-api/apply-outliner-ops method)
+                                               (reset! mutation-called?* true))
+                                             (throw (ex-info "unexpected invoke"
+                                                             {:method method})))]
+            (p/let [result (upsert-command/execute-upsert-page action {})]
+              (is (= :error (:status result)))
+              (is (= :property-not-found (get-in result [:error :code])))
+              (is (= "--update-properties" (get-in result [:error :option])))
+              (is (= :resolve-options (get-in result [:error :phase])))
+              (is (= :missing-prop (get-in result [:error :property])))
+              (is (false? @mutation-called?*)
+                  "must not mutate page when one option fails")))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest test-execute-upsert-task-page-invalid-status-fails-before-mutation
+  (async done
+    (let [calls* (atom [])
+          action {:type :upsert-task
+                  :mode :page
+                  :repo "demo-repo"
+                  :graph "demo-graph"
+                  :page "TaskHome"
+                  :status-input "invalid-status"
+                  :priority :logseq.property/priority.high}]
+      (-> (p/with-redefs [cli-server/ensure-server! (fn [config _repo]
+                                                      (p/resolved (assoc config :base-url "http://example")))
+                          transport/invoke (fn [_ method _ _]
+                                             (swap! calls* conj method)
+                                             (case method
+                                               :thread-api/q
+                                               (p/resolved [:logseq.property/status.todo
+                                                            :logseq.property/status.doing
+                                                            :logseq.property/status.done])
+
+                                               (throw (ex-info "unexpected invoke"
+                                                               {:method method}))))]
+            (p/let [result (upsert-command/execute-upsert-task action {})
+                    message (or (get-in result [:error :message]) "")]
+              (is (= :error (:status result)))
+              (is (= :invalid-options (get-in result [:error :code])))
+              (is (= "--status" (get-in result [:error :option])))
+              (is (= :validate-options (get-in result [:error :phase])))
+              (is (string/includes? message "invalid-status"))
+              (is (= [:thread-api/q] @calls*)
+                  "must fail before page resolution or mutation")))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+
diff --git a/src/test/logseq/cli/commands_test.cljs b/src/test/logseq/cli/commands_test.cljs
new file mode 100644
index 0000000000..54fde7e01c
--- /dev/null
+++ b/src/test/logseq/cli/commands_test.cljs
@@ -0,0 +1,4174 @@
+(ns logseq.cli.commands-test
+  (:require [cljs.test :refer [async deftest is testing]]
+            [babashka.cli :as cli]
+            [clojure.string :as string]
+            [logseq.cli.command.add :as add-command]
+            [logseq.cli.command.graph :as graph-command]
+            [logseq.cli.command.list :as list-command]
+            [logseq.cli.command.query :as query-command]
+            [logseq.cli.command.server :as server-command]
+            [logseq.db.frontend.rules :as rules]
+            [logseq.cli.command.show :as show-command]
+            [logseq.cli.command.sync :as sync-command]
+            [logseq.cli.command.upsert :as upsert-command]
+            [logseq.cli.commands :as commands]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.style :as style]
+            [logseq.cli.transport :as transport]
+            [promesa.core :as p]))
+
+(defn- strip-ansi
+  [value]
+  (style/strip-ansi value))
+
+(defn- contains-ansi?
+  [value]
+  (boolean (re-find style/ansi-pattern value)))
+
+(defn- escape-regex
+  [value]
+  (let [pattern (js/RegExp. "[.*+?^${}()|[\\]\\\\]" "g")]
+    (string/replace value pattern "\\\\$&")))
+
+(defn- contains-bold?
+  [value token]
+  (let [token (escape-regex token)
+        pattern (re-pattern (str "\\u001b\\[[0-9;]*m" token "\\u001b\\[[0-9;]*m"))]
+    (boolean (re-find pattern value))))
+
+(defn- capture-throw-message
+  [f]
+  (try
+    (f)
+    nil
+    (catch :default e
+      (or (ex-message e) (.-message e) (str e)))))
+
+(defn- command-lines
+  [summary]
+  (let [lines (string/split-lines (strip-ansi summary))
+        section (if (some #{"Commands:"} lines) "Commands:" "Subcommands:")
+        start (inc (.indexOf lines section))
+        end (.indexOf lines "Global options:")
+        entries (subvec (vec lines) start end)]
+    (->> entries
+         (filter #(string/starts-with? % "  "))
+         (remove string/blank?))))
+
+(defn- contains-block-uuid?
+  [value]
+  (cond
+    (map? value) (or (contains? value :block/uuid)
+                     (some contains-block-uuid? (vals value)))
+    (sequential? value) (some contains-block-uuid? value)
+    :else false))
+
+(defn- item-ids
+  [result]
+  (mapv :db/id (get-in result [:data :items])))
+
+(deftest test-help-output
+  (testing "top-level help lists command groups"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["--help"]))
+          summary (:summary result)
+          plain-summary (strip-ansi summary)]
+      (is (true? (:help? result)))
+      (is (not (string/includes? plain-summary "--auth-token")))
+      (is (not (string/includes? plain-summary "--retries")))
+      (is (string/includes? plain-summary "Graph Inspect and Edit"))
+      (is (string/includes? plain-summary "Graph Management"))
+      (is (string/includes? plain-summary "Authentication"))
+      (is (string/includes? plain-summary "list"))
+      (is (string/includes? plain-summary "list asset"))
+      (is (string/includes? plain-summary "upsert"))
+      (is (string/includes? plain-summary "upsert asset"))
+      (is (string/includes? plain-summary "remove"))
+      (is (string/includes? plain-summary "query"))
+      (is (string/includes? plain-summary "search"))
+      (is (string/includes? plain-summary "show"))
+      (is (string/includes? plain-summary "doctor"))
+      (is (string/includes? plain-summary "graph"))
+      (is (string/includes? plain-summary "server"))
+      (is (string/includes? plain-summary "sync"))
+      (is (string/includes? plain-summary "login"))
+      (is (string/includes? plain-summary "logout"))
+      (is (string/includes? plain-summary "debug"))
+      (is (not (string/includes? plain-summary "debug pull")))
+      (is (string/includes? plain-summary "completion"))
+      (is (string/includes? plain-summary "example"))
+      (is (not (string/includes? plain-summary "example upsert")))
+      (is (string/includes? plain-summary "skill"))
+      (is (not (string/includes? plain-summary "skill show")))
+      (is (string/includes? plain-summary "Path to CLI root dir (default ~/logseq)"))
+      (is (contains-bold? summary "list page"))
+      (is (contains-bold? summary "list tag"))
+      (is (contains-bold? summary "list property"))
+      (is (contains-bold? summary "list task"))
+      (is (contains-bold? summary "list node"))
+      (is (contains-bold? summary "list asset"))
+      (is (contains-bold? summary "upsert block"))
+      (is (contains-bold? summary "upsert page"))
+      (is (contains-bold? summary "upsert tag"))
+      (is (contains-bold? summary "upsert property"))
+      (is (contains-bold? summary "upsert task"))
+      (is (contains-bold? summary "upsert asset"))
+      (is (contains-bold? summary "remove block"))
+      (is (contains-bold? summary "remove page"))
+      (is (contains-bold? summary "remove tag"))
+      (is (contains-bold? summary "remove property"))
+      (is (contains-bold? summary "query"))
+      (is (contains-bold? summary "query list"))
+      (is (contains-bold? summary "search block"))
+      (is (contains-bold? summary "search page"))
+      (is (contains-bold? summary "search property"))
+      (is (contains-bold? summary "search tag"))
+      (is (contains-bold? summary "show"))
+      (is (contains-bold? summary "doctor"))
+      (is (contains-bold? summary "graph list"))
+      (is (contains-bold? summary "graph create"))
+      (is (contains-bold? summary "server list"))
+      (is (contains-bold? summary "server start"))
+      (is (contains-bold? summary "sync status"))
+      (is (contains-bold? summary "sync start"))
+      (is (contains-bold? summary "login"))
+      (is (contains-bold? summary "logout"))
+      (is (contains-bold? summary "debug"))
+      (is (not (contains-bold? summary "debug pull")))
+      (is (contains-bold? summary "completion"))
+      (is (contains-bold? summary "example"))
+      (is (not (contains-bold? summary "example upsert")))
+      (is (contains-bold? summary "skill"))
+      (is (not (contains-bold? summary "skill show")))
+      (is (contains-bold? summary "--help"))
+      (is (contains-bold? summary "--graph"))
+      (is (re-find #"\u001b\[[0-9;]*mCommands\u001b\[[0-9;]*m:" summary))
+      (is (re-find #"\u001b\[[0-9;]*moptions\u001b\[[0-9;]*m:" summary))))
+
+  (testing "top-level help command list omits [options]"
+    (let [summary (:summary (binding [style/*color-enabled?* true]
+                              (commands/parse-args ["--help"])))
+          lines (command-lines summary)]
+      (is (seq lines))
+      (is (every? #(not (string/includes? % "[options]")) lines))))
+
+  (testing "top-level help separates global and command options"
+    (let [summary (:summary (binding [style/*color-enabled?* true]
+                              (commands/parse-args ["--help"])))
+          plain-summary (strip-ansi summary)]
+      (is (string/includes? plain-summary "Global options:"))
+      (is (string/includes? plain-summary "Command options:")))))
+
+(deftest test-parse-args-help-groups-primary
+  (testing "graph/list/upsert/server groups show subcommands"
+    (doseq [[group plain-entries bold-entries]
+            [["graph"
+              ["graph list" "graph create" "graph export" "graph import"]
+              ["graph list" "graph create" "graph export" "graph import"]]
+             ["list"
+              ["list page" "list tag" "list property" "list task" "list node" "list asset"]
+              ["list page" "list tag" "list property" "list task" "list node" "list asset"]]
+             ["upsert"
+              ["upsert task" "upsert tag" "upsert property" "upsert asset"]
+              ["upsert task" "upsert tag" "upsert property" "upsert asset"]]
+             ["server"
+              ["server list" "server start"]
+              ["server list" "server start"]]]]
+      (let [result (binding [style/*color-enabled?* true]
+                     (commands/parse-args [group]))
+            summary (:summary result)
+            plain-summary (strip-ansi summary)]
+        (is (true? (:help? result)))
+        (doseq [entry plain-entries]
+          (is (string/includes? plain-summary entry)))
+        (doseq [entry bold-entries]
+          (is (contains-bold? summary entry)))
+        (when (= "list" group)
+          (is (string/includes? plain-summary "Global options:"))
+          (is (string/includes? plain-summary "Command options:")))))))
+
+(deftest test-parse-args-help-groups-secondary
+  (testing "query/search/example groups show subcommands"
+    (doseq [[group plain-entries bold-entries]
+            [["query"
+              ["query list" "query"]
+              ["query list" "query"]]
+             ["search"
+              ["search block" "search page" "search property" "search tag"]
+              ["search block" "search page" "search property" "search tag"]]
+             ["example"
+              ["example upsert" "example upsert page" "example show"]
+              ["example upsert" "example show"]]]]
+      (let [result (binding [style/*color-enabled?* true]
+                     (commands/parse-args [group]))
+            summary (:summary result)
+            plain-summary (strip-ansi summary)]
+        (is (true? (:help? result)))
+        (doseq [entry plain-entries]
+          (is (string/includes? plain-summary entry)))
+        (doseq [entry bold-entries]
+          (is (contains-bold? summary entry))))))
+
+  (testing "group help command list omits [options]"
+    (let [summary (:summary (binding [style/*color-enabled?* true]
+                              (commands/parse-args ["list"])))
+          lines (command-lines summary)]
+      (is (seq lines))
+      (is (every? #(not (string/includes? % "[options]")) lines)))))
+
+(deftest test-parse-args-help-debug-group
+  (let [result (binding [style/*color-enabled?* true]
+                 (commands/parse-args ["debug"]))
+        summary (:summary result)
+        plain-summary (strip-ansi summary)]
+    (is (true? (:help? result)))
+    (is (string/includes? plain-summary "debug pull"))
+    (is (contains-bold? summary "debug pull"))))
+
+(deftest test-parse-args-help-skill-group
+  (let [result (binding [style/*color-enabled?* true]
+                 (commands/parse-args ["skill"]))
+        summary (:summary result)
+        plain-summary (strip-ansi summary)]
+    (is (true? (:help? result)))
+    (is (string/includes? plain-summary "skill show"))
+    (is (string/includes? plain-summary "skill install"))
+    (is (contains-bold? summary "skill show"))
+    (is (contains-bold? summary "skill install"))))
+
+(deftest test-parse-args-help-graph-backup-group
+  (let [result (binding [style/*color-enabled?* true]
+                 (commands/parse-args ["graph"]))
+        summary (:summary result)
+        plain-summary (strip-ansi summary)]
+    (is (true? (:help? result)))
+    (is (string/includes? plain-summary "graph backup list"))
+    (is (string/includes? plain-summary "graph backup create"))
+    (is (string/includes? plain-summary "graph backup restore"))
+    (is (string/includes? plain-summary "graph backup remove"))
+    (is (contains-bold? summary "graph backup list"))
+    (is (contains-bold? summary "graph backup create"))
+    (is (contains-bold? summary "graph backup restore"))
+    (is (contains-bold? summary "graph backup remove"))))
+
+(deftest test-parse-args-help-graph-backup-subcommands
+  (doseq [args [["graph" "backup"]
+                ["graph" "backup" "-h"]
+                ["graph" "backup" "--help"]]]
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args args))
+          summary (:summary result)
+          plain-summary (strip-ansi summary)]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "Usage: logseq graph backup <subcommand> [options]"))
+      (is (string/includes? plain-summary "graph backup list"))
+      (is (string/includes? plain-summary "graph backup create"))
+      (is (string/includes? plain-summary "graph backup restore"))
+      (is (string/includes? plain-summary "graph backup remove"))
+      (is (not (string/includes? plain-summary "graph create")))
+      (is (contains-bold? summary "graph backup list"))
+      (is (contains-bold? summary "graph backup create")))))
+
+(deftest test-parse-args-help-command-examples
+  (testing "remove block command help no longer shows examples"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["remove" "block" "--help"]))
+          summary (:summary result)
+          plain-summary (strip-ansi summary)]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "Usage: logseq remove block"))
+      (is (string/includes? plain-summary "Command options:"))
+      (is (not (string/includes? plain-summary "Examples:")))
+      (is (contains-bold? summary "--id"))
+      (is (contains-bold? summary "--uuid"))))
+
+  (testing "sync config set command help no longer shows examples"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["sync" "config" "set" "--help"]))
+          plain-summary (strip-ansi (:summary result))]
+      (is (true? (:help? result)))
+      (is (not (string/includes? plain-summary "Examples:")))
+      (is (not (string/includes? plain-summary "logseq sync config set ws-url wss://sync.logseq.com")))
+      (is (not (string/includes? plain-summary "logseq sync config set http-base http://localhost:8080")))))
+
+  (testing "upsert block command help no longer shows examples"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["upsert" "block" "--help"]))
+          summary (:summary result)
+          plain-summary (strip-ansi summary)]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "Usage: logseq upsert block"))
+      (is (string/includes? plain-summary "Command options:"))
+      (is (not (string/includes? plain-summary "Examples:")))
+      (is (contains-bold? summary "--id"))
+      (is (contains-bold? summary "--uuid"))
+      (is (contains-bold? summary "--content"))
+      (is (contains-bold? summary "--target-id"))
+      (is (contains-bold? summary "--target-uuid"))
+      (is (contains-bold? summary "--update-tags"))
+      (is (contains-bold? summary "--update-properties"))
+      (is (contains-bold? summary "--remove-tags"))
+      (is (contains-bold? summary "--remove-properties"))))
+
+  (testing "example command help is the place that shows examples"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["example" "upsert" "--help"]))
+          plain-summary (strip-ansi (:summary result))]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "Usage: logseq example upsert"))
+      (is (string/includes? plain-summary "Examples:"))
+      (is (string/includes? plain-summary "logseq upsert block --graph my-graph --target-page Home --content \"New block\"")))))
+
+(deftest test-parse-args-group-help-flags
+  (testing "all groups show group help with -h and --help"
+    ;; query and example are excluded: they are both groups and exact commands,
+    ;; so -h shows their command help with options instead of group subcommand listing
+    (doseq [group ["graph" "server" "list" "upsert" "remove" "search" "sync" "debug" "skill"]
+            help-flag ["-h" "--help"]]
+      (let [result (binding [style/*color-enabled?* true]
+                     (commands/parse-args [group help-flag]))
+            plain-summary (strip-ansi (:summary result))]
+        (is (true? (:help? result)))
+        (is (string/includes? plain-summary (str "Usage: logseq " group " <subcommand> [options]"))))))
+
+  (testing "upsert block command short help flag shows command help"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["upsert" "block" "-h"]))
+          plain-summary (strip-ansi (:summary result))]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "Usage: logseq upsert block"))
+      (is (not (string/includes? plain-summary "Usage: logseq upsert <subcommand> [options]")))))
+
+  (testing "query -h shows command help with options (not group help)"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["query" "-h"]))
+          plain-summary (strip-ansi (:summary result))]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "--query"))
+      (is (string/includes? plain-summary "--name"))
+      (is (string/includes? plain-summary "--inputs"))))
+
+  (testing "example query executes (not group help)"
+    (let [result (commands/parse-args ["example" "query"])]
+      (is (= :example (:command result)))
+      (is (not (:help? result)))))
+
+  )
+
+(deftest test-parse-args-example-selectors
+  (testing "example supports exact selectors"
+    (doseq [args [["example" "upsert" "page"]
+                  ["example" "show"]
+                  ["example" "search" "block"]]]
+      (let [result (commands/parse-args args)]
+        (is (true? (:ok? result)))
+        (is (= :example (:command result))))))
+
+  (testing "example supports prefix selectors"
+    (doseq [args [["example" "upsert"]
+                  ["example" "list"]
+                  ["example" "query"]]]
+      (let [result (commands/parse-args args)]
+        (is (true? (:ok? result)))
+        (is (= :example (:command result))))))
+
+  (testing "example rejects uncovered selectors"
+    (let [result (commands/parse-args ["example" "graph"])]
+      (is (false? (:ok? result)))
+      (is (= :unknown-command (get-in result [:error :code]))))))
+
+(deftest test-parse-args-help-auth-commands
+  (testing "login command shows help"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["login" "--help"]))
+          summary (:summary result)
+          plain-summary (strip-ansi summary)]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "Usage: logseq login"))
+      (is (string/includes? plain-summary "Global options:"))
+      (is (string/includes? plain-summary "Command options:"))
+      (is (not (string/includes? plain-summary "Examples:")))))
+
+  (testing "logout command shows help"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["logout" "--help"]))
+          summary (:summary result)
+          plain-summary (strip-ansi summary)]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "Usage: logseq logout"))
+      (is (string/includes? plain-summary "Global options:"))
+      (is (string/includes? plain-summary "Command options:"))
+      (is (not (string/includes? plain-summary "Examples:"))))))
+
+(deftest test-parse-args-help-sync-group
+  (testing "sync group shows subcommands"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["sync"]))
+          summary (:summary result)
+          plain-summary (strip-ansi summary)]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "sync status"))
+      (is (string/includes? plain-summary "sync start"))
+      (is (string/includes? plain-summary "sync stop"))
+      (is (string/includes? plain-summary "sync upload"))
+      (is (string/includes? plain-summary "sync download"))
+      (is (string/includes? plain-summary "sync remote-graphs"))
+      (is (string/includes? plain-summary "sync ensure-keys"))
+      (is (string/includes? plain-summary "sync grant-access"))
+      (is (string/includes? plain-summary "sync config set"))
+      (is (string/includes? plain-summary "sync config get"))
+      (is (string/includes? plain-summary "sync config unset"))
+      (is (contains-bold? summary "sync status"))
+      (is (contains-bold? summary "sync config set"))
+      (is (contains-bold? summary "sync grant-access")))))
+
+(deftest test-parse-args-help-upsert-group
+  (testing "add group is removed"
+    (let [result (commands/parse-args ["add"])]
+      (is (false? (:ok? result)))
+      (is (= :unknown-command (get-in result [:error :code])))))
+
+  (testing "upsert group shows subcommands"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["upsert"]))
+          summary (:summary result)
+          plain-summary (strip-ansi summary)]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "upsert block"))
+      (is (string/includes? plain-summary "upsert page"))
+      (is (string/includes? plain-summary "upsert tag"))
+      (is (string/includes? plain-summary "upsert property"))
+      (is (string/includes? plain-summary "upsert task"))
+      (is (string/includes? plain-summary "upsert asset"))
+      (is (contains-bold? summary "upsert block"))
+      (is (contains-bold? summary "upsert page"))
+      (is (contains-bold? summary "upsert tag"))
+      (is (contains-bold? summary "upsert property"))
+      (is (contains-bold? summary "upsert task"))
+      (is (contains-bold? summary "upsert asset")))))
+
+(deftest test-parse-args-help-alignment
+  (testing "graph group aligns subcommand columns"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["graph"]))
+          summary (strip-ansi (:summary result))
+          subcommand-lines (let [lines (string/split-lines summary)
+                                 start (inc (.indexOf lines "Subcommands:"))]
+                             (->> lines
+                                  (drop start)
+                                  (take-while (complement string/blank?))))
+          desc-starts (->> subcommand-lines
+                           (keep (fn [line]
+                                   (when-let [[_ desc] (re-matches #"^\s+.*?\s{2,}(.+)$" line)]
+                                     (.indexOf line desc)))))]
+      (is (seq subcommand-lines))
+      (is (apply = desc-starts))))
+
+  (testing "list group aligns subcommand columns"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["list"]))
+          summary (strip-ansi (:summary result))
+          subcommand-lines (let [lines (string/split-lines summary)
+                                 start (inc (.indexOf lines "Subcommands:"))]
+                             (->> lines
+                                  (drop start)
+                                  (take-while (complement string/blank?))))
+          desc-starts (->> subcommand-lines
+                           (keep (fn [line]
+                                   (when-let [[_ desc] (re-matches #"^\s+.*?\s{2,}(.+)$" line)]
+                                     (.indexOf line desc)))))]
+      (is (seq subcommand-lines))
+      (is (apply = desc-starts)))))
+
+(deftest test-parse-args-errors
+  (testing "rejects legacy commands"
+    (doseq [command ["graph-list" "graph-create" "graph-switch" "graph-remove"
+                     "graph-validate" "graph-info" "block" "tree"
+                     "ping" "status" "export"]]
+      (let [result (commands/parse-args [command])]
+        (is (false? (:ok? result)))
+        (is (= :unknown-command (get-in result [:error :code]))))))
+
+  (testing "rejects removed group commands"
+    (doseq [args [["block" "add"]
+                  ["block" "remove"]
+                  ["block" "search"]
+                  ["block" "tree"]
+                  ["content" "add"]]]
+      (let [result (commands/parse-args args)]
+        (is (false? (:ok? result)))
+        (is (= :unknown-command (get-in result [:error :code]))))))
+
+  (testing "rejects removed write commands"
+    (doseq [args [["add" "block" "--content" "x"]
+                  ["add" "page" "--page" "Home"]
+                  ["update" "--id" "1" "--update-tags" "[\"TagA\"]"]]]
+      (let [result (commands/parse-args args)]
+        (is (false? (:ok? result)))
+        (is (= :unknown-command (get-in result [:error :code]))))))
+
+  (testing "no commands prints help"
+    (let [result (commands/parse-args [])]
+      (is (false? (:ok? result)))
+      (is (true? (:help? result)))))
+
+  (testing "errors on unknown command"
+    (let [result (commands/parse-args ["wat"])]
+      (is (false? (:ok? result)))
+      (is (= :unknown-command (get-in result [:error :code]))))))
+
+(deftest test-parse-args-rethrows-unexpected-dispatch-errors
+  (with-redefs [cli/dispatch (fn [& _]
+                               (throw (js/Error. "dispatch exploded")))]
+    (let [message (capture-throw-message #(commands/parse-args ["graph" "list"]))]
+      (is (string/includes? (or message "") "dispatch exploded")))))
+
+(deftest test-parse-args-remove-help-and-rejects-add-tag
+  (testing "bare remove shows remove subcommand help"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["remove"]))
+          summary (:summary result)
+          plain-summary (strip-ansi summary)]
+      (is (true? (:help? result)))
+      (is (string/includes? plain-summary "remove block"))
+      (is (string/includes? plain-summary "remove page"))
+      (is (string/includes? plain-summary "remove tag"))
+      (is (string/includes? plain-summary "remove property"))
+      (is (contains-bold? summary "remove block"))
+      (is (contains-bold? summary "remove page"))
+      (is (contains-bold? summary "remove tag"))
+      (is (contains-bold? summary "remove property"))))
+
+  (testing "rejects removed add tag command"
+    (let [result (commands/parse-args ["add" "tag" "--name" "Quote"])]
+      (is (false? (:ok? result)))
+      (is (= :unknown-command (get-in result [:error :code]))))))
+
+(deftest test-parse-args-global-options
+  (testing "global output option is accepted"
+    (let [result (commands/parse-args ["--output" "json" "graph" "list"])]
+      (is (true? (:ok? result)))
+      (is (= "json" (get-in result [:options :output])))))
+
+  (testing "global output option rejects invalid values"
+    (let [result (commands/parse-args ["--output" "yaml" "graph" "list"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? (string/lower-case (get-in result [:error :message])) "output"))))
+
+  (testing "global profile option defaults to absent"
+    (let [result (commands/parse-args ["graph" "list"])]
+      (is (true? (:ok? result)))
+      (is (nil? (get-in result [:options :profile])))))
+
+  (testing "global profile option is accepted as boolean flag"
+    (let [result (commands/parse-args ["--profile" "graph" "list"])]
+      (is (true? (:ok? result)))
+      (is (= true (get-in result [:options :profile])))))
+
+  (testing "-c is no longer a global alias for --config"
+    (let [result (commands/parse-args ["-c" "/tmp/cli.edn" "graph" "list"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code]))))))
+
+(deftest test-parse-args-doctor
+  (testing "doctor command parses"
+    (let [result (commands/parse-args ["doctor"])]
+      (is (true? (:ok? result)))
+      (is (= :doctor (:command result)))))
+
+  (testing "doctor command parses explicit dev script option"
+    (let [result (commands/parse-args ["doctor" "--dev-script"])]
+      (is (true? (:ok? result)))
+      (is (= :doctor (:command result)))
+      (is (= true (get-in result [:options :dev-script]))))))
+
+(deftest test-tree->text-format
+  (testing "show tree text uses db/id with tree glyphs"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child A"
+                                              :block/children [{:db/id 3
+                                                                :block/title "Grandchild A1"}]}
+                                             {:db/id 4
+                                              :block/title "Child B"}]}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (contains-ansi? output))
+      (is (string/includes? output (style/dim "├── ")))
+      (is (string/includes? output (style/dim "└── ")))
+      (is (string/includes? output (style/dim "│   ")))
+      (is (= (str "1 Root\n"
+                  "2 ├── Child A\n"
+                  "3 │   └── Grandchild A1\n"
+                  "4 └── Child B")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-dims-id-column
+  (testing "show tree text dims the id column"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child"}]}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (contains-ansi? output))
+      (is (string/includes? output (style/dim "1")))
+      (is (string/includes? output (style/dim "2")))
+      (is (= (str "1 Root\n"
+                  "2 └── Child")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-aligns-mixed-id-widths
+  (testing "show tree text aligns glyph column with mixed-width ids"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 7
+                            :block/title "Root"
+                            :block/children [{:db/id 88
+                                              :block/title "Child A"
+                                              :block/children [{:db/id 3
+                                                                :block/title "Grand"}]}
+                                             {:db/id 1000
+                                              :block/title "Child B"}]}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (= (str "7    Root\n"
+                  "88   ├── Child A\n"
+                  "3    │   └── Grand\n"
+                  "1000 └── Child B")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-multiline
+  (testing "show tree text renders multiline blocks under glyph column"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 168
+                            :block/title "Jan 18th, 2026"
+                            :block/children [{:db/id 169
+                                              :block/title "b1"}
+                                             {:db/id 173
+                                              :block/title "aaaxx"}
+                                             {:db/id 174
+                                              :block/title "block-line1\nblock-line2"}
+                                             {:db/id 175
+                                              :block/title "cccc"}]}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (= (str "168 Jan 18th, 2026\n"
+                  "169 ├── b1\n"
+                  "173 ├── aaaxx\n"
+                  "174 ├── block-line1\n"
+                  "    │   block-line2\n"
+                  "175 └── cccc")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-renders-properties-single-value
+  (testing "show tree text renders user properties below block labels"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child A"
+                                              :user.property/background "Because"}
+                                             {:db/id 3
+                                              :block/title "Child B"}]}
+                     :property-titles {:user.property/background "Background"}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (contains-bold? output "Background"))
+      (is (= (str "1 Root\n"
+                  "2 ├── Child A\n"
+                  "  │   Background: Because\n"
+                  "3 └── Child B")
+             (strip-ansi output)))
+      (is (not (string/includes? output "└── Background"))))))
+
+(deftest test-tree->text-renders-properties-multi-value
+  (testing "show tree text renders multi-value properties as a list"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child A"
+                                              :user.property/criteria ["One" "Two"]}
+                                             {:db/id 3
+                                              :block/title "Child B"}]}
+                     :property-titles {:user.property/criteria "Criteria"}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (contains-bold? output "Criteria"))
+      (is (not (contains-bold? output "- One")))
+      (is (not (contains-bold? output "- Two")))
+      (is (= (str "1 Root\n"
+                  "2 ├── Child A\n"
+                  "  │   Criteria:\n"
+                  "  │     - One\n"
+                  "  │     - Two\n"
+                  "3 └── Child B")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-renders-properties-map-value
+  (testing "show tree text renders literal map property values"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child A"
+                                              :user.property/config {:a 1 :b 2}}
+                                             {:db/id 3
+                                              :block/title "Child B"}]}
+                     :property-titles {:user.property/config "Config"}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (contains-bold? output "Config"))
+      (is (= (str "1 Root\n"
+                  "2 ├── Child A\n"
+                  "  │   Config: {:a 1, :b 2}\n"
+                  "3 └── Child B")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-properties-order
+  (testing "show tree text renders user properties in stable key order"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :user.property/zeta "Last"
+                            :user.property/alpha "First"}
+                     :property-titles {:user.property/zeta "Zeta"
+                                       :user.property/alpha "Alpha"}}
+          output (strip-ansi (tree->text tree-data))
+          alpha-idx (.indexOf output "Alpha:")
+          zeta-idx (.indexOf output "Zeta:")]
+      (is (<= 0 alpha-idx))
+      (is (<= 0 zeta-idx))
+      (is (< alpha-idx zeta-idx)))))
+
+(deftest test-tree->text-properties-multiline-alignment
+  (testing "show tree text keeps multiline alignment with properties"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root line1\nRoot line2"
+                            :user.property/background "Root prop"
+                            :block/children [{:db/id 22
+                                              :block/title "Child line1\nChild line2"
+                                              :user.property/notes "Child prop"}]}
+                     :property-titles {:user.property/background "Background"
+                                       :user.property/notes "Notes"}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (= (str "1  Root line1\n"
+                  "   Root line2\n"
+                  "   Background: Root prop\n"
+                  "22 └── Child line1\n"
+                  "       Child line2\n"
+                  "       Notes: Child prop")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-properties-dont-render-as-children
+  (testing "show tree text does not render property values as children"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :user.property/background "Child"}
+                     :property-titles {:user.property/background "Background"}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))
+          output* (strip-ansi output)]
+      (is (string/includes? output* "Background: Child"))
+      (is (not (string/includes? output* "└── Child")))
+      (is (not (string/includes? output* "├── Child"))))))
+
+(deftest test-tree->text-prefixes-status
+  (testing "show tree text prefixes status before block titles"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :logseq.property/status {:db/ident :logseq.property/status.todo
+                                                     :block/title "TODO"}
+                            :block/children [{:db/id 2
+                                              :block/title "Child"
+                                              :logseq.property/status {:db/ident :logseq.property/status.canceled
+                                                                       :block/title "CANCELED"}}]}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (string/includes? output
+                            (binding [style/*color-enabled?* true]
+                              (style/bold (style/yellow "TODO")))))
+      (is (string/includes? output
+                            (binding [style/*color-enabled?* true]
+                              (style/bold (style/red "CANCELED")))))
+      (is (= (str "1 TODO Root\n"
+                  "2 └── CANCELED Child")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-status-multiline-alignment
+  (testing "show tree text keeps multiline alignment when status prefix is present"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 22
+                                              :block/title "line1\nline2"
+                                              :logseq.property/status {:db/ident :logseq.property/status.todo
+                                                                       :block/title "TODO"}}]}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (= (str "1  Root\n"
+                  "22 └── TODO line1\n"
+                  "       line2")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-linked-references-tree
+  (testing "show tree text renders linked references as trees with db/id in first column"
+    (let [tree->text-with-linked-refs #'show-command/tree->text-with-linked-refs
+          tree-data {:root {:db/id 1
+                            :block/title "Root"}
+                     :linked-references {:count 2
+                                         :blocks [{:db/id 10
+                                                   :block/title "Ref A"
+                                                   :logseq.property/status {:db/ident :logseq.property/status.todo
+                                                                            :block/title "TODO"}
+                                                   :block/page {:db/id 100
+                                                                :block/title "Page A"}}
+                                                  {:db/id 11
+                                                   :block/title "Ref B"
+                                                   :block/page {:db/id 101
+                                                                :block/title "Page B"}}]}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text-with-linked-refs tree-data))]
+      (is (re-find #"\u001b\[[0-9;]*mTODO" output))
+      (is (= (str "1 Root\n"
+                  "\n"
+                  "Linked References (2)\n"
+                  "100 Page A\n"
+                  "10  └── TODO Ref A\n"
+                  "\n"
+                  "101 Page B\n"
+                  "11  └── Ref B")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-appends-tags
+  (testing "show tree text appends block tags to content"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child"
+                                              :block/tags [{:block/title "RTC"}
+                                                           {:block/name "task"}]}]}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (string/includes? output (style/bold "#RTC")))
+      (is (string/includes? output (style/bold "#task")))
+      (is (= (str "1 Root\n"
+                  "2 └── Child #RTC #task")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-status-colors
+  (testing "show tree text uses green for DONE status"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child"
+                                              :logseq.property/status {:db/ident :logseq.property/status.done
+                                                                       :block/title "DONE"}}]}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (string/includes? output (style/green "DONE")))
+      (is (= (str "1 Root\n"
+                  "2 └── DONE Child")
+             (strip-ansi output))))))
+
+(deftest test-tree->text-replaces-uuid-refs
+  (testing "show tree text replaces inline [[uuid]] with referenced block content recursively"
+    (let [tree->text #'show-command/tree->text
+          uuid "11111111-1111-1111-1111-111111111111"
+          nested "22222222-2222-2222-2222-222222222222"
+          tree-data {:root {:db/id 1
+                            :block/title (str "See [[" uuid "]]")}
+                     :uuid->label {(string/lower-case uuid) (str "Target [[" nested "]]")
+                                   (string/lower-case nested) "Inner"}}
+          output (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))]
+      (is (= "1 See [[Target [[Inner]]]]"
+             (strip-ansi output))))))
+
+(deftest test-help-upsert-update-options
+  (testing "upsert block help includes update options and removes legacy flags"
+    (let [summary (:summary (binding [style/*color-enabled?* true]
+                              (commands/parse-args ["upsert" "block" "--help"])))]
+      (is (string/includes? (strip-ansi summary) "--update-tags"))
+      (is (string/includes? (strip-ansi summary) "--update-properties"))
+      (is (not (string/includes? (strip-ansi summary) "--tags")))
+      (is (not (string/includes? (strip-ansi summary) "--properties")))))
+
+  (testing "upsert page help includes update options and removes legacy flags"
+    (let [summary (:summary (binding [style/*color-enabled?* true]
+                              (commands/parse-args ["upsert" "page" "--help"])))]
+      (is (string/includes? (strip-ansi summary) "--id"))
+      (is (string/includes? (strip-ansi summary) "--update-tags"))
+      (is (string/includes? (strip-ansi summary) "--update-properties"))
+      (is (not (string/includes? (strip-ansi summary) "--tags")))
+      (is (not (string/includes? (strip-ansi summary) "--properties")))))
+
+  (testing "upsert task help includes paired task set/clear options"
+    (let [summary (strip-ansi (:summary (binding [style/*color-enabled?* true]
+                                          (commands/parse-args ["upsert" "task" "--help"]))))]
+      (is (string/includes? summary "--status"))
+      (is (string/includes? summary "--priority"))
+      (is (string/includes? summary "--scheduled"))
+      (is (string/includes? summary "--deadline"))
+      (is (string/includes? summary "--no-status"))
+      (is (string/includes? summary "--no-priority"))
+      (is (string/includes? summary "--no-scheduled"))
+      (is (string/includes? summary "--no-deadline"))
+      (is (not (string/includes? summary "--update-tags")))
+      (is (not (string/includes? summary "--update-properties")))
+      (is (not (string/includes? summary "--remove-tags")))
+      (is (not (string/includes? summary "--remove-properties"))))))
+
+(deftest test-show-json-edn-strips-block-uuid
+  (testing "show json/edn removes :block/uuid recursively while keeping :db/id"
+    (let [tree-data {:root {:db/id 1
+                            :block/uuid "root-uuid"
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/uuid "child-uuid"
+                                              :block/title "Child"
+                                              :block/tags [{:db/id 3
+                                                            :block/uuid "tag-uuid"
+                                                            :block/title "Tag"}]}]}
+                     :linked-references {:count 1
+                                         :blocks [{:db/id 4
+                                                   :block/uuid "ref-uuid"
+                                                   :block/page {:db/id 5
+                                                                :block/uuid "page-uuid"
+                                                                :block/title "Page"}}]}
+                     :uuid->label {"root-uuid" "Root"}}
+          stripped (#'show-command/strip-block-uuid tree-data)]
+      (is (not (contains-block-uuid? stripped)))
+      (is (= 1 (get-in stripped [:root :db/id])))
+      (is (= 2 (get-in stripped [:root :block/children 0 :db/id]))))))
+
+(deftest test-show-selectors-include-db-ident
+  (async done
+         (let [selectors (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/pull (let [[_ selector _] args]
+                                                                       (swap! selectors conj selector)
+                                                                       (p/resolved {:db/id 1
+                                                                                    :block/page {:db/id 2}}))
+                                                    :thread-api/q (let [[_ [query _]] args
+                                                                        pull-form (second query)
+                                                                        selector (when (and (seq? pull-form)
+                                                                                            (= 'pull (first pull-form)))
+                                                                                   (nth pull-form 2))]
+                                                                    (when selector
+                                                                      (swap! selectors conj selector))
+                                                                    (p/resolved []))
+                                                    :thread-api/get-block-refs (p/resolved [{:db/id 10}])
+                                                    (p/resolved nil)))]
+                 (p/let [_ (show-command/execute-show {:type :show
+                                                       :repo "demo"
+                                                       :id 1}
+                                                      {:output-format :json})]
+                   (is (some #(some #{:db/ident} %) @selectors))
+                   (is (some #(and (some #{:db/ident} %)
+                                   (some (fn [entry]
+                                           (and (map? entry)
+                                                (contains? entry :block/page)))
+                                         %))
+                             @selectors))
+                   (is (some (fn [selector]
+                               (and (some #{:logseq.property/created-from-property} selector)
+                                    (some (fn [entry]
+                                            (and (map? entry)
+                                                 (contains? entry :block/page)))
+                                          selector)
+                                    (some (fn [entry]
+                                            (and (map? entry)
+                                                 (contains? entry :block/tags)
+                                                 (some #{:db/ident} (:block/tags entry))))
+                                          selector)))
+                             @selectors))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-show-linked-references-disabled
+  (async done
+         (let [method-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                               transport/invoke (fn [_ method _ _]
+                                                  (swap! method-calls conj method)
+                                                  (case method
+                                                    :thread-api/pull (p/resolved {:db/id 1
+                                                                                  :block/page {:db/id 2}})
+                                                    :thread-api/q (p/resolved [])
+                                                    :thread-api/get-block-refs (p/resolved [{:db/id 10}])
+                                                    (p/resolved nil)))]
+                 (p/let [result (show-command/execute-show {:type :show
+                                                            :repo "demo"
+                                                            :id 1
+                                                            :linked-references? false}
+                                                           {:output-format :json})]
+                   (is (= :ok (:status result)))
+                   (is (not (contains? (:data result) :linked-references)))
+                   (is (not (some #{:thread-api/get-block-refs} @method-calls)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-show-linked-references-enabled
+  (async done
+         (let [method-calls (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                               transport/invoke (fn [_ method _ _]
+                                                  (swap! method-calls conj method)
+                                                  (case method
+                                                    :thread-api/pull (p/resolved {:db/id 1
+                                                                                  :block/page {:db/id 2}})
+                                                    :thread-api/q (p/resolved [])
+                                                    :thread-api/get-block-refs (p/resolved [{:db/id 10}])
+                                                    (p/resolved nil)))]
+                 (p/let [result (show-command/execute-show {:type :show
+                                                            :repo "demo"
+                                                            :id 1
+                                                            :linked-references? true}
+                                                           {:output-format :json})]
+                   (is (= :ok (:status result)))
+                   (is (contains? (:data result) :linked-references))
+                   (is (some #{:thread-api/get-block-refs} @method-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-show-id-only-entity-is-not-found
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                             transport/invoke (fn [_ method _ _]
+                                                (case method
+                                                  :thread-api/pull (p/resolved {:db/id 212})
+                                                  :thread-api/q (p/resolved [])
+                                                  :thread-api/get-block-refs (p/resolved [])
+                                                  (p/resolved nil)))]
+               (show-command/execute-show {:type :show
+                                           :repo "demo"
+                                           :id 212}
+                                          {:output-format :json}))
+             (p/then (fn [_]
+                       (is false "expected execute-show to reject for id-only entity")))
+             (p/catch (fn [e]
+                        (is (= :entity-not-found (:code (ex-data e))))))
+             (p/finally done))))
+
+(deftest test-tree->text-uuid-ref-recursion-limit
+  (testing "show tree text limits uuid ref replacement depth"
+    (let [tree->text #'show-command/tree->text
+          uuids ["00000000-0000-0000-0000-000000000001"
+                 "00000000-0000-0000-0000-000000000002"
+                 "00000000-0000-0000-0000-000000000003"
+                 "00000000-0000-0000-0000-000000000004"
+                 "00000000-0000-0000-0000-000000000005"
+                 "00000000-0000-0000-0000-000000000006"
+                 "00000000-0000-0000-0000-000000000007"
+                 "00000000-0000-0000-0000-000000000008"
+                 "00000000-0000-0000-0000-000000000009"
+                 "00000000-0000-0000-0000-000000000010"
+                 "00000000-0000-0000-0000-000000000011"]
+          uuid->label (into {}
+                            (map-indexed (fn [idx id]
+                                           (let [label (if (< idx 10)
+                                                         (str "L" (inc idx) " [[" (nth uuids (inc idx)) "]]")
+                                                         (str "L" (inc idx)))]
+                                             [(string/lower-case id) label]))
+                                         uuids))
+          tree-data {:root {:db/id 1
+                            :block/title (str "Root [[" (first uuids) "]]")}
+                     :uuid->label uuid->label}
+          result (tree->text tree-data)]
+      (is (string/includes? result (str "[[" (nth uuids 10) "]]"))))))
+
+(deftest ^:large-vars/cleanup-todo test-list-subcommand-parse
+  (testing "list page parses"
+    (let [result (commands/parse-args ["list" "page"
+                                       "--expand"
+                                       "--include-journal"
+                                       "--limit" "10"
+                                       "--offset" "5"
+                                       "--sort" "updated-at"
+                                       "--order" "desc"
+                                       "--fields" "title,updated-at"])]
+      (is (true? (:ok? result)))
+      (is (= :list-page (:command result)))
+      (is (true? (get-in result [:options :expand])))
+      (is (true? (get-in result [:options :include-journal])))
+      (is (= 10 (get-in result [:options :limit])))
+      (is (= 5 (get-in result [:options :offset])))
+      (is (= "updated-at" (get-in result [:options :sort])))
+      (is (= "desc" (get-in result [:options :order])))
+      (is (= "title,updated-at" (get-in result [:options :fields])))))
+
+  (testing "list tag parses"
+    (let [result (commands/parse-args ["list" "tag"
+                                       "--expand"
+                                       "--include-built-in"
+                                       "--with-properties"
+                                       "--with-extends"
+                                       "--fields" "name,properties"])]
+      (is (true? (:ok? result)))
+      (is (= :list-tag (:command result)))
+      (is (true? (get-in result [:options :expand])))
+      (is (true? (get-in result [:options :include-built-in])))
+      (is (true? (get-in result [:options :with-properties])))
+      (is (true? (get-in result [:options :with-extends])))
+      (is (= "name,properties" (get-in result [:options :fields])))))
+
+  (testing "list property parses"
+    (let [result (commands/parse-args ["list" "property"
+                                       "--expand"
+                                       "--include-built-in"
+                                       "--with-classes"
+                                       "--with-type"
+                                       "--sort" "cardinality"
+                                       "--fields" "name,type,cardinality"])]
+      (is (true? (:ok? result)))
+      (is (= :list-property (:command result)))
+      (is (true? (get-in result [:options :expand])))
+      (is (true? (get-in result [:options :include-built-in])))
+      (is (true? (get-in result [:options :with-classes])))
+      (is (true? (get-in result [:options :with-type])))
+      (is (= "cardinality" (get-in result [:options :sort])))
+      (is (= "name,type,cardinality" (get-in result [:options :fields])))))
+
+  (testing "list task parses"
+    (let [result (commands/parse-args ["list" "task"
+                                       "--status" "doing"
+                                       "--priority" "high"
+                                       "--content" "alpha"
+                                       "--fields" "id,title,status,priority"
+                                       "--limit" "10"
+                                       "--offset" "2"
+                                       "--sort" "priority"
+                                       "--order" "desc"])]
+      (is (true? (:ok? result)))
+      (is (= :list-task (:command result)))
+      (is (= "doing" (get-in result [:options :status])))
+      (is (= "high" (get-in result [:options :priority])))
+      (is (= "alpha" (get-in result [:options :content])))
+      (is (= "id,title,status,priority" (get-in result [:options :fields])))
+      (is (= 10 (get-in result [:options :limit])))
+      (is (= 2 (get-in result [:options :offset])))
+      (is (= "priority" (get-in result [:options :sort])))
+      (is (= "desc" (get-in result [:options :order])))))
+
+  (testing "list task supports short -c alias for --content"
+    (let [result (commands/parse-args ["list" "task" "-c" "alpha"])]
+      (is (true? (:ok? result)))
+      (is (= :list-task (:command result)))
+      (is (= "alpha" (get-in result [:options :content])))))
+
+  (testing "list node parses with tags/properties and common options"
+    (let [result (commands/parse-args ["list" "node"
+                                       "--tags" "project,work"
+                                       "--properties" "status,priority"
+                                       "--fields" "id,title,type,updated-at"
+                                       "--limit" "10"
+                                       "--offset" "2"
+                                       "--sort" "updated-at"
+                                       "--order" "desc"])]
+      (is (true? (:ok? result)))
+      (is (= :list-node (:command result)))
+      (is (= "project,work" (get-in result [:options :tags])))
+      (is (= "status,priority" (get-in result [:options :properties])))
+      (is (= "id,title,type,updated-at" (get-in result [:options :fields])))
+      (is (= 10 (get-in result [:options :limit])))
+      (is (= 2 (get-in result [:options :offset])))
+      (is (= "updated-at" (get-in result [:options :sort])))
+      (is (= "desc" (get-in result [:options :order])))))
+
+  (testing "list asset parses with common list options"
+    (let [result (commands/parse-args ["list" "asset"
+                                       "--fields" "id,title,asset-type,size,updated-at"
+                                       "--limit" "5"
+                                       "--offset" "1"
+                                       "--sort" "updated-at"
+                                       "--order" "desc"])]
+      (is (true? (:ok? result)))
+      (is (= :list-asset (:command result)))
+      (is (= "id,title,asset-type,size,updated-at" (get-in result [:options :fields])))
+      (is (= 5 (get-in result [:options :limit])))
+      (is (= 1 (get-in result [:options :offset])))
+      (is (= "updated-at" (get-in result [:options :sort])))
+      (is (= "desc" (get-in result [:options :order])))))
+
+  (testing "list command help shows default sort and order"
+    (let [result (binding [style/*color-enabled?* true]
+                   (commands/parse-args ["list" "page" "--help"]))
+          summary (strip-ansi (:summary result))]
+      (is (string/includes? summary "Sort field. Default: updated-at"))
+      (is (string/includes? summary "Sort order. Default: desc")))))
+
+(deftest test-search-subcommand-parse
+  (testing "search block parses --content option"
+    (let [result (commands/parse-args ["search" "block" "--content" "Alpha"])]
+      (is (true? (:ok? result)))
+      (is (= :search-block (:command result)))
+      (is (= "Alpha" (get-in result [:options :content])))
+      (is (= [] (:args result)))))
+
+  (testing "search page parses multi-word --content value"
+    (let [result (commands/parse-args ["search" "page" "--content" "project notes"])]
+      (is (true? (:ok? result)))
+      (is (= :search-page (:command result)))
+      (is (= "project notes" (get-in result [:options :content])))))
+
+  (testing "search property parses"
+    (let [result (commands/parse-args ["search" "property" "--content" "owner"])]
+      (is (true? (:ok? result)))
+      (is (= :search-property (:command result)))))
+
+  (testing "search tag parses"
+    (let [result (commands/parse-args ["search" "tag" "--content" "quote"])]
+      (is (true? (:ok? result)))
+      (is (= :search-tag (:command result)))))
+
+  (testing "search block preserves --content with trailing global option"
+    (let [result (commands/parse-args ["search" "block" "--content" "alpha" "--output" "json"])]
+      (is (true? (:ok? result)))
+      (is (= "alpha" (get-in result [:options :content])))
+      (is (= "json" (get-in result [:options :output])))
+      (is (= [] (:args result)))))
+
+  (testing "search block supports short -c alias for --content"
+    (let [result (commands/parse-args ["search" "block" "-c" "Alpha"])]
+      (is (true? (:ok? result)))
+      (is (= :search-block (:command result)))
+      (is (= "Alpha" (get-in result [:options :content]))))))
+
+(deftest test-search-subcommand-validation
+  (testing "search block requires --content"
+    (let [result (commands/parse-args ["search" "block"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-query-text (get-in result [:error :code])))))
+
+  (testing "search page rejects blank --content"
+    (let [result (commands/parse-args ["search" "page" "--content" "   "])]
+      (is (false? (:ok? result)))
+      (is (= :missing-query-text (get-in result [:error :code])))))
+
+  (testing "search block rejects legacy positional query with migration guidance"
+    (let [result (commands/parse-args ["search" "block" "alpha"])
+          message (strip-ansi (get-in result [:error :message]))]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "use --content"))
+      (is (string/includes? message "search block --content")))))
+
+(deftest test-list-subcommand-validation
+  (testing "list page rejects mutually exclusive journal flags"
+    (let [result (commands/parse-args ["list" "page"
+                                       "--include-journal"
+                                       "--journal-only"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "list page rejects invalid sort field"
+    (let [result (commands/parse-args ["list" "page" "--sort" "wat"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "list tag rejects invalid sort field"
+    (let [result (commands/parse-args ["list" "tag" "--sort" "wat"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "list property rejects invalid sort field"
+    (let [result (commands/parse-args ["list" "property" "--sort" "wat"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "list task rejects invalid sort field"
+    (let [result (commands/parse-args ["list" "task" "--sort" "wat"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "list asset rejects invalid sort field"
+    (let [result (commands/parse-args ["list" "asset" "--sort" "wat"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "list asset accepts size sort field"
+    (let [result (commands/parse-args ["list" "asset" "--sort" "size"])]
+      (is (true? (:ok? result)))
+      (is (= :list-asset (:command result)))
+      (is (= "size" (get-in result [:options :sort])))))
+
+  (testing "list task rejects invalid priority"
+    (let [result (commands/parse-args ["list" "task" "--priority" "wat"])
+          message (or (some-> (get-in result [:error :message]) strip-ansi) "")]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "Invalid value for option :priority: wat"))
+      (is (string/includes? message "Available values: low, medium, high, urgent"))))
+
+  (testing "list task defers unknown --status to runtime validation"
+    (let [result (commands/parse-args ["list" "task" "--status" "custom-review"])]
+      (is (true? (:ok? result)))
+      (is (= :list-task (:command result)))
+      (is (= "custom-review" (get-in result [:options :status])))))
+
+  (testing "list node requires at least one filter"
+    (let [result (commands/parse-args ["list" "node"])
+          message (strip-ansi (get-in result [:error :message]))]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "list node requires at least one of --tags or --properties"))))
+
+  (testing "list node rejects blank --tags csv"
+    (let [result (commands/parse-args ["list" "node" "--tags" " , ,   "])
+          message (strip-ansi (get-in result [:error :message]))]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "list node --tags must include at least one non-empty value"))))
+
+  (testing "list node rejects blank --properties csv"
+    (let [result (commands/parse-args ["list" "node" "--properties" " , ,   "])
+          message (strip-ansi (get-in result [:error :message]))]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "list node --properties must include at least one non-empty value"))))
+
+  (testing "list node accepts normalized csv filters"
+    (let [result (commands/parse-args ["list" "node"
+                                       "--tags" "  project , , work  "
+                                       "--properties" "  status ,, priority "])]
+      (is (true? (:ok? result)))
+      (is (= :list-node (:command result)))
+      (is (= "project,work" (get-in result [:options :tags])))
+      (is (= "status,priority" (get-in result [:options :properties]))))))
+
+(deftest test-list-execute-default-sort-updated-at
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ _]
+                                                (case method
+                                                  :thread-api/cli-list-pages [{:db/id 11 :block/title "Page C" :block/updated-at 30}
+                                                                              {:db/id 7 :block/title "Page B" :block/updated-at 10}
+                                                                              {:db/id 5 :block/title "Page A" :block/updated-at 10}]
+                                                  :thread-api/cli-list-tags [{:db/id 4 :block/title "Tag C" :block/updated-at 20}
+                                                                             {:db/id 9 :block/title "Tag B" :block/updated-at 5}
+                                                                             {:db/id 2 :block/title "Tag A" :block/updated-at 5}]
+                                                  :thread-api/cli-list-properties [{:db/id 8 :block/title "Property C" :block/updated-at 9}
+                                                                                   {:db/id 6 :block/title "Property B" :block/updated-at 3}
+                                                                                   {:db/id 1 :block/title "Property A" :block/updated-at 3}]
+                                                  :thread-api/cli-list-tasks [{:db/id 14 :block/title "Task C" :block/updated-at 12}
+                                                                              {:db/id 12 :block/title "Task B" :block/updated-at 4}
+                                                                              {:db/id 10 :block/title "Task A" :block/updated-at 4}]
+                                                  (throw (ex-info "unexpected invoke" {:method method}))))]
+               (p/let [page-result (list-command/execute-list-page {:repo "demo" :options {}} {})
+                       tag-result (list-command/execute-list-tag {:repo "demo" :options {}} {})
+                       property-result (list-command/execute-list-property {:repo "demo" :options {}} {})
+                       task-result (list-command/execute-list-task {:repo "demo" :options {}} {})]
+                 (is (= [11 7 5] (item-ids page-result)))
+                 (is (= [4 9 2] (item-ids tag-result)))
+                 (is (= [8 6 1] (item-ids property-result)))
+                 (is (= [14 12 10] (item-ids task-result)))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-list-execute-default-limit-returns-newest-records
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ _]
+                                                (case method
+                                                  :thread-api/cli-list-pages (mapv (fn [id]
+                                                                                     {:db/id id
+                                                                                      :block/title (str "Page " id)
+                                                                                      :block/updated-at id})
+                                                                                   [4 12 1 8 3 11 2 10 5 9 6 7])
+                                                  (throw (ex-info "unexpected invoke" {:method method}))))]
+               (p/let [result (list-command/execute-list-page {:repo "demo" :options {:limit 10}} {})]
+                 (is (= [12 11 10 9 8 7 6 5 4 3] (item-ids result)))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-list-execute-default-sort-respects-order-and-explicit-sort
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ _]
+                                                (case method
+                                                  :thread-api/cli-list-pages [{:db/id 3 :block/title "Beta" :block/updated-at 20}
+                                                                              {:db/id 2 :block/title "Gamma" :block/updated-at 5}
+                                                                              {:db/id 1 :block/title "Alpha" :block/updated-at 10}]
+                                                  (throw (ex-info "unexpected invoke" {:method method}))))]
+               (p/let [default-result (list-command/execute-list-page {:repo "demo" :options {}} {})
+                       explicit-order-result (list-command/execute-list-page {:repo "demo" :options {:order "asc"}} {})
+                       explicit-sort-result (list-command/execute-list-page {:repo "demo" :options {:sort "title"}} {})]
+                 (is (= [3 1 2] (item-ids default-result)))
+                 (is (= [2 1 3] (item-ids explicit-order-result)))
+                 (is (= [2 3 1] (item-ids explicit-sort-result)))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-list-property-execute-supports-cardinality-sort-and-fields
+  (async done
+         (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ _]
+                                                (case method
+                                                  :thread-api/cli-list-properties [{:db/id 30
+                                                                                    :block/title "Gamma"
+                                                                                    :db/cardinality :db.cardinality/one}
+                                                                                   {:db/id 10
+                                                                                    :block/title "Alpha"
+                                                                                    :db/cardinality :db.cardinality/many}
+                                                                                   {:db/id 20
+                                                                                    :block/title "Beta"
+                                                                                    :db/cardinality :db.cardinality/many}]
+                                                  (throw (ex-info "unexpected invoke" {:method method}))))]
+               (p/let [result (list-command/execute-list-property
+                               {:repo "demo"
+                                :options {:sort "cardinality"
+                                          :fields "id,title,cardinality"}}
+                               {})
+                       items (get-in result [:data :items])]
+                 (is (= [30 20 10] (mapv :db/id items)))
+                 (is (= [#{:db/id :block/title :db/cardinality}
+                         #{:db/id :block/title :db/cardinality}
+                         #{:db/id :block/title :db/cardinality}]
+                        (mapv (comp set keys) items)))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-list-asset-execute-filters-by-asset-tag
+  (async done
+         (let [calls* (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (swap! calls* conj {:method method :args args})
+                                                  (case method
+                                                    :thread-api/pull
+                                                    {:db/id 900}
+
+                                                    :thread-api/cli-list-nodes
+                                                    [{:db/id 2
+                                                      :block/title "asset-b"
+                                                      :node/type "block"
+                                                      :block/updated-at 30}
+                                                     {:db/id 1
+                                                      :block/title "asset-a"
+                                                      :node/type "block"
+                                                      :block/updated-at 10}]
+
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (list-command/execute-list-asset
+                                 {:repo "demo"
+                                  :options {:limit 1}}
+                                 {})
+                         items (get-in result [:data :items])
+                         list-call (some #(when (= :thread-api/cli-list-nodes (:method %)) %) @calls*)]
+                   (is (= :ok (:status result)))
+                   (is (= [2] (mapv :db/id items)))
+                   (is (= [900] (get-in list-call [:args 1 :tag-ids])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-task-runtime-invalid-status-includes-graph-values
+  (async done
+         (let [list-calls* (atom [])
+               upsert-calls* (atom [])]
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (let [repo (first args)]
+                                                    (cond
+                                                      (= method :thread-api/q)
+                                                      (do
+                                                        (if (= repo "demo")
+                                                          (swap! list-calls* conj method)
+                                                          (swap! upsert-calls* conj method))
+                                                        [:logseq.property/status.todo
+                                                         :logseq.property/status.done
+                                                         :logseq.property/status.doing])
+
+                                                      (= method :thread-api/cli-list-tasks)
+                                                      (do
+                                                        (swap! list-calls* conj method)
+                                                        [])
+
+                                                      (= method :thread-api/pull)
+                                                      (do
+                                                        (swap! upsert-calls* conj method)
+                                                        {:db/id 1})
+
+                                                      (= method :thread-api/apply-outliner-ops)
+                                                      (do
+                                                        (swap! upsert-calls* conj method)
+                                                        {:result :ok})
+
+                                                      :else
+                                                      (throw (ex-info "unexpected invoke" {:method method :args args})))))]
+                 (p/let [list-result (list-command/execute-list-task
+                                      {:repo "demo"
+                                       :options {:status "invalid-status"}}
+                                      {})
+                         list-alias-result (list-command/execute-list-task
+                                            {:repo "demo"
+                                             :options {:status "now"}}
+                                            {})
+                         upsert-result (upsert-command/execute-upsert-task
+                                        {:repo "upsert-demo"
+                                         :mode :update
+                                         :id 1
+                                         :status "invalid-status"}
+                                        {})
+                         list-message (or (some-> (get-in list-result [:error :message]) strip-ansi) "")
+                         list-alias-message (or (some-> (get-in list-alias-result [:error :message]) strip-ansi) "")
+                         upsert-message (or (some-> (get-in upsert-result [:error :message]) strip-ansi) "")]
+                   (is (= :error (:status list-result)))
+                   (is (= :invalid-options (get-in list-result [:error :code])))
+                   (is (string/includes? list-message "Invalid value for option :status: invalid-status"))
+                   (is (string/includes? list-message "Available values: doing, done, todo"))
+                   (is (not (string/includes? list-message "from current graph")))
+
+                   (is (= :error (:status list-alias-result)))
+                   (is (= :invalid-options (get-in list-alias-result [:error :code])))
+                   (is (string/includes? list-alias-message "Invalid value for option :status: now"))
+                   (is (string/includes? list-alias-message "Available values: doing, done, todo"))
+                   (is (= [:thread-api/q :thread-api/q] @list-calls*))
+
+                   (is (= :error (:status upsert-result)))
+                   (is (= :invalid-options (get-in upsert-result [:error :code])))
+                   (is (string/includes? upsert-message "Invalid value for option :status: invalid-status"))
+                   (is (string/includes? upsert-message "Available values: doing, done, todo"))
+                   (is (not (string/includes? upsert-message "from current graph")))
+                   (is (= [:thread-api/q] @upsert-calls*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-verb-subcommand-parse-upsert-remove
+  (testing "remove block parses with id"
+    (let [result (commands/parse-args ["remove" "block" "--id" "10"])]
+      (is (true? (:ok? result)))
+      (is (= :remove-block (:command result)))
+      (is (= 10 (get-in result [:options :id])))))
+
+  (testing "remove page parses with page"
+    (let [result (commands/parse-args ["remove" "page" "--page" "Home"])]
+      (is (true? (:ok? result)))
+      (is (= :remove-page (:command result)))
+      (is (= "Home" (get-in result [:options :page])))))
+
+  (testing "remove page parses with id"
+    (let [result (commands/parse-args ["remove" "page" "--id" "42"])]
+      (is (true? (:ok? result)))
+      (is (= :remove-page (:command result)))
+      (is (= 42 (get-in result [:options :id])))))
+
+  (testing "remove page rejects --id and --page together"
+    (let [result (commands/parse-args ["remove" "page" "--id" "42" "--page" "Home"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "remove page rejects legacy --name"
+    (let [result (commands/parse-args ["remove" "page" "--name" "Home"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "remove tag parses with name"
+    (let [result (commands/parse-args ["remove" "tag" "--name" "Quote"])]
+      (is (true? (:ok? result)))
+      (is (= :remove-tag (:command result)))
+      (is (= "Quote" (get-in result [:options :name])))))
+
+  (testing "remove property parses with id"
+    (let [result (commands/parse-args ["remove" "property" "--id" "123"])]
+      (is (true? (:ok? result)))
+      (is (= :remove-property (:command result)))
+      (is (= 123 (get-in result [:options :id])))))
+
+  (testing "remove block rejects empty id vector"
+    (let [result (commands/parse-args ["remove" "block" "--id" "[]"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "remove block rejects invalid id vector"
+    (let [result (commands/parse-args ["remove" "block" "--id" "[1 \"no\"]"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  )
+
+(deftest test-verb-subcommand-parse-upsert-entity
+  (testing "upsert tag parses with name"
+    (let [result (commands/parse-args ["upsert" "tag" "--name" "Quote"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-tag (:command result)))
+      (is (= "Quote" (get-in result [:options :name])))))
+
+  (testing "upsert tag parses with id"
+    (let [result (commands/parse-args ["upsert" "tag" "--id" "10"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-tag (:command result)))
+      (is (= 10 (get-in result [:options :id])))))
+
+  (testing "upsert tag parses with id and name"
+    (let [result (commands/parse-args ["upsert" "tag"
+                                       "--id" "10"
+                                       "--name" "Project Renamed"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-tag (:command result)))
+      (is (= 10 (get-in result [:options :id])))
+      (is (= "Project Renamed" (get-in result [:options :name])))))
+
+  (testing "upsert property parses with type and cardinality"
+    (let [result (commands/parse-args ["upsert" "property"
+                                       "--name" "owner"
+                                       "--type" "node"
+                                       "--cardinality" "many"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-property (:command result)))
+      (is (= "owner" (get-in result [:options :name])))
+      (is (= "node" (get-in result [:options :type])))
+      (is (= "many" (get-in result [:options :cardinality])))))
+
+  (testing "upsert property parses with id and type"
+    (let [result (commands/parse-args ["upsert" "property"
+                                       "--id" "11"
+                                       "--type" "node"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-property (:command result)))
+      (is (= 11 (get-in result [:options :id])))
+      (is (= "node" (get-in result [:options :type])))))
+
+  (testing "upsert property rejects invalid type"
+    (let [result (commands/parse-args ["upsert" "property"
+                                       "--name" "owner"
+                                       "--type" "wat"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert property rejects invalid cardinality"
+    (let [result (commands/parse-args ["upsert" "property"
+                                       "--name" "owner"
+                                       "--cardinality" "triple"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code]))))))
+
+(deftest test-verb-subcommand-parse-upsert-block-mode
+
+  (testing "upsert block create mode requires content when source selectors are absent"
+    (let [result (commands/parse-args ["upsert" "block" "--target-id" "10"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-content (get-in result [:error :code])))))
+
+  (testing "upsert block update mode requires target or update/remove options"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert block parses with source and target"
+    (let [result (commands/parse-args ["upsert" "block" "--uuid" "11111111-1111-1111-1111-111111111111" "--target-uuid" "22222222-2222-2222-2222-222222222222" "--pos" "last-child"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= "11111111-1111-1111-1111-111111111111" (get-in result [:options :uuid])))
+      (is (= "22222222-2222-2222-2222-222222222222" (get-in result [:options :target-uuid])))
+      (is (= "last-child" (get-in result [:options :pos])))))
+
+  (testing "upsert block parses with update tags and properties"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1"
+                                       "--update-tags" "[\"TagA\"]"
+                                       "--update-properties" "{:logseq.property/publishing-public? true}"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= "[\"TagA\"]" (get-in result [:options :update-tags])))
+      (is (= "{:logseq.property/publishing-public? true}" (get-in result [:options :update-properties])))))
+
+  (testing "upsert block allows updates without move target"
+    (let [result (commands/parse-args ["upsert" "block" "--uuid" "11111111-1111-1111-1111-111111111111"
+                                       "--update-tags" "[\"TagA\"]"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= "11111111-1111-1111-1111-111111111111" (get-in result [:options :uuid])))))
+
+  (testing "upsert block rejects --status and guides migration to upsert task"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1"
+                                       "--status" "done"])
+          message (strip-ansi (get-in result [:error :message]))]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "--status"))
+      (is (string/includes? message "upsert task"))))
+
+  (testing "upsert block update mode accepts content-only updates"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1"
+                                       "--content" "updated text"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= 1 (get-in result [:options :id])))
+      (is (= "updated text" (get-in result [:options :content])))))
+
+  (testing "upsert block forces update mode when id and content are both provided"
+    (let [result (commands/parse-args ["upsert" "block"
+                                       "--id" "1"
+                                       "--content" "hello"
+                                       "--update-tags" "[\"TagA\"]"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= 1 (get-in result [:options :id])))
+      (is (= "hello" (get-in result [:options :content])))
+      (is (= "[\"TagA\"]" (get-in result [:options :update-tags]))))))
+
+(deftest test-verb-subcommand-parse-add
+  (testing "upsert block create mode requires content source"
+    (let [result (commands/parse-args ["upsert" "block"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-content (get-in result [:error :code])))))
+
+  (testing "upsert block create mode parses with content"
+    (let [result (commands/parse-args ["upsert" "block" "--content" "hello"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= "hello" (get-in result [:options :content])))))
+
+  (testing "upsert block create mode supports short -c alias for --content"
+    (let [result (commands/parse-args ["upsert" "block" "-c" "hello"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= "hello" (get-in result [:options :content])))))
+
+  (testing "upsert block create mode parses with target selectors and pos"
+    (let [result (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--target-uuid" "11111111-1111-1111-1111-111111111111"
+                                       "--pos" "first-child"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= "11111111-1111-1111-1111-111111111111" (get-in result [:options :target-uuid])))
+      (is (= "first-child" (get-in result [:options :pos])))))
+
+  (testing "upsert block create mode parses with update tags and update properties"
+    (let [result (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--update-tags" "[\"TagA\" \"TagB\"]"
+                                       "--update-properties" "{:logseq.property/publishing-public? true}"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= "[\"TagA\" \"TagB\"]" (get-in result [:options :update-tags])))
+      (is (= "{:logseq.property/publishing-public? true}" (get-in result [:options :update-properties])))))
+
+  (testing "upsert block rejects invalid pos"
+    (let [result (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--pos" "middle"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert block rejects removed --tags option"
+    (let [result (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--tags" "[\"TagA\"]"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert block rejects removed --properties option"
+    (let [result (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--properties" "{:logseq.property/publishing-public? true}"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code]))))))
+
+(deftest test-verb-subcommand-parse-upsert-page-mode
+  (testing "upsert page requires page name"
+    (let [result (commands/parse-args ["upsert" "page"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-page-name (get-in result [:error :code])))))
+
+  (testing "upsert page parses with name"
+    (let [result (commands/parse-args ["upsert" "page" "--page" "Home"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-page (:command result)))
+      (is (= "Home" (get-in result [:options :page])))))
+
+  (testing "upsert page allows page names containing hashtag at parse time"
+    (let [result (commands/parse-args ["upsert" "page" "--page" "foo#bar"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-page (:command result)))
+      (is (= "foo#bar" (get-in result [:options :page])))))
+
+  (testing "upsert page parses with id update mode"
+    (let [result (commands/parse-args ["upsert" "page"
+                                       "--id" "42"
+                                       "--update-properties" "{:logseq.property/publishing-public? true}"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-page (:command result)))
+      (is (= 42 (get-in result [:options :id])))
+      (is (= "{:logseq.property/publishing-public? true}" (get-in result [:options :update-properties])))))
+
+  (testing "upsert page rejects removed --tags and --properties options"
+    (let [result (commands/parse-args ["upsert" "page"
+                                       "--page" "Home"
+                                       "--tags" "[\"TagA\"]"
+                                       "--properties" "{:logseq.property/publishing-public? true}"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert page parses update and remove options"
+    (let [result (commands/parse-args ["upsert" "page"
+                                       "--page" "Home"
+                                       "--update-tags" "[\"TagB\"]"
+                                       "--remove-properties" "[:logseq.property/deadline]"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-page (:command result)))
+      (is (= "[\"TagB\"]" (get-in result [:options :update-tags])))
+      (is (= "[:logseq.property/deadline]" (get-in result [:options :remove-properties])))))
+
+  (testing "upsert page rejects selector conflict for --id and --page"
+    (let [result (commands/parse-args ["upsert" "page"
+                                       "--id" "10"
+                                       "--page" "Home"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "legacy add tag is no longer supported"
+    (let [result (commands/parse-args ["add" "tag" "--name" "Quote"])]
+      (is (false? (:ok? result)))
+      (is (= :unknown-command (get-in result [:error :code]))))))
+
+(deftest ^:large-vars/cleanup-todo test-verb-subcommand-parse-upsert-task-mode
+  (testing "upsert task parses block create mode with task fields"
+    (let [result (commands/parse-args ["upsert" "task"
+                                       "--content" "Ship CLI tasks"
+                                       "--target-page" "Home"
+                                       "--status" "todo"
+                                       "--priority" "high"
+                                       "--scheduled" "2026-02-10T08:00:00.000Z"
+                                       "--deadline" "2026-02-12T18:00:00.000Z"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-task (:command result)))
+      (is (= "Ship CLI tasks" (get-in result [:options :content])))
+      (is (= "Home" (get-in result [:options :target-page])))
+      (is (= "todo" (get-in result [:options :status])))
+      (is (= "high" (get-in result [:options :priority])))
+      (is (= "2026-02-10T08:00:00.000Z" (get-in result [:options :scheduled])))
+      (is (= "2026-02-12T18:00:00.000Z" (get-in result [:options :deadline])))))
+
+  (testing "upsert task parses explicit clear flags"
+    (let [result (commands/parse-args ["upsert" "task"
+                                       "--id" "42"
+                                       "--no-status"
+                                       "--no-priority"
+                                       "--no-scheduled"
+                                       "--no-deadline"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-task (:command result)))
+      (is (= 42 (get-in result [:options :id])))
+      (is (= true (get-in result [:options :no-status])))
+      (is (= true (get-in result [:options :no-priority])))
+      (is (= true (get-in result [:options :no-scheduled])))
+      (is (= true (get-in result [:options :no-deadline])))))
+
+  (testing "upsert task parses page mode"
+    (let [result (commands/parse-args ["upsert" "task" "--page" "Weekly Plan"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-task (:command result)))
+      (is (= "Weekly Plan" (get-in result [:options :page])))))
+
+  (testing "upsert task parses id update mode"
+    (let [result (commands/parse-args ["upsert" "task"
+                                       "--id" "42"
+                                       "--status" "done"
+                                       "--priority" "medium"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-task (:command result)))
+      (is (= 42 (get-in result [:options :id])))
+      (is (= "done" (get-in result [:options :status])))
+      (is (= "medium" (get-in result [:options :priority])))))
+
+  (testing "upsert task rejects removed generic mutation options and guides to upsert block"
+    (doseq [legacy-option ["--update-tags" "--update-properties" "--remove-tags" "--remove-properties"]]
+      (let [result (commands/parse-args ["upsert" "task"
+                                         "--id" "42"
+                                         legacy-option
+                                         (if (or (= legacy-option "--update-tags")
+                                                 (= legacy-option "--remove-tags"))
+                                           "[\"TagA\"]"
+                                           (if (= legacy-option "--update-properties")
+                                             "{:logseq.property/publishing-public? true}"
+                                             "[:logseq.property/publishing-public?]"))])
+            message (strip-ansi (get-in result [:error :message]))]
+        (is (false? (:ok? result)))
+        (is (= :invalid-options (get-in result [:error :code])))
+        (is (string/includes? message "upsert block")))))
+
+  (testing "upsert task defers unknown --status to runtime validation"
+    (let [result (commands/parse-args ["upsert" "task"
+                                       "--id" "42"
+                                       "--status" "custom-review"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-task (:command result)))
+      (is (= "custom-review" (get-in result [:options :status])))))
+
+  (testing "upsert task rejects set/no conflicts for the same field"
+    (doseq [args [["upsert" "task" "--id" "42" "--status" "todo" "--no-status"]
+                  ["upsert" "task" "--id" "42" "--priority" "high" "--no-priority"]
+                  ["upsert" "task" "--id" "42" "--scheduled" "2026-02-10T08:00:00.000Z" "--no-scheduled"]
+                  ["upsert" "task" "--id" "42" "--deadline" "2026-02-12T18:00:00.000Z" "--no-deadline"]]]
+      (let [result (commands/parse-args args)]
+        (is (false? (:ok? result)))
+        (is (= :invalid-options (get-in result [:error :code]))))))
+
+  (testing "upsert task requires selector, page, or content"
+    (let [result (commands/parse-args ["upsert" "task"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-target (get-in result [:error :code])))))
+
+  (testing "upsert task rejects selector conflicts"
+    (let [result (commands/parse-args ["upsert" "task"
+                                       "--id" "42"
+                                       "--uuid" "11111111-1111-1111-1111-111111111111"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert task rejects page and content combination"
+    (let [result (commands/parse-args ["upsert" "task"
+                                       "--page" "Home"
+                                       "--content" "Task block"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert task rejects id and content combination"
+    (let [result (commands/parse-args ["upsert" "task"
+                                       "--id" "42"
+                                       "--content" "Task block"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert task rejects target options in page mode"
+    (let [result (commands/parse-args ["upsert" "task"
+                                       "--page" "Home"
+                                       "--target-page" "Elsewhere"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert task rejects blank status with available values"
+    (let [parsed {:ok? true
+                  :command :upsert-task
+                  :options {:id 42 :status "   "}}
+          result (commands/build-action parsed {:graph "demo"})
+          message (or (some-> (get-in result [:error :message]) strip-ansi) "")]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "Invalid value for option :status:"))
+      (is (string/includes? message "Available values:"))
+      (is (not (string/includes? message "from current graph")))))
+
+  (testing "upsert task rejects invalid priority"
+    (let [result (commands/parse-args ["upsert" "task"
+                                       "--content" "Alpha"
+                                       "--priority" "wat"])
+          message (or (some-> (get-in result [:error :message]) strip-ansi) "")]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "Invalid value for option :priority: wat"))
+      (is (string/includes? message "Available values: low, medium, high, urgent")))))
+
+(deftest test-verb-subcommand-parse-upsert-asset-mode
+  (testing "upsert asset create mode requires --path"
+    (let [result (commands/parse-args ["upsert" "asset" "--content" "Asset title"])
+          message (or (some-> (get-in result [:error :message]) strip-ansi) "")]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "--path is required"))))
+
+  (testing "upsert asset create mode parses with path, target and pos"
+    (let [result (commands/parse-args ["upsert" "asset"
+                                       "--path" "./fixtures/image.png"
+                                       "--content" "Asset title"
+                                       "--target-page" "Home"
+                                       "--pos" "last-child"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-asset (:command result)))
+      (is (= "./fixtures/image.png" (get-in result [:options :path])))
+      (is (= "Asset title" (get-in result [:options :content])))
+      (is (= "Home" (get-in result [:options :target-page])))
+      (is (= "last-child" (get-in result [:options :pos])))))
+
+  (testing "upsert asset update mode parses with id and content"
+    (let [result (commands/parse-args ["upsert" "asset"
+                                       "--id" "42"
+                                       "--content" "Updated asset title"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-asset (:command result)))
+      (is (= 42 (get-in result [:options :id])))
+      (is (= "Updated asset title" (get-in result [:options :content])))))
+
+  (testing "upsert asset update mode rejects --path"
+    (let [result (commands/parse-args ["upsert" "asset"
+                                       "--id" "42"
+                                       "--path" "./fixtures/image.png"])
+          message (or (some-> (get-in result [:error :message]) strip-ansi) "")]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (string/includes? message "--path is only valid in create mode"))))
+
+  (testing "upsert asset rejects selector conflict"
+    (let [result (commands/parse-args ["upsert" "asset"
+                                       "--id" "42"
+                                       "--uuid" "11111111-1111-1111-1111-111111111111"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code]))))))
+
+(deftest test-verb-subcommand-parse-update-target-page
+  (testing "upsert block update mode parses with target page"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1" "--target-page" "Home"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= 1 (get-in result [:options :id])))
+      (is (= "Home" (get-in result [:options :target-page])))))
+
+  (testing "upsert block allows target page names containing hashtag at parse time"
+    (let [result (commands/parse-args ["upsert" "block" "--content" "hello" "--target-page" "foo#bar"])]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (:command result)))
+      (is (= "foo#bar" (get-in result [:options :target-page]))))))
+
+(deftest test-verb-subcommand-parse-show
+  (testing "show requires target"
+    (let [result (commands/parse-args ["show"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-target (get-in result [:error :code])))))
+
+  (testing "show parses with page"
+    (let [result (commands/parse-args ["show" "--page" "Home"])]
+      (is (true? (:ok? result)))
+      (is (= :show (:command result)))
+      (is (= "Home" (get-in result [:options :page])))))
+
+  (testing "show parses with id vector"
+    (let [result (commands/parse-args ["show" "--id" "[1 2]"])]
+      (is (true? (:ok? result)))
+      (is (= :show (:command result)))
+      (is (= "[1 2]" (get-in result [:options :id])))))
+
+  (testing "show rejects invalid id edn"
+    (let [result (commands/parse-args ["show" "--id" "[1"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "show rejects legacy page-name option"
+    (let [result (commands/parse-args ["show" "--page-name" "Home"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "show rejects format option"
+    (let [result (commands/parse-args ["show" "--format" "json" "--page" "Home"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "show parses ref-id-footer option"
+    (let [result (commands/parse-args ["show" "--page" "Home" "--ref-id-footer" "false"])]
+      (is (true? (:ok? result)))
+      (is (= false (get-in result [:options :ref-id-footer])))))
+
+  (testing "show help lists linked references and ref-id-footer options"
+    (let [summary (:summary (binding [style/*color-enabled?* true]
+                              (commands/parse-args ["show" "--help"])))]
+      (is (string/includes? (strip-ansi summary) "--linked-references"))
+      (is (string/includes? (strip-ansi summary) "--ref-id-footer")))))
+
+(deftest test-verb-subcommand-parse-debug
+  (testing "debug pull parses with id"
+    (let [result (commands/parse-args ["debug" "pull" "--id" "1"])]
+      (is (true? (:ok? result)))
+      (is (= :debug-pull (:command result)))
+      (is (= 1 (get-in result [:options :id])))))
+
+  (testing "debug pull parses with uuid"
+    (let [result (commands/parse-args ["debug" "pull" "--uuid" "11111111-1111-1111-1111-111111111111"])]
+      (is (true? (:ok? result)))
+      (is (= :debug-pull (:command result)))
+      (is (= "11111111-1111-1111-1111-111111111111" (get-in result [:options :uuid])))))
+
+  (testing "debug pull parses with ident"
+    (let [result (commands/parse-args ["debug" "pull" "--ident" ":logseq.class/Tag"])]
+      (is (true? (:ok? result)))
+      (is (= :debug-pull (:command result)))
+      (is (= :logseq.class/Tag (get-in result [:options :ident])))))
+
+  (testing "debug pull rejects missing selector"
+    (let [result (commands/parse-args ["debug" "pull"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "debug pull rejects multiple selectors"
+    (let [result (commands/parse-args ["debug" "pull" "--id" "1" "--uuid" "11111111-1111-1111-1111-111111111111"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "debug pull rejects malformed id"
+    (let [result (commands/parse-args ["debug" "pull" "--id" "abc"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "debug pull rejects malformed uuid"
+    (let [result (commands/parse-args ["debug" "pull" "--uuid" "not-a-uuid"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "debug pull rejects malformed ident"
+    (let [result (commands/parse-args ["debug" "pull" "--ident" "logseq.class/Tag"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code]))))))
+
+(deftest test-verb-subcommand-parse-skill
+  (testing "skill show parses"
+    (let [result (commands/parse-args ["skill" "show"])]
+      (is (true? (:ok? result)))
+      (is (= :skill-show (:command result)))))
+
+  (testing "skill install parses"
+    (let [result (commands/parse-args ["skill" "install"])]
+      (is (true? (:ok? result)))
+      (is (= :skill-install (:command result)))
+      (is (not (true? (get-in result [:options :global]))))))
+
+  (testing "skill install --global parses"
+    (let [result (commands/parse-args ["skill" "install" "--global"])]
+      (is (true? (:ok? result)))
+      (is (= :skill-install (:command result)))
+      (is (true? (get-in result [:options :global])))))
+
+  (testing "skill show rejects unknown option"
+    (let [result (commands/parse-args ["skill" "show" "--global"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code]))))))
+
+(deftest test-verb-subcommand-parse-query
+  (testing "query shows group help"
+    (let [result (commands/parse-args ["query"])]
+      (is (true? (:help? result)))
+      (is (string/includes? (:summary result) "query list"))))
+
+  (testing "query parses with query and inputs"
+    (let [result (commands/parse-args ["query"
+                                       "--query" "[:find ?e :where [?e :block/title \"Hello\"]]"
+                                       "--inputs" "[\"Hello\"]"])]
+      (is (true? (:ok? result)))
+      (is (= :query (:command result)))
+      (is (= "[:find ?e :where [?e :block/title \"Hello\"]]"
+             (get-in result [:options :query])))
+      (is (= "[\"Hello\"]" (get-in result [:options :inputs]))))))
+
+(deftest test-verb-subcommand-parse-graph-import-export
+  (testing "graph create requires --graph even with positional args"
+    (let [result (commands/parse-args ["graph" "create" "demo"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-graph (get-in result [:error :code])))))
+
+  (testing "graph export parses with type and file"
+    (let [result (commands/parse-args ["graph" "export"
+                                       "--type" "edn"
+                                       "--file" "export.edn"])]
+      (is (true? (:ok? result)))
+      (is (= :graph-export (:command result)))
+      (is (= "edn" (get-in result [:options :type])))
+      (is (= "export.edn" (get-in result [:options :file])))))
+
+  (testing "graph import parses with type, input, and repo"
+    (let [result (commands/parse-args ["graph" "import"
+                                       "--type" "sqlite"
+                                       "--input" "import.sqlite"
+                                       "--graph" "demo"])]
+      (is (true? (:ok? result)))
+      (is (= :graph-import (:command result)))
+      (is (= "sqlite" (get-in result [:options :type])))
+      (is (= "import.sqlite" (get-in result [:options :input])))
+      (is (= "demo" (get-in result [:options :graph])))))
+
+  (testing "graph export requires type"
+    (let [result (commands/parse-args ["graph" "export" "--file" "export.edn"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-type (get-in result [:error :code])))))
+
+  (testing "graph export requires file"
+    (let [result (commands/parse-args ["graph" "export" "--type" "edn"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-file (get-in result [:error :code])))))
+
+  (testing "graph export accepts global output format and still requires file"
+    (let [result (commands/parse-args ["graph" "export" "--type" "edn" "--output" "json"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-file (get-in result [:error :code])))))
+
+  (testing "graph import requires graph"
+    (let [result (commands/parse-args ["graph" "import"
+                                       "--type" "edn"
+                                       "--input" "import.edn"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-graph (get-in result [:error :code])))))
+
+  (testing "sync download requires graph"
+    (let [result (commands/parse-args ["sync" "download"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-graph (get-in result [:error :code])))))
+
+  (testing "sync download accepts progress option"
+    (let [disabled (commands/parse-args ["sync" "download" "--graph" "demo" "--progress" "false"])
+          enabled (commands/parse-args ["sync" "download" "--graph" "demo" "--progress" "true"])]
+      (is (true? (:ok? disabled)))
+      (is (= false (get-in disabled [:options :progress])))
+      (is (true? (:ok? enabled)))
+      (is (= true (get-in enabled [:options :progress])))))
+
+  (testing "sync ensure-keys accepts e2ee-password option"
+    (let [result (commands/parse-args ["sync" "ensure-keys" "--e2ee-password" "pw"])]
+      (is (true? (:ok? result)))
+      (is (= :sync-ensure-keys (:command result)))
+      (is (= "pw" (get-in result [:options :e2ee-password])))))
+
+  (testing "sync ensure-keys accepts upload-keys option"
+    (let [result (commands/parse-args ["sync" "ensure-keys" "--upload-keys"])]
+      (is (true? (:ok? result)))
+      (is (= :sync-ensure-keys (:command result)))
+      (is (= true (get-in result [:options :upload-keys])))))
+
+  (testing "graph import rejects unknown type"
+    (let [result (commands/parse-args ["graph" "import"
+                                       "--type" "zip"
+                                       "--input" "import.zip"
+                                       "--graph" "demo"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "server status is removed and parses as unknown command"
+    (let [result (commands/parse-args ["server" "status" "--graph" "demo"])]
+      (is (false? (:ok? result)))
+      (is (= :unknown-command (get-in result [:error :code])))))
+
+  (testing "server cleanup parses without --graph"
+    (let [result (commands/parse-args ["server" "cleanup"])]
+      (is (true? (:ok? result)))
+      (is (= :server-cleanup (:command result)))))
+
+  (testing "server cleanup accepts global -g alias but does not require graph"
+    (let [result (commands/parse-args ["server" "cleanup" "-g" "demo"])]
+      (is (true? (:ok? result)))
+      (is (= :server-cleanup (:command result)))
+      (is (= "demo" (get-in result [:options :graph]))))))
+
+(deftest test-verb-subcommand-parse-graph-backup
+  (testing "graph backup list parses"
+    (let [result (commands/parse-args ["graph" "backup" "list"])]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-list (:command result)))))
+
+  (testing "graph backup create parses with optional name"
+    (let [result (commands/parse-args ["graph" "backup" "create" "--name" "nightly"]) ]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-create (:command result)))
+      (is (= "nightly" (get-in result [:options :name])))))
+
+  (testing "graph backup create with name carries source and naming components"
+    (let [result (commands/parse-args ["graph" "backup" "create"
+                                       "--graph" "demo"
+                                       "--name" "nightly"]) ]
+      (is (true? (:ok? result)))
+      (is (= "demo" (get-in result [:options :graph])))
+      (is (= "nightly" (get-in result [:options :name])))))
+
+  (testing "graph backup restore parses with --src and --dst"
+    (let [result (commands/parse-args ["graph" "backup" "restore"
+                                       "--src" "demo-nightly"
+                                       "--dst" "demo-restored"]) ]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-restore (:command result)))
+      (is (= "demo-nightly" (get-in result [:options :src])))
+      (is (= "demo-restored" (get-in result [:options :dst])))))
+
+  (testing "graph backup restore requires --src"
+    (let [result (commands/parse-args ["graph" "backup" "restore" "--dst" "demo-restored"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-src (get-in result [:error :code])))))
+
+  (testing "graph backup restore requires --dst"
+    (let [result (commands/parse-args ["graph" "backup" "restore" "--src" "demo-nightly"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-dst (get-in result [:error :code])))))
+
+  (testing "graph backup remove parses with --src"
+    (let [result (commands/parse-args ["graph" "backup" "remove" "--src" "demo-nightly"])]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-remove (:command result)))
+      (is (= "demo-nightly" (get-in result [:options :src])))))
+
+  (testing "graph backup remove requires --src"
+    (let [result (commands/parse-args ["graph" "backup" "remove"])]
+      (is (false? (:ok? result)))
+      (is (= :missing-src (get-in result [:error :code]))))))
+
+(deftest test-verb-subcommand-parse-flags
+  (testing "verb subcommands reject unknown flags"
+    (doseq [args [["list" "page" "--wat"]
+                  ["upsert" "block" "--wat"]
+                  ["upsert" "page" "--wat"]
+                  ["remove" "block" "--wat"]
+                  ["upsert" "tag" "--wat"]
+                  ["show" "--wat"]
+                  ["debug" "pull" "--wat"]]]
+      (let [result (commands/parse-args args)]
+        (is (false? (:ok? result)))
+        (is (= :invalid-options (get-in result [:error :code]))))))
+
+  (testing "verb subcommands accept output option"
+    (let [result (commands/parse-args ["show" "--output" "json" "--page" "Home"])]
+      (is (true? (:ok? result)))
+      (is (= "json" (get-in result [:options :output]))))))
+
+(deftest test-build-action-graph
+  (testing "graph-list uses list-db"
+    (let [parsed {:ok? true :command :graph-list :options {}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :graph-list (get-in result [:action :type])))))
+
+  (testing "graph-create requires repo name"
+    (let [parsed {:ok? true :command :graph-create :options {}}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-graph (get-in result [:error :code])))))
+
+  (testing "graph-switch uses graph name"
+    (let [parsed {:ok? true :command :graph-switch :options {:graph "demo"}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :graph-switch (get-in result [:action :type])))))
+
+  (testing "graph-info defaults to config repo"
+    (let [parsed {:ok? true :command :graph-info :options {}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :graph-info (get-in result [:action :type])))))
+
+  (testing "graph export uses config repo"
+    (let [parsed {:ok? true
+                  :command :graph-export
+                  :options {:type "edn" :file "export.edn"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :graph-export (get-in result [:action :type])))))
+
+  (testing "graph import requires repo"
+    (let [parsed {:ok? true
+                  :command :graph-import
+                  :options {:type "edn" :input "import.edn"}}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+)
+
+(deftest test-build-action-graph-backup
+  (testing "graph backup list resolves source repo from --graph"
+    (let [parsed {:ok? true :command :graph-backup-list :options {:graph "demo"}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-list (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))))
+
+  (testing "graph backup list resolves source repo from config graph"
+    (let [parsed {:ok? true :command :graph-backup-list :options {}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-list (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))))
+
+  (testing "graph backup list fails when no source graph is available"
+    (let [parsed {:ok? true :command :graph-backup-list :options {}}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+  (testing "graph backup create resolves source repo from --graph"
+    (let [parsed {:ok? true :command :graph-backup-create :options {:graph "demo"}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-create (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))))
+
+  (testing "graph backup create resolves source repo from config graph"
+    (let [parsed {:ok? true :command :graph-backup-create :options {}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-create (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))))
+
+  (testing "graph backup create falls back to legacy config repo"
+    (let [parsed {:ok? true :command :graph-backup-create :options {}}
+          result (commands/build-action parsed {:repo "logseq_db_demo"})]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-create (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))))
+
+  (testing "graph backup create fails when no source graph is available"
+    (let [parsed {:ok? true :command :graph-backup-create :options {}}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+  (testing "graph backup create with --name generates backup name shape"
+    (let [parsed {:ok? true :command :graph-backup-create :options {:graph "demo" :name "nightly"}}
+          result (commands/build-action parsed {})
+          backup-name (get-in result [:action :backup-name])]
+      (is (true? (:ok? result)))
+      (is (string? backup-name))
+      (is (and (string? backup-name)
+               (re-matches #"demo-nightly-\d{8}T\d{6}Z(?:-\d+)?" backup-name)))))
+
+  (testing "graph backup restore resolves source repo from --graph"
+    (let [parsed {:ok? true :command :graph-backup-restore :options {:graph "demo" :src "demo-nightly" :dst "demo-restored"}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-restore (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :source-repo])))
+      (is (= "demo-nightly" (get-in result [:action :src])))
+      (is (= "demo-restored" (get-in result [:action :dst])))))
+
+  (testing "graph backup restore resolves source repo from config graph"
+    (let [parsed {:ok? true :command :graph-backup-restore :options {:src "demo-nightly" :dst "demo-restored"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-restore (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :source-repo])))))
+
+  (testing "graph backup restore fails when no source graph is available"
+    (let [parsed {:ok? true :command :graph-backup-restore :options {:src "demo-nightly" :dst "demo-restored"}}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+  (testing "graph backup remove resolves source repo from --graph"
+    (let [parsed {:ok? true :command :graph-backup-remove :options {:graph "demo" :src "demo-nightly"}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-remove (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))
+      (is (= "demo-nightly" (get-in result [:action :src])))))
+
+  (testing "graph backup remove resolves source repo from config graph"
+    (let [parsed {:ok? true :command :graph-backup-remove :options {:src "demo-nightly"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :graph-backup-remove (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))))
+
+  (testing "graph backup remove fails when no source graph is available"
+    (let [parsed {:ok? true :command :graph-backup-remove :options {:src "demo-nightly"}}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code]))))))
+
+(deftest test-build-action-server
+  (testing "server list builds action"
+    (let [parsed {:ok? true :command :server-list :options {}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :server-list (get-in result [:action :type])))))
+
+  (testing "server start requires repo"
+    (let [parsed {:ok? true :command :server-start :options {}}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+  (testing "server stop builds action"
+    (let [parsed {:ok? true :command :server-stop :options {:graph "demo"}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :server-stop (get-in result [:action :type])))))
+
+  (testing "server cleanup builds action without requiring repo"
+    (let [parsed {:ok? true :command :server-cleanup :options {}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :server-cleanup (get-in result [:action :type]))))))
+
+(deftest test-build-action-doctor
+  (testing "doctor builds action"
+    (let [parsed {:ok? true :command :doctor :options {}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :doctor (get-in result [:action :type])))))
+
+  (testing "doctor dev script option builds explicit static runtime action"
+    (let [parsed {:ok? true :command :doctor :options {:dev-script true}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :doctor (get-in result [:action :type])))
+      (is (= (cli-server/db-worker-dev-script-path)
+             (get-in result [:action :script-path]))))))
+
+(deftest test-build-action-example
+  (testing "example builds local action"
+    (let [parsed {:ok? true
+                  :command :example
+                  :cmds ["example" "upsert" "page"]
+                  :options {}
+                  :args []}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :example (get-in result [:action :type])))
+      (is (= "upsert page" (get-in result [:action :selector]))))))
+
+(deftest test-build-action-skill
+  (testing "skill show builds local action"
+    (let [parsed {:ok? true
+                  :command :skill-show
+                  :options {}
+                  :args []}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :skill-show (get-in result [:action :type])))))
+
+  (testing "skill install builds local target by default"
+    (let [parsed {:ok? true
+                  :command :skill-install
+                  :options {}
+                  :args []}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :skill-install (get-in result [:action :type])))
+      (is (false? (get-in result [:action :global?])))))
+
+  (testing "skill install builds global target with --global"
+    (let [parsed {:ok? true
+                  :command :skill-install
+                  :options {:global true}
+                  :args []}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :skill-install (get-in result [:action :type])))
+      (is (true? (get-in result [:action :global?]))))))
+
+(deftest ^:large-vars/cleanup-todo test-build-action-inspect-edit-add-upsert
+  (testing "list page requires repo"
+    (let [parsed {:ok? true :command :list-page :options {}}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+  (testing "list task builds action"
+    (let [parsed {:ok? true :command :list-task :options {:status "todo"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :list-task (get-in result [:action :type])))))
+
+  (testing "list node builds action"
+    (let [parsed {:ok? true :command :list-node :options {:tags "project,work" :properties "status"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :list-node (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))
+      (is (= "project,work" (get-in result [:action :options :tags])))
+      (is (= "status" (get-in result [:action :options :properties])))))
+
+  (testing "list asset builds action"
+    (let [parsed {:ok? true :command :list-asset :options {:limit 10 :sort "updated-at"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :list-asset (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))
+      (is (= 10 (get-in result [:action :options :limit])))))
+
+  (testing "search page builds action from --content option"
+    (let [parsed {:ok? true :command :search-page :options {:content "project home"} :args []}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= {:type :search-page
+              :repo "logseq_db_demo"
+              :graph "demo"
+              :query "project home"}
+             (:action result)))))
+
+  (testing "search block requires repo"
+    (let [parsed {:ok? true :command :search-block :options {:content "alpha"} :args []}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code])))))
+
+  (testing "search build-action keeps --content when trailing global option exists"
+    (let [parsed {:ok? true
+                  :command :search-tag
+                  :options {:content "quote" :output "json"}
+                  :args []}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))
+      (is (= "quote" (get-in result [:action :query])))))
+
+  (testing "add block requires content"
+    (let [parsed {:ok? true :command :upsert-block :options {}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :missing-content (get-in result [:error :code])))))
+
+  (testing "add block builds insert-blocks op"
+    (let [parsed {:ok? true :command :upsert-block :options {:content "hello"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (get-in result [:action :type])))))
+
+  (testing "add page requires name"
+    (let [parsed {:ok? true :command :upsert-page :options {}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :missing-page-name (get-in result [:error :code])))))
+
+  (testing "upsert page by id builds update action"
+    (let [parsed {:ok? true
+                  :command :upsert-page
+                  :options {:id 42
+                            :update-properties "{:logseq.property/publishing-public? true}"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :update (get-in result [:action :mode])))
+      (is (= 42 (get-in result [:action :id])))))
+
+  (testing "upsert task builds action"
+    (let [parsed {:ok? true
+                  :command :upsert-task
+                  :options {:content "Task from CLI" :status "todo"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :upsert-task (get-in result [:action :type])))))
+
+  (testing "upsert asset create builds action with default title"
+    (let [parsed {:ok? true
+                  :command :upsert-asset
+                  :options {:path "/tmp/asset-name.png"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :upsert-asset (get-in result [:action :type])))
+      (is (= :create (get-in result [:action :mode])))
+      (is (= "asset-name" (get-in result [:action :blocks 0 :block/title])))))
+
+  (testing "upsert asset update builds action"
+    (let [parsed {:ok? true
+                  :command :upsert-asset
+                  :options {:id 42 :content "New asset title"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :upsert-asset (get-in result [:action :type])))
+      (is (= :update (get-in result [:action :mode])))
+      (is (= 42 (get-in result [:action :id]))))))
+
+(deftest test-build-action-upsert-tag-property
+
+  (testing "upsert tag requires name"
+    (let [parsed {:ok? true :command :upsert-tag :options {}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :missing-tag-name (get-in result [:error :code])))))
+
+  (testing "upsert tag builds normalized action"
+    (let [parsed {:ok? true :command :upsert-tag :options {:name "  #Quote  "}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= {:type :upsert-tag
+              :mode :create
+              :repo "logseq_db_demo"
+              :graph "demo"
+              :name "Quote"}
+             (:action result)))))
+
+  (testing "upsert tag by id builds update action"
+    (let [parsed {:ok? true :command :upsert-tag :options {:id 123}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= {:type :upsert-tag
+              :mode :update
+              :repo "logseq_db_demo"
+              :graph "demo"
+              :id 123}
+             (:action result)))))
+
+  (testing "upsert tag by id with name builds update action"
+    (let [parsed {:ok? true :command :upsert-tag :options {:id 123 :name "  #Project Renamed  "}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= {:type :upsert-tag
+              :mode :update
+              :repo "logseq_db_demo"
+              :graph "demo"
+              :id 123
+              :name "Project Renamed"}
+             (:action result)))))
+
+  (testing "upsert tag by id rejects blank rename name"
+    (let [parsed {:ok? true :command :upsert-tag :options {:id 123 :name "   "}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert property coerces schema options"
+    (let [parsed {:ok? true
+                  :command :upsert-property
+                  :options {:name "owner"
+                            :type "node"
+                            :cardinality "many"
+                            :hide true
+                            :public false}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= {:type :upsert-property
+              :mode :create
+              :repo "logseq_db_demo"
+              :graph "demo"
+              :name "owner"
+              :schema {:logseq.property/type :node
+                       :db/cardinality :db.cardinality/many
+                       :logseq.property/hide? true
+                       :logseq.property/public? false}}
+             (:action result)))))
+
+  (testing "upsert property by id builds update action"
+    (let [parsed {:ok? true
+                  :command :upsert-property
+                  :options {:id 654
+                            :type "node"
+                            :cardinality "many"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= {:type :upsert-property
+              :mode :update
+              :repo "logseq_db_demo"
+              :graph "demo"
+              :id 654
+              :schema {:logseq.property/type :node
+                       :db/cardinality :db.cardinality/many}}
+             (:action result))))))
+
+(deftest test-build-action-inspect-edit-remove-show
+
+  (testing "remove block requires target"
+    (let [parsed {:ok? true :command :remove-block :options {}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :missing-target (get-in result [:error :code])))))
+
+  (testing "remove block normalizes id vector in build action"
+    (let [parsed {:ok? true :command :remove-block :options {:id "[1 2]"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :remove-block (get-in result [:action :type])))
+      (is (= [1 2] (get-in result [:action :ids])))))
+
+  (testing "remove page requires page"
+    (let [parsed {:ok? true :command :remove-page :options {}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :missing-page-name (get-in result [:error :code])))))
+
+  (testing "remove page accepts --page in action build"
+    (let [parsed {:ok? true :command :remove-page :options {:page "Home"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :remove-page (get-in result [:action :type])))
+      (is (= "Home" (get-in result [:action :page])))))
+
+  (testing "remove page accepts --id in action build"
+    (let [parsed {:ok? true :command :remove-page :options {:id 42}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :remove-page (get-in result [:action :type])))
+      (is (= 42 (get-in result [:action :id])))))
+
+  (testing "remove tag parses by id"
+    (let [parsed {:ok? true :command :remove-tag :options {:id 42}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :remove-tag (get-in result [:action :type])))
+      (is (= 42 (get-in result [:action :id])))))
+
+  (testing "remove property parses by name"
+    (let [parsed {:ok? true :command :remove-property :options {:name "owner"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :remove-property (get-in result [:action :type])))
+      (is (= "owner" (get-in result [:action :name])))))
+
+  (testing "show requires target"
+    (let [parsed {:ok? true :command :show :options {}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :missing-target (get-in result [:error :code])))))
+
+  (testing "show normalizes id vector in build action"
+    (let [parsed {:ok? true :command :show :options {:id "[1 2]"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :show (get-in result [:action :type])))
+      (is (= [1 2] (get-in result [:action :ids]))))))
+
+(deftest test-build-action-debug-pull
+  (testing "debug pull uses --graph when provided"
+    (let [parsed {:ok? true :command :debug-pull :options {:graph "demo" :id 1}}
+          result (commands/build-action parsed {})]
+      (is (true? (:ok? result)))
+      (is (= :debug-pull (get-in result [:action :type])))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))
+      (is (= 1 (get-in result [:action :lookup])))
+      (is (= '[*] (get-in result [:action :selector])))))
+
+  (testing "debug pull falls back to config graph"
+    (let [parsed {:ok? true :command :debug-pull :options {:id 1}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))))
+
+  (testing "debug pull falls back to config repo"
+    (let [parsed {:ok? true :command :debug-pull :options {:id 1}}
+          result (commands/build-action parsed {:repo "logseq_db_demo"})]
+      (is (true? (:ok? result)))
+      (is (= "logseq_db_demo" (get-in result [:action :repo])))))
+
+  (testing "debug pull fails when repo cannot be resolved"
+    (let [parsed {:ok? true :command :debug-pull :options {:id 1}}
+          result (commands/build-action parsed {})]
+      (is (false? (:ok? result)))
+      (is (= :missing-repo (get-in result [:error :code]))))))
+
+(deftest test-build-action-add-validates-properties
+  (testing "add block accepts custom property key in update-properties"
+    (let [parsed (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--update-properties" "{:not/a 1}"])
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= {:not/a 1} (get-in result [:action :update-properties])))))
+
+  (testing "add block accepts property title key"
+    (let [parsed (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--update-properties" "{\"Publishing Public?\" true}"])
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :logseq.property/publishing-public?
+             (-> result :action :update-properties keys first)))))
+
+  (testing "add block rejects non-public built-in property"
+    (let [parsed (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--update-properties" "{:logseq.property/heading 1}"])
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "add block rejects invalid checkbox value"
+    (let [parsed (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--update-properties" "{:logseq.property/publishing-public? \"nope\"}"])
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code]))))))
+
+(deftest test-build-action-add-accepts-tag-ids
+  (testing "add block accepts numeric tag ids"
+    (let [parsed (commands/parse-args ["upsert" "block"
+                                       "--content" "hello"
+                                       "--update-tags" "[42]"])
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= [42] (get-in result [:action :update-tags]))))))
+
+(deftest test-tag-lookup-ref-accepts-id
+  (let [tag-lookup-ref #'add-command/tag-lookup-ref]
+    (is (= 42 (tag-lookup-ref 42)))))
+
+(deftest test-normalize-property-key-input-accepts-id
+  (let [normalize-property-key-input #'add-command/normalize-property-key-input]
+    (is (= {:type :id :value 42} (normalize-property-key-input 42)))))
+
+(deftest test-build-action-update
+  (testing "upsert block create mode requires content when source selector is absent"
+    (let [parsed {:ok? true :command :upsert-block :options {:target-id 2}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :missing-content (get-in result [:error :code])))))
+
+  (testing "upsert block update mode requires target or update/remove options"
+    (let [parsed {:ok? true :command :upsert-block :options {:id 1}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "update accepts update tags without target"
+    (let [parsed {:ok? true
+                  :command :upsert-block
+                  :options {:id 1 :update-tags "[\"TagA\"]"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (get-in result [:action :type])))
+      (is (= ["TagA"] (get-in result [:action :update-tags])))))
+
+  (testing "update accepts status-only updates"
+    (let [parsed {:ok? true
+                  :command :upsert-block
+                  :options {:id 1 :status "in-progress"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (get-in result [:action :type])))
+      (is (= :logseq.property/status.doing
+             (get-in result [:action :update-properties :logseq.property/status])))))
+
+  (testing "update accepts content-only updates"
+    (let [parsed {:ok? true
+                  :command :upsert-block
+                  :options {:id 1 :content "updated text"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (get-in result [:action :type])))
+      (is (= "updated text" (get-in result [:action :content])))))
+
+  (testing "update rejects invalid status"
+    (let [parsed {:ok? true
+                  :command :upsert-block
+                  :options {:id 1 :status "invalid-status"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "update properties status takes precedence over --status"
+    (let [parsed {:ok? true
+                  :command :upsert-block
+                  :options {:id 1
+                            :status "doing"
+                            :update-properties "{:logseq.property/status :logseq.property/status.done}"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :logseq.property/status.done
+             (get-in result [:action :update-properties :logseq.property/status])))))
+
+  (testing "update rejects invalid update tags"
+    (let [parsed {:ok? true
+                  :command :upsert-block
+                  :options {:id 1 :update-tags "{:tag \"no\"}"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "upsert block forces update mode when id and content are both provided"
+    (let [parsed {:ok? true
+                  :command :upsert-block
+                  :options {:id 1 :content "hello" :update-tags "[\"TagA\"]"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (get-in result [:action :type])))
+      (is (= 1 (get-in result [:action :id])))
+      (is (= ["TagA"] (get-in result [:action :update-tags])))))
+
+  (testing "update accepts custom property identifiers"
+    (let [parsed {:ok? true
+                  :command :upsert-block
+                  :options {:id 1
+                            :update-properties "{:user.property/owner \"alice\"}"
+                            :remove-properties "[:user.property/owner]"}}
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (= :upsert-block (get-in result [:action :type])))
+      (is (= {:user.property/owner "alice"}
+             (get-in result [:action :update-properties])))
+      (is (= [:user.property/owner]
+             (get-in result [:action :remove-properties]))))))
+
+(deftest test-update-parse-validation
+  (testing "update rejects multiple source selectors"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1" "--uuid" "abc" "--target-id" "2"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "update rejects multiple target selectors"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1" "--target-id" "2" "--target-uuid" "def"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "update rejects invalid position"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1" "--target-id" "2" "--pos" "middle"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "update rejects sibling pos for page target"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1" "--target-page" "Home" "--pos" "sibling"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "update rejects legacy target-page-name option"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1" "--target-page-name" "Home"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))))
+
+  (testing "update rejects pos without target"
+    (let [result (commands/parse-args ["upsert" "block" "--id" "1" "--pos" "last-child" "--update-tags" "[\"TagA\"]"])]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code]))))))
+
+(deftest test-execute-upsert-tag-builds-create-page-op
+  (async done
+         (let [ops* (atom nil)
+               created?* (atom false)
+               action {:type :upsert-tag
+                       :repo "demo"
+                       :name "Quote"}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/q (if @created?*
+                                                                    [{:db/id 4242
+                                                                      :block/name "quote"
+                                                                      :block/title "Quote"
+                                                                      :block/tags [{:db/ident :logseq.class/Tag}]}]
+                                                                    [])
+                                                    :thread-api/apply-outliner-ops (let [[_ ops _] args]
+                                                                                     (reset! created?* true)
+                                                                                     (reset! ops* ops)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [4242] (get-in result [:data :result])))
+                   (is (= [[:create-page ["Quote" {:class? true}]]]
+                          @ops*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-tag-creates-tag-when-non-tag-page-exists
+  (async done
+         (let [created?* (atom false)
+               action {:type :upsert-tag
+                       :repo "demo"
+                       :name "Home"}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ _args]
+                                                  (case method
+                                                    ;; pull-tag-by-name finds no tag (only a page exists)
+                                                    :thread-api/q (if @created?*
+                                                                    [{:db/id 200
+                                                                      :block/name "home"
+                                                                      :block/title "Home"
+                                                                      :block/tags [{:db/ident :logseq.class/Tag}]}]
+                                                                    [])
+                                                    :thread-api/apply-outliner-ops (do
+                                                                                     (reset! created?* true)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [200] (get-in result [:data :result])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-tag-idempotent-when-tag-exists
+  (async done
+         (let [apply-calls* (atom 0)
+               action {:type :upsert-tag
+                       :repo "demo"
+                       :name "Quote"}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/q [{:db/id 4242
+                                                                    :block/name "quote"
+                                                                    :block/title "Quote"
+                                                                    :block/tags [{:db/ident :logseq.class/Tag}]}]
+                                                    :thread-api/apply-outliner-ops (do
+                                                                                     (swap! apply-calls* inc)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [4242] (get-in result [:data :result])))
+                   (is (= 0 @apply-calls*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-property-emits-upsert-op
+  (async done
+         (let [ops* (atom nil)
+               created?* (atom false)
+               action {:type :upsert-property
+                       :repo "demo"
+                       :name "owner"
+                       :schema {:logseq.property/type :node
+                                :db/cardinality :db.cardinality/many}}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/q (if @created?*
+                                                                    [{:db/id 654
+                                                                      :db/ident :user.property/owner
+                                                                      :block/name "owner"
+                                                                      :block/title "owner"
+                                                                      :logseq.property/type :node}]
+                                                                    [])
+                                                    :thread-api/apply-outliner-ops (let [[_ ops _] args]
+                                                                                     (reset! created?* true)
+                                                                                     (reset! ops* ops)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [[:upsert-property [nil
+                                              {:logseq.property/type :node
+                                               :db/cardinality :db.cardinality/many}
+                                              {:property-name "owner"}]]]
+                          @ops*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-tag-by-id-no-op
+  (async done
+         (let [apply-calls* (atom 0)
+               action {:type :upsert-tag
+                       :mode :update
+                       :repo "demo"
+                       :id 4242}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/pull (let [[_ _ lookup] args]
+                                                                       (if (= lookup 4242)
+                                                                         {:db/id 4242
+                                                                          :block/name "quote"
+                                                                          :block/title "Quote"
+                                                                          :block/tags [{:db/ident :logseq.class/Tag}]}
+                                                                         {}))
+                                                    :thread-api/apply-outliner-ops (do
+                                                                                     (swap! apply-calls* inc)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [4242] (get-in result [:data :result])))
+                   (is (= 0 @apply-calls*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-tag-by-id-with-name-emits-rename-op
+  (async done
+         (let [ops* (atom nil)
+               apply-calls* (atom 0)
+               action {:type :upsert-tag
+                       :mode :update
+                       :repo "demo"
+                       :id 4242
+                       :name "Project Renamed"}
+               tag-uuid (uuid "00000000-0000-0000-0000-000000004242")]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/pull (let [[_ _ lookup] args]
+                                                                       (if (= lookup 4242)
+                                                                         {:db/id 4242
+                                                                          :block/uuid tag-uuid
+                                                                          :block/name "project"
+                                                                          :block/title "Project"
+                                                                          :block/tags [{:db/ident :logseq.class/Tag}]}
+                                                                         {}))
+                                                    ;; pull-tag-by-name: no existing tag named "project renamed"
+                                                    :thread-api/q []
+                                                    :thread-api/apply-outliner-ops (let [[_ ops _] args]
+                                                                                     (swap! apply-calls* inc)
+                                                                                     (reset! ops* ops)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [4242] (get-in result [:data :result])))
+                   (is (= 1 @apply-calls*))
+                   (is (= [[:rename-page [tag-uuid "Project Renamed"]]]
+                          @ops*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-tag-by-id-with-name-no-op-when-normalized-name-matches
+  (async done
+         (let [apply-calls* (atom 0)
+               action {:type :upsert-tag
+                       :mode :update
+                       :repo "demo"
+                       :id 4242
+                       :name "  #QUOTE "}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/pull (let [[_ _ lookup] args]
+                                                                       (if (= lookup 4242)
+                                                                         {:db/id 4242
+                                                                          :block/uuid (uuid "00000000-0000-0000-0000-000000004242")
+                                                                          :block/name "quote"
+                                                                          :block/title "Quote"
+                                                                          :block/tags [{:db/ident :logseq.class/Tag}]}
+                                                                         {}))
+                                                    ;; pull-tag-by-name for rename target check
+                                                    :thread-api/q [{:db/id 4242
+                                                                    :block/name "quote"
+                                                                    :block/title "Quote"
+                                                                    :block/tags [{:db/ident :logseq.class/Tag}]}]
+                                                    :thread-api/apply-outliner-ops (do
+                                                                                     (swap! apply-calls* inc)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [4242] (get-in result [:data :result])))
+                   (is (= 0 @apply-calls*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-tag-by-id-rename-proceeds-when-only-non-tag-page-exists
+  (async done
+         (let [apply-calls* (atom 0)
+               action {:type :upsert-tag
+                       :mode :update
+                       :repo "demo"
+                       :id 4242
+                       :name "Project Renamed"}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/pull (let [[_ _ lookup] args]
+                                                                       (if (= lookup 4242)
+                                                                         {:db/id 4242
+                                                                          :block/uuid (uuid "00000000-0000-0000-0000-000000004242")
+                                                                          :block/name "project"
+                                                                          :block/title "Project"
+                                                                          :block/tags [{:db/ident :logseq.class/Tag}]}
+                                                                         {}))
+                                                    ;; pull-tag-by-name: no tag named "project renamed" (only a non-tag page)
+                                                    :thread-api/q []
+                                                    :thread-api/apply-outliner-ops (do
+                                                                                     (swap! apply-calls* inc)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [4242] (get-in result [:data :result])))
+                   (is (= 1 @apply-calls*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-tag-by-id-with-name-rejects-existing-tag
+  (async done
+         (let [apply-calls* (atom 0)
+               action {:type :upsert-tag
+                       :mode :update
+                       :repo "demo"
+                       :id 4242
+                       :name "Project Renamed"}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/pull (let [[_ _ lookup] args]
+                                                                       (if (= lookup 4242)
+                                                                         {:db/id 4242
+                                                                          :block/uuid (uuid "00000000-0000-0000-0000-000000004242")
+                                                                          :block/name "project"
+                                                                          :block/title "Project"
+                                                                          :block/tags [{:db/ident :logseq.class/Tag}]}
+                                                                         {}))
+                                                    ;; pull-tag-by-name: existing tag named "project renamed"
+                                                    :thread-api/q [{:db/id 9001
+                                                                    :block/uuid (uuid "00000000-0000-0000-0000-000000009001")
+                                                                    :block/name "project renamed"
+                                                                    :block/title "Project Renamed"
+                                                                    :block/tags [{:db/ident :logseq.class/Tag}]}]
+                                                    :thread-api/apply-outliner-ops (do
+                                                                                     (swap! apply-calls* inc)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :error (:status result)))
+                   (is (= :tag-rename-conflict (get-in result [:error :code])))
+                   (is (= 0 @apply-calls*))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-id-mode-validates-target-entity
+  (async done
+         (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                             cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ args]
+                                                (case method
+                                                  :thread-api/pull (let [[_ _ lookup] args]
+                                                                     (case lookup
+                                                                       100 {}
+                                                                       101 {:db/id 101
+                                                                            :block/uuid (uuid "00000000-0000-0000-0000-000000000101")}
+                                                                       200 {}
+                                                                       201 {:db/id 201
+                                                                            :block/name "not-a-tag"
+                                                                            :block/title "Not a tag"
+                                                                            :block/tags [{:db/ident :logseq.class/Page}]}
+                                                                       300 {}
+                                                                       301 {:db/id 301
+                                                                            :block/name "not-a-property"
+                                                                            :block/title "Not a property"}
+                                                                       {}))
+                                                  :thread-api/apply-outliner-ops
+                                                  (throw (ex-info "should not mutate on invalid id update mode" {:args args}))
+                                                  (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+               (p/let [page-missing (commands/execute {:type :upsert-page :mode :update :repo "demo" :id 100} {})
+                       page-mismatch (commands/execute {:type :upsert-page :mode :update :repo "demo" :id 101} {})
+                       tag-missing (commands/execute {:type :upsert-tag :mode :update :repo "demo" :id 200} {})
+                       tag-mismatch (commands/execute {:type :upsert-tag :mode :update :repo "demo" :id 201} {})
+                       property-missing (commands/execute {:type :upsert-property :mode :update :repo "demo" :id 300} {})
+                       property-mismatch (commands/execute {:type :upsert-property :mode :update :repo "demo" :id 301} {})]
+                 (is (= :error (:status page-missing)))
+                 (is (= :upsert-id-not-found (get-in page-missing [:error :code])))
+                 (is (= :error (:status page-mismatch)))
+                 (is (= :upsert-id-type-mismatch (get-in page-mismatch [:error :code])))
+                 (is (= :error (:status tag-missing)))
+                 (is (= :upsert-id-not-found (get-in tag-missing [:error :code])))
+                 (is (= :error (:status tag-mismatch)))
+                 (is (= :upsert-id-type-mismatch (get-in tag-mismatch [:error :code])))
+                 (is (= :error (:status property-missing)))
+                 (is (= :upsert-id-not-found (get-in property-missing [:error :code])))
+                 (is (= :error (:status property-mismatch)))
+                 (is (= :upsert-id-type-mismatch (get-in property-mismatch [:error :code])))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-upsert-block-create-resolves-options-before-add-block
+  (async done
+         (let [add-action* (atom nil)
+               property-lookups* (atom [])
+               apply-called?* (atom false)
+               action {:type :upsert-block :mode :create :repo "demo"
+                       :update-tags [:tag/new]
+                       :update-properties {:logseq.property/deadline "2026-01-25T12:00:00Z"}}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               add-command/execute-add-block (fn [add-action _]
+                                                               (reset! add-action* add-action)
+                                                               (p/resolved {:status :ok :data {:result [11 12]}}))
+                               add-command/resolve-tags (fn [_ _ tags]
+                                                          (p/resolved (cond (= tags [:tag/new]) [{:db/id 101}]
+                                                                            :else nil)))
+                               add-command/resolve-properties (fn [_ _ properties & _] (p/resolved properties))
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/pull (let [[_ _ lookup] args]
+                                                                       (swap! property-lookups* conj lookup)
+                                                                       (if (and (vector? lookup) (= :db/ident (first lookup)))
+                                                                         {:db/id 99}
+                                                                         {}))
+                                                    :thread-api/apply-outliner-ops (do
+                                                                                     (reset! apply-called?* true)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [11 12] (get-in result [:data :result])))
+                   (is (= :add-block (:type @add-action*)))
+                   (is (= [{:db/id 101}] (:resolved-tags @add-action*)))
+                   (is (= {:logseq.property/deadline "2026-01-25T12:00:00Z"}
+                          (:resolved-properties @add-action*)))
+                   (is (some #{[:db/ident :logseq.property/deadline]} @property-lookups*))
+                   (is (false? @apply-called?*)
+                       "upsert layer should not perform extra post-create mutations")))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-page-applies-ops-on-existing-page
+  (async done
+         (let [ops* (atom nil)
+               page-uuid (uuid "00000000-0000-0000-0000-000000000050")
+               block-uuids [page-uuid]
+               action {:type :upsert-page :repo "demo" :page "Home"
+                       :update-tags [:tag/next]
+                       :remove-tags [:tag/old]
+                       :update-properties {:logseq.property/publishing-public? true}
+                       :remove-properties [:logseq.property/deadline]}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               add-command/resolve-tags (fn [_ _ tags]
+                                                          (p/resolved (cond (= tags [:tag/next]) [{:db/id 303}]
+                                                                            (= tags [:tag/old]) [{:db/id 202}]
+                                                                            :else nil)))
+                               add-command/resolve-properties (fn [_ _ properties & _] (p/resolved properties))
+                               add-command/resolve-property-identifiers (fn [_ _ properties & _] (p/resolved properties))
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/q (let [[_ [_query input]] args]
+                                                                    (if (= input "home")
+                                                                      [{:db/id 50 :block/uuid page-uuid}]
+                                                                      []))
+                                                    :thread-api/pull (let [[_ selector lookup] args]
+                                                                       (cond
+                                                                         (= lookup [:block/name "home"])
+                                                                         {:db/id 50 :block/uuid page-uuid}
+                                                                         (and (= selector [:db/id :block/uuid])
+                                                                              (= lookup 50))
+                                                                         {:db/id 50 :block/uuid page-uuid}
+                                                                         (and (vector? lookup) (= :db/ident (first lookup)))
+                                                                         {:db/id 888}
+                                                                         :else {}))
+                                                    :thread-api/apply-outliner-ops (let [[_ ops _] args]
+                                                                                     (reset! ops* ops)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})
+                         ops @ops*]
+                   (is (= :ok (:status result)))
+                   (is (= [50] (get-in result [:data :result])))
+                   (is (= 4 (count ops)))
+                   (is (some #(= [:batch-delete-property-value [block-uuids :block/tags 202]] %) ops))
+                   (is (some #(= [:batch-remove-property [block-uuids :logseq.property/deadline]] %) ops))
+                   (is (some #(= [:batch-set-property [block-uuids :block/tags 303 {}]] %) ops))
+                   (is (some #(= [:batch-set-property [block-uuids :logseq.property/publishing-public? true {}]] %) ops))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-page-restores-recycled-page
+  ;; A recycled page with the same name must be treated as "not existing" so
+  ;; the create-page outliner op runs. The outliner's `create` already has a
+  ;; (ldb/recycled? existing-page) branch that restores the page in place,
+  ;; preventing duplicate :block/name entries.
+  (async done
+         (let [batches* (atom [])
+               recycled-uuid (uuid "00000000-0000-0000-0000-0000000000ec")
+               action {:type :upsert-page :repo "demo" :page "Home"
+                       :update-properties {:logseq.property/publishing-public? true}}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               add-command/resolve-tags (fn [_ _ _] (p/resolved nil))
+                               add-command/resolve-properties (fn [_ _ properties & _] (p/resolved properties))
+                               add-command/resolve-property-identifiers (fn [_ _ properties & _] (p/resolved properties))
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/q (let [[_ [_query input]] args]
+                                                                    (if (= input "home")
+                                                                      [{:db/id 50
+                                                                        :block/uuid recycled-uuid
+                                                                        :logseq.property/deleted-at 1712000000000}]
+                                                                      []))
+                                                    :thread-api/pull (let [[_ selector lookup] args]
+                                                                       (cond
+                                                                         (= lookup [:block/name "home"])
+                                                                         {:db/id 50
+                                                                          :block/uuid recycled-uuid
+                                                                          :logseq.property/deleted-at 1712000000000}
+                                                                         (= lookup [:block/uuid recycled-uuid])
+                                                                         {:db/id 50 :block/uuid recycled-uuid}
+                                                                         (and (= selector [:db/id :block/uuid])
+                                                                              (= lookup 50))
+                                                                         {:db/id 50 :block/uuid recycled-uuid}
+                                                                         (and (vector? lookup) (= :db/ident (first lookup)))
+                                                                         {:db/id 999}
+                                                                         :else {}))
+                                                    :thread-api/apply-outliner-ops (let [[_ ops _] args]
+                                                                                     (swap! batches* conj ops)
+                                                                                     ["Home" recycled-uuid])
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (some (fn [batch]
+                               (some #(= [:create-page ["Home" {}]] %) batch))
+                             @batches*)
+                       "create-page op is invoked, which restores the recycled page in the outliner")))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-page-errors-on-ambiguous-name
+  (async done
+         (let [action {:type :upsert-page :repo "demo" :page "c1"
+                       :update-tags [:tag/next]}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               add-command/resolve-tags (fn [_ _ _] (p/resolved nil))
+                               add-command/resolve-properties (fn [_ _ _ & _] (p/resolved nil))
+                               add-command/resolve-property-identifiers (fn [_ _ _ & _] (p/resolved nil))
+                               transport/invoke (fn [_ method _ _]
+                                                  (case method
+                                                    :thread-api/q [{:db/id 21
+                                                                    :block/name "c1"
+                                                                    :block/title "c1"
+                                                                    :block/uuid (uuid "00000000-0000-0000-0000-0000000000c1")}
+                                                                   {:db/id 22
+                                                                    :block/name "c1"
+                                                                    :block/title "c1"
+                                                                    :block/uuid (uuid "00000000-0000-0000-0000-0000000000c2")}]
+                                                    :thread-api/apply-outliner-ops
+                                                    (throw (ex-info "should not modify on ambiguous match" {:method method}))
+                                                    (throw (ex-info "unexpected invoke" {:method method}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :error (:status result)))
+                   (is (= :ambiguous-page-name (get-in result [:error :code])))
+                   (is (= #{21 22}
+                          (set (map :id (get-in result [:error :candidates])))))
+                   (is (string/includes? (get-in result [:error :message]) "rerun with --id"))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-upsert-page-by-id-rejects-recycled-page
+  (async done
+         (let [action {:type :upsert-page :mode :update :repo "demo" :id 50}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ _]
+                                                  (case method
+                                                    :thread-api/pull {:db/id 50
+                                                                      :block/name "home"
+                                                                      :block/title "Home"
+                                                                      :block/uuid (uuid "00000000-0000-0000-0000-0000000000ed")
+                                                                      :logseq.property/deleted-at 1712000000000}
+                                                    :thread-api/apply-outliner-ops
+                                                    (throw (ex-info "should not apply ops on recycled page" {:method method}))
+                                                    (throw (ex-info "unexpected invoke" {:method method}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :error (:status result)))
+                   (is (= :upsert-id-not-found (get-in result [:error :code])))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-show-page-skips-recycled-page
+  ;; `execute-show` throws `ex-info` with `:code :page-not-found` rather than
+  ;; returning `:status :error`; the top-level CLI catches it. The test
+  ;; mirrors that contract by inspecting the rejected promise.
+  (async done
+         (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                             cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ _]
+                                                (case method
+                                                  :thread-api/pull {:db/id 50
+                                                                    :block/uuid (uuid "00000000-0000-0000-0000-0000000000ee")
+                                                                    :block/title "Home"
+                                                                    :logseq.property/deleted-at 1712000000000}
+                                                  :thread-api/q []
+                                                  (throw (ex-info "unexpected invoke" {:method method}))))]
+               (-> (commands/execute {:type :show :repo "demo" :page "Home"} {})
+                   (p/then (fn [result]
+                             (is false (str "expected page-not-found error, got: " result))))
+                   (p/catch (fn [e]
+                              (is (= :page-not-found (:code (ex-data e))))
+                              (is (= "page not found" (ex-message e)))))))
+             (p/finally done))))
+
+(deftest test-build-action-upsert-page-accepts-user-property
+  (testing "upsert page accepts user property key in update-properties"
+    (let [parsed (commands/parse-args ["upsert" "page"
+                                       "--page" "Home"
+                                       "--update-properties" "{\"p1\" \"default\"}"])
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (some? (get-in result [:action :update-properties])))))
+
+  (testing "upsert page accepts user property key in remove-properties"
+    (let [parsed (commands/parse-args ["upsert" "page"
+                                       "--page" "Home"
+                                       "--remove-properties" "[\"p1\"]"])
+          result (commands/build-action parsed {:graph "demo"})]
+      (is (true? (:ok? result)))
+      (is (some? (get-in result [:action :remove-properties]))))))
+
+(deftest test-execute-upsert-page-errors-when-property-does-not-exist
+  (async done
+         (let [action {:type :upsert-page :repo "demo" :page "Home"
+                       :update-properties {:logseq.property/deadline "2026-01-25T12:00:00Z"}}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               add-command/resolve-tags (fn [_ _ _] (p/resolved nil))
+                               add-command/resolve-properties (fn [_ _ properties & _] (p/resolved properties))
+                               add-command/resolve-property-identifiers (fn [_ _ properties & _] (p/resolved properties))
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/pull (let [[_ _ lookup] args]
+                                                                       (cond
+                                                                         (= lookup [:block/name "home"]) {:db/id 50}
+                                                                         (and (vector? lookup) (= :db/ident (first lookup))) {}
+                                                                         :else {}))
+                                                    :thread-api/apply-outliner-ops
+                                                    (throw (ex-info "should not apply ops when property lookup fails" {:args args}))
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :error (:status result)))
+                   (is (= :property-not-found (get-in result [:error :code])))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-remove-tag-property
+  (async done
+         (let [ops* (atom [])]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/cli-list-tags [{:db/id 1 :block/title "Quote"}]
+                                                    :thread-api/cli-list-properties [{:db/id 2 :block/title "owner"}]
+                                                    :thread-api/pull (let [[_ selector lookup] args]
+                                                                       (cond
+                                                                         (= lookup 1) {:db/id 1 :block/title "Quote" :block/uuid (uuid "00000000-0000-0000-0000-000000000011") :block/tags [{:db/ident :logseq.class/Tag}] :logseq.property/public? true}
+                                                                         (= lookup 2) {:db/id 2 :db/ident :user.property/owner :block/title "owner" :block/uuid (uuid "00000000-0000-0000-0000-000000000022") :logseq.property/type :node :logseq.property/public? true}
+                                                                         (= lookup [:block/name "quote"]) {:db/id 1 :block/title "Quote" :block/uuid (uuid "00000000-0000-0000-0000-000000000011") :block/tags [{:db/ident :logseq.class/Tag}] :logseq.property/public? true}
+                                                                         (= lookup [:block/name "owner"]) {:db/id 2 :db/ident :user.property/owner :block/title "owner" :block/uuid (uuid "00000000-0000-0000-0000-000000000022") :logseq.property/type :node :logseq.property/public? true}
+                                                                         :else (throw (ex-info "unexpected pull lookup" {:lookup lookup :selector selector}))))
+                                                    :thread-api/apply-outliner-ops (let [[_ ops _] args]
+                                                                                     (swap! ops* conj ops)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [tag-result (commands/execute {:type :remove-tag :repo "demo" :name "Quote"} {})
+                         property-result (commands/execute {:type :remove-property :repo "demo" :id 2} {})]
+                   (is (= :ok (:status tag-result)))
+                   (is (= :ok (:status property-result)))
+                   (is (= [[:delete-page [(uuid "00000000-0000-0000-0000-000000000011") {}]]]
+                          (first @ops*)))
+                   (is (= [[:delete-page [(uuid "00000000-0000-0000-0000-000000000022") {}]]]
+                          (second @ops*)))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-remove-page-skips-recycled-page
+  (async done
+         (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                             cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ _]
+                                                (case method
+                                                  :thread-api/q [{:db/id 11
+                                                                  :block/title "Recycled"
+                                                                  :block/uuid (uuid "00000000-0000-0000-0000-00000000bee5")
+                                                                  :logseq.property/deleted-at 1712000000000}]
+                                                  :thread-api/apply-outliner-ops
+                                                  (throw (ex-info "should not delete a recycled page" {:method method}))
+                                                  (throw (ex-info "unexpected invoke" {:method method}))))]
+               (p/let [result (commands/execute {:type :remove-page :repo "demo" :page "Recycled"} {})]
+                 (is (= :error (:status result)))
+                 (is (= :page-not-found (get-in result [:error :code])))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-remove-page-returns-true-result-on-success
+  (async done
+         (let [ops* (atom nil)
+               page-uuid (uuid "00000000-0000-0000-0000-00000000abcd")]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/q (let [[_ [_query input]] args]
+                                                                    (if (= input "home")
+                                                                      [{:db/id 10
+                                                                        :block/title "Home"
+                                                                        :block/name "home"
+                                                                        :block/uuid page-uuid}]
+                                                                      []))
+                                                    :thread-api/apply-outliner-ops (let [[_ ops _] args]
+                                                                                     (reset! ops* ops)
+                                                                                     nil)
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute {:type :remove-page :repo "demo" :page "Home"} {})]
+                   (is (= :ok (:status result)))
+                   (is (= true (get-in result [:data :result])))
+                   (is (= [[:delete-page [page-uuid {}]]]
+                          @ops*))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-remove-page-errors-on-ambiguous-name
+  ;; `:block/name` is not unique — two distinct pages can have the same
+  ;; sanity-lc'd name. The CLI should refuse to randomly pick one and
+  ;; instead point the user at --id with the candidate ids.
+  (async done
+         (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                             cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ _]
+                                                (case method
+                                                  :thread-api/q [{:db/id 21
+                                                                  :block/name "c1"
+                                                                  :block/title "c1"
+                                                                  :block/uuid (uuid "00000000-0000-0000-0000-0000000000c1")}
+                                                                 {:db/id 22
+                                                                  :block/name "c1"
+                                                                  :block/title "c1"
+                                                                  :block/uuid (uuid "00000000-0000-0000-0000-0000000000c2")}]
+                                                  :thread-api/apply-outliner-ops
+                                                  (throw (ex-info "should not delete on ambiguous match" {:method method}))
+                                                  (throw (ex-info "unexpected invoke" {:method method}))))]
+               (p/let [result (commands/execute {:type :remove-page :repo "demo" :page "c1"} {})]
+                 (is (= :error (:status result)))
+                 (is (= :ambiguous-page-name (get-in result [:error :code])))
+                 (is (= #{21 22}
+                        (set (map :id (get-in result [:error :candidates])))))
+                 (is (string/includes? (get-in result [:error :message]) "rerun with --id"))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-remove-page-by-id
+  (async done
+         (let [ops* (atom nil)
+               page-uuid (uuid "00000000-0000-0000-0000-00000000abce")]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               transport/invoke (fn [_ method _ args]
+                                                  (case method
+                                                    :thread-api/pull (let [[_ _ lookup] args]
+                                                                       (if (= lookup 10)
+                                                                         {:db/id 10
+                                                                          :block/title "Home"
+                                                                          :block/name "home"
+                                                                          :block/uuid page-uuid}
+                                                                         {}))
+                                                    :thread-api/apply-outliner-ops (let [[_ ops _] args]
+                                                                                     (reset! ops* ops)
+                                                                                     nil)
+                                                    (throw (ex-info "unexpected invoke" {:method method :args args}))))]
+                 (p/let [result (commands/execute {:type :remove-page :repo "demo" :id 10} {})]
+                   (is (= :ok (:status result)))
+                   (is (= true (get-in result [:data :result])))
+                   (is (= [[:delete-page [page-uuid {}]]]
+                          @ops*))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-remove-tag-ambiguous-name
+  (async done
+         (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                             cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ _]
+                                                (case method
+                                                  :thread-api/cli-list-tags [{:db/id 1 :block/title "Quote"}
+                                                                             {:db/id 2 :block/title "QUOTE"}]
+                                                  (throw (ex-info "unexpected invoke" {:method method}))))]
+               (p/let [result (commands/execute {:type :remove-tag :repo "demo" :name "Quote"} {})]
+                 (is (= :error (:status result)))
+                 (is (= :ambiguous-tag-name (get-in result [:error :code])))
+                 (is (= 2 (count (get-in result [:error :candidates]))))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-update-builds-batch-ops
+  (async done
+         (let [ops* (atom nil)
+               calls* (atom [])
+               action {:type :upsert-block :mode :update :repo "demo" :id 1 :target-id 2 :pos "last-child"
+                       :content "Updated heading"
+                       :update-tags [:tag/new]
+                       :remove-tags [:tag/old]
+                       :update-properties {:logseq.property/deadline "2026-01-25T12:00:00Z"
+                                           :logseq.property/status :logseq.property/status.done}
+                       :remove-properties [:logseq.property/publishing-public?]}]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                               add-command/resolve-tags (fn [_ _ tags]
+                                                          (p/resolved (cond (= tags [:tag/new]) [{:db/id 101}]
+                                                                            (= tags [:tag/old]) [{:db/id 202}]
+                                                                            :else nil)))
+                               add-command/resolve-properties (fn [_ _ properties & _] (p/resolved properties))
+                               add-command/resolve-property-identifiers (fn [_ _ properties & _] (p/resolved properties))
+                               transport/invoke (fn [_ method _ args]
+                                                  (swap! calls* conj {:method method :args args})
+                                                  (case method
+                                                    :thread-api/pull (let [[_ _ lookup] args]
+                                                                       (cond
+                                                                         (= lookup 1) {:db/id 1 :block/name nil :block/uuid (uuid "00000000-0000-0000-0000-000000000001")}
+                                                                         (= lookup 2) {:db/id 2 :block/name nil :block/uuid (uuid "00000000-0000-0000-0000-000000000002")}
+                                                                         :else {}))
+                                                    :thread-api/apply-outliner-ops (let [[_ ops _] args]
+                                                                                     (reset! ops* ops)
+                                                                                     {:result :ok})
+                                                    (throw (ex-info "unexpected invoke" {:method method :calls @calls*}))))]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result)))
+                   (is (= [[:save-block [{:block/uuid (uuid "00000000-0000-0000-0000-000000000001")
+                                           :block/title "Updated heading"} {}]]
+                           [:move-blocks [[(uuid "00000000-0000-0000-0000-000000000001")]
+                                          (uuid "00000000-0000-0000-0000-000000000002")
+                                          {:sibling? false :bottom? true}]]
+                           [:batch-delete-property-value [[(uuid "00000000-0000-0000-0000-000000000001")]
+                                                          :block/tags
+                                                          202]]
+                           [:batch-remove-property [[(uuid "00000000-0000-0000-0000-000000000001")]
+                                                    :logseq.property/publishing-public?]]
+                           [:batch-set-property [[(uuid "00000000-0000-0000-0000-000000000001")]
+                                                 :block/tags
+                                                 101
+                                                 {}]]
+                           [:batch-set-property [[(uuid "00000000-0000-0000-0000-000000000001")]
+                                                 :logseq.property/deadline
+                                                 "2026-01-25T12:00:00Z"
+                                                 {}]]
+                           [:batch-set-property [[(uuid "00000000-0000-0000-0000-000000000001")]
+                                                 :logseq.property/status
+                                                 :logseq.property/status.done
+                                                 {}]]]
+                          @ops*))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e " calls: " @calls*))))
+               (p/finally done)))))
+
+(deftest test-execute-search-dispatch
+  (async done
+         (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                             cli-server/ensure-server! (fn [_ _] {:base-url "http://example"})
+                             transport/invoke (fn [_ method _ [repo [query-text query-input]]]
+                                                (is (= :thread-api/q method))
+                                                (is (= "logseq_db_demo" repo))
+                                                (is (= "quote" query-input))
+                                                (is (re-find #":logseq.class/Tag" (pr-str query-text)))
+                                                [{:db/id 1 :block/title "Quote"}])]
+               (p/let [result (commands/execute {:type :search-tag
+                                                 :repo "logseq_db_demo"
+                                                 :query "quote"}
+                                                {})]
+                 (is (= :ok (:status result)))
+                 (is (= :search-tag (:command result)))
+                 (is (= [{:db/id 1 :block/title "Quote"}] (get-in result [:data :items])))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-task-dispatch
+  (async done
+         (let [calls* (atom [])]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               list-command/execute-list-task (fn [action _]
+                                                                (swap! calls* conj action)
+                                                                (p/resolved {:status :ok
+                                                                             :data {:items []}}))
+                               upsert-command/execute-upsert-task (fn [action _]
+                                                                    (swap! calls* conj action)
+                                                                    (p/resolved {:status :ok
+                                                                                 :data {:result [101]}}))]
+                 (p/let [list-result (commands/execute {:type :list-task :repo "logseq_db_demo"} {})
+                         upsert-result (commands/execute {:type :upsert-task :repo "logseq_db_demo"} {})]
+                   (is (= :ok (:status list-result)))
+                   (is (= :list-task (:command list-result)))
+                   (is (= :ok (:status upsert-result)))
+                   (is (= :upsert-task (:command upsert-result)))
+                   (is (= [:list-task :upsert-task]
+                          (mapv :type @calls*)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-asset-dispatch
+  (async done
+         (let [calls* (atom [])]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               list-command/execute-list-asset (fn [action _]
+                                                                 (swap! calls* conj action)
+                                                                 (p/resolved {:status :ok
+                                                                              :data {:items []}}))
+                               upsert-command/execute-upsert-asset (fn [action _]
+                                                                     (swap! calls* conj action)
+                                                                     (p/resolved {:status :ok
+                                                                                  :data {:result [202]}}))]
+                 (p/let [list-result (commands/execute {:type :list-asset :repo "logseq_db_demo"} {})
+                         upsert-result (commands/execute {:type :upsert-asset :repo "logseq_db_demo"} {})]
+                   (is (= :ok (:status list-result)))
+                   (is (= :list-asset (:command list-result)))
+                   (is (= :ok (:status upsert-result)))
+                   (is (= :upsert-asset (:command upsert-result)))
+                   (is (= [:list-asset :upsert-asset]
+                          (mapv :type @calls*)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-server-cleanup-dispatch
+  (async done
+         (-> (p/with-redefs [server-command/execute-cleanup (fn [action config]
+                                                              (is (= :server-cleanup (:type action)))
+                                                              (is (= {:root-dir "/tmp/demo"} config))
+                                                              (p/resolved {:status :ok
+                                                                           :data {:checked 3}}))]
+               (p/let [result (commands/execute {:type :server-cleanup} {:root-dir "/tmp/demo"})]
+                 (is (= :ok (:status result)))
+                 (is (= :server-cleanup (:command result)))
+                 (is (= 3 (get-in result [:data :checked])))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-requires-existing-graph
+  (async done
+         (-> (p/with-redefs [cli-server/list-graphs (fn [_] [])
+                             cli-server/ensure-server! (fn [_ _]
+                                                         (throw (ex-info "should not start server" {})))]
+               (p/let [result (commands/execute {:type :list-page :repo "logseq_db_missing"} {})]
+                 (is (= :error (:status result)))
+                 (is (= :graph-not-exists (get-in result [:error :code])))
+                 (is (= "graph not exists" (get-in result [:error :message])))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-graph-import-rejects-existing-graph
+  (async done
+         (let [{:keys [action]} (graph-command/build-import-action "logseq_db_demo" "sqlite" "/tmp/test-db.sqlite")]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                              cli-server/ensure-server! (fn [_ _]
+                                                          (throw (ex-info "should not start server" {})))]
+                (p/let [result (commands/execute action {})]
+                  (is (= :error (:status result)))
+                  (is (= :graph-exists (get-in result [:error :code])))))
+              (p/catch (fn [e] (is false (str "unexpected error: " e))))
+              (p/finally done)))))
+
+(deftest test-execute-graph-import-edn-allows-existing-graph
+  (async done
+         (let [{:keys [action]} (graph-command/build-import-action "logseq_db_demo" "edn" "/tmp/test.edn")]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/stop-server! (fn [_ _] (p/resolved {:ok? true}))
+                               cli-server/restart-server! (fn [_ _] (p/resolved {:ok? true}))
+                               cli-server/ensure-server! (fn [config _] (assoc config :base-url "http://example"))
+                               transport/read-input (fn [_] {:page "Test"})
+                               transport/invoke (fn [_ _ _ _] {:ok true})]
+                 (p/let [result (commands/execute action {})]
+                   (is (= :ok (:status result))
+                       "edn import into existing graph should succeed")))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-sync-download-rejects-existing-graph
+  (async done
+         (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                             cli-server/ensure-server! (fn [_ _]
+                                                         (throw (ex-info "should not start server" {})))]
+               (p/let [result (commands/execute {:type :sync-download
+                                                 :repo "logseq_db_demo"
+                                                 :graph "demo"
+                                                 :allow-missing-graph true
+                                                 :require-missing-graph true}
+                                                {})]
+                 (is (= :error (:status result)))
+                 (is (= :graph-exists (get-in result [:error :code])))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-sync-download-runs-command-when-graph-is-missing
+  (async done
+         (let [captured (atom nil)]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] [])
+                               sync-command/execute (fn [action config]
+                                                      (reset! captured [action config])
+                                                      (p/resolved {:status :ok
+                                                                   :data {:repo (:repo action)}}))]
+                 (p/let [result (commands/execute {:type :sync-download
+                                                   :repo "logseq_db_demo"
+                                                   :graph "demo"
+                                                   :allow-missing-graph true
+                                                   :require-missing-graph true}
+                                                  {:root-dir "/tmp"})]
+                   (is (= :ok (:status result)))
+                   (is (= "logseq_db_demo" (get-in result [:data :repo])))
+                   (is (= :sync-download (get-in @captured [0 :type])))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-export
+  (async done
+         (let [invoke-calls (atom [])
+               write-calls (atom [])]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] ["demo"])
+                               cli-server/ensure-server! (fn [config _]
+                                                           (assoc config :base-url "http://127.0.0.1:9999"))
+                               transport/invoke (fn [_ method direct-pass? args]
+                                                  (swap! invoke-calls conj [method direct-pass? args])
+                                                  (if (= method :thread-api/export-db-base64)
+                                                    "c3FsaXRl"
+                                                    {:exported true}))
+                               transport/write-output (fn [opts]
+                                                        (swap! write-calls conj opts))]
+                 (p/let [edn-result (commands/execute {:type :graph-export :repo "logseq_db_demo" :graph "demo" :export-type "edn" :file "/tmp/export.edn" :allow-missing-graph true} {})
+                         sqlite-result (commands/execute {:type :graph-export :repo "logseq_db_demo" :graph "demo" :export-type "sqlite" :file "/tmp/export.sqlite" :allow-missing-graph true} {})]
+                   (is (= :ok (:status edn-result)))
+                   (is (= :ok (:status sqlite-result)))
+                   (is (= "edn" (get-in edn-result [:context :export-type])))
+                   (is (= "/tmp/export.edn" (get-in edn-result [:context :file])))
+                   (is (= "sqlite" (get-in sqlite-result [:context :export-type])))
+                   (is (= "/tmp/export.sqlite" (get-in sqlite-result [:context :file])))
+                   (is (= [[:thread-api/export-edn false ["logseq_db_demo" {:export-type :graph}]]
+                           [:thread-api/export-db-base64 true ["logseq_db_demo"]]]
+                          @invoke-calls))
+                   (is (= 2 (count @write-calls)))
+                   (let [[edn-write sqlite-write] @write-calls]
+                     (is (= {:format :edn :path "/tmp/export.edn" :data {:exported true}} edn-write))
+                     (is (= :sqlite (:format sqlite-write)))
+                     (is (= "/tmp/export.sqlite" (:path sqlite-write)))
+                     (is (= "sqlite" (.toString (:data sqlite-write) "utf8"))))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-import
+  (async done
+         (let [invoke-calls (atom [])
+               read-calls (atom [])
+               stop-calls (atom [])
+               restart-calls (atom [])]
+           (-> (p/with-redefs [cli-server/list-graphs (fn [_] [])
+                               cli-server/stop-server! (fn [_ repo] (swap! stop-calls conj repo) (p/resolved {:ok? true}))
+                               cli-server/restart-server! (fn [_ repo] (swap! restart-calls conj repo) (p/resolved {:ok? true}))
+                               cli-server/ensure-server! (fn [config _] (assoc config :base-url "http://127.0.0.1:9999"))
+                               transport/read-input (fn [{:keys [format path]}]
+                                                      (swap! read-calls conj [format path])
+                                                      (if (= format :edn)
+                                                        {:page "Import Page"}
+                                                        (js/Buffer.from "sqlite" "utf8")))
+                               transport/invoke (fn [_ method _ args]
+                                                  (swap! invoke-calls conj [method args])
+                                                  {:ok true})]
+                 (p/let [edn-result (commands/execute {:type :graph-import :repo "logseq_db_demo" :graph "demo" :import-type "edn" :input "/tmp/import.edn" :allow-missing-graph true} {})
+                         sqlite-result (commands/execute {:type :graph-import :repo "logseq_db_demo" :graph "demo" :import-type "sqlite" :input "/tmp/import.sqlite" :allow-missing-graph true} {})]
+                   (is (= :ok (:status edn-result)))
+                   (is (= :ok (:status sqlite-result)))
+                   (is (= "edn" (get-in edn-result [:context :import-type])))
+                   (is (= "/tmp/import.edn" (get-in edn-result [:context :input])))
+                   (is (= "sqlite" (get-in sqlite-result [:context :import-type])))
+                   (is (= "/tmp/import.sqlite" (get-in sqlite-result [:context :input])))
+                   (is (= [[:edn "/tmp/import.edn"] [:sqlite "/tmp/import.sqlite"]] @read-calls))
+                   (is (= [[:thread-api/import-edn ["logseq_db_demo" {:page "Import Page"}]]
+                           [:thread-api/import-db-base64 ["logseq_db_demo" "c3FsaXRl"]]]
+                          @invoke-calls))
+                   (is (= ["logseq_db_demo" "logseq_db_demo"] @stop-calls))
+                   (is (= ["logseq_db_demo" "logseq_db_demo"] @restart-calls))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-list-strips-db-prefix
+  (async done
+         (-> (p/with-redefs [cli-server/list-graph-items (fn [_] [{:kind :canonical
+                                                                   :graph-name "logseq_db_demo"
+                                                                   :graph-dir "logseq_db_demo"}
+                                                                  {:kind :canonical
+                                                                   :graph-name "logseq_db_logseq_db_other"
+                                                                   :graph-dir "logseq_db_logseq_db_other"}
+                                                                  {:kind :canonical
+                                                                   :graph-name "my_logseq_db_notes"
+                                                                   :graph-dir "my_logseq_db_notes"}])]
+               (p/let [result (commands/execute {:type :graph-list} {})]
+                 (is (= :ok (:status result)))
+                 (is (= ["demo" "logseq_db_other" "my_logseq_db_notes"]
+                        (get-in result [:data :graphs])))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-execute-graph-list-keeps-classified-items-without-legacy-string-compat
+  (async done
+         (let [graph-items [{:kind :canonical
+                             :graph-name "alpha"
+                             :graph-dir "alpha"}
+                            {:kind :legacy
+                             :legacy-dir "legacy++name"
+                             :legacy-graph-name "legacy/name"
+                             :target-graph-dir "legacy~2Fname"
+                             :conflict? false}]]
+           (-> (p/with-redefs [cli-server/list-graph-items (fn [_]
+                                                             graph-items)]
+                 (p/let [result (commands/execute {:type :graph-list} {})]
+                   (is (= :ok (:status result)))
+                   (is (= graph-items
+                          (get-in result [:data :graph-items])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest test-execute-graph-list-includes-legacy-metadata
+  (async done
+         (-> (p/with-redefs [cli-server/list-graph-items (fn [_]
+                                                           [{:kind :canonical
+                                                             :graph-name "alpha"
+                                                             :graph-dir "alpha"}
+                                                            {:kind :legacy
+                                                             :legacy-dir "legacy++name"
+                                                             :legacy-graph-name "legacy/name"
+                                                             :target-graph-dir "legacy~2Fname"
+                                                             :conflict? false}
+                                                            {:kind :legacy-undecodable
+                                                             :legacy-dir "mystery"
+                                                             :reason :undecodable}])]
+               (p/let [result (commands/execute {:type :graph-list} {:root-dir "/tmp/graphs"})]
+                 (is (= :ok (:status result)))
+                 (is (= ["alpha" "legacy/name" "mystery"]
+                        (get-in result [:data :graphs])))
+                 (is (= [{:kind :canonical
+                          :graph-name "alpha"
+                          :graph-dir "alpha"}
+                         {:kind :legacy
+                          :legacy-dir "legacy++name"
+                          :legacy-graph-name "legacy/name"
+                          :target-graph-dir "legacy~2Fname"
+                          :conflict? false}
+                         {:kind :legacy-undecodable
+                          :legacy-dir "mystery"
+                          :reason :undecodable}]
+                        (get-in result [:data :graph-items])))
+                 (is (= 2 (get-in result [:human :graph-list :legacy-count])))))
+             (p/catch (fn [e] (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest test-query-build-action-non-vector-inputs
+  (testing "non-vector inputs gives explicit error"
+    (let [result (query-command/build-action {:name "recent-updated" :inputs "1"}
+                                             "test-repo" {})]
+      (is (false? (:ok? result)))
+      (is (= :invalid-options (get-in result [:error :code])))
+      (is (= "inputs must be a vector" (get-in result [:error :message])))))
+
+  (testing "valid vector inputs succeeds"
+    (let [result (query-command/build-action {:name "recent-updated" :inputs "[1]"}
+                                             "test-repo" {})]
+      (is (true? (:ok? result))))))
+
+(deftest test-query-execute-appends-dsl-rules-for-percent-in
+  (async done
+         (let [captured-args (atom nil)
+               config {:custom-queries
+                       {:task
+                        {:query '[:find (pull ?b [*])
+                                  :in $ ?status %
+                                  :where
+                                  (task ?b ?status)]
+                         :inputs [{:name "task statuses set"}]}}}
+               action-result (query-command/build-action
+                              {:name "task" :inputs "[\"Todo\"]"}
+                              "test-repo" config)]
+           (is (true? (:ok? action-result)))
+           (-> (p/with-redefs [cli-server/ensure-server! (fn [config _] config)
+                                transport/invoke (fn [_ _method _ args]
+                                                   (reset! captured-args (second args))
+                                                   (p/resolved []))]
+                 (query-command/execute-query (:action action-result) config))
+               (p/then (fn [_]
+                         (let [args @captured-args
+                               last-arg (last args)]
+                           (is (vector? last-arg)
+                               "last arg should be the rules vector")
+                           (is (= last-arg
+                                  (rules/extract-rules rules/db-query-dsl-rules))
+                               "should append db-query-dsl-rules when :in ends with %"))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally done)))))
diff --git a/src/test/logseq/cli/common/db_worker_test.cljs b/src/test/logseq/cli/common/db_worker_test.cljs
new file mode 100644
index 0000000000..4b2cd324c8
--- /dev/null
+++ b/src/test/logseq/cli/common/db_worker_test.cljs
@@ -0,0 +1,344 @@
+(ns logseq.cli.common.db-worker-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [clojure.set :as set]
+            [datascript.core :as d]
+            [logseq.cli.common.db-worker :as cli-db-worker]
+            [logseq.db.test.helper :as db-test]))
+
+(defn- create-test-db
+  []
+  (let [conn (db-test/create-conn-with-blocks
+              {:classes {:custom-tag {}}
+               :properties {:custom-property {:logseq.property/type :default}}
+               :pages-and-blocks [{:page {:block/title "Visible Page"
+                                          :block/created-at 1000
+                                          :block/updated-at 2000}}
+                                  {:page {:block/title "Hidden Page"
+                                          :block/created-at 1500
+                                          :block/updated-at 2500
+                                          :build/properties {:logseq.property/hide? true}}}
+                                  {:page {:build/journal 20260201
+                                          :block/created-at 3000
+                                          :block/updated-at 4000}}
+                                  {:page {:block/title "Late Page"
+                                          :block/created-at 5000
+                                          :block/updated-at 6000}}]})]
+    @conn))
+
+(defn- list-item-ids
+  [items]
+  (->> items (map :db/id) set))
+
+(defn- first-user-tag-entity
+  [db]
+  (->> (d/datoms db :avet :block/tags :logseq.class/Tag)
+       (map :e)
+       (map #(d/entity db %))
+       (remove :logseq.property/built-in?)
+       first))
+
+(defn- first-user-property-entity
+  [db]
+  (->> (d/datoms db :avet :block/tags :logseq.class/Property)
+       (map :e)
+       (map #(d/entity db %))
+       (remove :logseq.property/built-in?)
+       first))
+
+(deftest test-list-non-expanded-contract
+  (let [db (create-test-db)
+        required-keys #{:db/id :block/title :block/created-at :block/updated-at}
+        required-property-keys #{:db/id :block/title :block/created-at :block/updated-at
+                                 :logseq.property/type :db/cardinality}
+        visible-page (some #(when (= "Visible Page" (:block/title %)) %)
+                           (cli-db-worker/list-pages db {}))
+        custom-tag-entity (first-user-tag-entity db)
+        custom-tag-title (:block/title custom-tag-entity)
+        custom-tag (some #(when (= custom-tag-title (:block/title %)) %)
+                         (cli-db-worker/list-tags db {}))
+        custom-property-entity (first-user-property-entity db)
+        custom-property-title (:block/title custom-property-entity)
+        custom-property (some #(when (= custom-property-title (:block/title %)) %)
+                              (cli-db-worker/list-properties db {}))]
+    (testing "list-pages non-expanded includes stable id and timestamps"
+      (is (some? visible-page))
+      (is (set/subset? required-keys (set (keys visible-page)))))
+
+    (testing "list-tags non-expanded includes stable id and timestamps"
+      (is (some? custom-tag))
+      (is (set/subset? required-keys (set (keys custom-tag)))))
+
+    (testing "list-properties non-expanded includes stable id, timestamps, and cardinality"
+      (is (some? custom-property))
+      (is (set/subset? required-property-keys (set (keys custom-property)))))))
+
+(deftest test-list-properties-default-cardinality-contract
+  (let [db (create-test-db)
+        custom-property-title (:block/title (first-user-property-entity db))
+        custom-property (some #(when (= custom-property-title (:block/title %)) %)
+                              (cli-db-worker/list-properties db {}))]
+    (testing "property without explicit cardinality defaults to :db.cardinality/one"
+      (is (some? custom-property))
+      (is (= :db.cardinality/one (:db/cardinality custom-property))))))
+
+(deftest test-list-tags-and-properties-include-built-in-default
+  (let [db (create-test-db)
+        built-in-tag-ids (->> (d/datoms db :avet :block/tags :logseq.class/Tag)
+                              (map :e)
+                              (map #(d/entity db %))
+                              (filter :logseq.property/built-in?)
+                              (map :db/id)
+                              set)
+        built-in-property-ids (->> (d/datoms db :avet :block/tags :logseq.class/Property)
+                                   (map :e)
+                                   (map #(d/entity db %))
+                                   (filter :logseq.property/built-in?)
+                                   (map :db/id)
+                                   set)
+        custom-tag-id (:db/id (first-user-tag-entity db))
+        custom-property-id (:db/id (first-user-property-entity db))
+        default-tag-ids (list-item-ids (cli-db-worker/list-tags db {}))
+        default-property-ids (list-item-ids (cli-db-worker/list-properties db {}))
+        no-built-in-tag-ids (list-item-ids (cli-db-worker/list-tags db {:include-built-in false}))
+        no-built-in-property-ids (list-item-ids (cli-db-worker/list-properties db {:include-built-in false}))]
+    (testing "built-ins are included by default"
+      (is (seq built-in-tag-ids))
+      (is (seq built-in-property-ids))
+      (is (seq (set/intersection default-tag-ids built-in-tag-ids)))
+      (is (seq (set/intersection default-property-ids built-in-property-ids))))
+
+    (testing "include-built-in=false excludes built-ins but keeps user entities"
+      (is (contains? no-built-in-tag-ids custom-tag-id))
+      (is (contains? no-built-in-property-ids custom-property-id))
+      (is (empty? (set/intersection no-built-in-tag-ids built-in-tag-ids)))
+      (is (empty? (set/intersection no-built-in-property-ids built-in-property-ids))))))
+
+(deftest test-list-pages-filter-contract
+  (let [db (create-test-db)
+        hidden-id (->> (d/q '[:find [?e ...]
+                              :in $ ?title
+                              :where
+                              [?e :block/title ?title]
+                              [?e :logseq.property/hide? true]]
+                            db "Hidden Page")
+                       first)
+        journal-id (->> (d/datoms db :avet :block/journal-day 20260201)
+                        first
+                        :e)
+        visible-id (->> (d/q '[:find [?e ...]
+                               :in $ ?title
+                               :where [?e :block/title ?title]]
+                             db "Visible Page")
+                        first)
+        late-id (->> (d/q '[:find [?e ...]
+                            :in $ ?title
+                            :where [?e :block/title ?title]]
+                          db "Late Page")
+                     first)
+        default-ids (list-item-ids (cli-db-worker/list-pages db {}))
+        include-hidden-ids (list-item-ids (cli-db-worker/list-pages db {:include-hidden true}))
+        exclude-journal-ids (list-item-ids (cli-db-worker/list-pages db {:include-journal false}))
+        journal-only-ids (list-item-ids (cli-db-worker/list-pages db {:journal-only true}))
+        created-after-ids (list-item-ids (cli-db-worker/list-pages db {:created-after 2500}))
+        updated-after-ids (list-item-ids (cli-db-worker/list-pages db {:updated-after "1970-01-01T00:00:03.500Z"}))
+        invalid-created-after-ids (list-item-ids (cli-db-worker/list-pages db {:created-after "not-a-date"}))
+        invalid-updated-after-ids (list-item-ids (cli-db-worker/list-pages db {:updated-after "still-not-a-date"}))]
+    (testing "journals are included by default and hidden pages are excluded by default"
+      (is (contains? default-ids journal-id))
+      (is (not (contains? default-ids hidden-id))))
+
+    (testing "include-hidden includes hidden pages"
+      (is (contains? include-hidden-ids hidden-id)))
+
+    (testing "include-journal and journal-only page filters"
+      (is (not (contains? exclude-journal-ids journal-id)))
+      (is (= #{journal-id} journal-only-ids)))
+
+    (testing "created-after and updated-after filters"
+      (is (contains? created-after-ids journal-id))
+      (is (contains? created-after-ids late-id))
+      (is (not (contains? created-after-ids visible-id)))
+      (is (contains? updated-after-ids journal-id))
+      (is (contains? updated-after-ids late-id))
+      (is (not (contains? updated-after-ids visible-id))))
+
+    (testing "invalid date filters behave as no-op"
+      (is (= default-ids invalid-created-after-ids))
+      (is (= default-ids invalid-updated-after-ids)))))
+
+(deftest test-list-tasks-contract
+  (let [db0 (create-test-db)
+        visible-id (->> (d/q '[:find [?e ...]
+                               :in $ ?title
+                               :where [?e :block/title ?title]]
+                             db0 "Visible Page")
+                        first)
+        late-id (->> (d/q '[:find [?e ...]
+                            :in $ ?title
+                            :where [?e :block/title ?title]]
+                          db0 "Late Page")
+                     first)
+        db1 (d/db-with db0 [[:db/add visible-id :block/tags :logseq.class/Task]
+                            [:db/add visible-id :logseq.property/status :logseq.property/status.todo]
+                            [:db/add visible-id :logseq.property/priority :logseq.property/priority.high]
+                            [:db/add visible-id :logseq.property/scheduled "2026-02-10T08:00:00.000Z"]
+                            [:db/add visible-id :logseq.property/deadline "2026-02-12T18:00:00.000Z"]
+                            [:db/add late-id :block/tags :logseq.class/Task]
+                            [:db/add late-id :logseq.property/status :logseq.property/status.done]
+                            [:db/add late-id :logseq.property/priority :logseq.property/priority.low]
+                            [:db/add -1 :block/title "Task Block Alpha"]
+                            [:db/add -1 :block/page visible-id]
+                            [:db/add -1 :block/parent visible-id]
+                            [:db/add -1 :block/order "a"]
+                            [:db/add -1 :block/created-at 7000]
+                            [:db/add -1 :block/updated-at 7100]
+                            [:db/add -1 :block/tags :logseq.class/Task]
+                            [:db/add -1 :logseq.property/status :logseq.property/status.doing]
+                            [:db/add -1 :logseq.property/priority :logseq.property/priority.high]])
+        task-block-id (->> (d/q '[:find [?e ...]
+                                  :in $ ?title
+                                  :where
+                                  [?e :block/title ?title]
+                                  [?e :block/page]]
+                                db1 "Task Block Alpha")
+                           first)
+        all-ids (list-item-ids (cli-db-worker/list-tasks db1 {}))
+        status-ids (list-item-ids (cli-db-worker/list-tasks db1 {:status :logseq.property/status.todo}))
+        priority-ids (list-item-ids (cli-db-worker/list-tasks db1 {:priority :logseq.property/priority.high}))
+        content-ids (list-item-ids (cli-db-worker/list-tasks db1 {:content "aLpHa"}))
+        combined-ids (list-item-ids (cli-db-worker/list-tasks db1 {:status :logseq.property/status.doing
+                                                                    :priority :logseq.property/priority.high
+                                                                    :content "alpha"}))
+        visible-task (->> (cli-db-worker/list-tasks db1 {})
+                          (filter #(= visible-id (:db/id %)))
+                          first)]
+    (testing "task list includes task pages and task blocks"
+      (is (contains? all-ids visible-id))
+      (is (contains? all-ids late-id))
+      (is (contains? all-ids task-block-id)))
+
+    (testing "task filters apply status, priority, and content constraints"
+      (is (= #{visible-id} status-ids))
+      (is (= #{visible-id task-block-id} priority-ids))
+      (is (= #{task-block-id} content-ids))
+      (is (= #{task-block-id} combined-ids)))
+
+    (testing "task rows include task property fields"
+      (is (= :logseq.property/status.todo (:logseq.property/status visible-task)))
+      (is (= :logseq.property/priority.high (:logseq.property/priority visible-task)))
+      (is (= "2026-02-10T08:00:00.000Z" (:logseq.property/scheduled visible-task)))
+      (is (= "2026-02-12T18:00:00.000Z" (:logseq.property/deadline visible-task))))))
+
+(defn- create-list-node-test-db
+  []
+  (let [conn (db-test/create-conn-with-blocks
+              {:classes {:tag-alpha {}
+                         :tag-beta {}
+                         :tag-gamma {}}
+               :properties {:prop-alpha {:logseq.property/type :default}
+                            :prop-beta {:logseq.property/type :default}
+                            :prop-gamma {:logseq.property/type :default}}
+               :pages-and-blocks [{:page {:block/title "Node Page AB"
+                                          :block/created-at 1000
+                                          :block/updated-at 2000
+                                          :build/tags [:tag-alpha :tag-beta]
+                                          :build/properties {:prop-alpha "a"
+                                                             :prop-beta "b"}}
+                                  :blocks [{:block/title "Node Block AB"
+                                            :build/tags [:tag-alpha :tag-beta]
+                                            :build/properties {:prop-alpha "a"
+                                                               :prop-beta "b"}}
+                                           {:block/title "Node Block A"
+                                            :build/tags [:tag-alpha]
+                                            :build/properties {:prop-alpha "a"}}]}
+                                 {:page {:block/title "Node Page A"
+                                         :block/created-at 3000
+                                         :block/updated-at 4000
+                                         :build/tags [:tag-alpha]
+                                         :build/properties {:prop-alpha "a"}}}
+                                 {:page {:block/title "Node Page B"
+                                         :block/created-at 5000
+                                         :block/updated-at 6000
+                                         :build/tags [:tag-beta]
+                                         :build/properties {:prop-beta "b"}}}]})]
+    @conn))
+
+(defn- title->id
+  [db title]
+  (->> (d/q '[:find [?e ...]
+              :in $ ?title
+              :where [?e :block/title ?title]]
+            db title)
+       first))
+
+(defn- block-title->id
+  [db title]
+  (->> (d/q '[:find [?e ...]
+              :in $ ?title
+              :where
+              [?e :block/title ?title]
+              [?e :block/page]]
+            db title)
+       first))
+
+(defn- invoke-list-nodes
+  [db options]
+  (when-let [list-nodes-fn (resolve 'logseq.cli.common.db-worker/list-nodes)]
+    (list-nodes-fn db options)))
+
+(defn- class-entity-id-by-name
+  [db class-ident block-name]
+  (->> (d/q '[:find [?e ...]
+              :in $ ?class-ident ?block-name
+              :where
+              [?e :block/name ?block-name]
+              [?e :block/tags ?class]
+              [?class :db/ident ?class-ident]]
+            db class-ident block-name)
+       first))
+
+(defn- property-ident-by-name
+  [db block-name]
+  (some-> (class-entity-id-by-name db :logseq.class/Property block-name)
+          ((fn [id] (d/entity db id)))
+          :db/ident))
+
+(deftest test-list-nodes-filter-contract
+  (let [db (create-list-node-test-db)
+        tag-alpha-id (class-entity-id-by-name db :logseq.class/Tag "tag-alpha")
+        tag-beta-id (class-entity-id-by-name db :logseq.class/Tag "tag-beta")
+        prop-alpha-ident (property-ident-by-name db "prop-alpha")
+        prop-beta-ident (property-ident-by-name db "prop-beta")
+        page-ab-id (title->id db "Node Page AB")
+        page-a-id (title->id db "Node Page A")
+        page-b-id (title->id db "Node Page B")
+        block-ab-id (block-title->id db "Node Block AB")
+        block-a-id (block-title->id db "Node Block A")
+        tag-match-ids (list-item-ids (or (invoke-list-nodes db {:tag-ids [tag-alpha-id tag-beta-id]}) []))
+        property-match-ids (list-item-ids (or (invoke-list-nodes db {:property-idents [prop-alpha-ident prop-beta-ident]}) []))
+        combined-match-ids (list-item-ids (or (invoke-list-nodes db {:tag-ids [tag-alpha-id tag-beta-id]
+                                                                     :property-idents [prop-alpha-ident prop-beta-ident]}) []))
+        schema-definition-ids (->> (concat (d/datoms db :avet :block/tags :logseq.class/Tag)
+                                           (d/datoms db :avet :block/tags :logseq.class/Property))
+                                   (map :e)
+                                   set)]
+    (testing "list-nodes function must exist"
+      (is (some? (resolve 'logseq.cli.common.db-worker/list-nodes))))
+
+    (testing "tag filter uses all-of semantics"
+      (is (= #{page-ab-id block-ab-id} tag-match-ids))
+      (is (not (contains? tag-match-ids page-a-id)))
+      (is (not (contains? tag-match-ids page-b-id))))
+
+    (testing "property filter uses all-of semantics"
+      (is (= #{page-ab-id block-ab-id} property-match-ids))
+      (is (not (contains? property-match-ids page-a-id)))
+      (is (not (contains? property-match-ids block-a-id))))
+
+    (testing "tag/property filters combine with AND semantics"
+      (is (= #{page-ab-id block-ab-id} combined-match-ids)))
+
+    (testing "schema-definition entities are excluded from node results"
+      (is (empty? (set/intersection tag-match-ids schema-definition-ids)))
+      (is (empty? (set/intersection property-match-ids schema-definition-ids)))
+      (is (empty? (set/intersection combined-match-ids schema-definition-ids))))))
diff --git a/src/test/logseq/cli/common/graph_test.cljs b/src/test/logseq/cli/common/graph_test.cljs
new file mode 100644
index 0000000000..6b61cabd92
--- /dev/null
+++ b/src/test/logseq/cli/common/graph_test.cljs
@@ -0,0 +1,45 @@
+(ns logseq.cli.common.graph-test
+  (:require [cljs.test :refer [deftest is]]
+            [clojure.string :as string]
+            [frontend.test.node-helper :as node-helper]
+            [logseq.cli.common.graph :as cli-common-graph]
+            ["fs" :as fs]
+            ["path" :as node-path]))
+
+(deftest get-db-based-graphs-canonicalizes-legacy-prefixed-directory-names
+  (let [graphs-dir (node-helper/create-tmp-dir "cli-common-graph")
+        _ (doseq [dir ["demo"
+                       "logseq_db_demo"
+                       "logseq_db_logseq_db_demo"
+                       "logseq_local_file-graph"
+                       "Unlinked graphs"]]
+            (fs/mkdirSync (node-path/join graphs-dir dir) #js {:recursive true}))]
+    (with-redefs [cli-common-graph/get-db-graphs-dir (fn [] graphs-dir)]
+      (let [graphs (cli-common-graph/get-db-based-graphs)]
+        (is (= #{"logseq_db_demo"} (set graphs)))
+        (is (not-any? #(string/starts-with? % "logseq_db_logseq_db_") graphs))))))
+
+(deftest get-db-based-graphs-decodes-encoded-graph-directories
+  (let [graphs-dir (node-helper/create-tmp-dir "cli-common-graph-encoded")
+        _ (doseq [dir ["foo~2Fbar"
+                       "a~3Ab"
+                       "space name"
+                       "space~20name"
+                       "space%20name"
+                       "Unlinked graphs"]]
+            (fs/mkdirSync (node-path/join graphs-dir dir) #js {:recursive true}))]
+    (with-redefs [cli-common-graph/get-db-graphs-dir (fn [] graphs-dir)]
+      (let [graphs (set (cli-common-graph/get-db-based-graphs))]
+        (is (= #{"logseq_db_foo/bar"
+                 "logseq_db_a:b"
+                 "logseq_db_space name"}
+               graphs))))))
+
+(deftest get-db-based-graphs-ignores-legacy-graph-dir-encodings
+  (let [graphs-dir (node-helper/create-tmp-dir "cli-common-graph-legacy")
+        _ (doseq [dir ["foo++bar"
+                       "a+3A+b"
+                       "Unlinked graphs"]]
+            (fs/mkdirSync (node-path/join graphs-dir dir) #js {:recursive true}))]
+    (with-redefs [cli-common-graph/get-db-graphs-dir (fn [] graphs-dir)]
+      (is (= [] (cli-common-graph/get-db-based-graphs))))))
diff --git a/src/test/logseq/cli/common_test.cljs b/src/test/logseq/cli/common_test.cljs
new file mode 100644
index 0000000000..8b33ee6272
--- /dev/null
+++ b/src/test/logseq/cli/common_test.cljs
@@ -0,0 +1,44 @@
+(ns logseq.cli.common-test
+  (:require ["fs-extra" :as fs]
+            ["path" :as node-path]
+            [cljs.test :refer [deftest is]]
+            [frontend.test.node-helper :as node-helper]
+            [logseq.cli.common :as cli-common]
+            [logseq.common.graph :as common-graph]
+            [logseq.common.config :as common-config]))
+
+(deftest unlink-graph-moves-to-unlinked-dir
+  (let [graphs-dir (node-helper/create-tmp-dir "unlink-graph")
+        graph-name "foo/bar"
+        repo (str common-config/db-version-prefix graph-name)
+        encoded-graph-dir "foo~2Fbar"
+        graph-path (node-path/join graphs-dir encoded-graph-dir)
+        unlinked-path (node-path/join graphs-dir common-config/unlinked-graphs-dir encoded-graph-dir)]
+    (fs/mkdirSync graph-path #js {:recursive true})
+    (fs/writeFileSync (node-path/join graph-path "db.sqlite") "test-data")
+    (with-redefs [common-graph/get-default-graphs-dir (fn [] graphs-dir)]
+      (cli-common/unlink-graph! repo)
+      (is (not (fs/existsSync graph-path))
+          "Original graph directory should no longer exist")
+      (is (fs/existsSync unlinked-path)
+          "Graph directory should be moved to Unlinked graphs")
+      (is (fs/existsSync (node-path/join unlinked-path "db.sqlite"))
+          "Graph contents should be preserved after move"))))
+
+(deftest unlink-graph-moves-space-preserving-canonical-dir
+  (let [graphs-dir (node-helper/create-tmp-dir "unlink-graph-space")
+        graph-name "space name"
+        repo (str common-config/db-version-prefix graph-name)
+        encoded-graph-dir "space name"
+        graph-path (node-path/join graphs-dir encoded-graph-dir)
+        unlinked-path (node-path/join graphs-dir common-config/unlinked-graphs-dir encoded-graph-dir)]
+    (fs/mkdirSync graph-path #js {:recursive true})
+    (fs/writeFileSync (node-path/join graph-path "db.sqlite") "test-data")
+    (with-redefs [common-graph/get-default-graphs-dir (fn [] graphs-dir)]
+      (cli-common/unlink-graph! repo)
+      (is (not (fs/existsSync graph-path))
+          "Original space-preserving graph directory should no longer exist")
+      (is (fs/existsSync unlinked-path)
+          "Space-preserving graph directory should be moved to Unlinked graphs")
+      (is (fs/existsSync (node-path/join unlinked-path "db.sqlite"))
+          "Graph contents should be preserved after move"))))
diff --git a/src/test/logseq/cli/completion_generator_test.cljs b/src/test/logseq/cli/completion_generator_test.cljs
new file mode 100644
index 0000000000..e54aaf7060
--- /dev/null
+++ b/src/test/logseq/cli/completion_generator_test.cljs
@@ -0,0 +1,611 @@
+(ns logseq.cli.completion-generator-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [clojure.string :as string]
+            [logseq.cli.command.completion :as completion-command]
+            [logseq.cli.command.core :as core]
+            [logseq.cli.command.debug :as debug-command]
+            [logseq.cli.command.doctor :as doctor-command]
+            [logseq.cli.command.example :as example-command]
+            [logseq.cli.command.graph :as graph-command]
+            [logseq.cli.command.list :as list-command]
+            [logseq.cli.command.query :as query-command]
+            [logseq.cli.command.remove :as remove-command]
+            [logseq.cli.command.search :as search-command]
+            [logseq.cli.command.server :as server-command]
+            [logseq.cli.command.show :as show-command]
+            [logseq.cli.command.skill :as skill-command]
+            [logseq.cli.command.upsert :as upsert-command]
+            [logseq.cli.completion-generator :as gen]))
+
+(def ^:private base-table
+  (vec (concat graph-command/entries
+               server-command/entries
+               list-command/entries
+               upsert-command/entries
+               remove-command/entries
+               query-command/entries
+               search-command/entries
+               show-command/entries
+               doctor-command/entries
+               debug-command/entries
+               completion-command/entries
+               skill-command/entries)))
+
+(def ^:private full-table
+  (vec (concat base-table
+               (example-command/build-example-entries base-table))))
+
+;; ---------------------------------------------------------------------------
+;; Phase 1 — Spec enrichment tests
+;; ---------------------------------------------------------------------------
+
+(deftest test-global-spec-metadata
+  (let [spec (core/global-spec)]
+    (testing ":output has :validate set"
+      (is (= #{"human" "json" "edn"} (get-in spec [:output :validate]))))
+    (testing ":graph has :complete :graphs"
+      (is (= :graphs (get-in spec [:graph :complete]))))
+    (testing ":config has :complete :file"
+      (is (= :file (get-in spec [:config :complete]))))
+    (testing ":root-dir has :complete :dir"
+      (is (= :dir (get-in spec [:root-dir :complete]))))
+    (testing ":profile is a global boolean flag"
+      (is (= :boolean (get-in spec [:profile :coerce]))))))
+
+(deftest test-list-spec-metadata
+  (let [entries list-command/entries
+        page-entry (first (filter #(= :list-page (:command %)) entries))
+        tag-entry (first (filter #(= :list-tag (:command %)) entries))
+        property-entry (first (filter #(= :list-property (:command %)) entries))
+        task-entry (first (filter #(= :list-task (:command %)) entries))]
+    (testing "page-spec :sort has some correct values"
+      (is (contains? (get-in page-entry [:spec :sort :validate]) "title")))
+    (testing "tag-spec :sort has some correct values"
+      (is (contains? (get-in tag-entry [:spec :sort :validate]) "title")))
+    (testing "property-spec :sort has some correct values"
+      (is (contains? (get-in property-entry [:spec :sort :validate]) "title")))
+    (testing "common :order has correct values"
+      (is (= #{"asc" "desc"}
+             (get-in page-entry [:spec :order :validate]))))
+    (testing "tag-spec :fields has :multiple-values"
+      (let [mv (get-in tag-entry [:spec :fields :multiple-values])]
+        (is (seq mv))
+        (is (some #{"title"} mv))
+        (is (some #{"uuid"} mv))))
+    (testing "list task :content has -c alias"
+      (is (= :c (get-in task-entry [:spec :content :alias]))))))
+
+(deftest test-upsert-spec-metadata
+  (let [entries upsert-command/entries
+        block-entry (first (filter #(= :upsert-block (:command %)) entries))
+        page-entry (first (filter #(= :upsert-page (:command %)) entries))
+        task-entry (first (filter #(= :upsert-task (:command %)) entries))
+        tag-entry (first (filter #(= :upsert-tag (:command %)) entries))
+        property-entry (first (filter #(= :upsert-property (:command %)) entries))]
+    (testing "block-spec :pos has :validate set"
+      (is (= #{"first-child" "last-child" "sibling"}
+             (get-in block-entry [:spec :pos :validate]))))
+    (testing "block-spec does not expose :status option"
+      (is (nil? (get-in block-entry [:spec :status]))))
+    (testing "block-spec :target-page has :complete :pages"
+      (is (= :pages (get-in block-entry [:spec :target-page :complete]))))
+    (testing "block-spec :blocks-file has :complete :file"
+      (is (= :file (get-in block-entry [:spec :blocks-file :complete]))))
+    (testing "page-spec :page has :complete :pages"
+      (is (= :pages (get-in page-entry [:spec :page :complete]))))
+    (testing "task-spec contains paired task set/clear options"
+      (is (contains? (:spec task-entry) :status))
+      (is (contains? (:spec task-entry) :priority))
+      (is (contains? (:spec task-entry) :scheduled))
+      (is (contains? (:spec task-entry) :deadline))
+      (is (contains? (:spec task-entry) :no-status))
+      (is (contains? (:spec task-entry) :no-priority))
+      (is (contains? (:spec task-entry) :no-scheduled))
+      (is (contains? (:spec task-entry) :no-deadline))
+      (is (not (contains? (:spec task-entry) :update-tags)))
+      (is (not (contains? (:spec task-entry) :update-properties)))
+      (is (not (contains? (:spec task-entry) :remove-tags)))
+      (is (not (contains? (:spec task-entry) :remove-properties))))
+    (testing "tag-spec :name has :complete :tags"
+      (is (= :tags (get-in tag-entry [:spec :name :complete]))))
+    (testing "property-spec :name has :complete :properties"
+      (is (= :properties (get-in property-entry [:spec :name :complete]))))
+    (testing "property-spec :type has :validate set"
+      (let [types (get-in property-entry [:spec :type :validate])]
+        (is (set? types))
+        (is (contains? types "default"))
+        (is (contains? types "node"))
+        (is (contains? types "checkbox"))))
+    (testing "property-spec :cardinality has :validate set"
+      (is (= #{"one" "many"}
+             (get-in property-entry [:spec :cardinality :validate]))))))
+
+(deftest test-graph-spec-metadata
+  (let [entries graph-command/entries
+        export-entry (first (filter #(= :graph-export (:command %)) entries))
+        import-entry (first (filter #(= :graph-import (:command %)) entries))
+        backup-create-entry (first (filter #(= :graph-backup-create (:command %)) entries))
+        backup-restore-entry (first (filter #(= :graph-backup-restore (:command %)) entries))
+        backup-remove-entry (first (filter #(= :graph-backup-remove (:command %)) entries))]
+    (testing "export-spec :type has :validate set"
+      (is (= #{"edn" "sqlite"} (get-in export-entry [:spec :type :validate]))))
+    (testing "export-spec :file has :complete :file"
+      (is (= :file (get-in export-entry [:spec :file :complete]))))
+    (testing "import-spec :type has :validate set"
+      (is (= #{"edn" "sqlite"} (get-in import-entry [:spec :type :validate]))))
+    (testing "import-spec :input has :complete :file"
+      (is (= :file (get-in import-entry [:spec :input :complete]))))
+    (testing "backup create has optional --name option"
+      (is (contains? (:spec backup-create-entry) :name)))
+    (testing "backup restore has --src and --dst options"
+      (is (contains? (:spec backup-restore-entry) :src))
+      (is (contains? (:spec backup-restore-entry) :dst)))
+    (testing "backup remove has --src option"
+      (is (contains? (:spec backup-remove-entry) :src)))))
+
+(deftest test-query-spec-metadata
+  (let [entries query-command/entries
+        query-entry (first (filter #(= :query (:command %)) entries))]
+    (testing "query-spec :name has :complete :queries"
+      (is (= :queries (get-in query-entry [:spec :name :complete]))))))
+
+(deftest test-show-spec-metadata
+  (let [entries show-command/entries
+        show-entry (first (filter #(= :show (:command %)) entries))]
+    (testing "show-spec :page has :complete :pages"
+      (is (= :pages (get-in show-entry [:spec :page :complete]))))))
+
+(deftest test-remove-spec-metadata
+  (let [entries remove-command/entries
+        page-entry (first (filter #(= :remove-page (:command %)) entries))
+        tag-entry (first (filter #(= :remove-tag (:command %)) entries))
+        property-entry (first (filter #(= :remove-property (:command %)) entries))]
+    (testing "remove-page :page has :complete :pages"
+      (is (= :pages (get-in page-entry [:spec :page :complete]))))
+    (testing "remove-tag :name has :complete :tags"
+      (is (= :tags (get-in tag-entry [:spec :name :complete]))))
+    (testing "remove-property :name has :complete :properties"
+      (is (= :properties (get-in property-entry [:spec :name :complete]))))))
+
+(deftest test-search-spec-metadata
+  (let [entries search-command/entries]
+    (doseq [command [:search-block :search-page :search-property :search-tag]]
+      (let [entry (first (filter #(= command (:command %)) entries))]
+        (testing (str (name command) " has :content option")
+          (is (contains? (:spec entry) :content))
+          (is (= :c (get-in entry [:spec :content :alias])))
+          (is (= "Search content text" (get-in entry [:spec :content :desc]))))))))
+
+;; ---------------------------------------------------------------------------
+;; Phase 2 — Generator table introspection utilities
+;; ---------------------------------------------------------------------------
+
+(deftest test-extract-groups
+  (let [groups (gen/extract-groups full-table)]
+    (testing "graph export is in graph group"
+      (let [graph-entries (get groups "graph")]
+        (is (some #(= ["graph" "export"] (:cmds %)) graph-entries))))
+    (testing "show is a standalone group"
+      (let [show-entries (get groups "show")]
+        (is (= 1 (count show-entries)))
+        (is (= ["show"] (:cmds (first show-entries))))))
+    (testing "completion is a standalone group"
+      (let [completion-entries (get groups "completion")]
+        (is (= 1 (count completion-entries)))
+        (is (= ["completion"] (:cmds (first completion-entries))))))
+    (testing "skill is a subcommand group"
+      (let [skill-entries (get groups "skill")
+            skill-cmds (set (map :cmds skill-entries))]
+        (is (= 2 (count skill-entries)))
+        (is (contains? skill-cmds ["skill" "show"]))
+        (is (contains? skill-cmds ["skill" "install"]))))))
+
+(deftest test-leaf-and-group-commands
+  (let [leaves (gen/leaf-commands full-table)
+        groups (gen/group-commands full-table)
+        leaf-names (set (map #(first (:cmds %)) leaves))
+        group-names (set groups)]
+    (testing "show and doctor are leaves"
+      (is (contains? leaf-names "show"))
+      (is (contains? leaf-names "doctor")))
+    (testing "graph, server, list, upsert, remove, search, debug, example, skill are groups"
+      (is (contains? group-names "graph"))
+      (is (contains? group-names "server"))
+      (is (contains? group-names "list"))
+      (is (contains? group-names "upsert"))
+      (is (contains? group-names "remove"))
+      (is (contains? group-names "search"))
+      (is (contains? group-names "debug"))
+      (is (contains? group-names "example"))
+      (is (contains? group-names "skill")))))
+
+(deftest test-spec->token
+  (testing "boolean spec → :flag type"
+    (let [token (gen/spec->token [:help {:coerce :boolean :desc "Show help"}])]
+      (is (= :flag (:type token)))))
+  (testing "spec with :validate set → :enum type"
+    (let [token (gen/spec->token [:output {:validate #{"human" "json" "edn"} :desc "Format"}])]
+      (is (= :enum (:type token)))
+      (is (= ["edn" "human" "json"] (:values token)))))
+  (testing "spec with :complete :graphs → :dynamic type"
+    (let [token (gen/spec->token [:graph {:complete :graphs :desc "Graph name"}])]
+      (is (= :dynamic (:type token)))
+      (is (= :graphs (:complete token)))))
+  (testing "spec with :complete :file → :file type"
+    (let [token (gen/spec->token [:config {:complete :file :desc "Config"}])]
+      (is (= :file (:type token)))))
+  (testing "spec with :complete :dir → :dir type"
+    (let [token (gen/spec->token [:root-dir {:complete :dir :desc "Root dir"}])]
+      (is (= :dir (:type token)))))
+  (testing "spec with :alias → includes alias"
+    (let [token (gen/spec->token [:help {:alias :h :coerce :boolean :desc "Help"}])]
+      (is (= :h (:alias token)))))
+  (testing "bare string spec → :free type"
+    (let [token (gen/spec->token [:query {:desc "Query EDN"}])]
+      (is (= :free (:type token)))))
+  (testing "spec with :multiple-values → :multi type"
+    (let [token (gen/spec->token [:fields {:desc "Fields" :multiple-values ["id" "title" "uuid"]}])]
+      (is (= :multi (:type token)))
+      (is (= ["id" "title" "uuid"] (:values token))))))
+
+;; ---------------------------------------------------------------------------
+;; Phase 3 — Zsh output
+;; ---------------------------------------------------------------------------
+
+(deftest test-generate-zsh-structure
+  (let [output (gen/generate-completions "zsh" full-table)]
+    (testing "output starts with #compdef logseq"
+      (is (string/starts-with? output "#compdef logseq")))
+    (testing "output contains dynamic helpers"
+      (is (string/includes? output "_logseq_graphs"))
+      (is (string/includes? output "_logseq_pages"))
+      (is (string/includes? output "_logseq_queries"))
+      (is (string/includes? output "_logseq_json_names"))
+      (is (string/includes? output "_logseq_current_graph")))
+    (testing "page completion reads namespaced block/title key"
+      (is (string/includes? output "_logseq_json_names data items block/title")))
+    (testing "output contains per-command functions"
+      (is (string/includes? output "_logseq_graph_export()"))
+      (is (string/includes? output "_logseq_graph_backup_restore()"))
+      (is (string/includes? output "_logseq_graph_backup_remove()"))
+      (is (string/includes? output "_logseq_debug_pull()"))
+      (is (string/includes? output "_logseq_show()"))
+      (is (string/includes? output "_logseq_example_upsert_page()")))
+    (testing "output contains group dispatchers"
+      (is (string/includes? output "_logseq_graph()"))
+      (is (string/includes? output "_logseq_list()"))
+      (is (string/includes? output "_logseq_search()"))
+      (is (string/includes? output "_logseq_upsert()"))
+      (is (string/includes? output "_logseq_debug()"))
+      (is (string/includes? output "_logseq_example()"))
+      (is (string/includes? output "_logseq_skill()")))
+    (testing "output contains top-level dispatcher"
+      (is (string/includes? output "_logseq()")))
+    (testing "output ends with compdef _logseq logseq"
+      (is (string/includes? output "compdef _logseq logseq")))
+    (testing "boolean flags emit alias grouping"
+      (is (string/includes? output "'{-v,--verbose}'[")))
+    (testing "global profile flag is present in zsh completion"
+      (is (string/includes? output "'--profile[")))
+    (testing "global boolean flags do NOT emit --no- negation token"
+      (is (not (string/includes? output "--no-verbose")))
+      (is (not (string/includes? output "--no-help")))
+      (is (not (string/includes? output "--no-profile"))))
+    (testing "enum options emit separate long= and short+ specs"
+      (is (string/includes? output "--output=[Output format. Default: human]:value:(edn human json)'"))
+      (is (string/includes? output "-o[Output format. Default: human]:value:(edn human json)'")))
+    (testing ":complete :graphs emits separate long= and short+ specs"
+      (is (string/includes? output "--graph=[Graph name]:value:{_logseq_graphs}'"))
+      (is (string/includes? output "-g[Graph name]:value:{_logseq_graphs}'")))
+    (testing ":complete :file emits long spec for --config without short alias"
+      (is (string/includes? output "--config=[Path to cli.edn (default <root-dir>/cli.edn)]:file:_files'"))
+      (is (not (string/includes? output "-c[Path to cli.edn (default <root-dir>/cli.edn)]:file:_files'"))))
+    (testing "-c is available as content alias in command-specific completion"
+      (is (re-find #"(?s)_logseq_search_block\(\).*?-c\[Search content text\]" output))
+      (is (re-find #"(?s)_logseq_upsert_block\(\).*?-c\[Block content" output))
+      (is (re-find #"(?s)_logseq_list_task\(\).*?-c\[Filter by task title content\]" output)))
+    (testing ":alias emits grouping without --no- for global flags"
+      (is (re-find #"\(-h --help\)" output)))))
+
+(deftest test-zsh-command-specific-values
+  (let [output (gen/generate-completions "zsh" full-table)]
+    (testing "--pos under upsert block offers correct values"
+      (is (re-find #"--pos=.*\(first-child last-child sibling\)" output)))))
+
+(deftest test-search-content-option-in-completions
+  (let [zsh-output (gen/generate-completions "zsh" full-table)
+        bash-output (gen/generate-completions "bash" full-table)]
+    (testing "zsh completion includes --content under search subcommands"
+      (is (re-find #"(?s)_logseq_search_block\(\).*--content" zsh-output))
+      (is (re-find #"(?s)_logseq_search_page\(\).*--content" zsh-output))
+      (is (re-find #"(?s)_logseq_search_property\(\).*--content" zsh-output))
+      (is (re-find #"(?s)_logseq_search_tag\(\).*--content" zsh-output)))
+    (testing "bash completion includes --content under search subcommands"
+      (is (string/includes? bash-output "search)"))
+      (is (string/includes? bash-output "--content -c")))))
+
+(deftest test-zsh-no-prefix-for-command-booleans
+  (let [output (gen/generate-completions "zsh" full-table)]
+    (testing "--no-include-built-in is offered for list tag"
+      (is (string/includes? output "--no-include-built-in")))
+    (testing "--no-with-type is offered for list property"
+      (is (string/includes? output "--no-with-type")))
+    (testing "--no- tokens have Negate description"
+      (is (string/includes? output "--no-include-built-in[Negate --include-built-in]")))
+    (testing "--no- and positive form are mutually exclusive"
+      (is (string/includes? output "(--include-built-in --no-include-built-in)")))
+    (testing "explicit no-* options do not produce --no-no-* artifacts"
+      (is (not (string/includes? output "--no-no-status")))
+      (is (not (string/includes? output "--no-no-priority")))
+      (is (not (string/includes? output "--no-no-scheduled")))
+      (is (not (string/includes? output "--no-no-deadline"))))))
+
+(deftest test-bash-no-prefix-for-command-booleans
+  (let [output (gen/generate-completions "bash" full-table)]
+    (testing "--no-include-built-in appears in bash wordlist"
+      (is (string/includes? output "--no-include-built-in")))
+    (testing "--no-with-type appears in bash wordlist"
+      (is (string/includes? output "--no-with-type")))
+    (testing "explicit no-* options do not produce --no-no-* artifacts"
+      (is (not (string/includes? output "--no-no-status")))
+      (is (not (string/includes? output "--no-no-priority")))
+      (is (not (string/includes? output "--no-no-scheduled")))
+      (is (not (string/includes? output "--no-no-deadline"))))))
+
+(deftest test-zsh-multi-value-completion
+  (let [output (gen/generate-completions "zsh" full-table)]
+    (testing "zsh preamble contains _logseq_multi_values helper"
+      (is (string/includes? output "_logseq_multi_values()")))
+    (testing "--fields under list tag uses {_logseq_multi_values ...} action"
+      (is (re-find #"--fields=.*\{_logseq_multi_values " output)))
+    (testing "multi-values include known tag field names"
+      (is (string/includes? output "created-at"))
+      (is (string/includes? output "title"))
+      (is (string/includes? output "uuid")))))
+
+(deftest test-bash-multi-value-completion
+  (let [output (gen/generate-completions "bash" full-table)]
+    (testing "bash preamble contains _logseq_multi_values_bash helper"
+      (is (string/includes? output "_logseq_multi_values_bash()")))
+    (testing "--fields case calls _logseq_multi_values_bash for list tag context"
+      (is (string/includes? output "_logseq_multi_values_bash \"$cur\" created-at")))))
+
+(deftest test-values-with-whitespace
+  (testing "zsh enum action escapes whitespace inside parenthesized list"
+    (let [token {:key :status :type :enum :desc "Filter status"
+                 :values ["backlog" "in review" "todo"]}
+          [spec] (gen/zsh-token-for token #{})]
+      (is (string/includes? spec "(backlog in\\ review todo)"))))
+  (testing "zsh multi action quotes whitespace values for shell call"
+    (let [token {:key :tags :type :multi :desc "Tags"
+                 :values ["alpha" "two words" "beta"]}
+          [spec] (gen/zsh-token-for token #{})]
+      (is (string/includes? spec "{_logseq_multi_values alpha \"two words\" beta}"))))
+  (testing "bash enum branch with whitespace uses _logseq_enum_values_bash helper"
+    (let [token {:key :status :type :enum :desc "Filter status"
+                 :values ["backlog" "in review" "todo"]}
+          branch (gen/bash-prev-completion-case token)]
+      (is (string/includes? branch "_logseq_enum_values_bash \"$cur\" backlog 'in review' todo"))
+      (is (not (string/includes? branch "compgen -W")))))
+  (testing "bash enum branch without whitespace keeps compgen -W form"
+    (let [token {:key :order :type :enum :desc "Order"
+                 :values ["asc" "desc"]}
+          branch (gen/bash-prev-completion-case token)]
+      (is (string/includes? branch "compgen -W 'asc desc'"))
+      (is (not (string/includes? branch "_logseq_enum_values_bash")))))
+  (testing "bash multi branch with whitespace single-quotes affected values"
+    (let [token {:key :fields :type :multi :desc "Fields"
+                 :values ["alpha" "two words" "beta"]}
+          branch (gen/bash-prev-completion-case token)]
+      (is (string/includes? branch "_logseq_multi_values_bash \"$cur\" alpha 'two words' beta"))))
+  (testing "single quote in a whitespace value is escaped via the standard '\\'' idiom"
+    (let [token {:key :tags :type :enum :desc "Tags"
+                 :values ["it's a test"]}
+          branch (gen/bash-prev-completion-case token)]
+      (is (string/includes? branch "'it'\\''s a test'"))))
+  (testing "bash preamble defines _logseq_enum_values_bash helper"
+    (let [output (gen/generate-completions "bash" full-table)]
+      (is (string/includes? output "_logseq_enum_values_bash()")))))
+
+(deftest test-zsh-all-commands-present
+  (let [output (gen/generate-completions "zsh" full-table)]
+    (testing "every command from the table appears"
+      (doseq [entry full-table]
+        (let [func-name (str "_logseq_" (string/join "_" (:cmds entry)))]
+          (is (string/includes? output (str func-name "()"))))))))
+
+;; ---------------------------------------------------------------------------
+;; Phase 4 — Bash output
+;; ---------------------------------------------------------------------------
+
+(deftest test-generate-bash-structure
+  (let [output (gen/generate-completions "bash" full-table)]
+    (testing "output contains dynamic helpers"
+      (is (string/includes? output "_logseq_graphs_bash"))
+      (is (string/includes? output "_logseq_pages_bash"))
+      (is (string/includes? output "_logseq_queries_bash"))
+      (is (string/includes? output "_logseq_compadd_lines"))
+      (is (string/includes? output "_logseq_json_names_bash"))
+      (is (string/includes? output "_logseq_current_graph_bash")))
+    (testing "bash page completion reads namespaced block/title key"
+      (is (string/includes? output "_logseq_json_names_bash data items block/title")))
+    (testing "output contains _logseq_opts_for"
+      (is (string/includes? output "_logseq_opts_for()")))
+    (testing "output contains _logseq_is_value_opt"
+      (is (string/includes? output "_logseq_is_value_opt()")))
+    (testing "output ends with complete -F _logseq logseq"
+      (is (string/includes? output "complete -F _logseq logseq")))
+    (testing "graph export case includes --type and --file"
+      (is (string/includes? output "--type"))
+      (is (string/includes? output "--file")))
+    (testing "graph backup options include --name, --src, and --dst"
+      (is (string/includes? output "--name"))
+      (is (string/includes? output "--src"))
+      (is (string/includes? output "--dst")))
+    (testing "skill subcommands include show/install and --global"
+      (is (string/includes? output "skill"))
+      (is (string/includes? output "show"))
+      (is (string/includes? output "install"))
+      (is (string/includes? output "--global")))
+    (testing "boolean flags appear in wordlist"
+      (is (string/includes? output "--verbose"))
+      (is (string/includes? output "--profile")))
+    (testing "global boolean flags do NOT have --no- variants in wordlist"
+      (is (not (string/includes? output "--no-verbose")))
+      (is (not (string/includes? output "--no-help")))
+      (is (not (string/includes? output "--no-profile"))))
+    (testing "enum values use compgen -W"
+      (is (re-find #"compgen -W.*edn human json" output)))
+    (testing ":complete :file uses compgen -f"
+      (is (re-find #"compgen -f" output)))))
+
+(deftest test-bash-all-commands-present
+  (let [output (gen/generate-completions "bash" full-table)]
+    (testing "every top-level command appears in subcommand completion"
+      (doseq [group-name (distinct (map #(first (:cmds %)) full-table))]
+        (is (string/includes? output group-name)
+            (str "missing command: " group-name))))))
+
+;; ---------------------------------------------------------------------------
+;; Phase 5 — Completion command entry
+;; ---------------------------------------------------------------------------
+
+(deftest test-completion-command-entry
+  (let [entries completion-command/entries]
+    (testing "contains one entry with :cmds [\"completion\"]"
+      (is (= 1 (count entries)))
+      (is (= ["completion"] (:cmds (first entries)))))
+    (testing "command is :completion"
+      (is (= :completion (:command (first entries)))))
+    (testing "spec has :shell with :validate set"
+      (is (= #{"zsh" "bash"}
+             (get-in (first entries) [:spec :shell :validate]))))))
+
+;; ---------------------------------------------------------------------------
+;; Phase 6 — End-to-end validation
+;; ---------------------------------------------------------------------------
+
+(deftest test-e2e-zsh-structural-markers
+  (let [output (gen/generate-completions "zsh" full-table)]
+    (testing "key structural markers present"
+      (is (string/includes? output "#compdef"))
+      (is (string/includes? output "_logseq_graph_export"))
+      (is (string/includes? output "_logseq_show"))
+      (is (string/includes? output "compdef _logseq logseq")))))
+
+(deftest test-e2e-bash-structural-markers
+  (let [output (gen/generate-completions "bash" full-table)]
+    (testing "key structural markers present"
+      (is (string/includes? output "complete -F _logseq logseq"))
+      (is (string/includes? output "_logseq_opts_for")))))
+
+(deftest test-e2e-sync-adding-command
+  (testing "adding a command updates output"
+    (let [base-output (gen/generate-completions "zsh" full-table)
+          fake-entry (core/command-entry ["fake"] :fake "Fake command"
+                                         {:foo {:desc "Foo option"}})
+          extended-table (conj full-table fake-entry)
+          new-output (gen/generate-completions "zsh" extended-table)]
+      (is (not (string/includes? base-output "_logseq_fake()")))
+      (is (string/includes? new-output "_logseq_fake()")))))
+
+(deftest test-e2e-context-dependent-name
+  (let [entries full-table]
+    (testing "query spec has :name with :complete :queries"
+      (let [query-entry (first (filter #(= :query (:command %)) entries))]
+        (is (= :queries (get-in query-entry [:spec :name :complete])))))
+    (testing "remove page spec has :page with :complete :pages"
+      (let [rm-page (first (filter #(= :remove-page (:command %)) entries))]
+        (is (= :pages (get-in rm-page [:spec :page :complete])))
+        (is (nil? (get-in rm-page [:spec :name])))))
+    (testing "upsert tag spec has :complete :tags on :name"
+      (let [tag (first (filter #(= :upsert-tag (:command %)) entries))]
+        (is (= :tags (get-in tag [:spec :name :complete])))))
+    (testing "remove tag spec has :complete :tags on :name"
+      (let [tag (first (filter #(= :remove-tag (:command %)) entries))]
+        (is (= :tags (get-in tag [:spec :name :complete])))))
+    (testing "upsert property spec has :complete :properties on :name"
+      (let [prop (first (filter #(= :upsert-property (:command %)) entries))]
+        (is (= :properties (get-in prop [:spec :name :complete])))))
+    (testing "remove property spec has :complete :properties on :name"
+      (let [prop (first (filter #(= :remove-property (:command %)) entries))]
+        (is (= :properties (get-in prop [:spec :name :complete])))))))
+
+(deftest test-bash-context-dependent-type
+  (let [output (gen/generate-completions "bash" full-table)]
+    (testing "--type completes with edn/sqlite under graph export context"
+      (is (string/includes? output "--type)"))
+      (is (string/includes? output "graph' && \"$__subcmd\" == 'export'"))
+      (is (string/includes? output "compgen -W 'edn sqlite'")))
+    (testing "--type completes with property types under upsert property context"
+      (is (string/includes? output "upsert' && \"$__subcmd\" == 'property'"))
+      (is (string/includes? output "compgen -W '"))
+      (is (string/includes? output "default"))
+      (is (string/includes? output "node")))
+
+    (testing "--type does NOT have a context-free case (simple COMPREPLY after --type)"
+      ;; --type should be in context-dependent if-blocks, not a simple case
+      (let [type-section (second (string/split output #"--type\)"))]
+        (is (string/starts-with? (string/trim type-section) "if"))))))
+
+(deftest test-bash-find-varied-option-keys
+  (let [global-spec (-> full-table first :spec
+                        (select-keys [:help :version :config :graph :root-dir
+                                      :timeout-ms :output :verbose :profile]))
+        global-keys (set (keys global-spec))
+        varied (gen/find-varied-option-keys full-table global-keys)]
+    (testing "--type is detected as varied"
+      (is (contains? varied :type)))
+    (testing "--name is detected as varied"
+      (is (contains? varied :name)))
+    (testing "uniform options like --pos are not varied"
+      (is (not (contains? varied :pos))))
+    (testing "uniform options like --cardinality are not varied"
+      (is (not (contains? varied :cardinality))))))
+
+(deftest test-zsh-nested-subcommand-completion
+  (let [output (gen/generate-completions "zsh" full-table)]
+    (testing "zsh generates subgroup dispatcher for graph backup"
+      (is (string/includes? output "_logseq_graph_backup()"))
+      (is (re-find #"(?s)_logseq_graph_backup\(\).*?'list:" output)
+          "graph backup dispatcher lists 'list' subcommand")
+      (is (re-find #"(?s)_logseq_graph_backup\(\).*?'create:" output)
+          "graph backup dispatcher lists 'create' subcommand")
+      (is (re-find #"(?s)_logseq_graph_backup\(\).*?'restore:" output)
+          "graph backup dispatcher lists 'restore' subcommand")
+      (is (re-find #"(?s)_logseq_graph_backup\(\).*?'remove:" output)
+          "graph backup dispatcher lists 'remove' subcommand"))
+    (testing "graph dispatcher dispatches backup to subgroup function"
+      (is (re-find #"(?s)_logseq_graph\(\).*?backup\) _logseq_graph_backup" output)))
+    (testing "graph backup remove leaf has its own function with --src option"
+      (is (string/includes? output "_logseq_graph_backup_remove()"))
+      (is (re-find #"(?s)_logseq_graph_backup\(\).*?remove\) _logseq_graph_backup_remove" output)))))
+
+(deftest test-bash-nested-subcommand-completion
+  (let [output (gen/generate-completions "bash" full-table)]
+    (testing "bash subcmd completion for graph includes backup (deduplicated)"
+      (is (re-find #"graph\) COMPREPLY=.*backup" output))
+      ;; backup should appear only once, not repeated per sub-subcommand
+      (let [graph-case (re-find #"graph\) COMPREPLY=\( \$\(compgen -W '([^']*)'" output)
+            subcmds (when graph-case (string/split (second graph-case) #" "))]
+        (is (= (count (filter #(= "backup" %) subcmds)) 1)
+            "backup appears exactly once in graph subcmd list")))
+    (testing "bash sub-subcommand dispatch for graph:backup"
+      (is (string/includes? output "graph:backup)")))
+    (testing "bash sub-subcommand completions for graph backup include list, create, restore, remove"
+      (let [case-match (re-find #"graph:backup\) COMPREPLY=\( \$\(compgen -W '([^']*)'" output)]
+        (is (some? case-match) "graph:backup case exists")
+        (when case-match
+          (let [sub-subcmds (set (string/split (second case-match) #" "))]
+            (is (contains? sub-subcmds "list"))
+            (is (contains? sub-subcmds "create"))
+            (is (contains? sub-subcmds "restore"))
+            (is (contains? sub-subcmds "remove"))))))))
+
+(deftest test-e2e-generated-header
+  (testing "zsh output includes do-not-edit header"
+    (let [output (gen/generate-completions "zsh" full-table)]
+      (is (string/includes? output "do not edit manually"))))
+  (testing "bash output includes do-not-edit header"
+    (let [output (gen/generate-completions "bash" full-table)]
+      (is (string/includes? output "do not edit manually")))))
diff --git a/src/test/logseq/cli/config_test.cljs b/src/test/logseq/cli/config_test.cljs
new file mode 100644
index 0000000000..c2a9c78590
--- /dev/null
+++ b/src/test/logseq/cli/config_test.cljs
@@ -0,0 +1,212 @@
+(ns logseq.cli.config-test
+  (:require [cljs.reader :as reader]
+            [cljs.test :refer [deftest is testing]]
+            [frontend.test.node-helper :as node-helper]
+            [goog.object :as gobj]
+            [logseq.cli.config :as config]
+            ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]))
+
+(defn- with-env
+  [env f]
+  (let [original (js/Object.assign #js {} (.-env js/process))]
+    (doseq [[k v] env]
+      (if (some? v)
+        (gobj/set (.-env js/process) k v)
+        (gobj/remove (.-env js/process) k)))
+    (try
+      (f)
+      (finally
+        (set! (.-env js/process) original)))))
+
+(deftest test-config-precedence
+  (let [dir (node-helper/create-tmp-dir)
+        cfg-path (node-path/join dir "cli.edn")
+        _ (fs/writeFileSync cfg-path
+                            (str "{:graph \"file-repo\" "
+                                 ":root-dir \"file-root\" "
+                                 ":timeout-ms 111 "
+                                 ":login-timeout-ms 444 "
+                                 ":logout-timeout-ms 555 "
+                                 ":output-format :edn "
+                                 ":auth-token \"file-secret\" "
+                                 ":e2ee-password \"legacy-password\"}"))
+        env {"LOGSEQ_CLI_GRAPH" "env-repo"
+             "LOGSEQ_CLI_ROOT_DIR" "env-root"
+             "LOGSEQ_CLI_TIMEOUT_MS" "222"
+             "LOGSEQ_CLI_LOGIN_TIMEOUT_MS" "666"
+             "LOGSEQ_CLI_LOGOUT_TIMEOUT_MS" "777"
+             "LOGSEQ_CLI_OUTPUT" "json"}
+        opts {:config-path cfg-path
+              :graph "cli-repo"
+              :root-dir "cli-root"
+              :timeout-ms 333
+              :login-timeout-ms 888
+              :logout-timeout-ms 999
+              :output-format :human}
+        result (with-env env #(config/resolve-config opts))]
+    (is (= cfg-path (:config-path result)))
+    (is (= "cli-repo" (:graph result)))
+    (is (= (node-path/resolve "cli-root") (:root-dir result)))
+    (is (= 333 (:timeout-ms result)))
+    (is (= 888 (:login-timeout-ms result)))
+    (is (= 999 (:logout-timeout-ms result)))
+    (is (nil? (:auth-token result)))
+    (is (nil? (:retries result)))
+    (is (nil? (:e2ee-password result)))
+    (is (= :human (:output-format result)))))
+
+(deftest test-env-overrides-file
+  (let [dir (node-helper/create-tmp-dir)
+        cfg-path (node-path/join dir "cli.edn")
+        _ (fs/writeFileSync cfg-path "{:graph \"file-repo\" :root-dir \"file-root\"}")
+        env {"LOGSEQ_CLI_GRAPH" "env-repo"
+             "LOGSEQ_CLI_ROOT_DIR" "env-root"}
+        result (with-env env #(config/resolve-config {:config-path cfg-path}))]
+    (is (= "env-repo" (:graph result)))
+    (is (= (node-path/resolve "env-root") (:root-dir result)))))
+
+(deftest test-output-format-env-overrides-file
+  (let [dir (node-helper/create-tmp-dir)
+        cfg-path (node-path/join dir "cli.edn")
+        _ (fs/writeFileSync cfg-path "{:output-format :edn}")
+        env {"LOGSEQ_CLI_OUTPUT" "json"}
+        result (with-env env #(config/resolve-config {:config-path cfg-path}))]
+    (is (= :json (:output-format result)))))
+
+(deftest test-output-format-precedence
+  (let [dir (node-helper/create-tmp-dir)
+        cfg-path (node-path/join dir "cli.edn")
+        _ (fs/writeFileSync cfg-path "{:output-format :edn}")
+        env {"LOGSEQ_CLI_OUTPUT" "json"}
+        result (with-env env #(config/resolve-config {:config-path cfg-path
+                                                      :output "human"}))]
+    (is (= :human (:output-format result)))))
+
+(deftest test-output-format-overrides-output
+  (let [result (config/resolve-config {:output-format :edn
+                                       :output "json"})]
+    (is (= :edn (:output-format result)))))
+
+(deftest test-output-format-invalid-values-fallback
+  (let [dir (node-helper/create-tmp-dir)
+        cfg-path (node-path/join dir "cli.edn")
+        _ (fs/writeFileSync cfg-path "{:output-format :edn}")
+        env {"LOGSEQ_CLI_OUTPUT" "yaml"}
+        result (with-env env #(config/resolve-config {:config-path cfg-path
+                                                      :output "xml"}))]
+    (is (= :edn (:output-format result)))))
+
+(deftest test-default-paths
+  (let [dir (node-helper/create-tmp-dir)
+        cfg-path (node-path/join dir "missing-cli.edn")
+        result (with-env {"LOGSEQ_CLI_GRAPH" nil
+                          "LOGSEQ_CLI_ROOT_DIR" nil
+                          "LOGSEQ_CLI_TIMEOUT_MS" nil
+                          "LOGSEQ_CLI_LOGIN_TIMEOUT_MS" nil
+                          "LOGSEQ_CLI_LOGOUT_TIMEOUT_MS" nil
+                          "LOGSEQ_CLI_OUTPUT" nil
+                          "LOGSEQ_CLI_CONFIG" nil}
+                 #(config/resolve-config {:config-path cfg-path}))]
+    (is (= cfg-path (:config-path result)))
+    (is (= (node-path/join (.homedir os) "logseq") (:root-dir result)))
+    (is (= "wss://api.logseq.io/sync/%s" (:ws-url result)))
+    (is (= "https://api.logseq.io" (:http-base result)))
+    (is (= 10000 (:timeout-ms result)))
+    (is (= 300000 (:login-timeout-ms result)))
+    (is (= 120000 (:logout-timeout-ms result)))
+    (is (= 40 (:list-title-max-display-width result)))))
+
+(deftest test-default-config-path-follows-root-dir
+  (let [result (with-env {"LOGSEQ_CLI_GRAPH" nil
+                          "LOGSEQ_CLI_ROOT_DIR" nil
+                          "LOGSEQ_CLI_TIMEOUT_MS" nil
+                          "LOGSEQ_CLI_LOGIN_TIMEOUT_MS" nil
+                          "LOGSEQ_CLI_LOGOUT_TIMEOUT_MS" nil
+                          "LOGSEQ_CLI_OUTPUT" nil
+                          "LOGSEQ_CLI_CONFIG" nil}
+                 #(config/resolve-config {:root-dir "~/custom-logseq"}))]
+    (is (= (node-path/join (.homedir os) "custom-logseq") (:root-dir result)))
+    (is (= (node-path/join (.homedir os) "custom-logseq" "cli.edn")
+           (:config-path result)))))
+
+(deftest test-explicit-config-path-does-not-change-root-dir-derived-defaults
+  (let [dir (node-helper/create-tmp-dir "cli-config-dir")
+        cfg-path (node-path/join dir "nested" "custom-cli.edn")
+        result (config/resolve-config {:config-path cfg-path
+                                       :root-dir "~/custom-logseq"})]
+    (is (= cfg-path (:config-path result)))
+    (is (= (node-path/join (.homedir os) "custom-logseq") (:root-dir result)))))
+
+(deftest test-server-list-path-follows-root-dir
+  (let [root-dir (node-path/join (node-helper/create-tmp-dir "cli-root") "nested-root")
+        expected (node-path/join root-dir "server-list")]
+    (is (= expected (config/server-list-path root-dir)))))
+
+(deftest test-server-list-path-defaults-under-default-root-dir
+  (let [expected (node-path/join (.homedir os) "logseq" "server-list")]
+    (is (= expected (config/server-list-path nil)))))
+
+(deftest test-list-title-max-display-width-config
+  (testing "reads valid list-title-max-display-width from cli.edn"
+    (let [dir (node-helper/create-tmp-dir)
+          cfg-path (node-path/join dir "cli.edn")
+          _ (fs/writeFileSync cfg-path "{:list-title-max-display-width 72}")
+          result (config/resolve-config {:config-path cfg-path})]
+      (is (= 72 (:list-title-max-display-width result)))))
+
+  (testing "falls back to default when cli.edn value is invalid"
+    (doseq [[label file-value]
+            [["zero" "0"]
+             ["negative" "-3"]
+             ["non-numeric" "\"abc\""]]]
+      (let [dir (node-helper/create-tmp-dir)
+            cfg-path (node-path/join dir "cli.edn")
+            _ (fs/writeFileSync cfg-path (str "{:list-title-max-display-width " file-value "}"))
+            result (config/resolve-config {:config-path cfg-path})]
+        (is (= 40 (:list-title-max-display-width result)) label)))))
+
+(deftest test-update-config
+  (let [dir (node-helper/create-tmp-dir "cli")
+        cfg-path (node-path/join dir "cli.edn")
+        _ (fs/writeFileSync cfg-path "{:graph \"old\"}")
+        _ (config/update-config! {:config-path cfg-path} {:graph "new"})
+        contents (.toString (fs/readFileSync cfg-path) "utf8")
+        parsed (reader/read-string contents)]
+    (is (= "new" (:graph parsed)))))
+
+(deftest test-update-config-strips-removed-options
+  (let [dir (node-helper/create-tmp-dir "cli")
+        cfg-path (node-path/join dir "cli.edn")
+        _ (fs/writeFileSync cfg-path "{:graph \"old\" :auth-token \"legacy-secret\" :e2ee-password \"legacy-password\"}")
+        _ (config/update-config! {:config-path cfg-path}
+                                 {:graph "new"
+                                  :auth-token "secret"
+                                  :retries 2
+                                  :e2ee-password "new-password"})
+        contents (.toString (fs/readFileSync cfg-path) "utf8")
+        parsed (reader/read-string contents)]
+    (is (= "new" (:graph parsed)))
+    (is (not (contains? parsed :auth-token)))
+    (is (not (contains? parsed :retries)))
+    (is (not (contains? parsed :e2ee-password)))))
+
+(deftest test-update-config-removes-nil-values
+  (let [dir (node-helper/create-tmp-dir "cli")
+        cfg-path (node-path/join dir "cli.edn")
+        _ (fs/writeFileSync cfg-path "{:graph \"old\" :auth-token \"secret\"}")
+        _ (config/update-config! {:config-path cfg-path}
+                                 {:auth-token nil})
+        contents (.toString (fs/readFileSync cfg-path) "utf8")
+        parsed (reader/read-string contents)]
+    (is (= "old" (:graph parsed)))
+    (is (not (contains? parsed :auth-token)))))
+
+(deftest test-update-config-expands-tilde-in-root-dir
+  (let [dir (node-helper/create-tmp-dir "cli-tilde")
+        cfg-path (node-path/join dir "cli.edn")
+        _ (config/update-config! {:root-dir dir} {:ws-url "wss://example.com"})
+        contents (.toString (fs/readFileSync cfg-path) "utf8")
+        parsed (reader/read-string contents)]
+    (is (= "wss://example.com" (:ws-url parsed)))))
diff --git a/src/test/logseq/cli/format_test.cljs b/src/test/logseq/cli/format_test.cljs
new file mode 100644
index 0000000000..20c9580d93
--- /dev/null
+++ b/src/test/logseq/cli/format_test.cljs
@@ -0,0 +1,1396 @@
+(ns logseq.cli.format-test
+  (:require [cljs.reader :as reader]
+            [cljs.test :refer [deftest is testing]]
+            [clojure.string :as string]
+            [logseq.cli.command.show :as show-command]
+            [logseq.cli.format :as format]
+            [logseq.cli.style :as style]
+            ["string-width" :default string-width]))
+
+(deftest test-format-success
+  (testing "json output via output-format"
+    (let [result (format/format-result {:status :ok :data {:message "ok"}}
+                                       {:output-format :json})]
+      (is (= "{\"status\":\"ok\",\"data\":{\"message\":\"ok\"}}" result))))
+
+  (testing "edn output via output-format"
+    (let [result (format/format-result {:status :ok :data {:message "ok"}}
+                                       {:output-format :edn})]
+      (is (= "{:status :ok, :data {:message \"ok\"}}" result))))
+
+  (testing "human output (default)"
+    (let [result (format/format-result {:status :ok :data {:message "ok"}}
+                                       {:output-format nil})]
+      (is (= "ok" result)))))
+
+(deftest test-format-ignores-legacy-json-flag
+  (testing "json? flag does not override output-format"
+    (let [result (format/format-result {:status :ok :data {:message "ok"}}
+                                       {:output-format nil
+                                        :json? true})]
+      (is (= "ok" result)))))
+
+(deftest test-format-example-output
+  (let [base-result {:status :ok
+                     :command :example
+                     :data {:selector "upsert"
+                            :matched-commands ["upsert block" "upsert page"]
+                            :examples ["logseq upsert block --graph my-graph --content \"hello\""
+                                       "logseq upsert page --graph my-graph --page Home"]
+                            :message "Found 2 examples for selector upsert"}}
+        human-result (format/format-result base-result {:output-format nil})
+        json-result (format/format-result base-result {:output-format :json})
+        edn-result (format/format-result base-result {:output-format :edn})
+        parsed-json (js->clj (js/JSON.parse json-result) :keywordize-keys true)
+        parsed-edn (reader/read-string edn-result)]
+    (testing "human output includes selector, matched commands and examples"
+      (is (string/includes? human-result "Selector: upsert"))
+      (is (string/includes? human-result "Matched commands:"))
+      (is (string/includes? human-result "upsert block"))
+      (is (string/includes? human-result "Examples:"))
+      (is (string/includes? human-result "logseq upsert page --graph my-graph --page Home")))
+
+    (testing "json output keeps required structured fields"
+      (is (= "upsert" (get-in parsed-json [:data :selector])))
+      (is (= ["upsert block" "upsert page"] (get-in parsed-json [:data :matched-commands])))
+      (is (= "Found 2 examples for selector upsert" (get-in parsed-json [:data :message]))))
+
+    (testing "edn output keeps required structured fields"
+      (is (= "upsert" (get-in parsed-edn [:data :selector])))
+      (is (= ["upsert block" "upsert page"] (get-in parsed-edn [:data :matched-commands])))
+      (is (= "Found 2 examples for selector upsert" (get-in parsed-edn [:data :message]))))))
+
+(deftest test-format-error
+  (testing "json error via output-format"
+    (let [result (format/format-result {:status :error :error {:code :boom :message "nope"}}
+                                       {:output-format :json})]
+      (is (= "{\"status\":\"error\",\"error\":{\"code\":\"boom\",\"message\":\"nope\"}}" result))))
+
+  (testing "edn error via output-format"
+    (let [result (format/format-result {:status :error :error {:code :boom :message "nope"}}
+                                       {:output-format :edn})]
+      (is (= "{:status :error, :error {:code :boom, :message \"nope\"}}" result))))
+
+  (testing "human error (default)"
+    (let [result (format/format-result {:status :error :error {:code :boom :message "nope"}}
+                                       {:output-format nil})]
+      (is (= "Error (boom): nope" result))))
+
+  (testing "human error with hint from context"
+    (let [result (format/format-result {:status :error
+                                        :error {:code :missing-auth
+                                                :message "missing auth"
+                                                :context {:code :missing-auth
+                                                          :hint "Run `logseq login` first."}}}
+                                       {:output-format nil})]
+      (is (= "Error (missing-auth): missing auth\nHint: Run `logseq login` first." result))))
+
+  (testing "human error with hint directly on error map"
+    (let [result (format/format-result {:status :error
+                                        :error {:code :e2ee-password-not-found
+                                                :message "e2ee-password not found"
+                                                :hint "Provide --e2ee-password to verify and persist it."}}
+                                       {:output-format nil})]
+      (is (= "Error (e2ee-password-not-found): e2ee-password not found\nHint: Provide --e2ee-password to verify and persist it." result)))))
+
+(deftest test-format-graph-validation
+  (testing "graph validation success prints validated"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-validate
+                                        :context {:graph "foo"}
+                                        :data {:result {:errors nil}}}
+                                       {:output-format nil})]
+      (is (= "Validated graph \"foo\"" result))))
+  (testing "graph validation error prints validation details without extra prefix"
+    (let [result (format/format-result {:status :error
+                                        :command :graph-validate
+                                        :error {:code :graph-validation-failed
+                                                :message "Found 1 entity with errors:\n({:entity {:db/id 1}})\n"}}
+                                       {:output-format nil})]
+      (is (= "Found 1 entity with errors:\n({:entity {:db/id 1}})\n" result)))))
+
+(deftest test-human-output-graph-list
+  (testing "graph list without current graph shows plain list"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-list
+                                        :data {:graphs ["alpha" "beta"]}}
+                                       {:output-format nil})]
+      (is (= (str "alpha\n"
+                  "beta\n"
+                  "Count: 2")
+             result))))
+
+  (testing "graph list with current graph marks it with * and indents others"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-list
+                                        :data {:graphs ["alpha" "beta" "gamma"]}}
+                                       {:output-format nil
+                                        :graph "beta"})]
+      (is (= (str "  alpha\n"
+                  "* beta\n"
+                  "  gamma\n"
+                  "Count: 3")
+             result))))
+
+  (testing "graph list marks legacy entries and prints rename guidance"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-list
+                                        :data {:graphs ["alpha" "legacy/name" "mystery"]
+                                               :graph-items [{:kind :canonical
+                                                              :graph-name "alpha"
+                                                              :graph-dir "alpha"}
+                                                             {:kind :legacy
+                                                              :legacy-dir "legacy++name"
+                                                              :legacy-graph-name "legacy/name"
+                                                              :target-graph-dir "legacy~2Fname"
+                                                              :conflict? false}
+                                                             {:kind :legacy-undecodable
+                                                              :legacy-dir "mystery"
+                                                              :reason :undecodable}]}}
+                                       {:output-format nil
+                                        :graph "legacy/name"
+                                        :graphs-dir "/tmp/graphs"})]
+      (is (string/includes? result "* legacy/name [legacy]"))
+      (is (string/includes? result "mystery [legacy]"))
+      (is (string/includes? result "Warning: 2 legacy graph directories detected."))
+      (is (string/includes? result "mv '/tmp/graphs/legacy++name' '/tmp/graphs/legacy~2Fname'"))
+      (is (string/includes? result "Warning: cannot derive graph name for legacy dir 'mystery'; rename command is not available."))))
+
+  (testing "graph list rename suggestion targets canonical dir with literal spaces"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-list
+                                        :data {:graphs ["space name"]
+                                               :graph-items [{:kind :legacy
+                                                              :legacy-dir "space~20name"
+                                                              :legacy-graph-name "space name"
+                                                              :target-graph-dir "space name"
+                                                              :conflict? false}]}}
+                                       {:output-format nil
+                                        :graphs-dir "/tmp/graphs"})]
+      (is (string/includes? result "mv '/tmp/graphs/space~20name' '/tmp/graphs/space name'"))))
+
+  (testing "graph list conflict warning does not print mv command"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-list
+                                        :data {:graphs ["legacy/name"]
+                                               :graph-items [{:kind :legacy
+                                                              :legacy-dir "legacy++name"
+                                                              :legacy-graph-name "legacy/name"
+                                                              :target-graph-dir "legacy~2Fname"
+                                                              :conflict? true}]}}
+                                       {:output-format nil
+                                        :graphs-dir "/tmp/graphs"})]
+      (is (string/includes? result "Warning: target directory already exists for legacy graph 'legacy/name'."))
+      (is (not (string/includes? result "mv '/tmp/graphs/legacy++name' '/tmp/graphs/legacy~2Fname'")))))
+
+  (testing "graph list rename command uses POSIX single-quote escaping"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-list
+                                        :data {:graphs ["weird'name"]
+                                               :graph-items [{:kind :legacy
+                                                              :legacy-dir "weird'++name"
+                                                              :legacy-graph-name "weird'/name"
+                                                              :target-graph-dir "weird~27~2Fname"
+                                                              :conflict? false}]}}
+                                       {:output-format nil
+                                        :graphs-dir "/tmp/graphs"})]
+      (is (string/includes? result "mv '/tmp/graphs/weird'\"'\"'++name' '/tmp/graphs/weird~27~2Fname'"))))
+
+  )
+
+(deftest test-human-output-graph-list-count-grouping
+  (let [graphs (mapv #(str "graph-" %) (range 1234))
+        result (format/format-result {:status :ok
+                                      :command :graph-list
+                                      :data {:graphs graphs}}
+                                     {:output-format nil})]
+    (is (string/includes? result "Count: 1,234"))))
+
+(deftest test-human-output-graph-list-legacy-warning-singular
+  (let [result (format/format-result {:status :ok
+                                      :command :graph-list
+                                      :data {:graphs ["legacy/name"]
+                                             :graph-items [{:kind :legacy
+                                                            :legacy-dir "legacy++name"
+                                                            :legacy-graph-name "legacy/name"
+                                                            :target-graph-dir "legacy~2Fname"
+                                                            :conflict? false}]}}
+                                     {:output-format nil
+                                      :graphs-dir "/tmp/graphs"})]
+    (is (string/includes? result "Warning: 1 legacy graph directory detected."))))
+
+(deftest test-human-output-list-page
+  (testing "list page renders a table with count"
+    (let [result (format/format-result {:status :ok
+                                        :command :list-page
+                                        :data {:items [{:db/id 1
+                                                        :title "Alpha"
+                                                        :updated-at 90000
+                                                        :created-at 40000}]}}
+                                       {:output-format nil
+                                        :now-ms 100000})]
+      (is (= (str "ID  TITLE  UPDATED-AT      CREATED-AT\n"
+                  "1   Alpha  10 seconds ago  1 minute ago\n"
+                  "Count: 1")
+             result)))))
+
+(deftest test-human-output-list-tag-property
+  (testing "list tag uses ID column from :db/id"
+    (let [result (format/format-result {:status :ok
+                                        :command :list-tag
+                                        :data {:items [{:block/title "Tag"
+                                                        :db/id 42
+                                                        :block/created-at 40000
+                                                        :block/updated-at 90000
+                                                        :db/ident :logseq.class/Tag}]}}
+                                       {:output-format nil
+                                        :now-ms 100000})]
+      (is (= (str "ID  TITLE  IDENT              UPDATED-AT      CREATED-AT\n"
+                  "42  Tag    :logseq.class/Tag  10 seconds ago  1 minute ago\n"
+                  "Count: 1")
+             result))))
+
+  (testing "list property uses ID column from :db/id"
+    (let [result (format/format-result {:status :ok
+                                        :command :list-property
+                                        :data {:items [{:block/title "Prop"
+                                                        :db/id 99
+                                                        :logseq.property/type :node
+                                                        :db/cardinality :db.cardinality/many
+                                                        :block/created-at 40000
+                                                        :block/updated-at 90000}]}}
+                                       {:output-format nil
+                                        :now-ms 100000})]
+      (is (= (str "ID  TITLE  TYPE  CARDINALITY  UPDATED-AT      CREATED-AT\n"
+                  "99  Prop   node  many         10 seconds ago  1 minute ago\n"
+                  "Count: 1")
+             result))))
+
+  (testing "list property renders missing type as - and missing cardinality as one"
+    (let [result (format/format-result {:status :ok
+                                        :command :list-property
+                                        :data {:items [{:block/title "Prop"
+                                                        :db/id 99
+                                                        :logseq.property/type :node
+                                                        :db/cardinality :db.cardinality/many
+                                                        :block/created-at 40000
+                                                        :block/updated-at 90000}
+                                                       {:block/title "Untyped"
+                                                        :db/id 100
+                                                        :block/created-at 40000
+                                                        :block/updated-at 90000}]}}
+                                       {:output-format nil
+                                        :now-ms 100000})]
+      (is (= (str "ID   TITLE    TYPE  CARDINALITY  UPDATED-AT      CREATED-AT\n"
+                  "99   Prop     node  many         10 seconds ago  1 minute ago\n"
+                  "100  Untyped  -     one          10 seconds ago  1 minute ago\n"
+                  "Count: 2")
+             result)))))
+
+(deftest test-human-output-list-task
+  (let [result (format/format-result {:status :ok
+                                      :command :list-task
+                                      :data {:items [{:db/id 12
+                                                      :block/title "Alpha task"
+                                                      :logseq.property/status :logseq.property/status.todo
+                                                      :logseq.property/priority :logseq.property/priority.high
+                                                      :logseq.property/scheduled "2026-02-10T08:00:00.000Z"
+                                                      :logseq.property/deadline "2026-02-12T18:00:00.000Z"
+                                                      :block/created-at 40000
+                                                      :block/updated-at 90000}]}}
+                                     {:output-format nil
+                                      :now-ms 100000})]
+    (is (string/includes? result "STATUS"))
+    (is (string/includes? result "PRIORITY"))
+    (is (string/includes? result "SCHEDULED"))
+    (is (string/includes? result "DEADLINE"))
+    (is (string/includes? result "Alpha task"))
+    (is (string/includes? result "Count: 1")))
+
+  (testing "list task renders epoch-ms scheduled/deadline with humanized relative datetime"
+    (let [now-ms 1000000000
+          scheduled-ms (+ now-ms (* 3 60 60 1000))
+          deadline-ms (- now-ms (* 2 24 60 60 1000))
+          result (format/format-result {:status :ok
+                                        :command :list-task
+                                        :data {:items [{:db/id 226
+                                                        :block/title "q3"
+                                                        :logseq.property/status :logseq.property/status.todo
+                                                        :logseq.property/priority :logseq.property/priority.high
+                                                        :logseq.property/scheduled scheduled-ms
+                                                        :logseq.property/deadline deadline-ms}]}}
+                                       {:output-format nil
+                                        :now-ms now-ms})]
+      (is (string/includes? result "in "))
+      (is (string/includes? result "ago"))
+      (is (not (string/includes? result (str scheduled-ms))))
+      (is (not (string/includes? result (str deadline-ms)))))))
+
+(deftest test-human-output-list-node
+  (let [result (format/format-result {:status :ok
+                                      :command :list-node
+                                      :data {:items [{:db/id 1
+                                                      :block/title "Node Page"
+                                                      :node/type "page"
+                                                      :block/uuid #uuid "11111111-1111-1111-1111-111111111111"
+                                                      :block/created-at 40000
+                                                      :block/updated-at 90000}
+                                                     {:db/id 2
+                                                      :block/title "Node Block"
+                                                      :node/type "block"
+                                                      :block/uuid #uuid "22222222-2222-2222-2222-222222222222"
+                                                      :block/page-id 1
+                                                      :block/page-title "Node Page"
+                                                      :block/created-at 45000
+                                                      :block/updated-at 95000}]}}
+                                     {:output-format nil
+                                      :now-ms 100000})]
+    (is (string/includes? result "TYPE"))
+    (is (string/includes? result "PAGE-ID"))
+    (is (string/includes? result "PAGE-TITLE"))
+    (is (not (string/includes? result "UUID")))
+    (is (not (string/includes? result "11111111-1111-1111-1111-111111111111")))
+    (is (string/includes? result "Node Page"))
+    (is (string/includes? result "Node Block"))
+    (is (string/includes? result "Count: 2"))))
+
+(deftest test-human-output-list-asset
+  (let [result (format/format-result {:status :ok
+                                      :command :list-asset
+                                      :data {:items [{:db/id 3
+                                                      :block/title "Asset Node"
+                                                      :logseq.property.asset/type "md"
+                                                      :logseq.property.asset/size 2552
+                                                      :block/created-at 40000
+                                                      :block/updated-at 90000}]}}
+                                     {:output-format nil
+                                      :now-ms 100000})
+        lines (string/split-lines result)
+        header (first lines)]
+    (is (string/includes? header "ID"))
+    (is (string/includes? header "TITLE"))
+    (is (string/includes? header "ASSET-TYPE"))
+    (is (string/includes? header "SIZE"))
+    (is (string/includes? header "UPDATED-AT"))
+    (is (string/includes? header "CREATED-AT"))
+    (is (string/includes? result "Asset Node"))
+    (is (string/includes? result "md"))
+    (is (not (string/includes? result "2552")))
+    (is (some? (re-find #"\b2(\.\d+)?\s*[KM]i?B\b" result)))
+    (is (not (string/includes? (first lines) " TYPE  ")))
+    (is (not (string/includes? result "PAGE-ID")))
+    (is (not (string/includes? result "PAGE-TITLE")))
+    (is (string/includes? result "Count: 1"))))
+
+(deftest test-human-output-list-title-max-display-width
+  (doseq [[label command item]
+          [["list page truncates title by configured display width"
+            :list-page
+            {:db/id 1
+             :block/title "ABCDEFGH"
+             :block/updated-at 90000
+             :block/created-at 40000}]
+           ["list tag truncates title by configured display width"
+            :list-tag
+            {:db/id 2
+             :block/title "ABCDEFGH"
+             :block/updated-at 90000
+             :block/created-at 40000}]
+           ["list property truncates title by configured display width"
+            :list-property
+            {:db/id 3
+             :block/title "ABCDEFGH"
+             :logseq.property/type :node
+             :db/cardinality :db.cardinality/one
+             :block/updated-at 90000
+             :block/created-at 40000}]
+           ["list task truncates title by configured display width"
+            :list-task
+            {:db/id 4
+             :block/title "ABCDEFGH"
+             :block/updated-at 90000
+             :block/created-at 40000}]
+           ["list node truncates title by configured display width"
+            :list-node
+            {:db/id 5
+             :block/title "ABCDEFGH"
+             :node/type "page"
+             :block/updated-at 90000
+             :block/created-at 40000}]
+           ["list asset truncates title by configured display width"
+            :list-asset
+            {:db/id 6
+             :block/title "ABCDEFGH"
+             :logseq.property.asset/type "png"
+             :logseq.property.asset/size 2048
+             :block/updated-at 90000
+             :block/created-at 40000}]]]
+    (testing label
+      (let [result (format/format-result {:status :ok
+                                          :command command
+                                          :data {:items [item]}}
+                                         {:output-format nil
+                                          :now-ms 100000
+                                          :list-title-max-display-width 6})]
+        (is (string/includes? result "ABCDE…"))
+        (is (not (string/includes? result "ABCDEFGH")))))))
+
+(deftest test-human-output-list-cjk-title-alignment
+  (let [result (format/format-result {:status :ok
+                                      :command :list-page
+                                      :data {:items [{:db/id 1
+                                                      :block/title "ABCD"
+                                                      :block/updated-at 90000
+                                                      :block/created-at 40000}
+                                                     {:db/id 2
+                                                      :block/title "你好"
+                                                      :block/updated-at 90000
+                                                      :block/created-at 40000}]}}
+                                     {:output-format nil
+                                      :now-ms 100000
+                                      :list-title-max-display-width 10})
+        lines (string/split-lines result)
+        line-1 (nth lines 1)
+        line-2 (nth lines 2)
+        updated-at-idx-1 (.indexOf line-1 "10 seconds ago")
+        updated-at-idx-2 (.indexOf line-2 "10 seconds ago")
+        prefix-width-1 (string-width (subs line-1 0 updated-at-idx-1))
+        prefix-width-2 (string-width (subs line-2 0 updated-at-idx-2))]
+    (is (pos? updated-at-idx-1))
+    (is (pos? updated-at-idx-2))
+    (is (= prefix-width-1 prefix-width-2))))
+
+(deftest test-human-output-search
+  (testing "search block renders the list table contract"
+    (let [result (format/format-result {:status :ok
+                                        :command :search-block
+                                        :data {:items [{:db/id 3
+                                                        :block/title "Alpha block"}
+                                                       {:db/id 7
+                                                        :block/title "Second line\nIndented"}]}}
+                                       {:output-format nil})]
+      (is (= (str "ID  TITLE\n"
+                  "3   Alpha block\n"
+                  "7   Second line\n"
+                  "    Indented\n"
+                  "Count: 2")
+             result))))
+
+  (testing "search page includes IDENT column when present"
+    (let [result (format/format-result {:status :ok
+                                        :command :search-page
+                                        :data {:items [{:db/id 9
+                                                        :block/title "Home"
+                                                        :db/ident :logseq.graph/home}]}}
+                                       {:output-format nil})]
+      (is (= (str "ID  TITLE  IDENT\n"
+                  "9   Home   :logseq.graph/home\n"
+                  "Count: 1")
+             result)))))
+
+(deftest test-search-json-edn-output
+  (let [base-result {:status :ok
+                     :command :search-tag
+                     :data {:items [{:db/id 2
+                                     :block/title "Quote"
+                                     :db/ident :logseq.class/Tag}]}}
+        json-result (format/format-result base-result {:output-format :json})
+        edn-result (format/format-result base-result {:output-format :edn})
+        parsed-json (js->clj (js/JSON.parse json-result) :keywordize-keys true)
+        parsed-edn (reader/read-string edn-result)]
+    (is (= "Quote" (get-in parsed-json [:data :items 0 :block/title])))
+    (is (= "logseq.class/Tag" (get-in parsed-json [:data :items 0 :db/ident])))
+    (is (= :logseq.class/Tag (get-in parsed-edn [:data :items 0 :db/ident])))))
+
+(deftest test-list-property-json-edn-cardinality-shape
+  (testing "list property json keeps namespaced db/cardinality while edn stays unchanged"
+    (let [base-result {:status :ok
+                       :command :list-property
+                       :data {:items [{:db/id 99
+                                       :block/title "Prop"
+                                       :logseq.property/type :number
+                                       :db/cardinality :db.cardinality/many}]}}
+          json-result (format/format-result base-result {:output-format :json})
+          edn-result (format/format-result base-result {:output-format :edn})
+          parsed-json (js->clj (js/JSON.parse json-result) :keywordize-keys true)
+          parsed-edn (reader/read-string edn-result)]
+      (is (= "db.cardinality/many" (get-in parsed-json [:data :items 0 :db/cardinality])))
+      (is (nil? (get-in parsed-json [:data :items 0 :cardinality])))
+      (is (= :db.cardinality/many (get-in parsed-edn [:data :items 0 :db/cardinality]))))))
+
+(deftest test-json-output-preserves-namespaced-keys-and-values
+  (let [payload {:status :ok
+                 :data {:item {:block/title "Block title"
+                               :logseq.property/title "Property title"
+                               :db/id 42
+                               :db/ident :logseq.class/Tag
+                               :block/uuid #uuid "2a847b91-1565-49cc-9f9f-0f6ee25ca0f3"}}}
+        json-result (format/format-result payload {:output-format :json})
+        parsed-json (js->clj (js/JSON.parse json-result) :keywordize-keys true)]
+    (is (= "Block title" (get-in parsed-json [:data :item :block/title])))
+    (is (= "Property title" (get-in parsed-json [:data :item :logseq.property/title])))
+    (is (= 42 (get-in parsed-json [:data :item :db/id])))
+    (is (= "logseq.class/Tag" (get-in parsed-json [:data :item :db/ident])))
+    (is (= "2a847b91-1565-49cc-9f9f-0f6ee25ca0f3" (get-in parsed-json [:data :item :block/uuid])))))
+
+(deftest test-human-output-upsert-success-lines
+  (doseq [[label payload expected]
+          [["upsert block renders ids in two lines"
+            {:status :ok
+             :command :upsert-block
+             :context {:repo "demo-repo"
+                       :blocks ["a" "b"]}
+             :data {:result [201 202]}}
+            "Upserted blocks:\n[201 202]"]
+           ["upsert page renders ids in two lines"
+            {:status :ok
+             :command :upsert-page
+             :context {:repo "demo-repo"
+                       :page "Home"}
+             :data {:result [123]}}
+            "Upserted page:\n[123]"]
+           ["upsert tag renders ids in two lines"
+            {:status :ok
+             :command :upsert-tag
+             :context {:repo "demo-repo"
+                       :name "Quote"}
+             :data {:result [321]}}
+            "Upserted tag:\n[321]"]
+           ["upsert property renders ids in two lines"
+            {:status :ok
+             :command :upsert-property
+             :context {:repo "demo-repo"
+                       :name "owner"}
+             :data {:result [654]}}
+            "Upserted property:\n[654]"]
+           ["upsert task renders ids in two lines"
+            {:status :ok
+             :command :upsert-task
+             :context {:repo "demo-repo"
+                       :page "Weekly Plan"}
+             :data {:result [987]}}
+            "Upserted task:\n[987]"]
+           ["upsert asset renders ids in two lines"
+            {:status :ok
+             :command :upsert-asset
+             :context {:repo "demo-repo"}
+             :data {:result [555]}}
+            "Upserted asset:\n[555]"]]]
+    (testing label
+      (let [result (format/format-result payload {:output-format nil})]
+        (is (= expected result))))))
+
+(deftest test-human-output-remove-success-lines
+  (doseq [[label payload expected]
+          [["remove page renders a succinct success line"
+            {:status :ok
+             :command :remove-page
+             :context {:repo "demo-repo"
+                       :page "Home"}
+             :data {:result {:ok true}}}
+            "Removed page: Home (repo: demo-repo)"]
+           ["remove block with id list renders block count"
+            {:status :ok
+             :command :remove-block
+             :context {:repo "demo-repo"
+                       :ids [1 2 3]}
+             :data {:result {:ok true}}}
+            "Removed blocks: 3 (repo: demo-repo)"]
+           ["remove block with large id list uses grouped count"
+            {:status :ok
+             :command :remove-block
+             :context {:repo "demo-repo"
+                       :ids (vec (range 1234))}
+             :data {:result {:ok true}}}
+            "Removed blocks: 1,234 (repo: demo-repo)"]
+           ["remove tag renders a succinct success line"
+            {:status :ok
+             :command :remove-tag
+             :context {:repo "demo-repo"
+                       :name "Quote"}
+             :data {:result {:ok true}}}
+            "Removed tag: Quote (repo: demo-repo)"]
+           ["remove property renders a succinct success line"
+            {:status :ok
+             :command :remove-property
+             :context {:repo "demo-repo"
+                       :name "owner"}
+             :data {:result {:ok true}}}
+            "Removed property: owner (repo: demo-repo)"]]]
+    (testing label
+      (let [result (format/format-result payload {:output-format nil})]
+        (is (= expected result))))))
+
+(deftest test-human-output-upsert-block-update-summary
+  (doseq [[label context expected]
+          [["upsert block update mode renders a succinct success line"
+            {:repo "demo-repo"
+             :source "source-uuid"
+             :target "target-uuid"
+             :update-tags ["TagA"]
+             :update-properties {:logseq.property/publishing-public? true}
+             :remove-tags ["TagB"]
+             :remove-properties [:logseq.property/deadline]}
+            "Upserted block: source-uuid -> target-uuid (repo: demo-repo, tags:+1, properties:+1, remove-tags:+1, remove-properties:+1)"]
+           ["upsert block update uses grouped counts for large changes"
+            {:repo "demo-repo"
+             :source "source-uuid"
+             :update-tags (vec (range 1234))
+             :update-properties (zipmap (map #(keyword (str "prop-" %)) (range 1234)) (repeat true))
+             :remove-tags (vec (range 1234))
+             :remove-properties (mapv #(keyword (str "remove-" %)) (range 1234))}
+            "Upserted block: source-uuid (repo: demo-repo, tags:+1,234, properties:+1,234, remove-tags:+1,234, remove-properties:+1,234)"]
+           ["upsert block update without move target renders a succinct success line"
+            {:repo "demo-repo"
+             :source "source-uuid"
+             :update-tags ["TagA"]}
+            "Upserted block: source-uuid (repo: demo-repo, tags:+1)"]]]
+    (testing label
+      (let [result (format/format-result {:status :ok
+                                          :command :upsert-block
+                                          :context context
+                                          :data {:result {:ok true}}}
+                                         {:output-format nil})]
+        (is (= expected result))))))
+
+(deftest test-human-output-graph-import-export
+  (testing "graph export renders a succinct success line"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-export
+                                        :context {:export-type "edn"
+                                                  :file "/tmp/export.edn"}}
+                                       {:output-format nil})]
+      (is (= "Exported edn to /tmp/export.edn" result))))
+
+  (testing "graph import renders a succinct success line"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-import
+                                        :context {:import-type "sqlite"
+                                                  :input "/tmp/import.sqlite"}
+                                        :data {:message "Imported sqlite from /tmp/import.sqlite"}}
+                                       {:output-format nil})]
+      (is (= "Imported sqlite from /tmp/import.sqlite" result)))))
+
+(deftest test-human-output-graph-backup
+  (testing "graph backup list renders metadata table"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-backup-list
+                                        :data {:backups [{:name "demo-nightly"
+                                                          :created-at 90000
+                                                          :size-bytes 2048}]}}
+                                       {:output-format nil
+                                        :now-ms 100000})]
+      (is (string/includes? result "NAME"))
+      (is (string/includes? result "CREATED-AT"))
+      (is (string/includes? result "SIZE-BYTES"))
+      (is (string/includes? result "demo-nightly"))
+      (is (string/includes? result "10 seconds ago"))
+      (is (string/includes? result "2048"))
+      (is (string/includes? result "Count: 1"))))
+
+  (testing "graph backup create renders a succinct success line"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-backup-create
+                                        :context {:graph "demo"
+                                                  :backup-name "demo-nightly"}}
+                                       {:output-format nil})]
+      (is (= "Created backup: demo-nightly (graph: demo)" result))))
+
+  (testing "graph backup restore renders a succinct success line"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-backup-restore
+                                        :context {:src "demo-nightly"
+                                                  :dst "demo-restored"}}
+                                       {:output-format nil})]
+      (is (= "Restored backup demo-nightly -> demo-restored" result))))
+
+  (testing "graph backup remove renders a succinct success line"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-backup-remove
+                                        :context {:src "demo-nightly"}}
+                                       {:output-format nil})]
+      (is (= "Removed backup: demo-nightly" result)))))
+
+(deftest test-machine-output-graph-backup-list-metadata
+  (let [base-result {:status :ok
+                     :command :graph-backup-list
+                     :data {:backups [{:name "demo-nightly"
+                                       :created-at 90000
+                                       :size-bytes 2048}]}}
+        json-result (format/format-result base-result {:output-format :json})
+        edn-result (format/format-result base-result {:output-format :edn})
+        parsed-json (js->clj (js/JSON.parse json-result) :keywordize-keys true)
+        parsed-edn (reader/read-string edn-result)]
+    (testing "graph backup list json output keeps metadata fields"
+      (is (= "demo-nightly" (get-in parsed-json [:data :backups 0 :name])))
+      (is (= 90000 (get-in parsed-json [:data :backups 0 :created-at])))
+      (is (= 2048 (get-in parsed-json [:data :backups 0 :size-bytes]))))
+
+    (testing "graph backup list edn output keeps metadata fields"
+      (is (= "demo-nightly" (get-in parsed-edn [:data :backups 0 :name])))
+      (is (= 90000 (get-in parsed-edn [:data :backups 0 :created-at])))
+      (is (= 2048 (get-in parsed-edn [:data :backups 0 :size-bytes]))))))
+
+(deftest test-human-output-sync-status
+  (testing "sync status renders runtime and queue fields"
+    (let [result (format/format-result {:status :ok
+                                        :command :sync-status
+                                        :data {:repo "demo-graph"
+                                               :graph-id "graph-uuid"
+                                               :ws-state :open
+                                               :pending-local 2345
+                                               :pending-asset 1234
+                                               :pending-server 9876
+                                               :local-tx 12345
+                                               :remote-tx 67890}}
+                                       {:output-format nil})]
+      (is (string/includes? result "Sync status"))
+      (is (string/includes? result "demo-graph"))
+      (is (string/includes? result "graph-uuid"))
+      (is (string/includes? result "pending-local: 2,345"))
+      (is (string/includes? result "pending-asset: 1,234"))
+      (is (string/includes? result "pending-server: 9,876"))
+      (is (string/includes? result "local-tx: 12,345"))
+      (is (string/includes? result "remote-tx: 67,890"))))
+
+  (testing "sync status renders last error diagnostic when present"
+    (let [result (format/format-result {:status :ok
+                                        :command :sync-status
+                                        :data {:repo "demo-graph"
+                                               :graph-id "graph-uuid"
+                                               :ws-state :open
+                                               :pending-local 2
+                                               :pending-asset 1
+                                               :pending-server 3
+                                               :local-tx 10
+                                               :remote-tx 13
+                                               :last-error {:code :decrypt-aes-key
+                                                            :message "decrypt-aes-key"}}}
+                                       {:output-format nil})]
+      (is (string/includes? result "last-error"))
+      (is (string/includes? result "decrypt-aes-key")))))
+
+(deftest test-human-output-sync-remote-graphs
+  (testing "sync remote-graphs renders a table"
+    (let [result (format/format-result {:status :ok
+                                        :command :sync-remote-graphs
+                                        :data {:graphs [{:graph-id "graph-1"
+                                                         :graph-name "Alpha"
+                                                         :role "manager"
+                                                         :graph-e2ee? true}
+                                                        {:graph-id "graph-2"
+                                                         :graph-name "Beta"
+                                                         :role "member"
+                                                         :graph-e2ee? false}]}}
+                                       {:output-format nil})]
+      (is (string/includes? result "GRAPH-ID"))
+      (is (string/includes? result "GRAPH-NAME"))
+      (is (string/includes? result "ROLE"))
+      (is (string/includes? result "Alpha"))
+      (is (string/includes? result "Beta"))
+      (is (string/includes? result "Count: 2")))))
+
+(deftest test-human-output-sync-actions
+  (testing "sync start renders a succinct success line"
+    (let [result (format/format-result {:status :ok
+                                        :command :sync-start
+                                        :context {:repo "demo-graph"}}
+                                       {:output-format nil})]
+      (is (string/includes? result "Sync started"))
+      (is (string/includes? result "demo-graph"))))
+
+  (testing "sync upload renders a succinct success line"
+    (let [result (format/format-result {:status :ok
+                                        :command :sync-upload
+                                        :context {:repo "demo-graph"}
+                                        :data {:graph-id "graph-uuid"}}
+                                       {:output-format nil})]
+      (is (string/includes? result "Sync upload"))
+      (is (string/includes? result "demo-graph"))))
+
+  (testing "sync download renders a succinct success line"
+    (let [result (format/format-result {:status :ok
+                                        :command :sync-download
+                                        :context {:repo "demo-graph"}}
+                                       {:output-format nil})]
+      (is (string/includes? result "Sync download"))
+      (is (string/includes? result "demo-graph")))))
+
+(deftest test-human-output-sync-config-get-ws-url
+  (testing "sync config get ws-url renders value in human output"
+    (let [value "wss://api.logseq.io/sync/%s"
+          result (format/format-result {:status :ok
+                                        :command :sync-config-get
+                                        :data {:key :ws-url
+                                               :value value}}
+                                       {:output-format nil})]
+      (is (string/includes? result "ws-url"))
+      (is (string/includes? result value)))))
+
+(deftest test-human-output-auth-commands
+  (testing "login human output reports auth path and user metadata without tokens"
+    (let [token "secret-token-value"
+          result (format/format-result {:status :ok
+                                        :command :login
+                                        :data {:auth-path "/tmp/auth.json"
+                                               :email "user@example.com"
+                                               :sub "user-123"
+                                               :authorize-url "https://example.com/oauth2/authorize?..."
+                                               :id-token token}}
+                                       {:output-format nil})]
+      (is (string/includes? result "Login successful"))
+      (is (string/includes? result "user@example.com"))
+      (is (string/includes? result "/tmp/auth.json"))
+      (is (not (string/includes? result token)))))
+
+  (testing "logout human output reports whether auth was removed"
+    (let [result (format/format-result {:status :ok
+                                        :command :logout
+                                        :data {:auth-path "/tmp/auth.json"
+                                               :deleted? true
+                                               :opened? true
+                                               :logout-completed? true}}
+                                       {:output-format nil})]
+      (is (string/includes? result "Logged out"))
+      (is (string/includes? result "/tmp/auth.json"))
+      (is (string/includes? result "Cognito logout: completed"))))
+
+  (testing "logout human output is still successful when auth file is absent"
+    (let [result (format/format-result {:status :ok
+                                        :command :logout
+                                        :data {:auth-path "/tmp/auth.json"
+                                               :deleted? false
+                                               :opened? true
+                                               :logout-completed? true}}
+                                       {:output-format nil})]
+      (is (string/includes? result "Already logged out"))
+      (is (string/includes? result "/tmp/auth.json"))
+      (is (string/includes? result "Cognito logout: completed")))))
+
+(deftest test-human-output-graph-info
+  (testing "graph info includes key metadata lines and kv section"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-info
+                                        :data {:graph "demo-graph"
+                                               :logseq.kv/graph-created-at 40000
+                                               :logseq.kv/schema-version 2
+                                               :kv {"logseq.kv/db-type" :sqlite
+                                                    "logseq.kv/graph-created-at" 40000
+                                                    "logseq.kv/schema-version" 2}}}
+                                       {:output-format nil
+                                        :now-ms 100000})]
+      (is (= (str "Graph: demo-graph\n"
+                  "Created at: 1 minute ago\n"
+                  "Schema version: 2\n"
+                  "KV:\n"
+                  "  logseq.kv/db-type: :sqlite\n"
+                  "  logseq.kv/graph-created-at: 40000\n"
+                  "  logseq.kv/schema-version: 2")
+             result)))))
+
+(deftest test-human-output-graph-info-kv-ordering
+  (testing "graph info kv section is sorted by ident key"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-info
+                                        :data {:graph "demo-graph"
+                                               :kv {"logseq.kv/schema-version" 2
+                                                    "logseq.kv/db-type" :sqlite
+                                                    "logseq.kv/graph-created-at" 40000}}}
+                                       {:output-format nil
+                                        :now-ms 100000})
+          idx-db-type (.indexOf result "logseq.kv/db-type")
+          idx-created (.indexOf result "logseq.kv/graph-created-at")
+          idx-schema (.indexOf result "logseq.kv/schema-version")]
+      (is (>= idx-db-type 0))
+      (is (< idx-db-type idx-created))
+      (is (< idx-created idx-schema)))))
+
+(deftest test-human-output-graph-info-kv-redaction
+  (testing "graph info redacts sensitive kv values in human output"
+    (let [token "secret-token-value"
+          result (format/format-result {:status :ok
+                                        :command :graph-info
+                                        :data {:graph "demo-graph"
+                                               :kv {"logseq.kv/api-token" token
+                                                    "logseq.kv/db-type" :sqlite}}}
+                                       {:output-format nil})]
+      (is (string/includes? result "logseq.kv/api-token"))
+      (is (string/includes? result "[REDACTED]"))
+      (is (not (string/includes? result token))))))
+
+(deftest test-human-output-graph-info-kv-truncates-long-strings
+  (testing "graph info truncates long string kv values in human output"
+    (let [long-text (apply str (repeat 180 "a"))
+          result (format/format-result {:status :ok
+                                        :command :graph-info
+                                        :data {:graph "demo-graph"
+                                               :kv {"logseq.kv/runtime-metadata" long-text}}}
+                                       {:output-format nil})]
+      (is (string/includes? result "... [truncated]"))
+      (is (not (string/includes? result long-text))))))
+
+(deftest test-machine-output-graph-info-kv-structure
+  (testing "graph info json output includes kv map"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-info
+                                        :data {:graph "demo-graph"
+                                               :kv {"logseq.kv/db-type" :sqlite
+                                                    "logseq.kv/schema-version" 2}}}
+                                       {:output-format :json})
+          parsed (js->clj (js/JSON.parse result) :keywordize-keys true)]
+      (is (= "ok" (:status parsed)))
+      (is (= "demo-graph" (get-in parsed [:data :graph])))
+      (is (= "sqlite" (get-in parsed [:data :kv :logseq.kv/db-type])))
+      (is (= 2 (get-in parsed [:data :kv :logseq.kv/schema-version])))))
+
+  (testing "graph info edn output includes kv map"
+    (let [result (format/format-result {:status :ok
+                                        :command :graph-info
+                                        :data {:graph "demo-graph"
+                                               :kv {"logseq.kv/db-type" :sqlite
+                                                    "logseq.kv/schema-version" 2}}}
+                                       {:output-format :edn})
+          parsed (reader/read-string result)]
+      (is (= :ok (:status parsed)))
+      (is (= "demo-graph" (get-in parsed [:data :graph])))
+      (is (= :sqlite (get-in parsed [:data :kv "logseq.kv/db-type"])))
+      (is (= 2 (get-in parsed [:data :kv "logseq.kv/schema-version"]))))))
+
+(deftest test-machine-output-graph-info-kv-redaction
+  (testing "graph info redacts sensitive kv values in json and edn output"
+    (let [token "my-secret-token"
+          json-result (format/format-result {:status :ok
+                                             :command :graph-info
+                                             :data {:graph "demo-graph"
+                                                    :kv {"logseq.kv/api-token" token
+                                                         "logseq.kv/db-type" :sqlite}}}
+                                            {:output-format :json})
+          json-parsed (js->clj (js/JSON.parse json-result) :keywordize-keys true)
+          edn-result (format/format-result {:status :ok
+                                            :command :graph-info
+                                            :data {:graph "demo-graph"
+                                                   :kv {"logseq.kv/api-token" token
+                                                        "logseq.kv/db-type" :sqlite}}}
+                                           {:output-format :edn})
+          edn-parsed (reader/read-string edn-result)]
+      (is (= "[REDACTED]" (get-in json-parsed [:data :kv :logseq.kv/api-token])))
+      (is (= "[REDACTED]" (get-in edn-parsed [:data :kv "logseq.kv/api-token"])))
+      (is (not (string/includes? json-result token)))
+      (is (not (string/includes? edn-result token))))))
+
+(deftest test-human-output-server-cleanup
+  (testing "server cleanup includes counts and failed targets"
+    (let [result (format/format-result {:status :ok
+                                        :command :server-cleanup
+                                        :data {:cli-revision "cli-rev"
+                                               :checked 4321
+                                               :mismatched 3210
+                                               :eligible 2100
+                                               :skipped-owner 1111
+                                               :skipped-owner-targets [{:repo "logseq_db_graph-b"
+                                                                        :pid 22
+                                                                        :owner-source :electron
+                                                                        :revision "worker-rev-b"}]
+                                               :killed (mapv (fn [idx]
+                                                               {:repo (str "logseq_db_graph-killed-" idx)
+                                                                :pid (+ 1000 idx)
+                                                                :owner-source :cli
+                                                                :revision "worker-rev-a"})
+                                                             (range 1234))
+                                               :failed [{:repo "logseq_db_graph-c"
+                                                         :pid 33
+                                                         :owner-source :cli
+                                                         :revision nil
+                                                         :error {:code :server-stop-timeout
+                                                                 :message "timed out stopping server"}}]}}
+                                       {:output-format nil})]
+      (is (string/includes? result "Server cleanup summary"))
+      (is (string/includes? result "CLI revision: cli-rev"))
+      (is (string/includes? result "Checked: 4,321"))
+      (is (string/includes? result "Mismatched: 3,210"))
+      (is (string/includes? result "Eligible (:cli owner): 2,100"))
+      (is (string/includes? result "Skipped owner mismatch: 1,111"))
+      (is (string/includes? result "Killed: 1,234"))
+      (is (string/includes? result "Failed: 1"))
+      (is (string/includes? result "Skipped owner targets:"))
+      (is (string/includes? result "graph-b"))
+      (is (string/includes? result "Failed targets:"))
+      (is (string/includes? result "server-stop-timeout")))))
+
+(deftest test-json-output-normalizes-graph-fields-with-single-leading-strip-only
+  (let [result (format/format-result {:status :ok
+                                      :data {:repo "logseq_db_logseq_db_demo"
+                                             :graph "my_logseq_db_notes"
+                                             :graphs ["logseq_db_logseq_db_demo"
+                                                      "my_logseq_db_notes"]}}
+                                     {:output-format :edn})
+        parsed (reader/read-string result)]
+    (is (= "logseq_db_demo" (get-in parsed [:data :repo])))
+    (is (= "my_logseq_db_notes" (get-in parsed [:data :graph])))
+    (is (= ["logseq_db_demo" "my_logseq_db_notes"]
+           (get-in parsed [:data :graphs])))))
+
+(deftest test-human-output-server-list-includes-owner-and-revision
+  (testing "server list shows owner and revision columns"
+    (let [result (format/format-result {:status :ok
+                                        :command :server-list
+                                        :data {:servers [{:repo "demo-repo"
+                                                          :status :ready
+                                                          :host "127.0.0.1"
+                                                          :port 1234
+                                                          :pid 9876
+                                                          :owner-source :cli
+                                                          :revision "worker-revision"}]}}
+                                       {:output-format nil})]
+      (is (= (str "GRAPH      STATUS  HOST       PORT  PID   OWNER  REVISION\n"
+                  "demo-repo  :ready  127.0.0.1  1234  9876  :cli   worker-revision\n"
+                  "Count: 1")
+             result))))
+
+  (testing "server list falls back to placeholder when owner or revision is missing"
+    (let [result (format/format-result {:status :ok
+                                        :command :server-list
+                                        :data {:servers [{:repo "demo-repo"
+                                                          :status :ready
+                                                          :host "127.0.0.1"
+                                                          :port 1234
+                                                          :pid 9876}]}}
+                                       {:output-format nil})]
+      (is (= (str "GRAPH      STATUS  HOST       PORT  PID   OWNER  REVISION\n"
+                  "demo-repo  :ready  127.0.0.1  1234  9876  -      -\n"
+                  "Count: 1")
+             result))))
+
+  (testing "server list shows revision mismatch warning in human output only"
+    (let [base-result {:status :ok
+                       :command :server-list
+                       :data {:servers [{:repo "demo-repo"
+                                         :status :ready
+                                         :host "127.0.0.1"
+                                         :port 1234
+                                         :pid 9876
+                                         :owner-source :cli
+                                         :revision "server-revision"}]}
+                       :human {:server-list {:revision-mismatch {:cli-revision "cli-revision"
+                                                                 :servers [{:repo "demo-repo"
+                                                                            :revision "server-revision"}]}}}}
+          human-result (format/format-result base-result {:output-format nil})
+          json-result (format/format-result base-result {:output-format :json})
+          json-parsed (js->clj (js/JSON.parse json-result) :keywordize-keys true)]
+      (is (string/includes? human-result "Warning:"))
+      (is (string/includes? human-result "cli-revision"))
+      (is (string/includes? human-result "demo-repo"))
+      (is (= "server-revision" (get-in json-parsed [:data :servers 0 :revision])))
+      (is (not (string/includes? json-result "Warning:"))))))
+
+(deftest test-human-output-show
+  (testing "show renders text payloads directly"
+    (let [result (format/format-result {:status :ok
+                                        :command :show
+                                        :data {:message "Line 1\nLine 2"}}
+                                       {:output-format nil})]
+      (is (= "Line 1\nLine 2" result)))))
+
+(deftest test-human-output-query-results
+  (testing "scalar id collections preserve EDN formatting"
+    (let [result (format/format-result {:status :ok
+                                        :command :query
+                                        :data {:result [1 2 3]}}
+                                       {:output-format nil})]
+      (is (= "[1 2 3]" result))))
+
+  (testing "non-scalar collections preserve EDN formatting"
+    (let [value [{:db/id 1 :block/title "Alpha"}
+                 {:db/id 2 :block/title "Beta"}]
+          result (format/format-result {:status :ok
+                                        :command :query
+                                        :data {:result value}}
+                                       {:output-format nil})]
+      (is (= (pr-str value) result))))
+
+  (testing "mixed scalar collections preserve EDN formatting"
+    (let [value [1 "two" 3]
+          result (format/format-result {:status :ok
+                                        :command :query
+                                        :data {:result value}}
+                                       {:output-format nil})]
+      (is (= (pr-str value) result))))
+
+  (testing "nil results render as nil"
+    (let [result (format/format-result {:status :ok
+                                        :command :query
+                                        :data {:result nil}}
+                                       {:output-format nil})]
+      (is (= "nil" result)))))
+
+(deftest test-human-output-show-styled-prefixes
+  (testing "show preserves styled status and tags in human output"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child"
+                                              :logseq.property/status {:db/ident :logseq.property/status.todo
+                                                                       :block/title "TODO"}
+                                              :block/tags [{:block/title "TagA"}]}]}}
+          styled (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))
+          result (format/format-result {:status :ok
+                                        :command :show
+                                        :data {:message styled}}
+                                       {:output-format nil})
+          styled-todo (binding [style/*color-enabled?* true]
+                        (style/bold (style/yellow "TODO")))
+          styled-tag (binding [style/*color-enabled?* true]
+                       (style/bold "#TagA"))]
+      (is (string/includes? result styled-todo))
+      (is (string/includes? result styled-tag))
+      (is (= (str "1 Root\n"
+                  "2 └── TODO Child #TagA")
+             (style/strip-ansi result))))))
+
+(deftest test-human-output-show-styled-property-keys
+  (testing "show preserves styled property keys in human output"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child"
+                                              :user.property/acceptance-criteria ["One" "Two"]}
+                                             {:db/id 3
+                                              :block/title "Sibling"}]}
+                     :property-titles {:user.property/acceptance-criteria "Acceptance Criteria"}}
+          styled (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))
+          result (format/format-result {:status :ok
+                                        :command :show
+                                        :data {:message styled}}
+                                       {:output-format nil})]
+      (is (re-find #"\u001b\[[0-9;]*mAcceptance Criteria\u001b\[[0-9;]*m" result))
+      (is (not (re-find #"\u001b\[[0-9;]*m- One\u001b\[[0-9;]*m" result)))
+      (is (not (re-find #"\u001b\[[0-9;]*m- Two\u001b\[[0-9;]*m" result)))
+      (is (= (str "1 Root\n"
+                  "2 ├── Child\n"
+                  "  │   Acceptance Criteria:\n"
+                  "  │     - One\n"
+                  "  │     - Two\n"
+                  "3 └── Sibling")
+             (style/strip-ansi result))))))
+
+(deftest test-human-output-show-preserves-styling
+  (testing "show returns styled text without stripping ANSI"
+    (let [tree->text #'show-command/tree->text
+          tree-data {:root {:db/id 1
+                            :block/title "Root"
+                            :block/children [{:db/id 2
+                                              :block/title "Child"}]}}
+          styled (binding [style/*color-enabled?* true]
+                   (tree->text tree-data))
+          result (format/format-result {:status :ok
+                                        :command :show
+                                        :data {:message styled}}
+                                       {:output-format nil})]
+      (is (= styled result))
+      (is (re-find #"\u001b\[[0-9;]*m" result)))))
+
+(deftest test-show-json-edn-output-ignores-styled-message
+  (testing "show json/edn outputs serialize data without ANSI styling"
+    (let [tree-data {:root {:db/id 1
+                            :block/title "Root"}}
+          json-result (format/format-result {:status :ok
+                                             :command :show
+                                             :data tree-data}
+                                            {:output-format :json})
+          edn-result (format/format-result {:status :ok
+                                            :command :show
+                                            :data tree-data}
+                                           {:output-format :edn})]
+      (is (string/includes? json-result "\"root\""))
+      (is (string/includes? edn-result ":root"))
+      (is (not (re-find #"\u001b\[[0-9;]*m" json-result)))
+      (is (not (re-find #"\u001b\[[0-9;]*m" edn-result))))))
+
+(deftest test-human-output-query
+  (testing "query renders raw result"
+    (let [result (format/format-result {:status :ok
+                                        :command :query
+                                        :data {:result [[1] [2] [3]]}}
+                                       {:output-format nil})]
+      (is (= "[[1] [2] [3]]" result)))))
+
+(deftest test-human-output-query-list
+  (testing "query list renders a table with count"
+    (let [result (format/format-result {:status :ok
+                                        :command :query-list
+                                        :data {:queries [{:name "block-search"
+                                                          :inputs ["search-title"]
+                                                          :doc "Find blocks"
+                                                          :source :built-in}]}}
+                                       {:output-format nil})]
+      (is (= (str "NAME          INPUTS        SOURCE    DOC\n"
+                  "block-search  search-title  built-in  Find blocks\n"
+                  "Count: 1")
+             result)))))
+
+(deftest test-human-output-error-formatting
+  (testing "errors include code and hint when available"
+    (let [result (format/format-result {:status :error
+                                        :command :graph-create
+                                        :error {:code :missing-graph
+                                                :message "graph name is required"}}
+                                       {:output-format nil})]
+      (is (= (str "Error (missing-graph): graph name is required\n"
+                  "Hint: Use --graph <name>")
+             result))))
+
+  (testing "missing query text uses per-subcommand --content hint"
+    (doseq [[command hint]
+            [[:search-block "Use: logseq search block --content <query>"]
+             [:search-page "Use: logseq search page --content <query>"]
+             [:search-property "Use: logseq search property --content <query>"]
+             [:search-tag "Use: logseq search tag --content <query>"]]]
+      (let [result (format/format-result {:status :error
+                                          :command command
+                                          :error {:code :missing-query-text
+                                                  :message "query text is required"}}
+                                         {:output-format nil})]
+        (is (= (str "Error (missing-query-text): query text is required\n"
+                    "Hint: " hint)
+               result)))))
+
+  (testing "owner mismatch includes ownership hint"
+    (let [result (format/format-result {:status :error
+                                        :command :server-stop
+                                        :error {:code :server-owned-by-other
+                                                :message "server is owned by another process"}}
+                                       {:output-format nil})]
+      (is (= (str "Error (server-owned-by-other): server is owned by another process\n"
+                  "Hint: Retry from the process owner that started the server")
+             result))))
+
+  (testing "orphan timeout includes recovery hint"
+    (let [result (format/format-result {:status :error
+                                        :command :server-start
+                                        :error {:code :server-start-timeout-orphan
+                                                :message "db-worker-node failed to create lock"}}
+                                       {:output-format nil})]
+      (is (= (str "Error (server-start-timeout-orphan): db-worker-node failed to create lock\n"
+                  "Hint: Check and stop lingering db-worker-node processes, then retry")
+             result))))
+
+  (testing "remove tag ambiguity includes candidate list"
+    (let [result (format/format-result {:status :error
+                                        :command :remove-tag
+                                        :error {:code :ambiguous-tag-name
+                                                :message "multiple tags match name: Quote"
+                                                :candidates [{:id 1 :name "Quote"}
+                                                             {:id 2 :name "QUOTE"}]}}
+                                       {:output-format nil})]
+      (is (string/includes? result "Error (ambiguous-tag-name):"))
+      (is (string/includes? result "multiple tags match name: Quote"))
+      (is (string/includes? result "1"))
+      (is (string/includes? result "2"))
+      (is (string/includes? result "Quote"))
+      (is (string/includes? result "QUOTE")))))
+
+(deftest test-human-output-doctor
+  (testing "doctor renders concise check summary"
+    (let [result (format/format-result {:status :ok
+                                        :command :doctor
+                                        :data {:status :warning
+                                               :checks [{:id :db-worker-script
+                                                         :status :ok
+                                                         :message "Found readable file: /tmp/db-worker-node.js"}
+                                                        {:id :root-dir
+                                                         :status :ok
+                                                         :message "Read/write access confirmed: /tmp/logseq"}
+                                                        {:id :running-servers
+                                                         :status :warning
+                                                         :message "1 server is still starting"}]}}
+                                       {:output-format nil})]
+      (is (= (str "Doctor: warning\n"
+                  "[ok] db-worker-script - Found readable file: /tmp/db-worker-node.js\n"
+                  "[ok] root-dir - Read/write access confirmed: /tmp/logseq\n"
+                  "[warning] running-servers - 1 server is still starting")
+             result))))
+
+  (testing "doctor includes restart guidance for revision mismatch"
+    (let [result (format/format-result {:status :ok
+                                        :command :doctor
+                                        :data {:status :warning
+                                               :checks [{:id :server-revision-mismatch
+                                                         :status :warning
+                                                         :message "2 servers use a different revision than this CLI"
+                                                         :servers [{:graph "graph-a"}
+                                                                   {:graph "team graph"}]}]}}
+                                       {:output-format nil})]
+      (is (= (str "Doctor: warning\n"
+                  "[warning] server-revision-mismatch - 2 servers use a different revision than this CLI\n"
+                  "  Run: logseq server restart --graph graph-a\n"
+                  "  Run: logseq server restart --graph \"team graph\"")
+             result)))))
+
+(deftest test-doctor-json-edn-output
+  (testing "doctor json and edn keep structured checks for failed runs"
+    (let [payload {:checks [{:id :db-worker-script
+                             :status :ok
+                             :message "Found readable file: /tmp/db-worker-node.js"}
+                            {:id :root-dir
+                             :status :error
+                             :code :root-dir-permission
+                             :message "root-dir is not readable/writable: /tmp/logseq"}]}
+          json-result (format/format-result {:status :error
+                                             :command :doctor
+                                             :error {:code :root-dir-permission
+                                                     :message "root-dir check failed"}
+                                             :data payload}
+                                            {:output-format :json})
+          edn-result (format/format-result {:status :error
+                                            :command :doctor
+                                            :error {:code :root-dir-permission
+                                                    :message "root-dir check failed"}
+                                            :data payload}
+                                           {:output-format :edn})
+          parsed-json (js->clj (js/JSON.parse json-result) :keywordize-keys true)
+          parsed-edn (reader/read-string edn-result)]
+      (is (= "error" (:status parsed-json)))
+      (is (= "root-dir-permission" (get-in parsed-json [:error :code])))
+      (is (= "root-dir" (get-in parsed-json [:data :checks 1 :id])))
+      (is (= "error" (get-in parsed-json [:data :checks 1 :status])))
+      (is (= :error (:status parsed-edn)))
+      (is (= :root-dir-permission (get-in parsed-edn [:error :code])))
+      (is (= :root-dir (get-in parsed-edn [:data :checks 1 :id])))
+      (is (= :error (get-in parsed-edn [:data :checks 1 :status]))))))
+
+(deftest test-doctor-json-edn-output-includes-revision-mismatch-check
+  (let [payload {:status :warning
+                 :checks [{:id :server-revision-mismatch
+                           :status :warning
+                           :code :doctor-server-revision-mismatch
+                           :cli-revision "cli-rev"
+                           :servers [{:repo "logseq_db_graph-b"
+                                      :graph "logseq_db_graph-b"
+                                      :revision "worker-rev"}]
+                           :message "1 server uses a different revision than this CLI"}]}
+        json-result (format/format-result {:status :ok
+                                           :command :doctor
+                                           :data payload}
+                                          {:output-format :json})
+        edn-result (format/format-result {:status :ok
+                                          :command :doctor
+                                          :data payload}
+                                         {:output-format :edn})
+        parsed-json (js->clj (js/JSON.parse json-result) :keywordize-keys true)
+        parsed-edn (reader/read-string edn-result)]
+    (is (= "ok" (:status parsed-json)))
+    (is (= "warning" (get-in parsed-json [:data :status])))
+    (is (= "server-revision-mismatch" (get-in parsed-json [:data :checks 0 :id])))
+    (is (= "doctor-server-revision-mismatch" (get-in parsed-json [:data :checks 0 :code])))
+    (is (= "graph-b" (get-in parsed-json [:data :checks 0 :servers 0 :repo])))
+    (is (= "graph-b" (get-in parsed-json [:data :checks 0 :servers 0 :graph])))
+    (is (= :ok (:status parsed-edn)))
+    (is (= :warning (get-in parsed-edn [:data :status])))
+    (is (= :server-revision-mismatch (get-in parsed-edn [:data :checks 0 :id])))
+    (is (= :doctor-server-revision-mismatch (get-in parsed-edn [:data :checks 0 :code])))
+    (is (= "graph-b" (get-in parsed-edn [:data :checks 0 :servers 0 :repo])))
+    (is (= "graph-b" (get-in parsed-edn [:data :checks 0 :servers 0 :graph])))))
diff --git a/src/test/logseq/cli/integration_test.cljs b/src/test/logseq/cli/integration_test.cljs
new file mode 100644
index 0000000000..dfe42f88b0
--- /dev/null
+++ b/src/test/logseq/cli/integration_test.cljs
@@ -0,0 +1,440 @@
+(ns logseq.cli.integration-test
+  (:require ["fs" :as fs]
+            ["path" :as node-path]
+            [cljs.test :refer [deftest is async]]
+            [frontend.test.node-helper :as node-helper]
+            [logseq.cli.auth :as cli-auth]
+            [logseq.cli.main :as cli-main]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.transport :as transport]
+            [promesa.core :as p]))
+
+;; NOTE: Non-sync CLI integration coverage moved to cli-e2e shell tests.
+;; Keep this namespace focused on auth and sync integration coverage only.
+;; See `cli-e2e/spec/non_sync_cases.edn` and run `bb dev:cli-e2e` for non-sync e2e coverage.
+
+(defn- run-cli
+  [args root-dir cfg-path]
+  (let [args (vec args)
+        output-idx (.indexOf args "--output")
+        [args output-args] (if (and (>= output-idx 0)
+                                    (< (inc output-idx) (count args)))
+                             [(vec (concat (subvec args 0 output-idx)
+                                           (subvec args (+ output-idx 2))))
+                              ["--output" (nth args (inc output-idx))]]
+                             [args []])
+        output-args (if (seq output-args)
+                      output-args
+                      ["--output" "json"])
+        global-opts ["--root-dir" root-dir "--config" cfg-path]
+        final-args (vec (concat global-opts output-args args))]
+    (-> (cli-main/run! final-args {:exit? false})
+        (p/then (fn [result]
+                  (let [res (if (map? result)
+                              result
+                              (js->clj result :keywordize-keys true))]
+                    res))))))
+
+(defn- parse-json-output
+  [result]
+  (try
+    (js->clj (js/JSON.parse (:output result)) :keywordize-keys true)
+    (catch :default e
+      (throw (ex-info "json parse failed"
+                      {:output (:output result)}
+                      e)))))
+
+(defn- parse-json-output-safe
+  [result label]
+  (try
+    (parse-json-output result)
+    (catch :default e
+      (throw (ex-info (str "json parse failed: " label)
+                      {:label label
+                       :output (:output result)}
+                      e)))))
+
+(defn- stop-repo!
+  [root-dir cfg-path repo]
+  (p/let [result (run-cli ["server" "stop" "--graph" repo] root-dir cfg-path)]
+    (parse-json-output result)))
+
+(defn- sample-auth
+  ([]
+   (sample-auth {}))
+  ([overrides]
+   (merge {:provider "cognito"
+           :id-token "id-token-1"
+           :access-token "access-token-1"
+           :refresh-token "refresh-token-1"
+           :expires-at (+ (js/Date.now) 3600000)
+           :sub "user-123"
+           :email "user@example.com"
+           :updated-at 1735686000000}
+          overrides)))
+
+(deftest ^:long test-cli-login-integration
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-login-data")
+               cfg-path (node-path/join (node-helper/create-tmp-dir "cli") "cli.edn")
+               auth-path (node-path/join (node-helper/create-tmp-dir "cli-auth") "auth.json")
+               open-calls (atom [])
+               auth-data (sample-auth)]
+           (fs/writeFileSync cfg-path "{:output-format :json}")
+           (let [promise
+                 (p/with-redefs [cli-auth/default-auth-path (fn [] auth-path)
+                                 cli-auth/open-browser! (fn [authorize-url]
+                                                          (swap! open-calls conj authorize-url)
+                                                          (let [parsed (js/URL. authorize-url)
+                                                                redirect-uri (.get (.-searchParams parsed) "redirect_uri")
+                                                                state (.get (.-searchParams parsed) "state")]
+                                                            (-> (js/fetch (str redirect-uri "?code=integration-code&state=" state))
+                                                                (p/then (fn [_]
+                                                                          {:opened? true})))))
+                                 cli-auth/exchange-code-for-auth! (fn [_opts payload]
+                                                                    (is (= "integration-code" (:code payload)))
+                                                                    (p/resolved auth-data))]
+                   (p/let [result (run-cli ["login"] root-dir cfg-path)
+                           payload (parse-json-output-safe result "login")
+                           stored (cli-auth/read-auth-file {:auth-path auth-path})]
+                     (is (= 0 (:exit-code result)))
+                     (is (= "ok" (:status payload)))
+                     (is (= auth-path (get-in payload [:data :auth-path])))
+                     (is (= "user@example.com" (get-in payload [:data :email])))
+                     (is (= 1 (count @open-calls)))
+                     (is (= auth-data stored))
+                     (is (fs/existsSync auth-path))))]
+             (-> promise
+                 (p/catch (fn [e]
+                            (is false (str "unexpected error: " e))))
+                 (p/finally (fn []
+                              (done))))))))
+
+(deftest ^:long test-cli-logout-integration
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-logout-data")
+               cfg-path (node-path/join (node-helper/create-tmp-dir "cli") "cli.edn")
+               auth-path (node-path/join (node-helper/create-tmp-dir "cli-auth") "auth.json")
+               open-calls (atom [])]
+           (fs/writeFileSync cfg-path "{:output-format :json}")
+           (cli-auth/write-auth-file! {:auth-path auth-path} (sample-auth))
+           (let [promise
+                 (p/with-redefs [cli-auth/default-auth-path (fn [] auth-path)
+                                 cli-auth/open-browser! (fn [url]
+                                                          (swap! open-calls conj url)
+                                                          (let [parsed (js/URL. url)
+                                                                logout-uri (.get (.-searchParams parsed) "logout_uri")]
+                                                            (-> (js/fetch logout-uri)
+                                                                (p/then (fn [_]
+                                                                          {:opened? true})))))]
+                   (p/let [result (run-cli ["logout"] root-dir cfg-path)
+                           payload (parse-json-output-safe result "logout")]
+                     (is (= 0 (:exit-code result)))
+                     (is (= "ok" (:status payload)))
+                     (is (= 1 (count @open-calls)))
+                     (is (= auth-path (get-in payload [:data :auth-path])))
+                     (is (= true (get-in payload [:data :deleted?])))
+                     (is (= true (get-in payload [:data :opened?])))
+                     (is (= true (get-in payload [:data :logout-completed?])))
+                     (is (not (fs/existsSync auth-path)))))]
+             (-> promise
+                 (p/catch (fn [e]
+                            (is false (str "unexpected error: " e))))
+                 (p/finally (fn []
+                              (done))))))))
+
+(deftest ^:long test-cli-sync-remote-graphs-refreshes-auth-file-and-injects-runtime-token
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-sync-auth")
+               cfg-path (node-path/join (node-helper/create-tmp-dir "cli") "cli.edn")
+               auth-path (node-path/join (node-helper/create-tmp-dir "cli-auth") "auth.json")
+               invoke-calls (atom [])
+               expired-auth (sample-auth {:id-token "expired-token"
+                                          :access-token "expired-access-token"
+                                          :expires-at 0})
+               refreshed-auth (sample-auth {:id-token "fresh-token"
+                                            :access-token "fresh-access-token"
+                                            :expires-at (+ (js/Date.now) 7200000)
+                                            :updated-at 1735689600000})]
+           (fs/writeFileSync cfg-path "{:output-format :json}")
+           (cli-auth/write-auth-file! {:auth-path auth-path} expired-auth)
+           (let [promise
+                 (p/with-redefs [cli-auth/default-auth-path (fn [] auth-path)
+                                 cli-auth/refresh-auth! (fn [_opts _auth-data]
+                                                          (p/resolved refreshed-auth))
+                                 cli-server/list-graphs (fn [_config]
+                                                          ["demo"])
+                                 cli-server/ensure-server! (fn [config _repo]
+                                                             (p/resolved (assoc config :base-url "http://example")))
+                                 transport/invoke (fn [_ method direct-pass? args]
+                                                    (swap! invoke-calls conj [method direct-pass? args])
+                                                    (case method
+                                                      :thread-api/set-db-sync-config
+                                                      (p/resolved nil)
+                                                      :thread-api/db-sync-list-remote-graphs
+                                                      (p/resolved [])
+                                                      (p/resolved nil)))]
+                   (p/let [result (run-cli ["sync" "remote-graphs"] root-dir cfg-path)
+                           payload (parse-json-output-safe result "sync remote-graphs")
+                           stored (cli-auth/read-auth-file {:auth-path auth-path})]
+                     (is (= 0 (:exit-code result)))
+                     (is (= "ok" (:status payload)))
+                     (is (= :thread-api/sync-app-state (ffirst @invoke-calls)))
+                     (is (= "fresh-token" (get-in (nth @invoke-calls 0) [2 0 :auth/id-token])))
+                     (is (= "fresh-token" (:id-token stored)))
+                     (is (= "fresh-access-token" (:access-token stored)))))]
+             (-> promise
+                 (p/catch (fn [e]
+                            (is false (str "unexpected error: " e))))
+                 (p/finally (fn []
+                              (done))))))))
+
+(deftest ^:long test-cli-sync-download-and-start-readiness-with-mocked-sync
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "db-worker-sync-cli")
+               download-repo "sync-download-graph"
+               start-repo "sync-start-graph"
+               invoke-calls (atom [])
+               status-calls (atom 0)]
+           (-> (p/let [cfg-path (node-path/join (node-helper/create-tmp-dir "cli") "cli.edn")
+                       _ (fs/writeFileSync cfg-path "{:output-format :json}")
+                       create-result (run-cli ["graph" "create" "--graph" start-repo] root-dir cfg-path)
+                       create-payload (parse-json-output-safe create-result "graph create")
+                       _ (is (= 0 (:exit-code create-result)))
+                       _ (is (= "ok" (:status create-payload)))
+                       [download-result start-result]
+                       (p/with-redefs [cli-auth/resolve-auth-token! (fn [_config]
+                                                                      (p/resolved "runtime-token"))
+                                       cli-auth/resolve-auth! (fn [_config]
+                                                                (p/resolved {:id-token "runtime-token"
+                                                                             :refresh-token "refresh-token"}))
+                                       cli-server/ensure-server! (fn [config _repo]
+                                                                   (p/resolved (assoc config :base-url "http://example")))
+                                       transport/invoke (fn [_ method _direct-pass? args]
+                                                          (swap! invoke-calls conj [method args])
+                                                          (case method
+                                                            :thread-api/set-db-sync-config
+                                                            (p/resolved nil)
+
+                                                            :thread-api/db-sync-list-remote-graphs
+                                                            (p/resolved [{:graph-id "remote-graph-id"
+                                                                          :graph-name download-repo
+                                                                          :graph-e2ee? true}])
+
+                                                            :thread-api/verify-and-save-e2ee-password
+                                                            (p/resolved nil)
+
+                                                            :thread-api/db-sync-download-graph-by-id
+                                                            (p/resolved {:repo "logseq_db_sync_integration_graph"
+                                                                         :graph-id "remote-graph-id"
+                                                                         :remote-tx 22
+                                                                         :graph-e2ee? true
+                                                                         :row-count 3})
+
+                                                            :thread-api/db-sync-start
+                                                            (p/resolved nil)
+
+                                                            :thread-api/db-sync-status
+                                                            (let [idx (swap! status-calls inc)]
+                                                              (p/resolved {:repo "logseq_db_sync_integration_graph"
+                                                                           :ws-state (if (= idx 1) :connecting :open)
+                                                                           :pending-local 0
+                                                                           :pending-asset 0
+                                                                           :pending-server 0}))
+
+                                                            :thread-api/q
+                                                            (p/resolved 0)
+
+                                                            (p/resolved nil)))]
+                         (p/let [download-result (run-cli ["--graph" download-repo "sync" "download" "--e2ee-password" "pw"] root-dir cfg-path)
+                                 start-result (run-cli ["--graph" start-repo "sync" "start" "--e2ee-password" "pw"] root-dir cfg-path)]
+                           [download-result start-result]))
+                       download-payload (parse-json-output-safe download-result "sync download")
+                       start-payload (parse-json-output-safe start-result "sync start")]
+                 (is (some #(= :thread-api/db-sync-download-graph-by-id (first %)) @invoke-calls))
+                 (is (some #(= :thread-api/q (first %)) @invoke-calls))
+                 (is (some #(= :thread-api/db-sync-status (first %)) @invoke-calls))
+                 (is (= 0 (:exit-code download-result)))
+                 (is (= "ok" (:status download-payload)))
+                 (is (= "remote-graph-id" (get-in download-payload [:data :graph-id])))
+                 (is (= 22 (get-in download-payload [:data :remote-tx])))
+                 (is (= 0 (:exit-code start-result)))
+                 (is (= "ok" (:status start-payload))
+                     (pr-str start-payload))
+                 (is (contains? #{"open" :open}
+                                (get-in start-payload [:data :ws-state])))
+                 (stop-repo! root-dir cfg-path start-repo)
+                 (done))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))
+                          (done)))))))
+
+(deftest ^:long test-cli-sync-download-missing-e2ee-password-cleans-created-graph-and-allows-retry
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "db-worker-sync-download-cleanup-cli")
+               download-graph "sync-download-cleanup-graph"
+               download-calls (atom 0)
+               invoke-calls (atom [])]
+           (-> (p/let [cfg-path (node-path/join (node-helper/create-tmp-dir "cli") "cli.edn")
+                       _ (fs/writeFileSync cfg-path "{:output-format :json}")
+                       _ (p/with-redefs [cli-auth/resolve-auth! (fn [_config]
+                                                                  (p/resolved {:id-token "runtime-token"
+                                                                               :refresh-token "refresh-token"}))
+                                         transport/invoke (fn [_ method direct-pass? args]
+                                                            (swap! invoke-calls conj [method direct-pass? args])
+                                                            (case method
+                                                              :thread-api/set-db-sync-config
+                                                              (p/resolved nil)
+
+                                                              :thread-api/db-sync-list-remote-graphs
+                                                              (p/resolved [{:graph-id "remote-graph-id"
+                                                                            :graph-name download-graph
+                                                                            :graph-e2ee? true}])
+
+                                                              :thread-api/get-e2ee-password
+                                                              (p/rejected (ex-info "missing-e2ee-password"
+                                                                                   {:code :db-sync/missing-e2ee-password
+                                                                                    :field :e2ee-password
+                                                                                    :reason :missing-persisted-password}))
+
+                                                              :thread-api/verify-and-save-e2ee-password
+                                                              (p/resolved nil)
+
+                                                              :thread-api/q
+                                                              (p/resolved 0)
+
+                                                              :thread-api/db-sync-download-graph-by-id
+                                                              (do
+                                                                (swap! download-calls inc)
+                                                                (p/resolved {:repo download-graph
+                                                                             :graph-id "remote-graph-id"
+                                                                             :remote-tx 22
+                                                                             :graph-e2ee? true}))
+
+                                                              (p/resolved nil)))]
+                           (p/let [failed-result (run-cli ["--graph" download-graph "sync" "download"] root-dir cfg-path)
+                                   failed-payload (parse-json-output-safe failed-result "failed encrypted sync download")
+                                   list-after-fail (run-cli ["graph" "list"] root-dir cfg-path)
+                                   list-payload (parse-json-output-safe list-after-fail "graph list after failed sync download")
+                                   servers-after-fail (run-cli ["server" "list"] root-dir cfg-path)
+                                   servers-payload (parse-json-output-safe servers-after-fail "server list after failed sync download")
+                                   _ (is (= 1 (:exit-code failed-result)))
+                                   _ (is (= "error" (:status failed-payload)))
+                                   _ (is (= "e2ee-password-not-found" (get-in failed-payload [:error :code])))
+                                   _ (is (not (some #(= download-graph %) (get-in list-payload [:data :graphs]))))
+                                   _ (is (not (some #(= download-graph (:repo %)) (get-in servers-payload [:data :servers]))))
+                                   _ (is (= 0 @download-calls))
+                                   retry-result (run-cli ["--graph" download-graph "sync" "download" "--e2ee-password" "pw"] root-dir cfg-path)
+                                   retry-payload (parse-json-output-safe retry-result "retry encrypted sync download")
+                                   _ (is (= 0 (:exit-code retry-result)))
+                                   _ (is (= "ok" (:status retry-payload))
+                                         (pr-str retry-payload))
+                                   _ (is (= "remote-graph-id" (get-in retry-payload [:data :graph-id])))
+                                   _ (is (= 1 @download-calls))]
+                             nil))
+                       _ (stop-repo! root-dir cfg-path download-graph)]
+                 nil)
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (try
+                              (fs/rmSync root-dir #js {:recursive true :force true})
+                              (catch :default _
+                                nil))
+                            (done)))))))
+
+(deftest ^:long test-cli-sync-upload-with-mocked-worker-bootstrap
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "db-worker-sync-upload-cli")
+               upload-repo "sync-upload-graph"
+               invoke-calls (atom [])]
+           (-> (p/let [cfg-path (node-path/join (node-helper/create-tmp-dir "cli") "cli.edn")
+                       _ (fs/writeFileSync cfg-path "{:output-format :json}")
+                       create-result (run-cli ["graph" "create" "--graph" upload-repo] root-dir cfg-path)
+                       create-payload (parse-json-output-safe create-result "graph create")
+                       _ (is (= 0 (:exit-code create-result)))
+                       _ (is (= "ok" (:status create-payload)))
+                       upload-result (p/with-redefs
+                                      [cli-auth/resolve-auth! (fn [_config]
+                                                                (p/resolved {:id-token "runtime-token"}))
+                                       cli-server/ensure-server! (fn [config _repo]
+                                                                   (p/resolved (assoc config :base-url "http://example")))
+                                       transport/invoke (fn [_ method _direct-pass? args]
+                                                          (swap! invoke-calls conj [method args])
+                                                          (case method
+                                                            :thread-api/set-db-sync-config
+                                                            (p/resolved nil)
+
+                                                            :thread-api/db-sync-upload-graph
+                                                            (p/resolved {:graph-id "created-graph-id"})
+
+                                                            (p/resolved nil)))]
+                                      (run-cli ["--graph" upload-repo "sync" "upload"] root-dir cfg-path))
+                       upload-payload (parse-json-output-safe upload-result "sync upload")]
+                 (is (= 0 (:exit-code upload-result)))
+                 (is (= "ok" (:status upload-payload)))
+                 (is (= "created-graph-id" (get-in upload-payload [:data :graph-id])))
+                 (is (= :thread-api/sync-app-state (ffirst @invoke-calls)))
+                 (is (= "runtime-token" (get-in (first @invoke-calls) [1 0 :auth/id-token])))
+                 (is (= [:thread-api/set-db-sync-config [{:ws-url "wss://api.logseq.io/sync/%s"
+                                                          :http-base "https://api.logseq.io"}]]
+                        (second @invoke-calls)))
+                 (is (= [:thread-api/db-sync-upload-graph ["logseq_db_sync-upload-graph"]]
+                        (nth @invoke-calls 2)))
+                 (stop-repo! root-dir cfg-path upload-repo))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest ^:long test-cli-sync-upload-followed-by-graph-info-shows-graph-uuid-test
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "db-worker-sync-upload-info-cli")
+               upload-repo "sync-upload-graph-info"
+               uploaded-graph-id "0f64b4a9-6f31-4f35-a83c-6b16f9ddf1ff"
+               invoke-calls (atom [])]
+           (-> (p/let [cfg-path (node-path/join (node-helper/create-tmp-dir "cli") "cli.edn")
+                       _ (fs/writeFileSync cfg-path "{:output-format :json}")
+                       create-result (run-cli ["graph" "create" "--graph" upload-repo] root-dir cfg-path)
+                       create-payload (parse-json-output-safe create-result "graph create")
+                       _ (is (= 0 (:exit-code create-result)))
+                       _ (is (= "ok" (:status create-payload)))
+                       [upload-result info-result]
+                       (p/with-redefs [cli-auth/resolve-auth! (fn [_config]
+                                                                (p/resolved {:id-token "runtime-token"}))
+                                       cli-server/ensure-server! (fn [config _repo]
+                                                                   (p/resolved (assoc config :base-url "http://example")))
+                                       transport/invoke (fn [_ method _direct-pass? args]
+                                                          (swap! invoke-calls conj [method args])
+                                                          (case method
+                                                            :thread-api/set-db-sync-config
+                                                            (p/resolved nil)
+
+                                                            :thread-api/db-sync-upload-graph
+                                                            (p/resolved {:graph-id uploaded-graph-id})
+
+                                                            :thread-api/q
+                                                            (p/resolved [[:logseq.kv/graph-uuid uploaded-graph-id]
+                                                                         [:logseq.kv/schema-version "65"]])
+
+                                                            (p/resolved nil)))]
+                         (p/let [upload-result (run-cli ["--graph" upload-repo "sync" "upload"] root-dir cfg-path)
+                                 info-result (run-cli ["--graph" upload-repo "graph" "info"] root-dir cfg-path)]
+                           [upload-result info-result]))
+                       upload-payload (parse-json-output-safe upload-result "sync upload")
+                       info-payload (parse-json-output-safe info-result "graph info after upload")
+                       q-call (some (fn [[method args]]
+                                      (when (= :thread-api/q method)
+                                        args))
+                                    @invoke-calls)]
+                 (is (= 0 (:exit-code upload-result)))
+                 (is (= "ok" (:status upload-payload)))
+                 (is (= uploaded-graph-id (get-in upload-payload [:data :graph-id])))
+                 (is (= 0 (:exit-code info-result)))
+                 (is (= "ok" (:status info-payload)))
+                 (is (= uploaded-graph-id
+                        (get-in info-payload [:data :kv :logseq.kv/graph-uuid])))
+                 (is (= "logseq_db_sync-upload-graph-info" (first q-call)))
+                 (stop-repo! root-dir cfg-path upload-repo))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
diff --git a/src/test/logseq/cli/log_test.cljs b/src/test/logseq/cli/log_test.cljs
new file mode 100644
index 0000000000..edfa0d7161
--- /dev/null
+++ b/src/test/logseq/cli/log_test.cljs
@@ -0,0 +1,48 @@
+(ns logseq.cli.log-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [lambdaisland.glogi :as log]
+            [logseq.cli.log :as cli-log]))
+
+(deftest test-truncate-preview
+  (testing "truncates long strings with length metadata"
+    (let [value (apply str (repeat 50 "a"))
+          result (cli-log/truncate-preview value 10)]
+      (is (= 50 (:length result)))
+      (is (= 10 (count (:preview result))))
+      (is (true? (:truncated? result)))))
+
+  (testing "does not truncate short strings"
+    (let [value "short"
+          result (cli-log/truncate-preview value 10)]
+      (is (= 5 (:length result)))
+      (is (= "short" (:preview result)))
+      (is (false? (:truncated? result)))))
+
+  (testing "handles collections"
+    (let [value [1 2 3]
+          result (cli-log/truncate-preview value 100)]
+      (is (= (count "[1 2 3]") (:length result)))
+      (is (= "[1 2 3]" (:preview result)))
+      (is (false? (:truncated? result)))))
+
+  (testing "handles nil"
+    (let [result (cli-log/truncate-preview nil 10)]
+      (is (= 3 (:length result)))
+      (is (= "nil" (:preview result)))
+      (is (false? (:truncated? result))))))
+
+(deftest test-debug-logging-gated-by-verbose
+  (let [records (atom [])
+        handler (fn [record]
+                  (swap! records conj record))]
+    (log/add-handler handler)
+    (cli-log/set-verbose! false)
+    (log/debug :event :cli/verbose-test)
+    (is (empty? @records))
+
+    (cli-log/set-verbose! true)
+    (log/debug :event :cli/verbose-test)
+    (is (= 1 (count @records)))
+
+    (log/remove-handler handler)
+    (cli-log/set-verbose! false)))
diff --git a/src/test/logseq/cli/main_test.cljs b/src/test/logseq/cli/main_test.cljs
new file mode 100644
index 0000000000..3fbb7a3718
--- /dev/null
+++ b/src/test/logseq/cli/main_test.cljs
@@ -0,0 +1,195 @@
+(ns logseq.cli.main-test
+  (:require [cljs.reader :as reader]
+            [cljs.test :refer [async deftest is]]
+            [clojure.string :as string]
+            [logseq.cli.commands :as commands]
+            [logseq.cli.main :as cli-main]
+            [logseq.cli.test-helper :as test-helper]
+            [promesa.core :as p]
+            ["fs" :as fs]
+            ["path" :as node-path]))
+
+(deftest test-version-output
+  (async done
+    (-> (p/let [result (cli-main/run! ["--version"] {:exit? false})]
+          (is (= 0 (:exit-code result)))
+          (is (string/includes? (:output result) "Build time: test-build-time"))
+          (is (string/includes? (:output result) "Revision: test-revision"))
+          (done))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))
+                   (done))))))
+
+(deftest test-help-output-omits-command-list
+  (async done
+    (-> (p/let [result (cli-main/run! ["--help"] {:exit? false})
+                output (:output result)]
+          (is (= 0 (:exit-code result)))
+          (is (not (string/includes? output "Commands: list page"))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))
+                   (done)))
+        (p/finally done))))
+
+(deftest test-help-output-respects-structured-modes
+  (async done
+    (-> (p/let [json-result (cli-main/run! ["--output" "json" "--help"] {:exit? false})
+                edn-result (cli-main/run! ["--output" "edn" "--help"] {:exit? false})
+                json-output (js->clj (js/JSON.parse (:output json-result)) :keywordize-keys true)
+                edn-output (reader/read-string (:output edn-result))]
+          (is (= 0 (:exit-code json-result)))
+          (is (= 0 (:exit-code edn-result)))
+          (is (= "ok" (:status json-output)))
+          (is (= :ok (:status edn-output)))
+          (is (string/includes? (get-in json-output [:data :message]) "Usage: logseq"))
+          (is (string/includes? (get-in edn-output [:data :message]) "Usage: logseq")))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))
+                   (done)))
+        (p/finally done))))
+
+(deftest test-parse-error-output-respects-structured-modes
+  (async done
+    (-> (p/let [json-result (cli-main/run! ["--output" "json" "wat"] {:exit? false})
+                edn-result (cli-main/run! ["--output" "edn" "wat"] {:exit? false})
+                json-output (js->clj (js/JSON.parse (:output json-result)) :keywordize-keys true)
+                edn-output (reader/read-string (:output edn-result))]
+          (is (= 1 (:exit-code json-result)))
+          (is (= 1 (:exit-code edn-result)))
+          (is (= "error" (:status json-output)))
+          (is (= :error (:status edn-output)))
+          (is (some? (get-in json-output [:error :message])))
+          (is (some? (get-in edn-output [:error :message]))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))
+                   (done)))
+        (p/finally done))))
+
+(deftest test-result->exit-code
+  (let [result->exit-code #'cli-main/result->exit-code]
+    (is (= 0 (result->exit-code {:status :ok})))
+    (is (= 1 (result->exit-code {:status :error})))
+    (is (= 7 (result->exit-code {:status :error :exit-code 7})))))
+
+(deftest test-profile-output-enabled-for-version
+  (async done
+    (-> (p/let [result (cli-main/run! ["--profile" "--version"] {:exit? false})
+                profile-lines (:profile-lines result)]
+          (is (= 0 (:exit-code result)))
+          (is (string/includes? (:output result) "Build time: test-build-time"))
+          (is (vector? profile-lines))
+          (is (seq profile-lines))
+          (when (seq profile-lines)
+            (is (re-find #"^\d+ms command=version status=ok$" (first profile-lines))))
+          (is (some #(= "stages" (string/trim %)) profile-lines))
+          (is (some #(string/includes? % "cli.parse-args") profile-lines))
+          (is (some #(string/includes? % "cli.total") profile-lines))
+          (done))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))
+                   (done))))))
+
+(deftest test-profile-output-disabled-by-default
+  (async done
+    (-> (p/let [result (cli-main/run! ["--version"] {:exit? false})]
+          (is (= 0 (:exit-code result)))
+          (is (nil? (:profile-lines result)))
+          (done))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))
+                   (done))))))
+
+(deftest test-run-profile-lines-enabled
+  (async done
+    (-> (p/let [result (cli-main/run! ["--profile" "--help"] {:exit? false})
+                lines (:profile-lines result)]
+          (is (= 0 (:exit-code result)))
+          (is (seq lines))
+          (when (seq lines)
+            (is (re-find #"^\d+ms command=help status=ok$" (first lines))))
+          (is (some #(= "stages" (string/trim %)) lines))
+          (is (some #(string/includes? % "cli.parse-args") lines))
+          (is (some #(string/includes? % "cli.total") lines))
+          (is (not-any? #(string/includes? % "[profile]") lines))
+          (is (not-any? #(string/includes? % "count=") lines))
+          (done))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))
+                   (done))))))
+
+(deftest test-run-profile-lines-disabled
+  (async done
+    (-> (p/let [result (cli-main/run! ["--help"] {:exit? false})]
+          (is (= 0 (:exit-code result)))
+          (is (nil? (:profile-lines result)))
+          (done))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))
+                   (done))))))
+
+(deftest test-main-prints-profile-lines-to-stderr
+  (async done
+    (let [stderr-writes (atom [])
+          stdout-lines (atom [])]
+      (-> (test-helper/with-js-property-override
+           (.-stderr js/process)
+           "write"
+           (fn [text]
+             (swap! stderr-writes conj text)
+             true)
+           (fn []
+             (p/with-redefs [cli-main/run! (fn [_args]
+                                             (p/resolved {:exit-code 0
+                                                          :output "ok-output"
+                                                          :profile-lines ["1ms command=help status=ok"
+                                                                          "    stages"
+                                                                          "1ms └── cli"
+                                                                          "1ms     └── cli.total"]}))
+                             println (fn [& args]
+                                       (swap! stdout-lines conj (string/join " " args)))]
+               (cli-main/main "--profile" "--help"))))
+          (p/then (fn [_]
+                    (let [stderr-text (apply str @stderr-writes)]
+                      (is (= ["ok-output"] @stdout-lines))
+                      (is (string/includes? stderr-text "1ms command=help status=ok"))
+                      (is (string/includes? stderr-text "    stages"))
+                      (is (string/includes? stderr-text "1ms     └── cli.total"))
+                      (done))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))
+                     (done)))))))
+
+(deftest test-build-action-sync-error-produces-clean-output
+  (async done
+         (let [tilde-dir (node-path/join (.cwd js/process) "~")
+               tmp-home (node-path/join (.cwd js/process) "tmp" "cli-main-home")]
+           (when (fs/existsSync tilde-dir)
+             (fs/rmSync tilde-dir #js {:recursive true :force true}))
+           (when (fs/existsSync tmp-home)
+             (fs/rmSync tmp-home #js {:recursive true :force true}))
+           (fs/mkdirSync tmp-home #js {:recursive true})
+           (-> (test-helper/with-js-property-override
+                js/process
+                "env"
+                (doto (js/Object.assign #js {} (.-env js/process))
+                  (aset "HOME" tmp-home)
+                  (js-delete "USERPROFILE"))
+                (fn []
+                  (p/with-redefs [commands/build-action
+                                  (fn [_ _]
+                                    (throw (js/Error. "ENOENT: no such file or directory, open 'blah'")))]
+                    (p/let [result (cli-main/run! ["upsert" "block" "-g" "test" "--blocks-file=blah"])]
+                      (is (= 1 (:exit-code result)))
+                      (is (string/includes? (:output result) "ENOENT"))
+                      (is (string/includes? (:output result) "blah"))
+                      (is (not (string/includes? (:output result) "at "))
+                          "output should not contain a stack trace")
+                      (is (not (fs/existsSync tilde-dir))
+                          "should not create a literal ~/ directory under cwd")))))
+               (p/catch (fn [e] (is false (str "unexpected error: " e))))
+               (p/finally (fn []
+                            (when (fs/existsSync tilde-dir)
+                              (fs/rmSync tilde-dir #js {:recursive true :force true}))
+                            (when (fs/existsSync tmp-home)
+                              (fs/rmSync tmp-home #js {:recursive true :force true}))
+                            (done)))))))
\ No newline at end of file
diff --git a/src/test/logseq/cli/output_mode_test.cljs b/src/test/logseq/cli/output_mode_test.cljs
new file mode 100644
index 0000000000..0b4b281e96
--- /dev/null
+++ b/src/test/logseq/cli/output_mode_test.cljs
@@ -0,0 +1,31 @@
+(ns logseq.cli.output-mode-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [logseq.cli.output-mode :as output-mode]))
+
+(deftest test-allowed-output-modes
+  (is (= #{:human :json :edn} output-mode/allowed-keywords))
+  (is (= #{"human" "json" "edn"} output-mode/allowed-values)))
+
+(deftest test-parse
+  (testing "parses string and keyword output modes"
+    (is (= :human (output-mode/parse "human")))
+    (is (= :json (output-mode/parse " JSON ")))
+    (is (= :edn (output-mode/parse :edn))))
+
+  (testing "returns nil for unknown or blank values"
+    (is (nil? (output-mode/parse "")))
+    (is (nil? (output-mode/parse "  ")))
+    (is (nil? (output-mode/parse "yaml")))
+    (is (nil? (output-mode/parse :yaml)))
+    (is (nil? (output-mode/parse nil)))))
+
+(deftest test-structured-output
+  (is (true? (output-mode/structured? :json)))
+  (is (true? (output-mode/structured? "edn")))
+  (is (false? (output-mode/structured? :human)))
+  (is (false? (output-mode/structured? "yaml"))))
+
+(deftest test-string-value
+  (is (= "json" (output-mode/string-value :json)))
+  (is (= "edn" (output-mode/string-value "EDN")))
+  (is (nil? (output-mode/string-value :yaml))))
diff --git a/src/test/logseq/cli/profile_test.cljs b/src/test/logseq/cli/profile_test.cljs
new file mode 100644
index 0000000000..7086534c29
--- /dev/null
+++ b/src/test/logseq/cli/profile_test.cljs
@@ -0,0 +1,169 @@
+(ns logseq.cli.profile-test
+  (:require [cljs.test :refer [async deftest is testing]]
+            [clojure.string :as string]
+            [logseq.cli.profile :as profile]
+            [promesa.core :as p]))
+
+(deftest test-create-session
+  (testing "disabled profile returns nil session"
+    (is (nil? (profile/create-session false))))
+
+  (testing "enabled profile returns session map"
+    (let [session (profile/create-session true)]
+      (is (map? session))
+      (is (some? (:started-ms session))))))
+
+(deftest test-report-aggregates-repeated-stages
+  (let [session (profile/create-session true)]
+    (profile/time! session "cli.parse-args" (fn [] :ok))
+    (profile/time! session "cli.parse-args" (fn [] :ok))
+    (profile/time! session "cli.build-action" (fn [] :ok))
+    (let [report (profile/report session {:command "graph-list" :status :ok})
+          by-stage (into {} (map (juxt :stage identity) (:stages report)))]
+      (is (number? (:total-ms report)))
+      (is (>= (:total-ms report) 0))
+      (is (= "graph-list" (:command report)))
+      (is (= :ok (:status report)))
+      (is (= 2 (get-in by-stage ["cli.parse-args" :count])))
+      (is (= 1 (get-in by-stage ["cli.build-action" :count])))
+      (is (= 1 (get-in by-stage ["cli.total" :count]))))))
+
+(deftest test-time-records-stage-when-thunk-throws
+  (let [session (profile/create-session true)]
+    (try
+      (profile/time! session "cli.parse-args" (fn []
+                                                 (throw (ex-info "boom" {:code :boom}))))
+      (is false "expected exception")
+      (catch :default _
+        (let [report (profile/report session {:command "graph-list" :status :error})
+              by-stage (into {} (map (juxt :stage identity) (:stages report)))]
+          (is (= 1 (get-in by-stage ["cli.parse-args" :count]))))))))
+
+(deftest test-render-lines-renders-logical-containment-tree
+  (let [lines (profile/render-lines {:command "graph-list"
+                                     :status :ok
+                                     :total-ms 42
+                                     :stages []
+                                     :spans [{:stage "cli.total"
+                                              :elapsed-ms 42
+                                              :started-ms 0
+                                              :ended-ms 42
+                                              :span-id 0}
+                                             {:stage "cli.parse-args"
+                                              :elapsed-ms 2
+                                              :started-ms 1
+                                              :ended-ms 3
+                                              :span-id 1}
+                                             {:stage "cli.execute-action"
+                                              :elapsed-ms 30
+                                              :started-ms 5
+                                              :ended-ms 35
+                                              :span-id 2}
+                                             {:stage "transport.invoke:thread-api/q"
+                                              :elapsed-ms 8
+                                              :started-ms 12
+                                              :ended-ms 20
+                                              :span-id 3}]})]
+    (is (= "42ms command=graph-list status=ok" (first lines)))
+    (is (= "stages" (string/trim (second lines))))
+    (is (some #(= "42ms └── cli.total" %) lines))
+    (is (some #(string/includes? % "├── cli.parse-args") lines))
+    (is (some #(string/includes? % "└── cli.execute-action") lines))
+    (is (some #(string/includes? % "└── transport.invoke:thread-api/q") lines))
+    (is (not-any? #(string/includes? % "[profile]") lines))
+    (is (not-any? #(string/includes? % "count=") lines))
+    (is (not-any? #(string/includes? % "avg=") lines))))
+
+(deftest test-render-lines-uses-containment-not-stage-prefix
+  (let [lines (profile/render-lines {:command "query"
+                                     :status :ok
+                                     :total-ms 20
+                                     :stages []
+                                     :spans [{:stage "outer"
+                                              :elapsed-ms 20
+                                              :started-ms 0
+                                              :ended-ms 20
+                                              :span-id 0}
+                                             {:stage "transport.invoke:thread-api/q"
+                                              :elapsed-ms 10
+                                              :started-ms 5
+                                              :ended-ms 15
+                                              :span-id 1}]})]
+    (is (some #(= "20ms └── outer" %) lines))
+    (is (some #(string/includes? % "└── transport.invoke:thread-api/q") lines))))
+
+(deftest test-render-lines-does-not-merge-identical-stage-calls
+  (let [lines (profile/render-lines {:command "query"
+                                     :status :ok
+                                     :total-ms 30
+                                     :stages []
+                                     :spans [{:stage "outer"
+                                              :elapsed-ms 30
+                                              :started-ms 0
+                                              :ended-ms 30
+                                              :span-id 0}
+                                             {:stage "transport.invoke:thread-api/q"
+                                              :elapsed-ms 5
+                                              :started-ms 5
+                                              :ended-ms 10
+                                              :span-id 1}
+                                             {:stage "transport.invoke:thread-api/q"
+                                              :elapsed-ms 5
+                                              :started-ms 15
+                                              :ended-ms 20
+                                              :span-id 2}]})
+        q-lines (filter #(string/includes? % "transport.invoke:thread-api/q") lines)]
+    (is (= 2 (count q-lines)))
+    (is (= ["5ms      ├── transport.invoke:thread-api/q"
+            "5ms      └── transport.invoke:thread-api/q"]
+           (vec q-lines)))))
+
+(deftest test-render-lines-aligns-tree-column-for-different-durations
+  (let [lines (profile/render-lines {:command "query"
+                                     :status :ok
+                                     :total-ms 120
+                                     :stages []
+                                     :spans [{:stage "outer"
+                                              :elapsed-ms 120
+                                              :started-ms 0
+                                              :ended-ms 120
+                                              :span-id 0}
+                                             {:stage "child.short"
+                                              :elapsed-ms 2
+                                              :started-ms 5
+                                              :ended-ms 7
+                                              :span-id 1}
+                                             {:stage "child.long"
+                                              :elapsed-ms 45
+                                              :started-ms 10
+                                              :ended-ms 55
+                                              :span-id 2}]})
+        short-line (first (filter #(string/includes? % "child.short") lines))
+        long-line (first (filter #(string/includes? % "child.long") lines))]
+    (is (some? short-line))
+    (is (some? long-line))
+    (is (= (string/index-of short-line "├──")
+           (string/index-of long-line "└──")))))
+
+(deftest test-time-records-async-stage
+  (async done
+         (let [session (profile/create-session true)]
+           (-> (profile/time! session "transport.invoke:thread-api/q"
+                             (fn []
+                               (p/delay 5 :ok)))
+               (p/then (fn [result]
+                         (is (= :ok result))
+                         (let [report (profile/report session {:command "query" :status :ok})
+                               by-stage (into {} (map (juxt :stage identity) (:stages report)))]
+                           (is (= 1 (get-in by-stage ["transport.invoke:thread-api/q" :count]))))))
+               (p/then (fn [_]
+                         (let [lines (profile/render-lines (profile/report session {:command "query" :status :ok}))]
+                           (is (seq lines))
+                           (when (seq lines)
+                             (is (re-find #"^\d+ms command=query status=ok$" (first lines))))
+                           (is (some #(= "stages" (string/trim %)) lines))
+                           (is (some #(string/includes? % "transport.invoke:thread-api/q") lines))
+                           (done))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))
+                          (done)))))))
\ No newline at end of file
diff --git a/src/test/logseq/cli/root_dir_test.cljs b/src/test/logseq/cli/root_dir_test.cljs
new file mode 100644
index 0000000000..f7a3b84dee
--- /dev/null
+++ b/src/test/logseq/cli/root_dir_test.cljs
@@ -0,0 +1,55 @@
+(ns logseq.cli.root-dir-test
+  (:require ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]
+            [cljs.test :refer [deftest is testing]]
+            [frontend.test.node-helper :as node-helper]
+            [logseq.cli.root-dir :as root-dir]))
+
+(deftest ensure-root-dir-creates-missing-dir
+  (testing "creates missing directories and returns normalized path"
+    (let [base (node-helper/create-tmp-dir "root-dir")
+          target (node-path/join base "nested" "dir")]
+      (is (not (fs/existsSync target)))
+      (let [resolved (root-dir/ensure-root-dir! target)]
+        (is (fs/existsSync target))
+        (is (.isDirectory (fs/statSync target)))
+        (is (= (node-path/resolve target) resolved))))))
+
+(deftest ensure-root-dir-rejects-file-path
+  (testing "rejects paths that are files"
+    (let [base (node-helper/create-tmp-dir "root-dir-file")
+          target (node-path/join base "file.txt")]
+      (fs/writeFileSync target "x")
+      (try
+        (root-dir/ensure-root-dir! target)
+        (is false "expected root-dir permission error")
+        (catch :default e
+          (let [data (ex-data e)]
+            (is (= :root-dir-permission (:code data)))
+            (is (= (node-path/resolve target) (:path data)))))))))
+
+(deftest ensure-root-dir-rejects-read-only-dir
+  (testing "rejects directories without write permission"
+    (when-not (= "win32" (.-platform js/process))
+      (let [target (node-helper/create-tmp-dir "root-dir-readonly")]
+        (fs/chmodSync target 365)
+        (try
+          (root-dir/ensure-root-dir! target)
+          (is false "expected root-dir permission error")
+          (catch :default e
+            (let [data (ex-data e)]
+              (is (= :root-dir-permission (:code data)))
+              (is (= (node-path/resolve target) (:path data))))))))))
+
+(deftest normalize-root-dir-default
+  (testing "defaults to ~/logseq"
+    (let [expected (node-path/resolve (node-path/join (.homedir os) "logseq"))
+          resolved (root-dir/normalize-root-dir nil)]
+      (is (= expected resolved)))))
+
+(deftest graphs-dir-derived-from-root-dir
+  (testing "graphs dir is derived as <root-dir>/graphs"
+    (let [root-dir-path (node-path/join (.homedir os) "custom-logseq")]
+      (is (= (node-path/resolve root-dir-path "graphs")
+             (root-dir/graphs-dir root-dir-path))))))
diff --git a/src/test/logseq/cli/server_test.cljs b/src/test/logseq/cli/server_test.cljs
new file mode 100644
index 0000000000..a2e877125c
--- /dev/null
+++ b/src/test/logseq/cli/server_test.cljs
@@ -0,0 +1,784 @@
+(ns logseq.cli.server-test
+  {:clj-kondo/config '{:linters {:private-var-access {:level :off}}}}
+  (:require ["child_process" :as child-process]
+            ["fs" :as fs]
+            ["http" :as http]
+            ["path" :as node-path]
+            [cljs.test :refer [async deftest is]]
+            [frontend.test.node-helper :as node-helper]
+            [logseq.cli.config :as cli-config]
+            [logseq.cli.profile :as profile]
+            [logseq.cli.server :as cli-server]
+            [logseq.cli.test-helper :as test-helper]
+            [logseq.db-worker.daemon :as daemon]
+            [promesa.core :as p]))
+
+(deftest spawn-server-omits-host-and-port-flags
+  (let [spawn-server! #'cli-server/spawn-server!
+        captured (atom nil)
+        original-cwd (.cwd js/process)]
+    (try
+      (.chdir js/process "/")
+      (-> (test-helper/with-js-property-override
+            child-process
+            "spawn"
+            (fn [cmd args opts]
+              (reset! captured {:cmd cmd
+                                :args (vec (js->clj args))
+                                :opts (js->clj opts :keywordize-keys true)})
+              (js-obj "unref" (fn [] nil)))
+            (fn []
+              (spawn-server! {:repo "logseq_db_spawn_test"
+                              :root-dir "/tmp/logseq-root"})
+              (p/resolved true)))
+          (p/then (fn [_]
+                    (is (= (.-execPath js/process)
+                           (:cmd @captured)))
+                    (is (= (cli-server/db-worker-script-path)
+                           (first (:args @captured))))
+                    (is (some #{"--repo"} (:args @captured)))
+                    (is (some #{"--root-dir"} (:args @captured)))
+                    (is (not-any? #{"--host" "--port"} (:args @captured)))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e)))))
+      (finally
+        (.chdir js/process original-cwd)))))
+
+(deftest lock-path-uses-canonical-graph-dir
+  (let [root-dir "/tmp/logseq-root"
+        repo "logseq_db_demo"
+        expected (node-path/join root-dir "graphs" "demo" "db-worker.lock")]
+    (is (= expected (cli-server/lock-path root-dir repo)))))
+
+(deftest lock-path-encodes-special-characters-in-graph-dir
+  (let [root-dir "/tmp/logseq-root"
+        repo "logseq_db_foo/bar"
+        expected (node-path/join root-dir "graphs" "foo~2Fbar" "db-worker.lock")]
+    (is (= expected (cli-server/lock-path root-dir repo)))))
+
+(deftest db-worker-runtime-script-path-matches-runtime-selection
+  (is (= (cli-server/db-worker-script-path)
+         (cli-server/db-worker-runtime-script-path))))
+
+(deftest cli-server-spawn-server-does-not-forward-server-list-file
+  (async done
+         (let [spawn-server! #'cli-server/spawn-server!
+               captured (atom nil)]
+           (-> (p/with-redefs [daemon/spawn-server! (fn [opts]
+                                                      (reset! captured opts)
+                                                      nil)]
+                 (p/resolved
+                  (spawn-server! {:repo "logseq_db_spawn_test"
+                                  :root-dir "/tmp/logseq-root"
+                                  :owner-source :cli
+                                  :server-list-file "/tmp/server-list"
+                                  :create-empty-db? true})))
+               (p/then (fn [_]
+                         (is (= "logseq_db_spawn_test" (:repo @captured)))
+                         (is (= "/tmp/logseq-root" (:root-dir @captured)))
+                         (is (= true (:create-empty-db? @captured)))
+                         (is (nil? (:server-list-file @captured)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest ensure-server-repairs-stale-lock
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server")
+               repo (str "logseq_db_stale_" (subs (str (random-uuid)) 0 8))
+               path (cli-server/lock-path root-dir repo)
+               cleanup-stale-lock! #'cli-server/cleanup-stale-lock!
+               lock {:repo repo
+                     :pid (.-pid js/process)
+                     :host "127.0.0.1"
+                     :port 0
+                     :startedAt (.toISOString (js/Date.))}]
+           (fs/mkdirSync (node-path/dirname path) #js {:recursive true})
+           (fs/writeFileSync path (js/JSON.stringify (clj->js lock)))
+           (-> (p/let [_ (cleanup-stale-lock! path lock)]
+                 (is (not (fs/existsSync path)))
+                 (done))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))
+                          (done)))))))
+
+(deftest ensure-server-reuses-existing-running-daemon-lock
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-reuse")
+               repo (str "logseq_db_reuse_" (subs (str (random-uuid)) 0 8))
+               lock-file (cli-server/lock-path root-dir repo)
+               config-path (node-path/join root-dir "cli.edn")
+               server-list-file (cli-config/server-list-path root-dir)
+               host "127.0.0.1"
+               port* (atom nil)
+               spawn-calls (atom 0)
+               server (http/createServer
+                       (fn [^js req ^js res]
+                         (case (.-url req)
+                           "/healthz" (do (.writeHead res 200 #js {"Content-Type" "application/json"})
+                                          (.end res (js/JSON.stringify #js {:repo repo
+                                                                            :status "ready"
+                                                                            :host host
+                                                                            :port @port*
+                                                                            :pid (.-pid js/process)
+                                                                            :owner-source "cli"
+                                                                            :revision "server-revision"})))
+                           (do (.writeHead res 404 #js {"Content-Type" "text/plain"})
+                               (.end res "not-found")))))]
+           (.listen server 0 host
+                    (fn []
+                      (let [address (.address server)
+                            port (if (number? address) address (.-port address))
+                            _ (reset! port* port)
+                            lock {:repo repo
+                                  :pid (.-pid js/process)
+                                  :lock-id "reuse-lock"
+                                  :owner-source :cli}]
+                        (fs/mkdirSync (node-path/dirname lock-file) #js {:recursive true})
+                        (fs/writeFileSync lock-file (js/JSON.stringify (clj->js lock)))
+                        (fs/writeFileSync server-list-file (str (.-pid js/process) " " port "\n"))
+                        (-> (p/with-redefs [daemon/spawn-server! (fn [_opts]
+                                                                   (swap! spawn-calls inc)
+                                                                   (throw (ex-info "should not spawn when server-list entry is ready" {})))]
+                              (cli-server/ensure-server! {:root-dir root-dir
+                                                          :config-path config-path}
+                                                         repo))
+                            (p/then (fn [config]
+                                      (is (= (str "http://" host ":" port) (:base-url config)))
+                                      (is (= 0 @spawn-calls))))
+                            (p/catch (fn [e]
+                                       (is false (str "unexpected error: " e))))
+                            (p/finally (fn []
+                                         (.close server (fn [] (done))))))))))))
+
+(deftest start-server-reports-repo-locked-error-stably
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-repo-locked")
+               repo (str "logseq_db_locked_" (subs (str (random-uuid)) 0 8))
+               lock-file (cli-server/lock-path root-dir repo)
+               lock {:repo repo
+                     :pid 999999
+                     :host "127.0.0.1"
+                     :port 55555}]
+           (fs/mkdirSync (node-path/dirname lock-file) #js {:recursive true})
+           (fs/writeFileSync lock-file (js/JSON.stringify (clj->js lock)))
+           (-> (p/with-redefs [daemon/cleanup-stale-lock! (fn [_path _lock] (p/resolved nil))
+                               cli-server/discover-servers (fn [_] (p/resolved [{:repo repo
+                                                                                  :host "127.0.0.1"
+                                                                                  :port 55555
+                                                                                  :pid 999999
+                                                                                  :owner-source :cli
+                                                                                  :revision nil
+                                                                                  :status :starting}]))
+                               daemon/wait-for-ready (fn [_lock]
+                                                       (p/rejected (ex-info "graph already locked"
+                                                                            {:code :repo-locked
+                                                                             :lock lock})))]
+                 (cli-server/start-server! {:root-dir root-dir} repo))
+               (p/then (fn [result]
+                         (is (= false (:ok? result)))
+                         (is (= :repo-locked (get-in result [:error :code])))
+                         (is (= lock (get-in result [:error :lock])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest stop-server-denies-owner-mismatch
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-owner-stop")
+               repo (str "logseq_db_owner_stop_" (subs (str (random-uuid)) 0 8))
+               lock-file (cli-server/lock-path root-dir repo)
+               lock {:repo repo
+                     :pid (.-pid js/process)
+                     :host "127.0.0.1"
+                     :port 9101
+                     :owner-source :electron}]
+           (fs/mkdirSync (node-path/dirname lock-file) #js {:recursive true})
+           (fs/writeFileSync lock-file (js/JSON.stringify (clj->js lock)))
+           (-> (p/with-redefs [daemon/http-request (fn [_] (p/resolved {:status 200 :body ""}))
+                               daemon/wait-for (fn [_ _] (p/resolved true))]
+                 (cli-server/stop-server! {:root-dir root-dir
+                                           :owner-source :cli}
+                                          repo))
+               (p/then (fn [result]
+                         (is (= false (:ok? result)))
+                         (is (= :server-owned-by-other (get-in result [:error :code])))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest restart-server-does-not-sigterm-external-owner-daemon
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-owner-restart")
+               repo (str "logseq_db_owner_restart_" (subs (str (random-uuid)) 0 8))
+               lock-file (cli-server/lock-path root-dir repo)
+               lock {:repo repo
+                     :pid 424242
+                     :host "127.0.0.1"
+                     :port 9102
+                     :owner-source :electron}
+               start-calls (atom 0)
+               kill-calls (atom [])]
+           (fs/mkdirSync (node-path/dirname lock-file) #js {:recursive true})
+           (fs/writeFileSync lock-file (js/JSON.stringify (clj->js lock)))
+           (-> (test-helper/with-js-property-override
+                 js/process
+                 "kill"
+                 (fn [pid signal]
+                   (swap! kill-calls conj [pid signal])
+                   true)
+                 (fn []
+                   (p/with-redefs [daemon/http-request (fn [_] (p/resolved {:status 200 :body ""}))
+                                   daemon/wait-for (fn [_ _] (p/rejected (ex-info "timeout" {:code :timeout})))
+                                   daemon/pid-status (fn [_] :alive)
+                                   cli-server/start-server! (fn [_ _]
+                                                              (swap! start-calls inc)
+                                                              (p/resolved {:ok? true
+                                                                           :data {:repo repo}}))]
+                     (cli-server/restart-server! {:root-dir root-dir
+                                                  :owner-source :cli}
+                                                 repo))))
+               (p/then (fn [result]
+                         (is (= false (:ok? result)))
+                         (is (= :server-owned-by-other (get-in result [:error :code])))
+                         (is (zero? @start-calls))
+                         (is (empty? @kill-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest start-server-returns-timeout-orphan-error-with-pids
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-orphan-timeout")
+               repo (str "logseq_db_orphan_timeout_" (subs (str (random-uuid)) 0 8))
+               spawn-calls (atom 0)]
+           (-> (p/with-redefs [daemon/cleanup-stale-lock! (fn [_ _] (p/resolved nil))
+                               daemon/spawn-server! (fn [_]
+                                                      (swap! spawn-calls inc)
+                                                      nil)
+                               daemon/wait-for-lock (fn [_]
+                                                      (p/rejected (ex-info "timeout"
+                                                                           {:code :timeout})))]
+                 (cli-server/start-server! {:root-dir root-dir
+                                            :owner-source :cli}
+                                           repo))
+               (p/then (fn [result]
+                         (is (= false (:ok? result)))
+                         (is (= :server-start-timeout-orphan (get-in result [:error :code])))
+                         (is (= 1 @spawn-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest ensure-server-forwards-create-empty-db-flag-when-spawning-daemon
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-create-empty")
+               config-path (node-path/join root-dir "custom" "cli.edn")
+               repo (str "logseq_db_create_empty_" (subs (str (random-uuid)) 0 8))
+               captured (atom nil)
+               lock {:repo repo
+                     :pid (.-pid js/process)
+                     :host "127.0.0.1"
+                     :port 9301
+                     :owner-source :cli}
+               read-lock-calls (atom 0)
+               discover-calls (atom 0)]
+           (-> (p/with-redefs [daemon/read-lock (fn [_]
+                                                  (if (= 1 (swap! read-lock-calls inc))
+                                                    nil
+                                                    lock))
+                               daemon/cleanup-stale-lock! (fn [_ _] (p/resolved nil))
+                               daemon/spawn-server! (fn [opts]
+                                                      (reset! captured opts)
+                                                      nil)
+                               daemon/wait-for-lock (fn [_] (p/resolved true))
+                               cli-server/discover-servers (fn [_]
+                                                            (p/resolved (if (= 1 (swap! discover-calls inc))
+                                                                          []
+                                                                          [{:repo repo
+                                                                            :host "127.0.0.1"
+                                                                            :port 9301
+                                                                            :pid (.-pid js/process)
+                                                                            :owner-source :cli
+                                                                            :revision nil
+                                                                            :status :ready}])))
+                               daemon/wait-for-ready (fn [_] (p/resolved true))]
+                 (cli-server/ensure-server! {:root-dir root-dir
+                                             :config-path config-path
+                                             :create-empty-db? true}
+                                            repo))
+               (p/then (fn [_]
+                         (is (= repo (:repo @captured)))
+                         (is (= (cli-server/resolve-root-dir {:root-dir root-dir})
+                                (:root-dir @captured)))
+                         (is (= true (:create-empty-db? @captured)))
+                         (is (nil? (:server-list-file @captured)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest ensure-server-records-profile-stages-on-spawn-path
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-profile")
+               repo (str "logseq_db_profile_" (subs (str (random-uuid)) 0 8))
+               session (profile/create-session true)
+               read-lock-calls (atom 0)
+               discover-calls (atom 0)
+               lock {:repo repo
+                     :pid (.-pid js/process)
+                     :host "127.0.0.1"
+                     :port 9310
+                     :owner-source :cli}]
+           (-> (p/with-redefs [daemon/read-lock (fn [_]
+                                                  (if (= 1 (swap! read-lock-calls inc))
+                                                    nil
+                                                    lock))
+                               daemon/cleanup-stale-lock! (fn [_ _] (p/resolved nil))
+                               daemon/spawn-server! (fn [_] nil)
+                               daemon/wait-for-lock (fn [_] (p/resolved true))
+                               cli-server/discover-servers (fn [_]
+                                                            (p/resolved (if (= 1 (swap! discover-calls inc))
+                                                                          []
+                                                                          [{:repo repo
+                                                                            :host "127.0.0.1"
+                                                                            :port 9310
+                                                                            :pid (.-pid js/process)
+                                                                            :owner-source :cli
+                                                                            :revision nil
+                                                                            :status :ready}])))
+                               daemon/wait-for-ready (fn [_] (p/resolved true))]
+                 (cli-server/ensure-server! {:root-dir root-dir
+                                             :profile-session session}
+                                            repo))
+               (p/then (fn [_]
+                         (let [report (profile/report session {:command "server-start"
+                                                               :status :ok})
+                               by-stage (into {} (map (juxt :stage identity) (:stages report)))]
+                           (is (= 1 (get-in by-stage ["server.ensure-started" :count])))
+                           (is (= 1 (get-in by-stage ["server.spawn-daemon" :count])))
+                           (is (= 1 (get-in by-stage ["server.wait-lock" :count])))
+                           (is (= 1 (get-in by-stage ["server.wait-ready" :count]))))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest ensure-server-waits-for-server-list-publication-after-lock
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-wait-publish")
+               repo (str "logseq_db_wait_publish_" (subs (str (random-uuid)) 0 8))
+               read-lock-calls (atom 0)
+               discover-calls (atom 0)
+               lock {:repo repo
+                     :pid (.-pid js/process)
+                     :lock-id "wait-publish-lock"
+                     :owner-source :cli}
+               server {:repo repo
+                       :host "127.0.0.1"
+                       :port 9311
+                       :pid (.-pid js/process)
+                       :owner-source :cli
+                       :revision nil
+                       :status :ready}]
+           (-> (p/with-redefs [daemon/read-lock (fn [_]
+                                                  (if (= 1 (swap! read-lock-calls inc))
+                                                    nil
+                                                    lock))
+                               daemon/cleanup-stale-lock! (fn [_ _] (p/resolved nil))
+                               daemon/spawn-server! (fn [_] nil)
+                               daemon/wait-for-lock (fn [_] (p/resolved true))
+                               cli-server/discover-servers (fn [_]
+                                                            (let [call (swap! discover-calls inc)]
+                                                              (p/resolved (if (< call 3)
+                                                                            []
+                                                                            [server]))))
+                               daemon/wait-for-ready (fn [_] (p/resolved true))]
+                 (cli-server/ensure-server! {:root-dir root-dir} repo))
+               (p/then (fn [config]
+                         (is (= "http://127.0.0.1:9311" (:base-url config)))
+                         (is (true? (:owned? config)))
+                         (is (<= 3 @discover-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest ensure-server-preserves-live-server-list-entry-after-transient-healthz-failure
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-transient-healthz")
+               config-path (node-path/join root-dir "cli.edn")
+               server-list-file (cli-config/server-list-path root-dir)
+               repo (str "logseq_db_transient_healthz_" (subs (str (random-uuid)) 0 8))
+               pid 424242
+               port 9312
+               read-lock-calls (atom 0)
+               healthz-calls (atom 0)
+               lock {:repo repo
+                     :pid pid
+                     :lock-id "transient-healthz-lock"
+                     :owner-source :cli}]
+           (-> (p/with-redefs [daemon/read-lock (fn [_]
+                                                  (if (= 1 (swap! read-lock-calls inc))
+                                                    nil
+                                                    lock))
+                               daemon/cleanup-stale-lock! (fn [_ _] (p/resolved nil))
+                               daemon/spawn-server! (fn [_]
+                                                      (fs/writeFileSync server-list-file
+                                                                        (str pid " " port "\n"))
+                                                      nil)
+                               daemon/wait-for-lock (fn [_] (p/resolved true))
+                               daemon/pid-status (fn [_] :alive)
+                               daemon/http-request (fn [{:keys [path]}]
+                                                     (if (= "/healthz" path)
+                                                       (let [call (swap! healthz-calls inc)]
+                                                         (if (= 1 call)
+                                                           (p/rejected (ex-info "connection refused" {:code :econnrefused}))
+                                                           (p/resolved {:status 200
+                                                                        :body (js/JSON.stringify
+                                                                               (clj->js {:repo repo
+                                                                                         :status "ready"
+                                                                                         :host "127.0.0.1"
+                                                                                         :port port
+                                                                                         :pid pid
+                                                                                         :owner-source "cli"
+                                                                                         :root-dir root-dir
+                                                                                         :revision "server-revision"}))})))
+                                                       (p/resolved {:status 200 :body ""})))
+                               daemon/wait-for-ready (fn [_] (p/resolved true))]
+                 (cli-server/ensure-server! {:root-dir root-dir
+                                             :config-path config-path}
+                                            repo))
+               (p/then (fn [config]
+                         (is (= "http://127.0.0.1:9312" (:base-url config)))
+                         (is (true? (:owned? config)))
+                         (is (>= @healthz-calls 2))
+                         (is (= (str pid " " port "\n")
+                                (.toString (fs/readFileSync server-list-file) "utf8")))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest ensure-server-ignores-discovered-server-from-other-root-dir
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-other-root-dir")
+               root-dir-a (node-path/join root-dir "graphs-a")
+               root-dir-b (node-path/join root-dir "graphs-b")
+               config-path (node-path/join root-dir "cli.edn")
+               repo (str "logseq_db_shared_repo_" (subs (str (random-uuid)) 0 8))
+               spawned? (atom false)
+               captured (atom nil)
+               lock {:repo repo
+                     :pid (.-pid js/process)
+                     :lock-id "local-lock"
+                     :owner-source :cli}
+               remote-server {:repo repo
+                              :host "127.0.0.1"
+                              :port 9320
+                              :pid 1001
+                              :owner-source :cli
+                              :revision nil
+                              :status :ready
+                              :root-dir root-dir-a}
+               local-server {:repo repo
+                             :host "127.0.0.1"
+                             :port 9321
+                             :pid (.-pid js/process)
+                             :owner-source :cli
+                             :revision nil
+                             :status :ready
+                             :root-dir root-dir-b}]
+           (-> (p/with-redefs [daemon/read-lock (fn [_]
+                                                  (when @spawned?
+                                                    lock))
+                               daemon/cleanup-stale-lock! (fn [_ _] (p/resolved nil))
+                               daemon/spawn-server! (fn [opts]
+                                                      (reset! captured opts)
+                                                      (reset! spawned? true)
+                                                      nil)
+                               daemon/wait-for-lock (fn [_] (p/resolved true))
+                               cli-server/discover-servers (fn [_]
+                                                            (p/resolved (if @spawned?
+                                                                          [remote-server local-server]
+                                                                          [remote-server])))
+                               daemon/wait-for-ready (fn [_] (p/resolved true))]
+                 (cli-server/ensure-server! {:root-dir root-dir-b
+                                             :config-path config-path}
+                                            repo))
+               (p/then (fn [config]
+                         (is (= root-dir-b (:root-dir @captured)))
+                         (is (= "http://127.0.0.1:9321" (:base-url config)))
+                         (is (true? (:owned? config)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest ensure-server-reuses-discovered-server-across-symlinked-root-dir-spellings
+  (async done
+         (let [base-dir (node-path/resolve (node-helper/create-tmp-dir "cli-server-symlink-root-dir"))
+               real-root-dir (node-path/join base-dir "real-root-dir")
+               symlink-root-dir (node-path/join base-dir "symlink-root-dir")
+               symlink-type (if (= "win32" (.-platform js/process)) "junction" "dir")
+               repo (str "logseq_db_symlink_dir_" (subs (str (random-uuid)) 0 8))
+               lock {:repo repo
+                     :pid (.-pid js/process)
+                     :lock-id "symlink-lock"
+                     :owner-source :cli}
+               spawned? (atom false)]
+           (fs/mkdirSync real-root-dir #js {:recursive true})
+           (fs/symlinkSync real-root-dir symlink-root-dir symlink-type)
+           (-> (p/with-redefs [daemon/read-lock (fn [_] lock)
+                               daemon/cleanup-stale-lock! (fn [_ _] (p/resolved nil))
+                               daemon/spawn-server! (fn [_]
+                                                      (reset! spawned? true)
+                                                      nil)
+                               cli-server/discover-servers (fn [_]
+                                                            (p/resolved [{:repo repo
+                                                                          :host "127.0.0.1"
+                                                                          :port 9322
+                                                                          :pid (.-pid js/process)
+                                                                          :owner-source :cli
+                                                                          :revision nil
+                                                                          :status :ready
+                                                                          :root-dir symlink-root-dir}]))
+                               daemon/wait-for-ready (fn [_] (p/resolved true))]
+                 (cli-server/ensure-server! {:root-dir real-root-dir}
+                                            repo))
+               (p/then (fn [config]
+                         (is (false? @spawned?))
+                         (is (= "http://127.0.0.1:9322" (:base-url config)))
+                         (is (true? (:owned? config)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest stop-server-targets-discovered-server-for-current-root-dir
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-stop-target")
+               root-dir-a (node-path/join root-dir "graphs-a")
+               root-dir-b (node-path/join root-dir "graphs-b")
+               config-path (node-path/join root-dir "cli.edn")
+               repo (str "logseq_db_stop_target_" (subs (str (random-uuid)) 0 8))
+               lock-file (cli-server/lock-path root-dir-b repo)
+               request* (atom nil)
+               lock {:repo repo
+                     :pid (.-pid js/process)
+                     :lock-id "stop-lock"
+                     :owner-source :cli}]
+           (fs/mkdirSync (node-path/dirname lock-file) #js {:recursive true})
+           (fs/writeFileSync lock-file (js/JSON.stringify (clj->js lock)))
+           (-> (p/with-redefs [cli-server/discover-servers (fn [_]
+                                                            (p/resolved [{:repo repo
+                                                                          :host "127.0.0.1"
+                                                                          :port 9401
+                                                                          :pid 4001
+                                                                          :owner-source :cli
+                                                                          :revision nil
+                                                                          :status :ready
+                                                                          :root-dir root-dir-a}
+                                                                         {:repo repo
+                                                                          :host "127.0.0.1"
+                                                                          :port 9402
+                                                                          :pid 4002
+                                                                          :owner-source :cli
+                                                                          :revision nil
+                                                                          :status :ready
+                                                                          :root-dir root-dir-b}]))
+                               daemon/http-request (fn [opts]
+                                                     (reset! request* opts)
+                                                     (p/resolved {:status 200 :body ""}))
+                               daemon/wait-for (fn [_ _] (p/resolved true))]
+                 (cli-server/stop-server! {:root-dir root-dir-b
+                                           :config-path config-path
+                                           :owner-source :cli}
+                                          repo))
+               (p/then (fn [result]
+                         (is (= true (:ok? result)))
+                         (is (= 9402 (:port @request*)))
+                         (is (= "127.0.0.1" (:host @request*)))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest list-servers-reads-server-list-and-healthz-details
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-list-revision")
+               config-path (node-path/join root-dir "cli.edn")
+               server-list-file (cli-config/server-list-path root-dir)
+               repo (str "logseq_db_list_revision_" (subs (str (random-uuid)) 0 8))
+               host "127.0.0.1"
+               port* (atom nil)
+               server (http/createServer
+                       (fn [^js req ^js res]
+                         (case (.-url req)
+                           "/healthz" (do (.writeHead res 200 #js {"Content-Type" "application/json"})
+                                          (.end res (js/JSON.stringify #js {:repo repo
+                                                                            :status "ready"
+                                                                            :host host
+                                                                            :port @port*
+                                                                            :pid (.-pid js/process)
+                                                                            :owner-source "cli"
+                                                                            :root-dir root-dir
+                                                                            :revision "server-revision"})))
+                           (do (.writeHead res 404 #js {"Content-Type" "text/plain"})
+                               (.end res "not-found")))))]
+           (.listen server 0 host
+                    (fn []
+                      (let [address (.address server)
+                            port (if (number? address) address (.-port address))
+                            _ (reset! port* port)]
+                        (fs/writeFileSync server-list-file (str (.-pid js/process) " " port "\n"))
+                        (-> (cli-server/list-servers {:root-dir root-dir
+                                                      :config-path config-path})
+                            (p/then (fn [servers]
+                                      (is (= 1 (count servers)))
+                                      (is (= repo (:repo (first servers))))
+                                      (is (= :ready (:status (first servers))))
+                                      (is (= root-dir (:root-dir (first servers))))
+                                      (is (= "server-revision" (:revision (first servers))))))
+                            (p/catch (fn [e]
+                                       (is false (str "unexpected error: " e))))
+                            (p/finally (fn []
+                                         (.close server (fn [] (done))))))))))))
+
+(deftest list-servers-lazily-cleans-stale-server-list-entries
+  (async done
+         (let [root-dir (node-helper/create-tmp-dir "cli-server-list-cleanup")
+               config-path (node-path/join root-dir "cli.edn")
+               server-list-file (cli-config/server-list-path root-dir)]
+           (fs/writeFileSync server-list-file "999999 65535\n")
+           (-> (cli-server/list-servers {:root-dir root-dir
+                                         :config-path config-path})
+               (p/then (fn [servers]
+                         (is (empty? servers))
+                         (let [contents (when (fs/existsSync server-list-file)
+                                          (.toString (fs/readFileSync server-list-file) "utf8"))]
+                           (is (or (nil? contents)
+                                   (= "" contents))))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest cleanup-revision-mismatched-servers-kills-only-cli-owned-targets
+  (async done
+         (let [stop-calls (atom [])]
+           (-> (p/with-redefs [cli-server/list-servers (fn [_]
+                                                         (p/resolved [{:repo "logseq_db_a"
+                                                                       :pid 11
+                                                                       :owner-source :cli
+                                                                       :revision "worker-rev-a"}
+                                                                      {:repo "logseq_db_b"
+                                                                       :pid 22
+                                                                       :owner-source :electron
+                                                                       :revision "worker-rev-b"}
+                                                                      {:repo "logseq_db_c"
+                                                                       :pid 33
+                                                                       :owner-source :cli
+                                                                       :revision "cli-rev"}
+                                                                      {:repo "logseq_db_nil"
+                                                                       :pid 44
+                                                                       :owner-source :cli
+                                                                       :revision nil}]))
+                               cli-server/stop-server! (fn [config repo]
+                                                         (swap! stop-calls conj {:config config
+                                                                                 :repo repo})
+                                                         (p/resolved {:ok? true
+                                                                      :data {:repo repo}}))]
+                 (cli-server/cleanup-revision-mismatched-servers! {:root-dir "/tmp/graphs"} "cli-rev"))
+               (p/then (fn [result]
+                         (is (= true (:ok? result)))
+                         (is (= 4 (get-in result [:data :checked])))
+                         (is (= 3 (get-in result [:data :mismatched])))
+                         (is (= 2 (get-in result [:data :eligible])))
+                         (is (= 1 (get-in result [:data :skipped-owner])))
+                         (is (= ["logseq_db_a" "logseq_db_nil"]
+                                (mapv :repo (get-in result [:data :killed]))))
+                         (is (empty? (get-in result [:data :failed])))
+                         (is (= #{"logseq_db_a" "logseq_db_nil"}
+                                (set (map :repo @stop-calls))))
+                         (is (every? #(= :cli (get-in % [:config :owner-source]))
+                                     @stop-calls))))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))))
+               (p/finally done)))))
+
+(deftest cleanup-revision-mismatched-servers-reports-failures
+  (async done
+         (-> (p/with-redefs [cli-server/list-servers (fn [_]
+                                                       (p/resolved [{:repo "logseq_db_a"
+                                                                     :pid 11
+                                                                     :owner-source :cli
+                                                                     :revision "worker-rev-a"}
+                                                                    {:repo "logseq_db_b"
+                                                                     :pid 22
+                                                                     :owner-source :cli
+                                                                     :revision "worker-rev-b"}]))
+                             cli-server/stop-server! (fn [_ repo]
+                                                       (p/resolved (if (= "logseq_db_a" repo)
+                                                                     {:ok? true
+                                                                      :data {:repo repo}}
+                                                                     {:ok? false
+                                                                      :error {:code :server-stop-timeout
+                                                                              :message "timed out stopping server"}})))]
+               (cli-server/cleanup-revision-mismatched-servers! {:root-dir "/tmp/graphs"} "cli-rev"))
+             (p/then (fn [result]
+                       (is (= true (:ok? result)))
+                       (is (= ["logseq_db_a"]
+                              (mapv :repo (get-in result [:data :killed]))))
+                       (is (= ["logseq_db_b"]
+                              (mapv :repo (get-in result [:data :failed]))))
+                       (is (= :server-stop-timeout
+                              (get-in result [:data :failed 0 :error :code])))))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))))
+             (p/finally done))))
+
+(deftest list-graph-items-ignores-non-graph-directories
+  (let [root-dir (node-helper/create-tmp-dir "cli-list-graphs-ignore")
+        graphs-dir (node-path/join root-dir "graphs")
+        _ (doseq [dir ["alpha"
+                       "backup"
+                       "foo~2G"
+                       "Unlinked graphs"
+                       "logseq_local_1"]]
+            (fs/mkdirSync (node-path/join graphs-dir dir) #js {:recursive true}))
+        items (cli-server/list-graph-items {:root-dir root-dir})]
+    (is (= [{:kind :canonical
+             :graph-name "alpha"
+             :graph-dir "alpha"}]
+           items))))
+
+(deftest list-graph-items-marks-legacy-conflict
+  (let [root-dir (node-helper/create-tmp-dir "cli-list-graphs-legacy")
+        graphs-dir (node-path/join root-dir "graphs")
+        _ (doseq [dir ["legacy++name"
+                       "legacy~2Fname"
+                       "bad%ZZname"]]
+            (fs/mkdirSync (node-path/join graphs-dir dir) #js {:recursive true}))
+        items (cli-server/list-graph-items {:root-dir root-dir})
+        by-kind (group-by :kind items)
+        legacy-item (first (get by-kind :legacy))
+        undecodable-item (first (get by-kind :legacy-undecodable))]
+    (is (= "legacy/name" (:legacy-graph-name legacy-item)))
+    (is (= "legacy~2Fname" (:target-graph-dir legacy-item)))
+    (is (= true (:conflict? legacy-item)))
+    (is (= "bad%ZZname" (:legacy-dir undecodable-item)))))
+
+(deftest list-graph-items-treats-percent-encoded-dir-as-legacy-when-non-canonical
+  (let [root-dir (node-helper/create-tmp-dir "cli-list-graphs-percent-legacy")
+        graphs-dir (node-path/join root-dir "graphs")
+        _ (doseq [dir ["yy y"
+                       "yy~20y"
+                       "yy%20y"]]
+            (fs/mkdirSync (node-path/join graphs-dir dir) #js {:recursive true}))
+        items (cli-server/list-graph-items {:root-dir root-dir})
+        by-kind (group-by :kind items)
+        canonical-item (first (get by-kind :canonical))
+        legacy-items (get by-kind :legacy)
+        legacy-by-dir (into {} (map (juxt :legacy-dir identity) legacy-items))]
+    (is (= "yy y" (:graph-dir canonical-item)))
+    (is (= "yy y" (:graph-name canonical-item)))
+    (is (= #{"yy~20y" "yy%20y"}
+           (set (map :legacy-dir legacy-items))))
+    (doseq [legacy-dir ["yy~20y" "yy%20y"]]
+      (let [legacy-item (get legacy-by-dir legacy-dir)]
+        (is (= "yy y" (:legacy-graph-name legacy-item)))
+        (is (= "yy y" (:target-graph-dir legacy-item)))
+        (is (= true (:conflict? legacy-item)))))))
diff --git a/src/test/logseq/cli/style_test.cljs b/src/test/logseq/cli/style_test.cljs
new file mode 100644
index 0000000000..808f6559fa
--- /dev/null
+++ b/src/test/logseq/cli/style_test.cljs
@@ -0,0 +1,23 @@
+(ns logseq.cli.style-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [logseq.cli.style :as style]))
+
+(deftest test-strip-ansi
+  (testing "strip-ansi removes ANSI sequences"
+    (is (= "Hello"
+           (style/strip-ansi "\u001b[1mHello\u001b[22m")))
+    (is (= "Hello"
+           (style/strip-ansi "\u001b[31mHello\u001b[39m")))))
+
+(deftest test-style-disabled
+  (testing "style helpers return plain text when color is disabled"
+    (binding [style/*color-enabled?* false]
+      (is (= "Hi" (style/bold "Hi")))
+      (is (= "Hi" (style/dim "Hi")))
+      (is (= "Hi" (style/green "Hi"))))))
+
+(deftest test-style-enabled
+  (testing "style helpers include ANSI when color is enabled"
+    (binding [style/*color-enabled?* true]
+      (is (not= "Hi" (style/bold "Hi")))
+      (is (re-find #"\u001b\[[0-9;]*m" (style/bold "Hi"))))))
diff --git a/src/test/logseq/cli/test_helper.cljs b/src/test/logseq/cli/test_helper.cljs
new file mode 100644
index 0000000000..9f0238fb38
--- /dev/null
+++ b/src/test/logseq/cli/test_helper.cljs
@@ -0,0 +1,16 @@
+(ns logseq.cli.test-helper
+  (:require [goog.object :as gobj]
+            [promesa.core :as p]))
+
+(defn with-js-property-override
+  "Temporarily override a JS object property for the duration of an async body.
+
+  Restores the original property value after the returned promise settles. Use
+  this for process/module globals that cannot be handled by `with-redefs`.
+  Resource cleanup still belongs in outer `p/finally` blocks."
+  [obj prop value f]
+  (let [original (gobj/get obj prop)]
+    (gobj/set obj prop value)
+    (-> (f)
+        (p/finally (fn []
+                     (gobj/set obj prop original))))))
diff --git a/src/test/logseq/cli/transport_test.cljs b/src/test/logseq/cli/transport_test.cljs
new file mode 100644
index 0000000000..95e8a427e9
--- /dev/null
+++ b/src/test/logseq/cli/transport_test.cljs
@@ -0,0 +1,361 @@
+(ns logseq.cli.transport-test
+  (:require [cljs.test :refer [deftest is async testing]]
+            [clojure.string :as string]
+            [logseq.cli.profile :as profile]
+            [logseq.cli.test-helper :as test-helper]
+            [logseq.cli.transport :as transport]
+            [logseq.db :as ldb]
+            [promesa.core :as p]))
+
+(def ^:private fs (js/require "fs"))
+(def ^:private os (js/require "os"))
+(def ^:private path (js/require "path"))
+
+(defn- temp-path
+  [filename]
+  (let [dir (.mkdtempSync fs (.join path (.tmpdir os) "logseq-cli-"))]
+    (.join path dir filename)))
+
+(defn- capture-throw-message
+  [f]
+  (try
+    (f)
+    nil
+    (catch :default e
+      (or (ex-message e) (.-message e) (str e)))))
+
+(defn- start-server
+  [handler]
+  (p/create
+   (fn [resolve reject]
+     (let [http (js/require "http")
+           server (.createServer http handler)]
+       (.on server "error" reject)
+       (.listen server 0 "127.0.0.1"
+                (fn []
+                  (let [address (.address server)
+                        port (.-port address)
+                        stop! (fn []
+                                (p/create (fn [resolve _]
+                                            (.close server (fn [] (resolve true))))))]
+                    (resolve {:url (str "http://127.0.0.1:" port)
+                              :stop! stop!}))))))))
+
+(deftest test-request-avoids-deprecated-url-parse
+  (async done
+         (let [url-module (js/require "url")
+               original-parse (.-parse url-module)
+               parse-calls (atom 0)]
+           (-> (test-helper/with-js-property-override
+                 url-module
+                 "parse"
+                 (fn [& args]
+                   (swap! parse-calls inc)
+                   (.apply original-parse url-module (to-array args)))
+                 (fn []
+                   (p/let [{:keys [url stop!]} (start-server
+                                                (fn [_req ^js res]
+                                                  (.writeHead res 200 #js {"Content-Type" "text/plain"})
+                                                  (.end res "ok")))]
+                     (p/let [response (transport/request {:method "GET"
+                                                          :url (str url "/status")
+                                                          :timeout-ms 1000})]
+                       (is (= 200 (:status response)))
+                       (is (= 0 @parse-calls))
+                       (p/let [_ (stop!)] true)))))
+               (p/then (fn [_] (done)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))
+                          (done)))))))
+
+(deftest test-request-does-not-retry
+  (async done
+         (let [calls (atom 0)]
+           (-> (p/let [{:keys [url stop!]} (start-server
+                                            (fn [_req ^js res]
+                                              (let [attempt (swap! calls inc)]
+                                                (if (= attempt 1)
+                                                  (do
+                                                    (.writeHead res 500 #js {"Content-Type" "text/plain"})
+                                                    (.end res "boom"))
+                                                  (do
+                                                    (.writeHead res 200 #js {"Content-Type" "text/plain"})
+                                                    (.end res "ok"))))))]
+                 (p/catch
+                  (transport/request {:method "GET"
+                                      :url (str url "/retry")
+                                      :timeout-ms 1000})
+                  (fn [e]
+                    (is (= :http-error (-> (ex-data e) :code)))
+                    (is (= 500 (-> (ex-data e) :status)))))
+                 (is (= 1 @calls))
+                 (p/let [_ (stop!)] true))
+               (p/then (fn [_] (done)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))
+                          (done)))))))
+
+(deftest test-request-error-includes-body
+  (async done
+         (-> (p/let [{:keys [url stop!]} (start-server
+                                           (fn [_req ^js res]
+                                             (.writeHead res 500 #js {"Content-Type" "text/plain"})
+                                             (.end res "property type mismatch")))]
+               (p/catch
+                (transport/request {:method "GET"
+                                    :url (str url "/fail")
+                                    :timeout-ms 1000})
+                (fn [e]
+                  (is (= :http-error (-> (ex-data e) :code)))
+                  (is (= "property type mismatch" (-> (ex-data e) :body)))
+                  (is (re-find #"500" (ex-message e))
+                      "error message includes status code")
+                  (is (re-find #"property type mismatch" (ex-message e))
+                      "error message includes response body")))
+               (p/let [_ (stop!)] true))
+             (p/then (fn [_] (done)))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))
+                        (done))))))
+
+(deftest test-request-400-extracts-api-message
+  (async done
+         (-> (p/let [{:keys [url stop!]} (start-server
+                                           (fn [_req ^js res]
+                                             (.writeHead res 400 #js {"Content-Type" "application/json"})
+                                             (.end res (js/JSON.stringify
+                                                        #js {:ok false
+                                                             :error #js {:code "validation-failed"
+                                                                         :message "Can't set tag with built-in #Journal"}}))))]
+               (p/catch
+                (transport/request {:method "POST"
+                                    :url (str url "/invoke")
+                                    :timeout-ms 1000})
+                (fn [e]
+                  (is (= :validation-failed (-> (ex-data e) :code)))
+                  (is (= 400 (-> (ex-data e) :status)))
+                  (is (= "Can't set tag with built-in #Journal" (ex-message e))
+                      "error message is the clean API message, not raw JSON")))
+               (p/let [_ (stop!)] true))
+             (p/then (fn [_] (done)))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))
+                        (done))))))
+
+(deftest test-request-propagates-server-error-code-for-non-400
+  (async done
+         (-> (p/let [{:keys [url stop!]} (start-server
+                                           (fn [_req ^js res]
+                                             (.writeHead res 409 #js {"Content-Type" "application/json"})
+                                             (.end res (js/JSON.stringify
+                                                        #js {:ok false
+                                                             :error #js {:code "repo-locked"
+                                                                         :message "graph is locked"}}))))]
+               (p/catch
+                (transport/request {:method "POST"
+                                    :url (str url "/invoke")
+                                    :timeout-ms 1000})
+                (fn [e]
+                  (is (= :repo-locked (-> (ex-data e) :code)))
+                  (is (= 409 (-> (ex-data e) :status)))
+                  (is (= "graph is locked" (ex-message e)))))
+               (p/let [_ (stop!)] true))
+             (p/then (fn [_] (done)))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))
+                        (done))))))
+
+(deftest test-request-rethrows-non-syntax-json-parse-errors
+  (async done
+         (-> (test-helper/with-js-property-override
+               js/JSON
+               "parse"
+               (fn [_]
+                 (throw (js/Error. "json parser exploded")))
+               (fn []
+                 (p/let [{:keys [url stop!]} (start-server
+                                              (fn [_req ^js res]
+                                                (.writeHead res 500 #js {"Content-Type" "application/json"})
+                                                (.end res "{\"ok\":false}")))]
+                   (p/catch
+                    (transport/request {:method "POST"
+                                        :url (str url "/invoke")
+                                        :timeout-ms 1000})
+                    (fn [e]
+                      (is (string/includes? (or (ex-message e) (str e)) "json parser exploded"))))
+                   (p/let [_ (stop!)] true))))
+             (p/then (fn [_] (done)))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))
+                        (done))))))
+
+(deftest test-request-timeout
+  (async done
+         (-> (p/let [{:keys [url stop!]} (start-server
+                                          (fn [_req _res]
+                                            nil))]
+               (p/catch
+                (transport/request {:method "GET"
+                                    :url (str url "/hang")
+                                    :timeout-ms 10})
+                (fn [e]
+                  (is (= :timeout (-> (ex-data e) :code)))
+                  (p/let [_ (stop!)] true))))
+             (p/then (fn [_] (done)))
+             (p/catch (fn [e]
+                        (is false (str "unexpected error: " e))
+                        (done))))))
+
+(deftest test-invoke-accepts-keyword-method
+  (async done
+         (let [received (atom nil)]
+           (-> (p/let [{:keys [url stop!]} (start-server
+                                            (fn [^js req ^js res]
+                                              (let [chunks (array)]
+                                                (.on req "data" (fn [chunk] (.push chunks chunk)))
+                                                (.on req "end" (fn []
+                                                                 (let [buf (js/Buffer.concat chunks)
+                                                                       payload (js/JSON.parse (.toString buf "utf8"))]
+                                                                   (reset! received (js->clj payload :keywordize-keys true))
+                                                                   (.writeHead res 200 #js {"Content-Type" "application/json"})
+                                                                   (.end res (js/JSON.stringify #js {:result "ok"}))))))))]
+                 (p/let [result (transport/invoke {:base-url url} :thread-api/pull true ["repo" [:block/title]])]
+                   (is (= "ok" result))
+                   (is (= "thread-api/pull" (:method @received)))
+                   (is (= true (:directPass @received)))
+                   (p/let [_ (stop!)] true)))
+               (p/then (fn [_] (done)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))
+                          (done)))))))
+
+(deftest test-invoke-requires-explicit-base-url-and-method
+  (testing "invoke fails fast when base-url is missing"
+    (let [message (capture-throw-message #(transport/invoke {} :thread-api/q true []))]
+      (is (re-find #"base-url is required" (or message "")))))
+
+  (testing "invoke fails fast when method is missing"
+    (let [message (capture-throw-message #(transport/invoke {:base-url "http://127.0.0.1:8123"}
+                                                            nil
+                                                            true
+                                                            []))]
+      (is (re-find #"invoke method is required" (or message ""))))))
+
+(deftest test-connect-events-requires-valid-arguments
+  (testing "connect-events! requires base-url"
+    (let [message (capture-throw-message #(transport/connect-events! {} (fn [_ _] nil)))]
+      (is (re-find #"base-url is required" (or message "")))))
+
+  (testing "connect-events! requires function handler"
+    (let [message (capture-throw-message #(transport/connect-events! {:base-url "http://127.0.0.1:8123"} nil))]
+      (is (re-find #"handler must be a function" (or message ""))))))
+
+(deftest test-invoke-does-not-send-auth-header
+  (async done
+         (let [auth-header (atom :unset)]
+           (-> (p/let [{:keys [url stop!]} (start-server
+                                            (fn [^js req ^js res]
+                                              (let [headers (.-headers req)]
+                                                (reset! auth-header (aget headers "authorization")))
+                                              (.writeHead res 200 #js {"Content-Type" "application/json"})
+                                              (.end res (js/JSON.stringify #js {:result "ok"}))))]
+                 (p/let [result (transport/invoke {:base-url url
+                                                   :auth-token "secret"}
+                                                  :thread-api/pull
+                                                  true
+                                                  ["repo" [:block/title]])]
+                   (is (= "ok" result))
+                   (is (nil? @auth-header))
+                   (p/let [_ (stop!)] true)))
+               (p/then (fn [_] (done)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))
+                          (done)))))))
+
+(deftest test-invoke-records-profile-stage-and-aggregation
+  (async done
+         (let [session (profile/create-session true)]
+           (-> (p/let [{:keys [url stop!]} (start-server
+                                            (fn [_req ^js res]
+                                              (.writeHead res 200 #js {"Content-Type" "application/json"})
+                                              (.end res (js/JSON.stringify #js {:result "ok"}))))
+                       _ (transport/invoke {:base-url url
+                                            :profile-session session}
+                                           :thread-api/q
+                                           true
+                                           ["repo" [:block/title]])
+                       _ (transport/invoke {:base-url url
+                                            :profile-session session}
+                                           :thread-api/q
+                                           true
+                                           ["repo" [:block/title]])
+                       report (profile/report session {:command "query"
+                                                       :status :ok})
+                       by-stage (into {} (map (juxt :stage identity) (:stages report)))]
+                 (is (= 2 (get-in by-stage ["transport.invoke:thread-api/q" :count])))
+                 (is (>= (get-in by-stage ["transport.invoke:thread-api/q" :total-ms]) 0))
+                 (p/let [_ (stop!)] true))
+               (p/then (fn [_] (done)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))
+                          (done)))))))
+
+(deftest test-connect-events-decodes-rtc-log-and-cleans-up
+  (async done
+         (let [received (atom [])
+               client-closed? (atom false)]
+           (-> (p/let [{:keys [url stop!]} (start-server
+                                            (fn [^js req ^js res]
+                                              (if (= "/v1/events" (.-url req))
+                                                (do
+                                                  (.writeHead res 200 #js {"Content-Type" "text/event-stream"
+                                                                           "Cache-Control" "no-cache"
+                                                                           "Connection" "keep-alive"})
+                                                  (let [payload (ldb/write-transit-str {:type :rtc.log/download
+                                                                                        :graph-uuid "graph-1"
+                                                                                        :message "Preparing graph snapshot download"})
+                                                        data (js/JSON.stringify #js {:type "rtc-log"
+                                                                                     :payload payload})]
+                                                    (.write res (str "data: " data "\n\n")))
+                                                  (.on req "close" (fn []
+                                                                     (reset! client-closed? true))))
+                                                (do
+                                                  (.writeHead res 404 #js {"Content-Type" "text/plain"})
+                                                  (.end res "not-found")))))]
+                 (let [{:keys [close!]} (transport/connect-events! {:base-url url}
+                                                                    (fn [event-type payload]
+                                                                      (swap! received conj [event-type payload])))]
+                   (p/let [_ (p/delay 50)
+                           _ (close!)
+                           _ (p/delay 50)]
+                     (is (= [[:rtc-log {:type :rtc.log/download
+                                        :graph-uuid "graph-1"
+                                        :message "Preparing graph snapshot download"}]]
+                            @received))
+                     (is (= true @client-closed?))
+                     (stop!))))
+               (p/then (fn [_] (done)))
+               (p/catch (fn [e]
+                          (is false (str "unexpected error: " e))
+                          (done)))))))
+
+(deftest test-read-input
+  (testing "reads edn input"
+    (let [file-path (temp-path "input.edn")]
+      (.writeFileSync fs file-path "{:a 1}")
+      (is (= {:a 1} (transport/read-input {:format :edn :path file-path})))))
+
+  (testing "reads sqlite input as buffer"
+    (let [file-path (temp-path "input.sqlite")
+          buffer (js/Buffer.from "sqlite-data")]
+      (.writeFileSync fs file-path buffer)
+      (let [result (transport/read-input {:format :sqlite :path file-path})]
+        (is (instance? js/Buffer result))
+        (is (= "sqlite-data" (.toString result "utf8")))))))
+
+(deftest test-write-output
+  (testing "writes sqlite output as buffer"
+    (let [file-path (temp-path "output.sqlite")
+          buffer (js/Buffer.from "sqlite-export")]
+      (transport/write-output {:format :sqlite :path file-path :data buffer})
+      (is (= "sqlite-export" (.toString (.readFileSync fs file-path) "utf8"))))))
diff --git a/src/test/logseq/common/cognito_config_test.cljs b/src/test/logseq/common/cognito_config_test.cljs
new file mode 100644
index 0000000000..93cd762b81
--- /dev/null
+++ b/src/test/logseq/common/cognito_config_test.cljs
@@ -0,0 +1,8 @@
+(ns logseq.common.cognito-config-test
+  (:require [cljs.test :refer [deftest is]]
+            [frontend.config :as config]
+            [logseq.common.cognito-config :as cognito-config]))
+
+(deftest test-shared-cognito-config-matches-frontend-config
+  (is (= config/COGNITO-CLIENT-ID cognito-config/COGNITO-CLIENT-ID))
+  (is (= config/OAUTH-DOMAIN cognito-config/OAUTH-DOMAIN)))
diff --git a/src/test/logseq/db/common_sqlite_test.cljs b/src/test/logseq/db/common_sqlite_test.cljs
new file mode 100644
index 0000000000..8767eedca4
--- /dev/null
+++ b/src/test/logseq/db/common_sqlite_test.cljs
@@ -0,0 +1,17 @@
+(ns logseq.db.common-sqlite-test
+  (:require [cljs.test :refer [deftest is]]
+            [logseq.db.common.sqlite :as common-sqlite]))
+
+(deftest get-db-full-path-uses-encoded-graph-dir
+  (is (= ["foo~2Fbar" "/tmp/graphs/foo~2Fbar/db.sqlite"]
+         (common-sqlite/get-db-full-path "/tmp/graphs" "logseq_db_foo/bar"))))
+
+(deftest get-db-backups-path-uses-encoded-graph-dir
+  (is (= "/tmp/graphs/foo~2Fbar/backups"
+         (common-sqlite/get-db-backups-path "/tmp/graphs" "logseq_db_foo/bar"))))
+
+(deftest get-db-paths-preserve-space-in-canonical-graph-dir
+  (is (= ["space name" "/tmp/graphs/space name/db.sqlite"]
+         (common-sqlite/get-db-full-path "/tmp/graphs" "logseq_db_space name")))
+  (is (= "/tmp/graphs/space name/backups"
+         (common-sqlite/get-db-backups-path "/tmp/graphs" "logseq_db_space name"))))
diff --git a/src/test/logseq/db_worker/daemon_test.cljs b/src/test/logseq/db_worker/daemon_test.cljs
new file mode 100644
index 0000000000..0c256f741d
--- /dev/null
+++ b/src/test/logseq/db_worker/daemon_test.cljs
@@ -0,0 +1,191 @@
+(ns logseq.db-worker.daemon-test
+  (:require [cljs.test :refer [async deftest is]]
+            [frontend.test.node-helper :as node-helper]
+            [logseq.cli.test-helper :as test-helper]
+            [logseq.db-worker.daemon :as daemon]
+            [promesa.core :as p]
+            ["fs" :as fs]
+            ["path" :as node-path]
+            ["child_process" :as child-process]))
+
+(defn- call-private
+  [sym & args]
+  (when-let [v (get (ns-interns 'logseq.db-worker.daemon) sym)]
+    (apply @v args)))
+
+(deftest spawn-server-ignores-server-list-file-and-uses-detached-process
+  (let [captured (atom nil)
+        unref-called? (atom false)
+        original-spawn (.-spawn child-process)]
+    (set! (.-spawn child-process)
+          (fn [cmd args opts]
+            (reset! captured {:cmd cmd
+                              :args (vec (js->clj args))
+                              :opts (js->clj opts :keywordize-keys true)})
+            (js-obj "unref" (fn [] (reset! unref-called? true)))))
+    (try
+      (daemon/spawn-server! {:script "/tmp/db-worker-node.js"
+                             :repo "logseq_db_spawn_helper_test"
+                             :root-dir "/tmp/logseq-root"
+                             :server-list-file "/tmp/server-list"})
+      (is (= (.-execPath js/process) (:cmd @captured)))
+      (is (= "/tmp/db-worker-node.js" (first (:args @captured))))
+      (is (some #{"--repo"} (:args @captured)))
+      (is (some #{"--root-dir"} (:args @captured)))
+      (is (not-any? #{"--server-list-file"} (:args @captured)))
+      (is (not-any? #{"/tmp/server-list"} (:args @captured)))
+      (is (not-any? #{"--host" "--port"} (:args @captured)))
+      (is (= true (get-in @captured [:opts :detached])))
+      (is (= "1" (get-in @captured [:opts :env :ELECTRON_RUN_AS_NODE])))
+      (is (= true @unref-called?))
+      (finally
+        (set! (.-spawn child-process) original-spawn)))))
+
+(deftest spawn-server-keeps-electron-owned-process-attached
+  (let [captured (atom nil)
+        unref-called? (atom false)
+        original-spawn (.-spawn child-process)]
+    (set! (.-spawn child-process)
+          (fn [cmd args opts]
+            (reset! captured {:cmd cmd
+                              :args (vec (js->clj args))
+                              :opts (js->clj opts :keywordize-keys true)})
+            (js-obj "unref" (fn [] (reset! unref-called? true)))))
+    (try
+      (daemon/spawn-server! {:script "/tmp/db-worker-node.js"
+                             :repo "logseq_db_spawn_helper_test"
+                             :root-dir "/tmp/logseq-root"
+                             :owner-source :electron})
+      (is (= false (get-in @captured [:opts :detached])))
+      (is (= "inherit" (get-in @captured [:opts :stdio])))
+      (is (= false @unref-called?))
+      (finally
+        (set! (.-spawn child-process) original-spawn)))))
+
+(deftest spawn-server-appends-create-empty-db-flag-when-enabled
+  (let [captured (atom nil)
+        original-spawn (.-spawn child-process)]
+    (set! (.-spawn child-process)
+          (fn [cmd args opts]
+            (reset! captured {:cmd cmd
+                              :args (vec (js->clj args))
+                              :opts (js->clj opts :keywordize-keys true)})
+            (js-obj "unref" (fn [] nil))))
+    (try
+      (daemon/spawn-server! {:script "/tmp/db-worker-node.js"
+                             :repo "logseq_db_spawn_helper_test"
+                             :root-dir "/tmp/logseq-root"
+                             :create-empty-db? true})
+      (is (some #{"--create-empty-db"} (:args @captured)))
+      (finally
+        (set! (.-spawn child-process) original-spawn)))))
+
+(deftest spawn-server-omits-create-empty-db-flag-by-default
+  (let [captured (atom [])
+        original-spawn (.-spawn child-process)
+        capture! (fn [_cmd args _opts]
+                   (swap! captured conj (vec (js->clj args)))
+                   (js-obj "unref" (fn [] nil)))]
+    (set! (.-spawn child-process) capture!)
+    (try
+      (daemon/spawn-server! {:script "/tmp/db-worker-node.js"
+                             :repo "logseq_db_spawn_helper_test"
+                             :root-dir "/tmp/logseq-root"})
+      (daemon/spawn-server! {:script "/tmp/db-worker-node.js"
+                             :repo "logseq_db_spawn_helper_test"
+                             :root-dir "/tmp/logseq-root"
+                             :create-empty-db? false})
+      (is (every? (fn [args]
+                    (not-any? #{"--create-empty-db"} args))
+                  @captured))
+      (finally
+        (set! (.-spawn child-process) original-spawn)))))
+
+(deftest cleanup-stale-lock-removes-invalid-lock
+  (async done
+    (let [root-dir (node-helper/create-tmp-dir "db-worker-daemon-helper")
+          repo (str "logseq_db_helper_stale_" (subs (str (random-uuid)) 0 8))
+          path (node-path/join root-dir "db-worker.lock")
+          invalid-lock {:repo repo
+                        :pid (.-pid js/process)
+                        :host "127.0.0.1"
+                        :port 0}]
+      (fs/mkdirSync root-dir #js {:recursive true})
+      (fs/writeFileSync path (js/JSON.stringify (clj->js invalid-lock)))
+      (-> (p/let [_ (daemon/cleanup-stale-lock! path invalid-lock)]
+            (is (not (fs/existsSync path)))
+            (done))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))
+                     (done)))))))
+
+(deftest terminate-process-uses-platform-appropriate-stop-command
+  (async done
+    (let [terminate-process! (fn [pid force?]
+                               (call-private 'terminate-process! pid force?))
+          spawn-calls (atom [])
+          kill-calls (atom [])]
+      (-> ((if (= "win32" (.-platform js/process))
+             (fn [f]
+               (test-helper/with-js-property-override
+                child-process
+                "spawnSync"
+                (fn [command args opts]
+                  (swap! spawn-calls conj {:command command
+                                           :args (vec (js->clj args))
+                                           :opts (js->clj opts :keywordize-keys true)})
+                  #js {:status 0})
+                f))
+             (fn [f]
+               (test-helper/with-js-property-override
+                js/process
+                "kill"
+                (fn [pid signal]
+                  (swap! kill-calls conj [pid signal])
+                  true)
+                f)))
+           (fn []
+             (p/let [_ (terminate-process! 424242 false)
+                     _ (terminate-process! 424242 true)]
+               (if (= "win32" (.-platform js/process))
+                 (is (= [{:command "taskkill"
+                          :args ["/PID" "424242" "/T"]
+                          :opts {:windowsHide true
+                                 :stdio "ignore"}}
+                         {:command "taskkill"
+                          :args ["/PID" "424242" "/T" "/F"]
+                          :opts {:windowsHide true
+                                 :stdio "ignore"}}]
+                        @spawn-calls))
+                 (is (= [[424242 "SIGTERM"]
+                         [424242 "SIGKILL"]]
+                        @kill-calls))))))
+          (p/catch (fn [e]
+                     (is false (str "unexpected error: " e))))
+          (p/finally done)))))
+
+(deftest ready-uses-healthz-200-only
+  (async done
+    (-> (p/with-redefs [daemon/http-request (fn [{:keys [path]}]
+                                              (is (= "/healthz" path))
+                                              (p/resolved {:status 200
+                                                           :body "{\"status\":\"ready\"}"}))]
+          (daemon/ready? {:host "127.0.0.1" :port 7001}))
+        (p/then (fn [result]
+                  (is (= true result))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))))
+        (p/finally done))))
+
+(deftest healthy-treats-healthz-503-as-alive
+  (async done
+    (-> (p/with-redefs [daemon/http-request (fn [{:keys [path]}]
+                                              (is (= "/healthz" path))
+                                              (p/resolved {:status 503
+                                                           :body "{\"status\":\"starting\"}"}))]
+          (daemon/healthy? {:host "127.0.0.1" :port 7002}))
+        (p/then (fn [result]
+                  (is (= true result))))
+        (p/catch (fn [e]
+                   (is false (str "unexpected error: " e))))
+        (p/finally done))))
diff --git a/src/test/logseq/db_worker/server_list_test.cljs b/src/test/logseq/db_worker/server_list_test.cljs
new file mode 100644
index 0000000000..2f79364c82
--- /dev/null
+++ b/src/test/logseq/db_worker/server_list_test.cljs
@@ -0,0 +1,12 @@
+(ns logseq.db-worker.server-list-test
+  (:require [cljs.test :refer [deftest is]]
+            [logseq.db-worker.server-list :as server-list]))
+
+(deftest path-derives-server-list-from-root-dir
+  (is (= "/tmp/logseq-root/server-list"
+         (server-list/path "/tmp/logseq-root"))))
+
+(deftest path-rejects-missing-root-dir
+  (is (thrown-with-msg? js/Error
+                        #"root-dir is required"
+                        (server-list/path nil))))
diff --git a/src/test/logseq/outliner/page_backend_validation_test.cljs b/src/test/logseq/outliner/page_backend_validation_test.cljs
new file mode 100644
index 0000000000..2632a4c96c
--- /dev/null
+++ b/src/test/logseq/outliner/page_backend_validation_test.cljs
@@ -0,0 +1,12 @@
+(ns logseq.outliner.page-backend-validation-test
+  (:require [cljs.test :refer [deftest is]]
+            [logseq.db.test.helper :as db-test]
+            [logseq.outliner.page :as outliner-page]))
+
+(deftest create-page-rejects-hashtag-title
+  (let [conn (db-test/create-conn)]
+    (doseq [title ["foo#bar" "#tagstyle"]]
+      (is (thrown-with-msg?
+           js/Error
+           #"Page name can't include \"#\"."
+           (outliner-page/create! conn title {}))))))
diff --git a/typos.toml b/typos.toml
index 7f1350dd5f..c3f09537f7 100644
--- a/typos.toml
+++ b/typos.toml
@@ -17,6 +17,8 @@ deleteable = "deleteable"
 fom = "fom"
 tne = "tne"
 Damon = "Damon"
+Ede = "Ede"
+
 [files]
 extend-exclude = ["resources/*",
                   "src/resources/*",