pi-vault-mind 0.16.29 → 0.16.31

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.16.31 — 2026-08-28
+
+### Added
+
+- **One-command vault setup.** `pvm setup [vault-path]` installs the complete vault-local extension, task/subagent, NotebookLM, and curated skill profile before merge-safely scaffolding Vault Mind, model-router, and main-agent configuration.
+- **Resource-only repair.** `pvm setup --resources-only [vault-path]` refreshes extensions, tools, and skills without changing vault configuration.
+- **Dependency audit and repair.** `pvm check-deps [--fix] [--strict] [--obsidian] [vault-path]` verifies the host runtime, vault-local extensions, curated skills, and optional content or Obsidian tooling.
+
+### Changed
+
+- **Pi 0.84.3 runtime.** Development and compatibility checks now target `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` 0.84.3.
+- **Node.js 22.19 runtime floor.** Package metadata, dependency audits, and setup documentation now match the minimum Node version required by Pi 0.84.3.
+- **Current task and subagent extensions.** New vault setup installs `@juicesharp/rpiv-todo` 2.7.1 and `pi-subagents` 0.58.0, while removing the obsolete `@tintinweb/pi-tasks` package.
+- **Pi Context 2.1.2 integration.** Session-start and turn-end capture now use the current checkpoint and context-event APIs.
+- **Curated package surface.** Published Pi discovery exposes only Vault Mind usage, setup, and specialist content skills; internal release, plugin-development, and test workflows are no longer shipped as runtime skills.
+- **Reproducible package tooling.** The repository now pins pnpm 10.34.5 so Corepack does not select an incompatible pnpm major during clean release builds.
+
+### Fixed
+
+- **Quiet main-agent startup.** Automatic context management initializes without injecting a synthetic `/acm` user message into a new session.
+- **Stable Pi launcher selection.** Setup avoids transient `npx` binaries and consistently provisions the vault-local agent directory with the installed Pi runtime.
+
+### Verification
+
+- Node 24.19.0 with pnpm 10.34.5: dependency install, core build, and package-scoped Biome check completed successfully.
+- Full core test suite: 937/937 passing.
+- Packed `pi-vault-mind-0.16.31.tgz` successfully; the packaged `pvm --help` executable ran and exposed the `run`, `setup`, and `check-deps` commands.
+
+## 0.16.30 — 2026-08-27
+
+### Added
+
+- **First-class `pvm` executable.** The npm package now exposes `pvm run [vault-path]`; it uses the current directory when the vault path is omitted and supports both global installation and `npx pi-vault-mind run`.
+- **Explicit launch modes.** `pvm run` stays in the current terminal by default, with `--same-terminal`, `--new-window`, and `--auto` overrides.
+
+### Fixed
+
+- **Portable vault launcher.** `vault-pi.sh` now handles interactive terminals directly, normalizes relative vault paths before deriving runtime state, removes inline-session PID files on exit, and rejects unknown flags instead of treating them as vault paths.
+
+### Verification
+
+- Root and Obsidian builds passed; full test suite: 910/910 passing.
+- `npm pack` includes `scripts/pvm.mjs` as an executable, and `npm exec` resolved the packed tarball's `pvm` command successfully.
+
 ## 0.16.29 — 2026-08-27
 
 ### Fixed

package/README.md

@@ -176,7 +176,7 @@ The Broadcaster agent can generate podcasts, study guides, and slide decks from
 
 ### Prerequisites
 
-- **Node.js** 20+ (matches `engines` in `package.json`)
+- **Node.js** 22.19.0+ (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)
@@ -190,32 +190,66 @@ The Broadcaster agent can generate podcasts, study guides, and slide decks from
 > bearer token are private to whoever owns it. (A standalone PyPI package for the
 > server may come later.)
 
-### 1. Install with pi
+### 1. Install and set up the vault-local runtime
+
+Install the first-class `pvm` CLI once, then run setup against a vault:
 
 ```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
+npm install --global pi-vault-mind
+pvm setup /path/to/your/vault
+pvm run /path/to/your/vault
 ```
 
-Or from git:
+`pvm setup` is safe to repeat. It installs or updates the required Vault Mind,
+context, model-routing, task, and subagent extensions inside
+`<vault>/.vault-mind/.pi/agent/`; installs the curated `obsidian-cli`,
+`obsidian-markdown`, `obsidian-bases`, and `json-canvas` skills; and
+merge-safely scaffolds Vault Mind, model-router, and main-agent configuration.
+Existing user configuration, collections, model choices, and `system.md` are
+preserved.
+
+Refresh only extensions, tools, and skills without touching vault
+configuration:
 
 ```bash
-pi install git:git@github.com:kylebrodeur/pi-vault-mind
+pvm setup --resources-only /path/to/your/vault
 ```
 
