mnotes-cli 1.9.2 → 1.10.1

package/dist/commands/connect/__tests__/connect.test.js

@@ -43,6 +43,21 @@ const config_utils_1 = require("../config-utils");
 const claude_code_1 = require("../../../templates/claude-code");
 const codex_1 = require("../../../templates/codex");
 const openclaw_1 = require("../../../templates/openclaw");
+// Mock createClient so resolveWorkspace can validate workspaces without a real server
+vitest_1.vi.mock("../../../client", () => ({
+    createClient: () => ({
+        listWorkspaces: async () => ({
+            data: [
+                { id: "ws-123", name: "Test", slug: "test-123", isDefault: true },
+                { id: "ws-explicit-id", name: "Explicit", slug: "explicit-id", isDefault: false },
+                { id: "ws-new", name: "New", slug: "new", isDefault: false },
+            ],
+        }),
+        createWorkspace: async (name) => ({
+            data: { id: name, name, slug: name, isDefault: false },
+        }),
+    }),
+}));
 // -- Helper: capture stdout --
 function captureStdout(fn) {
     const chunks = [];
@@ -380,14 +395,14 @@ function cleanTmpDir(dir) {
         (0, vitest_1.expect)(result).toContain("https://notes.example.com");
         (0, vitest_1.expect)(result).toContain("ws-abc-123");
     });
-    (0, vitest_1.it)("includes session lifecycle sections", () => {
+    (0, vitest_1.it)("includes session lifecycle tools and wiki framing", () => {
         const result = (0, claude_code_1.generateClaudeCodeTemplate)({
             url: "http://localhost:3000",
             workspaceId: "ws-test",
         });
-        (0, vitest_1.expect)(result).toContain("Session Start");
-        (0, vitest_1.expect)(result).toContain("Session End");
-        (0, vitest_1.expect)(result).toContain("During Work");
+        (0, vitest_1.expect)(result).toContain("living wiki");
+        (0, vitest_1.expect)(result).toContain("Ingest Loop");
+        (0, vitest_1.expect)(result).toContain("Lint Loop");
         (0, vitest_1.expect)(result).toContain("project_context_load");
         (0, vitest_1.expect)(result).toContain("session_context_resume");
         (0, vitest_1.expect)(result).toContain("knowledge_store");
@@ -417,13 +432,30 @@ function cleanTmpDir(dir) {
             "recall_knowledge",
             "bulk_knowledge_recall",
             "knowledge_snapshot",
+            "scan_knowledge_conflicts",
             "session_log",
             "context_fetch",
+            "create_note",
+            "update_note",
+            "append_to_note",
+            "search_notes",
+            "daily_note",
+            "populate_graph",
+            "query_note_graph",
         ];
         for (const tool of expectedTools) {
             (0, vitest_1.expect)(result).toContain(tool);
         }
     });
+    (0, vitest_1.it)("does not reference phantom MCP tools", () => {
+        const result = (0, claude_code_1.generateClaudeCodeTemplate)({
+            url: "http://localhost:3000",
+            workspaceId: "ws-test",
+        });
+        // These tool names don't exist in the MCP server — guard against regressions.
+        (0, vitest_1.expect)(result).not.toMatch(/\bcreate_folder\b/);
+        (0, vitest_1.expect)(result).not.toMatch(/\bmove_note\b/);
+    });
 });
 // =============================================================
 // Template generation — generateCodexTemplate (AC-6.3)
