agentic-knowledge-mcp 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-knowledge-mcp",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "A Model Context Protocol server for agentic knowledge guidance with web-based documentation loading and intelligent search instructions",
   "type": "module",
   "main": "packages/cli/dist/index.js",
@@ -8,7 +8,7 @@
     "agentic-knowledge": "packages/cli/dist/index.js"
   },
   "engines": {
-    "node": ">=18.0.0",
+    "node": ">=20.0.0",
     "pnpm": ">=9.0.0"
   },
   "files": [
@@ -29,9 +29,9 @@
     "commander": "^12.0.0",
     "js-yaml": "4.1.0",
     "ora": "^8.0.1",
-    "@codemcp/knowledge": "1.4.0",
-    "@codemcp/knowledge-content-loader": "1.4.0",
-    "@codemcp/knowledge-core": "1.4.0"
+    "@codemcp/knowledge-content-loader": "1.6.0",
+    "@codemcp/knowledge-core": "1.6.0",
+    "@codemcp/knowledge": "1.6.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.34.0",

package/packages/cli/dist/commands/init.js

@@ -3,10 +3,8 @@
  */
 import { Command } from "commander";
 import chalk from "chalk";
-import { promises as fs } from "node:fs";
-import * as path from "node:path";
-import { ConfigManager, calculateLocalPath, ensureKnowledgeGitignoreSync, discoverDirectoryPatterns, safelyClearDirectory, getDirectoryInfo, } from "@codemcp/knowledge-core";
-import { GitRepoLoader, ArchiveLoader, WebSourceType, } from "@codemcp/knowledge-content-loader";
+import { ConfigManager, ensureKnowledgeGitignoreSync, discoverDirectoryPatterns, } from "@codemcp/knowledge-core";
+import { initDocset, } from "@codemcp/knowledge-content-loader";
 export const initCommand = new Command("init")
     .description("Initialize sources for a docset from configuration")
     .argument("<docset-id>", "ID of the docset to initialize")
@@ -16,216 +14,37 @@ export const initCommand = new Command("init")
     .action(async (docsetId, options) => {
     console.log(chalk.blue("🚀 Agentic Knowledge Integration Test"));
     try {
-        // Use ConfigManager for all config operations
         const configManager = new ConfigManager();
         const { config, configPath } = await configManager.loadConfig(process.cwd());
-        // Ensure .knowledge/.gitignore exists and contains docsets/ ignore rule
         ensureKnowledgeGitignoreSync(configPath);
         const docset = config.docsets.find((d) => d.id === docsetId);
         if (!docset) {
             throw new Error(`Docset '${docsetId}' not found in configuration. Available: ${config.docsets.map((d) => d.id).join(", ")}`);
         }
-        if (!docset.sources || docset.sources.length === 0) {
-            throw new Error(`Docset '${docsetId}' has no sources configured`);
-        }
         console.log(chalk.green(`✅ Found docset: ${docset.name}`));
         console.log(chalk.gray(`📝 Description: ${docset.description}`));
         console.log(chalk.gray(`🔗 Sources: ${docset.sources.length}`));
-        // Calculate the local path for this docset
-        const localPath = calculateLocalPath(docset, configPath);
-        console.log(chalk.yellow(`\n📁 Target directory: ${localPath}`));
-        // Check if already exists
-        let existsAlready = false;
-        try {
-            const stat = await fs.stat(localPath);
-            if (stat.isDirectory()) {
-                existsAlready = true;
-            }
-        }
-        catch {
-            // Directory doesn't exist, which is fine
-        }
-        if (existsAlready && !options.force) {
-            console.log(chalk.yellow("⚠️  Directory already exists. Use --force to overwrite."));
-            const files = await fs.readdir(localPath);
-            console.log(chalk.gray(`Existing files: ${files.slice(0, 5).join(", ")}${files.length > 5 ? "..." : ""}`));
+        const result = await initDocset(docsetId, docset, configPath, {
+            force: options.force,
+            onSourceProgress: (sourceResult) => {
+                const icon = sourceResult.type === "git_repo"
+                    ? "Copied"
+                    : sourceResult.type === "local_folder"
+                        ? "Created symlinks:"
+                        : "Extracted";
+                console.log(chalk.green(`    ✅ ${icon} — ${sourceResult.message}`));
+            },
+        });
+        if (result.alreadyInitialized) {
+            console.log(chalk.yellow("⚠️  Directory already exists and is initialized. Use --force to overwrite."));
             return;
         }
-        // Clear directory for force re-initialization
-        if (existsAlready && options.force) {
-            // Get info about what we're clearing (for logging)
-            const dirInfo = await getDirectoryInfo(localPath);
-            console.log(chalk.yellow("🗑️  Clearing existing directory..."));
-            console.log(chalk.gray(`    Removing: ${dirInfo.files} files, ${dirInfo.directories} dirs, ${dirInfo.symlinks} symlinks`));
-            if (dirInfo.symlinks > 0) {
-                console.log(chalk.gray("    ⚠️  Note: Symlinks will be removed, but source files are preserved"));
-            }
-            // Safely clear directory (preserves source files for symlinked folders)
-            await safelyClearDirectory(localPath);
-        }
-        // Create target directory
-        await fs.mkdir(localPath, { recursive: true });
-        let totalFiles = 0;
-        const allDiscoveredPaths = [];
-        // Process each source
-        for (const [index, source] of docset.sources.entries()) {
-            console.log(chalk.yellow(`\n🔄 Loading source ${index + 1}/${docset.sources.length}: ${source.type === "git_repo" ? source.url : source.paths?.join(", ")}`));
-            if (source.type === "git_repo") {
-                // Use GitRepoLoader for all Git operations (REQ-19)
-                const loader = new GitRepoLoader();
-                console.log(chalk.gray(`  Using GitRepoLoader for smart content filtering`));
-                const webSourceConfig = {
-                    url: source.url,
-                    type: WebSourceType.GIT_REPO,
-                    options: {
-                        branch: source.branch || "main",
-                        paths: source.paths || [],
-                    },
-                };
-                // Validate configuration
-                const validation = loader.validateConfig(webSourceConfig);
-                if (validation !== true) {
-                    throw new Error(`Invalid Git repository configuration: ${validation}`);
-                }
-                // Load content using GitRepoLoader
-                const result = await loader.load(webSourceConfig, localPath);
-                if (!result.success) {
-                    throw new Error(`Git repository loading failed: ${result.error}`);
-                }
-                // Collect discovered paths for config update
-                allDiscoveredPaths.push(...result.files);
-                totalFiles += result.files.length;
-                console.log(chalk.green(`    ✅ Copied ${result.files.length} files using smart filtering`));
-                // Create source metadata
-                const metadata = {
-                    source_url: source.url,
-                    source_type: source.type,
-                    downloaded_at: new Date().toISOString(),
-                    files_count: result.files.length,
-                    files: result.files,
-                    docset_id: docsetId,
-                    content_hash: result.contentHash,
-                };
-                await fs.writeFile(path.join(localPath, `.agentic-source-${index}.json`), JSON.stringify(metadata, null, 2));
-            }
-            else if (source.type === "local_folder") {
-                // Handle local folder initialization
-                console.log(chalk.gray(`  Creating symlinks for local folder`));
-                if (!source.paths || source.paths.length === 0) {
-                    throw new Error(`Local folder source has no paths configured`);
-                }
-                // Import symlink utilities
-                const { createSymlinks } = await import("@codemcp/knowledge-core");
-                // Note: directory is already cleared above if --force is used,
-                // so no need to call removeSymlinks here
-                const configDir = path.dirname(configPath);
-                const projectRoot = path.dirname(configDir);
-                // Verify source paths exist
-                const validatedPaths = [];
-                for (const sourcePath of source.paths) {
-                    const absolutePath = path.isAbsolute(sourcePath)
-                        ? sourcePath
-                        : path.resolve(projectRoot, sourcePath);
-                    try {
-                        const stat = await fs.stat(absolutePath);
-                        if (!stat.isDirectory()) {
-                            throw new Error(`Path is not a directory: ${sourcePath}`);
-                        }
-                        validatedPaths.push(sourcePath);
-                    }
-                    catch {
-                        throw new Error(`Local folder path does not exist: ${sourcePath}`);
-                    }
-                }
-                // Create symlinks
-                await createSymlinks(validatedPaths, localPath, projectRoot);
-                console.log(chalk.green(`    ✅ Created ${validatedPaths.length} symlink(s)`));
-                // Count files in symlinked directories for metadata
-                let fileCount = 0;
-                const files = [];
-                async function countFilesRecursive(dir) {
-                    const entries = await fs.readdir(dir, { withFileTypes: true });
-                    for (const entry of entries) {
-                        const fullPath = path.join(dir, entry.name);
-                        if (entry.isDirectory()) {
-                            await countFilesRecursive(fullPath);
-                        }
-                        else if (entry.isFile()) {
-                            fileCount++;
-                            files.push(path.relative(localPath, fullPath));
-                        }
-                    }
-                }
-                await countFilesRecursive(localPath);
-                totalFiles += fileCount;
-                // Create source metadata
-                const metadata = {
-                    source_paths: validatedPaths,
-                    source_type: source.type,
-                    initialized_at: new Date().toISOString(),
-                    files_count: fileCount,
-                    files: files,
-                    docset_id: docsetId,
-                };
-                await fs.writeFile(path.join(localPath, `.agentic-source-${index}.json`), JSON.stringify(metadata, null, 2));
-            }
-            else if (source.type === "archive") {
-                // Handle archive file initialization (zip, tar.gz, etc.)
-                const loader = new ArchiveLoader();
-                const sourceUrl = source.url || source.path || "";
-                console.log(chalk.gray(`  Using ArchiveLoader for archive extraction`));
-                const webSourceConfig = {
-                    url: sourceUrl,
-                    type: WebSourceType.ARCHIVE,
-                    options: {
-                        paths: source.paths || [],
-                    },
-                };
-                // Validate configuration
-                const validation = loader.validateConfig(webSourceConfig);
-                if (validation !== true) {
-                    throw new Error(`Invalid archive source configuration: ${validation}`);
-                }
-                // Load content using ArchiveLoader
-                const result = await loader.load(webSourceConfig, localPath);
-                if (!result.success) {
-                    throw new Error(`Archive loading failed: ${result.error}`);
-                }
-                // Collect discovered paths for config update
-                allDiscoveredPaths.push(...result.files);
-                totalFiles += result.files.length;
-                console.log(chalk.green(`    ✅ Extracted ${result.files.length} files from archive`));
-                // Create source metadata
-                const metadata = {
-                    source_url: sourceUrl,
-                    source_type: source.type,
-                    downloaded_at: new Date().toISOString(),
-                    files_count: result.files.length,
-                    files: result.files,
-                    docset_id: docsetId,
-                    content_hash: result.contentHash,
-                };
-                await fs.writeFile(path.join(localPath, `.agentic-source-${index}.json`), JSON.stringify(metadata, null, 2));
-            }
-            else {
-                console.log(chalk.red(`    ❌ Source type '${source.type}' not yet supported`));
-            }
-        }
-        // Create overall metadata
-        const overallMetadata = {
-            docset_id: docsetId,
-            docset_name: docset.name,
-            initialized_at: new Date().toISOString(),
-            total_files: totalFiles,
-            sources_count: docset.sources.length,
-        };
-        await fs.writeFile(path.join(localPath, ".agentic-metadata.json"), JSON.stringify(overallMetadata, null, 2));
         // Update configuration with discovered paths (only if --discover-paths flag used)
-        if (allDiscoveredPaths.length > 0 && options.discoverPaths) {
+        const allFiles = result.sourceResults.flatMap((r) => r.files);
+        if (allFiles.length > 0 && options.discoverPaths) {
             console.log(chalk.yellow(`\n📝 Discovering directory patterns from extracted files...`));
-            // Convert file list to directory patterns
-            const directoryPatterns = discoverDirectoryPatterns(allDiscoveredPaths);
-            console.log(chalk.gray(`    Found ${allDiscoveredPaths.length} files → ${directoryPatterns.length} patterns`));
+            const directoryPatterns = discoverDirectoryPatterns(allFiles);
+            console.log(chalk.gray(`    Found ${allFiles.length} files → ${directoryPatterns.length} patterns`));
             try {
                 await configManager.updateDocsetPaths(docsetId, directoryPatterns);
                 console.log(chalk.green(`    ✅ Updated config with discovered patterns: ${directoryPatterns.slice(0, 5).join(", ")}${directoryPatterns.length > 5 ? "..." : ""}`));
@@ -235,8 +54,8 @@ export const initCommand = new Command("init")
             }
         }
         console.log(chalk.green(`\n🎉 Successfully initialized docset '${docsetId}'`));
-        console.log(chalk.gray(`📁 Location: ${localPath}`));
-        console.log(chalk.gray(`📄 Total files: ${totalFiles}`));
+        console.log(chalk.gray(`📁 Location: ${result.localPath}`));
+        console.log(chalk.gray(`📄 Total files: ${result.totalFiles}`));
         console.log(chalk.gray(`🔗 Sources processed: ${docset.sources.length}`));
     }
     catch (error) {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-cli",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Command-line interface for agentic knowledge web content management",
   "type": "module",
   "main": "dist/exports.js",

package/packages/content-loader/dist/docset-init.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Docset initialization logic shared between CLI and MCP server.
+ */
+import { type DocsetConfig } from "@codemcp/knowledge-core";
+export interface SourceResult {
+    index: number;
+    type: string;
+    filesCount: number;
+    files: string[];
+    message: string;
+    contentHash?: string;
+}
+export interface InitDocsetResult {
+    localPath: string;
+    totalFiles: number;
+    sourceResults: SourceResult[];
+    /** True when already initialized and force was not set */
+    alreadyInitialized: boolean;
+}
+export interface InitDocsetOptions {
+    force?: boolean;
+    /** Called after each source is processed so callers can show progress */
+    onSourceProgress?: (result: SourceResult) => void;
+}
+/**
+ * Download / symlink all sources for a docset and write metadata files.
+ * Does not load config or produce console output — callers handle both.
+ */
+export declare function initDocset(docsetId: string, docset: DocsetConfig, configPath: string, options?: InitDocsetOptions): Promise<InitDocsetResult>;

package/packages/content-loader/dist/docset-init.js

@@ -0,0 +1,196 @@
+/**
+ * Docset initialization logic shared between CLI and MCP server.
+ */
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { calculateLocalPath, safelyClearDirectory, createSymlinks, } from "@codemcp/knowledge-core";
+import { GitRepoLoader } from "./content/git-repo-loader.js";
+import { ArchiveLoader } from "./content/archive-loader.js";
+import { WebSourceType } from "./types.js";
+/**
+ * Download / symlink all sources for a docset and write metadata files.
+ * Does not load config or produce console output — callers handle both.
+ */
+export async function initDocset(docsetId, docset, configPath, options = {}) {
+    const { force = false, onSourceProgress } = options;
+    if (!docset.sources || docset.sources.length === 0) {
+        throw new Error(`Docset '${docsetId}' has no sources configured`);
+    }
+    const localPath = calculateLocalPath(docset, configPath);
+    let existsAlready = false;
+    try {
+        const stat = await fs.stat(localPath);
+        if (stat.isDirectory())
+            existsAlready = true;
+    }
+    catch {
+        // not yet created
+    }
+    if (existsAlready && !force) {
+        const metadataPath = path.join(localPath, ".agentic-metadata.json");
+        if (existsSync(metadataPath)) {
+            return {
+                localPath,
+                totalFiles: 0,
+                sourceResults: [],
+                alreadyInitialized: true,
+            };
+        }
+    }
+    if (existsAlready && force) {
+        await safelyClearDirectory(localPath);
+    }
+    await fs.mkdir(localPath, { recursive: true });
+    const configDir = path.dirname(configPath);
+    const projectRoot = path.dirname(configDir);
+    let totalFiles = 0;
+    const sourceResults = [];
+    for (const [index, source] of docset.sources.entries()) {
+        let result;
+        if (source.type === "git_repo") {
+            const loader = new GitRepoLoader();
+            const webSourceConfig = {
+                url: source.url,
+                type: WebSourceType.GIT_REPO,
+                options: {
+                    branch: source.branch || "main",
+                    paths: source.paths || [],
+                },
+            };
+            const validation = loader.validateConfig(webSourceConfig);
+            if (validation !== true) {
+                throw new Error(`Invalid Git repository configuration: ${validation}`);
+            }
+            const loadResult = await loader.load(webSourceConfig, localPath);
+            if (!loadResult.success) {
+                throw new Error(`Git repository loading failed: ${loadResult.error}`);
+            }
+            result = {
+                index,
+                type: "git_repo",
+                filesCount: loadResult.files.length,
+                files: loadResult.files,
+                message: `${loadResult.files.length} files loaded from ${source.url}`,
+                contentHash: loadResult.contentHash,
+            };
+            await fs.writeFile(path.join(localPath, `.agentic-source-${index}.json`), JSON.stringify({
+                source_url: source.url,
+                source_type: source.type,
+                downloaded_at: new Date().toISOString(),
+                files_count: loadResult.files.length,
+                files: loadResult.files,
+                docset_id: docsetId,
+                content_hash: loadResult.contentHash,
+            }, null, 2));
+        }
+        else if (source.type === "local_folder") {
+            if (!source.paths || source.paths.length === 0) {
+                throw new Error(`Local folder source ${index + 1} has no paths configured`);
+            }
+            const validatedPaths = [];
+            for (const sourcePath of source.paths) {
+                const absolutePath = path.isAbsolute(sourcePath)
+                    ? sourcePath
+                    : path.resolve(projectRoot, sourcePath);
+                try {
+                    const stat = await fs.stat(absolutePath);
+                    if (!stat.isDirectory()) {
+                        throw new Error(`Path is not a directory: ${sourcePath}`);
+                    }
+                    validatedPaths.push(sourcePath);
+                }
+                catch {
+                    throw new Error(`Local folder path does not exist: ${sourcePath}`);
+                }
+            }
+            await createSymlinks(validatedPaths, localPath, projectRoot);
+            let fileCount = 0;
+            const files = [];
+            async function countFiles(dir) {
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        await countFiles(fullPath);
+                    }
+                    else if (entry.isFile()) {
+                        fileCount++;
+                        files.push(path.relative(localPath, fullPath));
+                    }
+                }
+            }
+            await countFiles(localPath);
+            result = {
+                index,
+                type: "local_folder",
+                filesCount: fileCount,
+                files,
+                message: `${validatedPaths.length} symlink(s) created, ${fileCount} files accessible`,
+            };
+            await fs.writeFile(path.join(localPath, `.agentic-source-${index}.json`), JSON.stringify({
+                source_paths: validatedPaths,
+                source_type: source.type,
+                initialized_at: new Date().toISOString(),
+                files_count: fileCount,
+                files,
+                docset_id: docsetId,
+            }, null, 2));
+        }
+        else if (source.type === "archive") {
+            const loader = new ArchiveLoader();
+            const sourceUrl = source.url || source.path || "";
+            const webSourceConfig = {
+                url: sourceUrl,
+                type: WebSourceType.ARCHIVE,
+                options: { paths: source.paths || [] },
+            };
+            const validation = loader.validateConfig(webSourceConfig);
+            if (validation !== true) {
+                throw new Error(`Invalid archive source configuration: ${validation}`);
+            }
+            const loadResult = await loader.load(webSourceConfig, localPath);
+            if (!loadResult.success) {
+                throw new Error(`Archive loading failed: ${loadResult.error}`);
+            }
+            result = {
+                index,
+                type: "archive",
+                filesCount: loadResult.files.length,
+                files: loadResult.files,
+                message: `${loadResult.files.length} files extracted from ${sourceUrl}`,
+                contentHash: loadResult.contentHash,
+            };
+            await fs.writeFile(path.join(localPath, `.agentic-source-${index}.json`), JSON.stringify({
+                source_url: sourceUrl,
+                source_type: source.type,
+                downloaded_at: new Date().toISOString(),
+                files_count: loadResult.files.length,
+                files: loadResult.files,
+                docset_id: docsetId,
+                content_hash: loadResult.contentHash,
+            }, null, 2));
+        }
+        else {
+            result = {
+                index,
+                type: source.type,
+                filesCount: 0,
+                files: [],
+                message: `source type '${source.type}' not supported, skipped`,
+            };
+        }
+        totalFiles += result.filesCount;
+        sourceResults.push(result);
+        onSourceProgress?.(result);
+    }
+    // Write the overall metadata file — this is what search_docs checks for
+    await fs.writeFile(path.join(localPath, ".agentic-metadata.json"), JSON.stringify({
+        docset_id: docsetId,
+        docset_name: docset.name,
+        initialized_at: new Date().toISOString(),
+        total_files: totalFiles,
+        sources_count: docset.sources.length,
+    }, null, 2));
+    return { localPath, totalFiles, sourceResults, alreadyInitialized: false };
+}

package/packages/content-loader/dist/index.d.ts

@@ -3,3 +3,5 @@
  */
 export * from "./types.js";
 export * from "./content/index.js";
+export { initDocset } from "./docset-init.js";
+export type { InitDocsetOptions, InitDocsetResult, SourceResult, } from "./docset-init.js";

package/packages/content-loader/dist/index.js

@@ -3,3 +3,4 @@
  */
 export * from "./types.js";
 export * from "./content/index.js";
+export { initDocset } from "./docset-init.js";

package/packages/content-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-content-loader",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Web content loading and metadata management for agentic knowledge system",
   "type": "module",
   "main": "dist/index.js",
@@ -29,6 +29,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@codemcp/knowledge-core": "workspace:*",
     "adm-zip": "0.5.16",
     "simple-git": "^3.22.0",
     "tar": "7.5.9"

package/packages/core/dist/index.d.ts

@@ -13,3 +13,4 @@ export { createSymlinks, removeSymlinks } from "./paths/symlinks.js";
 export { discoverDirectoryPatterns, discoverMinimalPatterns, } from "./paths/discovery.js";
 export { safelyClearDirectory, containsSymlinks, getDirectoryInfo, } from "./paths/cleanup.js";
 export { processTemplate, getEffectiveTemplate, validateTemplate, extractVariables, createTemplateContext, createStructuredResponse, } from "./templates/processor.js";
+export { buildFileIndex, searchDocset, formatSearchResult, type DocsetIndex, } from "./search/searcher.js";

package/packages/core/dist/index.js

@@ -20,3 +20,5 @@ export { discoverDirectoryPatterns, discoverMinimalPatterns, } from "./paths/dis
 export { safelyClearDirectory, containsSymlinks, getDirectoryInfo, } from "./paths/cleanup.js";
 // Export template processing
 export { processTemplate, getEffectiveTemplate, validateTemplate, extractVariables, createTemplateContext, createStructuredResponse, } from "./templates/processor.js";
+// Export search functionality
+export { buildFileIndex, searchDocset, formatSearchResult, } from "./search/searcher.js";

package/packages/core/dist/paths/symlinks.js

@@ -12,32 +12,31 @@ import { KnowledgeError, ErrorType } from "../types.js";
  */
 export async function createSymlinks(sourcePaths, targetDir, projectRoot) {
     try {
-        // Ensure target directory exists
         await fs.mkdir(targetDir, { recursive: true });
         for (const sourcePath of sourcePaths) {
-            // Resolve source path to absolute
             const absoluteSourcePath = isAbsolute(sourcePath)
                 ? sourcePath
                 : resolve(projectRoot, sourcePath);
-            // Check if source exists
             try {
                 await fs.access(absoluteSourcePath);
             }
             catch {
                 throw new Error(`Source path does not exist: ${absoluteSourcePath}`);
             }
-            // Determine target symlink path
-            const sourceName = sourcePath.split("/").pop() || "unknown";
-            const symlinkPath = join(targetDir, sourceName);
-            // Remove existing symlink if it exists
-            try {
-                await fs.unlink(symlinkPath);
-            }
-            catch {
-                // Ignore if doesn't exist
+            // Link each entry inside the source directory directly into targetDir
+            // so that the docset root is flat — consistent with git_repo / archive.
+            const entries = await fs.readdir(absoluteSourcePath);
+            for (const entry of entries) {
+                const symlinkPath = join(targetDir, entry);
+                const entryAbsPath = join(absoluteSourcePath, entry);
+                try {
+                    await fs.unlink(symlinkPath);
+                }
+                catch {
+                    // ignore — entry doesn't exist yet
+                }
+                await fs.symlink(entryAbsPath, symlinkPath);
             }
-            // Create symlink
-            await fs.symlink(absoluteSourcePath, symlinkPath);
         }
     }
     catch (error) {
@@ -55,7 +54,6 @@ export async function validateSymlinks(targetDir) {
         for (const entry of entries) {
             if (entry.isSymbolicLink()) {
                 const symlinkPath = join(targetDir, entry.name);
-                // Check if symlink target exists
                 try {
                     await fs.access(symlinkPath);
                 }