@zosmaai/pi-llm-wiki 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 ## [Unreleased]
 
 ### Fixed
+- **MCP server failed to start on `@modelcontextprotocol/server` 2.0.0** (Issue #128): `mcp/index.ts` imported `StdioServerTransport` from the package root, but SDK 2.0.0 (published 2026-07-27) moved that export to the `./stdio` subpath, so `node dist/mcp/index.js` died with `SyntaxError: The requested module '@modelcontextprotocol/server' does not provide an export named 'StdioServerTransport'` before the transport ever connected. The declared range `^2.0.0-alpha.2` is a caret range over a prerelease, so it permits `2.0.0`: every fresh consumer install resolved the stable SDK against the pre-stable import, while `pnpm-lock.yaml` pinned the `2.0.0-alpha.2` floor — so `test/mcp-package.test.ts`, which does spawn the published command and complete the stdio handshake, only ever exercised the alpha where the root export still existed. Fixed by importing `StdioServerTransport` from `@modelcontextprotocol/server/stdio` (the `./stdio` subpath does not exist in `2.0.0-alpha.2`, so the range, the lockfile and the import move together), raising the range to `^2.0.0`, and refreshing the lockfile so the existing smoke test now runs against the SDK consumers actually get.
+- **Packaged MCP server was never exercised with consumer-resolved dependencies**: a new `packaged-mcp-consumer` CI job packs the tarball, installs it into a directory with **no lockfile**, prints the resolved SDK version, and runs `scripts/mcp-smoke.mjs` — the stdio handshake (`initialize` → `tools/list`) — against that install. This closes the whole class of failure behind Issue #128: a dependency range that resolves differently for consumers than for this repo's lockfile can no longer break the published server undetected.
+- **README documented a standalone MCP command that ships no JavaScript** (Issue #129): all ten READMEs pointed MCP clients at `node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js`, but the published `mcp/` directory contains only TypeScript (`index.ts`, `exec.ts`, `operations.ts`), so the documented command failed with `MODULE_NOT_FOUND` — independently of any dependency-resolution problem. The runnable entry is `dist/mcp/index.js`, which the package's own `pi.mcpservers` manifest already declared correctly. Every README now documents that path and adds an `mcpServers` config block for `.mcp.json` / `claude_desktop_config.json` using **absolute** paths, because MCP clients spawn the command without a shell: a `~` in `args` or `env` is passed through literally and the server fails to start behind a generic connection error. A new `test/package-structure.test.ts` case derives the expected path from `pi.mcpservers` — the same command `test/mcp-package.test.ts` spawns and handshakes with — and asserts every documented `…/mcp/index.js` occurrence in every README resolves to it, so docs cannot drift from the runnable entry point again.
+- **Authoritative activity history**: `meta/events.jsonl` is now documented as durable append-only extension state rather than rebuildable metadata. Missing or unreadable event sources warn and preserve existing Markdown logs while unrelated projections continue rebuilding.
+- **Portable log privacy**: local-file capture events no longer duplicate caller-supplied filesystem paths into `events.jsonl` or OKF `wiki/log.md`; exact paths remain in extension-owned raw manifests.
 - **Vault layout migration safety and packaging**: `scripts/migrate-llm-wiki.js` now runs on the minimum supported Node 18 runtime, accepts absolute or relative roots regardless of flag order, reserves the destination root atomically, uses no-clobber file moves, rejects destination collisions before moving data, and ships in the npm package. A durable journal records source hashes and completed moves so an interrupted migration resumes safely; file and directory durability boundaries are flushed before completion. Black-box tests cover paths with spaces, dry-run immutability, hash-preserving apply, idempotency, preflight/raced collisions, real subprocess `SIGKILL` recovery, doubled-layout recovery, packed-artifact contents, and packed execution on Node 18.
 - **Malformed legacy pages blocked every metadata rebuild**: `wiki_lint auto_fix=true` now backs up recoverable malformed pages, repairs missing frontmatter or `type` fields, archives unparseable raw frontmatter, preserves bodies, and writes a manifest containing old/new SHA-256 hashes before rebuilding metadata. Audit-only lint remains read-only.
 - **Generated source pages emitted unresolved first-party links**: source skeletons no longer create fake entity/concept links, and raw packet artifacts are rendered as extension-owned code paths rather than Markdown links inside the OKF bundle. Captured and ingested pages now rebuild without unexpected `link_unresolved` or `link_path_escape` diagnostics while retaining valid entity/concept backlinks.

package/README.de.md

@@ -363,11 +363,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Skill-Verhalten

package/README.es.md

@@ -347,11 +347,29 @@ El paquete incluye un servidor MCP independiente que expone 5 herramientas de wi
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Independiente con cualquier cliente MCP:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Establece `WIKI_ROOT` en el directorio de tu vault de wiki. Si no está establecido, el servidor lo detecta automáticamente desde el directorio de trabajo actual.
 
+### Configuración del cliente
+
+El mismo servidor como entrada en `.mcp.json` (Claude Code) o `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> Los clientes MCP lanzan el comando **sin shell**, por lo que `~` nunca se expande. Un `~/my-wiki` en `args` o `env` se pasa literalmente y el servidor no arranca, algo que el cliente solo informa como un error de conexión genérico: usa rutas absolutas aquí. El fragmento de shell anterior sí funciona, porque tu shell expande `~` antes de que `node` lo reciba.
+
 ---
 
 ## Comportamiento de la Habilidad

package/README.fr.md

@@ -363,11 +363,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Comportement de la Compétence

package/README.hi.md

@@ -363,11 +363,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## स्किल व्यवहार

package/README.ja.md

@@ -363,11 +363,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## スキルの動作

package/README.ko.md

@@ -363,11 +363,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## 스킬 동작

package/README.md

@@ -271,11 +271,19 @@ my-wiki/
 | `.llm-wiki/meta/registry.json` | Extension | Generated |
 | `.llm-wiki/meta/backlinks.json` | Extension | Generated |
 | `.llm-wiki/meta/index.md` | Extension | Generated |
-| `.llm-wiki/meta/events.jsonl` | Extension / tool | Append-only |
+| `.llm-wiki/meta/events.jsonl` | Extension / tool | Authoritative append-only state; back up for activity continuity |
 | `.llm-wiki/meta/log.md` | Extension | Generated from events |
 | `.llm-wiki/meta/lint-report.md` | Extension | Generated |
 | `.llm-wiki/WIKI_SCHEMA.md` | Human + explicit request | Operating manual |
 
+### Activity history, backup, and portability
+
+`meta/events.jsonl` is the authoritative source for recorded extension activity. Unlike registry, backlinks, indexes, logs, and embeddings, it cannot be rebuilt from wiki pages or raw packets. Preserve it when backing up or Git-synchronizing a complete pi-llm-wiki vault.
+
+`meta/log.md` and OKF-mode `wiki/log.md` are generated views. `wiki/log.md` can travel with the OKF bundle as a readable snapshot, but it cannot reconstruct or resume the originating JSONL stream. Manual page edits are intentionally absent, so this is selected extension activity rather than a complete revision audit.
+
+File-capture events omit machine-local paths from the public log projection. Callers of `wiki_log_event` still control arbitrary detail fields and must not record secrets or private host paths.
+
 ---
 
 ## Linking & Citation Style
@@ -351,11 +359,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Skill Behavior
@@ -385,7 +411,7 @@ Each wiki vault has four layers with clear ownership:
 ```
 .llm-wiki/raw/sources/SRC-*/     # Immutable source packets (extension-owned)
 .llm-wiki/wiki/                   # Editable knowledge pages (you + LLM)
-.llm-wiki/meta/                   # Auto-generated registry, backlinks, index, log
+.llm-wiki/meta/                   # Durable event source + generated internal projections
 .llm-wiki/                        # Config and templates
 ```
 
@@ -475,6 +501,13 @@ Thanks to everyone who has contributed! This list is regenerated automatically b
                     <sub><b>Daniel Naab</b></sub>
                 </a>
             </td>
+            <td align="center">
+                <a href="https://github.com/mkuhl">
+                    <img src="https://avatars.githubusercontent.com/u/61073?v=4" width="64;" alt="mkuhl"/>
+                    <br />
+                    <sub><b>Mike P. Kuhl</b></sub>
+                </a>
+            </td>
             <td align="center">
                 <a href="https://github.com/deestax">
                     <img src="https://avatars.githubusercontent.com/u/152369481?v=4" width="64;" alt="deestax"/>
@@ -482,6 +515,8 @@ Thanks to everyone who has contributed! This list is regenerated automatically b
                     <sub><b>Superdao</b></sub>
                 </a>
             </td>
+		</tr>
+		<tr>
             <td align="center">
                 <a href="https://github.com/mystery4f">
                     <img src="https://avatars.githubusercontent.com/u/40482524?v=4" width="64;" alt="mystery4f"/>

package/README.pt.md

@@ -363,11 +363,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Comportamento da Skill

package/README.ru.md

@@ -363,11 +363,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Поведение навыка

package/README.zh.md

@@ -347,11 +347,29 @@ my-wiki/
 pi install npm:@zosmaai/pi-llm-wiki
 
 # 独立使用任何 MCP 客户端：
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 设置 `WIKI_ROOT` 为您的 wiki vault 目录。如果未设置，服务器从当前工作目录自动检测。
 
+### 客户端配置
+
+在 `.mcp.json`（Claude Code）或 `claude_desktop_config.json` 中配置同一个服务器：
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP 客户端在**不经过 shell** 的情况下启动该命令，因此 `~` 不会被展开。`args` 或 `env` 中的 `~/my-wiki` 会被原样传递，服务器随即启动失败，而客户端只会报告一个笼统的连接错误——这里请使用绝对路径。上面的 shell 命令没有问题：`~` 由你的 shell 在 `node` 收到之前展开。
+
 ---
 
 ## 技能行为

package/dist/extensions/llm-wiki/lib/bootstrap.js

@@ -12,9 +12,12 @@ export const WIKI_SCHEMA = [
     "|------|-------|------|",
     "| raw/** | extension | immutable after capture |",
     "| wiki/** | model + user | editable knowledge pages |",
-    "| meta/* | extension | auto-generated |",
+    "| meta/events.jsonl | extension tools | append-only authoritative state |",
+    "| meta/* except events.jsonl | extension | generated projections |",
     "| . | human + explicit request | operating rules |",
     "",
+    "Back up `meta/events.jsonl` to preserve activity history. Generated logs cannot reconstruct it.",
+    "",
     "## Source Packet Format",
     "",
     "```",