clawvault 3.5.0 → 3.5.2

package/README.md

@@ -267,24 +267,29 @@ clawvault setup --theme neural --canvas --bases
 
 ## OpenClaw Integration
 
-ClawVault integrates with OpenClaw as a plugin package (not the deprecated `openclaw hooks install/enable` flow):
+ClawVault integrates with OpenClaw as a plugin. Install the npm package, then configure it in your OpenClaw config:
 
 ```bash
-# Install ClawVault
-npm install -g clawvault
+# 1. Install the ClawVault package
+npm install clawvault
 
-# Add ClawVault package path to plugins.load.paths in openclaw.json
-# (You can use `npm root -g` to locate node_modules)
+# 2. Register the plugin and memory slot in openclaw.json
+openclaw config set plugins.entries.clawvault.package clawvault
+openclaw config set plugins.slots.memory clawvault
 
-# Enable plugin + memory slot in openclaw.json:
-# plugins.slots.memory = "clawvault"
-# plugins.entries.clawvault.enabled = true
+# 3. Configure your vault path
+openclaw config set plugins.entries.clawvault.config.vaultPath ~/my-vault
 
-# Verify runtime assumptions
+# 4. Verify
 clawvault compat
 ```
 
-The plugin provides lifecycle hooks, memory tools, and protocol-safe messaging behavior for OpenClaw sessions.
+The plugin automatically:
+- Detects context death and injects recovery alerts
+- Auto-checkpoints before session resets
+- Provides `--profile auto` for context queries
+
+> **Legacy note:** The older `openclaw hooks install` / `openclaw hooks enable` flow is no longer the recommended path. Use the plugin model above.
 
 ### MEMORY.md vs Vault
 
@@ -352,26 +357,29 @@ clawvault compat
 
 ## OpenClaw Setup (Canonical)
 
-Use this sequence for plugin-based OpenClaw integration:
+ClawVault integrates with OpenClaw as a plugin. Use this sequence:
 
 ```bash
-# Install CLI
-npm install -g clawvault
+# Install ClawVault
+npm install clawvault
+
+# Register plugin and memory slot
+openclaw config set plugins.entries.clawvault.package clawvault
+openclaw config set plugins.slots.memory clawvault
 
-# Locate global node_modules
-npm root -g
+# Configure vault path and desired features
+openclaw config set plugins.entries.clawvault.config.vaultPath ~/my-vault
+openclaw config set plugins.entries.clawvault.config.enableStartupRecovery true
+openclaw config set plugins.entries.clawvault.config.enableSessionContextInjection true
 
-# In openclaw.json:
-# - add <npm-root>/clawvault to plugins.load.paths
-# - set plugins.slots.memory = "clawvault"
-# - set plugins.entries.clawvault.enabled = true
-# - set plugins.entries.clawvault.config.vaultPath as needed
+# Verify
+clawvault compat
 ```
 
 Important:
 
-- `clawhub install clawvault` installs skill guidance, but does not configure OpenClaw plugin loading.
-- After changing plugin config, restart the OpenClaw gateway process.
+- `clawhub install clawvault` installs skill guidance, but does not replace plugin configuration.
+- After changing plugin config, restart the OpenClaw gateway process so plugin registration reloads.
 
 ## Minimal AGENTS.md Additions
 
@@ -489,9 +497,9 @@ vault/
   - `qmd` is optional; in-process BM25 search is available without it
   - if you want fallback compatibility, ensure `qmd --version` works in the same shell
 - Plugin not active in OpenClaw:
-  - verify `plugins.load.paths` includes the ClawVault package path
-  - verify `plugins.slots.memory` is `clawvault`
-  - verify `plugins.entries.clawvault.enabled` is `true`
+  - run `openclaw config set plugins.entries.clawvault.package clawvault`
+  - run `openclaw config set plugins.slots.memory clawvault`
+  - restart the OpenClaw gateway process
 - OpenClaw integration drift:
   - run `clawvault compat`
 - Session transcript corruption:

package/bin/command-registration.test.js

