pi-vault-mind 0.14.2 → 0.16.3

package/scripts/vault-pi.sh

@@ -8,7 +8,7 @@
 #   Command: bash /path/to/pi-vault-mind/scripts/vault-pi.sh {{vault_path}}
 #
 # The script:
-#   1. Checks for an existing PID file at <vault>/.pi/agent/daemon.pid
+#   1. Checks for an existing PID file at <vault>/.vault-mind/.pi/agent/daemon.pid
 #   2. If the PID is alive → exits silently (already running)
 #   3. If stale/dead → cleans up and starts fresh
 #   4. Opens a new terminal window with pi using the vault-local config dir
@@ -16,7 +16,7 @@
 set -euo pipefail
 
 VAULT="${1:?Usage: vault-pi.sh <vault-path>}"
-PI_DIR="${VAULT}/.pi/agent"
+PI_DIR="${VAULT}/.vault-mind/.pi/agent"
 PID_FILE="${PI_DIR}/daemon.pid"
 
 # Ensure the vault-local agent dir exists
@@ -33,10 +33,19 @@ if [ -f "${PID_FILE}" ]; then
 	rm -f "${PID_FILE}"
 fi
 
+# --op-env is a flag registered by pi-1password. Passing it when that
+# extension isn't installed makes pi reject the whole invocation with
+# "Unknown option: --op-env" — only pass it when both the env file exists
+# AND pi-1password is actually installed in the vault-local agent dir.
+OP_ENV_ARG=""
+if [ -f "${VAULT}/.vault-mind/.env.1pass" ] && [ -d "${PI_DIR}/npm/node_modules/pi-1password" ]; then
+	OP_ENV_ARG="--op-env .vault-mind/.env.1pass"
+fi
+
 # Start pi in a new terminal window.
 # macOS: open -a Terminal or open -a iTerm
 # The trap writes the PID and cleans up on exit.
-PI_CMD="PI_CODING_AGENT_DIR='${PI_DIR}' pi; rm -f '${PID_FILE}'"
+PI_CMD="PI_CODING_AGENT_DIR='${PI_DIR}' pi ${OP_ENV_ARG}; rm -f '${PID_FILE}'"
 
 if [ -d "/Applications/iTerm.app" ]; then
 	open -a iTerm --args --detach bash -c "echo \$\$ > '${PID_FILE}'; cd '${VAULT}'; ${PI_CMD}"

package/skills/github-release-notes-file/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: github-release-notes-file
+description: Create GitHub releases with multi-line notes by writing to a file and using gh --notes-file
+---
+
+# GitHub Release Notes — Use `--notes-file`
+
+When you need multi-line markdown release notes, **do not** use inline `--notes` with `\n` escapes. Bash keeps the backslashes literal, and the release notes will display `\n` on GitHub.
+
+## Recommended pattern
+
+1. Create the notes file with the `write` tool:
+
+   Path: `/tmp/release-notes-vX.Y.Z.md`
+
+   Content:
+   ```markdown
+   ## What's new
+
+   - Feature one
+   - Feature two
+
+   ## Known issues
+
+   - Issue one
+   ```
+
+2. Create the release with `--notes-file`:
+
+```bash
+gh release create vX.Y.Z --title "vX.Y.Z" --notes-file /tmp/release-notes-vX.Y.Z.md
+```
+
+3. To edit an existing release:
+
+```bash
+gh release edit vX.Y.Z --notes-file /tmp/release-notes-vX.Y.Z.md
+```
+
+## Why not inline?
+
+Double-quoted shell strings do not interpret `\n` as a newline. `$'...'` or `printf` can work, but they are fragile for markdown containing quotes and backticks. The bash tool also blocks `cat > file <<'EOF'` redirects for file creation, so use the `write` tool instead.