-### 2. Configure (interactive wizard)
+Audit the isolated runtime without changing it, or repair it in place:
 
-```
-/vm setup
+```bash
+pvm check-deps /path/to/your/vault
+pvm check-deps --fix /path/to/your/vault
 ```
 
-This configures the current vault's setup surface: vault path, embedding
-provider details, folder layout, and scaffolding.
+Add `--strict` to fail when optional tools are missing and `--obsidian` to
+include recommended Obsidian plugin checks.
 
-Or via CLI for scripting/repair:
+Run either mode without a global installation:
 
 ```bash
+npx --yes pi-vault-mind setup /path/to/your/vault
+npx --yes pi-vault-mind run /path/to/your/vault
+```
+
+Installing only the Pi extension remains supported:
+
+```bash
+pi install npm:pi-vault-mind
+pi -e npm:pi-vault-mind
+```
+
+### 2. Configure interactively when needed
+
+Inside Pi, use the wizard to choose or change embedding providers, folder
+layout, and other user-facing settings:
+
+```text
+/vm setup
+```
+For a non-interactive repair inside Pi:
+
+```text
 /vm setup --vault /home/you/Obsidian/MyVault --remoteUrl https://your-embedding-service-url.example.com --model embeddinggemma
 ```
 
@@ -269,6 +303,174 @@ Edit `<vault>/.vault-mind/vault-mind.config.json` to match your domain:
 }
 ```
 
+## Using Vault Mind agent identities
+
+Vault Mind keeps the interactive Pi session on the unrestricted `main` persona
+unless you explicitly select a specialist boundary. Bundled specialist skills
+are available resources; merely loading them does not change the active
+persona.
+
+### Start the vault-local main agent
+
+From the vault directory, start Pi in the current terminal:
+
+```bash
+pvm run
+```
+
+You can launch a different vault from anywhere or use the package without a
+global install:
+
+```bash
+pvm run /path/to/your/vault
+npx --yes pi-vault-mind run /path/to/your/vault
+```
+
+`pvm run` defaults to the current terminal. This is the recommended Obsidian
+Terminal profile command. Use a vault-path placeholder supplied by the plugin,
+or provide the vault's absolute path. Override the launch mode when needed:
+
+```bash
+pvm run --same-terminal /path/to/your/vault
+pvm run --new-window /path/to/your/vault
+pvm run --auto /path/to/your/vault
+```
+
+`--new-window` opens a dedicated Terminal/iTerm window. `--auto` uses the
+current terminal when attached to a TTY and falls back to a new window
+otherwise. The packaged shell launcher remains available for direct use as
+`scripts/vault-pi.sh`.
+
+In every mode, the launcher runs Pi inside the target vault with its
+configuration isolated under `<vault>/.vault-mind/.pi/agent/`. It also prevents
+two launcher-managed Pi processes from running for the same vault and removes
+the PID file when an inline session exits.
+
+Check the active persona after startup:
+
+```text
+/vm identity status
+```
+
+A normal main-agent session reports:
+
+```text
+Persona: main
+Effective boundary: none (main agent)
+```
+
+`Injection` may report `enabled` or `disabled`. An enabled injector still
+applies no boundary while the persona is `main`.
+
+### Use specialist agents without changing the main session
+
+Normally, leave the interactive session on `main` and dispatch specialist work
+through the passive watcher:
+
+```text
+@agent-Miner
+Research and extract the durable facts from this note.
+```
+
+The watcher runs that work as an isolated specialist job. It does not turn the
+interactive terminal into the Miner persona. The same distinction applies to
+`@agent-Broadcaster`, `@agent-Manager`, and `@agent-Heavy-Lifter`.
+
+### Explicitly change the interactive persona
+
+Use an identity boundary only when the current interactive session itself
+should follow a specialist capability contract:
+
+```text
+/vm identity set miner
+/vm identity set broadcaster
+/vm identity set manager
+/vm identity set heavy-lifter
+```
+
+| Persona | Intended interactive boundary |
+|---|---|
+| `main` | Unrestricted primary agent with the full configured toolset |
+| `manager` | Orchestrates collections, publishing, and subagents; does not run Bash |
+| `miner` | Extracts and stores knowledge; does not run Bash or publish |
+| `broadcaster` | Produces presentation artifacts; does not run Bash or write durable knowledge |
+| `heavy-lifter` | Performs file and Bash work in isolation; does not write durable knowledge or publish |
+
+`/vm identity set <role>` persists the selected persona, enables boundary
+injection, and applies on the next agent turn.
+
+Use the remaining controls to inspect or suspend that selection:
+
+```text
+/vm identity status
+/vm identity off
+/vm identity on
+```
+
+- `off` disables boundary injection without discarding the selected persona.
+- `on` re-enables the configured persona boundary on the next agent turn.
+- `status` shows the configured persona, injection switch, effective boundary,
+  and any environment overrides.
+
+Restore the safe main-agent default with:
+
+```text
+/vm identity set main
+/vm identity off
+/vm identity status
+```
+
+The final status should show `Effective boundary: none (main agent)`.
+
+### Configuration and environment overrides
+
+Identity controls are stored in the vault-local configuration:
+
+```json
+{
+  "vaultMind": {
+    "identities": {
+      "activeRole": "main",
+      "injectBoundaries": false
+    }
+  }
+}
+```
+
+The canonical path is
+`<vault>/.vault-mind/vault-mind.config.json` under
+`vaultMind.identities`. Identity commands preserve any existing
+`vaultMind.identities.roles` allowlists.
+
+Launch automation and explicit specialist forks can override the saved values
+for one process:
+
+```bash
+VAULT_MIND_AGENT_ROLE=miner VAULT_MIND_IDENTITY_INJECTION=on pi
+VAULT_MIND_IDENTITY_INJECTION=off pi
+```
+
+`VAULT_MIND_AGENT_ROLE` takes precedence over `activeRole`.
+`VAULT_MIND_IDENTITY_INJECTION=off` suppresses every boundary, while `on`
+enables the explicitly selected role. Missing, `main`, `none`, and unknown
+roles all resolve safely to the unrestricted main agent.
+
+### Troubleshoot an unexpected specialist boundary
+
+1. Run `/vm identity status` and check both the configured persona and any
+   reported environment overrides.
+2. If an environment override is present, exit Pi, unset
+   `VAULT_MIND_AGENT_ROLE` and `VAULT_MIND_IDENTITY_INJECTION`, then relaunch.
+3. Run `/vm identity set main`, followed by `/vm identity off`.
+4. Send the next agent turn and re-run `/vm identity status`; boundary changes
+   take effect on the next turn.
+5. Confirm Pi was started for the intended vault and uses
+   `<vault>/.vault-mind/.pi/agent/` as `PI_CODING_AGENT_DIR`.
+
+Do not edit `SYSTEM.md` or an agent skill to change the interactive identity.
+Those files provide operating instructions and resources; persona selection
+belongs in `vaultMind.identities` or an explicit environment override.
+
 ## Example domains
 
 ### Research project

