Install Playbook¶

The single source of truth for installing pi-vault-mind and all its dependencies. If something isn't here, it isn't officially supported.

TL;DR for the impatient:

# pi extensions
pi install npm:pi-vault-mind pi install npm:pi-subagents pi install npm:pi-context

# Obsidian plugins (Obsidian must be running, 1.12+)
obsidian plugin:install id=obsidian-git enable
obsidian plugin:install id=obsidian-breadcrumbs enable
obsidian plugin:install id=graph-analysis enable
obsidian plugin:install id=actions-uri enable
obsidian plugin:install id=shellcommands enable

# Pi skills (auto-discovered)
DISABLE_TELEMETRY=1 yes y | npx -y skills add https://github.com/kepano/obsidian-skills \
  --skill obsidian-markdown --skill obsidian-bases \
  --skill json-canvas --skill obsidian-cli --skill defuddle \
  -g -a pi --copy -y

# Configure
/wiki setup --vault /path/to/your/vault --provider transformers

Layer 1: pi extensions (npm)¶

All pi extensions install via pi install <source>. Sources can be npm:, git:, or absolute paths.

Required (hard dependencies)¶

Extension	Purpose	Install
pi-vault-mind	The wiki itself	`pi install npm:pi-vault-mind`
pi-subagents	The `subagent()` tool — Manager uses this to fork isolated workers	`pi install npm:pi-subagents`
pi-context	Context hygiene tools (`context_tag`, `context_log`, `context_checkout`)	`pi install npm:pi-context`

Optional (enhance specific workflows)¶

Extension	Purpose	Install
pi-intercom	Inter-agent coordination	`pi install npm:pi-intercom`

Install pattern¶

# All required extensions in one command
pi install npm:pi-vault-mind npm:pi-subagents npm:pi-context

# Or one at a time
pi install npm:pi-vault-mind
pi install npm:pi-subagents
pi install npm:pi-context

# From git (for development)
pi install git:git@github.com:kylebrodeur/pi-vault-mind

# Try without installing
pi -e npm:pi-vault-mind

Verify¶

pi list
# Should show: pi-vault-mind, pi-subagents, pi-context

Layer 2: pi skills (auto-discovered at `~/.pi/agent/skills/<name>/SKILL.md`)¶

Skills are auto-loaded by pi at session start. The install path MUST be ~/.pi/agent/skills/<name>/SKILL.md (one folder per skill). Use the official skills CLI to handle path detection, symlinks, and security confirmations correctly.

Required: kepano/obsidian-skills (5 skills)¶

These teach agents Obsidian-specific formats (markdown, bases, canvas, CLI, web extraction). Without them, agents generate technically-valid markdown that Obsidian doesn't render correctly.

DISABLE_TELEMETRY=1 yes y | npx -y skills add https://github.com/kepano/obsidian-skills \
  --skill obsidian-markdown --skill obsidian-bases \
  --skill json-canvas --skill obsidian-cli --skill defuddle \
  -g -a pi --copy -y

Why the pipe: The CLI presents a "Security Risk Assessments" confirmation even with -y. The yes y handles it, and DISABLE_TELEMETRY=1 opts out of anonymous usage data.

Why -a pi: Pi is a first-class target agent — the CLI knows to install at ~/.pi/agent/skills/.

Why --copy: Creates real copies (not symlinks). Safer for multi-agent setups; each agent has its own copy.

Optional: NotebookLM skill (nlm-skill)¶

For the Broadcaster agent's podcast generation:

# The nlm-skill ships with the notebooklm-mcp-cli MCP server
# Install the MCP server globally and the skill auto-loads
npm install -g notebooklm-mcp-cli
nlm login  # authenticate with Google

Verify¶

for s in obsidian-markdown obsidian-bases json-canvas obsidian-cli defuddle; do
  [ -f ~/.pi/agent/skills/$s/SKILL.md ] && echo "✅ $s" || echo "❌ $s"
