@theglitchking/semantic-pages 0.6.5 → 0.6.6

package/README.md

@@ -88,50 +88,60 @@ Only the 14 read tools are exposed (`search_*`, `read_note`, `read_multiple_note
 
 ### 1. Installation Methods
 
-#### Method A: NPX (No installation needed)
+#### Method A: Claude Code Plugin (Recommended — zero config, auto-wires)
 
-This lets you run the server without installing it permanently.
+The easiest path if you use Claude Code. Install once per project; the plugin handles `.mcp.json` wiring automatically.
 
-**Step 1**: Open your terminal in your project folder
-
-**Step 2**: Run:
 ```bash
-npx semantic-pages --notes ./vault --stats
+# Inside a Claude Code session:
+/plugin marketplace add TheGlitchKing/semantic-pages
+/plugin install semantic-pages@semantic-pages-marketplace
 ```
 
-**Step 3**: The first time you run it, NPX downloads the package and the embedding model (~80MB). This takes 1-2 minutes.
-
-**Step 4**: After that, it runs instantly.
-
-**Use this method when**: You want to try it out, or you're adding it to a project's `.mcp.json` config.
+What happens next session:
+1. A `SessionStart` hook runs and ensures `./.claude/.vault/` exists
+2. Your project's `.mcp.json` gets a `semantic-vault` entry pointed at `./.claude/.vault` (read/write)
+3. **If** `hit-em-with-the-docs` is also installed **and** `./.documentation/` exists → a second `semantic-pages` entry is added, pointed at `./.documentation` with `--read-only`
+4. You get 21 tools (14 if the docs server is the one being used) for semantic search, graph traversal, and (for the vault) note CRUD
 
-#### Method B: Global Installation (Recommended for regular use)
+No manual `.mcp.json` editing. Uninstalling the plugin cleanly leaves your existing entries alone on the next session.
 
-This installs the tool on your computer so you can use it in any project.
+#### Method B: Project Installation (Recommended for teams and AI-assisted projects)
 
-**Step 1**: Open your terminal
+Install per-project so the version is pinned in `package.json`, stays in sync across teammates and CI, and is visible to any LLM reading the repo.
 
-**Step 2**: Type this command and press Enter:
 ```bash
-npm install -g @theglitchking/semantic-pages
+npm install --save-dev @theglitchking/semantic-pages
 ```
 
-**Step 3**: Test that it worked:
-```bash
-semantic-pages --version
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "semantic-vault": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["--no", "@theglitchking/semantic-pages", "--notes", "./.claude/.vault"]
+    }
+  }
+}
 ```
 
-**Step 4**: You should see a version number. If you do, it's installed correctly!
+> **Why project-level over global?** A global install is invisible to collaborators, CI, and LLMs reading the repo. A project-level install pins the exact version in `package.json`, so every agent and developer working in the repo sees the same binary. Use `npx --no` (not `npx -y`) so npx uses the locally-installed version instead of fetching from the registry.
 
-#### Method C: MCP Configuration (Recommended for Claude Code)
+#### Method C: MCP Configuration via NPX (Quick setup, no install)
 
-Add to your project's `.mcp.json` so Claude has automatic access:
+Add directly to your project's `.mcp.json`. npx downloads and caches the package on first use.
 
 ```json
 {
-  "semantic-pages": {
-    "command": "npx",
-    "args": ["-y", "semantic-pages", "--notes", "./vault"]
+  "mcpServers": {
+    "semantic-vault": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@theglitchking/semantic-pages", "--notes", "./.claude/.vault"]
+    }
   }
 }
 ```
@@ -140,45 +150,23 @@ Point `--notes` at any folder of `.md` files: `./vault`, `./docs`, `./notes`, or
 
 **What to expect**: Next time you run `claude` in that project, Claude will have 21 new tools for searching, reading, writing, and traversing your notes.
 
-#### Method D: Project Installation (For team projects)
-
-This installs the tool only for one specific project.
+> **Note on `@latest` and npx caching**: If you use `@latest` in the args, npx may serve a stale cached version after a new release. To force a refresh: `rm -rf ~/.npm/_npx/*/node_modules/@theglitchking`. Project-level installation (Method B) avoids this entirely.
 
-**Step 1**: Open your terminal in your project folder
+#### Method D: Try it with NPX (No installation needed)
 
-**Step 2**: Type this command:
 ```bash
-npm install --save-dev @theglitchking/semantic-pages
-```
-
-**Step 3**: Add a script to your `package.json` file:
-```json
-{
-  "scripts": {
-    "notes": "semantic-pages --notes ./vault",
-    "notes:stats": "semantic-pages --notes ./vault --stats",
-    "notes:reindex": "semantic-pages --notes ./vault --reindex"
-  }
-}
+npx @theglitchking/semantic-pages --notes ./vault --stats
 ```
 
-#### Method E: Claude Code Plugin (Recommended — zero config, auto-wires)
+The first run downloads the package and the embedding model (~80 MB) and takes 1–2 minutes. After that it runs instantly from cache. Use this to evaluate before committing to a project install.
 
-This is the easiest path if you use Claude Code and want `.claude/.vault/` + (optionally) `.documentation/` indexed automatically.
+#### Method E: Global Installation (Not recommended)
 
 ```bash
-# Inside a Claude Code session:
-/plugin marketplace add TheGlitchKing/semantic-pages
-/plugin install semantic-pages@semantic-pages-marketplace
+npm install -g @theglitchking/semantic-pages
 ```
 
-What happens next session:
-1. A `SessionStart` hook runs and ensures `./.claude/.vault/` exists
-2. Your project's `.mcp.json` gets a `semantic-vault` entry pointed at `./.claude/.vault` (read/write)
-3. **If** `hit-em-with-the-docs` is also installed **and** `./.documentation/` exists → a second `semantic-pages` entry is added, pointed at `./.documentation` with `--read-only`
-4. You get 21 tools (14 if the docs server is the one being used) for semantic search, graph traversal, and (for the vault) note CRUD
-
-No manual `.mcp.json` editing. Uninstalling the plugin cleanly leaves your existing entries alone on the next session.
+Avoid this for projects — a global install is invisible to collaborators, CI, and LLMs reading the repo, and will silently fall out of sync with the version everyone else is using. Use project-level installation (Method B) instead.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/semantic-pages",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Semantic search + knowledge graph MCP server for markdown vaults. Claude Code plugin with auto-wiring for .claude/.vault and read-only .documentation companion when hit-em-with-the-docs is installed.",
   "type": "module",
   "main": "./dist/core/index.js",