pkm-mcp-server 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-03-19
+
+### Added
+- `pkm-mcp-server init` — interactive onboarding wizard that walks users through vault setup, template installation, folder structure, OpenAI API key configuration, and Claude Code registration in a single session
+- `cli.js` — new CLI dispatcher with `init` and `--version` subcommands; existing MCP server behavior unchanged when run without arguments
+- `templates/note.md` — minimal generic note template for users who prefer to define their own templates
+- 36 unit tests for init wizard helpers
+
+### Changed
+- `index.js` refactored to export `startServer()` for CLI dispatcher (backward compatible — `node index.js` still works)
+- Entry point updated from `index.js` to `cli.js` in package.json (`bin`, `main`, `exports`)
+
+### Dependencies
+- Added `@inquirer/prompts` for interactive CLI prompts
+
+## [1.2.1] - 2026-03-17
+
+### Added
+- CI workflow for automated npm publishing via GitHub releases (OIDC trusted publishing, no tokens)
+
+### Fixed
+- Hook setup instructions now included in main README Quick Start (previously only in `hooks/README.md`, invisible on npm)
+- `hooks/` directory added to architecture file tree in README
+
 ## [1.2.0] - 2026-03-17
 
 ### Added
@@ -73,7 +97,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Atomic file creation in `vault_write` (`wx` flag) prevents race conditions
 - Error messages sanitized to prevent leaking absolute vault paths
 
