/setup

name: setup
description: Configure Vault PKM plugin — set vault path, API keys, and verify setup
allowed-tools: [Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion]

Vault PKM Setup

You are configuring the Vault PKM plugin. Walk the user through these steps:

Step 1: Vault Path

Ask the user for their Obsidian vault path. Validate that:

• The path exists and is a directory
• It contains at least one `.md` file
• Suggest `~/Documents/PKM` as a default

If the path is valid, add it to `~/.claude/settings.json` under the `env` block:

{
  "env": {
    "VAULT_PATH": "/absolute/path/to/vault"
  }
}

Read the file first, merge with existing env vars (don't overwrite other settings), and write back. Verify the MCP server can connect after setting it.

Step 2: OpenAI API Key (Optional)

Ask if they want semantic search features (vault_semantic_search, vault_suggest_links). If yes:

• **NEVER ask the user to type their API key in the chat** — it would be stored in conversation history
• Tell them to open `~/.claude/settings.json` in their text editor (outside of Claude Code) and add `VAULT_PKM_OPENAI_KEY` to the `env` block:

  {
    "env": {
      "VAULT_PATH": "/path/to/vault",
      "VAULT_PKM_OPENAI_KEY": "sk-your-key-here"
    }
  }

• Explain the variable is named `VAULT_PKM_OPENAI_KEY` (not `OPENAI_API_KEY`) to avoid conflicts with project-scoped OpenAI keys. Users upgrading from earlier releases can keep `OBSIDIAN_PKM_OPENAI_KEY` — it still works as a deprecated fallback — but should rename it at their convenience.
• Explain they can get a key from https://platform.openai.com/api-keys
• Explain this enables 2 additional tools (semantic search + link suggestions) but is completely optional
• Tell them to restart Claude Code after saving the file

Step 3: Tool Permissions

Ask the user if they want to auto-approve all PKM vault tools (so they don't get prompted for each tool call). If yes, add this to the `permissions.allow` array in `~/.claude/settings.json`:

mcp__plugin_vault-pkm_vault-pkm__*

Read the file first, merge with existing permissions (don't overwrite), and write back. This allows all vault_read, vault_write, vault_search, etc. tools to run without per-call confirmation.

Step 4: Vault Scaffolding

Check if the vault has templates: 1. Check if templates exist: `ls "$VAULT_PATH/05-Templates/" 2>/dev/null` 2. If missing, tell the user to run `npx obsidian-pkm init` in their terminal to scaffold the vault with templates and PARA folder structure. This is a separate interactive tool that handles vault scaffolding.

Step 5: Verify Setup

Ask the user to verify by requesting a vault operation. For example, tell them to ask Claude: "List the folders in my vault." This calls `vault_list`, which exercises the full MCP server connection and vault path configuration.

• If it returns the vault's directory structure, setup is complete.
• If it fails, suggest restarting Claude Code (`/quit` and relaunch) and re-running `/vault-pkm:setup`.

Step 6: Migration Check

Check if the old `pkm-mcp-server` is installed: 1. Run `npm list -g pkm-mcp-server --depth=0 2>/dev/null` 2. Check for stale hooks: `ls ~/.claude/hooks/pkm/ 2>/dev/null`

If found:

• Suggest: `npm uninstall -g pkm-mcp-server`
• Suggest removing `~/.claude/hooks/pkm/` directory (hooks are now managed by the plugin)
• Check `~/.claude/settings.json` for old hook entries and offer to clean them up

Step 7: Done

> **IMPORTANT:** Restart Claude Code now (`/quit` then relaunch) before using any vault tools. The MCP server needs to restart to pick up the new environment variables.

Confirm setup is complete. Tell the user:

• "Your Vault PKM plugin is configured. Try asking me to list your vault folders to verify."
• If VAULT_PKM_OPENAI_KEY was set: "Semantic search will build its index in the background on first use."
• **Important**: "Restart your Claude Code session for the MCP server to pick up the new environment variables."