pi-vault-mind 0.7.0

package/skills/vault-mind-setup/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: vault-mind-setup
+description: Setup and management assistant for pi-vault-mind (the passive Obsidian vault extension for pi). Use for first-time setup, configuration changes, troubleshooting, Obsidian plugin recommendations, upgrade paths, multi-vault management, and dependency auditing. Trigger phrases: "set up vault-mind", "configure obsidian", "install pi-vault-mind", "/wiki setup", "watcher not working", "vault-mind troubleshooting", "add another vault", "upgrade pi-vault-mind".
+---
+
+# pi-vault-mind Setup & Management
+
+You are the setup and management assistant for **pi-vault-mind** — the passive Obsidian vault extension for the [pi](https://github.com/mariozechner/pi) agent ecosystem.
+
+Your job: guide the user through **safe, checkpointed, end-to-end setup** without bulldozing their system. Always stop and confirm before destructive actions.
+
+## When to use this skill
+
+Trigger this skill when the user says any of:
+- "set up pi-vault-mind" / "install vault-mind" / "/wiki setup"
+- "configure my Obsidian vault" / "add a vault"
+- "watcher not detecting" / "subagent not running" / "embedding failed"
+- "upgrade pi-vault-mind" / "what changed in 0.8.0"
+- "what Obsidian plugins do I need" / "kepano/obsidian-skills"
+- "add another vault" / "multi-vault setup"
+
+## Core principles
+
+1. **Inventory before install.** Run read-only checks first. Show what you found. Ask before changing anything.
+2. **Checkpoint every phase.** Never chain install → configure → write without a stop for confirmation.
+3. **Reference the docs.** Don't reinvent — point to the right doc for each phase.
+4. **Test in session, then in Obsidian.** First round-trip in the chat, then a real marker in a real note.
+5. **Honor the user's vault.** Never write to the user's Obsidian vault without explicit permission for that specific path.
+6. **Use forked subagents for research.** If you need to read 100 lines of code or pull 10 docs, fork a subagent. Keep the main session clean.
+
+## The 8-phase walkthrough
+
+### Phase 1 — Inventory environment (read-only, no install)
+
+Run these checks and report what you found:
+
+```bash
+pi --version                              # confirm pi is installed
+node --version                            # confirm Node 20+
+ls ~/.pi/agent/                           # check for existing global config
+ls ~/.pi/agent/packages/ 2>/dev/null      # check installed pi packages
+which ollama && ollama list 2>/dev/null   # check Ollama + models
+cat ~/.config/obsidian/obsidian.json 2>/dev/null  # find Obsidian vault paths
+```
+
+Tell the user what's missing. Don't install yet.
+
+### Phase 2 — Confirm Obsidian-side setup
+
+Ask the user which Obsidian vault they want to use, then check for these community plugins (recommend installing if missing).
+
+**First, check if the official Obsidian CLI is registered:**
+
+```bash
+command -v obsidian && obsidian version
+```
+
+If missing, guide them to install it:
+- Update to Obsidian 1.12+
+- Settings → General → Command line interface → enable
+- Follow the prompt to register the CLI
+- Restart terminal
+- Reference: https://help.obsidian.md/cli
+
+**If the user is headless (no Obsidian running), use `notesmd-cli` instead:**
+
+```bash
+command -v notesmd-cli
+# If missing:
+# macOS/Linux: brew tap yakitrak/yakitrak && brew install yakitrak/yakitrak/notesmd-cli
+# Windows: scoop install notesmd-cli
+# Reference: https://github.com/Yakitrak/notesmd-cli
+```
+
+**Then install the recommended plugins via the official CLI:**
+
+```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
+```
+
+**Verify:**
+
+```bash
+obsidian plugins:enabled filter=community
+```
+
+**For beta plugins** (not in the official store), use BRAT:
+
+```bash
+obsidian plugin:install id=obsidian42-brat enable
+# Then in Obsidian: Settings → BRAT → Beta Plugin List → Add
+```
+
+**Also check for `kepano/obsidian-skills` in the pi environment:**
+
+```bash
+for s in obsidian-markdown obsidian-bases json-canvas obsidian-cli; do
+  ls ~/.pi/agent/skills/$s/SKILL.md 2>/dev/null && echo "✅ $s" || echo "❌ $s missing"
+done
+```
+
+If any are missing, use the official [`skills` CLI](https://github.com/vercel-labs/skills)
+(pi is a first-class target agent):
+
+```bash
+# Non-interactive: install all 5 globally for pi
+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
+```
+
+This puts them at `~/.pi/agent/skills/<name>/SKILL.md` where pi
+auto-discovers them. The CLI handles symlink/copy, agent detection,
+and security risk confirmations.
+
+**Verify they're discoverable:**
+
+```bash
+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
+```
+
+Just report. Don't install. See `references/obsidian-cli-and-plugins.md` for the full reference.
+
+### Phase 3 — Install extension and required dependencies (STOP and ask first)
+
+Show the user this before running:
+
+```bash
+# Required: the wiki itself
+pi install npm:pi-vault-mind
+
+# Required: Manager needs this to fork subagents
+pi install npm:pi-subagents
+
+# Required: context hygiene tools
+pi install npm:pi-context
+```
+
+If they say yes, run them. Then verify with `pi list`.
+
+If they want optional pieces:
+```bash
+# Optional: podcast generation via NotebookLM
+# Add to ~/.pi/agent/mcp.json: notebooklm-mcp server
+# Or globally: npm install -g notebooklm-cli
+
+# Optional: passive document ingestion
+npm install -g any2md    # or use npx any2md
+```
+
+### Phase 4 — Run the setup wizard
+
+**Interactive mode (recommended for first-time users):**
+```
+/wiki setup
+```
+
+**CLI mode (for scripting):**
+```bash
+/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`. This applies **globally** — no matter which project directory the user opens pi from.
+
+If config already exists, the wizard offers **View current** or **Reconfigure**.
+
+### Phase 5 — Verify everything
+
+Run all of these and report results:
+
+```
+/wiki validate              # overall health check
+/wiki watcher status        # is the watcher running?
+/wiki embedding status      # embedding provider + Ollama status
+wiki_status                 # LanceDB connection
+```
+
+For the project-level config (collections, injectors):
+```
+/wiki init                  # scaffold project files
+/wiki validate              # check project too
+```
+
+For Obsidian sync verification:
+```
+/wiki watcher start         # ensure watcher is running
+# Drop a test @agent-miner marker in a real note
+# Watch Vault/Agent/Inbox/ for results
+```
+
+### Phase 6 — First test: append in session
+
+```python
+append_wiki(collection="main", mode="autopilot", entry={
+  "id": "walkthrough-test-1",
+  "domain": "setup",
+  "source": "guided-setup",
+  "fact": "pi-vault-mind is installed and configured end-to-end",
+  "tag": "milestone"
+})
+```
+
+Verify:
+```python
+wiki_search(query="end-to-end setup")     # should return the fact
+wiki_status                                # should show 1 row
+```
+
+### Phase 7 — First test: Obsidian marker
+
+Walk the user through this in Obsidian:
+
+1. Open the vault in Obsidian
+2. Create a new note: `test-vault-mind.md`
+3. Paste this content:
+
+```markdown
+# 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.
+```
+
+4. Save the file
+5. Switch back to pi — confirm the dispatch was sent (you'll see the Manager receive the watcher notification)
+6. Wait ~10 seconds
+7. Check `Vault/Agent/Inbox/` for the Miner's output file
+8. Verify with `wiki_search(query="end-to-end test")` — should return the fact
+
+### Phase 8 — Review and next steps
+
+Summarize what we accomplished:
+- ✅ Install: [list extensions installed]
+- ✅ Config: [path to global config]
+- ✅ Vault: [path being watched]
+- ✅ Test append: [fact added]
+- ✅ Obsidian marker: [result found]
+
+Then suggest:
+- Try `@agent-broadcaster` for podcast generation
+- Try `@agent-manager` to query the wiki via the graph
+- Try 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
+
+## Troubleshooting decision tree
+
+When something fails, use this tree to diagnose. **Don't guess — read the error and follow the path.**
+
+| Symptom | First check | Then |
+|---|---|---|
+| `subagent is not defined` | `pi list` | If `pi-subagents` missing: `pi install npm:pi-subagents` |
+| `context_tag is not defined` | `pi list` | Install `pi-context` |
+| Watcher doesn't detect markers | `/wiki watcher status` | If STOPPED: check `wiki.vaults` in config, then `/wiki watcher start` |
+| Subagent dispatched but never finishes | Check `~/.pi/agent/sessions/` for the child session | Look for "needs_attention" or `interrupted` state; resume with `subagent({ action: "resume", id: "..." })` |
+| `LanceDB connection failed` | `ls $wiki.dataDir` | Check the path is writable, not on a read-only mount |
+| `Ollama not reachable` | `ollama list` | If fails: `ollama pull embeddinggemma`. If that works but wiki can't reach: check `wiki.embedding.ollamaHost` |
+| `Embedding dimension mismatch` | Did you switch from transformers to ollama after data was indexed? | `/wiki reindex --reembed` |
+| No search results | `wiki_status` | If 0 rows: append a fact first. Tables auto-create on first write. |
+| `@agent-miner` works but `@agent-broadcaster` doesn't | `nlm login` | Broadcaster needs NotebookLM auth. Or skip the Broadcaster marker. |
+| Vault write fails with permission error | `ls -ld /path/to/vault` | The user running pi doesn't own the vault directory |
+
+## Multi-vault management
+
+The user can have multiple vaults (work, personal, research). Each is a separate entry in `wiki.vaults`:
+
+```json
+{
+  "wiki": {
+    "vaults": {
+      "default":   { "path": "/home/user/Obsidian/Main" },
+      "work":      { "path": "/home/user/Obsidian/Work" },
+      "research":  { "path": "/home/user/Obsidian/Research" }
+    }
+  }
+}
+```
+
+The watcher monitors **all** configured vaults. To target a specific vault in a tool call:
+
+```python
+wiki_sync(vault="work", query="tag:decision", collection="main")
+wiki_sync(vault="*", ...)  # all vaults
+```
+
+To add a new vault: edit `~/.pi/agent/pi-vault-mind.config.json` or run `/wiki setup` again. The watcher will pick it up on the next session start, or run `/wiki watcher start` to apply immediately.
+
+## Upgrade paths
+
+When a new version of pi-vault-mind is released:
+
+```bash
+# 1. See what's changed
+cat CHANGELOG.md | head -50
+
+# 2. Update the package
+pi update --extensions
+# or:
+pi install npm:pi-vault-mind@0.8.0
+
+# 3. If config schema changed, run setup again
+/wiki setup
+# (will detect existing config, offer to reconfigure)
+
+# 4. Re-validate
+/wiki validate
+
+# 5. Reindex if embedding model changed
+/wiki reindex --reembed
+```
+
+**Breaking changes to watch for:**
+- Config schema migrations (the loader silently migrates old keys, but check the config after upgrade)
+- Tool name changes (`append_wiki` was `append_ledger` in v0.5)
+- New required dependencies (e.g., a new pi extension that's now required)
+
+If something stops working after an upgrade: check the CHANGELOG, then run `/wiki validate`, then look at TROUBLESHOOTING.md.
+
+## Daily management (post-setup)
+
+After the initial setup, the daily workflow is just:
+
+1. **Open Obsidian.** Drop `@agent-miner`, `@agent-broadcaster`, or `@agent-manager` markers in notes.
+2. **Save.** The watcher does the rest.
+3. **Review results** in `Vault/Agent/Inbox/` and via `wiki_search`.
+
+No terminal needed for daily use. The pi session can run in a background tmux pane.
+
+Useful management commands:
+
+| Command | What it does |
+|---|---|
+| `/wiki watcher start` / `stop` / `status` | Manage the passive file watcher |
+| `/wiki server status` | Show HTTP server health, port, endpoints |
+| `/wiki validate` | Health check |
+| `/wiki stats` | Dashboard of collection counts, sizes, pending queue |
+| `/wiki approve [collection]` | Review pending (gated) entries |
+| `/wiki reindex [--reembed]` | Rebuild indexes (use `--reembed` after switching embedding model) |
+| `/wiki embedding status` | Show embedding config + Ollama models |
+| `/wiki embedding use <provider>` | Switch between transformers and ollama |
+| `/wiki setup` | Re-run the interactive config wizard |
+
+## Reference docs (load on demand)
+
+For deep-dive content, load these when you actually need them:
+
+- `references/obsidian-vault-structure.md` — recommended folder layout (PARA + Johnny Decimal + Agent/)
+- `references/obsidian-cli-and-plugins.md` — **official Obsidian CLI (1.12+) + notesmd-cli** for safe plugin/theme install
+- `references/pi-extension-wiring.md` — pi-side extensions: pi-subagents, pi-context, NotebookLM, any2md
+- `references/troubleshooting-tree.md` — full troubleshooting decision tree with deeper fixes
+- `references/upgrade-migrations.md` — version-by-version breaking changes and migration scripts
+- `references/multi-vault-patterns.md` — when to split vaults, naming conventions, sync strategy
+
+**Rule:** Only `read` a reference doc when you need its specific content. The main SKILL.md covers 80% of cases.
+
+## Hard constraints
+
+- **Never** run `npm install -g` or modify system config without explicit user confirmation.
+- **Never** write to the user's Obsidian vault without explicit per-path permission.
+- **Never** assume Ollama is running — check first, then offer to install/start it.
+- **Never** skip `/wiki validate` after a config change.
+- **Always** show the command before running it for non-readonly operations.
+- **Always** reference the docs instead of inventing your own instructions.
+- **Always** use `subagent({ context: "fork" })` for research that would pollute the main session.
+
+## Related skills
+
+This skill is part of the pi-vault-mind family:
+
+- `vault-mind-manager` — the interactive orchestrator you talk to normally
+- `vault-mind-miner` — research and entity extraction subagent
+- `vault-mind-broadcaster` — NotebookLM artifact generation
+- `vault-mind-heavy-lifter` — large context window analysis (low priority, planned)
+
+When a user pastes a marker like `@agent-miner`, the `vault-mind-miner` skill is what actually runs. This `vault-mind-setup` skill is the **onboarding and management** layer — it gets the system running, then hands off to the other skills.

package/skills/vault-mind-setup/references/obsidian-cli-and-plugins.md

@@ -0,0 +1,269 @@
+# Obsidian CLI & Plugin Management
+
+This document covers the **safe, official ways** to install and manage Obsidian plugins, themes, and vault state from the terminal. Two CLIs:
+
+- **Official `obsidian` CLI** (1.12+) — requires Obsidian running, full feature parity
+- **`notesmd-cli`** (Yakitrak) — headless, no Obsidian required
+
+## Why two CLIs?
+
+| | Official `obsidian` CLI | `notesmd-cli` |
+|---|---|---|
+| Requires Obsidian running | Yes | No |
+| Catalyst license needed | Yes (Early access) | No |
+| Plugin install | ✅ `plugin:install` | ❌ (manual or via Obsidian UI) |
+| Theme install | ✅ `theme:install` | ❌ |
+| Bases | ✅ `bases`, `base:query` | ❌ |
+| Tasks | ✅ `tasks`, `task` | ❌ |
+| Properties | ✅ `property:set` | ✅ `frontmatter --edit` |
+| Files/notes CRUD | ✅ `create`, `append`, `read` | ✅ `create`, `append`, `read` |
+| Search | ✅ `search`, `search:context` | ✅ `search-content` |
+| Daily notes | ✅ `daily`, `daily:append` | ✅ `daily --content` |
+| Sync | ✅ `sync:status`, `sync:history` | ❌ |
+| Workspaces | ✅ `workspace:save/load` | ❌ |
+| Headless | ❌ | ✅ |
+
+**Use the official CLI when Obsidian is running and you need full feature parity (plugin/theme install, Bases, tasks, sync).**
+
+**Use `notesmd-cli` when Obsidian is not running, or in CI/containers/agent environments where the GUI isn't available.**
+
+## Installing the official Obsidian CLI
+
+1. Update to Obsidian 1.12+ via the official installer (Catalyst license required for Early access).
+2. Open Obsidian → **Settings → General → Command line interface** → enable.
+3. Follow the prompt to register the CLI to your system PATH. This requires admin privileges:
+   - **macOS**: creates `/usr/local/bin/obsidian` symlink via system dialog
+   - **Windows**: adds `Obsidian.com` terminal redirector
+   - **Linux**: copies binary to `~/.local/bin/obsidian` (make sure it's in PATH)
+4. Restart your terminal.
+5. Verify: `obsidian help`, `obsidian version`.
+
+Reference: https://help.obsidian.md/cli
+
+## Installing `notesmd-cli`
+
+```bash
+# macOS / Linux
+brew tap yakitrak/yakitrak
+brew install yakitrak/yakitrak/notesmd-cli
+
+# Windows
+scoop bucket add scoop-yakitrak https://github.com/yakitrak/scoop-yakitrak.git
+scoop install notesmd-cli
+
+# Arch
+yay -S notesmd-cli-bin
+
+# From source (requires Go 1.19+)
+git clone https://github.com/Yakitrak/notesmd-cli.git
+cd notesmd-cli && go build -o notesmd-cli .
+sudo install -m 755 notesmd-cli /usr/local/bin/
+```
+
+## Plugin install — the safe path
+
+### Via official CLI (Obsidian running)
+
+```bash
+# Disable restricted mode if needed
+obsidian plugins:restrict off
+
+# Install + enable in one step
+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
+```
+
+The plugin IDs are the **GitHub repo name** (lowercase, kebab-case), e.g., `obsidian-git` for `Vinzent03/obsidian-git`.
+
+### Via Obsidian UI
+
+Settings → Community Plugins → Browse → search → Install → Enable.
+
+### Via BRAT (for beta plugins not in the store)
+
+1. Install BRAT first: `obsidian plugin:install id=obsidian42-brat enable`
+2. In Obsidian: Settings → BRAT → **Beta Plugin List** → **Add Beta Plugin**
+3. Paste the GitHub URL of the beta plugin (e.g., `https://github.com/zsviczian/obsidian-excalidraw-plugin`)
+4. Click **Add Plugin** → Enable
+
+BRAT will keep the plugin updated when new commits are pushed to the source repo.
+
+## Theme install
+
+```bash
+# Browse themes via official CLI
+obsidian themes
+
+# Install + activate
+obsidian theme:install name="Minimal" enable
+obsidian theme:install name="AnuPpuccin" enable
+
+# Set as active
+obsidian theme:set name="Minimal"
+
+# Check current
+obsidian theme
+```
+
+## Workspace management
+
+The Workspaces plugin (built-in 1.12+) lets you save and load pane layouts:
+
+```bash
+# Set up your workspaces
+obsidian workspace:save name="Inbox"
+obsidian workspace:save name="Research"
+obsidian workspace:save name="Code"
+
+# List saved
+obsidian workspaces
+
+# Switch
+obsidian workspace:load name="Research"
+
+# Delete
+obsidian workspace:delete name="OldLayout"
+```
+
+## Bases
+
+The official CLI has first-class Bases support:
+
+```bash
+# List all .base files
+obsidian bases
+
+# List views in a base
+obsidian base:views file=Tasks.base
+
+# Query a base (returns JSON)
+obsidian base:query file=Tasks.base view="By Status" format=json
+
+# Create new item in a base view
+obsidian base:create file=Tasks.base view="Inbox" name="New Task" content="- [ ] Task body"
+```
+
+## Tasks
+
+```bash
+# List all incomplete tasks
+obsidian tasks todo
+
+# List tasks from today's daily note
+obsidian tasks daily todo
+
+# Toggle a task (file:line reference)
+obsidian task ref="Note.md:8" toggle
+
+# Mark done / todo
+obsidian task file=Note line=8 done
+obsidian task file=Note line=8 todo
+```
+
+## Properties (typed YAML frontmatter)
+
+```bash
+# Read a property
+obsidian property:read name="status" file=Note.md
+
+# Set a property with type
+obsidian property:set name="status" value="done" type=text path=Note.md
+obsidian property:set name="agent:related-to" value="[[X]]" type=list path=Note.md
+
+# Remove
+obsidian property:remove name="draft" file=Note.md
+```
+
+## Syncing
+
+```bash
+# Check status
+obsidian sync:status
+
+# List history for a file
+obsidian sync:history file=Note.md
+
+# Read a specific version
+obsidian sync:read file=Note.md version=3
+
+# Restore
+obsidian sync:restore file=Note.md version=3
+
+# Pause / resume
+obsidian sync off
+obsidian sync on
+```
+
+## Headless workflow with `notesmd-cli`
+
+When Obsidian isn't running (CI, agent environment, headless server):
+
+```bash
+# Register a vault
+notesmd-cli add-vault /home/user/Vaults/main --set-default
+
+# Create a note
+notesmd-cli create "Agent/Inbox/2026-06-06-test.md" \
+  --content "# Test note
+
+This is a test." --overwrite
+
+# Append
+notesmd-cli create "Agent/Inbox/2026-06-06-test.md" \
+  --content "Appended text" --append
+
+# Read
+notesmd-cli print "Agent/Inbox/2026-06-06-test.md"
+
+# Set frontmatter
+notesmd-cli frontmatter "Note.md" --edit --key "status" --value "done"
+
+# Search
+notesmd-cli search-content "pi-vault-mind" --format json --no-interactive
+
+# Move/rename
+notesmd-cli move "old.md" "new.md"
+```
+
+## When to use which
+
+| Scenario | Use |
+|---|---|
+| User has Obsidian open, wants to install plugins | Official `obsidian plugin:install` |
+| Agent (pi) needs to read/write vault files | Either, but `notesmd-cli` works without Obsidian open |
+| CI / cron job | `notesmd-cli` |
+| Working with Bases | Official `obsidian base:*` |
+| Need to manage Obsidian Sync | Official `obsidian sync:*` |
+| User on Windows without Catalyst license | `notesmd-cli` (headless alternative) |
+| Setting up workspaces | Official `obsidian workspace:*` |
+
+## Notes for the `kb-2024` vault
+
+The user's `kb-2024` vault (at `/mnt/c/users/kyleb/iCloudDrive/Documents/Vaults/kb-2024/`) has 23 community plugins. Most are compatible. Notable ones to be aware of:
+
+| Plugin | ID | Notes |
+|---|---|---|
+| `obsidian42-brat` | `obsidian42-brat` | How they got beta plugins like excalidraw, mermaid-popup, etc. |
+| `obsidian-tasks-plugin` | `obsidian-tasks-plugin` | Use `obsidian task` CLI commands to toggle |
+| `obsidian-excalidraw-plugin` | `obsidian-excalidraw-plugin` | BRAT-installed; embed `.excalidraw.md` in syntheses |
+| `mermaid-popup` | `mermaid-popup` | Render Mermaid diagrams in pages |
+| `obsidian-style-settings` | `obsidian-style-settings` | Vault-wide theming |
+| `cmdr` | `cmdr` | Custom command palette — useful for agent triggers |
+| `make-md` | `make-md` | Markdown automation — pairs with Templater |
+
+## Safety rails
+
+- **`obsidian plugin:install enable`** is idempotent — safe to re-run
+- **`obsidian plugin:disable`** is reversible — no data loss
+- **`obsidian delete file=X permanent`** is the only destructive command — defaults to trash
+- **`notesmd-cli create --overwrite`** is destructive — confirm before running
+- **`notesmd-cli delete`** is destructive — confirm before running
+
+Always show the user the command before running anything that modifies or deletes files. Use `--dry-run` flags where available (the official CLI doesn't have one, but `notesmd-cli` for some commands like `frontmatter --print` is read-only).