@@ -0,0 +1,179 @@
+import { describe, expect, it } from 'vitest';
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { registerCoreCommands } from './register-core-commands.js';
+import { registerMaintenanceCommands } from './register-maintenance-commands.js';
+import { registerQueryCommands } from './register-query-commands.js';
+import { registerResilienceCommands } from './register-resilience-commands.js';
+import { registerSessionLifecycleCommands } from './register-session-lifecycle-commands.js';
+import { registerTemplateCommands } from './register-template-commands.js';
+import { registerVaultOperationsCommands } from './register-vault-operations-commands.js';
+import { registerConfigCommands } from './register-config-commands.js';
+import { registerRouteCommands } from './register-route-commands.js';
+import {
+  chalkStub,
+  createGetVaultStub,
+  registerAllCommandModules,
+  stubResolveVaultPath
+} from './test-helpers/cli-command-fixtures.js';
+
+function listCommandNames(program) {
+  return program.commands.map((command) => command.name()).sort((a, b) => a.localeCompare(b));
+}
+
+describe('CLI command registration modules', () => {
+  it('registers core lifecycle commands', () => {
+    const program = new Command();
+    registerCoreCommands(program, {
+      chalk: chalkStub,
+      path,
+      fs,
+      createVault: async () => ({ getCategories: () => [], getQmdRoot: () => '', getQmdCollection: () => '' }),
+      getVault: createGetVaultStub({ store: async () => ({}), capture: async () => ({}) }),
+      runQmd: async () => {}
+    });
+
+    const names = listCommandNames(program);
+    expect(names).toEqual(expect.arrayContaining(['init', 'setup', 'store', 'patch', 'capture', 'inbox']));
+  });
+
+  it('registers query commands with profile option', () => {
+    const program = new Command();
+    registerQueryCommands(program, {
+      chalk: chalkStub,
+      getVault: createGetVaultStub({ find: async () => [], vsearch: async () => [] }),
+      resolveVaultPath: stubResolveVaultPath,
+      QmdUnavailableError: class extends Error {},
+      printQmdMissing: () => {}
+    });
+
+    const names = listCommandNames(program);
+    expect(names).toEqual(expect.arrayContaining(['search', 'vsearch', 'context', 'recall', 'inject', 'observe', 'reflect', 'session-recap']));
+
+    const contextCommand = program.commands.find((command) => command.name() === 'context');
+    const profileOption = contextCommand?.options.find((option) => option.flags.includes('--profile <profile>'));
+    expect(profileOption?.description).toContain('auto');
+  });
+
+  it('registers vault operation commands', () => {
+    const program = new Command();
+    registerVaultOperationsCommands(program, {
+      chalk: chalkStub,
+      fs,
+      getVault: createGetVaultStub({
+        list: async () => [],
+        get: async () => null,
+        stats: async () => ({ tags: [], categories: {} }),
+        sync: async () => ({ copied: [], deleted: [], unchanged: [], errors: [] }),
+        reindex: async () => 0,
+        remember: async () => ({ id: '' }),
+        getQmdCollection: () => ''
+      }),
+      runQmd: async () => {},
+      resolveVaultPath: stubResolveVaultPath,
+      path
+    });
+
+    const names = listCommandNames(program);
+    expect(names).toEqual(expect.arrayContaining([
+      'list',
+      'get',
+      'stats',
+      'sync',
+      'reindex',
+      'remember',
+      'shell-init',
+      'dashboard'
+    ]));
+  });
+
+  it('registers maintenance, resilience, session-lifecycle and template commands', () => {
+    const program = new Command();
+    registerMaintenanceCommands(program, { chalk: chalkStub });
+    registerResilienceCommands(program, {
+      chalk: chalkStub,
+      resolveVaultPath: stubResolveVaultPath
+    });
+    registerSessionLifecycleCommands(program, {
+      chalk: chalkStub,
+      resolveVaultPath: stubResolveVaultPath,
+      QmdUnavailableError: class extends Error {},
+      printQmdMissing: () => {},
+      getVault: createGetVaultStub({
+        createHandoff: async () => ({ id: '', path: '' }),
+        getQmdCollection: () => '',
+        generateRecap: async () => ({}),
+        formatRecap: () => ''
+      }),
+      runQmd: async () => {}
+    });
+    registerTemplateCommands(program, { chalk: chalkStub });
+    registerConfigCommands(program, {
+      chalk: chalkStub,
+      resolveVaultPath: stubResolveVaultPath
+    });
+    registerRouteCommands(program, {
+      chalk: chalkStub,
+      resolveVaultPath: stubResolveVaultPath
+    });
+
+    const names = listCommandNames(program);
+    expect(names).toEqual(expect.arrayContaining([
+      'doctor',
+      'benchmark',
+      'maintain',
+      'embed',
+      'compat',
+      'graph',
+      'entities',
+      'entity',
+      'link',
+      'rebuild',
+      'archive',
+      'migrate-observations',
+      'replay',
+      'sync-bd',
+      'checkpoint',
+      'recover',
+      'status',
+      'clean-exit',
+      'repair-session',
+      'wake',
+      'sleep',
+      'handoff',
+      'recap',
+      'template',
+      'config',
+      'route'
+    ]));
+
+    const templateCommand = program.commands.find((command) => command.name() === 'template');
+    const templateSubcommands = templateCommand?.commands.map((command) => command.name()) ?? [];
+    expect(templateSubcommands).toEqual(expect.arrayContaining(['list', 'create', 'add']));
+
+    const compatCommand = program.commands.find((command) => command.name() === 'compat');
+    const strictOption = compatCommand?.options.find((option) => option.flags.includes('--strict'));
+    const baseDirOption = compatCommand?.options.find((option) => option.flags.includes('--base-dir <path>'));
+    expect(strictOption).toBeTruthy();
+    expect(baseDirOption).toBeTruthy();
+  });
+
+  it('keeps top-level command names unique when modules are combined', () => {
+    const program = registerAllCommandModules(new Command());
+
+    const names = program.commands.map((command) => command.name());
+    const unique = new Set(names);
+    expect(unique.size).toBe(names.length);
+  });
+
+  it('does not register removed workgraph commands', () => {
+    const program = registerAllCommandModules(new Command());
+    const names = listCommandNames(program);
+
+    expect(names).not.toContain('wg');
+    expect(names).not.toContain('thread');
+    expect(names).not.toContain('primitive');
+    expect(names).not.toContain('ledger');
+  });
+});

