wangchuan 5.7.0 → 5.8.0

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|")
+```