@@ -615,7 +647,7 @@ function cleanTmpDir(dir) {
         const claudeMd = fs.readFileSync(path.join(tmpDir, "CLAUDE.md"), "utf-8");
         (0, vitest_1.expect)(claudeMd).toContain("<!-- m-notes:start -->");
         (0, vitest_1.expect)(claudeMd).toContain("<!-- m-notes:end -->");
-        (0, vitest_1.expect)(claudeMd).toContain("m-notes AI Knowledge Base");
+        (0, vitest_1.expect)(claudeMd).toContain("m-notes — Your Wiki");
         (0, vitest_1.expect)(claudeMd).toContain("ws-123");
     });
     (0, vitest_1.it)("replaces existing m-notes block on re-run", async () => {

package/dist/commands/connect/__tests__/wizard.test.js

@@ -41,6 +41,19 @@ const wizard_1 = require("../wizard");
 const hooks_1 = require("../../../templates/claude-code/hooks");
 const skills_1 = require("../../../templates/claude-code/skills");
 const agents_1 = require("../../../templates/claude-code/agents");
+// Mock createClient so resolveWorkspace can validate workspaces without a real server
+vitest_1.vi.mock("../../../client", () => ({
+    createClient: () => ({
+        listWorkspaces: async () => ({
+            data: [
+                { id: "ws-123", name: "Test", slug: "test-123", isDefault: true },
+            ],
+        }),
+        createWorkspace: async (name) => ({
+            data: { id: name, name, slug: name, isDefault: false },
+        }),
+    }),
+}));
 function makeTmpDir() {
     return fs.mkdtempSync(path.join(os.tmpdir(), "mnotes-wizard-test-"));
 }
@@ -55,20 +68,29 @@ const DEFAULT_OPTS = {
 // T-1: Template generation — hooks
 // =============================================================
 (0, vitest_1.describe)("hooks template", () => {
-    (0, vitest_1.it)("generates SessionStart hook with correct URL and workspaceId", () => {
+    (0, vitest_1.it)("generates SessionStart hook referencing bash script", () => {
         const hooks = (0, hooks_1.generateHooksTemplate)(DEFAULT_OPTS);
         (0, vitest_1.expect)(hooks.SessionStart).toBeDefined();
         (0, vitest_1.expect)(hooks.SessionStart).toHaveLength(1);
         (0, vitest_1.expect)(hooks.SessionStart[0].matcher).toBe("");
         (0, vitest_1.expect)(hooks.SessionStart[0].hooks).toHaveLength(1);
         (0, vitest_1.expect)(hooks.SessionStart[0].hooks[0].type).toBe("command");
-        (0, vitest_1.expect)(hooks.SessionStart[0].hooks[0].command).toContain("localhost:3000");
-        (0, vitest_1.expect)(hooks.SessionStart[0].hooks[0].command).toContain("ws-test-123");
-    });
-    (0, vitest_1.it)("strips trailing slashes from URL", () => {
-        const hooks = (0, hooks_1.generateHooksTemplate)({ url: "http://example.com///", workspaceId: "ws-1" });
-        (0, vitest_1.expect)(hooks.SessionStart[0].hooks[0].command).toContain("http://example.com/api/mcp");
-        (0, vitest_1.expect)(hooks.SessionStart[0].hooks[0].command).not.toContain("///");
+        (0, vitest_1.expect)(hooks.SessionStart[0].hooks[0].command).toBe(".claude/hooks/mnotes-session-start.sh");
+    });
+    (0, vitest_1.it)("generates hook scripts with correct URL, workspaceId, and Accept headers", () => {
+        const scripts = (0, hooks_1.generateHookScripts)(DEFAULT_OPTS);
+        (0, vitest_1.expect)(scripts).toHaveLength(2);
+        const startScript = scripts.find((s) => s.filename === "mnotes-session-start.sh");
+        (0, vitest_1.expect)(startScript.content).toContain("localhost:3000/api/mcp");
+        (0, vitest_1.expect)(startScript.content).toContain("ws-test-123");
+        (0, vitest_1.expect)(startScript.content).toContain('Accept: text/event-stream');
+        (0, vitest_1.expect)(startScript.content).toContain('Accept: application/json');
+    });
+    (0, vitest_1.it)("strips trailing slashes from URL in hook scripts", () => {
+        const scripts = (0, hooks_1.generateHookScripts)({ url: "http://example.com///", workspaceId: "ws-1" });
+        const startScript = scripts.find((s) => s.filename === "mnotes-session-start.sh");
+        (0, vitest_1.expect)(startScript.content).toContain("http://example.com/api/mcp");
+        (0, vitest_1.expect)(startScript.content).not.toContain("///");
     });
 });
 // =============================================================
@@ -162,17 +184,26 @@ const DEFAULT_OPTS = {
     (0, vitest_1.afterEach)(() => {
         cleanTmpDir(tmpDir);
     });
-    (0, vitest_1.it)("creates .claude/settings.json with hooks (AC-4)", () => {
+    (0, vitest_1.it)("creates .claude/settings.json with hooks and bash scripts (AC-4)", () => {
         const results = (0, wizard_1.scaffoldItems)(tmpDir, ["hooks"], DEFAULT_OPTS);
         (0, vitest_1.expect)(results).toHaveLength(1);
         (0, vitest_1.expect)(results[0].item).toBe("hooks");
-        (0, vitest_1.expect)(results[0].filesWritten).toHaveLength(1);
+        // 2 bash scripts + settings.json
+        (0, vitest_1.expect)(results[0].filesWritten).toHaveLength(3);
         const settingsPath = path.join(tmpDir, ".claude", "settings.json");
         (0, vitest_1.expect)(fs.existsSync(settingsPath)).toBe(true);
         const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
         (0, vitest_1.expect)(settings.hooks).toBeDefined();
         (0, vitest_1.expect)(settings.hooks.SessionStart).toBeDefined();
         (0, vitest_1.expect)(settings.hooks.SessionStart).toHaveLength(1);
+        // Bash scripts exist and are executable
+        const startScript = path.join(tmpDir, ".claude", "hooks", "mnotes-session-start.sh");
+        const stopScript = path.join(tmpDir, ".claude", "hooks", "mnotes-session-stop.sh");
+        (0, vitest_1.expect)(fs.existsSync(startScript)).toBe(true);
+        (0, vitest_1.expect)(fs.existsSync(stopScript)).toBe(true);
+        const startContent = fs.readFileSync(startScript, "utf-8");
+        (0, vitest_1.expect)(startContent).toContain("Accept: text/event-stream");
+        (0, vitest_1.expect)(startContent).toContain("Accept: application/json");
     });
     (0, vitest_1.it)("merges hooks into existing settings.json (AC-5)", () => {
         const claudeDir = path.join(tmpDir, ".claude");

package/dist/commands/connect/index.js

@@ -38,9 +38,11 @@ exports.handleClaudeCode = handleClaudeCode;
 exports.registerConnectCommand = registerConnectCommand;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
 const config_utils_1 = require("./config-utils");
 const workspace_prompt_1 = require("./workspace-prompt");
 const config_1 = require("../../config");
+const client_1 = require("../../client");
 const claude_code_1 = require("../../templates/claude-code");
 const codex_1 = require("../../templates/codex");
 const openclaw_1 = require("../../templates/openclaw");
@@ -90,13 +92,45 @@ function printConnectionStatus() {
 /**
  * Resolves the workspace ID — uses --workspace flag if provided, otherwise
  * prompts interactively after validating the connection.
+ *
+ * When a workspace value is provided (flag, env, or config), validates it
+ * against the API by matching on ID or slug. If not found, prompts to create.
  */
 async function resolveWorkspace(opts) {
     // Check flag, env, dir map, global config
     const fromConfig = (0, config_1.resolveConfig)({ workspaceId: opts.workspace });
-    if (fromConfig.workspaceId)
-        return fromConfig.workspaceId;
-    // Nothing stored — interactive selection/creation
+    const candidate = fromConfig.workspaceId;
+    if (candidate) {
+        // Validate the candidate against the API
+        const client = (0, client_1.createClient)(opts.url, opts.apiKey);
+        let workspaces;
+        try {
+            const res = await client.listWorkspaces();
+            workspaces = res.data;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to fetch workspaces: ${message}`);
+        }
+        // Match by ID or slug
+        const match = workspaces.find((ws) => ws.id === candidate || ws.slug === candidate);
+        if (match) {
+            return match.id;
+        }
+        // Not found — ask user to create
+        process.stderr.write(`\nWorkspace "${candidate}" not found.\n`);
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        const answer = await new Promise((resolve) => rl.question(`Create workspace "${candidate}"? [Y/n] `, resolve));
+        rl.close();
+        if (answer.trim() === "" || answer.trim().toLowerCase() === "y") {
+            const created = await client.createWorkspace(candidate);
+            process.stderr.write(`Created workspace "${created.data.name}" (${created.data.id})\n`);
+            return created.data.id;
+        }
+        // User declined — fall through to interactive
+        process.stderr.write("Falling back to interactive workspace selection.\n");
+    }
+    // Nothing stored or user declined — interactive selection/creation
     const resolved = await (0, workspace_prompt_1.resolveWorkspaceInteractively)(opts.url, opts.apiKey);
     return resolved.id;
 }

package/dist/commands/connect/wizard.js

@@ -102,13 +102,23 @@ function scaffoldItems(dir, items, opts) {
     return results;
 }
 /**
- * Merges hooks into `.claude/settings.json`.
+ * Merges hooks into `.claude/settings.json` and writes bash scripts to `.claude/hooks/`.
  * Preserves all existing settings and hooks.
  */
 function scaffoldHooks(dir, opts) {
     const settingsPath = path.join(dir, ".claude", "settings.json");
     const claudeDir = path.join(dir, ".claude");
-    fs.mkdirSync(claudeDir, { recursive: true });
+    const hooksDir = path.join(claudeDir, "hooks");
+    fs.mkdirSync(hooksDir, { recursive: true });
+    const filesWritten = [];
+    // 1. Write bash scripts to .claude/hooks/
+    const scripts = (0, index_1.generateHookScripts)(opts);
+    for (const script of scripts) {
+        const scriptPath = path.join(hooksDir, script.filename);
+        fs.writeFileSync(scriptPath, script.content, { mode: 0o755 });
+        filesWritten.push(scriptPath);
+    }
+    // 2. Merge hook entries into settings.json
     let existing = {};
     try {
         const raw = fs.readFileSync(settingsPath, "utf-8");
@@ -158,7 +168,8 @@ function scaffoldHooks(dir, opts) {
         mnotesMetadata.items.push("hooks");
     }
     fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
-    return { item: "hooks", filesWritten: [settingsPath] };
+    filesWritten.push(settingsPath);
+    return { item: "hooks", filesWritten };
 }
 /**
  * Writes skill files to `.claude/skills/`.

package/dist/templates/claude-code/hooks.d.ts

@@ -1,6 +1,6 @@
 /**
  * Template for Claude Code session hooks.
- * Written to `.claude/settings.json` under the `hooks` field.
+ * Generates bash scripts in `.claude/hooks/` and hook entries for `.claude/settings.json`.
  * Generated by m-notes CLI — do not edit manually.
  */
 export interface HooksTemplateOpts {
@@ -19,11 +19,17 @@ export interface ClaudeCodeHooks {
     SessionStart?: ClaudeCodeHookEntry[];
     [key: string]: ClaudeCodeHookEntry[] | undefined;
 }
+export interface HookScript {
+    filename: string;
+    content: string;
+}
+/**
+ * Generates bash scripts to be written to `.claude/hooks/`.
+ */
+export declare function generateHookScripts(opts: HooksTemplateOpts): HookScript[];
 /**
  * Generates the hooks object to merge into `.claude/settings.json`.
- * Currently provides a SessionStart hook that auto-loads project context.
- *
- * Claude Code hooks format requires: { matcher, hooks[] } wrapper.
+ * References bash scripts in `.claude/hooks/` instead of inline commands.
  */
 export declare function generateHooksTemplate(opts: HooksTemplateOpts): ClaudeCodeHooks;
 /** Header comment for the hooks section, used for identification. */

package/dist/templates/claude-code/hooks.js

@@ -1,31 +1,69 @@
 "use strict";
 /**
  * Template for Claude Code session hooks.
- * Written to `.claude/settings.json` under the `hooks` field.
+ * Generates bash scripts in `.claude/hooks/` and hook entries for `.claude/settings.json`.
  * Generated by m-notes CLI — do not edit manually.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HOOKS_HEADER = void 0;
+exports.generateHookScripts = generateHookScripts;
 exports.generateHooksTemplate = generateHooksTemplate;
 /**
- * Generates the hooks object to merge into `.claude/settings.json`.
- * Currently provides a SessionStart hook that auto-loads project context.
- *
- * Claude Code hooks format requires: { matcher, hooks[] } wrapper.
+ * Generates bash scripts to be written to `.claude/hooks/`.
  */
-function generateHooksTemplate(opts) {
+function generateHookScripts(opts) {
     const baseUrl = opts.url.replace(/\/+$/, "");
     const mcpUrl = `${baseUrl}/api/mcp`;
-    const authHeader = `Authorization: Bearer $MNOTES_API_KEY`;
-    function mcpCall(method, args) {
-        const payload = JSON.stringify({
+    function mcpPayload(method, args) {
+        return JSON.stringify({
             jsonrpc: "2.0",
             method: "tools/call",
             params: { name: method, arguments: args },
             id: 1,
         });
-        return `curl -s -H "${authHeader}" "${mcpUrl}" -d '${payload}' -H "Content-Type: application/json" > /dev/null 2>&1 || true`;
     }
+    const sessionStartScript = `#!/usr/bin/env bash
+# Generated by m-notes CLI — do not edit manually.
+# Loads project context on Claude Code session start.
+set -euo pipefail
+
+MNOTES_URL="${mcpUrl}"
+PAYLOAD='${mcpPayload("project_context_load", { workspaceId: opts.workspaceId, query: "session start" })}'
+
+curl -s \\
+  -H "Authorization: Bearer $MNOTES_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -H "Accept: text/event-stream" \\
+  -H "Accept: application/json" \\
+  "$MNOTES_URL" \\
+  -d "$PAYLOAD" > /dev/null 2>&1 || true
+`;
+    const sessionStopScript = `#!/usr/bin/env bash
+# Generated by m-notes CLI — do not edit manually.
+# Logs session end to m-notes.
+set -euo pipefail
+
+MNOTES_URL="${mcpUrl}"
+PAYLOAD='${mcpPayload("session_log", { workspaceId: opts.workspaceId, summary: "Session ended", decisions: [], actions: [] })}'
+
+curl -s \\
+  -H "Authorization: Bearer $MNOTES_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -H "Accept: text/event-stream" \\
+  -H "Accept: application/json" \\
+  "$MNOTES_URL" \\
+  -d "$PAYLOAD" > /dev/null 2>&1 || true
+`;
+    return [
+        { filename: "mnotes-session-start.sh", content: sessionStartScript },
+        { filename: "mnotes-session-stop.sh", content: sessionStopScript },
+    ];
+}
+/**
+ * Generates the hooks object to merge into `.claude/settings.json`.
+ * References bash scripts in `.claude/hooks/` instead of inline commands.
+ */
+function generateHooksTemplate(opts) {
     return {
         SessionStart: [
             {
@@ -33,10 +71,7 @@ function generateHooksTemplate(opts) {
                 hooks: [
                     {
                         type: "command",
-                        command: mcpCall("project_context_load", {
-                            workspaceId: opts.workspaceId,
-                            query: "session start",
-                        }),
+                        command: ".claude/hooks/mnotes-session-start.sh",
                     },
                 ],
             },
@@ -47,12 +82,7 @@ function generateHooksTemplate(opts) {
                 hooks: [
                     {
                         type: "command",
-                        command: mcpCall("session_log", {
-                            workspaceId: opts.workspaceId,
-                            summary: "Session ended",
-                            decisions: [],
-                            actions: [],
-                        }),
+                        command: ".claude/hooks/mnotes-session-stop.sh",
                     },
                 ],
             },

package/dist/templates/claude-code/index.d.ts

@@ -1,5 +1,5 @@
-export { generateHooksTemplate, HOOKS_HEADER } from "./hooks";
-export type { HooksTemplateOpts, ClaudeCodeHooks, ClaudeCodeHook } from "./hooks";
+export { generateHooksTemplate, generateHookScripts, HOOKS_HEADER } from "./hooks";
+export type { HooksTemplateOpts, ClaudeCodeHooks, ClaudeCodeHook, HookScript } from "./hooks";
 export { generateSkillTemplates } from "./skills";
 export type { SkillTemplateOpts, SkillFile } from "./skills";
 export { generateAgentTemplates } from "./agents";

package/dist/templates/claude-code/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateAgentTemplates = exports.generateSkillTemplates = exports.HOOKS_HEADER = exports.generateHooksTemplate = void 0;
+exports.generateAgentTemplates = exports.generateSkillTemplates = exports.HOOKS_HEADER = exports.generateHookScripts = exports.generateHooksTemplate = void 0;
 var hooks_1 = require("./hooks");
 Object.defineProperty(exports, "generateHooksTemplate", { enumerable: true, get: function () { return hooks_1.generateHooksTemplate; } });
+Object.defineProperty(exports, "generateHookScripts", { enumerable: true, get: function () { return hooks_1.generateHookScripts; } });
 Object.defineProperty(exports, "HOOKS_HEADER", { enumerable: true, get: function () { return hooks_1.HOOKS_HEADER; } });
 var skills_1 = require("./skills");
 Object.defineProperty(exports, "generateSkillTemplates", { enumerable: true, get: function () { return skills_1.generateSkillTemplates; } });

package/dist/templates/claude-code.js

@@ -2,107 +2,131 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateClaudeCodeTemplate = generateClaudeCodeTemplate;
 function generateClaudeCodeTemplate(opts) {
-    return `# m-notes — Persistent Knowledge Base (MANDATORY)
+    return `<!-- m-notes instructions v3 -->
+# m-notes — Your Wiki (MANDATORY)
 
 **Server**: ${opts.url}
 **Workspace**: ${opts.workspaceId}
 
-> **IMPORTANT**: You MUST use m-notes tools throughout every session. This is your persistent memory across sessions — without it you start from zero every time. The instructions below are NOT optional.
+> You are not a reader of a scratchpad. You are the **author and maintainer of a living wiki**. Every session, three things compound: the wiki grows, links densify, contradictions get resolved. This is your persistent memory — without it you start from zero every conversation.
+
+## The Three Layers
+
+1. **Raw sources** — user messages, pasted docs, URLs, files. Immutable. You never edit these.
+2. **The wiki** — your notes. You *write* these. They are interlinked with \`[[wikilinks]]\`, tagged for retrieval, and updated whenever sources change.
+3. **Schema pages** — notes tagged \`type:config\` (or in a \`_schema/\` folder). The user's rules for how the wiki is organized. **Read these before editing the wiki.**
 
 ## Rules (follow strictly)
 
-1. **ALWAYS recall before researching.** Before exploring the codebase, reading files, or making assumptions about architecture — call \`recall_knowledge\` first. Past you already figured things out; don't waste tokens rediscovering them.
-2. **ALWAYS store what you learn.** When you discover something non-obvious (architecture decisions, gotchas, patterns, bug root causes, dependency quirks) — store it immediately with \`knowledge_store\`. If it took effort to figure out, it's worth storing.
-3. **ALWAYS log sessions.** Before the session ends, call \`session_log\` with a summary of what was accomplished, decisions made, and next steps. Future sessions depend on this.
-4. **ALWAYS load context at session start.** Call \`project_context_load\` at the beginning of every session. The SessionStart hook does this automatically, but if you're resuming mid-conversation, call \`session_context_resume\`.
+1. **ALWAYS recall before researching.** Before exploring the codebase or making assumptions — call \`recall_knowledge\` and \`search_notes\`. Past you already figured things out.
+2. **ALWAYS store what you learn.** Non-obvious discoveries → \`knowledge_store\` immediately. Anything worth re-finding belongs in the wiki.
+3. **ALWAYS log sessions.** Call \`session_log\` before the session ends.
+4. **ALWAYS load context at session start.** Call \`project_context_load\`. Use \`session_context_resume\` if mid-conversation.
+5. **INGEST sources coherently.** When the user drops a URL, long paste, or file: don't just dump it into one note. Run the **ingest loop** (below).
+6. **LINT the wiki periodically.** On session start for large workspaces, and after any ingest, run the **lint loop** (below).
+7. **READ schema before editing.** Before creating or updating notes, call \`search_notes\` for \`type:config\` notes. Follow their conventions. If none exist, offer to create a starter schema note.
+8. **EVERY note must link.** Outbound \`[[wikilinks]]\` are mandatory — an orphan note is invisible.
+
+## The Ingest Loop
+
+When the user supplies a source (URL, paste, file):
+
+1. **Find related pages**: \`search_notes\` + \`query_graph\` to identify 3–15 existing notes affected.
+2. **Plan the edits**: which existing notes need \`append_to_note\` / \`update_note\`, which new notes need \`create_note\`, and what \`[[wikilinks]]\` connect them.
+3. **Apply**: execute the plan. Every touched note gets:
+   - A \`source/<slug>\` tag or a "Sources" section listing provenance
+   - At least one \`[[wikilink]]\` to another touched note
+4. **Summarize**: tell the user which notes were created vs. updated.
+
+A single source should rarely touch fewer than 3 notes — that's a sign you're treating the wiki as a dumping ground.
+
+## The Lint Loop
+
+Periodically (session start on large workspaces; after ingests):
+
+- **Contradictions** → call \`scan_knowledge_conflicts\`. Resolve, don't stack.
+- **Orphans** → \`query_note_graph\` for notes with zero inbound or outbound links. Link them or delete.
+- **Broken wikilinks** → \`[[X]]\` targets that don't exist. Create a stub note or fix the link.
+- **Stale** → notes untouched >90 days referenced by new sources. Update them.
+
+Report findings as a short list; ask before bulk-deleting.
 
 ## When to Store Knowledge
 
-Store knowledge **proactively** — don't wait for the user to ask. Store when you:
-- Make or discover an architecture decision → \`arch/{component}\`
-- Find a code pattern or convention → \`pattern/{name}\`
-- Debug and fix a bug → \`bug/{id-or-description}\`
-- Learn something about a dependency → \`dep/{package}\`
-- Make a product or tech decision → \`decision/{topic}\`
-- Build understanding of a domain area → \`context/{area}\`
-- Discover a gotcha or footgun → \`gotcha/{description}\`
-- Complete a task or story → \`task/{id}\`
+Store **proactively** — don't wait to be asked. Categories:
+- Architecture decision → \`arch/{component}\`
+- Code pattern or convention → \`pattern/{name}\`
+- Debugged bug → \`bug/{id}\`
+- Dependency quirk → \`dep/{package}\`
+- Product/tech decision → \`decision/{topic}\`
+- Domain understanding → \`context/{area}\`
+- Gotcha or footgun → \`gotcha/{description}\`
+- Completed task → \`task/{id}\`
+
+**Promotion rule**: if a knowledge entry is recalled 3+ times, promote it to a full note with \`create_note\` — it has earned a wiki page.
 
 ## When to Recall Knowledge
 
-Recall knowledge **before acting**. Specifically:
-- Before making a tech decision → recall \`arch/*\` and \`decision/*\`
-- Before touching a module → recall relevant \`pattern/*\` and \`context/*\`
-- Before debugging → recall \`bug/*\` for similar past issues
-- Before adding a dependency → recall \`dep/*\`
-- At session start → \`project_context_load\` loads everything relevant
-- When the user asks about past work → \`session_context_resume\`
-
-## Notes — Your Working Documents
-
-m-notes is not just a knowledge base — it's a full note-taking system. **Use notes actively** to create and maintain living documents:
-
-### When to Create Notes
-- **Meeting notes** → \`create_note\` after any planning discussion or decision
-- **Investigation logs** → create a note when debugging, append findings as you go with \`append_to_note\`
-- **Design docs** → write architecture or design decisions as full notes, not just knowledge entries
-- **Task summaries** → after completing a story/task, create a note summarizing what was done
-- **Checklists and plans** → create notes with markdown checklists for multi-step work
-- **Daily notes** → use \`daily_note\` to create/get today's note for quick captures
-
-### When to Edit Notes
-- **Append progress** → use \`append_to_note\` to add to existing notes as work progresses
-- **Update docs** → when code changes invalidate existing notes, update them with \`update_note\`
-- **Tag and organize** → use \`manage_tags\` and folder tools to keep notes findable
-
-### Note vs Knowledge Entry
-| Use a **note** when... | Use **knowledge_store** when... |
+Recall **before acting**:
+- Tech decision → \`arch/*\` + \`decision/*\`
+- Touching a module → relevant \`pattern/*\` + \`context/*\`
+- Debugging → \`bug/*\` for similar past issues
+- Adding a dependency → \`dep/*\`
+- Session start → \`project_context_load\` (automatic via SessionStart hook)
+- User asks about past work → \`session_context_resume\`
+
+## Notes vs. Knowledge Entries
+
+In the wiki model, **notes are primary**. Knowledge entries are fast-capture for things that haven't earned a page yet.
+
+| Use a **note** when... | Use \`knowledge_store\` when... |
 |---|---|
-| Content is long-form (paragraphs, lists, docs) | Content is a single fact or decision |
-| Document will be updated over time | Entry is a permanent record |
-| Needs folder organization | Needs key/tag retrieval |
-| Meeting notes, plans, investigations | Architecture decisions, gotchas, patterns |
+| Content is long-form or evolving | Content is a single fact |
+| Needs \`[[wikilinks]]\` and backlinks | Key/tag retrieval is enough |
+| Subject will be referenced repeatedly | One-shot capture |
+| Meeting notes, investigations, design docs | Architecture decisions, gotchas |
+
+**When in doubt, create a note.**
 
-**When in doubt, create a note.** Notes are searchable, linkable, and visible in the UI.
+### Note Creation
+- **Meetings / planning** → \`create_note\`
+- **Investigations** → \`create_note\` then \`append_to_note\` as you go
+- **Design / architecture** → full notes, not just knowledge entries
+- **Task summaries** → after completing a story
+- **Daily captures** → \`daily_note\`
 
-## Knowledge Graph — Build Structured Memory
+### Note Maintenance
+- \`append_to_note\` — add progress
+- \`update_note\` — supersede stale content
+- \`manage_tags\` / folder tools — keep notes findable
 
-Beyond flat knowledge entries, you have a **knowledge graph** for structured relationships between concepts. Use it to map how things connect — architecture components, dependencies, decisions, and patterns.
+## Knowledge Graph — Non-Optional
 
-### When to Build the Graph
-- **Session start**: If the graph is empty, call \`populate_graph\` to initialize from existing notes and wikilinks.
-- **Architecture decisions**: Create concept nodes for components, link them with "related" or "parent" edges.
-- **Dependency discovery**: Create nodes for packages, link to the components that use them.
-- **Bug investigations**: Link bug nodes to the components and patterns involved.
-- **Any time you see a relationship**: If A relates to B, create an edge. The graph gets more valuable over time.
+The graph is how the wiki stays navigable. **Every note you write or edit must have at least one outbound wikilink.**
+
+### When to Build
+- **Session start**: call \`populate_graph\` if the graph is empty (idempotent).
+- **Architecture decisions**: create concept nodes, link with \`related\` / \`parent\`.
+- **Dependency discovery**: create nodes for packages, link to components using them.
+- **Bug investigations**: link bug nodes to affected components/patterns.
+- **Any A↔B relationship**: create the edge. The graph compounds.
 
 ### Graph Tools
 | Tool | When to use |
 |------|------------|
-| \`populate_graph\` | Initialize graph from existing notes (idempotent, safe to re-run) |
-| \`create_node\` | Create a concept, tag, or note-linked node |
-| \`create_edge\` | Link two nodes (types: wikilink, related, parent, tagged, custom) |
-| \`query_graph\` | Search the graph by node type, label, or connectivity |
-| \`get_neighbors\` | Explore nodes connected to a specific node |
-| \`query_note_graph\` | Get the connection subgraph around a note |
-
-### Node Types
-- **note** — linked to an existing note (set \`noteId\`)
-- **tag** — represents a tag or category
-- **concept** — free-form concept (architecture component, pattern, decision)
-
-### Edge Types
-- **wikilink** — note links to another note
-- **related** — general relationship
-- **parent** — hierarchical (component contains sub-component)
-- **tagged** — node is tagged with a category
-- **custom** — any other relationship (describe in metadata)
-
-### Example: Mapping Architecture
+| \`populate_graph\` | Initialize from existing notes (idempotent) |
+| \`create_node\` | Add a concept/tag/note-linked node |
+| \`create_edge\` | Link two nodes (wikilink, related, parent, tagged, custom) |
+| \`query_graph\` | Search by type, label, or connectivity |
+| \`get_neighbors\` | Explore connections from a node |
+| \`query_note_graph\` | Get subgraph around a note |
+
+Node types: **note**, **tag**, **concept**. Edge types: **wikilink**, **related**, **parent**, **tagged**, **custom**.
+
 \`\`\`
-create_node({ label: "Auth Module", nodeType: "concept", workspaceId: "..." })
-create_node({ label: "PostgreSQL", nodeType: "concept", workspaceId: "..." })
-create_edge({ sourceId: authNodeId, targetId: pgNodeId, edgeType: "related", workspaceId: "..." })
+create_node({ label: "Auth Module", nodeType: "concept", workspaceId: "${opts.workspaceId}" })
+create_node({ label: "PostgreSQL", nodeType: "concept", workspaceId: "${opts.workspaceId}" })
+create_edge({ sourceId: authNodeId, targetId: pgNodeId, edgeType: "related", workspaceId: "${opts.workspaceId}" })
 \`\`\`
 
 ## MCP Tools Reference
@@ -110,49 +134,44 @@ create_edge({ sourceId: authNodeId, targetId: pgNodeId, edgeType: "related", wor
 ### Session & Context
 | Tool | When to use |
 |------|------------|
-| \`project_context_load\` | Session start — loads project context |
-| \`session_context_resume\` | Resume from previous session |
-| \`session_log\` | Log session summary at end |
+| \`project_context_load\` | Session start |
+| \`session_context_resume\` | Resume mid-conversation |
+| \`session_log\` | Log summary at end |
 
-### Knowledge (quick structured entries)
+### Knowledge (fast capture)
 | Tool | When to use |
 |------|------------|
-| \`knowledge_store\` | Store a knowledge entry (key, content, tags) |
-| \`recall_knowledge\` | Semantic search across stored knowledge |
-| \`bulk_knowledge_recall\` | Recall by tag patterns (e.g., all \`arch/*\`) |
-| \`knowledge_snapshot\` | Export all knowledge at once |
+| \`knowledge_store\` | Store a single fact |
+| \`recall_knowledge\` | Semantic search |
+| \`bulk_knowledge_recall\` | Recall by tag pattern (e.g., \`arch/*\`) |
+| \`knowledge_snapshot\` | Export all knowledge |
+| \`scan_knowledge_conflicts\` | Lint: find contradictions |
 
-### Notes (full documents)
+### Notes (wiki pages)
 | Tool | When to use |
 |------|------------|
-| \`create_note\` | Create a new note (title, content, folderId) |
-| \`update_note\` | Replace note content |
-| \`append_to_note\` | Add content to an existing note |
-| \`get_note\` | Read a note by ID |
-| \`get_note_by_title\` | Find a note by title |
-| \`search_notes\` | Full-text or semantic search |
-| \`list_notes\` | List notes in a folder |
-| \`daily_note\` | Create or get today's daily note |
-| \`manage_tags\` | Add/remove tags on notes |
-| \`pin_note\` / \`toggle_star\` | Pin or star important notes |
+| \`create_note\` | New page |
+| \`update_note\` | Replace content |
+| \`append_to_note\` | Add to existing page |
+| \`get_note\` / \`get_note_by_title\` | Read |
+| \`search_notes\` | FTS + semantic search |
+| \`list_notes\` | List by folder |
+| \`daily_note\` | Today's capture note |
+| \`manage_tags\` | Add/remove tags |
+| \`pin_note\` / \`toggle_star\` | Elevate importance |
 
 ### Organization
 | Tool | When to use |
 |------|------------|
-| \`list_folders\` | List folders in workspace |
-| \`create_folder\` | Create a new folder |
-| \`move_note\` | Move note to a different folder |
+| \`list_folders\` / \`manage_folders\` / \`move_folder\` / \`bulk_move\` | Folder + note-move ops |
 | \`context_fetch\` | Search notes by query |
 
 ### Knowledge Graph
 | Tool | When to use |
 |------|------------|
-| \`populate_graph\` | Initialize graph from notes (run once at start) |
-| \`create_node\` | Add a concept, tag, or note-linked node |
-| \`create_edge\` | Link two nodes with a typed relationship |
-| \`query_graph\` | Search graph by type, label, or connectivity |
-| \`get_neighbors\` | Explore connections from a node |
-| \`query_note_graph\` | Get subgraph around a specific note |
+| \`populate_graph\` | Initialize graph |
+| \`create_node\` / \`create_edge\` | Build structure |
+| \`query_graph\` / \`get_neighbors\` / \`query_note_graph\` | Explore |
 
 All tools require \`workspaceId: "${opts.workspaceId}"\`.`;
 }

package/dist/templates/codex.js

@@ -2,63 +2,67 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateCodexTemplate = generateCodexTemplate;
 function generateCodexTemplate(opts) {
-    return `# m-notes AI Knowledge Base
+    return `<!-- m-notes instructions v3 -->
+# m-notes — Your Wiki
 
 Server: ${opts.url}
 Workspace: ${opts.workspaceId}
 
+You are the author and maintainer of a living wiki. Raw sources are immutable inputs; your notes are the wiki; notes tagged \`type:config\` are the rules you follow when editing.
+
 ## Session Lifecycle
 
 ### Session Start
-Call \`project_context_load\` with workspaceId "${opts.workspaceId}" and a query describing your current task.
-To resume a previous session, call \`session_context_resume\` with workspaceId "${opts.workspaceId}".
+- Call \`project_context_load\` with workspaceId "${opts.workspaceId}".
+- To resume, call \`session_context_resume\`.
+- If the graph is empty, call \`populate_graph\` (idempotent).
+- Read any notes tagged \`type:config\` before editing.
 
 ### During Work
-Store discoveries, decisions, and patterns via \`knowledge_store\`:
-- workspaceId: "${opts.workspaceId}"
-- key: "<category>/<name>"
-- content: what you learned
-- tags: [category]
+- Recall before researching: \`recall_knowledge\`, \`search_notes\`.
+- Store discoveries via \`knowledge_store\` (key: \`<category>/<name>\`, tags: [category]).
+- When the user supplies a source (URL/paste/file), run the **ingest loop**:
+  1. \`search_notes\` + \`query_graph\` to find 3–15 related notes
+  2. Plan creates/updates with \`[[wikilinks]]\` connecting touched notes
+  3. Apply — each touched note gets a \`source/<slug>\` tag
+- Periodically run the **lint loop**: \`scan_knowledge_conflicts\`, find orphans via \`query_note_graph\`, fix broken \`[[wikilinks]]\`, update stale notes.
+- Every new or edited note must have at least one outbound \`[[wikilink]]\`.
 
 ### Key Naming Conventions
-- arch/{component} -- architecture decisions (e.g. arch/database, arch/auth)
+- arch/{component} -- architecture decisions
 - pattern/{name} -- code patterns and idioms
-- bug/{id} -- bug investigations and fixes
-- dep/{package} -- dependency notes and version constraints
-- decision/{topic} -- product/tech decisions with rationale
-- context/{area} -- project context and domain knowledge
+- bug/{id} -- bug investigations
+- dep/{package} -- dependency notes
+- decision/{topic} -- product/tech decisions
+- context/{area} -- domain knowledge
 
 ### Session End
-Call \`session_log\` with workspaceId "${opts.workspaceId}", a summary, decisions, and actions.
+- Call \`session_log\` with workspaceId "${opts.workspaceId}", summary, decisions, actions.
 
 ## Knowledge Graph
 
-Build structured relationships between concepts as you work. The graph maps how architecture components, dependencies, decisions, and patterns connect.
-
-### When to Build
-- Session start: call \`populate_graph\` if graph is empty (idempotent)
-- When you discover relationships between components, patterns, or decisions: create nodes and edges
-- Architecture decisions: create concept nodes, link with "related" or "parent" edges
+Every note belongs to the graph. Build relationships proactively.
 
-### Node types: note, tag, concept
-### Edge types: wikilink, related, parent, tagged, custom
+- Node types: note, tag, concept
+- Edge types: wikilink, related, parent, tagged, custom
 
 Example:
   create_node({ label: "Auth Module", nodeType: "concept", workspaceId: "${opts.workspaceId}" })
   create_edge({ sourceId: "...", targetId: "...", edgeType: "related", workspaceId: "${opts.workspaceId}" })
 
 ## Available MCP Tools
-- project_context_load -- load project context at session start
-- session_context_resume -- resume from previous session
-- knowledge_store -- store knowledge entries
-- recall_knowledge -- semantic search for knowledge
-- bulk_knowledge_recall -- recall by tag patterns
+- project_context_load -- load context at session start
+- session_context_resume -- resume previous session
+- knowledge_store -- store knowledge entry
+- recall_knowledge -- semantic search
+- bulk_knowledge_recall -- recall by tag pattern
 - knowledge_snapshot -- export all knowledge
+- scan_knowledge_conflicts -- lint for contradictions
 - session_log -- log session summary
+- create_note / update_note / append_to_note -- note authoring
+- search_notes / get_note / list_notes -- note retrieval
 - context_fetch -- search notes by query
-- populate_graph -- initialize knowledge graph from notes
-- create_node -- add a concept/tag/note node to the graph
-- create_edge -- link two nodes with a typed relationship
-- query_graph -- search graph by type, label, or connectivity
-- get_neighbors -- explore connections from a node`;
+- populate_graph -- initialize graph (idempotent)
+- create_node / create_edge -- build graph structure
+- query_graph / get_neighbors / query_note_graph -- explore graph`;
 }

package/dist/templates/openclaw.js

@@ -2,11 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateOpenClawTemplate = generateOpenClawTemplate;
 function generateOpenClawTemplate(opts) {
-    return `# m-notes Knowledge Base
+    return `<!-- m-notes instructions v3 -->
+# m-notes — Your Wiki
 
 **Server**: ${opts.url}
 **Workspace**: ${opts.workspaceId}
 
+You are the author of a living wiki. Notes are interlinked with \`[[wikilinks]]\`. Sources are immutable; your writing is the wiki.
+
+## Core Loops
+
+**Ingest** — when given a source (URL/paste): find 3+ related notes via \`recall_knowledge\`, update or create, link them with \`[[wikilinks]]\`, tag each with \`source/<slug>\`.
+
+**Lint** — periodically check for contradictions, orphan notes, broken wikilinks, stale entries.
+
 ## Quick Reference
 
 Store knowledge:
@@ -33,11 +42,11 @@ Call recall_knowledge with:
 
 ## Knowledge Graph
 
-Build structured relationships as you work:
+Every note should link to at least one other. Build the graph proactively:
 \`\`\`
 Call populate_graph with:
   - workspaceId: "${opts.workspaceId}"
-(initializes graph from existing notes — run once)
+(initializes from existing notes — idempotent)
 
 Call create_node with:
   - label: "<concept name>"
@@ -52,14 +61,14 @@ Call create_edge with:
 \`\`\`
 
 ## Available MCP Tools
-- \`knowledge_store\` -- Store knowledge entries
-- \`recall_knowledge\` -- Semantic search for knowledge
-- \`bulk_knowledge_recall\` -- Recall by tag patterns
+- \`knowledge_store\` -- Store knowledge
+- \`recall_knowledge\` -- Semantic search
+- \`bulk_knowledge_recall\` -- Recall by tag pattern
 - \`knowledge_snapshot\` -- Export all knowledge
-- \`context_fetch\` -- Search notes by query
-- \`populate_graph\` -- Initialize knowledge graph from notes
-- \`create_node\` -- Add concept/tag/note node to the graph
-- \`create_edge\` -- Link two nodes with a typed relationship
-- \`query_graph\` -- Search graph by type, label, or connectivity
-- \`get_neighbors\` -- Explore connections from a node`;
+- \`scan_knowledge_conflicts\` -- Lint: find contradictions
+- \`context_fetch\` / \`search_notes\` -- Search notes
+- \`create_note\` / \`update_note\` / \`append_to_note\` -- Note authoring
+- \`populate_graph\` -- Initialize graph
+- \`create_node\` / \`create_edge\` -- Build graph structure
+- \`query_graph\` / \`get_neighbors\` / \`query_note_graph\` -- Explore graph`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnotes-cli",
-  "version": "1.9.2",
+  "version": "1.10.1",
   "description": "CLI for m-notes AI knowledge base — manage notes, search, and CRUD from the terminal",
   "bin": {
     "mnotes": "./dist/index.js"