package/bin/command-runtime.test.js

@@ -0,0 +1,154 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import path from 'path';
+
+const {
+  spawnMock,
+  resolveConfiguredVaultPathMock,
+  clawvaultCtorMock,
+  loadMock
+} = vi.hoisted(() => ({
+  spawnMock: vi.fn(),
+  resolveConfiguredVaultPathMock: vi.fn(),
+  clawvaultCtorMock: vi.fn(),
+  loadMock: vi.fn()
+}));
+
+vi.mock('child_process', () => ({
+  spawn: spawnMock
+}));
+
+vi.mock('../dist/index.js', () => ({
+  ClawVault: clawvaultCtorMock,
+  resolveVaultPath: resolveConfiguredVaultPathMock,
+  QmdUnavailableError: class QmdUnavailableError extends Error {},
+  QMD_INSTALL_COMMAND: 'install-qmd'
+}));
+
+async function loadRuntimeModule() {
+  vi.resetModules();
+  return await import('./command-runtime.js');
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  clawvaultCtorMock.mockImplementation(() => ({
+    load: loadMock
+  }));
+});
+
+describe('command runtime helpers', () => {
+  it('delegates vault path resolution and loads vaults', async () => {
+    resolveConfiguredVaultPathMock.mockReturnValue('/resolved/vault');
+    loadMock.mockResolvedValue(undefined);
+    const { getVault, resolveVaultPath } = await loadRuntimeModule();
+
+    const resolved = resolveVaultPath('/explicit');
+    expect(resolveConfiguredVaultPathMock).toHaveBeenCalledWith({ explicitPath: '/explicit' });
+    expect(resolved).toBe('/resolved/vault');
+
+    await getVault('/explicit');
+    expect(clawvaultCtorMock).toHaveBeenCalledWith('/resolved/vault');
+    expect(loadMock).toHaveBeenCalled();
+  });
+
+  it('maps qmd ENOENT failures to QmdUnavailableError', async () => {
+    const { runQmd, QmdUnavailableError } = await loadRuntimeModule();
+    spawnMock.mockImplementation(() => {
+      const handlers = {};
+      const proc = {
+        on: (event, handler) => {
+          handlers[event] = handler;
+        }
+      };
+      queueMicrotask(() => {
+        handlers.error?.({ code: 'ENOENT' });
+      });
+      return proc;
+    });
+
+    await expect(runQmd(['update'])).rejects.toBeInstanceOf(QmdUnavailableError);
+  });
+
+  it('injects qmd index from environment when configured', async () => {
+    const previous = process.env.CLAWVAULT_QMD_INDEX;
+    process.env.CLAWVAULT_QMD_INDEX = 'clawvault-test';
+
+    try {
+      const { runQmd } = await loadRuntimeModule();
+      spawnMock.mockImplementation((_command, _args) => {
+        const handlers = {};
+        const proc = {
+          on: (event, handler) => {
+            handlers[event] = handler;
+          }
+        };
+        queueMicrotask(() => {
+          handlers.close?.(0);
+        });
+        return proc;
+      });
+
+      await runQmd(['update']);
+      expect(spawnMock).toHaveBeenCalledWith(
+        'qmd',
+        ['--index', 'clawvault-test', 'update'],
+        { stdio: 'inherit' }
+      );
+    } finally {
+      if (previous === undefined) {
+        delete process.env.CLAWVAULT_QMD_INDEX;
+      } else {
+        process.env.CLAWVAULT_QMD_INDEX = previous;
+      }
+    }
+  });
+
+  it('surfaces qmd non-zero exit codes as errors', async () => {
+    const { runQmd } = await loadRuntimeModule();
+    spawnMock.mockImplementation(() => {
+      const handlers = {};
+      const proc = {
+        on: (event, handler) => {
+          handlers[event] = handler;
+        }
+      };
+      queueMicrotask(() => {
+        handlers.close?.(2);
+      });
+      return proc;
+    });
+
+    await expect(runQmd(['update'])).rejects.toThrow('qmd exited with code 2');
+  });
+
+  it('exports and enforces argument/path sanitization helpers', async () => {
+    const { sanitizeQmdArg, validatePathWithinBase } = await loadRuntimeModule();
+    expect(sanitizeQmdArg('update')).toBe('update');
+    expect(sanitizeQmdArg(42)).toBe('42');
+    expect(() => sanitizeQmdArg('bad\0arg')).toThrow('contains null byte');
+
+    const safePath = validatePathWithinBase('notes/today.md', '/tmp/vault');
+    expect(safePath).toBe(path.resolve('/tmp/vault', 'notes/today.md'));
+    expect(() => validatePathWithinBase('../etc/passwd', '/tmp/vault')).toThrow('Path traversal detected');
+  });
+
+  it('rejects qmd args with null-byte injection attempts', async () => {
+    const { runQmd } = await loadRuntimeModule();
+    await expect(runQmd(['up\0date'])).rejects.toThrow('contains null byte');
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it('prints consistent qmd missing guidance', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      const { printQmdMissing } = await loadRuntimeModule();
+      printQmdMissing();
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('ClawVault requires qmd.'));
+      expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('install-qmd'));
+    } finally {
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+});

package/bin/help-contract.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { registerAllCommandModules } from './test-helpers/cli-command-fixtures.js';
+
+describe('CLI help contract', () => {
+  it('includes expected high-level command surface', () => {
+    const help = registerAllCommandModules().helpInformation();
+    expect(help).toContain('init');
+    expect(help).toContain('context');
+    expect(help).toContain('recall');
+    expect(help).toContain('inject');
+    expect(help).toContain('doctor');
+    expect(help).toContain('benchmark');
+    expect(help).toContain('maintain');
+    expect(help).toContain('embed');
+    expect(help).toContain('inbox');
+    expect(help).toContain('patch');
+    expect(help).toContain('compat');
+    expect(help).toContain('graph');
+    expect(help).toContain('reflect');
+    expect(help).toContain('replay');
+    expect(help).toContain('repair-session');
+    expect(help).toContain('project');
+    expect(help).toContain('template');
+    expect(help).toContain('config');
+    expect(help).toContain('route');
+    expect(help).toContain('entity');
+  });
+
+  it('documents context/compat/inject/project help details', () => {
+    const program = registerAllCommandModules();
+    const contextHelp = program.commands.find((command) => command.name() === 'context')?.helpInformation() ?? '';
+    const compatHelp = program.commands.find((command) => command.name() === 'compat')?.helpInformation() ?? '';
+    const injectHelp = program.commands.find((command) => command.name() === 'inject')?.helpInformation() ?? '';
+    const projectCommand = program.commands.find((command) => command.name() === 'project');
+    const projectListHelp = projectCommand?.commands.find((command) => command.name() === 'list')?.helpInformation() ?? '';
+    const projectBoardHelp = projectCommand?.commands.find((command) => command.name() === 'board')?.helpInformation() ?? '';
+    expect(contextHelp).toContain('--profile <profile>');
+    expect(contextHelp).toContain('auto');
+    expect(compatHelp).toContain('--strict');
+    expect(injectHelp).toContain('inject.maxResults');
+    expect(injectHelp).toContain('inject.scope');
+    expect(projectListHelp).toContain('archived projects are hidden');
+    expect(projectBoardHelp).toContain('default: status');
+  });
+
+  it('does not advertise removed workgraph commands', () => {
+    const program = registerAllCommandModules();
+    const names = program.commands.map((command) => command.name());
+
+    expect(names).not.toContain('wg');
+    expect(names).not.toContain('thread');
+    expect(names).not.toContain('primitive');
+    expect(names).not.toContain('ledger');
+  });
+});

package/bin/register-config-route-commands.test.js

@@ -0,0 +1,121 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Command } from 'commander';
+import { registerConfigCommands } from './register-config-commands.js';
+import { registerRouteCommands } from './register-route-commands.js';
+import { chalkStub } from './test-helpers/cli-command-fixtures.js';
+
+const {
+  getConfigValueMock,
+  setConfigValueMock,
+  listConfigMock,
+  resetConfigMock,
+  addRouteRuleMock,
+  listRouteRulesMock,
+  removeRouteRuleMock,
+  testRouteRuleMock
+} = vi.hoisted(() => ({
+  getConfigValueMock: vi.fn(),
+  setConfigValueMock: vi.fn(),
+  listConfigMock: vi.fn(),
+  resetConfigMock: vi.fn(),
+  addRouteRuleMock: vi.fn(),
+  listRouteRulesMock: vi.fn(),
+  removeRouteRuleMock: vi.fn(),
+  testRouteRuleMock: vi.fn()
+}));
+
+vi.mock('../dist/index.js', () => ({
+  SUPPORTED_CONFIG_KEYS: [
+    'name',
+    'categories',
+    'theme',
+    'observe.model',
+    'observe.provider',
+    'observer.compression.provider',
+    'observer.compression.model',
+    'observer.compression.baseUrl',
+    'observer.compression.apiKey',
+    'context.maxResults',
+    'context.defaultProfile',
+    'graph.maxHops',
+    'inject.maxResults',
+    'inject.useLlm',
+    'inject.scope'
+  ],
+  getConfigValue: getConfigValueMock,
+  setConfigValue: setConfigValueMock,
+  listConfig: listConfigMock,
+  resetConfig: resetConfigMock,
+  addRouteRule: addRouteRuleMock,
+  listRouteRules: listRouteRulesMock,
+  removeRouteRule: removeRouteRuleMock,
+  testRouteRule: testRouteRuleMock
+}));
+
+function buildProgram() {
+  const program = new Command();
+  const resolveVaultPath = (value) => value ?? '/vault';
+  registerConfigCommands(program, { chalk: chalkStub, resolveVaultPath });
+  registerRouteCommands(program, { chalk: chalkStub, resolveVaultPath });
+  return program;
+}
+
+async function runCommand(args) {
+  const program = buildProgram();
+  await program.parseAsync(args, { from: 'user' });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  getConfigValueMock.mockReturnValue('demo-vault');
+  setConfigValueMock.mockReturnValue({ value: 'demo-vault' });
+  listConfigMock.mockReturnValue({ name: 'demo-vault', context: { maxResults: 5 } });
+  resetConfigMock.mockReturnValue(undefined);
+  addRouteRuleMock.mockReturnValue({ pattern: 'Pedro', target: 'people/pedro', priority: 1 });
+  listRouteRulesMock.mockReturnValue([{ pattern: 'Pedro', target: 'people/pedro', priority: 1 }]);
+  removeRouteRuleMock.mockReturnValue(true);
+  testRouteRuleMock.mockReturnValue({ pattern: 'Pedro', target: 'people/pedro', priority: 1 });
+});
+
+describe('config and route command registrations', () => {
+  it('executes config get/set/list subcommands', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      await runCommand(['config', 'get', 'name']);
+      expect(getConfigValueMock).toHaveBeenCalledWith('/vault', 'name');
+
+      await runCommand(['config', 'set', 'categories', 'people,projects']);
+      expect(setConfigValueMock).toHaveBeenCalledWith('/vault', 'categories', 'people,projects');
+
+      await runCommand(['config', 'list']);
+      expect(listConfigMock).toHaveBeenCalledWith('/vault');
+
+      const output = logSpy.mock.calls.map((call) => call.join(' ')).join('\n');
+      expect(output).toContain('context.maxResults');
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it('executes route add/remove/test subcommands', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      await runCommand(['route', 'add', 'Pedro', 'people/pedro']);
+      expect(addRouteRuleMock).toHaveBeenCalledWith('/vault', 'Pedro', 'people/pedro');
+
+      await runCommand(['route', 'remove', 'Pedro']);
+      expect(removeRouteRuleMock).toHaveBeenCalledWith('/vault', 'Pedro');
+
+      await runCommand(['route', 'test', 'Talked to Pedro']);
+      expect(testRouteRuleMock).toHaveBeenCalledWith('/vault', 'Talked to Pedro');
+
+      await runCommand(['route', 'list']);
+      expect(listRouteRulesMock).toHaveBeenCalledWith('/vault');
+
+      const output = logSpy.mock.calls.map((call) => call.join(' ')).join('\n');
+      expect(output).toContain('Route matched');
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+});

package/bin/register-core-commands.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { registerCoreCommands } from './register-core-commands.js';
+import { chalkStub } from './test-helpers/cli-command-fixtures.js';
+
+function buildProgram(patchImpl) {
+  const program = new Command();
+  registerCoreCommands(program, {
+    chalk: chalkStub,
+    path,
+    fs,
+    createVault: async () => ({ getCategories: () => [], getQmdRoot: () => '', getQmdCollection: () => '' }),
+    getVault: async () => ({ patch: patchImpl }),
+    runQmd: async () => {}
+  });
+  return program;
+}
+
+describe('register-core-commands patch command', () => {
+  it('exposes patch command mode flags', () => {
+    const program = buildProgram(async () => ({ id: 'decisions/example', path: '/vault/decisions/example.md' }));
+    const patchCommand = program.commands.find((command) => command.name() === 'patch');
+    expect(patchCommand).toBeDefined();
+    const optionFlags = patchCommand?.options.map((option) => option.flags) ?? [];
+    expect(optionFlags).toEqual(expect.arrayContaining([
+      '--append <text>',
+      '--replace <text>',
+      '--with <text>',
+      '--section <heading>',
+      '--content <text>',
+      '-v, --vault <path>'
+    ]));
+  });
+
+  it('forwards append mode payload to vault.patch', async () => {
+    const patchMock = vi.fn(async () => ({ id: 'decisions/example', path: '/vault/decisions/example.md' }));
+    const program = buildProgram(patchMock);
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    try {
+      await program.parseAsync(['patch', 'decisions/example', '--append', 'new line'], { from: 'user' });
+      expect(patchMock).toHaveBeenCalledWith({
+        idOrPath: 'decisions/example',
+        mode: 'append',
+        append: 'new line'
+      });
+      expect(errorSpy).not.toHaveBeenCalled();
+    } finally {
+      logSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it('forwards section/content mode payload to vault.patch', async () => {
+    const patchMock = vi.fn(async () => ({ id: 'decisions/example', path: '/vault/decisions/example.md' }));
+    const program = buildProgram(patchMock);
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    try {
+      await program.parseAsync(
+        ['patch', 'decisions/example', '--section', 'Notes', '--content', 'updated notes'],
+        { from: 'user' }
+      );
+      expect(patchMock).toHaveBeenCalledWith({
+        idOrPath: 'decisions/example',
+        mode: 'content',
+        content: 'updated notes',
+        section: 'Notes'
+      });
+      expect(errorSpy).not.toHaveBeenCalled();
+    } finally {
+      logSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+});