clawvault 2.5.1 → 2.5.2

package/README.md

@@ -92,6 +92,7 @@ Auto-compress conversations into prioritized observations. Critical items route
 ```bash
 clawvault observe --compress session.md      # One-shot compression
 clawvault observe --active                   # Incremental from transcripts
+clawvault observe --cron                     # Cron-safe one-shot summary + exit code
 ```
 
 ### 🛡️ Context Death Recovery

package/bin/command-registration.test.js

@@ -121,6 +121,7 @@ describe('CLI command registration modules', () => {
     const names = listCommandNames(program);
     expect(names).toEqual(expect.arrayContaining([
       'doctor',
+      'embed',
       'compat',
       'graph',
       'entities',

package/bin/command-runtime.js

@@ -8,6 +8,8 @@ import {
   resolveVaultPath as resolveConfiguredVaultPath
 } from '../dist/index.js';
 
+const QMD_INDEX_ENV_VAR = 'CLAWVAULT_QMD_INDEX';
+
 /**
  * Validates that a path is within an allowed base directory.
  * Prevents path traversal attacks.
@@ -29,15 +31,29 @@ export function validatePathWithinBase(inputPath, basePath) {
 
 /**
  * Sanitizes an argument that may contain a path to prevent injection.
- * @param {string} arg - The argument to sanitize
+ * @param {unknown} arg - The argument to sanitize
  * @returns {string} The sanitized argument
  */
-function sanitizeQmdArg(arg) {
+export function sanitizeQmdArg(arg) {
+  const normalizedArg = String(arg);
   // Reject arguments with null bytes (injection attempt)
-  if (arg.includes('\0')) {
+  if (normalizedArg.includes('\0')) {
     throw new Error('Invalid argument: contains null byte');
   }
-  return arg;
+  return normalizedArg;
+}
+
+function withQmdIndex(args) {
+  if (args.includes('--index')) {
+    return [...args];
+  }
+
+  const indexName = process.env[QMD_INDEX_ENV_VAR]?.trim();
+  if (!indexName) {
+    return [...args];
+  }
+
+  return ['--index', indexName, ...args];
 }
 
 export function resolveVaultPath(vaultPath) {
@@ -53,7 +69,7 @@ export async function getVault(vaultPath) {
 export async function runQmd(args) {
   return new Promise((resolve, reject) => {
     // Sanitize all arguments before passing to spawn
-    const sanitizedArgs = args.map(sanitizeQmdArg);
+    const sanitizedArgs = withQmdIndex(args).map(sanitizeQmdArg);
     const proc = spawn('qmd', sanitizedArgs, { stdio: 'inherit' });
     proc.on('close', (code) => {
       if (code === 0) resolve();

package/bin/command-runtime.test.js

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import path from 'path';
 
 const {
   spawnMock,
@@ -68,6 +69,40 @@ describe('command runtime helpers', () => {
     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(() => {
@@ -86,6 +121,23 @@ describe('command runtime helpers', () => {
     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(() => {});

package/bin/help-contract.test.js

@@ -7,22 +7,33 @@ describe('CLI help contract', () => {
     expect(help).toContain('init');
     expect(help).toContain('context');
     expect(help).toContain('inject');
+    expect(help).toContain('doctor');
+    expect(help).toContain('embed');
     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');
   });
 
-  it('documents context auto profile and compat strict options', () => {
+  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');
   });
 });

package/bin/register-config-commands.js

@@ -66,7 +66,7 @@ function normalizeConfigKey(key) {
 export function registerConfigCommands(program, { chalk, resolveVaultPath }) {
   const config = program
     .command('config')
-    .description('Read and modify runtime config');
+    .description('Read and modify runtime configuration');
 
   config
     .command('get <key>')
@@ -135,7 +135,7 @@ export function registerConfigCommands(program, { chalk, resolveVaultPath }) {
   config
     .command('reset')
     .description('Reset runtime config values to defaults')
-    .option('--confirm', 'Confirm reset')
+    .option('--confirm', 'Confirm reset (required)')
     .option('-v, --vault <path>', 'Vault path')
     .action(async (options) => {
       try {

package/bin/register-core-commands.js

@@ -11,8 +11,8 @@ export function registerCoreCommands(
   // === INIT ===
   program
     .command('init [path]')
-    .description('Initialize a new ClawVault')
-    .option('-n, --name <name>', 'Vault name')
+    .description('Initialize a new ClawVault vault')
+    .option('-n, --name <name>', 'Vault name (default: target directory name)')
     .option('--qmd', 'Set up qmd semantic search collection')
     .option('--qmd-collection <name>', 'qmd collection name (defaults to vault name)')
     .option('--no-bases', 'Skip Obsidian Bases file generation')
@@ -20,7 +20,7 @@ export function registerCoreCommands(
     .option('--no-graph', 'Skip initial graph build')
     .option('--categories <list>', 'Comma-separated list of custom categories to create')
     .option('--canvas', 'Generate a vault status canvas dashboard on init')
-    .option('--theme <style>', 'Graph color theme to apply (neural, minimal, none)', 'none')
+    .option('--theme <style>', 'Graph color theme to apply (neural, minimal, none) (default: none)', 'none')
     .option('--minimal', 'Create minimal vault (memory categories only, no tasks/bases/graph)')
     .action(async (vaultPath, options) => {
       const targetPath = vaultPath || '.';
@@ -135,14 +135,14 @@ export function registerCoreCommands(
   // === SETUP ===
   program
     .command('setup')
-    .description('Auto-discover and configure a ClawVault')
+    .description('Auto-discover and configure an existing ClawVault vault')
     .option('--graph-colors', 'Set up graph color scheme for Obsidian')
     .option('--no-graph-colors', 'Skip graph color configuration')
     .option('--bases', 'Generate Obsidian Bases views for task management')
     .option('--no-bases', 'Skip Bases file generation')
     .option('--canvas', 'Generate vault status canvas dashboard')
     .option('--no-canvas', 'Skip canvas generation')
-    .option('--theme <style>', 'Graph color theme (neural, minimal, none)', 'neural')
+    .option('--theme <style>', 'Graph color theme (neural, minimal, none) (default: neural)', 'neural')
     .option('--force', 'Overwrite existing configuration files')
     .option('-v, --vault <path>', 'Vault path')
     .action(async (options) => {
@@ -165,11 +165,11 @@ export function registerCoreCommands(
   // === STORE ===
   program
     .command('store')
-    .description('Store a new memory')
+    .description('Store a new memory document')
     .requiredOption('-c, --category <category>', 'Category (preferences, decisions, patterns, people, projects, goals, transcripts, inbox)')
     .requiredOption('-t, --title <title>', 'Document title')
     .option('--content <content>', 'Content body')
-    .option('-f, --file <file>', 'Read content from file')
+    .option('-f, --file <file>', 'Read content from file (validated against current working directory)')
     .option('--stdin', 'Read content from stdin')
     .option('--overwrite', 'Overwrite if exists')
     .option('--no-index', 'Skip qmd index update (auto-updates by default)')
@@ -215,10 +215,10 @@ export function registerCoreCommands(
   // === CAPTURE ===
   program
     .command('capture <note>')
-    .description('Quick capture to inbox')
+    .description('Quick-capture a note to inbox')
     .option('-t, --title <title>', 'Note title')
     .option('-v, --vault <path>', 'Vault path')
-    .option('--no-index', 'Skip qmd index update')
+    .option('--no-index', 'Skip qmd index update (auto-updates by default)')
     .action(async (note, options) => {
       try {
         const vault = await getVault(options.vault);

package/bin/register-kanban-commands.js

@@ -8,17 +8,17 @@ export function registerKanbanCommands(
 ) {
   const kanbanCmd = program
     .command('kanban')
-    .description('Sync Obsidian Kanban boards with task frontmatter');
+    .description('Manage Obsidian Kanban sync for task frontmatter');
 
   kanbanCmd
     .command('sync')
     .description('Generate and sync an Obsidian Kanban board from tasks')
-    .option('-v, --vault <path>', 'Vault path')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
     .option('--output <path>', 'Board markdown path (default: Board.md)')
-    .option('--group-by <field>', 'Grouping field (status, priority, project, owner)')
+    .option('--group-by <field>', 'Grouping field (status, priority, project, owner) (default: status)')
     .option('--filter-project <project>', 'Only include tasks from a project')
     .option('--filter-owner <owner>', 'Only include tasks for an owner')
-    .option('--include-done', 'Include done tasks')
+    .option('--include-done', 'Include done tasks (default: hidden)')
     .action(async (options) => {
       try {
         const vaultPath = resolveVaultPath(options.vault);
@@ -39,7 +39,7 @@ export function registerKanbanCommands(
   kanbanCmd
     .command('import')
     .description('Import lane state from an Obsidian Kanban board into tasks')
-    .option('-v, --vault <path>', 'Vault path')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
     .option('--output <path>', 'Board markdown path (default: Board.md)')
     .action(async (options) => {
       try {

package/bin/register-maintenance-commands.js

@@ -7,27 +7,42 @@ export function registerMaintenanceCommands(program, { chalk }) {
   // === DOCTOR (health check) ===
   program
     .command('doctor')
-    .description('Check ClawVault setup health')
+    .description('Diagnose vault health and optionally apply fixes')
     .option('-v, --vault <path>', 'Vault path')
+    .option('--fix', 'Apply safe auto-fixes for qmd index, embeddings, and dead collections')
+    .option('--json', 'Output machine-readable JSON')
     .action(async (options) => {
       try {
         const { doctor } = await import('../dist/commands/doctor.js');
-        const report = await doctor(options.vault);
+        const report = await doctor({
+          vaultPath: options.vault,
+          fix: options.fix
+        });
 
-        console.log(chalk.cyan('\n🩺 ClawVault Health Check\n'));
-        if (report.vaultPath) {
-          console.log(chalk.dim(`Vault: ${report.vaultPath}`));
-          console.log();
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+          return;
         }
 
+        console.log(chalk.cyan('\n🩺 ClawVault Health Check\n'));
+        console.log(chalk.dim(`Vault: ${report.vaultPath}`));
+        console.log(chalk.dim(`qmd collection: ${report.qmdCollection}`));
+        console.log(chalk.dim(`qmd root: ${report.qmdRoot}`));
+        console.log();
+
         for (const check of report.checks) {
           const prefix = check.status === 'ok'
             ? chalk.green('✓')
             : check.status === 'warn'
               ? chalk.yellow('⚠')
               : chalk.red('✗');
-          const detail = check.detail ? ` — ${check.detail}` : '';
-          console.log(`${prefix} ${check.label}${detail}`);
+          const line = `${check.label}: ${check.detail}`;
+          const renderedLine = check.status === 'ok'
+            ? chalk.green(line)
+            : check.status === 'warn'
+              ? chalk.yellow(line)
+              : chalk.red(line);
+          console.log(`${prefix} ${renderedLine}`);
           if (check.hint) {
             console.log(chalk.dim(`  ${check.hint}`));
           }
@@ -38,7 +53,9 @@ export function registerMaintenanceCommands(program, { chalk }) {
         if (issues === 0) {
           console.log(chalk.green('✅ ClawVault is healthy!\n'));
         } else {
-          console.log(chalk.yellow(`⚠ ${issues} issue(s) found\n`));
+          const summary = `${report.errors} error(s), ${report.warnings} warning(s)`;
+          const colorized = report.errors > 0 ? chalk.red(summary) : chalk.yellow(summary);
+          console.log(`${report.errors > 0 ? '✗' : '⚠'} ${colorized}\n`);
         }
       } catch (err) {
         console.error(chalk.red(`Error: ${err.message}`));
@@ -46,6 +63,23 @@ export function registerMaintenanceCommands(program, { chalk }) {
       }
     });
 
+  // === EMBED ===
+  program
+    .command('embed')
+    .description('Run qmd embedding for pending vault documents')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        const { embedCommand } = await import('../dist/commands/embed.js');
+        await embedCommand({
+          vaultPath: options.vault
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
   // === COMPAT (OpenClaw compatibility) ===
   program
     .command('compat')
@@ -160,7 +194,7 @@ export function registerMaintenanceCommands(program, { chalk }) {
   program
     .command('archive')
     .description('Archive old observations into ledger/archive')
-    .option('--older-than <days>', 'Archive observations older than this many days', '14')
+    .option('--older-than <days>', 'Archive observations older than this many days (default: 14)', '14')
     .option('--dry-run', 'Show archive candidates without writing')
     .option('-v, --vault <path>', 'Vault path')
     .action(async (options) => {

package/bin/register-project-commands.js

@@ -18,14 +18,14 @@ export function registerProjectCommands(
 ) {
   const projectCmd = program
     .command('project')
-    .description('Project management');
+    .description('Manage projects and project boards');
 
   projectCmd
     .command('add <title>')
     .description('Add a new project')
-    .option('-v, --vault <path>', 'Vault path')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
     .option('--owner <owner>', 'Project owner')
-    .option('--status <status>', 'Project status (active, paused, completed, archived)')
+    .option('--status <status>', 'Project status (active, paused, completed, archived) (default: active)')
     .option('--team <team>', 'Comma-separated team members')
     .option('--client <client>', 'Client name')
     .option('--tags <tags>', 'Comma-separated tags')
@@ -60,7 +60,7 @@ export function registerProjectCommands(
   projectCmd
     .command('update <slug>')
     .description('Update a project')
-    .option('-v, --vault <path>', 'Vault path')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
     .option('--status <status>', 'Project status (active, paused, completed, archived)')
     .option('--owner <owner>', 'Project owner')
     .option('--team <team>', 'Comma-separated team members')
@@ -97,7 +97,7 @@ export function registerProjectCommands(
   projectCmd
     .command('archive <slug>')
     .description('Archive a project')
-    .option('-v, --vault <path>', 'Vault path')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
     .option('--reason <reason>', 'Reason for archiving')
     .action(async (slug, options) => {
       try {
@@ -117,9 +117,9 @@ export function registerProjectCommands(
 
   projectCmd
     .command('list')
-    .description('List projects')
-    .option('-v, --vault <path>', 'Vault path')
-    .option('--status <status>', 'Filter by status')
+    .description('List projects (archived projects are hidden unless --status archived)')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
+    .option('--status <status>', 'Filter by status (active, paused, completed, archived)')
     .option('--owner <owner>', 'Filter by owner')
     .option('--client <client>', 'Filter by client')
     .option('--tag <tag>', 'Filter by tag')
@@ -146,7 +146,7 @@ export function registerProjectCommands(
   projectCmd
     .command('show <slug>')
     .description('Show project details')
-    .option('-v, --vault <path>', 'Vault path')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
     .option('--json', 'Output as JSON')
     .action(async (slug, options) => {
       try {
@@ -166,8 +166,8 @@ export function registerProjectCommands(
 
   projectCmd
     .command('tasks <slug>')
-    .description('List tasks for a project')
-    .option('-v, --vault <path>', 'Vault path')
+    .description('List tasks linked to a project')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
     .option('--json', 'Output as JSON')
     .action(async (slug, options) => {
       try {
@@ -187,10 +187,10 @@ export function registerProjectCommands(
 
   projectCmd
     .command('board')
-    .description('Generate project kanban board')
-    .option('-v, --vault <path>', 'Vault path')
+    .description('Generate and sync the project kanban board')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
     .option('--output <path>', 'Board markdown path (default: Projects-Board.md)')
-    .option('--group-by <field>', 'Grouping field (status, owner, client)')
+    .option('--group-by <field>', 'Grouping field (status, owner, client) (default: status)')
     .action(async (options) => {
       try {
         const vaultPath = resolveVaultPath(options.vault);

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

@@ -76,6 +76,11 @@ describe('register-project-commands', () => {
       '--output <path>',
       '--group-by <field>'
     ]));
+
+    expect(listCommand?.description()).toContain('archived projects are hidden');
+
+    const boardGroupByOption = boardCommand?.options.find((option) => option.flags === '--group-by <field>');
+    expect(boardGroupByOption?.description).toContain('default: status');
   });
 
   it('dispatches project subcommands to project command handler', async () => {

package/bin/register-query-commands.js

@@ -16,7 +16,7 @@ export function registerQueryCommands(
   program
     .command('search <query>')
     .description('Search the vault via qmd (BM25)')
-    .option('-n, --limit <n>', 'Max results', '10')
+    .option('-n, --limit <n>', 'Max results (default: 10)', '10')
     .option('-c, --category <category>', 'Filter by category')
     .option('--tags <tags>', 'Filter by tags (comma-separated)')
     .option('--recent', 'Boost recent documents')
@@ -71,7 +71,7 @@ export function registerQueryCommands(
   program
     .command('vsearch <query>')
     .description('Semantic search via qmd (requires qmd installed)')
-    .option('-n, --limit <n>', 'Max results', '5')
+    .option('-n, --limit <n>', 'Max results (default: 5)', '5')
     .option('-c, --category <category>', 'Filter by category')
     .option('--tags <tags>', 'Filter by tags (comma-separated)')
     .option('--recent', 'Boost recent documents')
@@ -126,13 +126,13 @@ export function registerQueryCommands(
   program
     .command('context <task>')
     .description('Generate task-relevant context for prompt injection')
-    .option('-n, --limit <n>', 'Max results', '5')
-    .option('--format <format>', 'Output format (markdown|json)', 'markdown')
+    .option('-n, --limit <n>', 'Max results (default: 5)', '5')
+    .option('--format <format>', 'Output format (markdown|json) (default: markdown)', 'markdown')
     .option('--recent', 'Boost recent documents (enabled by default)', true)
-    .option('--include-observations', 'Include observation memories in output', true)
+    .option('--include-observations', 'Include observation memories in output (enabled by default)', true)
     .option('--budget <number>', 'Optional token budget for assembled context')
-    .option('--profile <profile>', 'Context profile (default|planning|incident|handoff|auto)', 'default')
-    .option('--max-hops <n>', 'Maximum graph expansion hops', '2')
+    .option('--profile <profile>', 'Context profile (default|planning|incident|handoff|auto) (default: default)', 'default')
+    .option('--max-hops <n>', 'Maximum graph expansion hops (default: 2)', '2')
     .option('-v, --vault <path>', 'Vault path')
     .action(async (task, options) => {
       try {
@@ -171,12 +171,12 @@ export function registerQueryCommands(
   // === INJECT ===
   program
     .command('inject <message>')
-    .description('Inject relevant rules, decisions, and preferences for prompt context')
-    .option('-n, --max-results <n>', 'Maximum injected items')
-    .option('--scope <scope>', 'Comma-separated scope filter override')
-    .option('--enable-llm', 'Enable optional LLM fuzzy intent matching')
-    .option('--disable-llm', 'Disable optional LLM fuzzy intent matching')
-    .option('--format <format>', 'Output format (markdown|json)', 'markdown')
+    .description('Inject relevant rules, decisions, and preferences into prompt context')
+    .option('-n, --max-results <n>', 'Maximum injected items (default: config inject.maxResults, fallback 8)')
+    .option('--scope <scope>', 'Comma-separated scope filter override (default: config inject.scope, fallback global)')
+    .option('--enable-llm', 'Enable LLM fuzzy intent matching (overrides config inject.useLlm)')
+    .option('--disable-llm', 'Disable LLM fuzzy intent matching (overrides config inject.useLlm)')
+    .option('--format <format>', 'Output format (markdown|json) (default: markdown)', 'markdown')
     .option('--model <model>', 'Override LLM model when fuzzy matching is enabled')
     .option('-v, --vault <path>', 'Vault path')
     .action(async (message, options) => {
@@ -214,13 +214,16 @@ export function registerQueryCommands(
     .description('Observe session files and build observational memory')
     .option('--watch <path>', 'Watch session file or directory')
     .option('--active', 'Observe active OpenClaw sessions incrementally')
+    .option('--cron', 'Run one-shot active observation for cron hooks')
     .option('--agent <id>', 'OpenClaw agent ID (default: OPENCLAW_AGENT_ID or clawdious)')
     .option('--min-new <bytes>', 'Override minimum new-content threshold in bytes')
     .option('--sessions-dir <path>', 'Override OpenClaw sessions directory')
     .option('--dry-run', 'Show active observation candidates without compressing')
-    .option('--threshold <n>', 'Compression token threshold', '30000')
-    .option('--reflect-threshold <n>', 'Reflection token threshold', '40000')
+    .option('--threshold <n>', 'Compression token threshold (default: 30000)', '30000')
+    .option('--reflect-threshold <n>', 'Reflection token threshold (default: 40000)', '40000')
     .option('--model <model>', 'LLM model override')
+    .option('--extract-tasks', 'Extract task-like observations into backlog (enabled by default)', true)
+    .option('--no-extract-tasks', 'Disable task extraction from observations')
     .option('--compress <file>', 'One-shot compression for a conversation file')
     .option('--daemon', 'Run in detached background mode')
     .option('-v, --vault <path>', 'Vault path')
@@ -245,6 +248,7 @@ export function registerQueryCommands(
         await observeCommand({
           watch: options.watch,
           active: options.active,
+          cron: options.cron,
           agent: options.agent,
           minNew,
           sessionsDir: options.sessionsDir,
@@ -252,6 +256,7 @@ export function registerQueryCommands(
           threshold,
           reflectThreshold,
           model: options.model,
+          extractTasks: options.extractTasks,
           compress: options.compress,
           daemon: options.daemon,
           vaultPath: resolveVaultPath(options.vault)
@@ -266,7 +271,7 @@ export function registerQueryCommands(
   program
     .command('reflect')
     .description('Promote stable observations into weekly reflections')
-    .option('--days <n>', 'Observation window in days', '14')
+    .option('--days <n>', 'Observation window in days (default: 14)', '14')
     .option('--dry-run', 'Show reflection output candidates without writing')
     .option('-v, --vault <path>', 'Vault path')
     .action(async (options) => {
@@ -291,8 +296,8 @@ export function registerQueryCommands(
   program
     .command('session-recap <sessionKey>')
     .description('Generate recap from a specific OpenClaw session transcript')
-    .option('-n, --limit <n>', 'Number of messages to include', '15')
-    .option('--format <format>', 'Output format (markdown|json)', 'markdown')
+    .option('-n, --limit <n>', 'Number of messages to include (default: 15)', '15')
+    .option('--format <format>', 'Output format (markdown|json) (default: markdown)', 'markdown')
     .option('-a, --agent <id>', 'Agent ID (default: OPENCLAW_AGENT_ID or clawdious)')
     .action(async (sessionKey, options) => {
       try {