docs: clarify two install paths (plugin + npm-global) with Mermaid diagram across 11 READMEs#49
Merged
Merged
Conversation
…READMEs The session-long fix today exposed a real onboarding gap: a user who runs `/plugin install memesh@pcircle-memesh` then tries `memesh reindex` in a terminal gets `command not found`. The README told them "plugin install includes the CLI" via `npx`, which is technically true but practically misleading — almost everyone wants a real `memesh` shell command, not `npx @pcircle/memesh ...` typed every time. Added a new "## Install paths at a glance" section before "Get Started" in all 11 READMEs (English canonical + 10 locales) that: 1. States the two-paths model up front: plugin (Path A) for Claude Code MCP / hooks / skill, npm-global (Path B) for shell CLI / use from Cursor / Cline / other MCP clients. Both write to the same ~/.memesh/knowledge-graph.db so memories are shared. 2. Embeds a Mermaid flowchart diagram (GitHub-native rendering) showing the two paths converging on the shared database. Same diagram across all locales — labels are English tech terms which is conventional. 3. Adds a "Which one do you need?" matrix mapping concrete user intentions to the required install path, with a clear "install both if you want all of the above" row. 4. Adds an "⚠️ Installing the plugin does NOT install the CLI" subsection that calls out the gotcha by name with the exact symptom (`zsh: command not found: memesh`) and the fix (`npm install -g @pcircle/memesh`). 5. Softens the Option A description so it no longer claims "no global install needed" without qualifying that this means CLI access requires `npx` per call — most readers expect a shell `memesh`. After: locale H2 counts go from 15 → 16 across all 10 locales (EN: 16 → 17), keeping the locale-parity check at delta = 1 (within the ±1 tolerance). `memesh doctor` reports `[PASS] README locale parity` post-change. No version bump — this is doc-only.
Multi-Model SynthesisBoth Claude and Codex reviews above are independent. The most Reviewer responsibility: read both, surface non-overlapping |
15 tasks
kevintseng
added a commit
that referenced
this pull request
May 13, 2026
…#50) (#51) * feat(doctor): add Shell CLI on PATH check — surfaces plugin-without-global gotcha (v4.2.7) The most common onboarding confusion (user hit it themselves today, README PR #49 documented it): `/plugin install memesh@pcircle-memesh` gives you MCP tools + hooks + `/memesh` skill inside Claude Code, but does NOT put `memesh` on the shell PATH. Typing `memesh reindex` in a terminal → `command not found`. New doctor check `Shell CLI on PATH` resolves `memesh` via `which` (POSIX) / `where` (Windows) and reports per install channel: - **plugin-marketplace**, no shell-PATH memesh → WARN with the exact fix (`npm install -g @pcircle/memesh`) and the clarification that both paths coexist and share `~/.memesh/knowledge-graph.db`. - **plugin-marketplace** with a separate shell-PATH memesh → PASS, names the path so the user knows where the global lives. - **npm-global** → PASS (running from the install itself, shell access available). - **source-checkout / npm-local / unknown** → informational PASS (no shell CLI is expected and `which` failing is not a real problem here). Wires through `runDoctor` like the existing `inspectNativeBinding` check, with a `resolveShellMemeshImpl` test seam so unit tests can inject success / failure paths without touching the real PATH. 4 new tests added (34 total in doctor.test.ts): - WARN on plugin-marketplace without shell PATH - PASS on plugin-marketplace with separate shell PATH - PASS on npm-global regardless of which output - informational PASS on source-checkout without shell PATH Version bumped 4.2.6 → 4.2.7 across all 7 anchor files. CHANGELOG entry added. Validation: - 34/34 doctor tests pass - npm run lint: clean - npx tsc --noEmit: clean - Manual: `memesh doctor` on this source checkout reports PASS with "/Users/.../bin/memesh (separate from this install...)" — correctly identifies the global memesh we installed earlier today. - Full test suite: 1039/1042 (same 3 pre-existing flakes — http /v1/recall, tools auto-archive, pre-bash-orchestration-nudge — confirmed unrelated to this change). * fix(cli,http,install-hooks,docs): close 5 UX gaps surfaced by E2E sweep (v4.2.7) Combined with the Shell CLI on PATH doctor check from previously-open PR #50 (cherry-picked here — superseded). Five user-visible fixes from the comprehensive E2E UX sweep: B1 — `memesh forget --confirm` is now accepted as a no-op Soft archive doesn't need a confirmation gate, but rejecting the flag as `error: unknown option '--confirm'` was hostile to users coming from `rm -i` / `git branch -D` conventions. Marked `[deprecated, no-op]` in --help. B2 — `memesh export -o <file>` flag Previously the only way to write to a file was shell redirection (`memesh export > backup.json`), undocumented in --help. Users tried `-o backup.json` first and saw `unknown option '-o'`. Added the flag with synchronous write + stderr confirmation. Stdout mode is preserved as the default (pipe-friendly). B3 — HTTP server returns JSON on unknown routes The 32 documented routes return `{success, data}` JSON, but unknown paths fell through to Express's default text/html 404 page. Clients piping responses into `JSON.parse` choked on `<!DOCTYPE html>`. Added a catch-all JSON 404 middleware: `{success: false, code: "NOT_FOUND", error: "No route for <M> <p>"}`. B4 — README upgrade-plugin.sh path includes pre-v4.2.5 fallback v4.2.6 release notes told users to run `bash ~/.claude/plugins/ cache/pcircle-memesh/memesh/<v>/scripts/upgrade-plugin.sh`, but plugin installs created before v4.2.5 don't contain this file. v4.2.3 / v4.2.4 users had no way to bootstrap the upgrade from inside their plugin. Added a fallback line pointing at the npm-global copy. README.md (EN) + README.th.md (TH already had "## Upgrading" section); 9 other locales still need that section added before they can host this fallback note — noted in CHANGELOG. B5 — `memesh install-hooks` refuses to double-wire over plugin runtime When Claude Code's plugin install is active, writing the same hooks into ~/.claude/settings.json caused every event to fire memesh's hook scripts TWICE — duplicate session-insight entities, duplicate recall injections, duplicate orchestration nudges. `installHooks()` now detects the plugin via ~/.claude/plugins/installed_plugins.json and bails with a clear message naming the install path + version, plus a `--force-over-plugin` escape hatch. Also fixed the `--dry-run` wording from past-tense "Added 7 hook entries" to future-tense "Would add 7". Plus the carried-over doctor Shell CLI on PATH check from PR #50: checks for shell-PATH `memesh` and surfaces a WARN with the exact `npm install -g @pcircle/memesh` fix when plugin-marketplace install lacks a separate global. PR #50 is now redundant — closing in favor of this PR. Validation: - 1043/1045 tests pass (same 2 pre-existing flakes — http /v1/recall, tools auto-archive — confirmed unrelated) - 7 new tests added: 3 install-hooks (plugin-runtime detect + force + no-memesh-entry) + 4 doctor (carried from PR #50) - npm run lint: clean - npx tsc --noEmit: clean - memesh doctor: Overall PASS_WITH_CONCERNS (only WARN is vector_index, unrelated) - All 5 fixes verified live end-to-end after build Version bump 4.2.6 → 4.2.7. CHANGELOG entry documents all 7 surfaces.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Real onboarding gap surfaced today: a user who runs
/plugin install memesh@pcircle-memeshthen typesmemesh reindexin a terminal getscommand not found. The old README claimed "plugin includes CLI" vianpx, which is technically true but practically misleading — almost everyone wants a realmemeshshell command.This PR adds a new
## Install paths at a glancesection before## Get Startedin all 11 READMEs (English canonical + 10 locales):~/.memesh/knowledge-graph.db. GitHub renders this natively. Same diagram in every locale (labels are English tech terms — conventional).⚠️ Installing the plugin does NOT install the CLIsubsection that calls out the gotcha by name with the exact symptom + fix.npxis a complete substitute for a shellmemeshcommand.Heading counts: EN 16 → 17, all 10 locales 15 → 16. Locale-parity delta = 1, within tolerance.
Docs synced
npm run build) since README files are not in the manifest but the build step still ran cleanlymemesh doctorreports Overall: PASS_WITH_CONCERNS;[PASS] README locale paritypost-changeTest plan
memesh doctor→[PASS] README locale paritynpm run buildclean (smoke 6/6)