byterover-cli 0.4.0 → 1.0.0

package/dist/infra/cipher/tools/implementations/bash-exec-tool.js

@@ -43,23 +43,24 @@ const BashExecInputSchema = z
  *
  * Executes shell commands with security validation and approval for dangerous commands.
  * Supports both foreground (wait for completion) and background (return immediately) execution.
+ * When a metadata callback is provided, streams output updates in real-time.
  *
  * @param processService - Process service for command execution
  * @returns bash_exec tool instance
  */
 export function createBashExecTool(processService) {
     return {
-        description: `Execute a shell command and return its output.
-
-If there is a memory about suggested commands, read that first.
-
-**IMPORTANT:** Do not use this tool to start any process that is not intended to terminate quickly, or requires user interaction.
-
-Examples of inappropriate use:
-- Long-running processes (e.g. servers) that are not intended to terminate quickly
-- Processes that require user interaction`,
-        async execute(input, _context) {
+        description: `Execute a shell command and return its output.`,
+        async execute(input, context) {
             const { command, cwd, description, runInBackground, timeout } = input;
+            // Stream initial status via metadata callback if available
+            if (context?.metadata) {
+                context.metadata({
+                    description: description ?? `Executing: ${command.slice(0, 50)}${command.length > 50 ? '...' : ''}`,
+                    output: '',
+                    progress: 0,
+                });
+            }
             // Execute command via process service
             const result = await processService.executeCommand(command, {
                 cwd,
@@ -69,6 +70,14 @@ Examples of inappropriate use:
             });
             // Return based on execution mode
             if ('stdout' in result) {
+                // Stream final output via metadata callback if available
+                if (context?.metadata) {
+                    context.metadata({
+                        description: description ?? 'Command completed',
+                        output: result.stdout + (result.stderr ? `\n[stderr]\n${result.stderr}` : ''),
+                        progress: 100,
+                    });
+                }
                 // Foreground execution result
                 return {
                     duration: result.duration,
@@ -77,6 +86,14 @@ Examples of inappropriate use:
                     stdout: result.stdout,
                 };
             }
+            // Stream background process info via metadata callback if available
+            if (context?.metadata) {
+                context.metadata({
+                    description: `Background process started: ${result.processId}`,
+                    output: `Process started with PID ${result.pid}`,
+                    progress: 100,
+                });
+            }
             // Background execution handle
             return {
                 command: result.command,

package/dist/infra/cipher/tools/implementations/bash-output-tool.js

@@ -22,11 +22,7 @@ const BashOutputInputSchema = z
  */
 export function createBashOutputTool(processService) {
     return {
-        description: `Retrieve output from a background process started by bash_exec.
-
-Returns new output since last read (incremental). Reading output clears the buffer, so output is returned only once. Shows process status (running/completed/failed) and includes exit code and duration when completed.
-
-**IMPORTANT:** Output is truncated if it exceeds buffer limit (default 1MB). Process is automatically cleaned up 1 hour after completion.`,
+        description: `Retrieve output from a background process started by bash_exec.`,
         async execute(input, _context) {
             const { processId } = input;
             // Get output from process service

package/dist/infra/cipher/tools/implementations/batch-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { ToolProviderGetter } from '../tool-provider-getter.js';
+/**
+ * Create batch tool.
+ *
+ * Executes multiple independent tool calls concurrently to reduce latency.
+ * Best used for gathering context (reads, searches, listings).
+ *
+ * @param getToolProvider - Lazy getter for tool provider (avoids circular dependency)
+ * @returns batch tool instance
+ */
+export declare function createBatchTool(getToolProvider: ToolProviderGetter): Tool;

package/dist/infra/cipher/tools/implementations/batch-tool.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Tools that are not allowed in batch execution.
+ * - batch: No nesting of batch calls
+ * - edit_file: Sequential edits for proper conflict handling
+ * - write_todos: Lightweight, call directly
+ */
+const DISALLOWED_TOOLS = new Set(['batch', 'edit_file', 'write_todos']);
+/**
+ * Maximum number of tool calls allowed in a single batch.
+ */
+const MAX_BATCH_SIZE = 10;
+/**
+ * Input schema for batch tool.
+ */
+const BatchInputSchema = z
+    .object({
+    /**
+     * Array of tool calls to execute in parallel.
+     */
+    toolCalls: z
+        .array(z.object({
+        /**
+         * Parameters for the tool.
+         */
+        parameters: z.record(z.unknown()).describe('Parameters for the tool'),
+        /**
+         * The name of the tool to execute.
+         */
+        tool: z.string().describe('The name of the tool to execute'),
+    }))
+        .min(1, 'Provide at least one tool call')
+        .describe('Array of tool calls to execute in parallel'),
+})
+    .strict();
+/**
+ * Create batch tool.
+ *
+ * Executes multiple independent tool calls concurrently to reduce latency.
+ * Best used for gathering context (reads, searches, listings).
+ *
+ * @param getToolProvider - Lazy getter for tool provider (avoids circular dependency)
+ * @returns batch tool instance
+ */
+export function createBatchTool(getToolProvider) {
+    return {
+        description: 'Execute multiple independent tool calls concurrently.',
+        async execute(input, context) {
+            const { toolCalls } = input;
+            const toolProvider = getToolProvider();
+            // Limit to MAX_BATCH_SIZE
+            const activeCalls = toolCalls.slice(0, MAX_BATCH_SIZE);
+            const discardedCalls = toolCalls.slice(MAX_BATCH_SIZE);
+            /**
+             * Execute a single tool call and return the result.
+             */
+            const executeCall = async (call) => {
+                const startTime = Date.now();
+                // Check if tool is disallowed in batch
+                if (DISALLOWED_TOOLS.has(call.tool)) {
+                    return {
+                        durationMs: Date.now() - startTime,
+                        error: `Tool '${call.tool}' is not allowed in batch. Disallowed tools: ${[...DISALLOWED_TOOLS].join(', ')}`,
+                        success: false,
+                        tool: call.tool,
+                    };
+                }
+                // Check if tool exists
+                if (!toolProvider.hasTool(call.tool)) {
+                    const availableTools = toolProvider.getToolNames().filter((name) => !DISALLOWED_TOOLS.has(name));
+                    return {
+                        durationMs: Date.now() - startTime,
+                        error: `Tool '${call.tool}' not found. Available tools: ${availableTools.join(', ')}`,
+                        success: false,
+                        tool: call.tool,
+                    };
+                }
+                try {
+                    const result = await toolProvider.executeTool(call.tool, call.parameters, context?.sessionId, context);
+                    return {
+                        durationMs: Date.now() - startTime,
+                        result,
+                        success: true,
+                        tool: call.tool,
+                    };
+                }
+                catch (error) {
+                    return {
+                        durationMs: Date.now() - startTime,
+                        error: error instanceof Error ? error.message : String(error),
+                        success: false,
+                        tool: call.tool,
+                    };
+                }
+            };
+            // Execute all calls in parallel
+            const results = await Promise.all(activeCalls.map((call) => executeCall(call)));
+            // Add discarded calls as errors
+            for (const call of discardedCalls) {
+                results.push({
+                    durationMs: 0,
+                    error: `Maximum of ${MAX_BATCH_SIZE} tools allowed in batch`,
+                    success: false,
+                    tool: call.tool,
+                });
+            }
+            const successful = results.filter((r) => r.success).length;
+            const failed = results.length - successful;
+            // Stream progress update
+            if (context?.metadata) {
+                context.metadata({
+                    description: 'Batch execution complete',
+                    output: `${successful}/${results.length} tools executed successfully`,
+                    progress: 100,
+                });
+            }
+            // Build output message
+            const outputMessage = failed > 0
+                ? `Executed ${successful}/${results.length} tools successfully. ${failed} failed.`
+                : `All ${successful} tools executed successfully.\n\nKeep using the batch tool for optimal performance!`;
+            return {
+                metadata: {
+                    details: results.map((r) => ({ success: r.success, tool: r.tool })),
+                    failed,
+                    successful,
+                    tools: toolCalls.map((c) => c.tool),
+                    totalCalls: results.length,
+                },
+                results: results.map((r) => ({
+                    durationMs: r.durationMs,
+                    success: r.success,
+                    tool: r.tool,
+                    ...(r.success ? { result: r.result } : { error: r.error }),
+                })),
+                summary: outputMessage,
+            };
+        },
+        id: ToolName.BATCH,
+        inputSchema: BatchInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/curate-tool.js

@@ -1,9 +1,20 @@
+import * as fs from 'node:fs/promises';
 import { join } from 'node:path';
 import { z } from 'zod';
+import { DEFAULT_CONTEXT_TREE_DOMAINS } from '../../../../config/context-tree-domains.js';
 import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
 import { DirectoryManager } from '../../../../core/domain/knowledge/directory-manager.js';
 import { MarkdownWriter } from '../../../../core/domain/knowledge/markdown-writer.js';
-import { sanitizeFolderName } from '../../../../utils/file-helpers.js';
+import { toSnakeCase } from '../../../../utils/file-helpers.js';
+/**
+ * Predefined domain names from configuration.
+ */
+const PREDEFINED_DOMAIN_NAMES = DEFAULT_CONTEXT_TREE_DOMAINS.map((domain) => domain.name);
+/**
+ * Maximum number of custom domains allowed beyond predefined domains.
+ * This prevents excessive domain proliferation which degrades query quality.
+ */
+const MAX_CUSTOM_DOMAINS = 3;
 /**
  * Operation types for curating knowledge topics.
  * Inspired by ACE Curator patterns.
@@ -25,8 +36,10 @@ const ContentSchema = z.object({
 const OperationSchema = z.object({
     content: ContentSchema.optional().describe('Content for ADD/UPDATE operations'),
     mergeTarget: z.string().optional().describe('Target path for MERGE operation'),
+    mergeTargetTitle: z.string().optional().describe('Title of the target file for MERGE operation'),
     path: z.string().describe('Path: domain/topic or domain/topic/subtopic'),
     reason: z.string().describe('Reasoning for this operation'),
+    title: z.string().optional().describe('Title for the context file (saved as {title}.md in snake_case). Required for ADD/UPDATE/MERGE, optional for DELETE'),
     type: OperationType.describe('Operation type: ADD, UPDATE, MERGE, or DELETE'),
 });
 /**
@@ -50,26 +63,79 @@ function parsePath(path) {
         topic: parts[1],
     };
 }
+/**
+ * Get existing domain names from the context tree.
+ * Returns domain folder names that exist in the context tree.
+ */
+async function getExistingDomains(basePath) {
+    try {
+        const entries = await fs.readdir(basePath, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch {
+        // Directory doesn't exist yet
+        return [];
+    }
+}
+/**
+ * Check if a domain is valid (either predefined or existing in context tree).
+ * Also enforces the maximum custom domains limit.
+ */
+async function validateDomain(basePath, domainName) {
+    const normalizedDomain = toSnakeCase(domainName);
+    const existingDomains = await getExistingDomains(basePath);
+    // Check if it's a predefined domain - always allowed
+    if (PREDEFINED_DOMAIN_NAMES.includes(normalizedDomain)) {
+        return { allowed: true, existingDomains };
+    }
+    // Check if it already exists in context tree - always allowed
+    if (existingDomains.includes(normalizedDomain)) {
+        return { allowed: true, existingDomains };
+    }
+    // Count how many custom domains already exist
+    const customDomains = existingDomains.filter((domain) => !PREDEFINED_DOMAIN_NAMES.includes(domain));
+    // Check if we've exceeded the custom domain limit
+    if (customDomains.length >= MAX_CUSTOM_DOMAINS) {
+        return {
+            allowed: false,
+            existingDomains,
+            reason: `Cannot create new domain "${normalizedDomain}". Maximum of ${MAX_CUSTOM_DOMAINS} custom domains allowed. ` +
+                `Existing custom domains: ${customDomains.join(', ')}. ` +
+                `Please use one of the predefined domains (${PREDEFINED_DOMAIN_NAMES.join(', ')}) or existing domains.`,
+        };
+    }
+    // New custom domain within limit - allowed
+    return { allowed: true, existingDomains };
+}
 /**
  * Build the full filesystem path from base path and knowledge path.
+ * Returns the folder path (not including filename).
  */
 function buildFullPath(basePath, knowledgePath) {
     const parsed = parsePath(knowledgePath);
     if (!parsed) {
         throw new Error(`Invalid path format: ${knowledgePath}`);
     }
-    const domainPath = join(basePath, sanitizeFolderName(parsed.domain));
-    const topicPath = join(domainPath, sanitizeFolderName(parsed.topic));
+    const domainPath = join(basePath, toSnakeCase(parsed.domain));
+    const topicPath = join(domainPath, toSnakeCase(parsed.topic));
     if (parsed.subtopic) {
-        return join(topicPath, sanitizeFolderName(parsed.subtopic));
+        return join(topicPath, toSnakeCase(parsed.subtopic));
     }
     return topicPath;
 }
 /**
- * Execute ADD operation - create new domain/topic/subtopic with context.md
+ * Execute ADD operation - create new domain/topic/subtopic with {title}.md
  */
 async function executeAdd(basePath, operation) {
-    const { content, path, reason } = operation;
+    const { content, path, reason, title } = operation;
+    if (!title) {
+        return {
+            message: 'ADD operation requires a title',
+            path,
+            status: 'failed',
+            type: 'ADD',
+        };
+    }
     if (!content) {
         return {
             message: 'ADD operation requires content',
@@ -88,30 +154,33 @@ async function executeAdd(basePath, operation) {
                 type: 'ADD',
             };
         }
-        // Ensure base structure exists
-        await DirectoryManager.ensureKnowledgeStructure(basePath);
-        // Create domain folder
-        const domainPath = join(basePath, sanitizeFolderName(parsed.domain));
-        await DirectoryManager.createOrUpdateDomain(domainPath);
-        // Create topic folder
-        const topicPath = join(domainPath, sanitizeFolderName(parsed.topic));
-        await DirectoryManager.createOrUpdateTopic(topicPath);
-        // Determine final path (topic or subtopic)
-        let finalPath = topicPath;
-        if (parsed.subtopic) {
-            finalPath = join(topicPath, sanitizeFolderName(parsed.subtopic));
-            await DirectoryManager.createOrUpdateTopic(finalPath);
+        // Validate domain before creating
+        const domainValidation = await validateDomain(basePath, parsed.domain);
+        if (!domainValidation.allowed) {
+            return {
+                message: domainValidation.reason,
+                path,
+                status: 'failed',
+                type: 'ADD',
+            };
         }
-        // Generate and write context.md
+        // Build the final folder path (topic or subtopic)
+        const domainPath = join(basePath, toSnakeCase(parsed.domain));
+        const topicPath = join(domainPath, toSnakeCase(parsed.topic));
+        const finalPath = parsed.subtopic ? join(topicPath, toSnakeCase(parsed.subtopic)) : topicPath;
+        // Generate and write {title}.md (snake_case filename)
+        // Note: writeFileAtomic creates parent directories as needed, avoiding empty folder creation
         const contextContent = MarkdownWriter.generateContext({
-            name: parsed.subtopic || parsed.topic,
+            name: title,
             relations: content.relations,
             snippets: content.snippets || [],
         });
-        const contextPath = join(finalPath, 'context.md');
+        const filename = `${toSnakeCase(title)}.md`;
+        const contextPath = join(finalPath, filename);
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
         return {
-            message: `Created ${path} with ${content.snippets?.length || 0} snippets. Reason: ${reason}`,
+            filePath: contextPath,
+            message: `Created ${path}/${filename} with ${content.snippets?.length || 0} snippets. Reason: ${reason}`,
             path,
             status: 'success',
             type: 'ADD',
@@ -127,10 +196,18 @@ async function executeAdd(basePath, operation) {
     }
 }
 /**
- * Execute UPDATE operation - modify existing context.md
+ * Execute UPDATE operation - modify existing {title}.md
  */
 async function executeUpdate(basePath, operation) {
-    const { content, path, reason } = operation;
+    const { content, path, reason, title } = operation;
+    if (!title) {
+        return {
+            message: 'UPDATE operation requires a title',
+            path,
+            status: 'failed',
+            type: 'UPDATE',
+        };
+    }
     if (!content) {
         return {
             message: 'UPDATE operation requires content',
@@ -141,27 +218,28 @@ async function executeUpdate(basePath, operation) {
     }
     try {
         const fullPath = buildFullPath(basePath, path);
-        const contextPath = join(fullPath, 'context.md');
-        // Check if topic exists
+        const filename = `${toSnakeCase(title)}.md`;
+        const contextPath = join(fullPath, filename);
+        // Check if the specific titled file exists
         const exists = await DirectoryManager.fileExists(contextPath);
         if (!exists) {
             return {
-                message: `Topic does not exist: ${path}`,
+                message: `File does not exist: ${path}/${filename}`,
                 path,
                 status: 'failed',
                 type: 'UPDATE',
             };
         }
-        // Generate and write updated context.md (full replacement)
-        const parsed = parsePath(path);
+        // Generate and write updated content (full replacement)
         const contextContent = MarkdownWriter.generateContext({
-            name: parsed?.subtopic || parsed?.topic || path,
+            name: title,
             relations: content.relations,
             snippets: content.snippets || [],
         });
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
         return {
-            message: `Updated ${path}. Reason: ${reason}`,
+            filePath: contextPath,
+            message: `Updated ${path}/${filename}. Reason: ${reason}`,
             path,
             status: 'success',
             type: 'UPDATE',
@@ -177,10 +255,18 @@ async function executeUpdate(basePath, operation) {
     }
 }
 /**
- * Execute MERGE operation - combine source into target, delete source
+ * Execute MERGE operation - combine source file into target file, delete source file
  */
 async function executeMerge(basePath, operation) {
-    const { mergeTarget, path, reason } = operation;
+    const { mergeTarget, mergeTargetTitle, path, reason, title } = operation;
+    if (!title) {
+        return {
+            message: 'MERGE operation requires a title (source file)',
+            path,
+            status: 'failed',
+            type: 'MERGE',
+        };
+    }
     if (!mergeTarget) {
         return {
             message: 'MERGE operation requires mergeTarget',
@@ -189,17 +275,27 @@ async function executeMerge(basePath, operation) {
             type: 'MERGE',
         };
     }
+    if (!mergeTargetTitle) {
+        return {
+            message: 'MERGE operation requires mergeTargetTitle',
+            path,
+            status: 'failed',
+            type: 'MERGE',
+        };
+    }
     try {
-        const sourcePath = buildFullPath(basePath, path);
-        const targetPath = buildFullPath(basePath, mergeTarget);
-        const sourceContextPath = join(sourcePath, 'context.md');
-        const targetContextPath = join(targetPath, 'context.md');
-        // Check if both exist
+        const sourceFolderPath = buildFullPath(basePath, path);
+        const targetFolderPath = buildFullPath(basePath, mergeTarget);
+        const sourceFilename = `${toSnakeCase(title)}.md`;
+        const targetFilename = `${toSnakeCase(mergeTargetTitle)}.md`;
+        const sourceContextPath = join(sourceFolderPath, sourceFilename);
+        const targetContextPath = join(targetFolderPath, targetFilename);
+        // Check if both files exist
         const sourceExists = await DirectoryManager.fileExists(sourceContextPath);
         const targetExists = await DirectoryManager.fileExists(targetContextPath);
         if (!sourceExists) {
             return {
-                message: `Source topic does not exist: ${path}`,
+                message: `Source file does not exist: ${path}/${sourceFilename}`,
                 path,
                 status: 'failed',
                 type: 'MERGE',
@@ -207,22 +303,23 @@ async function executeMerge(basePath, operation) {
         }
         if (!targetExists) {
             return {
-                message: `Target topic does not exist: ${mergeTarget}`,
+                message: `Target file does not exist: ${mergeTarget}/${targetFilename}`,
                 path,
                 status: 'failed',
                 type: 'MERGE',
             };
         }
-        // Read both contexts
+        // Read both files
         const sourceContent = await DirectoryManager.readFile(sourceContextPath);
         const targetContent = await DirectoryManager.readFile(targetContextPath);
-        // Merge the contexts using MarkdownWriter
+        // Merge the contents using MarkdownWriter
         const mergedContent = MarkdownWriter.mergeContexts(sourceContent, targetContent);
         await DirectoryManager.writeFileAtomic(targetContextPath, mergedContent);
-        // Delete source folder
-        await DirectoryManager.deleteTopicRecursive(sourcePath);
+        // Delete source file (not the entire folder, just the file)
+        await DirectoryManager.deleteFile(sourceContextPath);
         return {
-            message: `Merged ${path} into ${mergeTarget}. Reason: ${reason}`,
+            filePath: targetContextPath,
+            message: `Merged ${path}/${sourceFilename} into ${mergeTarget}/${targetFilename}. Reason: ${reason}`,
             path,
             status: 'success',
             type: 'MERGE',
@@ -238,27 +335,47 @@ async function executeMerge(basePath, operation) {
     }
 }
 /**
- * Execute DELETE operation - remove topic/subtopic folder recursively
+ * Execute DELETE operation - remove specific file or entire folder
+ * If title is provided, deletes specific file; if omitted, deletes entire folder
  */
 async function executeDelete(basePath, operation) {
-    const { path, reason } = operation;
+    const { path, reason, title } = operation;
     try {
         const fullPath = buildFullPath(basePath, path);
-        const contextPath = join(fullPath, 'context.md');
-        // Check if topic exists
-        const exists = await DirectoryManager.fileExists(contextPath);
+        if (title) {
+            // Delete specific file
+            const filename = `${toSnakeCase(title)}.md`;
+            const filePath = join(fullPath, filename);
+            const exists = await DirectoryManager.fileExists(filePath);
+            if (!exists) {
+                return {
+                    message: `File does not exist: ${path}/${filename}`,
+                    path,
+                    status: 'failed',
+                    type: 'DELETE',
+                };
+            }
+            await DirectoryManager.deleteFile(filePath);
+            return {
+                message: `Deleted ${path}/${filename}. Reason: ${reason}`,
+                path,
+                status: 'success',
+                type: 'DELETE',
+            };
+        }
+        // Delete entire folder (when no title provided)
+        const exists = await DirectoryManager.folderExists(fullPath);
         if (!exists) {
             return {
-                message: `Topic does not exist: ${path}`,
+                message: `Folder does not exist: ${path}`,
                 path,
                 status: 'failed',
                 type: 'DELETE',
             };
         }
-        // Delete folder recursively
         await DirectoryManager.deleteTopicRecursive(fullPath);
         return {
-            message: `Deleted ${path}. Reason: ${reason}`,
+            message: `Deleted folder ${path}. Reason: ${reason}`,
             path,
             status: 'success',
             type: 'DELETE',
@@ -345,25 +462,35 @@ export function createCurateTool() {
         description: `Curate knowledge topics with atomic operations. This tool manages the knowledge structure using four operation types:
 
 **Operations:**
-1. **ADD** - Create new domain/topic/subtopic with context.md
-   - Requires: path, content (snippets and/or relations), reason
-   - Example: { type: "ADD", path: "code_style/error-handling", content: { snippets: ["..."], relations: ["logging/basics"] }, reason: "New pattern identified" }
+1. **ADD** - Create new titled context file in domain/topic/subtopic
+   - Requires: path, title, content (snippets and/or relations), reason
+   - Example: { type: "ADD", path: "code_style/error_handling", title: "Best Practices", content: { snippets: ["..."], relations: ["logging/basics"] }, reason: "New pattern" }
+   - Creates: code_style/error_handling/best_practices.md
+
+2. **UPDATE** - Modify existing titled context file (full replacement)
+   - Requires: path, title, content, reason
+   - Example: { type: "UPDATE", path: "code_style/error_handling", title: "Best Practices", content: { snippets: ["Updated"] }, reason: "Improved" }
 
-2. **UPDATE** - Modify existing context.md (full replacement)
-   - Requires: path, content, reason
-   - Example: { type: "UPDATE", path: "code_style/error-handling", content: { snippets: ["Updated content"] }, reason: "Improved guidance" }
+3. **MERGE** - Combine source file into target file, delete source
+   - Requires: path (source), title (source file), mergeTarget (destination path), mergeTargetTitle (destination file), reason
+   - Example: { type: "MERGE", path: "code_style/old_topic", title: "Old Guide", mergeTarget: "code_style/new_topic", mergeTargetTitle: "New Guide", reason: "Consolidating" }
 
-3. **MERGE** - Combine source topic into target, delete source
-   - Requires: path (source), mergeTarget (destination), reason
-   - Example: { type: "MERGE", path: "code_style/old-topic", mergeTarget: "code_style/new-topic", reason: "Consolidating duplicates" }
+4. **DELETE** - Remove specific file or entire folder
+   - Requires: path, title (optional), reason
+   - With title: deletes specific file; without title: deletes entire folder
+   - Example (file): { type: "DELETE", path: "code_style/deprecated", title: "Old Guide", reason: "No longer relevant" }
+   - Example (folder): { type: "DELETE", path: "code_style/deprecated", title: "", reason: "Removing topic" }
 
-4. **DELETE** - Remove topic/subtopic folder recursively
-   - Requires: path, reason
-   - Example: { type: "DELETE", path: "code_style/deprecated-topic", reason: "No longer relevant" }
+**Path format:** domain/topic or domain/topic/subtopic (uses snake_case automatically)
+**File naming:** Titles are converted to snake_case (e.g., "Best Practices" -> "best_practices.md")
 
-**Path format:** domain/topic or domain/topic/subtopic
+**Domain constraints:**
+- Predefined domains: code_style, design, structure, compliance, testing, bug_fixes
+- Up to 3 additional custom domains are allowed
+- Always prefer predefined domains when possible
+- Creating new domains beyond the limit will fail
 
-**Output:** Returns applied operations with status (success/failed) and a summary of counts.`,
+**Output:** Returns applied operations with status (success/failed), filePath (for created/modified files), and a summary of counts.`,
         execute: executeCurate,
         id: ToolName.CURATE,
         inputSchema: CurateInputSchema,

package/dist/infra/cipher/tools/implementations/list-directory-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { IFileSystem } from '../../../../core/interfaces/cipher/i-file-system.js';
+/**
+ * Creates the list directory tool.
+ *
+ * Lists files and directories in a tree structure.
+ * Automatically ignores common build artifacts and caches.
+ *
+ * @param fileSystemService - File system service dependency
+ * @returns Configured list directory tool
+ */
+export declare function createListDirectoryTool(fileSystemService: IFileSystem): Tool;