pi-vault-mind 0.8.7 → 0.9.0

package/dist/src/commands.js

@@ -5,7 +5,7 @@ import { Container, SelectList, Text } from "@earendil-works/pi-tui";
 import * as lancedb from "@lancedb/lancedb";
 import { getActiveCollection, setActiveCollection } from "./state.js";
 import { DEFAULT_CONFIG } from "./types.js";
-import { CONFIG_FILES, EXT_ROOT, collectionNames, ensureDir, findConfig, getPiContextConfig, hasPiContextTools, loadConfig, } from "./utils.js";
+import { CONFIG_FILES, EXT_ROOT, collectionNames, ensureDir, findConfig, getPiContextConfig, hasPiContextTools, loadConfig, resolveInitCollectionName, } from "./utils.js";
 import { updateActiveCollectionWidget } from "./widget.js";
 import { cancelJobHelper, listJobs, retryJob, } from "./agent-queue.js";
 import { revokeToken, rotateToken } from "./auth.js";
@@ -23,8 +23,7 @@ import { createWatcherState, getWatcherStatus, startWatcher, stopWatcher } from
 // ── Shared helpers ───────────────────────────────────────────────────────────
 const VM_USAGE = [
     "**pi-vault-mind Commands**",
-    "",
-    "  /vm init                    Scaffold config + collections",
+    "  /vm init [--collection <name>] Scaffold config + collections (default collection path uses vault name)",
     "  /vm validate                Check LanceDB, config, and collection health",
     "  /vm validate --audit         Audit config for missing defaults",
     "  /vm approve [collection]    Batch-review pending entries",
@@ -200,6 +199,15 @@ const handleInit = async (_args, ctx, pi) => {
     const created = [];
     const updated = [];
     const skipped = [];
+    const initTokens = _args.trim().split(/\s+/).filter(Boolean);
+    let requestedCollection;
+    for (let i = 0; i < initTokens.length; i++) {
+        if (initTokens[i] === "--collection") {
+            requestedCollection = initTokens[i + 1];
+            i++;
+        }
+    }
+    const initCollection = resolveInitCollectionName(ctx.cwd, requestedCollection);
     const ensureFile = (dest, tmpl) => {
         if (fs.existsSync(dest)) {
             skipped.push(dest);
@@ -216,7 +224,7 @@ const handleInit = async (_args, ctx, pi) => {
             version: 2,
             collections: {
                 main: {
-                    path: "collections/main.jsonl",
+                    path: `collections/${initCollection}.jsonl`,
                     schema: ["id", "domain", "source", "fact", "tag", "artifact"],
                     dedupField: "fact",
                 },
@@ -284,7 +292,7 @@ const handleInit = async (_args, ctx, pi) => {
     if (skipped.length) {
         msg.push("", "Skipped (already exist):", ...skipped.map((s) => `  • ${path.relative(ctx.cwd, s)}`));
     }
-    msg.push("", '💡 Tip: Tell the agent "Remember: [fact]" to auto-append to the main collection!');
+    msg.push("", `💡 Tip: default collection file is collections/${initCollection}.jsonl (override with /vm init --collection <name>).`);
     if (ctx.hasUI) {
         ctx.ui.notify(msg.join("\n"), "info");
     }
@@ -1584,6 +1592,11 @@ export const registerCommands = (pi) => {
             const subcommand = words[0];
             if (words.length >= 2) {
                 const prefix = words[1] || "";
+                if (subcommand === "init") {
+                    return ["--collection"]
+                        .filter((c) => c.startsWith(prefix))
+                        .map((c) => ({ label: c, value: c, description: `init ${c}` }));
+                }
                 if (subcommand === "embedding") {
                     return ["status", "use", "model", "models", "pull", "cloud"]
                         .filter((c) => c.startsWith(prefix))

package/dist/src/server.js

@@ -30,7 +30,7 @@ import { authoriseRequest, resolveAuthToken } from "./auth.js";
 import { GITIGNORE_ENTRIES } from "./commands.js";
 import { searchHybrid, upsertEntry } from "./lance.js";
 import { DEFAULT_CONFIG } from "./types.js";
-import { EXT_ROOT, ensureDir, expandHome, findConfig, loadConfig, shrinkHome } from "./utils.js";
+import { ensureDir, expandHome, findConfig, loadConfig, resolveInitCollectionName, shrinkHome, } from "./utils.js";
 import { processQueue, scanFile, startWatcher, stopWatcher } from "./watcher.js";
 export function createServerState(port = 11435) {
     return { server: null, wss: null, port, startTime: 0 };
@@ -493,22 +493,43 @@ function handleVmInit(req, res) {
             res.end(JSON.stringify({ error: `Vault path does not exist: ${vaultPath}` }));
             return;
         }
+        const initCollection = resolveInitCollectionName(vaultPath, parsed.collection);
         // Scaffold project config
         const cfgPath = path.join(vaultPath, "pi-vault-mind.config.json");
         if (!fs.existsSync(cfgPath)) {
-            const tmpl = path.join(EXT_ROOT, "templates", "pi-vault-mind.config.json");
-            if (fs.existsSync(tmpl)) {
-                fs.copyFileSync(tmpl, cfgPath);
-            }
-            else {
-                fs.writeFileSync(cfgPath, `${JSON.stringify({ version: 2, collections: DEFAULT_CONFIG.collections, injectors: DEFAULT_CONFIG.injectors, vaultMind: DEFAULT_CONFIG.vaultMind }, null, 2)}\n`, "utf-8");
-            }
-        }
-        // Scaffold collections dir
-        const collDir = path.join(vaultPath, "collections");
-        if (!fs.existsSync(collDir))
-            fs.mkdirSync(collDir, { recursive: true });
-        for (const [name, def] of Object.entries(DEFAULT_CONFIG.collections)) {
+            const tmpl = {
+                version: 2,
+                collections: {
+                    main: {
+                        path: `collections/${initCollection}.jsonl`,
+                        schema: ["id", "domain", "source", "fact", "tag", "artifact"],
+                        dedupField: "fact",
+                    },
+                    pending: { path: "collections/pending.jsonl", schema: "main" },
+                    context_events: {
+                        path: "collections/context_events.jsonl",
+                        schema: ["id", "type", "session_entry_id", "content", "timestamp", "tags"],
+                        dedupField: "id",
+                    },
+                },
+                injectors: [
+                    {
+                        name: "draft-context",
+                        regex: "draft\\s+(\\S+)",
+                        collection: "main",
+                        filterField: "tag",
+                        artifactPath: "collections/artifact.md",
+                    },
+                ],
+                vaultMind: DEFAULT_CONFIG.vaultMind,
+            };
+            fs.writeFileSync(cfgPath, `${JSON.stringify(tmpl, null, 2)}\n`, "utf-8");
+        }
+        // Scaffold collections dir from config
+        const projectCfg = JSON.parse(fs.readFileSync(cfgPath, "utf-8"));
+        for (const def of Object.values(projectCfg.collections || {})) {
+            if (!def.path)
+                continue;
             const p = path.join(vaultPath, def.path);
             if (!fs.existsSync(p)) {
                 fs.mkdirSync(path.dirname(p), { recursive: true });

package/dist/src/settings-ui.d.ts

@@ -1,4 +1,12 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+export interface ObsidianPluginRequirement {
+    id: string;
+    label: string;
+    required: boolean;
+    reason: string;
+}
+export declare const getMissingOnboardingPlugins: (vaultPath: string) => ObsidianPluginRequirement[];
+export declare const buildPluginInstallGuidance: (plugins: ObsidianPluginRequirement[]) => string;
 export declare const detectVaultFromCwd: (cwd: string) => string | null;
 export declare const createCollectionWizard: (ctx: ExtensionContext) => Promise<void>;
 export declare const createInjectorWizard: (ctx: ExtensionContext) => Promise<void>;

package/dist/src/settings-ui.js

@@ -1,7 +1,158 @@
+import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { MODAL_TOKEN_ENV, createModalClient, modalUrl, resolveModalToken } from "./modal-config.js";
 import { collectionNames, findConfig, getGlobalConfigPath, loadConfig, shrinkHome, } from "./utils.js";
+const ONBOARDING_PLUGIN_REQUIREMENTS = [
+    {
+        id: "obsidian42-brat",
+        label: "BRAT (Beta Reviewer's Auto-update Tester)",
+        required: true,
+        reason: "required to install obsidian-pi-vault-mind (not yet in community registry)",
+    },
+    {
+        id: "obsidian-pi-vault-mind",
+        label: "Vault Mind plugin",
+        required: true,
+        reason: "native setup/status/chat UI and local bridge controls",
+    },
+    {
+        id: "actions-uri",
+        label: "Actions URI",
+        required: false,
+        reason: "deep-link automation and capture shortcuts",
+    },
+    {
+        id: "obsidian-git",
+        label: "Obsidian Git",
+        required: false,
+        reason: "vault backup and change history safety net",
+    },
+];
+const readEnabledCommunityPlugins = (vaultPath) => {
+    const communityPluginsPath = path.join(vaultPath, ".obsidian", "community-plugins.json");
+    try {
+        const parsed = JSON.parse(fs.readFileSync(communityPluginsPath, "utf-8"));
+        if (!Array.isArray(parsed))
+            return new Set();
+        return new Set(parsed.filter((value) => typeof value === "string"));
+    }
+    catch {
+        return new Set();
+    }
+};
+export const getMissingOnboardingPlugins = (vaultPath) => {
+    const enabled = readEnabledCommunityPlugins(vaultPath);
+    return ONBOARDING_PLUGIN_REQUIREMENTS.filter((plugin) => !enabled.has(plugin.id));
+};
+const hasObsidianCli = () => {
+    try {
+        execFileSync("obsidian", ["help"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const formatExecError = (err) => {
+    if (err && typeof err === "object" && "stderr" in err) {
+        const stderr = err.stderr;
+        if (typeof stderr === "string" && stderr.trim())
+            return stderr.trim();
+        if (stderr instanceof Buffer && stderr.length > 0)
+            return stderr.toString("utf-8").trim();
+    }
+    return err instanceof Error ? err.message : String(err);
+};
+const BRAT_REPO = "kylebrodeur/obsidian-pi-vault-mind";
+const installViaBrat = () => {
+    try {
+        execFileSync("obsidian", ["eval", `app.plugins.getPlugin("obsidian42-brat").addPlugin("${BRAT_REPO}")`], { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: formatExecError(err) };
+    }
+};
+const installObsidianPlugin = (pluginId) => {
+    // vault-mind plugin must be installed via BRAT (not in community registry)
+    if (pluginId === "obsidian-pi-vault-mind") {
+        return installViaBrat();
+    }
+    try {
+        execFileSync("obsidian", ["plugin:install", `id=${pluginId}`, "enable"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: formatExecError(err) };
+    }
+};
+export const buildPluginInstallGuidance = (plugins) => {
+    const bratPlugins = plugins.filter((p) => p.id === "obsidian-pi-vault-mind");
+    const registryPlugins = plugins.filter((p) => p.id !== "obsidian-pi-vault-mind");
+    const lines = ["Install missing Obsidian plugins:", ""];
+    if (registryPlugins.length > 0) {
+        lines.push("CLI (when Obsidian CLI is available):", ...registryPlugins.map((plugin) => `  obsidian plugin:install id=${plugin.id} enable`), "", "Deep links (open each URI):", ...registryPlugins.map((plugin) => `  obsidian://show-plugin?id=${encodeURIComponent(plugin.id)}`), "", "GUI fallback: Obsidian → Settings → Community plugins → Browse");
+    }
+    if (bratPlugins.length > 0) {
+        lines.push("", "Via BRAT (not yet in community registry):", `  Settings → BRAT → "Add Beta plugin" → ${BRAT_REPO}`, `  Or CLI: obsidian eval 'app.plugins.getPlugin("obsidian42-brat").addPlugin("${BRAT_REPO}")'`);
+    }
+    return lines.join("\n");
+};
+const runPluginOnboarding = async (ctx, vaultPath) => {
+    const missingPlugins = getMissingOnboardingPlugins(vaultPath);
+    if (missingPlugins.length === 0) {
+        ctx.ui.notify("Obsidian plugin check: required integration plugins already enabled.", "info");
+        return;
+    }
+    ctx.ui.notify([
+        "Missing Obsidian plugins detected:",
+        ...missingPlugins.map((plugin) => `- ${plugin.label} (${plugin.id})${plugin.required ? " [required]" : " [recommended]"} — ${plugin.reason}`),
+    ].join("\n"), "warning");
+    const cliAvailable = hasObsidianCli();
+    const options = cliAvailable
+        ? [
+            "Install missing plugins now (Obsidian CLI)",
+            "I'll install manually (show commands + URIs)",
+            "Skip plugin setup for now",
+        ]
+        : ["I'll install manually (show commands + URIs)", "Skip plugin setup for now"];
+    const choice = await ctx.ui.select("Obsidian plugin onboarding", options);
+    if (!choice || choice === "Skip plugin setup for now")
+        return;
+    if (choice === "Install missing plugins now (Obsidian CLI)") {
+        const installed = [];
+        const failed = [];
+        for (const plugin of missingPlugins) {
+            const result = installObsidianPlugin(plugin.id);
+            if (result.ok) {
+                installed.push(plugin.id);
+            }
+            else {
+                failed.push({ plugin, error: result.error || "Unknown error" });
+            }
+        }
+        if (installed.length > 0) {
+            ctx.ui.notify([`Installed plugins (${installed.length}):`, ...installed.map((id) => `- ${id}`)].join("\n"), "info");
+        }
+        if (failed.length > 0) {
+            ctx.ui.notify([
+                "Some plugin installs failed:",
+                ...failed.map(({ plugin, error }) => `- ${plugin.id}: ${error}`),
+                "",
+                buildPluginInstallGuidance(failed.map(({ plugin }) => plugin)),
+            ].join("\n"), "warning");
+        }
+        return;
+    }
+    ctx.ui.notify(buildPluginInstallGuidance(missingPlugins), "info");
+};
 export const detectVaultFromCwd = (cwd) => {
     const obsidianDir = path.join(cwd, ".obsidian");
     try {
@@ -91,6 +242,60 @@ export const createInjectorWizard = async (ctx) => {
     fs.writeFileSync(cfgPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
     ctx.ui.notify(`✅ Injector "${name}" created and configured!`, "info");
 };
+/** Probe Ollama at localhost for available embedding models. */
+const probeOllamaModels = async () => {
+    try {
+        const res = await fetch("http://127.0.0.1:11434/api/tags", {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (!res.ok)
+            return [];
+        const data = (await res.json());
+        if (!Array.isArray(data.models))
+            return [];
+        // Filter to embedding-capable models (heuristic: name contains "embed" or known embedding models)
+        const embeddingHints = ["embed", "minilm", "nomic", "bge", "gte", "e5", "mxbai"];
+        const all = data.models
+            .filter((m) => embeddingHints.some((h) => m.name.toLowerCase().includes(h)))
+            .map((m) => ({
+            name: m.name,
+            size: m.size > 1e9 ? `${(m.size / 1e9).toFixed(1)}GB` : `${(m.size / 1e6).toFixed(0)}MB`,
+        }));
+        // Also include all models as secondary options (user might know what they want)
+        const nonEmbedding = data.models
+            .filter((m) => !embeddingHints.some((h) => m.name.toLowerCase().includes(h)))
+            .map((m) => ({
+            name: m.name,
+            size: m.size > 1e9 ? `${(m.size / 1e9).toFixed(1)}GB` : `${(m.size / 1e6).toFixed(0)}MB`,
+        }));
+        return [...all, ...nonEmbedding];
+    }
+    catch {
+        return [];
+    }
+};
+/** Probe a Modal deployment for available embedding models via GET /models. */
+const probeModalModels = async (baseUrl, cfg) => {
+    try {
+        const token = resolveModalToken(cfg);
+        const headers = {};
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        const res = await fetch(`${baseUrl.replace(/\/$/, "")}/models`, {
+            headers,
+            signal: AbortSignal.timeout(8000),
+        });
+        if (!res.ok)
+            return [];
+        const data = (await res.json());
+        if (!Array.isArray(data.models))
+            return [];
+        return data.models.filter((m) => m.enabled);
+    }
+    catch {
+        return [];
+    }
+};
 export const setupWizard = async (ctx, cliArgs) => {
     const existingGlobal = fs.existsSync(getGlobalConfigPath());
     const detectedVaultPath = detectVaultFromCwd(ctx.cwd);
@@ -142,6 +347,21 @@ export const setupWizard = async (ctx, cliArgs) => {
             lines.push(`   Dim: ${cliArgs.dim}`);
         if (cliArgs.workspace)
             lines.push(`   Modal workspace: ${cliArgs.workspace}`);
+        if (effectiveVaultPath) {
+            const obsidianDir = path.join(effectiveVaultPath, ".obsidian");
+            if (fs.existsSync(obsidianDir)) {
+                const missingPlugins = getMissingOnboardingPlugins(effectiveVaultPath);
+                if (missingPlugins.length === 0) {
+                    lines.push("", "Obsidian plugin check: required integration plugins already enabled.");
+                }
+                else {
+                    lines.push("", "Missing Obsidian plugins:", ...missingPlugins.map((plugin) => `- ${plugin.label} (${plugin.id})`), "", buildPluginInstallGuidance(missingPlugins));
+                }
+            }
+            else {
+                lines.push("", "Obsidian plugin check skipped: .obsidian/ not found.", "Open the vault in Obsidian once, then re-run /vm setup for plugin guidance.");
+            }
+        }
         ctx.ui.notify(lines.join("\n"), "info");
         return;
     }
@@ -186,55 +406,86 @@ export const setupWizard = async (ctx, cliArgs) => {
             return;
         }
     }
+    // ── Step 1.5: Obsidian plugin readiness ────────────────────────────────
+    await runPluginOnboarding(ctx, vaultPath);
     // ── Step 2: Embedding config ──────────────────────────────────────────
-    let remoteUrl = await ctx.ui.input("Remote Embedding URL (e.g. https://.../v1, optional):", "");
-    const localUrl = await ctx.ui.input("Local Embedding URL (e.g. http://127.0.0.1:11434/v1, optional):", "");
+    let remoteUrl = "";
+    let localUrl = "";
     let useTransformers = false;
     let guidedModalWorkspace;
-    if (!remoteUrl && !localUrl) {
-        const route = await ctx.ui.select("No embedding URL configured", [
-            "Use local transformers (offline)",
-            "Guide me through Modal setup",
-            "Cancel setup",
-        ]);
-        if (!route || route === "Cancel setup") {
-            ctx.ui.notify("Setup cancelled — at least one URL or transformers is required.", "warning");
+    let model = "";
+    let dim;
+    // Probe Ollama for local embedding models
+    const ollamaModels = await probeOllamaModels();
+    const providerOptions = [
+        ...(ollamaModels.length > 0 ? ["Local (Ollama — models detected)"] : []),
+        "Cloud (Modal workspace)",
+        "Custom URL (any /v1/embeddings endpoint)",
+        "Offline (transformers.js — no external service)",
+    ];
+    const provider = await ctx.ui.select("Embedding provider:", providerOptions);
+    if (!provider) {
+        ctx.ui.notify("Setup cancelled.", "warning");
+        return;
+    }
+    if (provider.startsWith("Local")) {
+        localUrl = "http://127.0.0.1:11434/v1";
+        // Let user pick from detected Ollama embedding models
+        const modelChoice = await ctx.ui.select("Select embedding model:", ollamaModels.map((m) => `${m.name} (${m.size})`));
+        if (!modelChoice) {
+            ctx.ui.notify("Setup cancelled.", "warning");
             return;
         }
-        if (route === "Use local transformers (offline)") {
-            useTransformers = true;
+        model = modelChoice.replace(/\s*\(.*\)$/, "");
+    }
+    else if (provider.startsWith("Cloud")) {
+        const workspaceSlug = await ctx.ui.input("Modal workspace slug:", "");
+        if (!workspaceSlug) {
+            ctx.ui.notify("Setup cancelled — workspace is required.", "warning");
+            return;
         }
-        else {
-            const workspaceSlug = await ctx.ui.input("Modal workspace slug:", "");
-            if (!workspaceSlug) {
-                ctx.ui.notify("Setup cancelled — workspace is required for Modal guidance.", "warning");
-                return;
+        guidedModalWorkspace = workspaceSlug.trim();
+        remoteUrl = modalUrl(guidedModalWorkspace);
+        // Probe Modal /models for available embedders
+        const modalModels = await probeModalModels(remoteUrl, loadConfig(ctx.cwd).vaultMind);
+        if (modalModels.length > 0) {
+            const modalChoice = await ctx.ui.select("Select cloud embedding model:", modalModels.map((m) => `${m.key} (dim ${m.native_dim}${m.gated ? ", gated" : ""})`));
+            if (modalChoice) {
+                model = modalChoice.replace(/\s*\(.*\)$/, "");
+                const matched = modalModels.find((m) => m.key === model);
+                if (matched)
+                    dim = matched.native_dim;
             }
-            guidedModalWorkspace = workspaceSlug.trim();
-            remoteUrl = modalUrl(guidedModalWorkspace);
-            ctx.ui.notify([
-                "Modal endpoint discovery:",
-                `- Derived remote URL: ${remoteUrl}`,
-                "- Set token now with one of:",
-                "  /vm remote token",
-                "  ./scripts/fetch-modal-token.sh --write",
-                "- Reference docs:",
-                "  docs/getting-started/NEW_VAULT_WALKTHROUGH.md",
-                "  docs/integrations/MODAL_EMBEDDING.md",
-            ].join("\n"), "info");
         }
+        else {
+            ctx.ui.notify("Could not reach Modal /models — using default (embeddinggemma @ 768).", "warning");
+            model = "embeddinggemma";
+            dim = 768;
+        }
+        ctx.ui.notify([
+            "Modal endpoint discovery:",
+            `- Remote URL: ${remoteUrl}`,
+            "- Set token with: /vm remote token  or  ./scripts/fetch-modal-token.sh --write",
+        ].join("\n"), "info");
     }
-    const model = (await ctx.ui.input("Embedding model key (optional):", ""))?.trim();
-    if (model === undefined) {
-        ctx.ui.notify("Setup cancelled.", "warning");
-        return;
+    else if (provider.startsWith("Custom")) {
+        const url = await ctx.ui.input("Embedding URL (e.g. https://my-server.com/v1):", "");
+        if (!url) {
+            ctx.ui.notify("Setup cancelled — URL required.", "warning");
+            return;
+        }
+        remoteUrl = url;
+        model = (await ctx.ui.input("Model name (optional):", ""))?.trim() || "";
+        const dimStr = await ctx.ui.input("Dimensions (optional):", "");
+        dim = dimStr ? Number.parseInt(dimStr, 10) : undefined;
     }
-    const dimStr = await ctx.ui.input("Dimensions (optional):", "");
-    const dim = dimStr ? Number.parseInt(dimStr, 10) : undefined;
-    let workspace = guidedModalWorkspace;
-    if (!workspace && remoteUrl?.includes("modal.run")) {
-        workspace = await ctx.ui.input("Modal workspace (optional):", "");
+    else {
+        // Offline transformers
+        useTransformers = true;
+        model = "Xenova/all-MiniLM-L6-v2";
+        dim = 384;
     }
+    const workspace = guidedModalWorkspace;
     // ── Step 3: Deterministic runtime settings ──────────────────────────────
     const enableContextAutomation = await ctx.ui.confirm("Context automation", "Enable pi-context integration with auto-/acm trigger and event indexing?");
     const enableAutoStart = await ctx.ui.confirm("Vault auto-start", "Auto-start watcher/server for this vault when pi session starts?");

package/dist/src/utils.d.ts

@@ -21,6 +21,9 @@ export declare const hasPiContextTools: (pi: ExtensionAPI) => boolean;
 export declare const isPiContextEnabled: (cfg: UniversalConfig) => boolean;
 export declare const getPiContextConfig: (cfg: UniversalConfig) => PiContextDef;
 export declare const collectionNames: (cfg: UniversalConfig) => string[];
+export declare const normalizeCollectionName: (value: string) => string;
+export declare const deriveCollectionNameFromVaultPath: (vaultPath: string) => string;
+export declare const resolveInitCollectionName: (vaultPath: string, override?: string) => string;
 /** Resolve a configured vault folder, falling back to the default layout. */
 export declare function resolveVaultFolder(cfg: VaultMindConfig, key: "inbox" | "library" | "presentations" | "journal"): string;
 /** Resolve the configured default vault path, or null if none is configured. */

package/dist/src/utils.js

@@ -132,6 +132,25 @@ export const getPiContextConfig = (cfg) => ({
 });
 // Backward compat alias
 export const collectionNames = (cfg) => Object.keys(cfg.collections);
+export const normalizeCollectionName = (value) => value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 64);
+export const deriveCollectionNameFromVaultPath = (vaultPath) => {
+    const base = path.basename(path.resolve(vaultPath));
+    const normalized = normalizeCollectionName(base);
+    return normalized || "main";
+};
+export const resolveInitCollectionName = (vaultPath, override) => {
+    if (override && override.trim().length > 0) {
+        const normalized = normalizeCollectionName(override);
+        if (normalized)
+            return normalized;
+    }
+    return deriveCollectionNameFromVaultPath(vaultPath);
+};
 /** Default vault folder layout. Paths are relative to the vault root. */
 const DEFAULT_VAULT_FOLDERS = {
     inbox: "Agent/Inbox",

package/dist/test/rest-setup.test.js

@@ -114,16 +114,30 @@ describe("REST setup routes", () => {
         const { status } = await fetchJson("127.0.0.1", port, "GET", "/vm/status");
         assert.equal(status, 401);
     });
-    it("POST /vm/init scaffolds config and collections", async () => {
+    it("POST /vm/init scaffolds config and vault-named collection file", async () => {
         const { status, body } = await fetchJson("127.0.0.1", port, "POST", "/vm/init", { vaultPath }, "test-token");
         assert.equal(status, 200);
         const b = body;
         assert.equal(b.ok, true);
         assert.equal(b.path, vaultPath);
-        assert.ok(fs.existsSync(path.join(vaultPath, "pi-vault-mind.config.json")));
-        assert.ok(fs.existsSync(path.join(vaultPath, "collections", "main.jsonl")));
+        const configPath = path.join(vaultPath, "pi-vault-mind.config.json");
+        assert.ok(fs.existsSync(configPath));
+        const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        const mainPath = String(cfg.collections?.main?.path || "");
+        assert.notEqual(mainPath, "collections/main.jsonl");
+        assert.match(mainPath, /^collections\/.+\.jsonl$/);
+        assert.ok(fs.existsSync(path.join(vaultPath, mainPath)));
         assert.ok(fs.existsSync(path.join(vaultPath, ".gitignore")));
     });
+    it("POST /vm/init accepts collection override", async () => {
+        const { status, body } = await fetchJson("127.0.0.1", port, "POST", "/vm/init", { vaultPath, collection: "returnvape" }, "test-token");
+        assert.equal(status, 200);
+        const b = body;
+        assert.equal(b.ok, true);
+        const cfg = JSON.parse(fs.readFileSync(path.join(vaultPath, "pi-vault-mind.config.json"), "utf-8"));
+        assert.equal(cfg.collections?.main?.path, "collections/returnvape.jsonl");
+        assert.ok(fs.existsSync(path.join(vaultPath, "collections", "returnvape.jsonl")));
+    });
     it("POST /vm/init is idempotent", async () => {
         await fetchJson("127.0.0.1", port, "POST", "/vm/init", { vaultPath }, "test-token");
         const { status, body } = await fetchJson("127.0.0.1", port, "POST", "/vm/init", { vaultPath }, "test-token");

package/dist/test/settings-ui.test.js

@@ -3,8 +3,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { afterEach, describe, it } from "node:test";
-import { detectVaultFromCwd, setupWizard } from "../src/settings-ui.js";
 import { modalUrl } from "../src/modal-config.js";
+import { buildPluginInstallGuidance, detectVaultFromCwd, getMissingOnboardingPlugins, setupWizard, } from "../src/settings-ui.js";
 import { getGlobalConfigPath } from "../src/utils.js";
 const savedHome = process.env.HOME;
 const mkTmpDir = (prefix) => fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -37,6 +37,27 @@ describe("settings-ui vault detection", () => {
         fs.rmSync(dir, { recursive: true, force: true });
     });
 });
+describe("setupWizard plugin onboarding helpers", () => {
+    it("reports only missing community plugins", () => {
+        const vault = mkTmpDir("pvm-plugin-check-");
+        const obsidianDir = path.join(vault, ".obsidian");
+        fs.mkdirSync(obsidianDir, { recursive: true });
+        fs.writeFileSync(path.join(obsidianDir, "community-plugins.json"), JSON.stringify(["obsidian-pi-vault-mind"], null, 2), "utf-8");
+        const missing = getMissingOnboardingPlugins(vault).map((plugin) => plugin.id);
+        assert.equal(missing.includes("obsidian-pi-vault-mind"), false);
+        assert.equal(missing.includes("actions-uri"), true);
+        assert.equal(missing.includes("obsidian-git"), true);
+        fs.rmSync(vault, { recursive: true, force: true });
+    });
+    it("builds manual guidance with CLI commands and Obsidian URIs", () => {
+        const vault = mkTmpDir("pvm-plugin-guide-");
+        const guidance = buildPluginInstallGuidance(getMissingOnboardingPlugins(vault));
+        assert.match(guidance, /obsidian plugin:install id=obsidian42-brat enable/);
+        assert.match(guidance, /obsidian plugin:install id=actions-uri enable/);
+        assert.match(guidance, /BRAT.*kylebrodeur\/obsidian-pi-vault-mind/);
+        fs.rmSync(vault, { recursive: true, force: true });
+    });
+});
 describe("setupWizard CLI defaults", () => {
     it("auto-uses cwd as vault when cwd is an Obsidian vault", async () => {
         const home = mkTmpDir("pvm-home-");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-vault-mind",
-  "version": "0.8.7",
+  "version": "0.9.0",
   "description": "Passive Obsidian vault extension for pi. Watches @agent markers, dispatches forked subagents (Miner, Broadcaster, Heavy-Lifter), stores in LanceDB with vector + FTS + graph. Multi-agent 'Drop & Forget' workflow for the pi agent ecosystem.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",