README installation guide gaps — marketplace sync, daemon cleanup, version update

[pitimon]

Installation Guide Gaps from Real-World QA Experience

After upgrading from v1.3.1 → v2.0.0 → v2.0.1 on macOS, we encountered several issues not covered in the README installation guide. Here are corrections based on practical experience.

---

1. Missing: bun install must run in BOTH cache AND marketplace directories

README says:

cd ~/.claude/plugins/cache/pitimon-c-memforge/memforge-client/*/
bun install

Reality: Claude Code uses TWO paths:

• ~/.claude/plugins/cache/pitimon-c-memforge/memforge-client/<version>/ — where installed_plugins.json points (MCP server runs from here)
• ~/.claude/plugins/marketplaces/pitimon-c-memforge/ — where the plugin system reads hooks.json, plugin.json

If bun install only runs in cache, the marketplace copy may lack node_modules. Both directories need deps installed.

Suggested fix: Add to README:

# Also install deps in marketplace directory
cd ~/.claude/plugins/marketplaces/pitimon-c-memforge/
bun install

---

2. Missing: Version upgrade procedure

README has no upgrade section. In practice, upgrading requires:

1. Clone new version to cache
2. Sync cache → marketplace (this was the biggest gotcha)
3. bun install in both locations
4. Update installed_plugins.json
5. Restart Claude session (or /reload-plugins)

We hit this: updated installed_plugins.json to v2.0.1 but MCP server still ran v1.3.1 because marketplace directory wasn't updated. Required manual rsync.

Suggested fix: Add "Upgrading" section:

# After installing new version to cache:
rsync -a --delete \
  ~/.claude/plugins/cache/pitimon-c-memforge/memforge-client/<new-version>/ \
  ~/.claude/plugins/marketplaces/pitimon-c-memforge/
cd ~/.claude/plugins/marketplaces/pitimon-c-memforge/ && bun install

---

3. Stale v1.x daemon not killed on upgrade (unless bun run setup is run)

README says "setup script saves your config and cleans up legacy sync daemon files."

But if user already has ~/.memforge/config.json from v1.x, they may skip bun run setup — leaving the old db-watcher daemon running silently.

We found PID 39977 (db-watcher from v1.1.0, running since March 11) still active after upgrading to v2.0.1.

Suggested fix: Add warning:

⚠️ If upgrading from v1.x: Run `bun run setup` even if you already have a config file.
   This kills any running daemon and cleans up legacy state files.
   
   Or manually: ps aux | grep db-watcher | grep -v grep | awk '{print $2}' | xargs kill

---

4. CLAUDE.md says "15 MCP tools" — actual count is 16

.claude-plugin/CLAUDE.md line 7 says "15 MCP tools" but getAllTools() in handlers/index.ts exports 16 tools. (README correctly says 16.)

---

5. No guidance on verifying sync works after install

Users have no way to confirm that the in-process SyncPoller is actually running. Suggest adding:

# Verify v2.0.1 sync is working:
# 1. Check MCP server is from v2.0.1 (not v1.x):
ps aux | grep 'memforge.*mcp-server' | grep -v grep

# 2. Check no legacy daemon:
ps aux | grep db-watcher | grep -v grep  # should be empty

# 3. Use mem_status MCP tool — Connectivity: OK means server + sync running

---

Environment

• macOS Darwin 25.3.0, Bun 1.3.5
• Upgraded path: v1.1.0 → v1.3.1 → v2.0.0 → v2.0.1
• Issues encountered during each upgrade step

[pitimon]

Status Update

#4 (CLAUDE.md tool count) — Fixed in PR #29 (v2.0.1). CLAUDE.md now says 16 tools.

#1, #2, #3, #5 — Assigned to QA to update README based on real plugin marketplace install/upgrade experience. Dev environment uses repo directly, not plugin marketplace flow.

Notes for QA

• The cleanupLegacySync() function in scripts/setup.ts already handles Semantic/hybrid search latency 20-38s on 50k dataset - consider caching or async patterns #3 (kills daemon + removes hooks) — just needs prominent documentation
• For Add pagination support (offset/cursor) for search tools #5, mem_status tool already reports connectivity — document it as the verification step
• For config.local.json not propagated to cache directory - causes 401 on MCP server startup #1 and Snapshot tools should require admin role - not exposed to general clients #2, please verify the exact cache/marketplace paths and rsync flow on a clean install before updating README