done

List what's installed¶

npx skills list -g -a pi

Update¶

npx skills update -g -a pi -y

Layer 3: Obsidian plugins (two ways)¶

Option A: Official Obsidian CLI (1.12+)¶

The recommended way. Requires Obsidian 1.12+ running, with CLI enabled in Settings → General → Command line interface.

Install: 1. Update to Obsidian 1.12+ via official installer 2. Open Obsidian → Settings → General → Command line interface → enable 3. Follow prompt to register CLI to PATH 4. Restart terminal 5. Verify: obsidian help, obsidian version

Install plugins:

# Disable restricted mode
obsidian plugins:restrict off

# Recommended plugins
obsidian plugin:install id=obsidian-git enable
obsidian plugin:install id=obsidian-breadcrumbs enable
obsidian plugin:install id=graph-analysis enable
obsidian plugin:install id=actions-uri enable
obsidian plugin:install id=shellcommands enable
obsidian plugin:install id=obsidian42-brat enable  # for beta plugins

Verify:

obsidian plugins:enabled filter=community

Option B: `notesmd-cli` (headless)¶

For CI, containers, or when Obsidian isn't running. Doesn't support plugin install (use the official CLI for that).

# macOS / Linux
brew tap yakitrak/yakitrak
brew install yakitrak/yakitrak/notesmd-cli

# Windows (Scoop)
scoop bucket add scoop-yakitrak https://github.com/yakitrak/scoop-yakitrak.git
scoop install notesmd-cli

# Arch
yay -S notesmd-cli-bin

Option C: Obsidian UI (manual fallback)¶

Settings → Community Plugins → Browse → search → Install → Enable.

Plugin reference¶

Plugin	Install ID	Why
obsidian-git	`obsidian-git`	Backup, conflict resolution
Breadcrumbs	`obsidian-breadcrumbs`	Typed-edge graph UI
Graph Analysis	`graph-analysis`	Co-citation discovery
Actions URI	`actions-uri`	Cross-app automation
obsidian-shellcommands	`shellcommands`	Obsidian events → pi
BRAT	`obsidian42-brat`	Beta plugins by GitHub URL

Layer 4: Configuration (no install needed)¶

After installs, configure pi-vault-mind:

# Interactive wizard (recommended for first-time)
/wiki setup

# CLI mode (for scripting)
/wiki setup --vault /home/user/Obsidian/MyVault --provider transformers
/wiki setup --vault /home/user/Obsidian/MyVault --provider ollama --model embeddinggemma

Config writes to ~/.pi/agent/pi-vault-mind.config.json (global, applies to all projects).

For project-specific knowledge:

/wiki init           # scaffold project collections
/wiki validate       # health check

Layer 5: External CLIs (optional)¶

Ollama (for higher-quality embeddings)¶

# Install from https://ollama.com
curl -fsSL https://ollama.com/install.sh | sh

# Pull the embedding model
ollama pull embeddinggemma

any2md (for Miner passive document ingestion)¶

# Available via npx (no global install needed)
npx any2md https://arxiv.org/abs/... > paper.md

# Or install globally
npm install -g any2md

NotebookLM CLI (for Broadcaster)¶

npm install -g notebooklm-cli
nlm login  # Google account auth

Order of operations (for a clean first install)¶

Install pi extensions (Layer 1) — required for everything else
Install Obsidian CLI (Layer 3 Option A) — prerequisite for plugin install
Install Obsidian plugins (Layer 3) — via obsidian plugin:install
Install pi skills (Layer 2) — via npx skills add
Install external CLIs (Layer 5) — only what you need
Configure (Layer 4) — /wiki setup

For minimum viable: layers 1 + 4. That gives you the wiki working in the terminal with no Obsidian integration.

For full Obsidian integration: all 5 layers.

Verifying everything is installed¶

# Layer 1: pi extensions
pi list

