wangchuan 5.7.1 → 5.9.0

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` |

package/skill/references/install-setup.md

@@ -0,0 +1,142 @@
+# Installation, Initialization, and Key Management
+
+## Prerequisites
+
+1. Node.js >= 18
+2. Git installed and configured (SSH key or HTTPS credentials)
+3. A **private** Git repo on any hosting platform
+
+## Install CLI
+
+```bash
+npm install -g wangchuan
+```
+
+## Initialization (when `~/.wangchuan/config.json` does not exist)
+
+**IMPORTANT: Interactive mode does NOT work in agent shell (non-TTY). Always pass flags explicitly.**
+
+Ask user: brand new setup or restoring existing repo?
+
+### Scenario A — Brand new setup
+
+1. Guide user to create a **private** repo (or auto-create via `gh repo create wangchuan-sync --private`)
+2. Run: `wangchuan init --repo <url>`
+3. Auto: generates key → clones → detects agents → extracts shared resources → first sync
+4. **Remind user to back up key**: `wangchuan doctor --key-export`
+
+### Scenario B — Restore / new machine (may already have local agent data)
+
+This is a multi-step flow with a **mandatory backup checkpoint**. If the user doesn't confirm backup, **stop and do not proceed** — next time the skill is triggered, start from Step 1 again.
+
+**Step 1: Collect credentials.**
+Ask for **repo SSH URL** and **master key** (`wangchuan_<hex>`).
+
+**Step 2: Init (clone only, no sync yet).**
+```bash
+wangchuan init --repo <url> --key <key>
+```
+Init clones the repo and auto-runs a first sync. But BEFORE that happens, the agent must handle Steps 3-5 manually. Since init auto-syncs, the agent should instead do a **manual init sequence** to control the flow:
+
+Actually, `wangchuan init` auto-syncs at the end and there's no flag to skip it. So the agent must do the backup warning BEFORE running init:
+
+**Step 3: Check if local agent data exists and warn about shared resource overwrites.**
+```bash
+# Check if any agent workspace has data
+for agent_dir in ~/.claude ~/.cursor ~/.openclaw/workspace ~/.codebuddy ~/.workbuddy ~/.codex ~/.gemini; do
+  [ -d "$agent_dir" ] && echo "  ⚠️ Local data found: $agent_dir"
+done
+```
+If local data exists, **inform the user**:
+- "⚠️ **Shared skills and custom agents in the cloud will OVERWRITE your local versions** (no merge — direct copy)."
+- "Your MCP servers will be safely merged (additive)."
+- "Your memory files (CLAUDE.md, MEMORY.md) will be preserved (local wins on conflict)."
+- "Your local-only files (skills, configs not in cloud) will be auto-pushed to cloud — please review after init."
+
+**Ask user: "Have you backed up your important local skills/agents? Confirm to proceed, or cancel to back up first."**
+
+If user says **cancel/not yet** → **STOP**. Do NOT run init. Tell user:
+```
+Please back up your local data first:
+  cp -r ~/.claude/skills/ ~/backup-claude-skills/
+  cp -r ~/.claude/agents/ ~/backup-claude-agents/
+  # (repeat for other agents as needed)
+Then say "初始化忘川" again to resume.
+```
+
+If user says **confirmed** → proceed to Step 4.
+
+**Step 4: Check cloud environments and let user choose.**
+After init, check if cloud repo has multiple environments:
+```bash
+# Init first (this will clone + auto-sync to default branch)
+wangchuan init --repo <url> --key <key>
+# Then check for environments
+wangchuan env list
+```
+If multiple environments exist (e.g. `default`, `work`, `personal`):
+- List all environments to the user
+- Ask: "Which environment do you want to sync with this machine?"
+- If user picks non-default → `wangchuan env switch <chosen>` (auto-pulls that env's data)
+
+If only `default` exists → no need to ask, already synced.
+
+**Step 5: Post-init review.**
+```bash
+wangchuan status -v
+```
+Report what was synced: pulled files, pushed files, any conflicts detected. If shared skills were overwritten, inform user which ones.
+
+**Complete flow summary:**
+```
+Ask credentials → Check local data exists?
+  → Yes: warn overwrites → ask backup confirmed?
+    → No: STOP (resume next time)
+    → Yes: init → check envs → user picks env → status -v → ensure watch
+  → No: init → check envs → user picks env → ensure watch
+```
+
+## Key management
+
+```bash
+# Export key (on source machine):
+wangchuan doctor --key-export    # prints wangchuan_<hex>
+# Import key (on target machine):
+wangchuan init --repo <url> --key wangchuan_<hex>
+# Rotate key:
+wangchuan doctor --key-rotate
+# Generate setup one-liner for new machine:
+wangchuan doctor --setup
+```
+
+**`master.key` is the ONLY thing that cannot be recovered.** Back it up securely.
+
+## Key mismatch handling
+
+If `Key mismatch!` appears during sync:
+1. `wangchuan doctor --key-export` on the machine that last pushed
+2. Copy key hex to current machine
+3. `wangchuan init --key <hex>` or write to `~/.wangchuan/master.key`
+
+## Installing the skill to agents
+
+```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 sync distribute automatically:
+wangchuan sync
+```
+
+## Setting up Git repo
+
+| Platform | How |
+|----------|-----|
+| GitHub | `wangchuan init` auto-creates via `gh` CLI |
+| GitLab | gitlab.com → New project → Private |
+| Gitee | gitee.com → New repo → Private |
+| Bitbucket | bitbucket.org → Create repository → Private |
+| Gitea | Your instance → New Repository → Private |

package/skill/references/resource-crud.md

@@ -0,0 +1,153 @@
+# Resource CRUD — Skills, Custom Agents, MCP, Memory
+
+## Resource types and their mechanisms
+
+| Resource | Local path | Sharing model | Registry | Applicable agents |
+|----------|-----------|---------------|----------|-------------------|
+| **Skills** | `<workspace>/skills/<name>/` | Directory copy, shared-registry | `kind:'skill'` | OpenClaw, Claude, CodeBuddy, WorkBuddy, Gemini (5) |
+| **Custom agents** | `<workspace>/agents/<name>/` | Directory copy, shared-registry | `kind:'agent'` | Claude, Cursor, CodeBuddy, WorkBuddy (4) |
+| **MCP servers** | JSON field `mcpServers` in config file | JSON key merge, single shared file in cloud | None (auto) | Claude (`.claude.json`), OpenClaw (`config/mcporter.json`), CodeBuddy/WorkBuddy/Cursor (`mcp.json`) (5) |
+| **Memory** | `<workspace>/MEMORY.md` etc. | Per-agent file, manual copy/broadcast | None | OpenClaw/CodeBuddy/WorkBuddy/Codex (`MEMORY.md`); Claude (`CLAUDE.md`); shared (`SHARED.md`) |
+
+---
+
+## Creating or modifying skills or custom agents
+
+Skills and custom agents use the **same** flow — both are directories tracked by `shared-registry.json`.
+
+**`shared-registry.json` schema** (at `~/.wangchuan/shared-registry.json`):
+```json
+{
+  "entries": [
+    { "name": "wangchuan", "kind": "skill", "sourceAgent": "claude", "sharedAt": "2026-04-14T10:00:00Z" },
+    { "name": "my-reviewer", "kind": "agent", "sourceAgent": "claude", "sharedAt": "2026-04-14T11:00:00Z" }
+  ]
+}
+```
+- `kind`: `"skill"` or `"agent"` — determines which resource type
+- `name`: directory name (e.g. skill dir name or custom agent dir name)
+- `sourceAgent`: which agent first shared it
+- A resource is **shared** only if it has an entry here. Absent = local-only.
+
+**Step 1: Determine if the resource is already shared.**
+- **Newly created** → NOT shared (skip to Step 2b).
+- **Existing** → check `~/.wangchuan/shared-registry.json` for the name with `kind:'skill'` or `kind:'agent'`.
+
+**Step 2a: Already-shared** — distribute + sync automatically:
+```bash
+# Example: shared skill "foo" modified in claude, also used by cursor and codebuddy
+cp -r ~/.claude/skills/foo/ ~/.cursor/skills/foo/
+cp -r ~/.claude/skills/foo/ ~/.codebuddy/skills/foo/
+# Example: shared custom agent "my-reviewer" modified in claude
+cp -r ~/.claude/agents/my-reviewer/ ~/.cursor/agents/my-reviewer/
+cp -r ~/.claude/agents/my-reviewer/ ~/.codebuddy/agents/my-reviewer/
+wangchuan sync -y
+```
+
+**Step 2b: New / agent-local** — ask the user before distributing:
+```bash
+# List enabled agents for skills:
+jq -r '.profiles.default | to_entries[] | select(.value.enabled) | "\(.key) → \(.value.workspacePath)/skills/"' ~/.wangchuan/config.json
+# List enabled agents for custom agents (only 4 support them):
+for a in claude cursor codebuddy workbuddy; do
+  jq -r --arg a "$a" '.profiles.default[$a] | select(.enabled) | "\($a) → \(.workspacePath)/agents/"' ~/.wangchuan/config.json
+done
+```
+Present options:
+- **All agents** — copy to every applicable agent's dir → `wangchuan sync -y` (registers as shared)
+- **Specific agents** — copy only to selected → `wangchuan sync -y`
+- **No distribution** — keep local only → `wangchuan sync -y`
+
+---
+
+## Deleting skills or custom agents
+
+Deletion is destructive — **always ask the user** regardless of shared status.
+
+**Step 1: Determine shared status and inform the user.**
+```bash
+# For skills:
+cat ~/.wangchuan/shared-registry.json 2>/dev/null | grep -q '"name":"xxx".*"kind":"skill"' && echo "SHARED SKILL" || echo "LOCAL SKILL"
+# For custom agents:
+cat ~/.wangchuan/shared-registry.json 2>/dev/null | grep -q '"name":"xxx".*"kind":"agent"' && echo "SHARED AGENT" || echo "LOCAL AGENT"
+```
+
+**Step 2: List agents that have it and ask which to remove from.**
+```bash
+# For skills:
+for entry in $(jq -r '.profiles.default | to_entries[] | select(.value.enabled) | "\(.key)=\(.value.workspacePath)"' ~/.wangchuan/config.json); do
+  agent="${entry%%=*}"; expanded=$(echo "${entry#*=}" | sed "s|^~|$HOME|")
+  [ -d "${expanded}/skills/xxx" ] && echo "  ✓ $agent"
+done
+# For custom agents (only 4 agents support them):
+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"
+done
+```
+Options: **All agents** / **[individual agents]** / **Cancel**
+
+**Step 3: Execute.**
+
+**All agents**: `rm -rf` from every agent → unregister from shared-registry.json → `wangchuan sync -y`.
+```bash
+rm -rf ~/.claude/skills/xxx/ ~/.cursor/skills/xxx/ ~/.codebuddy/skills/xxx/  # etc.
+jq '.entries |= map(select(.name != "xxx" or .kind != "skill"))' ~/.wangchuan/shared-registry.json > /tmp/wc-sr.json && mv /tmp/wc-sr.json ~/.wangchuan/shared-registry.json
+wangchuan sync -y
+```
+
+**Specific agents**: `rm -rf` from selected → unregister (demote) → `wangchuan sync -y`. Remaining agents keep local copies.
+
+**Cancel**: no action.
+
+---
+
+## Creating, modifying, or deleting MCP servers
+
+MCP servers are JSON fields (`mcpServers`). They have **no shared registry** — wangchuan auto-merges on sync. But agent should give user control.
+
+**Creating or modifying:**
+1. Edit the current agent's MCP config file:
+   - Claude: `~/.claude/.claude.json` → `mcpServers`
+   - CodeBuddy/WorkBuddy/Cursor: `~/<workspace>/mcp.json` → `mcpServers`
+   - OpenClaw: `~/.openclaw/workspace/config/mcporter.json` → `mcpServers`
+2. Ask user: "Sync this MCP server to other agents?"
+   - **All**: write same entry to every MCP-enabled agent's config via jq
+   - **Specific**: write to selected only
+   - **No**: keep local
+3. `wangchuan sync -y`
+
+Example — add server to another agent:
+```bash
+SERVER_JSON=$(jq '.mcpServers["my-db"]' ~/.claude/.claude.json)
+jq --argjson srv "$SERVER_JSON" '.mcpServers["my-db"] = $srv' ~/.codebuddy/mcp.json > /tmp/mcp.json && mv /tmp/mcp.json ~/.codebuddy/mcp.json
+```
+
+**Deleting:**
+1. List which agents have it: `jq -e '.mcpServers["xxx"]' <file>` per agent
+2. Ask user: All / Specific / Cancel
+3. Remove via `jq 'del(.mcpServers["xxx"])'` from selected agents
+4. `wangchuan sync -y`
+
+**Note**: wangchuan's MCP auto-merge is **additive only** (never deletes keys). Agent-side `jq del()` is the only way to propagate removal.
+
+---
+
+## Creating, modifying, or deleting memory
+
+Memory files are **per-agent** — no automatic cross-agent distribution.
+
+**Creating or modifying:**
+1. Write/update memory file (e.g. `~/.claude/CLAUDE.md`)
+2. Ask user: "Sync to other agents?"
+   - **All**: `wangchuan memory broadcast <agent>` → `wangchuan sync -y`
+   - **Specific**: `wangchuan memory copy <source> <target>` → `wangchuan sync -y`
+   - **No**: `wangchuan sync -y`
+
+**Deleting:**
+1. `wangchuan memory list` to see who has what
+2. Ask user: All / Specific / Cancel
+3. `rm -f` selected agents' memory files → `wangchuan sync -y`
+
+**Note**: Memory filenames differ per agent — Claude uses `CLAUDE.md`, OpenClaw/CodeBuddy/WorkBuddy/Codex use `MEMORY.md`.

package/skill/references/sync-conflict.md

@@ -0,0 +1,69 @@
+# Pushing, Pulling, and Conflict Resolution
+
+## How sync works
+
+`wangchuan sync` is **bidirectional**: pull first, then push. `wangchuan watch` is **pull-only** — it periodically pulls cloud changes but never pushes. Users must run `wangchuan sync` manually to push local changes.
+
+Flow of `sync`: **auto-snapshot** → fetch remote → if remote ahead → git pull → three-way merge → then stage + push local changes.
+Flow of `watch`: fetch remote → if remote ahead → git pull → restore to local → record unresolved conflicts.
+
+**Note**: sync automatically creates a safety snapshot of the repo before every sync. This means you can always roll back to the pre-sync state via `wangchuan snapshot list` + `wangchuan snapshot restore`.
+
+**Environment**: all sync/push/pull operations target the **current environment's branch only** (`cfg.environment`). After sync completes, always report the current environment name to the user (e.g. "Synced to cloud (environment: work)").
+
+## Pushing memory to cloud
+
+1. **Preview** (optional): `wangchuan status -v`
+2. **Sync**: `wangchuan sync -y`
+3. **Conflict resolution** (auto for `.md` files):
+   - Non-overlapping edits → auto-merged ✅
+   - Overlapping identical edits → deduplicated ✅
+   - Overlapping conflicting edits → conflict markers written:
+     ```
+     <<<<<<< LOCAL
+     (your local changes)
+     =======
+     (cloud changes)
+     >>>>>>> REMOTE
+     ```
+4. **If conflict markers written** → read file, show conflicts to user, ask how to resolve, edit to remove markers, `wangchuan sync -y` again.
+5. **If no conflicts** → done.
+
+```bash
+# Full push flow:
+wangchuan sync -y
+# Check for conflict markers:
+grep -l '<<<<<<< LOCAL' ~/.claude/CLAUDE.md ~/.openclaw/workspace/MEMORY.md ~/.codebuddy/MEMORY.md ~/.workbuddy/MEMORY.md ~/.codex/MEMORY.md 2>/dev/null
+```
+
+## Pulling memory from cloud
+
+Same command: `wangchuan sync -y`. Use `wangchuan sync -n` for dry-run preview first.
+
+Conflict resolution is identical to pushing. Encrypted files are decrypted transparently during pull.
+
+**Pulling from a specific environment**: push/pull always targets the **current** environment's branch. To pull from a different env:
+```bash
+wangchuan env switch <target-env>   # switches branch + auto-syncs (pulls target env's data)
+# When done, switch back:
+wangchuan env switch <original-env>
+```
+There is no `--from-env` flag — must switch first.
+
+## Syncing resources between agents
+
+When user says "sync A's config to B", intent may be ambiguous.
+
+**Step 1: Clarify** — ask which resources: Memory / Skills / MCP servers / Custom agents / All.
+
+**Step 2: Execute per type:**
+- **Memory**: `wangchuan memory copy <source> <target>` → `wangchuan sync -y`
+- **Skills**: `cp -r "${SRC_WS}/skills/"* "${DST_WS}/skills/"` → `wangchuan sync -y`
+- **MCP**: read mcpServers from source, jq merge into target → `wangchuan sync -y`
+- **Custom agents**: `cp -r "${SRC_WS}/agents/"* "${DST_WS}/agents/"` → `wangchuan sync -y`
+
+Get workspace paths:
+```bash
+SRC=$(jq -r '.profiles.default.<source>.workspacePath' ~/.wangchuan/config.json | sed "s|^~|$HOME|")
+DST=$(jq -r '.profiles.default.<target>.workspacePath' ~/.wangchuan/config.json | sed "s|^~|$HOME|")
+```