pi-vault-mind 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Brodeur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,428 @@
+# pi-vault-mind
+
+[![npm version](https://img.shields.io/npm/v/pi-vault-mind)](https://www.npmjs.com/package/pi-vault-mind)
+[![license](https://img.shields.io/npm/l/pi-vault-mind)](LICENSE)
+[![pi-extension](https://img.shields.io/badge/pi-extension-blue)](https://github.com/mariozechner/pi)
+[![docs](https://img.shields.io/badge/docs-pi--vault--mind-blue)](https://kylebrodeur.github.io/pi-vault-mind/)
+[![docs build](https://github.com/kylebrodeur/pi-vault-mind/actions/workflows/docs.yml/badge.svg)](https://github.com/kylebrodeur/pi-vault-mind/actions/workflows/docs.yml)
+
+Passive Obsidian vault extension for the [pi](https://github.com/mariozechner/pi) agent ecosystem. Watches `@agent` markers in your vault, dispatches forked subagents, and stores results in LanceDB with vector + FTS + graph. Multi-agent "Drop & Forget" workflow.
+
+> Looking for the legacy ledger-first extension (predecessor project)?
+> See [kylebrodeur/pi-qmd-ledger](https://github.com/kylebrodeur/pi-qmd-ledger).
+> This project was renamed twice: `pi-qmd-ledger` → `pi-llm-wiki` (intermediate) → `pi-vault-mind` (current).
+
+## Features
+
+- **Passive File Watcher** — drop `@agent-Miner`, `@agent-Broadcaster`, etc. in any Obsidian note. Save the file. The watcher detects the marker, groups by role, and dispatches isolated subagent forks (`vault-mind-{role}` agents). No chat pollution, no manual triggers.
+- **Multi-Agent Architecture** — five specialist agents under the `vault-mind-{role}` skill naming: **Manager** (interactive orchestrator), **Miner** (research + entity extraction), **Broadcaster** (NotebookLM artifacts), **Heavy-Lifter** (external delegation), **Watcher** (passive file observer).
+- **LanceDB Vector + FTS + Graph** — hybrid semantic + keyword search with automatic entity extraction and BFS graph traversal. All local, no external binaries.
+- **JSONL Source-of-Truth + LanceDB Index** — every fact lives in a durable, human-readable, version-control-friendly `collections/*.jsonl` file. The LanceDB index is derived and rebuildable via `/wiki reindex --all --reembed`.
+- **Bidirectional Obsidian Sync** — substantial entries (`>200 chars` or tagged `decision`/`insight`/`requirement`) auto-write to `Vault/Agent/Inbox/`. Graph entities render as Obsidian Canvas files.
+- **Two-Layer Config** — global (`~/.pi/agent/vault-mind.config.json`) for shared settings, project (`./pi-vault-mind.config.json`) for project-specific knowledge. Works across all projects from any directory.
+- **Interactive Setup Wizard** — `/wiki setup` walks through vault path, embedding provider, and model selection. CLI mode: `--vault`, `--provider`, `--model` flags for scripting.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  User prompt                             │
+│  e.g. "draft login"                      │
+└──────┬──────────────────────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────────┐
+│  Injector regex match                    │
+│  → matches "draft\s+(\S+)"              │
+└──────┬──────────────────────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────────┐
+│  query collections/main.jsonl            │
+│  where tag="login" + inject artifact.md  │
+└──────┬──────────────────────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────────┐
+│  Appended to system prompt               │
+│  → LLM now has pre-fetched context       │
+└─────────────────────────────────────────┘
+
+Data Layer:
+┌─────────────────────────────────────────┐
+│  JSONL WAL (collections/*.jsonl)        │
+│  ─ durable, human-readable, versionable │
+│       │                                  │
+│       ▼ (auto-embed on append)           │
+│  LanceDB (.lancedb/)                    │
+│  ─ vector search + FTS + graph          │
+│       │                                  │
+│       ▼ (graph extraction)               │
+│  Graph Tables (entities + relations)     │
+│  ─ entity linking + traversal            │
+└─────────────────────────────────────────┘
+```
+
+See [`docs/architecture/index.md`](docs/architecture/index.md) for the full agent flow.
+
+## Obsidian Counterparts & Requirements
+
+pi-vault-mind works on any directory, but for the **full Obsidian experience**, you need a few things in Obsidian itself:
+
+### Required: An Obsidian vault
+Just point `/wiki setup` at any directory used as an Obsidian vault. pi-vault-mind auto-detects `.obsidian/` and respects `.obsidian/`, `.git/`, `.trash/`.
+
+### Recommended: Official Obsidian CLI (1.12+)
+
+The [official Obsidian CLI](https://help.obsidian.md/cli) lets you install plugins, themes, and manage vault state from the terminal. **This is the safest, most direct install path** for pi-vault-mind's required plugins.
+
+Install: Open Obsidian → **Settings → General → Command line interface** → enable. Follow the prompt to register the CLI to your system PATH. Restart your terminal. Test: `obsidian help`.
+
+Then run:
+```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
+```
+
+Full walkthrough: see [`docs/OBSIDIAN_SETUP.md`](docs/OBSIDIAN_SETUP.md).
+
+### Recommended: Obsidian Community Plugins
+
+| Plugin | Install ID | Why | Status |
+|---|---|---|---|
+| **obsidian-git** | `obsidian-git` | Auto-commits vault changes for backup & conflict resolution. Heavy-Lifter uses git worktrees for isolated refactors. | Essential |
+| **Breadcrumbs** | `obsidian-breadcrumbs` | Parses typed edges (`agent:related-to`, `agent:derived-from`) in YAML frontmatter. The recommended way to display the agent-extracted knowledge graph in Obsidian's UI. | Highly recommended |
+| **Graph Analysis** | `graph-analysis` | Co-citation discovery, Jaccard similarity on the native Obsidian graph. Surfaces "always cited together but not yet linked" notes — a key agent discovery signal. | Highly recommended |
+| **Actions URI** | `actions-uri` | `x-callback-url` endpoints so the Manager agent can trigger Obsidian UI commands (open notes, run commands) from pi. | Recommended |
+| **obsidian-shellcommands** | `shellcommands` | Bridge from Obsidian events (e.g., file save) to pi agent workflows. Configure a `curl` to `http://127.0.0.1:11435/vault-mind/scan` on file save. | Recommended |
+
+### Recommended: `notesmd-cli` (headless alternative)
+
+For headless operations, CI, or when Obsidian isn't running, use [Yakitrak/notesmd-cli](https://github.com/Yakitrak/notesmd-cli). It does everything the official CLI does but doesn't require Obsidian to be open.
+
+```bash
+brew tap yakitrak/yakitrak && brew install yakitrak/yakitrak/notesmd-cli
+# or scoop, AUR, etc.
+
+notesmd-cli add-vault /path/to/vault
+notesmd-cli create "Note.md" --content "..." --append
+```
+
+Use the official `obsidian` CLI when Obsidian is running; use `notesmd-cli` when it isn't.
+
+### Beta plugins via BRAT
+
+For beta plugins not in the official store:
+
+```bash
+# Install BRAT first
+obsidian plugin:install id=obsidian42-brat enable
+
+# Then add beta plugin URLs via BRAT's interface, or:
+# In Obsidian: Settings → BRAT → Beta Plugin List → Add
+```
+
+### Recommended: kepano/obsidian-skills (pi skills)
+
+Install via the official [`skills` CLI](https://github.com/vercel-labs/skills)
+(pi is a first-class target agent — auto-detected):
+
+```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 agent detection, symlink/copy,
+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
+```
+- `obsidian-markdown` — agent learns Obsidian-flavored markdown syntax
+- `obsidian-bases` — agent learns to generate valid `.base` files (database views)
+- `json-canvas` — agent learns Canvas JSON format (used for our graph sync)
+- `obsidian-cli` — agent learns to use the Obsidian CLI
+- `defuddle` — cleaner markdown extraction from web pages
+
+These skills let the **Miner, Broadcaster, and Heavy-Lifter agents** produce valid Obsidian content.
+
+### Built-in Obsidian features used
+
+| Feature | How pi-vault-mind uses it |
+|---|---|
+| **YAML frontmatter properties** | Strict schema for typed edges (`agent:related-to`, `status: needs-podcast`, `domain:`, `tag:`) |
+| **Callouts** | `> [!info]`, `> [!warning]` for syntheses and contradictions |
+| **Embeds** | `![[Note]]` to transclude summaries into synthesis docs |
+| **Obsidian Bases (`.base`)** | Agent-generated dynamic tables/boards/kanbans in `Agent/Tasks/` |
+| **JSON Canvas (`.canvas`)** | `wiki_sync(format="canvas")` writes entity graph as Canvas JSON |
+| **Obsidian Sync** | Primary sync mechanism across devices |
+
+### Optional: NotebookLM integration (Broadcaster)
+
+The Broadcaster agent can generate podcasts, study guides, and slide decks from vault content via the [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) MCP server. Requires Google account login.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- **Node.js** 20+ (matches `engines` in `package.json`)
+- **Embedding Provider** — choose one:
+  - `@xenova/transformers` — built-in, no external deps (uses all-MiniLM-L6-v2, offline-capable)
+  - `ollama` — requires Ollama running locally with `embeddinggemma` (higher quality)
+
+### 1. Install with pi
+
+```bash
+pi install npm:pi-vault-mind              # latest
+pi install npm:pi-vault-mind@0.7.0        # pinned
+pi -e npm:pi-vault-mind                   # try without installing
+```
+
+Or from git:
+
+```bash
+pi install git:git@github.com:kylebrodeur/pi-vault-mind
+```
+
+### 2. Configure (interactive wizard)
+
+```
+/wiki setup
+```
+
+This walks you through: vault path → embedding provider → Ollama model (if applicable).
+
+Or via CLI for scripting:
+
+```bash
+/wiki setup --vault /home/you/Obsidian/MyVault --provider transformers
+/wiki setup --vault /home/you/Obsidian/MyVault --provider ollama --model embeddinggemma
+```
+
+Config is written to `~/.pi/agent/vault-mind.config.json` — it applies globally
+no matter which project directory you open pi from.
+
+You can re-run `/wiki setup` anytime to view or change settings.
+
+### 3. Start using
+
+```
+append_wiki(collection="main", mode="autopilot", entry={"id":"1","domain":"auth","fact":"JWT tokens expire after 1 hour","tag":"security"})
+wiki_search(collection="main", query="token expiry")
+```
+
+Entries are automatically embedded and stored in LanceDB. If graph is enabled, entities and relations are also extracted.
+
+### 4. Adapt the config
+
+Edit `pi-vault-mind.config.json` to match your domain:
+
+```json
+{
+  "version": 2,
+  "collections": {
+    "main": {
+      "path": "collections/main.jsonl",
+      "schema": ["id", "domain", "source", "fact", "tag", "artifact"],
+      "dedupField": "fact"
+    }
+  },
+  "injectors": [
+    {
+      "name": "draft-context",
+      "regex": "draft\\s+(\\S+)",
+      "collection": "main",
+      "filterField": "tag"
+    }
+  ],
+  "wiki": {
+    "dataDir": ".lancedb",
+    "embedding": {
+      "provider": "transformers",
+      "ollamaModel": "embeddinggemma",
+      "ollamaHost": "http://127.0.0.1:11434"
+    },
+    "ftsEnabled": true,
+    "graph": { "enabled": true, "canvasSync": false }
+  }
+}
+```
+
+## Example domains
+
+### Research project
+
+```json
+{
+  "collections": {
+    "findings": {
+      "path": "research/findings.jsonl",
+      "schema": ["id", "paper", "claim", "evidence", "confidence", "tag"],
+      "dedupField": "claim"
+    }
+  },
+  "injectors": [
+    {
+      "name": "lit-review",
+      "regex": "review\\s+(\\S+)",
+      "collection": "findings",
+      "filterField": "tag",
+      "artifactPath": "research/synthesis.md"
+    }
+  ]
+}
+```
+
+### Decision log
+
+```json
+{
+  "collections": {
+    "decisions": {
+      "path": "decisions/log.jsonl",
+      "schema": [
+        "id",
+        "date",
+        "context",
+        "decision",
+        "rationale",
+        "status",
+        "owner"
+      ],
+      "dedupField": "decision"
+    }
+  },
+  "injectors": [
+    {
+      "name": "decide",
+      "regex": "decide\\s+(\\S+)",
+      "collection": "decisions",
+      "filterField": "context"
+    }
+  ]
+}
+```
+
+## Tools
+
+| Tool               | Purpose                                                 |
+| ------------------ | ------------------------------------------------------- |
+| `wiki_search`       | Semantic search via LanceDB (vector + FTS)       |
+| `wiki_fts_search`    | Exact keyword full-text search (Tantivy BM25)      |
+| `wiki_graph_query`  | Traverse entity connections in the graph layer          |
+| `wiki_status`       | Show LanceDB table sizes and health                     |
+| `query_wiki`      | Deterministic JSONL search by collection name           |
+| `append_wiki`     | Append with strict/gated/autopilot modes + dual-write   |
+| `configure_wiki`  | Read or update config at runtime                        |
+| `describe_wiki`   | Introspect schema, count, and sample entries            |
+| `wiki_stats`      | Dashboard: counts, sizes, LanceDB status                |
+| `wiki_export`     | Export to JSON, CSV, or Markdown                        |
+| `promote_wiki`    | Promote entries between collections via pending queue  |
+
+## Commands
+
+| Command                        | Purpose                                                  |
+| ------------------------------ | -------------------------------------------------------- |
+| `/wiki help`                   | Show usage help                                          |
+| `/wiki setup`                  | **Interactive global config wizard** (vault, embedding) |
+| `/wiki init`                   | Scaffold project config + collections                    |
+| `/wiki validate`               | Health check LanceDB, config, and all collection paths   |
+| `/wiki approve [collection]`   | Batch-review pending entries                              |
+| `/wiki settings`               | Open interactive settings dashboard                       |
+| `/wiki audit`                  | Audit config for missing defaults                         |
+| `/wiki reindex [--all] [--reembed]` | Rebuild FTS + vector indexes                       |
+| `/wiki collection select`      | Select active collection (shortcut: ctrl+alt+l)          |
+| `/wiki collection create`      | Interactive wizard to create a new collection              |
+| `/wiki injector create`        | Interactive wizard to create a new injector                |
+| `/wiki context enable \| disable \| status` | Manage pi-context integration              |
+| `/wiki embedding status \| use \| model \| models \| pull` | Manage embedding provider |
+| `/wiki watcher start \| stop \| status` | Manage the passive file watcher                  |
+| `/wiki server status` | Show HTTP server status, port, and uptime |
+
+## Documentation
+
+> **Full docs site:** [kylebrodeur.github.io/pi-vault-mind](https://kylebrodeur.github.io/pi-vault-mind/) (GH Pages, built from [`docs/`](docs/)).
+> The links below point to the source files in this repository.
+
+### Getting started
+
+| Doc | Description |
+|---|---|
+| [docs/QUICKSTART.md](docs/QUICKSTART.md) | **Fastest path** — 60-second install, setup, first append |
+| [docs/INSTALL.md](docs/INSTALL.md) | **Canonical install playbook** — all 5 layers (pi ext, skills, Obsidian, config, external CLIs) |
+| [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) | End-to-end workflow + daily "drop & forget" usage |
+| [docs/WALKTHROUGH_PROMPT.md](docs/WALKTHROUGH_PROMPT.md) | Paste-into-pi guided setup with checkpoints between phases |
+
+### Architecture & design
+
+| Doc | Description |
+|---|---|
+| [docs/AGENTS.md](docs/AGENTS.md) | Agent Roster and Multi-Agent Architecture ("Fork & Review" model) |
+| [docs/EXTENSION_WIRING.md](docs/EXTENSION_WIRING.md) | Extension dependencies, runtime wiring, auto-install patterns |
+| [docs/DISPATCHER_SPEC.md](docs/DISPATCHER_SPEC.md) | Technical spec for the passive file-watcher and subagent routing |
+| [docs/PASSIVE_INTERACTION_MODEL.md](docs/PASSIVE_INTERACTION_MODEL.md) | "Fork & Dispatch" model — why we don't pollute the main chat session |
+| [docs/PASSIVE_INGESTION_WORKFLOW.md](docs/PASSIVE_INGESTION_WORKFLOW.md) | The "Drop & Forget" document ingestion pipeline |
+| [docs/NOTEBOOKLM_PIPELINE.md](docs/NOTEBOOKLM_PIPELINE.md) | NotebookLM automated podcast and study guide generation |
+| [docs/OBSIDIAN_SETUP.md](docs/OBSIDIAN_SETUP.md) | Recommended Obsidian vault structure, plugins, and CLI |
+
+### Reference
+
+| Doc | Description |
+|---|---|
+| [skills/vault-mind/SKILL.md](skills/vault-mind/SKILL.md) | The Manager skill — what pi auto-loads about this extension |
+| [docs/CHANGELOG.md](docs/CHANGELOG.md) | Version history (rename from `pi-llm-wiki` to `pi-vault-mind` was v0.7.0) |
+| [docs/reference/tools.md](docs/reference/tools.md) | The 11 `wiki_*` and `query_wiki`/`append_wiki`/etc. tools — parameters, return shapes |
+| [docs/reference/commands.md](docs/reference/commands.md) | Full `/wiki` slash command tree |
+| [docs/reference/configuration.md](docs/reference/configuration.md) | The complete `pi-vault-mind.config.json` schema |
+| [docs/reference/skill.md](docs/reference/skill.md) | Manifest of all bundled skills and their trigger phrases |
+
+### Testing
+
+| Doc | Description |
+|---|---|
+| [docs/TESTING.md](docs/TESTING.md) | Test plan for agent / human / HITL personas, regression suite |
+| [docs/E2E_MANUAL_TEST.md](docs/E2E_MANUAL_TEST.md) | Manual end-to-end verification procedure (watcher → dispatch → vault) |
+
+### Development
+
+| Doc | Description |
+|---|---|
+| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | Dev setup, testing, and commit conventions |
+| [docs/dev/PUBLISHING.md](docs/dev/PUBLISHING.md) | How to publish this extension to npm |
+| [docs/dev/FUTURE_WORK.md](docs/dev/FUTURE_WORK.md) | Roadmap — codegraph integration, pagination, TUI rendering, etc. |
+
+### Research
+
+| Doc | Description |
+|---|---|
+| [docs/COMPETITOR_COMPARISON.md](docs/COMPETITOR_COMPARISON.md) | Tier 1/2/3 comparison vs. other Obsidian-LLM tools (22 competitors) |
+| [docs/research/naming-decisions.md](docs/research/naming-decisions.md) | Historical record of the 2026-06-06 decision to name the project `pi-vault-mind` |
+| [docs/research/obsidian-links-reviewed.csv](docs/research/obsidian-links-reviewed.csv) | Curated subset of starred Obsidian repos with adoption verdicts |
+
+### Archive
+
+| Doc | Description |
+|---|---|
+| [docs/_archive/](docs/_archive/) | Historical docs kept for context (e.g. the `pi-llm-wiki` → `pi-vault-mind` rename audit) |
+| [docs/plans/legacy-audit.md](docs/plans/legacy-audit.md) | The 2026-06-08 legacy-terminology audit (139 findings, 13 blockers) and its resolution log (in the repo, not on the docs site) |
+
+## Contributing
+
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for dev setup, testing, and commit conventions.
+
+## License
+
+MIT — see [LICENSE](LICENSE) (or package.json).

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/dist/src/commands.d.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ServerState } from "./server.js";
+export declare const auditConfig: (ctx: ExtensionContext) => Promise<void>;
+export declare const selectActiveCollection: (ctx: ExtensionContext) => Promise<void>;
+export declare const watcherState: import("./watcher.js").WatcherState;
+/** Module-level server state, referenced by the /wiki server command.
+ *  Port is set when the server starts in index.ts. */
+export declare const serverState: ServerState;
+export declare const registerCommands: (pi: ExtensionAPI) => void;