# Layer 2: pi skills
for s in obsidian-markdown obsidian-bases json-canvas obsidian-cli defuddle; do
  [ -f ~/.pi/agent/skills/$s/SKILL.md ] && echo "✅ skill: $s" || echo "❌ skill: $s"
done

# Layer 3: Obsidian plugins (if CLI installed)
obsidian plugins:enabled filter=community

# Layer 4: configuration
ls -la ~/.pi/agent/pi-vault-mind.config.json

# Layer 5: external CLIs
which ollama npx notesmd-cli 2>/dev/null
ollama list 2>/dev/null | head -5

# End-to-end: open pi and run
pi
/wiki validate
/wiki watcher status
/wiki setup    # if you haven't configured yet

Troubleshooting¶

Symptom	Check	Fix
`pi: command not found`	Install pi	See pi docs
`obsidian: command not found`	Install Obsidian CLI	Settings → General → Command line interface
Skill not loading in pi	Check path	`~/.pi/agent/skills/<name>/SKILL.md` (one folder per skill)
`subagent is not defined`	pi-subagents missing	`pi install npm:pi-subagents`
`context_tag is not defined`	pi-context missing	`pi install npm:pi-context`
`npx skills add` hangs	Security prompt	Pipe `yes y` to it
Plugin install fails	Restricted mode on	`obsidian plugins:restrict off`
Embedding model not found	ollama not running	`ollama list` and `ollama pull <model>`

For deeper troubleshooting, see the vault-mind-setup skill's references/troubleshooting-tree.md (loaded by the setup wizard), or file an issue at https://github.com/kylebrodeur/pi-vault-mind/issues.

How to approach this in the future¶

When a new dependency or install step is needed:

Check this playbook first. Is the new thing in Layer 1-5? Follow the same pattern.
Use the official CLIs. pi install, obsidian, npx skills, brew. Avoid custom scripts.
Read the docs of the tool you're installing. Don't guess CLI flags from random StackOverflow posts.
Verify the install path. Pi skills MUST be at ~/.pi/agent/skills/<name>/SKILL.md. If they're not, the agent won't see them.
Test in a fresh session. Close and reopen pi to verify skills reload correctly.
Update the playbook. If a new tool needs to be installed for the wiki to work, document it here.

When in doubt, run the Inventory command from the vault-mind-setup skill:

pi --version
node --version
ls ~/.pi/agent/skills/ | head -20
pi list
which obsidian notesmd-cli ollama
obsidian plugins:enabled filter=community 2>/dev/null
ls ~/.pi/agent/pi-vault-mind.config.json 2>/dev/null

That tells you exactly what's installed and what's missing.

Install Playbook¶

Layer 1: pi extensions (npm)¶

Required (hard dependencies)¶

Optional (enhance specific workflows)¶

Install pattern¶

Verify¶

Layer 2: pi skills (auto-discovered at ~/.pi/agent/skills/<name>/SKILL.md)¶

Required: kepano/obsidian-skills (5 skills)¶

Optional: NotebookLM skill (nlm-skill)¶

Verify¶

List what's installed¶

Update¶

Layer 3: Obsidian plugins (two ways)¶

Option A: Official Obsidian CLI (1.12+)¶

Option B: notesmd-cli (headless)¶

Option C: Obsidian UI (manual fallback)¶

Plugin reference¶

Layer 4: Configuration (no install needed)¶

Layer 5: External CLIs (optional)¶

Ollama (for higher-quality embeddings)¶

any2md (for Miner passive document ingestion)¶

NotebookLM CLI (for Broadcaster)¶

Order of operations (for a clean first install)¶

Verifying everything is installed¶

Troubleshooting¶

How to approach this in the future¶

Layer 2: pi skills (auto-discovered at `~/.pi/agent/skills/<name>/SKILL.md`)¶

Option B: `notesmd-cli` (headless)¶