package/skills/obsidian-guided-test-session/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: obsidian-guided-test-session
+description: "Run structured manual test sessions in the ReturnVape Obsidian vault: attach debugger, guide user through steps, poll console/errors, collect Developer Toolbox screenshots, and produce a token-efficient session report."
+---
+
+# obsidian-guided-test-session
+
+Use this when manually testing the Vault Mind Obsidian plugin in the ReturnVape test vault. The assistant guides the session; the user drives the interaction in Obsidian and captures annotated screenshots with Developer Toolbox.
+
+## Preconditions
+
+- Obsidian is running with the ReturnVape vault open.
+- Developer Toolbox plugin is installed and enabled.
+- Vault Mind plugin is installed (BRAT-managed) and enabled.
+- `obsidian` CLI is available in this session.
+
+## Session artifacts
+
+- Working scratchpad: `local://test-session-YYYY-MM-DD.md` (or `local://test-session-YYYY-MM-DD-HHMM.md` if multiple sessions per day).
+- Archived report: `docs/test-sessions/YYYY-MM-DD-HHMM.md` after the session.
+
+Template sections in the scratchpad:
+
+```markdown
+# Test Session — YYYY-MM-DD HH:MM
+
+## Scope
+- Plugin version tested:
+- pi-vault-mind version tested:
+- Areas under test:
+
+## Steps / Checklist
+- [ ] Step 1: ...
+
+## Findings
+| # | Step | Severity | Summary | Screenshot | Console/errors | Follow-up |
+|---|------|----------|---------|------------|----------------|-----------|
+| 1 |      |          |         |            |                |           |
+
+## Console dump (only if relevant)
+```
+
+## Start a session
+
+1. Create the scratchpad from the template above.
+2. Record plugin versions:
+   ```bash
+   obsidian plugin id=vault-mind vault=ReturnVape
+   ```
+3. Attach the debugger and clear buffers:
+   ```bash
+   obsidian dev:debug on --vault ReturnVape
+   obsidian dev:errors --vault ReturnVape clear
+   obsidian dev:console --vault ReturnVape clear
+   ```
+4. Define the test plan checklist in the scratchpad.
+
+## During the session
+
+For each step:
+
+1. Tell the user what to do in Obsidian (one action at a time, e.g. "Open the Vault Mind panel from the left sidebar", "Click the Setup tab").
+2. Wait for the user to report completion or paste a screenshot path/annotation.
+3. Poll errors and console:
+   ```bash
+   obsidian dev:errors --vault ReturnVape
+   obsidian dev:console --vault ReturnVape --lines 50
+   ```
+4. If the user shares a screenshot, record its path. If they used Developer Toolbox annotations, note the annotation text.
+5. If an issue is found, record it immediately in the findings table with:
+   - Repro step
+   - Expected vs actual behavior
+   - Severity: `blocker`, `major`, `minor`, `polish`
+   - Screenshot path (if any)
+   - Relevant console/error snippet
+   - Follow-up action (file bug, investigate, expected, etc.)
+6. If the step succeeds, mark the checklist item done.
+
+## Asking for screenshots
+
+When a visual state matters, ask the user:
+
+> Please capture a screenshot with Developer Toolbox and paste the saved file path here. Annotate anything that looks wrong.
+
+Do not ask for screenshots on every step — only when visual state is ambiguous or an issue appears.
+
+## Ending a session
+
+1. Detach debugger:
+   ```bash
+   obsidian dev:debug off --vault ReturnVape
+   ```
+2. Summarize findings: count by severity, list blockers/majors first.
+3. Archive the scratchpad to `docs/test-sessions/YYYY-MM-DD-HHMM.md`.
+4. If there are actionable bugs, file them or add them to ROADMAP/Open Questions.
+
+## Token efficiency rules
+
+- Never paste image bytes into the conversation; only record paths/URIs.
+- Pull full console/error output only when a step fails or an issue is found.
+- Keep the running scratchpad as the single source of truth; append to it instead of repeating findings in chat.
+- Use tables and short bullets for findings.
+- Link follow-ups to existing ROADMAP/P2 items when possible.
+
+## Common pitfalls to watch for
+
+- Plugin fails to load: check `obsidian dev:errors` for `MODULE_NOT_FOUND` — usually an npm dependency not bundled into `main.js`.
+- `PVM_API_TOKEN` missing: check Obsidian Settings → Vault Mind token status and the `obsidian dev:console` output.
+- Chat composer blank or unresponsive: check console for Arrow/runtime errors; ask for a screenshot.
+- Setup wizard looping: verify `.pi/` state and whether the vault has already been initialized.

