Guided Walkthrough Prompt¶
How to use: Open a fresh pi session in any project directory. Paste the entire block under "THE PROMPT" below. The agent will walk you through the full setup → first-use → review loop, with checkpoints between each phase.
The Prompt¶
I want to set up and run pi-vault-mind (the passive Obsidian vault extension
for pi) end-to-end for the first time. Please walk me through it step by
step, with checkpoints between each phase. Stop and ask me before running
anything destructive (writing to my Obsidian vault, installing global npm
packages, or starting background watchers).
**Phase 1 — Inventory my environment**
Before we start, check what I already have:
- `pi --version` — confirm pi is installed
- `node --version` — confirm Node 20+
- `ls ~/.pi/agent/` — see if any global config already exists
- `ls ~/.pi/agent/packages/` — see if pi-vault-mind is already installed
- `which ollama && ollama list` — check if Ollama is running
- Find my Obsidian vault(s) by checking `~/.config/obsidian/obsidian.json`
or by asking me for the path
Tell me what's missing and what we need to install. Don't install anything
yet — just report.
**Phase 2 — Confirm Obsidian-side setup**
Ask me which Obsidian vault I want to use, and confirm these community
plugins are installed (or note which are missing). The recommended way
to install them is via the official Obsidian CLI (Settings → General →
Command line interface → enable), then:
```bash
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
For headless installs (Obsidian not running), use notesmd-cli instead.
For beta plugins not in the store, use BRAT (obsidian42-brat).
Also confirm whether the kepano/obsidian-skills are installed and
discoverable by pi in your environment (must be at
~/.pi/agent/skills/<name>/SKILL.md for pi to auto-discover them):
- [ -f ~/.pi/agent/skills/obsidian-markdown/SKILL.md ] && echo "✅" || echo "❌"
- [ -f ~/.pi/agent/skills/obsidian-bases/SKILL.md ] && echo "✅" || echo "❌"
- [ -f ~/.pi/agent/skills/json-canvas/SKILL.md ] && echo "✅" || echo "❌"
- [ -f ~/.pi/agent/skills/obsidian-cli/SKILL.md ] && echo "✅" || echo "❌"
- [ -f ~/.pi/agent/skills/defuddle/SKILL.md ] && echo "✅" || echo "❌"
If any are missing, just list them and note that they can be
installed with the skills CLI:
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
Phase 3 — Install the extension and dependencies
Show me the install commands before running them:
- pi install npm:pi-vault-mind
- pi install npm:pi-subagents (REQUIRED — Manager needs subagent() tool)
- pi install npm:pi-context (REQUIRED — context hygiene tools)
If I confirm, run them. Then verify with pi list.
Phase 4 — Run the setup wizard
Run /wiki setup interactively. Walk me through the prompts:
- Vault path: I'll provide this
- Embedding provider: recommend transformers for zero-setup; ollama for
higher quality
- If ollama: model selection
- Confirm config written to ~/.pi/agent/pi-vault-mind.config.json
If I have an existing config, offer to view it instead of reconfiguring.
Phase 5 — Verify everything works
Run these and report results:
- /wiki validate — health check
- /wiki watcher status — confirm watcher is running
- /wiki embedding status — confirm embedding provider
- wiki_status tool — confirm LanceDB connection
- node --test in the project — confirm tests pass (if applicable)
Show me the full output. If anything is red, help me fix it.
Phase 6 — First test: append a fact
Run this in the active session:
append_wiki(collection="main", mode="autopilot", entry={
"id": "test-1",
"domain": "walkthrough",
"source": "guided-setup",
"fact": "pi-vault-mind is installed and configured end-to-end",
"tag": "milestone"
})
Then verify:
- wiki_search(query="end-to-end setup") — should return the fact
- wiki_status — should show 1 row
- ~/.pi/agent/pi-vault-mind.config.json — show me the file contents
- find ~/.pi/agent -name "main.jsonl" 2>/dev/null — find the JSONL
Phase 7 — First test: Obsidian marker
I have an Obsidian vault at [PATH]. I'll create a test note there. Walk me
through:
1. Open Obsidian, navigate to your vault
2. Create a new note called test-vault-mind.md
3. Paste this content:
# Test: Vault Mind Walkthrough
@agent-miner Extract this test fact and confirm the system is working end-to-end.
This is a test of the passive Obsidian integration. The watcher should
detect this marker, dispatch a Miner subagent, extract entities, and
write results back to the vault.
- Save the file
- Switch back to this pi session — confirm the dispatch was sent
- Wait ~10 seconds, then check
Vault/Agent/Inbox/for the Miner's output - Run
wiki_search(query="end-to-end test")to confirm the fact was indexed
Report what you found in the Inbox/ folder and LanceDB.
Phase 8 — Review and next steps
Summarize what we accomplished: - ✅ Install: [list extensions installed] - ✅ Config: [path to global config] - ✅ Vault: [path to vault being watched] - ✅ Test append: [fact added] - ✅ Obsidian marker: [result found]
Then suggest next steps:
- Try @agent-broadcaster for podcast generation
- Try @agent-manager to query the wiki via the graph
- Try the multi-marker test: one file with @agent-miner and @agent-broadcaster
- Try named IDs: @agent-miner:custom1 and @agent-miner:custom2 in the same file
Constraints for this whole walkthrough:
- STOP and ask before any of these:
- Installing global npm packages
- Writing to my Obsidian vault (except the test note in Phase 7)
- Starting background watchers (it auto-starts; just confirm)
- Modifying system config files
- For each command, show me what it does before running
- If something fails, show me the error and suggest fixes from
docs/TROUBLESHOOTING.md or docs/EXTENSION_WIRING.md
- Use the subagent tool with context: "fork" for any research that
would pollute the main session
- Reference the docs as we go:
- GETTING_STARTED.md
- docs/OBSIDIAN_SETUP.md
- docs/EXTENSION_WIRING.md
- docs/PASSIVE_INGESTION_WORKFLOW.md
- docs/E2E_MANUAL_TEST.md
- research/COMPETITOR_COMPARISON.md
Start with Phase 1. Let me know what you find.
---
## What to expect
The agent will:
1. **Inventory** — run safe read-only checks first
2. **Confirm** — show you what it found, ask before installing
3. **Install** — only after your explicit "yes"
4. **Configure** — via `/wiki setup` or pre-fill
5. **Verify** — show you green/red status for each check
6. **Test** — first in the session, then in Obsidian
7. **Summarize** — what worked, what to try next
Each phase has a clear stopping point. The agent won't bulldoze through
your system — it will pause for confirmation at every risky step.
---
## Variants
Want a faster version? Use this minimal prompt:
After the walkthrough¶
Once everything is green, the daily workflow is just:
- Open Obsidian. Drop
@agent-miner,@agent-broadcaster, or@agent-managermarkers in your notes. - Save. The watcher does the rest.
- Review results in
Vault/Agent/Inbox/and viawiki_search.
No terminal needed for daily use — the pi session can run in the background (e.g., in a tmux pane) and only the Obsidian side matters.