package/dist/src/commands.js

@@ -259,7 +259,7 @@ const handleInit = async (_args, ctx, pi) => {
         const existing = JSON.parse(fs.readFileSync(cfgDest, "utf-8"));
         existing.extensionCompatibility = existing.extensionCompatibility || {};
         existing.extensionCompatibility["pi-context"] = {
-            tagPatterns: [],
+            checkpointPatterns: [],
             enhanceInjectors: false,
             autoEnableAcm: true,
             indexContextEvents: true,
@@ -314,7 +314,7 @@ const handleValidate = async (_args, ctx, pi) => {
     const contextCfg = getPiContextConfig(cfg);
     const willCapture = hasContext && contextCfg.enabled;
     lines.push("", "🧩 Extension Integrations:", "   • pi-context:");
-    lines.push(`       - Tools installed: ${hasContext ? "✅ Yes (context_tag, context_log, context_checkout)" : "❌ No"}`);
+    lines.push(`       - Tools installed: ${hasContext ? "✅ Yes (context_checkpoint, context_timeline, context_compact)" : "❌ No"}`);
     lines.push(`       - Config enabled: ${contextCfg.enabled ? "✅ Yes" : "❌ No"}`);
     lines.push(`       - Will capture events: ${willCapture ? "✅ Yes — on next turn" : "❌ No"}`);
     if (hasContext && !contextCfg.enabled)
@@ -1122,10 +1122,10 @@ const handleContext = async (args, ctx, pi) => {
                 `  - Config enabled: ${piContextCfg.enabled ? "✅" : "❌"}`,
                 `  - Will capture on next turn: ${willCapture ? "✅ Yes" : "❌ No"}`,
                 "",
-                `Tag Patterns: ${piContextCfg.tagPatterns?.length || 0}`,
-                ...(piContextCfg.tagPatterns?.length
-                    ? piContextCfg.tagPatterns.map((p) => `  • "${p}"`)
-                    : ["  (none — no tag-based lookups)"]),
+                `Checkpoint Patterns: ${piContextCfg.checkpointPatterns?.length || 0}`,
+                ...(piContextCfg.checkpointPatterns?.length
+                    ? piContextCfg.checkpointPatterns.map((p) => `  • "${p}"`)
+                    : ["  (none — no checkpoint-based lookups)"]),
                 "",
                 `Enhance Injectors: ${piContextCfg.enhanceInjectors ? "Yes" : "No"}`,
                 `autoEnableAcm: ${piContextCfg.autoEnableAcm ? "Yes" : "No"}`,
@@ -1163,7 +1163,7 @@ const _toggleContext = (cfgPath, enabled) => {
     const existing = JSON.parse(fs.readFileSync(cfgPath, "utf-8"));
     existing.extensionCompatibility = existing.extensionCompatibility || {};
     existing.extensionCompatibility["pi-context"] = {
-        tagPatterns: [],
+        checkpointPatterns: [],
         enhanceInjectors: false,
         autoEnableAcm: true,
         indexContextEvents: true,

package/dist/src/context-capture.d.ts

@@ -1,18 +1,23 @@
 /**
- * Context Capture — Layer 4 auto-trigger pi-context /acm.
+ * Context Capture — Layer 4 pi-context /acm reminder.
+ *
+ * On extension load, reminds the human to run /acm to enable agentic context
+ * management. Does NOT inject /acm as a user or model message; the reminder
+ * is an unobtrusive UI notification only.
  *
- * On extension load, auto-sends /acm to enable agentic context management.
  * Injects context_checkpoint instructions into agent task prompts.
  *
  * Note: context_compact requires CommandCtx (only in main session, not
  * subagent forks). Subagent forks use context_checkpoint and context_timeline.
  */
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 /**
- * Auto-send /acm on extension load to enable agentic context management
- * for the Manager session.
+ * Notify the human to run /acm to enable agentic context management.
+ *
+ * Uses ctx.ui.notify — a transient TUI notification that never enters the
+ * session history and is never delivered to the model.
  */
-export declare function enableACM(pi: ExtensionAPI): void;
+export declare function notifyAcmReminder(ctx: ExtensionContext): void;
 /**
  * Build context_checkpoint instructions to inject into a dispatch task prompt.
  *

package/dist/src/context-capture.js

@@ -1,19 +1,24 @@
 /**
- * Context Capture — Layer 4 auto-trigger pi-context /acm.
+ * Context Capture — Layer 4 pi-context /acm reminder.
+ *
+ * On extension load, reminds the human to run /acm to enable agentic context
+ * management. Does NOT inject /acm as a user or model message; the reminder
+ * is an unobtrusive UI notification only.
  *
- * On extension load, auto-sends /acm to enable agentic context management.
  * Injects context_checkpoint instructions into agent task prompts.
  *
  * Note: context_compact requires CommandCtx (only in main session, not
  * subagent forks). Subagent forks use context_checkpoint and context_timeline.
  */
-// ── ACM auto-trigger ──────────────────────────────────────────────────────────
+// ── ACM reminder notification ─────────────────────────────────────────────────
 /**
- * Auto-send /acm on extension load to enable agentic context management
- * for the Manager session.
+ * Notify the human to run /acm to enable agentic context management.
+ *
+ * Uses ctx.ui.notify — a transient TUI notification that never enters the
+ * session history and is never delivered to the model.
  */
-export function enableACM(pi) {
-    pi.sendUserMessage("/acm", { deliverAs: "followUp" });
+export function notifyAcmReminder(ctx) {
+    ctx.ui.notify("Run /acm to enable agentic context management for this session.", "info");
 }
 // ── Checkpoint instructions for agent task prompts ────────────────────────────
 /**

package/dist/src/events.d.ts

@@ -1,13 +1,13 @@
 import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, TurnEndEvent } from "@earendil-works/pi-coding-agent";
 /**
- * Handles before_agent_start to inject collection entries and pi-context tag matches
+ * Handles before_agent_start to inject collection entries and pi-context checkpoint matches
  * into the system prompt.
  */
 export declare const handleBeforeAgentStart: (pi: ExtensionAPI, event: BeforeAgentStartEvent, ctx: ExtensionContext) => Promise<{
     systemPrompt?: string;
 } | undefined>;
 /**
- * Handles turn_end to capture pi-context events and append them to the
+ * Handles turn_end to capture pi-context checkpoints and summaries in the
  * context_events collection.
  */
 export declare const handleTurnEnd: (pi: ExtensionAPI, _event: TurnEndEvent, ctx: ExtensionContext) => Promise<void>;