wangchuan 5.7.0 → 5.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wangchuan",
-  "version": "5.7.0",
+  "version": "5.8.0",
   "description": "忘川 · AI 记忆同步系统 — 智能体记忆永不遗失",
   "bin": {
     "wangchuan": "./dist/bin/wangchuan.js"

package/skill/SKILL.md

@@ -1,239 +1,113 @@
+---
+name: wangchuan
+version: 1.4.0
+description: >-
+  Encrypt and sync AI agent configs, memories, skills, and MCP servers across environments via a private Git repo.
+  Supports Claude, OpenClaw, Gemini, CodeBuddy, WorkBuddy, Cursor, and Codex.
+  TRIGGER when: user mentions syncing AI memories/configs, wangchuan/忘川, cross-machine agent setup, backup/restore agent settings, memory sync, skill distribution, MCP server sync, agent migration, master key export, sync status, watch daemon, environment management, snapshot, pushing/pulling memories, conflict resolution, syncing between agents, rolling back/restoring versions, switching environments, health check, customizing agent paths, or any commands: init, sync, status, watch, doctor, memory, env, snapshot, lang.
+  Triggers: 忘川、wangchuan、同步记忆、同步配置、同步技能、同步MCP、初始化忘川、备份记忆、恢复记忆、迁移agent、导出密钥、轮换密钥、同步状态、健康检查、多环境、快照、跨机器同步、agent记忆、配置路径、查看技能、删除技能、新增技能、修改技能、自定义agent、MCP服务器、新增MCP、删除MCP、修改MCP、查看MCP、写记忆、删除记忆、修改记忆、查看记忆、广播记忆、复制记忆、推送记忆、拉取记忆、同步到agent、冲突、合并记忆、回退记忆、回滚、恢复版本、切换环境、忘川状态、新建环境、删除环境、查看环境、切换语言、sync memories、push memory、pull memory、rollback、switch environment、custom agent、MCP server、health status、rotate key、switch language.
+  DO NOT TRIGGER when: general git operations, unrelated CLI tools, or AI model APIs.
+---
+
 # wangchuan — AI Agent Memory Sync Skill
 
-## Overview
+## Quick Start
 
-OpenClaw Skill wrapper for the Wangchuan AI memory sync system. Invoke directly in conversation to sync AI agent configs — memories never lost across environments.
+```bash
+command -v wangchuan || npm install -g wangchuan
+```
+If `~/.wangchuan/config.json` does not exist → Read [references/install-setup.md](references/install-setup.md) for initialization guide.
 
 ## Command Reference
 
 ```
-wangchuan init     [--repo <url>] [--key <path>]           One-time setup — auto-detects agents, offers gh repo create, runs first sync
-wangchuan sync     [-a, --agent <name>] [-n, --dry-run]    Smart bidirectional sync (THE daily command)
-                   [-o, --only <patterns...>]              Filter: only sync files matching patterns
-                   [-x, --exclude <patterns...>]           Filter: exclude files matching patterns
-wangchuan status   [-v, --verbose]                         One-screen summary + health score
-wangchuan watch    [-i, --interval <min>]                  Background daemon for continuous sync
-wangchuan doctor   [--key-export|--key-rotate|--setup]     Diagnose + auto-fix everything
-wangchuan memory   list|show|copy|broadcast                Browse/copy memories between agents
-wangchuan env      list|create|switch|current|delete       Multi-environment management
-wangchuan snapshot save|list|restore|delete [name]         Manage sync snapshots
-wangchuan lang     [zh|en]                                 Switch CLI display language
+wangchuan init     [--repo <url>] [--key <path>]           One-time setup
+wangchuan sync     [-a <agent>] [-n] [-o <pat>] [-x <pat>] Smart bidirectional sync
+wangchuan status   [-v]                                     Health + diff summary
+wangchuan watch    [-i <min>]                               Pull-only background daemon
+wangchuan doctor   [--key-export|--key-rotate|--setup]      Diagnose + auto-fix
+wangchuan memory   list|show|copy|broadcast [-a <agent>]    Memory management
+wangchuan env      list|create|switch|current|delete        Multi-environment
+wangchuan snapshot save|list|restore|delete [name]          Snapshots
+wangchuan lang     [zh|en]                                  Display language
 ```
+Aliases: `sync`→`s`, `status`→`st`, `snapshot`→`snap`. All support `--agent` / `-a` filter.
 
-Aliases: `sync` → `s`, `status` → `st`, `snapshot` → `snap`
-
-## Invocation Examples
-
-> Sync my AI memories
-
-> Check sync status
-
-> Show full sync status with file list and diff
-
-> Sync claude configs only
-
-> Run a health check and fix any issues
-
-> Export my master key for migration
-
-> Generate a setup command for my new laptop
-
-> Create a work environment
-
-> Switch to work environment
-
-> Start continuous background sync
-
-> List memories from all agents
-
-> Copy openclaw memory to claude
-
-> Broadcast a memory to all agents
-
-> Save a snapshot before making changes
+## Task Routing — Load the right reference BEFORE acting
 
-> Restore the last snapshot
+| User intent | Read this reference first |
+|-------------|--------------------------|
+| Create/modify/delete skills, custom agents, MCP, or memory | [references/resource-crud.md](references/resource-crud.md) |
+| Push/pull memories, resolve conflicts, sync between agents | [references/sync-conflict.md](references/sync-conflict.md) |
+| Switch/create/list/delete environments, rollback, snapshots | [references/environment.md](references/environment.md) |
+| Inspect/check skills, agents, MCP, memory, or health status | [references/inspect-status.md](references/inspect-status.md) |
+| Initialize wangchuan, install, migrate key, new machine setup | [references/install-setup.md](references/install-setup.md) |
 
-> Switch to English output
+**IMPORTANT**: Before executing any task below, **Read the corresponding reference file** for detailed instructions, bash commands, and decision flows. The reference files contain the complete procedures.
 
-## Output Guide
+## Non-TTY Constraints (Agent shell)
 
-### status (default)
-- Health score bar (0-100)
-- Changed files count since last sync
-- Last sync timestamp
-- Hint: `wangchuan sync` to update
+| Command | Constraint | Required |
+|---------|-----------|----------|
+| `wangchuan init` | Interactive prompt fails | Must pass `--repo <url>` |
+| `wangchuan sync` | Pending confirmations skipped | Must pass `-y` |
+| `wangchuan env create` | Memory import prompt fails | Auto-forks (OK) |
 
-### status --verbose
-- Full file inventory with local/repo presence
-- Line-level diff for changed files
-- Recent sync history
-- Per-agent health breakdown
+## Customizing Agent Workspace Paths
 
-### sync
-- Auto-creates safety snapshot before syncing
-- Pulls remote changes if any, then pushes local changes
-- Shows compact summary with files synced count
-- `--only` / `--exclude` for fine-grained file filtering (stale detection auto-skipped when filters active)
-
-### snapshot
-- `save [name]` — save a named snapshot (auto-named if omitted)
-- `list` — show all saved snapshots with timestamps
-- `restore <name>` — roll back to a previous snapshot
-- `delete <name>` — remove a snapshot
-
-### watch
-- Runs as a background daemon with configurable interval
-- Auto-syncs on detected file changes
-- PID file at `~/.wangchuan/watch.pid`
-
-### doctor
-- Auto-fixes all common issues (no --fix needed)
-- Auto-discovers installed agents and enables them
-- Detects stale/phantom files
-- `--key-export` / `--key-rotate` for key management
-- Validates key fingerprint against repo — detects wrong master.key before sync
-- `--setup` generates migration one-liner
-
-**Key mismatch error handling**: If `⛔ Key mismatch!` appears during sync, the local `master.key` does not match the repo. Guide the user to:
-1. Run `wangchuan doctor --key-export` on the machine that last pushed
-2. Copy the key hex to the current machine
-3. Run `wangchuan init --key <hex>` or write to `~/.wangchuan/master.key`
-
-### memory
-- `list` — show all agent memories with summaries
-- `show <agent>` — list all files when no filename given; fuzzy/substring matching with suggestions on mismatch
-- `copy <from> <to>` — copy memory between agents
-- `broadcast <agent>` — distribute memory to all agents
-
-## --agent Filter
-
-Supported by: `sync`, `status`, `watch`, `memory`.
-
-| Value | Description |
-|-------|-------------|
-| `openclaw`  | MEMORY.md (enc), AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md (enc), HEARTBEAT.md, BOOTSTRAP.md, memory/ (enc), openclaw.json → agents/skills/ui (enc), skills/ |
-| `claude`    | CLAUDE.md, settings.json (enc), .claude.json → mcpServers (enc), commands/ (dir), plugins/ (installed + marketplaces) |
-| `gemini`    | settings.internal.json → security + model + general (enc), skills/ (dir) |
-| `codebuddy` | MEMORY.md (enc), CODEBUDDY.md, mcp.json → mcpServers (enc), settings.json → enabledPlugins + hooks (enc), plugins/ (marketplaces) |
-| `workbuddy` | MEMORY.md (enc), IDENTITY.md, SOUL.md, USER.md (enc), BOOTSTRAP.md, mcp.json → mcpServers (enc), settings.json → enabledPlugins + hooks (enc), skills/ (dir), extensions/ |
-| `cursor`    | rules/ dir, mcp.json → mcpServers (enc), cli-config.json → permissions + model + enabledPlugins (enc), extensions/, hooks.json |
-| `codex`     | MEMORY.md (enc), instructions.md, config.toml (enc), skills/ (dir), memories/ (enc) |
-
-When omitted, operates on all enabled agents plus the shared tier (skills/MCP/custom agents/shared memory).
-
-## Custom Sub-Agent Sync
-
-Custom sub-agents defined in the `agents/` directory of any supported agent (Claude, Cursor, CodeBuddy, WorkBuddy) are automatically synced across all agents via the shared tier (`shared/agents/`). The same deletion confirmation logic as skills applies — a custom agent is pruned from the repo only when all local agents have removed it.
-
-## Dynamic Agent Registration
-
-Custom agents can be registered at runtime via the `customAgents` field in `config.json`, without recompilation. Custom agents participate in sync identically to built-in agents and support all three entry types (`syncFiles`, `syncDirs`, `jsonFields`).
-
-## Sync Protocol for AI Agents (IMPORTANT — all agents must follow)
-
-When this skill is loaded by an AI agent, the agent MUST follow these rules:
-
-### After modifying skills or custom agents
-If you (the AI agent) create, modify, or delete any file under your `skills/` or `agents/` directory, you MUST immediately run:
+Default paths are in `~/.wangchuan/config.json`. To change (e.g. Claude to `~/.claude-internal`):
 ```bash
-wangchuan sync
+jq '.profiles.default.claude.workspacePath = "~/.claude-internal"' ~/.wangchuan/config.json > /tmp/wc-cfg.json && mv /tmp/wc-cfg.json ~/.wangchuan/config.json
+wangchuan sync -y
 ```
-This triggers cross-agent distribution with user confirmation — the user chooses which other agents receive the change.
 
-### After modifying memory or config
-If you update MEMORY.md, CLAUDE.md, settings.json, or any synced config file, run `wangchuan sync` to push changes to the cloud.
+## Sync Protocol — Rules agents MUST follow
 
 ### On session start
-Check if the watch daemon is running. If not, suggest starting it:
 ```bash
-wangchuan watch
+wangchuan status
+wangchuan sync -y   # process pending actions
 ```
-The watch daemon auto-detects file changes and triggers sync, serving as a safety net when the agent forgets to sync manually.
-
-### Rule summary
-| Event | Action |
-|-------|--------|
-| Created/modified/deleted a skill | Run `wangchuan sync` immediately |
-| Created/modified/deleted a custom agent | Run `wangchuan sync` immediately |
-| Updated memory or config | Run `wangchuan sync` |
-| Session start | Check `wangchuan status`, suggest `wangchuan watch` if not running |
-
-## Prerequisites
-
-1. Node.js ≥ 18
-2. Git installed and configured (SSH key or HTTPS credentials)
-3. A **private** Git repo on any hosting platform (GitHub, GitLab, Gitee, Bitbucket, Gitea, or self-hosted)
-
-## Installation
-
-### Install wangchuan CLI
-
-```bash
-npm install -g wangchuan
-```
-
-### First-time setup
 
+### After EVERY skill invocation (mandatory)
+After completing any user instruction, check if the watch daemon is running and start it if not:
 ```bash
-# Interactive — auto-detects installed agents, creates repo via GitHub CLI if available
-wangchuan init
-
-# Or specify a repo URL directly (any Git hosting):
-wangchuan init --repo git@github.com:you/brain.git
-wangchuan init --repo git@gitlab.com:you/brain.git
-wangchuan init --repo git@gitee.com:you/brain.git
+# Check if watch is running, start if not (pull-only daemon)
+pgrep -f 'wangchuan.*watch' >/dev/null 2>&1 || nohup wangchuan watch >/dev/null 2>&1 &
 ```
+This ensures cloud memories are always pulled in the background. Watch is pull-only — it never pushes.
 
-### Install this skill to an agent
-
-Copy the `wangchuan/` skill folder to your agent's skills directory:
-
-```bash
-# Claude
-cp -r wangchuan/ ~/.claude/skills/wangchuan/
-
-# OpenClaw
-cp -r wangchuan/ ~/.openclaw/workspace/skills/wangchuan/
-
-# Codex
-cp -r wangchuan/ ~/.codex/skills/wangchuan/
-
-# Or let wangchuan sync distribute it to all agents automatically:
-wangchuan sync
-```
-
-### Setting up Git repo (if you don't have one)
-
-Create a **private** repo on your preferred platform:
-
-| Platform | How to create |
-|----------|--------------|
-| **GitHub** | `wangchuan init` auto-creates via `gh` CLI, or: github.com → New repository → Private |
-| **GitLab** | gitlab.com → New project → Private |
-| **Gitee** | gitee.com → New repo → Private |
-| **Bitbucket** | bitbucket.org → Create repository → Private |
-| **Gitea** | Your instance → New Repository → Private |
-
-Then: `wangchuan init --repo <ssh-url>`
-
-### New machine setup
-
-```bash
-npm install -g wangchuan
-wangchuan init --repo <your-repo-url> --key <master-key-hex>
-```
-
-Get the master key from your original machine: `wangchuan doctor --key-export`
-
-### Migrating the master key
-
-⚠️ **`master.key` is the ONLY thing that cannot be recovered.** Back it up securely.
-
-```bash
-# On the source machine:
-wangchuan doctor --key-export    # prints wangchuan_<hex>
+### Rule summary
 
-# On the target machine:
-wangchuan init --repo <url> --key wangchuan_<hex>
-```
+| Event | Action |
+|-------|--------|
+| Created/modified a **shared** skill or custom agent | Copy to all other agents → `wangchuan sync -y` |
+| Created/modified a **new/local** skill or custom agent | Ask user which agents → copy → `wangchuan sync -y` |
+| **Deleted** a skill or custom agent | **Always ask** → inform shared status → remove selected → `wangchuan sync -y` |
+| Created/modified an **MCP server** | Ask user which agents → jq write → `wangchuan sync -y` |
+| **Deleted** an MCP server | Ask user which agents → jq del → `wangchuan sync -y` |
+| Created/modified **memory** | Ask user → broadcast/copy if yes → `wangchuan sync -y` |
+| **Deleted** memory | Ask user which agents → rm → `wangchuan sync -y` |
+| Updated other config | `wangchuan sync -y` |
+| **Any skill invocation completes** | **Ensure watch daemon is running** (see above) |
+
+### Environment awareness
+
+All push/pull/watch operations target the **current environment's branch only**. Key rules:
+- **Push/pull**: always bound to `cfg.environment` → the current env's git branch
+- **Watch**: pulls from current env only. After `env switch`, restart watch
+- **Cross-env access**: NOT supported — must `env switch` first, then sync
+- **Workspace leakage**: switching env does NOT delete local files from the previous env. After switch, stale files from old env may remain in `~/.claude/skills/` etc. Do NOT push these to the new env — run `wangchuan status -v` to check `localOnly` files first
+- **Pull from another env**: if user asks "pull work env's memory", must switch first: `wangchuan env switch work` → auto-syncs
+
+### --agent filter values
+
+| Agent | Key synced files |
+|-------|-----------------|
+| `openclaw` | MEMORY.md (enc), AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md (enc), memory/ (enc), skills/ |
+| `claude` | CLAUDE.md, settings.json (enc), .claude.json→mcpServers (enc), commands/, plugins/ |
+| `gemini` | settings.internal.json→security+model+general (enc), skills/ |
+| `codebuddy` | MEMORY.md (enc), CODEBUDDY.md, mcp.json→mcpServers (enc), settings.json→enabledPlugins (enc), plugins/ |
+| `workbuddy` | MEMORY.md (enc), IDENTITY.md, SOUL.md, USER.md (enc), mcp.json→mcpServers (enc), skills/, extensions/ |
+| `cursor` | rules/, mcp.json→mcpServers (enc), cli-config.json→permissions+model (enc), extensions/ |
+| `codex` | MEMORY.md (enc), instructions.md, config.toml (enc), skills/, memories/ (enc) |

package/skill/references/environment.md

@@ -0,0 +1,198 @@
+# Environment Management, Rollback, and Snapshots
+
+## Environment basics
+
+Environments map to git branches: `default` → `main`, `<name>` → `env/<name>`.
+
+**Critical: isolation model.** Environments are **Git-branch-only isolation**. The local workspace (`~/.claude/`, `~/.cursor/`, etc.) is a **single shared copy** across all environments. Switching env = switch branch + overwrite local from new branch. But pull **never deletes** local files — files from the old env may remain as "leakage".
+
+### Impact on all operations
+
+| Operation | Environment behavior |
+|-----------|---------------------|
+| `sync` (push/pull) | Always targets current env's branch. Cannot push to or pull from another env. |
+| `watch` | Pulls from current env only. After `env switch`, **must restart watch**. |
+| Skill/agent/MCP CRUD | Changes apply to local workspace, pushed to current env's branch on sync. |
+| `memory copy/broadcast` | Operates on local workspace files (shared). Pushed to current env on sync. |
+| After `env switch` | Old env's local files may linger. Check `wangchuan status -v` for `localOnly` files before pushing — do NOT blindly push stale files to the new env. |
+| Pull from another env | Must `env switch <target>` first. No `--from-env` flag exists. |
+
+## Listing environments (指令 26)
+
+When user says "查看忘川环境列表" / "list environments":
+
+```bash
+# List all environments
+wangchuan env list
+```
+
+For per-environment health, iterate branches and check sync metadata:
+```bash
+# For each environment, check active machines and health
+cd ~/.wangchuan/repo
+for branch in $(git branch -r --list 'origin/env/*' | sed 's|origin/||'); do
+  env_name=$(echo "$branch" | sed 's|env/||')
+  echo "=== Environment: $env_name ==="
+  # Count active machines from recent commits on that branch
+  git log "origin/$branch" --oneline -20 --format="%s" | grep -oP '\[([^\]]+)\]$' | sort -u | wc -l | xargs -I{} echo "  Active machines: {}"
+  # Check last sync time
+  git log "origin/$branch" --oneline -1 --format="%ci" | xargs -I{} echo "  Last sync: {}"
+done
+# Also check default branch
+echo "=== Environment: default ==="
+git log origin/main --oneline -20 --format="%s" | grep -oP '\[([^\]]+)\]$' | sort -u | wc -l | xargs -I{} echo "  Active machines: {}"
+```
+
+For detailed health of a specific environment, switch to it and run `wangchuan status -v` (see inspect-status.md).
+
+## Current environment (指令 27)
+
+When user says "看下忘川当前环境" / "which environment am I in":
+
+```bash
+wangchuan env current
+wangchuan status -v
+```
+
+Report: environment name, active machines count, health score, unsynced files, anomalies.
+
+## Creating a new environment (指令 28)
+
+When user says "新建忘川 xxx 环境" / "create xxx environment":
+
+**Step 1: Check if environment already exists.**
+```bash
+wangchuan env list
+```
+If the name already exists, inform the user and ask: "Environment 'xxx' already exists. Switch to it instead?"
+
+**Step 2: Ask about data initialization.**
+Ask the user which option they prefer:
+- **Fork current environment** (recommended for most cases) — the new env starts with a complete copy of the current env's memories, skills, MCP, agents, and configs. This is the default.
+- **Start empty** — the new env starts with no data. Note: `env create` in non-TTY mode auto-forks; to create a truly empty env, the agent must create the branch manually and make an empty initial commit.
+
+**Step 3: Create.**
+```bash
+# Fork current env (default, works in non-TTY):
+wangchuan env create <name>
+
+# To create from a specific existing env instead of current:
+wangchuan env switch <source-env>       # switch to source first
+wangchuan env create <name>             # fork from it
+wangchuan env switch <name>             # switch to the new env
+```
+
+**Step 4: Confirm and report.**
+After creation, the user is still on the **original** environment. Ask if they want to switch to the new one:
+```bash
+wangchuan env switch <name>
+```
+
+`env create` in non-TTY mode auto-forks with memories (no interactive prompt needed). To create an empty environment, there is no flag — the fork behavior is the default. If user explicitly wants empty, agent would need to create the branch manually.
+
+## Deleting an environment (指令 29)
+
+When user says "删除忘川 xxx 环境" / "delete xxx environment":
+
+**Step 1: Confirm with user.**
+Ask: "Are you sure you want to delete environment 'xxx'? This removes the cloud branch and all its history."
+
+**Step 2: Check constraints.**
+- Cannot delete `default` environment
+- Cannot delete the currently active environment (must switch first)
+
+**Step 3: Execute.**
+```bash
+wangchuan env delete <name>
+```
+
+**Important**: `env delete` only removes the git branch. Local workspace files are NOT affected — they belong to whatever environment is currently active. Cloud data for that environment is permanently gone.
+
+## Switching environments
+
+When user says "切换到 xxx 环境" / "switch to work environment":
+
+**Step 1: Check for unsynced local changes BEFORE switching.**
+```bash
+wangchuan status
+```
+- **Few changes (≤3 files)**: warn briefly, push first: `wangchuan sync -y`
+- **Many changes or conflicts**: `wangchuan status -v` → show diff → ask "Push current changes first, or discard and switch?"
+
+**Step 2: Switch.**
+```bash
+wangchuan env switch <name>
+```
+Auto-switches branch, updates config, runs sync to pull target env's data.
+
+**Step 3: Post-switch checks.**
+
+Check for conflict markers:
+```bash
+grep -rl '<<<<<<< LOCAL' ~/.claude/ ~/.openclaw/workspace/ ~/.codebuddy/ ~/.workbuddy/ ~/.codex/ 2>/dev/null
+```
+- No conflicts → success
+- Conflicts → show to user, resolve
+
+Check for stale files from previous env (workspace leakage):
+```bash
+wangchuan status -v   # look for "localOnly" files — these are from the old env
+```
+Warn user: "These files exist locally but not in the new environment. Do NOT push them unless you intentionally want to bring them into this env."
+
+**Step 4: Restart watch daemon** (watch only pulls from current env's branch):
+```bash
+pkill -f 'wangchuan.*watch' 2>/dev/null; nohup wangchuan watch >/dev/null 2>&1 &
+```
+Watch mode **only pulls** cloud changes — it does NOT push local changes. Users must run `wangchuan sync` manually to push. If watch encounters a conflict it cannot auto-merge, it records it to `~/.wangchuan/pending-conflicts.json` — the next `wangchuan sync` will display these conflicts for user resolution.
+
+**Step 5: If user asked "pull memory from env X" without switching:**
+Explain that cross-env pull is not supported — must switch first:
+```bash
+wangchuan env switch <target-env>   # switch → auto-pulls target env's data
+# After done, switch back:
+wangchuan env switch <original-env>
+```
+
+## Rolling back (snapshots and git history)
+
+When user says "回退记忆" / "rollback" / "restore a previous version":
+
+**Step 1: Identify target.** Ask user's intent:
+- **Undo last sync** → find auto-snapshot
+- **Specific time** → `wangchuan snapshot list`
+- **Recover deleted file** → `cd ~/.wangchuan/repo && git log --oneline --name-status -20`
+- **Revert specific change** → `git log` + `git show <hash> --stat`
+
+**Step 2: Find version.**
+
+Option A — Snapshot:
+```bash
+wangchuan snapshot list
+```
+
+Option B — Git history:
+```bash
+cd ~/.wangchuan/repo && git log --oneline --name-status -20
+cd ~/.wangchuan/repo && git show <hash> --stat
+cd ~/.wangchuan/repo && git show <hash>:<file-path>
+```
+
+**Step 3: Execute.**
+
+Snapshot restore (auto-pushes to cloud):
+```bash
+wangchuan snapshot restore <name>
+```
+
+Single file from git (needs sync after):
+```bash
+cd ~/.wangchuan/repo && git checkout <hash> -- <file-path>
+wangchuan sync -y
+```
+
+Undo last sync:
+```bash
+wangchuan snapshot list  # find pre-sync auto-snapshot (second most recent)
+wangchuan snapshot restore <pre-sync-snapshot>
+```

package/skill/references/inspect-status.md

@@ -0,0 +1,90 @@
+# Inspecting Resources and Status
+
+## Inspecting a skill
+
+Report three things:
+```bash
+# 1. Which agents have it:
+for entry in $(jq -r '.profiles.default | to_entries[] | select(.value.enabled) | "\(.key)=\(.value.workspacePath)"' ~/.wangchuan/config.json); do
+  agent="${entry%%=*}"; wspath="${entry#*=}"
+  expanded=$(echo "$wspath" | sed "s|^~|$HOME|")
+  [ -d "${expanded}/skills/xxx" ] && echo "  ✓ $agent" || echo "  ✗ $agent"
+done
+# 2. Shared or local:
+cat ~/.wangchuan/shared-registry.json 2>/dev/null | grep -q '"name":"xxx".*"kind":"skill"' && echo "SHARED" || echo "LOCAL"
+# 3. Cloud sync:
+[ -d ~/.wangchuan/repo/shared/skills/xxx ] && echo "Synced to cloud" || echo "Not in cloud"
+```
+
+## Inspecting a custom agent
+
+Same pattern, but only Claude, Cursor, CodeBuddy, WorkBuddy support custom agents.
+```bash
+for a in claude cursor codebuddy workbuddy; do
+  wspath=$(jq -r ".profiles.default.${a}.workspacePath" ~/.wangchuan/config.json)
+  expanded=$(echo "$wspath" | sed "s|^~|$HOME|")
+  [ -d "${expanded}/agents/xxx" ] && echo "  ✓ $a" || echo "  ✗ $a"
+done
+cat ~/.wangchuan/shared-registry.json 2>/dev/null | grep -q '"name":"xxx".*"kind":"agent"' && echo "SHARED" || echo "LOCAL"
+[ -d ~/.wangchuan/repo/shared/agents/xxx ] && echo "Synced to cloud" || echo "Not in cloud"
+```
+
+## Inspecting MCP servers
+
+MCP configs are JSON fields. Agents with MCP: Claude, OpenClaw, CodeBuddy, WorkBuddy, Cursor.
+```bash
+# List servers per agent:
+jq -r '.mcpServers // {} | keys[]' ~/.claude/.claude.json 2>/dev/null | sed 's/^/  claude: /'
+jq -r '.mcpServers // {} | keys[]' ~/.codebuddy/mcp.json 2>/dev/null | sed 's/^/  codebuddy: /'
+# (repeat for workbuddy, cursor with mcp.json; openclaw with config/mcporter.json)
+```
+MCP has **no shared registry** — it uses a single merged file in the cloud (`shared/mcp/mcpServers.json.enc`). On each sync, all agents' MCP servers are merged into one superset and distributed to all agents locally. Report which agents have a given server, compare config values.
+
+## Inspecting memory
+
+```bash
+# 1. List all agents' memory files:
+wangchuan memory list
+# 2. Show specific agent's memory:
+wangchuan memory show <agent>
+# 3. Shared memory status:
+expanded=$(echo "~/.openclaw/workspace/memory/SHARED.md" | sed "s|^~|$HOME|")
+[ -f "$expanded" ] && echo "✓ Shared memory exists" || echo "✗ No shared memory"
+[ -f ~/.wangchuan/repo/shared/memory/SHARED.md.enc ] && echo "✓ Synced to cloud" || echo "✗ Not in cloud"
+# 4. Per-agent cloud sync:
+for a in openclaw codebuddy workbuddy codex; do
+  [ -f ~/.wangchuan/repo/agents/${a}/MEMORY.md.enc ] && echo "  ✓ $a synced" || echo "  ✗ $a not synced"
+done
+[ -f ~/.wangchuan/repo/agents/claude/CLAUDE.md ] && echo "  ✓ claude synced" || echo "  ✗ claude not synced"
+```
+
+## Status diagnostic (wangchuan status)
+
+### Compact view: `wangchuan status`
+- Health score (0–100), 4 dimensions: freshness / coverage / integrity / encryption
+- Current environment and branch
+- Changed files count (+added, ~modified, -missing)
+- Last sync timestamp, pending actions
+
+### Verbose view: `wangchuan status -v`
+All of compact, plus:
+- 4 health sub-scores with explanations
+- File inventory per-agent (local ✔/✖, repo ✔/·, [enc], [field])
+- Line-level diff per modified file
+- Active machines (from git commit `[hostname]`)
+- Recent 3 git commits
+- Sync history (last 5 events)
+- Conflict detection (local+remote both changed)
+- Sync lock warnings
+
+### Interpreting health issues
+
+| Symptom | Meaning | Fix |
+|---------|---------|-----|
+| Freshness low | Haven't synced recently | `wangchuan sync -y` |
+| Coverage low | Local files missing | `wangchuan sync -y` (pull restores) |
+| Integrity low | Checksums mismatch | `wangchuan doctor` |
+| Encryption low | Sensitive files unencrypted | Review config profiles |
+| Conflict warning | Local+remote both changed | `wangchuan sync -y` → resolve markers |
+| Stale sync lock | Previous sync crashed | `wangchuan doctor` |
+| Pending distributions | Unprocessed sharing | `wangchuan sync -y` |