-[Unreleased]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.2.1...HEAD
+[1.2.1]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/AdrianV101/Obsidian-MCP/releases/tag/v1.0.0

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js >= 20](https://img.shields.io/badge/Node.js-%3E%3D20-green.svg)](https://nodejs.org/)
 [![CI](https://github.com/AdrianV101/Obsidian-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/AdrianV101/Obsidian-MCP/actions/workflows/ci.yml)
 
-An MCP (Model Context Protocol) server that gives Claude Code full read/write access to your Obsidian vault. 18 tools for note CRUD, full-text search, semantic search, graph traversal, metadata queries, and session activity tracking. Published on npm as [`pkm-mcp-server`](https://www.npmjs.com/package/pkm-mcp-server).
+An MCP (Model Context Protocol) server that gives Claude Code full read/write access to your Obsidian vault. 19 tools for note CRUD, full-text search, semantic search, graph traversal, metadata queries, session activity tracking, and passive knowledge capture. Published on npm as [`pkm-mcp-server`](https://www.npmjs.com/package/pkm-mcp-server).
 
 ## Why
 
@@ -42,6 +42,7 @@ https://github.com/user-attachments/assets/58ad9c9b-d987-4728-89e7-33de20b73a38
 | `vault_trash` | Soft-delete to `.trash/` (Obsidian convention), warns about broken incoming links |
 | `vault_move` | Move/rename files with automatic wikilink updating across vault |
 | `vault_update_frontmatter` | Atomic YAML frontmatter updates (set, create, remove fields; validates enum fields by note type) |
+| `vault_capture` | Signal a PKM-worthy capture (decision, task, research, bug); returns immediately, background hook creates the note |
 
 ### Fuzzy Path Resolution
 
@@ -55,7 +56,7 @@ vault_read({ path: "devlog.md" })
 // Same result — .md extension is optional
 
 vault_links({ path: "alpha" })
-// Works on vault_links, vault_neighborhood, vault_suggest_links too
+// Works on vault_peek, vault_links, vault_neighborhood, vault_suggest_links too
 ```
 
 Folder-scoped tools accept partial folder names:
@@ -148,6 +149,67 @@ Add your OpenAI API key to the env block:
 
 This enables `vault_semantic_search` and `vault_suggest_links`. Uses `text-embedding-3-large` with a SQLite + sqlite-vec index stored at `.obsidian/semantic-index.db`. The index rebuilds automatically — delete the DB file to force a full re-embed.
 
+### 4. Enable PKM Hooks (optional)
+
+The hook system adds automatic context loading at session start and passive knowledge capture during coding. Requires the [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) installed and authenticated.
+
+Add to your `~/.claude/settings.json` (alongside the `mcpServers` block):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" node /path/to/Obsidian-MCP/hooks/session-start.js",
+            "timeout": 15,
+            "statusMessage": "Loading PKM project context..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" /path/to/Obsidian-MCP/hooks/stop-sweep.sh",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__obsidian-pkm__vault_capture",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" /path/to/Obsidian-MCP/hooks/capture-handler.sh",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Replace `/path/to/your/vault` with your Obsidian vault path and `/path/to/Obsidian-MCP` with the path to this repo (or the global npm install location).
+
+| Hook | Event | What it does |
+|------|-------|--------------|
+| `session-start.js` | SessionStart | Loads project context (index, devlog, active tasks) at session start |
+| `stop-sweep.sh` | Stop | Scans each exchange for PKM-worthy decisions/tasks, appends to daily captures |
+| `capture-handler.sh` | PostToolUse | Creates structured vault notes when `vault_capture` is called |
+
+See [hooks/README.md](hooks/README.md) for architecture details and troubleshooting.
+
 ## Vault Structure
 
 The server works with any Obsidian vault. The included templates assume this layout:
@@ -203,6 +265,7 @@ graph LR
 ├── embeddings.js     # Semantic index (OpenAI embeddings, SQLite + sqlite-vec)
 ├── activity.js       # Activity log (session tracking, SQLite)
 ├── utils.js          # Shared utilities (frontmatter parsing, file listing)
+├── hooks/            # Claude Code hooks (session context, passive capture)
 ├── templates/        # Obsidian note templates
 └── sample-project/   # Sample CLAUDE.md for your repos
 ```
@@ -217,7 +280,9 @@ All paths passed to tools are relative to vault root. The server includes path s
 
 **Graph exploration** resolves `[[wikilinks]]` to file paths (handling aliases, headings, and ambiguous basenames), then does BFS traversal to return notes grouped by hop distance.
 
-**Activity logging** records every tool call with timestamps and session IDs, enabling Claude to recall what happened in previous conversations.
+**Activity logging** records every tool call (except `vault_activity` itself) with timestamps and session IDs, enabling Claude to recall what happened in previous conversations.
+
+**Passive capture** uses `vault_capture` to signal that something is worth persisting (a decision, task, research finding, or bug). The tool returns immediately — a PostToolUse hook spawns a background agent that creates the structured vault note. Combined with the Stop hook (which sweeps each session for un-captured decisions and tasks), this keeps the vault up to date without interrupting the coding flow.
 
 ## Troubleshooting
 
@@ -240,6 +305,8 @@ Check your Node version with `node -v`. The file watcher uses `fs.watch({ recurs
 
 Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style guidelines, and the pull request process before submitting changes.
 
+See [CHANGELOG.md](CHANGELOG.md) for release history and [SECURITY.md](SECURITY.md) to report vulnerabilities.
+
 ## License
 
 MIT

package/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { createRequire } from "module";
+
+const subcommand = process.argv[2];
+
+try {
+  if (subcommand === "init") {
+    const { runInit } = await import("./init.js");
+    await runInit();
+  } else if (subcommand === "--version" || subcommand === "-v") {
+    const require = createRequire(import.meta.url);
+    const { version } = require("./package.json");
+    console.log(`pkm-mcp-server v${version}`);
+  } else if (!subcommand) {
+    const { startServer } = await import("./index.js");
+    await startServer();
+  } else {
+    console.error(`Unknown command: ${subcommand}`);
+    console.error("Usage: pkm-mcp-server [init]");
+    process.exit(1);
+  }
+} catch (e) {
+  console.error(`Fatal: ${e.message}`);
+  process.exit(1);
+}

package/hooks/README.md

@@ -0,0 +1,125 @@
+# PKM Hook System
+
+Claude Code hooks that enable automatic knowledge capture during coding sessions.
+
+## Overview
+
+The hook system consists of three hooks:
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `session-start.js` | SessionStart | Loads project context from the vault at the start of each session |
+| `stop-sweep.sh` | Stop | Passive capture: scans the latest exchange for PKM-worthy content |
+| `capture-handler.sh` | PostToolUse | Explicit capture: creates structured vault notes when `vault_capture` is called |
+
+### How it works
+
+- **SessionStart** (`session-start.js`): Runs synchronously. Resolves the current working directory to a vault project, reads the project index, recent devlog entries, and active tasks, then injects them as context.
+- **Stop** (`stop-sweep.sh`): Runs asynchronously after each assistant response. Spawns a background `claude -p` (Haiku) that reads the transcript, identifies decisions/tasks/findings from the latest exchange, and appends them to a daily captures file in `00-Inbox/`.
+- **PostToolUse** (`capture-handler.sh`): Runs asynchronously after `vault_capture` tool use. Spawns a background `claude -p` (Sonnet) that creates a properly structured vault note (ADR, task, research note, or troubleshooting log) from the capture payload.
+
+## Setup
+
+### Prerequisites
+
+- [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) installed and authenticated
+- This repository cloned locally
+- An Obsidian vault following the [vault structure convention](../CLAUDE.md#vault-structure-convention)
+
+### Configuration
+
+Add the following to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" node /path/to/Obsidian-MCP/hooks/session-start.js",
+            "timeout": 15,
+            "statusMessage": "Loading PKM project context..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" /path/to/Obsidian-MCP/hooks/stop-sweep.sh",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__obsidian-pkm__vault_capture",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" /path/to/Obsidian-MCP/hooks/capture-handler.sh",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Replace `/path/to/your/vault` with the absolute path to your Obsidian vault (e.g., `~/Documents/PKM`), and `/path/to/Obsidian-MCP` with the absolute path to this repository.
+
+## Architecture Notes
+
+### Command hooks with background subprocesses
+
+The hook system uses `type: "command"` hooks (not `type: "agent"`). The shell scripts themselves exit quickly (within the configured timeout), but they spawn `claude -p` as a detached background process via `nohup ... &`. This means:
+
+- The hook script exits immediately, satisfying the timeout constraint
+- The `claude -p` process continues running independently, doing the actual vault work
+- `--max-turns` limits how many tool calls the background process can make (5 for stop-sweep, 25 for capture-handler)
+
+### MCP config resolution
+
+The shell scripts use `cd "$(dirname "$0")" && pwd -P` to resolve their own location, then construct the path to `index.js` relative to the script directory. This means the scripts work regardless of the current working directory. The `VAULT_PATH` environment variable must be set in the hook command because hook scripts run outside the MCP server process.
+
+### Async behavior
+
+Both `stop-sweep.sh` and `capture-handler.sh` use `async: true` in the hook config. This means Claude Code does not wait for the hook script to finish before continuing. The script starts, spawns the background `claude -p` process, and exits. The background process runs to completion on its own.
+
+### Noise suppression and deduplication
+
+The stop-sweep hook is conservative by design. It only looks at the last exchange (one user message + one assistant response) and skips trivial interactions. If the exchange already contains an explicit `vault_capture` call, the stop-sweep skips that content to avoid duplication with the capture-handler.
+
+## Troubleshooting
+
+### Hook not firing
+
+- Verify the hook config is valid JSON in `~/.claude/settings.json`
+- Check that the `matcher` pattern matches (SessionStart uses `"startup|clear|compact"`, PostToolUse uses the full MCP tool name)
+- Ensure the script paths are absolute
+
+### Script errors
+
+- Check that `VAULT_PATH` is set correctly and the directory exists
+- Verify `node` is available in the hook's PATH
+- Test the script manually: `echo '{"cwd":"/tmp","transcript_path":"/tmp/test","session_id":"abc123"}' | VAULT_PATH="/path/to/vault" ./hooks/stop-sweep.sh`
+
+### Background process not running
+
+- Check for `claude` CLI in PATH
+- Look for `claude -p` processes: `ps aux | grep 'claude -p'`
+- Test `claude -p` directly: `echo "say hello" | claude -p --model sonnet`
+- Check logs in `$VAULT_PATH/.obsidian/hook-logs/` for background process output
+
+### macOS compatibility
+
+The scripts use POSIX-compatible `cd "$(dirname "$0")" && pwd -P` for path resolution, so they work on both Linux and macOS without additional dependencies.

package/hooks/capture-handler.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# PostToolUse hook: explicit PKM capture via vault_capture tool
+# Runs async after vault_capture returns. Spawns claude -p with Sonnet
+# to create a properly structured vault note.
+
+set -euo pipefail
+
+LOG_DIR="${VAULT_PATH:?}/.obsidian/hook-logs"
+mkdir -p "$LOG_DIR"
+PROMPT_FILE=""
+cleanup() { [ -n "$PROMPT_FILE" ] && rm -f "$PROMPT_FILE"; }
+trap 'echo "capture-handler: failed at line $LINENO" >> "$LOG_DIR/capture-errors.log"; cleanup' ERR
+trap cleanup EXIT
+
+# Read hook input from stdin
+INPUT=$(cat)
+
+# Extract tool_input fields (buffer all stdin before parsing)
+eval "$(echo "$INPUT" | node -e "
+  let b='';
+  process.stdin.on('data',c=>b+=c);
+  process.stdin.on('end',()=>{
+    const j=JSON.parse(b);
+    const ti=j.tool_input||{};
+    console.log('TOOL_INPUT='+JSON.stringify(JSON.stringify(ti)));
+    console.log('CAPTURE_TYPE='+JSON.stringify(ti.type||''));
+    console.log('CAPTURE_TITLE='+JSON.stringify(ti.title||''));
+    console.log('CAPTURE_CONTENT='+JSON.stringify(ti.content||''));
+  })
+")"
+
+# Skip if missing required fields
+if [ -z "$CAPTURE_TYPE" ] || [ -z "$CAPTURE_TITLE" ] || [ -z "$CAPTURE_CONTENT" ]; then
+  echo "capture-handler: skipping - missing required fields (type='$CAPTURE_TYPE')" >&2
+  exit 0
+fi
+
+# MCP config for obsidian-pkm server
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd -P)
+MCP_CONFIG=$(node -e "console.log(JSON.stringify({mcpServers:{'obsidian-pkm':{command:'node',args:[process.argv[1]],env:{VAULT_PATH:process.argv[2]}}}}))" "$SCRIPT_DIR/../index.js" "${VAULT_PATH:-$HOME/Documents/PKM}")
+
+# Build prompt via Node.js to avoid shell injection from user content
+PROMPT_FILE=$(mktemp)
+node -e "
+const ti = JSON.parse(process.argv[1]);
+const project = ti.project
+  ? 'The project is: ' + ti.project
+  : 'The project is not specified. Check vault_activity recent entries to infer the active project.';
+const prompt = \`You are a PKM note creation agent. Your job is NOT done until the note has real content — not template placeholders.
+
+## What to capture
+
+- Type: \${ti.type}
+- Title: \${ti.title}
+- Content: \${ti.content}
+- Priority: \${ti.priority || 'normal'}
+- \${project}
+
+## Required steps (you must do ALL of these)
+
+1. Create the note with vault_write using the appropriate template:
+   - research → template 'research-note', path: 01-Projects/{project}/research/{kebab-title}.md
+   - adr → template 'adr', path: 01-Projects/{project}/development/decisions/ADR-NNN-{kebab-title}.md (use vault_list to get next number)
+   - task → template 'task', path: 01-Projects/{project}/tasks/{kebab-title}.md (vault_query first to check for duplicates)
+   - bug → template 'troubleshooting-log', path: 01-Projects/{project}/development/debug/{kebab-title}.md
+   If vault_write fails because the file exists, use a different filename.
+
+2. Read the created note with vault_read.
+
+3. Use vault_edit to replace EVERY template placeholder with real content derived from the Title and Content above. For example, replace 'Brief description of the technology, tool, or concept.' with an actual description. Do this for EACH section — you will need multiple vault_edit calls.
+
+4. Read the note one final time to confirm no placeholder text remains.
+
+CRITICAL: If you stop after step 1 or 2, you have FAILED. The note will contain useless placeholder text like 'Brief description of the technology, tool, or concept.' which is worse than no note at all. You MUST reach step 4.\`;
+require('fs').writeFileSync(process.argv[2], prompt);
+" "$TOOL_INPUT" "$PROMPT_FILE"
+
+# Spawn claude -p in background with logging
+nohup claude -p --model sonnet --mcp-config "$MCP_CONFIG" --max-turns 25 --allowedTools "mcp__obsidian-pkm__vault_write mcp__obsidian-pkm__vault_read mcp__obsidian-pkm__vault_edit mcp__obsidian-pkm__vault_append mcp__obsidian-pkm__vault_query mcp__obsidian-pkm__vault_list mcp__obsidian-pkm__vault_update_frontmatter mcp__obsidian-pkm__vault_activity" < "$PROMPT_FILE" >> "$LOG_DIR/capture-$(date +%Y%m%d-%H%M%S).log" 2>&1 &
+
+exit 0

package/hooks/load-context.js

@@ -0,0 +1,64 @@
+import fs from "fs/promises";
+import path from "path";
+import { extractFrontmatter } from "../utils.js";
+import { extractTailSections } from "../helpers.js";
+
+export async function loadProjectContext(vaultPath, projectPath) {
+  const projectName = path.basename(projectPath);
+  const projectDir = path.join(vaultPath, projectPath);
+  const sections = [];
+
+  sections.push(`## PKM Project Context: ${projectName}`);
+
+  try {
+    const indexContent = await fs.readFile(path.join(projectDir, "_index.md"), "utf-8");
+    sections.push(`### Project Index\n${indexContent}`);
+  } catch (e) {
+    if (e.code !== "ENOENT") console.error("PKM load-context: error reading _index.md:", e.message);
+  }
+
+  try {
+    const devlogContent = await fs.readFile(
+      path.join(projectDir, "development", "devlog.md"), "utf-8"
+    );
+    const tailSections = extractTailSections(devlogContent, 3, 2);
+    sections.push(`### Recent Development Activity\n${tailSections}`);
+  } catch (e) {
+    if (e.code !== "ENOENT") console.error("PKM load-context: error reading devlog:", e.message);
+  }
+
+  const tasks = [];
+  try {
+    const taskDir = path.join(projectDir, "tasks");
+    const entries = await fs.readdir(taskDir);
+    for (const entry of entries) {
+      if (!entry.endsWith(".md")) continue;
+      const content = await fs.readFile(path.join(taskDir, entry), "utf-8");
+      const fm = extractFrontmatter(content);
+      if (!fm || (fm.status !== "active" && fm.status !== "pending")) continue;
+
+      const bodyStart = content.indexOf("\n---", 3);
+      const body = bodyStart !== -1 ? content.slice(bodyStart + 4).trim() : content;
+      const lines = body.split("\n");
+      const titleLine = lines.find(l => l.startsWith("# "));
+      const title = titleLine ? titleLine.slice(2).trim() : entry.replace(".md", "");
+      const descLines = lines
+        .filter(l => l.trim() && !l.startsWith("#"))
+        .slice(0, 2)
+        .map(l => `  ${l.trim()}`)
+        .join("\n");
+
+      tasks.push(`- ${title} (status: ${fm.status}, priority: ${fm.priority || "normal"})\n${descLines}`);
+    }
+  } catch (e) {
+    if (e.code !== "ENOENT") console.error("PKM load-context: error reading tasks:", e.message);
+  }
+
+  if (tasks.length > 0) {
+    sections.push(`### Active Tasks\n${tasks.join("\n")}`);
+  } else {
+    sections.push("### Active Tasks\nNo active tasks");
+  }
+
+  return sections.join("\n\n");
+}

package/hooks/resolve-project.js

@@ -0,0 +1,67 @@
+import fs from "fs/promises";
+import path from "path";
+import { resolvePath } from "../helpers.js";
+
+export async function resolveProject(cwd, vaultPath) {
+  try {
+    await fs.access(vaultPath);
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      return { error: `VAULT_PATH does not exist: ${vaultPath}` };
+    }
+    return { error: `Cannot access VAULT_PATH (${e.code}): ${vaultPath}` };
+  }
+
+  const projectsDir = path.join(vaultPath, "01-Projects");
+  const cwdBasename = path.basename(cwd).toLowerCase();
+
+  try {
+    const entries = await fs.readdir(projectsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.toLowerCase() === cwdBasename) {
+        return { projectPath: `01-Projects/${entry.name}` };
+      }
+    }
+  } catch (e) {
+    if (e.code !== "ENOENT") {
+      return { error: `Error reading 01-Projects/: ${e.message}` };
+    }
+    // 01-Projects/ doesn't exist -- fall through to CLAUDE.md check
+  }
+
+  try {
+    const claudeMd = await fs.readFile(path.join(cwd, "CLAUDE.md"), "utf-8");
+    const match = claudeMd.match(/^#\s+PKM:\s*(.+)$/m);
+    if (match) {
+      const annotatedPath = match[1].trim();
+      try {
+        resolvePath(annotatedPath, vaultPath);
+      } catch (e) {
+        if (e.message === "Path escapes vault directory") {
+          return { error: `CLAUDE.md annotation escapes vault directory: ${annotatedPath}` };
+        }
+        throw e;
+      }
+      try {
+        await fs.access(path.join(vaultPath, annotatedPath));
+        return { projectPath: annotatedPath };
+      } catch (e) {
+        if (e.code === "ENOENT") {
+          return { error: `CLAUDE.md annotation points to non-existent vault path: ${annotatedPath}` };
+        }
+        return { error: `Cannot access annotated vault path (${e.code}): ${annotatedPath}` };
+      }
+    }
+  } catch (e) {
+    if (e.code !== "ENOENT" && e.code !== "EACCES") {
+      return { error: `Error reading CLAUDE.md: ${e.message}` };
+    }
+    // No CLAUDE.md or not readable -- fall through
+  }
+
+  return {
+    error: `No vault project found for "${path.basename(cwd)}". ` +
+      `To fix: ensure your project folder name matches the repo name in 01-Projects/, ` +
+      `or add "# PKM: 01-Projects/YourProject" to your project's CLAUDE.md.`
+  };
+}

package/hooks/session-start.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+import { resolveProject } from "./resolve-project.js";
+import { loadProjectContext } from "./load-context.js";
+
+const VAULT_PATH = process.env.VAULT_PATH;
+
+async function main() {
+  let inputJson = "";
+  for await (const chunk of process.stdin) {
+    inputJson += chunk;
+  }
+
+  let input;
+  try {
+    input = JSON.parse(inputJson);
+  } catch {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: "PKM hook error: could not parse hook input JSON."
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  const { cwd } = input;
+
+  if (!cwd || typeof cwd !== "string") {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: "PKM hook error: hook input missing 'cwd' field."
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  if (!VAULT_PATH) {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: "PKM hook warning: VAULT_PATH environment variable not set. Vault context unavailable."
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  const { projectPath, error } = await resolveProject(cwd, VAULT_PATH);
+
+  if (error) {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: `PKM: ${error}`
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  let context;
+  try {
+    context = await loadProjectContext(VAULT_PATH, projectPath);
+  } catch (e) {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: `PKM hook error: failed to load project context: ${e.message}`
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: context
+    }
+  };
+  console.log(JSON.stringify(output));
+}
+
+main().catch((err) => {
+  console.error(`PKM SessionStart hook error: ${err.message}`);
+  process.exit(1);
+});