package/skills/obsidian-interactive-test/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: obsidian-interactive-test
+description: "Use during plugin testing — enables debug monitoring, takes screenshots (via CLI or Developer Toolbox), inspects DOM, tails console, checks functional state."
+---
+
+# Obsidian Interactive Test Monitor
+
+Run these during plugin testing to see what the user sees in real time.
+
+## Setup (run once at start of test session)
+
+```bash
+obsidian dev:debug on              # enable console capture
+obsidian vault="ReturnVape" plugin:reload id=vault-mind  # ensure latest
+```
+
+**Developer Toolbox** (v0.9.0, installed in ReturnVape) provides richer dev tools:
+- **Issue Capture**: annotated screenshots with plugin context — use instead of dev:screenshot when documenting bugs
+- **Plugin Reloader**: auto-reload on build change — replaces manual plugin:reload
+- **CSS inspector**: browse `--vm-*` variables
+- **Icon browser**: find icon IDs
+
+Trigger from Obsidian command palette: "Developer Toolbox: ..."
+
+## Screenshots
+
+```bash
+# Quick — obsidian CLI
+obsidian vault="ReturnVape" dev:screenshot path=/tmp/vm-test.png
+
+# Rich — Developer Toolbox (use when annotating a bug)
+# Trigger: Cmd+P → "Developer Toolbox: Capture screenshot"
+```
+
+## Monitoring loop (run while user tests)
+
+```bash
+# Errors
+obsidian vault="ReturnVape" dev:errors
+
+# DOM state — what's visible
+obsidian vault="ReturnVape" dev:dom selector=".vault-mind-panel" text
+obsidian vault="ReturnVape" dev:dom selector=".vault-mind-tab-content:not([style*='none'])" text
+
+# Full functional state check
+obsidian vault="ReturnVape" eval code="(()=>{const l=app.workspace.getLeavesOfType('vault-mind-panel');const v=l[0]?.view;const chat=v?.tabs?.find(t=>t.id==='chat');return JSON.stringify({tabs:v?.tabs?.length,activeTab:v?.activeTab,chatHasPi:!!chat?.tab?.connection?.process?.pid,msgCount:chat?.tab?.view?.messages?.length})})()"
+
+# Pi process running?
+pgrep -fl "pi" | grep -v "Applications\|System\|usr\|omp\|Claude"
+
+# Check heights (layout issues)
+obsidian vault="ReturnVape" eval code="(()=>{const msgs=document.querySelector('.pi-messages');return JSON.stringify({h:msgs?.offsetHeight,children:msgs?.children.length})})()"
+```
+
+## After user reports an issue
+
+1. `obsidian vault="ReturnVape" dev:errors` — crashes
+2. `obsidian vault="ReturnVape" dev:dom selector=".vault-mind-tab-content:not([style*='none'])" text` — what's showing
+3. `obsidian vault="ReturnVape" dev:console` — recent logs  
+4. **Use Developer Toolbox Issue Capture** for annotated screenshot with context
+
+## Deploy fix and reload
+
+```bash
+cd packages/obsidian && node esbuild.config.mjs production
+cp main.js ~/workspace/recycvape/ReturnVape/.obsidian/plugins/vault-mind/
+obsidian vault="ReturnVape" plugin:reload id=vault-mind
+# Or use Developer Toolbox auto-reload if watching build output
+```
+
+## Functional assertions (not just error-free)
+
+After init, verify these are ALL true:
+```bash
+obsidian vault="ReturnVape" eval code="(()=>{
+  const hasPi=!!require('child_process').execSync('pgrep -f \"pi.*rpc\"',{stdio:['pipe','pipe','pipe']}).toString().trim();
+  const panel=app.workspace.getLeavesOfType('vault-mind-panel')[0]?.view;
+  const chat=panel?.tabs?.find(t=>t.id==='chat')?.tab;
+  return JSON.stringify({
+    panel_has_tabs: panel?.tabs?.length>0,
+    chat_mounted: chat?.mounted,
+    pi_connected: chat?.connection?.isConnected(),
+    pi_process_alive: !!(chat?.connection?.process?.pid),
+    messages_area_height: document.querySelector('.pi-messages')?.offsetHeight,
+    piConfigDir_correct: chat?.deps?.piConfigDir?.startsWith('/')
+  })
+})()"
+```

