From e526e671c06547351c8e3a63dc9e75d1ba80481e Mon Sep 17 00:00:00 2001 From: alifsayalee Date: Thu, 30 Jul 2026 18:09:10 +0500 Subject: [PATCH] docs: fix five README gaps found in the macOS pass The CLI behaves correctly in every case; only the docs were wrong or incomplete. Found while validating context-plugins@0.4.1 on macOS. - The `doctor` sample output hardcoded the Linux VS Code user directory. Label the block as Linux and add a per-platform path table, so a macOS or Windows user does not read a different path as misconfiguration. - Add the `-h`/`--help` and `-v`/`--version` rows missing from the options table. (`--long` was already added in ad869e2.) - "Node.js 18 or newer. That is the whole list." contradicted the troubleshooting table: the Claude Code leg also needs the `claude` CLI on `PATH`, and its absence silently skips that assistant. State each target's own prerequisite instead. - Mention `/reload-plugins`, which the CLI already offers after an install, rather than only pointing at a full relaunch. - Detection keys off the assistant's config directory, not whether it is installed, which is the root cause of the false positive in #24. Say so. Refs apimatic/contextmatic-crawler#42, apimatic/contextmatic-crawler#24 Co-Authored-By: Claude Opus 5 --- README.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b994c41..a139085 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,10 @@ installed are skipped. Nothing is installed globally; `npx` runs the CLI from a ## Requirements -- **Node.js 18 or newer.** That's the whole list. +- **Node.js 18 or newer** — the only requirement for the CLI itself. +- **At least one assistant.** Each has its own prerequisite: Claude Code needs the `claude` CLI on + `PATH`, Cursor needs `~/.cursor`, VS Code needs its user directory. Missing ones are skipped, so + an install succeeds as long as one is present. - `git` is optional — it makes fetching faster; without it the CLI uses the GitHub API instead. ## Commands @@ -45,6 +48,8 @@ context-plugins doctor # check this machine can install | `--long` | off | Show plugin descriptions in `list` | | `--json` | off | Machine-readable output for `list` / `installed` | | `--verbose` / `--quiet` | off | More or less progress detail | +| `-h`, `--help` | — | Show usage and exit | +| `-v`, `--version` | — | Print the version and exit | Environment equivalents: `CP_PLUGIN`, `CP_REPO`, `CP_REF`, `CP_MARKETPLACE`. `GITHUB_TOKEN` raises the GitHub API rate limit. `CP_STATE_DIR` moves the state directory. @@ -58,7 +63,7 @@ directory: ## Choosing where to install -`install` detects which assistants are present and asks before touching each one: +`install` looks for each assistant and asks before touching the ones it finds: ``` [Harnesses] @@ -71,6 +76,11 @@ Only the ones you accept are installed. Assistants that aren't detected are neve the plugin is downloaded *after* you answer — decline everything and nothing is fetched, written, or recorded. +Detection is a directory check, not a true install check: Claude Code is found by looking for the +`claude` CLI on `PATH`, but Cursor and VS Code are found by the presence of their user directories. +A leftover directory from an uninstalled editor still counts as present, and an editor that has +never been launched may not be found yet. + The question is skipped when the answer is already known: with `--targets`, with `-y`, during `update` (which reuses your earlier choices), and in a non-interactive shell such as CI, where it falls back to every detected assistant rather than waiting on input. @@ -86,7 +96,8 @@ falls back to every detected assistant rather than waiting on input. Everything is installed for the current user, so it is available in every project you open. After installing, reload the editor: `Ctrl+Shift+P` (`Cmd+Shift+P`) → **Developer: Reload Window**. -Claude Code picks up skills on next launch. +In Claude Code, run `/reload-plugins` to load the plugin without restarting — or start a new +`claude` session. `settings.json` is edited as text and never reparsed, so comments and trailing commas survive — and it is backed up to `settings.json.bak-` before any change. @@ -105,7 +116,7 @@ and it is backed up to `settings.json.bak-` before any change. ``` $ npx context-plugins doctor -# example output - versions, paths, and counts will differ on your machine +# example output from Linux - versions, paths, and counts will differ on your machine Environment ✓ Node.js v20.11.0 @@ -126,6 +137,14 @@ Local state ✓ Installed 2 plugins ``` +The VS Code path on that last `Editors` line is platform-specific: + +| Platform | VS Code user directory | +| --- | --- | +| macOS | `~/Library/Application Support/Code/User` | +| Linux | `~/.config/Code/User` (or `$XDG_CONFIG_HOME/Code/User`) | +| Windows | `%APPDATA%\Code\User` | + `✓` fine, `!` works but worth knowing, `x` blocks an install. It exits non-zero only when something blocks, so it can be used in a script; add `--json` for machine-readable output.