package/skills/obsidian-plugin-publish/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: obsidian-plugin-publish
+description: Publishing the Vault Mind Obsidian plugin from the pi-vault-mind monorepo to the separate obsidian-vault-mind repo via BRAT
+---
+
+# Publishing the Obsidian Plugin
+
+## Architecture
+
+- Source: `packages/obsidian/` in the `pi-vault-mind` monorepo
+- Distribution repo: `kylebrodeur/obsidian-vault-mind` (releases only)
+- Plugin ID: `vault-mind`
+- BRAT install: `kylebrodeur/obsidian-vault-mind`
+
+## Build
+
+```bash
+cd packages/obsidian && node esbuild.config.mjs production
+```
+
+## Publish (local)
+
+```bash
+./scripts/publish-obsidian-plugin.sh [version]
+```
+
+Reads version from `packages/obsidian/manifest.json` if not specified.
+Clones plugin repo, copies `main.js`, `manifest.json`, `styles.css`, `versions.json`, `README.md`, commits, pushes, creates GitHub release.
+
+## Publish (CI)
+
+Tag with `obsidian-v<version>` and push. The `release-obsidian.yml` workflow runs the publish script.
+Requires `PLUGIN_REPO_TOKEN` secret (PAT with repo scope).
+
+## Test locally
+
+```bash
+# Copy to vault for immediate testing
+cp packages/obsidian/main.js <vault>/.obsidian/plugins/vault-mind/main.js
+obsidian plugin:reload id=vault-mind
+obsidian dev:errors
+```
+
+## BRAT install command (for users)
+
+```bash
+obsidian eval code='(async()=>{await app.plugins.getPlugin("obsidian42-brat").betaPlugins.addPlugin("kylebrodeur/obsidian-vault-mind")})()'
+```
+
+Note: `betaPlugins.addPlugin` (not `addPlugin` on plugin root), async IIFE required.
+
+## Version bump checklist
+
+1. Bump `packages/obsidian/manifest.json` version
+2. Bump root `manifest.json` to match
+3. Build: `node esbuild.config.mjs production`
+4. Commit
+5. Run `./scripts/publish-obsidian-plugin.sh`

package/skills/pi-vault-mind-release/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: pi-vault-mind-release
+description: "Release workflow for the pi-vault-mind monorepo: version bump, build, commit, GitHub releases, Obsidian plugin publish, BRAT test-vault install, npm publish"
+---
+
+# pi-vault-mind release workflow
+
+Use this when cutting a new release of `pi-vault-mind` (backend/core) and `obsidian-pi-vault-mind` (Obsidian plugin).
+
+## Preconditions
+
+- `pnpm check` passes.
+- `pnpm test` passes.
+- `packages/obsidian` build passes (`pnpm --filter obsidian-pi-vault-mind build`).
+
+## Version files to bump
+
+Keep versions aligned for coordinated releases:
+
+- `package.json` root → `pi-vault-mind` package version.
+- `packages/obsidian/package.json` → plugin package version (should track manifest).
+- `packages/obsidian/manifest.json` → `version`.
+- `manifest.json` root → mirror `packages/obsidian/manifest.json`.
+- `packages/obsidian/versions.json` → add new row: `"<version>": "<minAppVersion>"`.
+
+Example: bump root to `0.13.0`, plugin files to `0.5.0`.
+
+For **plugin-only hotfixes**, bump only the plugin files (`packages/obsidian/package.json`, `packages/obsidian/manifest.json`, root `manifest.json`, `versions.json`). Do **not** bump the root `package.json` if the npm package itself did not change.
+
+## Build and verify
+
+```bash
+pnpm run build
+pnpm --filter obsidian-pi-vault-mind build
+pnpm check && pnpm test
+```
+
+## Update CHANGELOG.md
+
+Add a section under `# Changelog` at the top, e.g.:
+
+```markdown
+## 0.5.1 — YYYY-MM-DD
+
+### Fixed
+...
+
+## 0.13.0 / 0.5.0 — YYYY-MM-DD
+
+### Added
+...
+```
+
+For plugin-only hotfixes, use a plugin-version-only header.
+
+## Commit and push
+
+```bash
+git add -A
+git commit -m "feat: <summary>"
+git push origin main
+```
+
+For a plugin-only hotfix:
+
+```bash
+git commit -m "fix(obsidian): <summary>
+
+- Root package stays at 0.13.0 since the npm package did not change."
+```
+
+## Create GitHub releases
+
+Main repo (only when the npm package / root changed):
+
+```bash
+gh release create v<version> --repo kylebrodeur/pi-vault-mind \
+  --title "v<version> — <summary>" \
+  --notes "<markdown release notes>"
+```
+
+Obsidian plugin repo:
+
+```bash
+bash scripts/publish-obsidian-plugin.sh <plugin-version>
+```
+
+This script pushes `manifest.json`, `main.js`, `styles.css`, and `versions.json` to `kylebrodeur/obsidian-vault-mind` and creates a GitHub release there.
+
+## Install/update in the test vault via BRAT
+
+Never manually copy plugin files into `.obsidian/plugins/vault-mind/`. Let BRAT manage the install.
+
+The ReturnVape test vault has BRAT configured with `kylebrodeur/obsidian-vault-mind` as a beta plugin. Trigger an update:
+
+```bash
+obsidian command id=obsidian42-brat:checkForUpdatesAndUpdate vault=ReturnVape
+```
+
+Then verify:
+
+```bash
+obsidian plugin id=vault-mind vault=ReturnVape
+obsidian plugin:reload id=vault-mind vault=ReturnVape
+obsidian dev:errors --vault ReturnVape
+obsidian dev:console --vault ReturnVape --lines 50
+```
+
+Expected: plugin version matches the new release, reload succeeds, no plugin-load errors.
+
+## Reset the test vault data (optional)
+
+```bash
+./scripts/reset-test-vault.sh
+```
+
+This removes `.pi/`, `.lancedb/`, `pi-vault-mind.config.json`, and `collections/` while preserving vault notes and `.obsidian/` (including the BRAT-managed plugin).
+
+## Publish to npm (only when root package changed)
+
+```bash
+npm pack
+npm publish pi-vault-mind-<version>.tgz --otp=<your-otp>
+```
+
+Requires the user's one-time password.
+
+## Post-release smoke test
+
+1. Open the vault in Obsidian.
+2. Trigger BRAT update if not already done.
+3. Open the Vault Mind panel → Setup tab.
+4. Walk through init: model-router picker, Modal setup + test connection, chat composer, session popover.
+5. Exercise the **Vault Mind: Dispatch agent** palette command on a note with `@agent` markers.
+6. Verify chat messages render and actions (copy/info/rewind) work.
+
+## Obsidian dependency bundling rule
+
+If the plugin imports an npm package (e.g. `json5`), it must be bundled into `main.js`. Do **not** list it in `esbuild.config.mjs`'s `external` array. Only `obsidian`, `electron`, `@codemirror/view`, and Node built-ins should be external.
+
+Verify a dependency is bundled by ensuring `main.js` contains its code and that `require("<dep>")` does not appear in the bundle.

package/skills/pre-test-release/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: pre-test-release
+description: "Use before handing off to the user for manual testing — runs full CI, updates docs/versions, publishes plugin, resets test vault, and alerts for npm OTP."
+---
+
+# Pre-Test Release Checklist
+
+Run this procedure when implementation is complete and the user needs a clean, publishable build to test against.
+
+## 1. Full CI Check
+
+```bash
+cd packages/obsidian && npx tsc --noEmit          # plugin types
+cd ~/workspace/pi-vault-mind && pnpm run build     # full project build
+cd ~/workspace/pi-vault-mind && pnpm test          # all tests (expect 238 pass / 0 fail)
+cd packages/obsidian && node esbuild.config.mjs production  # plugin bundle
+```
+
+All must pass with zero errors. Fix any issues before proceeding. Do not rely on piped `tail` for exit status — verify the actual test summary and exit code.
+
+## 2. Clean Git Tree
+
+```bash
+git status   # must be clean — no unstaged, no untracked
+```
+
+If dirty: stage and commit with an appropriate message, or stash unrelated changes.
+
+## 3. Docs Review & Update
+
+- Read `docs/NEXT_STEPS.md` — move completed items to ✅ Shipped, update Now/Next
+- Read `docs/ROADMAP.md` — add new version row to Shipped table, update date and current status
+- Read `docs/getting-started/WALKTHROUGH.md` — verify steps match current behavior
+- Commit doc changes: `docs: update status for v<version>`
+
+## 4. Version Bump
+
+Determine bump type (patch/minor) based on changes. Update ALL version files:
+
+```python
+# package.json — npm package version
+# packages/obsidian/manifest.json — plugin version
+# manifest.json (root) — mirror of plugin manifest
+# packages/obsidian/versions.json — add "<plugin-ver>": "<minAppVersion>"
+```
+
+Rebuild plugin after bump: `cd packages/obsidian && node esbuild.config.mjs production`
+
+## 5. Commit, Push, Release
+
+Write the release notes to a temp markdown file so multi-line formatting is preserved literally. Use the `write` tool to save it to `/tmp/release-notes-v<npm-ver>.md`:
+
+```markdown
+## What's new
+
+< bullets >
+
+## Release gate
+
+< pending verification, known issues >
+```
+
+```bash
+git add -A
+git commit -m "feat(...): <summary>\n\n<details>"
+git push origin main
+gh release create v<npm-ver> --title "v<npm-ver>" --notes-file /tmp/release-notes-v<npm-ver>.md
+```
+
+## 6. Publish Obsidian Plugin
+
+```bash
+bash scripts/publish-obsidian-plugin.sh <plugin-ver>
+```
+
+This clones `kylebrodeur/obsidian-vault-mind`, copies built assets, commits, pushes, and creates a GH release with main.js + manifest.json + styles.css.
+
+## 7. Reset & Update Test Vault
+
+```bash
+./scripts/reset-test-vault.sh
+```
+
+This removes `.pi/`, config, `.lancedb/`, `collections/`, and copies the latest plugin build into the test vault.
+
+After reset, remind user to **reload the plugin in Obsidian** (reopen vault or disable/re-enable plugin).
+
+## 8. npm Pack & Test
+
+```bash
+cd ~/workspace/pi-vault-mind
+npm pack --dry-run    # verify package contents look correct
+npm pack              # create tarball for inspection
+```
+
+## 9. Alert User
+
+Tell the user:
+- Everything is published (GH releases for both repos)
+- Test vault is reset and ready
+- npm needs their OTP: `npm publish --otp=<code>`
+- Where to start testing (specific WALKTHROUGH step or doc section)
+- What was changed since last test (brief summary)
+- Any known issues or areas to watch
+- Remind to reload plugin in Obsidian after reset
+
+## Key paths
+
+| Artifact | Location |
+|----------|----------|
+| npm package | `pi-vault-mind` on npm |
+| Plugin repo | `kylebrodeur/obsidian-vault-mind` (BRAT) |
+| Test vault | `~/workspace/recycvape/ReturnVape/` |
+| Plugin in vault | `<vault>/.obsidian/plugins/vault-mind/` |
+| Publish script | `scripts/publish-obsidian-plugin.sh` |
+| Reset script | `scripts/reset-test-vault.sh` |

package/dist/test/auto-indexer.test.js

@@ -1,2 +0,0 @@
-import { strict as assert } from "node:assert";
-assert.equal(1, 1);