@j0hanz/filesystem-mcp 1.7.1 → 1.7.3

package/dist/lib/file-operations/search-content.js

@@ -291,6 +291,25 @@ async function scanFileResolved(resolvedPath, requestedPath, matcher, options, s
         await handle.close();
     }
 }
+function buildScanFileOptions(opts) {
+    return {
+        maxFileSize: opts.maxFileSize,
+        skipBinary: opts.skipBinary,
+        contextLines: opts.contextLines,
+    };
+}
+function applyScanOutcome(summary, outcome) {
+    if (outcome.matched)
+        summary.filesMatched++;
+    if (outcome.skippedBinary)
+        summary.skippedBinary++;
+    if (outcome.skippedTooLarge)
+        summary.skippedTooLarge++;
+}
+function markTruncated(summary, reason) {
+    summary.truncated = true;
+    summary.stoppedReason = reason;
+}
 function createScanSummary() {
     return {
         filesScanned: 0,
@@ -474,32 +493,21 @@ function getPool() {
 async function executeSequential(files, pattern, opts, signal, summary) {
     const matches = [];
     const matcher = buildMatcher(pattern, opts);
-    const scanOpts = {
-        maxFileSize: opts.maxFileSize,
-        skipBinary: opts.skipBinary,
-        contextLines: opts.contextLines,
-    };
+    const scanOpts = buildScanFileOptions(opts);
     for await (const file of files) {
         if (signal.aborted) {
-            summary.truncated = true;
-            summary.stoppedReason = 'timeout';
+            markTruncated(summary, 'timeout');
             break;
         }
         if (matches.length >= opts.maxResults) {
-            summary.truncated = true;
-            summary.stoppedReason = 'maxResults';
+            markTruncated(summary, 'maxResults');
             break;
         }
         try {
             assertAllowedFileAccess(file.requestedPath, file.resolvedPath);
             const remaining = opts.maxResults - matches.length;
             const result = await scanFileResolved(file.resolvedPath, file.requestedPath, matcher, scanOpts, signal, remaining);
-            if (result.matched)
-                summary.filesMatched++;
-            if (result.skippedBinary)
-                summary.skippedBinary++;
-            if (result.skippedTooLarge)
-                summary.skippedTooLarge++;
+            applyScanOutcome(summary, result);
             matches.push(...result.matches);
         }
         catch {
@@ -542,12 +550,7 @@ function processScanResult(winner, summary, matches, maxResults) {
     }
     if (winner.result) {
         const res = winner.result;
-        if (res.matched)
-            summary.filesMatched++;
-        if (res.skippedBinary)
-            summary.skippedBinary++;
-        if (res.skippedTooLarge)
-            summary.skippedTooLarge++;
+        applyScanOutcome(summary, res);
         const remaining = maxResults - matches.length;
         if (remaining > 0 && res.matches.length > 0) {
             const take = Math.min(remaining, res.matches.length);
@@ -582,11 +585,7 @@ async function waitForWinner(pending) {
 async function executeParallel(files, pattern, opts, signal, summary) {
     const pool = getPool();
     const matches = [];
-    const scanOpts = {
-        maxFileSize: opts.maxFileSize,
-        skipBinary: opts.skipBinary,
-        contextLines: opts.contextLines,
-    };
+    const scanOpts = buildScanFileOptions(opts);
     const matcherOpts = {
         caseSensitive: opts.caseSensitive,
         wholeWord: opts.wholeWord,
@@ -596,8 +595,7 @@ async function executeParallel(files, pattern, opts, signal, summary) {
     const iterator = files[Symbol.asyncIterator]();
     let exhausted = false;
     const onAbort = () => {
-        summary.truncated = true;
-        summary.stoppedReason = 'timeout';
+        markTruncated(summary, 'timeout');
         for (const t of pending)
             t.cancel();
     };
@@ -629,12 +627,10 @@ async function executeParallel(files, pattern, opts, signal, summary) {
     }
     // Update summary truncation
     if (signal.aborted) {
-        summary.truncated = true;
-        summary.stoppedReason = 'timeout';
+        markTruncated(summary, 'timeout');
     }
     else if (matches.length >= opts.maxResults) {
-        summary.truncated = true;
-        summary.stoppedReason = 'maxResults';
+        markTruncated(summary, 'maxResults');
     }
     return matches;
 }
@@ -649,6 +645,80 @@ export async function scanFileInWorker(resolvedPath, requestedPath, matcher, opt
         skippedTooLarge: res.skippedTooLarge,
     };
 }
+async function searchSingleFile(details, opts, pattern, signal) {
+    const summary = createScanSummary();
+    summary.filesScanned = 1;
+    const matcher = buildMatcher(pattern, opts);
+    const result = await scanFileResolved(details.resolvedPath, details.requestedPath, matcher, {
+        ...buildScanFileOptions(opts),
+    }, signal, opts.maxResults);
+    if (result.matched)
+        summary.filesMatched = 1;
+    return buildSearchResult(path.dirname(details.resolvedPath), pattern, opts.filePattern, result.matches, summary);
+}
+async function searchDirectory(details, opts, pattern, signal, onProgress) {
+    const root = await validateExistingDirectory(details.resolvedPath, signal);
+    const rootDirectories = [root];
+    const stream = globEntries({
+        cwd: root,
+        pattern: opts.filePattern,
+        excludePatterns: opts.excludePatterns,
+        includeHidden: opts.includeHidden,
+        baseNameMatch: opts.baseNameMatch,
+        caseSensitiveMatch: opts.caseSensitiveFileMatch,
+        followSymbolicLinks: false,
+        onlyFiles: true,
+        stats: false,
+        suppressErrors: true,
+    });
+    async function* fileGenerator() {
+        let scanned = 0;
+        for await (const entry of stream) {
+            if (signal.aborted)
+                break;
+            if (scanned >= opts.maxFilesScanned)
+                break;
+            if (!entry.dirent.isFile())
+                continue;
+            const normalized = normalizePath(entry.path);
+            if (!isPathWithinDirectories(normalized, rootDirectories))
+                continue;
+            if (isSensitivePath(entry.path, normalized))
+                continue;
+            scanned++;
+            reportSearchProgress(onProgress, scanned, opts.maxFilesScanned);
+            yield { resolvedPath: normalized, requestedPath: entry.path };
+        }
+        reportSearchProgress(onProgress, scanned, opts.maxFilesScanned, true);
+    }
+    const summary = createScanSummary();
+    const resolvedStream = fileGenerator();
+    async function* countingStream() {
+        for await (const f of resolvedStream) {
+            summary.filesScanned++;
+            yield f;
+        }
+        if (summary.filesScanned >= opts.maxFilesScanned) {
+            summary.truncated = true;
+            summary.stoppedReason = 'maxFiles';
+        }
+    }
+    const matcherOpts = {
+        caseSensitive: opts.caseSensitive,
+        wholeWord: opts.wholeWord,
+        isLiteral: opts.isLiteral,
+    };
+    validatePattern(pattern, matcherOpts);
+    const matches = shouldUseWorkers()
+        ? await executeParallel(countingStream(), pattern, opts, signal, summary)
+        : await executeSequential(countingStream(), pattern, opts, signal, summary);
+    return buildSearchResult(root, pattern, opts.filePattern, matches, summary);
+}
+function buildTimeoutSearchResult(basePath, pattern, filePattern) {
+    const timeoutSummary = createScanSummary();
+    markTruncated(timeoutSummary, 'timeout');
+    return buildSearchResult(basePath, pattern, filePattern, [], timeoutSummary);
+}
 export async function searchContent(basePath, pattern, options = {}) {
     if (!basePath.trim())
         throw new McpError(ErrorCode.E_INVALID_INPUT, 'basePath required');
@@ -659,94 +729,17 @@ export async function searchContent(basePath, pattern, options = {}) {
     try {
         const details = await validateExistingPathDetailed(basePath, signal);
         const stats = await withAbort(fsp.stat(details.resolvedPath), signal);
-        // Check if simple file scan
         if (stats.isFile()) {
-            const summary = createScanSummary();
-            summary.filesScanned = 1;
-            // Single file execution
-            const matcher = buildMatcher(pattern, opts);
-            const result = await scanFileResolved(details.resolvedPath, details.requestedPath, matcher, {
-                maxFileSize: opts.maxFileSize,
-                skipBinary: opts.skipBinary,
-                contextLines: opts.contextLines,
-            }, signal, opts.maxResults);
-            if (result.matched)
-                summary.filesMatched = 1;
-            return buildSearchResult(path.dirname(details.resolvedPath), pattern, opts.filePattern, result.matches, summary);
+            return await searchSingleFile(details, opts, pattern, signal);
         }
         if (!stats.isDirectory()) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, `Path must be file or directory`, basePath);
+            throw new McpError(ErrorCode.E_INVALID_INPUT, 'Path must be file or directory', basePath);
         }
-        const root = await validateExistingDirectory(details.resolvedPath, signal);
-        const rootDirectories = [root];
-        // Glob
-        const stream = globEntries({
-            cwd: root,
-            pattern: opts.filePattern,
-            excludePatterns: opts.excludePatterns,
-            includeHidden: opts.includeHidden,
-            baseNameMatch: opts.baseNameMatch,
-            caseSensitiveMatch: opts.caseSensitiveFileMatch,
-            followSymbolicLinks: false,
-            onlyFiles: true,
-            stats: false,
-            suppressErrors: true,
-        });
-        // Generator adapter to resolve paths
-        async function* fileGenerator() {
-            let scanned = 0;
-            for await (const entry of stream) {
-                if (signal.aborted)
-                    break;
-                if (scanned >= opts.maxFilesScanned)
-                    break;
-                if (!entry.dirent.isFile())
-                    continue;
-                // Helper to resolve
-                // We duplicate simple resolution logic to keep it fast
-                const normalized = normalizePath(entry.path);
-                if (!isPathWithinDirectories(normalized, rootDirectories))
-                    continue;
-                if (isSensitivePath(entry.path, normalized))
-                    continue;
-                scanned++;
-                reportSearchProgress(options.onProgress, scanned, opts.maxFilesScanned);
-                yield { resolvedPath: normalized, requestedPath: entry.path };
-            }
-            reportSearchProgress(options.onProgress, scanned, opts.maxFilesScanned, true);
-        }
-        // Choose Strategy
-        // We recreate summary to track actual scans
-        const summary = createScanSummary();
-        const resolvedStream = fileGenerator();
-        // Wrap generator to count scanned files in summary
-        async function* countingStream() {
-            for await (const f of resolvedStream) {
-                summary.filesScanned++;
-                yield f;
-            }
-            if (summary.filesScanned >= opts.maxFilesScanned) {
-                summary.truncated = true;
-                summary.stoppedReason = 'maxFiles';
-            }
-        }
-        const matcherOpts = {
-            caseSensitive: opts.caseSensitive,
-            wholeWord: opts.wholeWord,
-            isLiteral: opts.isLiteral,
-        };
-        validatePattern(pattern, matcherOpts);
-        const matches = shouldUseWorkers()
-            ? await executeParallel(countingStream(), pattern, opts, signal, summary)
-            : await executeSequential(countingStream(), pattern, opts, signal, summary);
-        return buildSearchResult(root, pattern, opts.filePattern, matches, summary);
+        return await searchDirectory(details, opts, pattern, signal, options.onProgress);
     }
     catch (error) {
         if (isTimeoutLikeError(error)) {
-            const timeoutSummary = createScanSummary();
-            timeoutSummary.truncated = true;
-            timeoutSummary.stoppedReason = 'timeout';
-            return buildSearchResult(basePath, pattern, opts.filePattern, [], timeoutSummary);
+            return buildTimeoutSearchResult(basePath, pattern, opts.filePattern);
         }
         throw error;
     }

package/dist/lib/file-operations/search-files.js

@@ -3,9 +3,9 @@ import { DEFAULT_SEARCH_MAX_FILES, DEFAULT_SEARCH_TIMEOUT_MS, } from '../constan
 import { createTimedAbortSignal } from '../fs-helpers.js';
 import { isSensitivePath } from '../path-policy.js';
 import { isPathWithinDirectories, normalizePath, validateExistingDirectory, validateExistingPathDetailed, } from '../path-validation.js';
-import { needsStatsForSort, withOptionalStoppedReason } from './common.js';
+import { compareOptionalNumberDesc, compareStringValues, isEntryAccessibleByType, needsStatsForSort, resolveEntryType, resolveStopReason, stableSortByDerivedString, withOptionalStoppedReason, } from './common.js';
 import { isIgnoredByGitignore, loadRootGitignore } from './gitignore.js';
-import { globEntries, resolveEntryType } from './glob-engine.js';
+import { globEntries } from './glob-engine.js';
 // Internal default for find tool - not exposed to MCP users
 const INTERNAL_MAX_RESULTS = 1000;
 function normalizeOptions(options) {
@@ -41,17 +41,17 @@ function buildSearchResult(entry, entryType, needsStats) {
         ...(modified !== undefined ? { modified } : {}),
     };
 }
-function markStopped(state, reason) {
-    state.truncated = true;
-    state.stoppedReason = reason;
-}
 function shouldStopCollecting(state, normalized, signal) {
-    if (signal.aborted) {
-        markStopped(state, 'timeout');
-        return true;
-    }
-    if (state.filesScanned >= normalized.maxFilesScanned) {
-        markStopped(state, 'maxFiles');
+    const stopReason = resolveStopReason({
+        signal,
+        current: state.filesScanned,
+        max: normalized.maxFilesScanned,
+        abortedReason: 'timeout',
+        maxReason: 'maxFiles',
+    });
+    if (stopReason !== undefined) {
+        state.truncated = true;
+        state.stoppedReason = stopReason;
         return true;
     }
     return false;
@@ -99,7 +99,8 @@ function buildCollectResult(state) {
 function handleEntry(entry, entryType, needsStats, normalized, state) {
     state.results.push(buildSearchResult(entry, entryType, needsStats));
     if (state.results.length >= normalized.maxResults) {
-        markStopped(state, 'maxResults');
+        state.truncated = true;
+        state.stoppedReason = 'maxResults';
     }
 }
 function reportSearchFilesProgress(onProgress, current, total, force = false) {
@@ -109,7 +110,7 @@ function reportSearchFilesProgress(onProgress, current, total, force = false) {
         return;
     onProgress({ current, total });
 }
-async function collectFromStream(stream, root, rootDirectories, gitignoreMatcher, normalized, needsStats, state, signal, onProgress) {
+async function collectFromStream(stream, root, rootDirectories, gitignoreMatcher, normalized, needsStats, state, signal, accessDeps, onProgress) {
     for await (const entry of stream) {
         if (shouldStopCollecting(state, normalized, signal))
             break;
@@ -122,7 +123,7 @@ async function collectFromStream(stream, root, rootDirectories, gitignoreMatcher
         if (!shouldIncludeEntry(entryType, normalized)) {
             continue;
         }
-        const isAccessible = await isEntryAccessible(entry, entryType, rootDirectories, signal);
+        const isAccessible = await isEntryAccessibleByType(entry.path, entryType, rootDirectories, signal, accessDeps);
         if (!isAccessible) {
             state.skippedInaccessible++;
             continue;
@@ -138,31 +139,21 @@ function isEntryIgnoredByGitignore(matcher, root, entryPath, relativePath) {
         return false;
     return isIgnoredByGitignore(matcher, root, entryPath, relativePath ? { relativePath } : {});
 }
-async function isEntryAccessible(entry, entryType, rootDirectories, signal) {
-    if (entryType === 'symlink') {
-        try {
-            const validated = await validateExistingPathDetailed(entry.path, signal);
-            return !isSensitivePath(validated.requestedPath, validated.resolvedPath);
-        }
-        catch {
-            return false;
-        }
-    }
-    const resolvedPath = normalizePath(entry.path);
-    if (!isPathWithinDirectories(resolvedPath, rootDirectories)) {
-        return false;
-    }
-    return !isSensitivePath(entry.path, resolvedPath);
-}
 async function collectSearchResults(root, pattern, excludePatterns, normalized, signal, onProgress) {
     const needsStats = needsStatsForSort(normalized.sortBy);
     const stream = buildSearchStream(root, pattern, excludePatterns, normalized, needsStats);
     const state = createCollectState();
     const rootDirectories = [root];
+    const accessDeps = {
+        normalizePath,
+        isPathWithinDirectories,
+        isSensitivePath,
+        validateSymlinkPath: validateExistingPathDetailed,
+    };
     const gitignoreMatcher = normalized.respectGitignore
         ? await loadRootGitignore(root, signal)
         : null;
-    await collectFromStream(stream, root, rootDirectories, gitignoreMatcher, normalized, needsStats, state, signal, onProgress);
+    await collectFromStream(stream, root, rootDirectories, gitignoreMatcher, normalized, needsStats, state, signal, accessDeps, onProgress);
     return buildCollectResult(state);
 }
 function buildSearchSummary(results, filesScanned, truncated, stoppedReason, skippedInaccessible) {
@@ -174,27 +165,17 @@ function buildSearchSummary(results, filesScanned, truncated, stoppedReason, ski
     };
     return withOptionalStoppedReason(summary, stoppedReason);
 }
-const collator = new Intl.Collator(undefined, { numeric: true });
-function compareString(a, b) {
-    return collator.compare(a ?? '', b ?? '');
-}
 function compareNameThenPath(a, b) {
-    const nameCompare = compareString(a.name, b.name);
+    const nameCompare = compareStringValues(a.name, b.name);
     if (nameCompare !== 0)
         return nameCompare;
-    return compareString(a.path, b.path);
+    return compareStringValues(a.path, b.path);
 }
 function comparePathThenName(a, b) {
-    const pathCompare = compareString(a.path, b.path);
+    const pathCompare = compareStringValues(a.path, b.path);
     if (pathCompare !== 0)
         return pathCompare;
-    return compareString(a.name, b.name);
-}
-function compareOptionalNumberDesc(left, right, tieBreak) {
-    const diff = (right ?? 0) - (left ?? 0);
-    if (diff !== 0)
-        return diff;
-    return tieBreak();
+    return compareStringValues(a.name, b.name);
 }
 const SORT_COMPARATORS = {
     size: (a, b) => compareOptionalNumberDesc(a.size, b.size, () => compareNameThenPath(a, b)),
@@ -204,32 +185,7 @@ const SORT_COMPARATORS = {
 };
 export function sortSearchResults(results, sortBy) {
     if (sortBy === 'name') {
-        const decorated = [];
-        for (let index = 0; index < results.length; index += 1) {
-            const item = results[index];
-            if (!item)
-                continue;
-            decorated.push({
-                item,
-                baseName: path.basename(item.path ?? ''),
-                index,
-            });
-        }
-        decorated.sort((a, b) => {
-            const baseCompare = compareString(a.baseName, b.baseName);
-            if (baseCompare !== 0)
-                return baseCompare;
-            const pathCompare = compareString(a.item.path, b.item.path);
-            if (pathCompare !== 0)
-                return pathCompare;
-            return a.index - b.index;
-        });
-        for (let index = 0; index < decorated.length; index += 1) {
-            const entry = decorated[index];
-            if (entry) {
-                results[index] = entry.item;
-            }
-        }
+        stableSortByDerivedString(results, (item) => path.basename(item.path ?? ''), (left, right) => comparePathThenName(left, right));
         return;
     }
     const comparator = SORT_COMPARATORS[sortBy];

package/dist/lib/file-operations/tree.d.ts

@@ -1,7 +1,7 @@
-type TreeEntryType = 'file' | 'directory' | 'symlink' | 'other';
+import type { EntryType } from './common.js';
 interface TreeEntry {
     name: string;
-    type: TreeEntryType;
+    type: EntryType;
     relativePath: string;
     children?: TreeEntry[];
 }

package/dist/lib/file-operations/tree.js

@@ -4,8 +4,9 @@ import { createTimedAbortSignal } from '../fs-helpers.js';
 import { toPosixPath } from '../path-format.js';
 import { isSensitivePath } from '../path-policy.js';
 import { isPathWithinDirectories, normalizePath, validateExistingDirectory, validateExistingPathDetailed, } from '../path-validation.js';
+import { isEntryAccessibleByType, resolveEntryType, resolveStopReason, } from './common.js';
 import { isIgnoredByGitignore, loadRootGitignore } from './gitignore.js';
-import { globEntries, resolveEntryType } from './glob-engine.js';
+import { globEntries } from './glob-engine.js';
 function toSafeNonNegativeInt(value, fallback) {
     if (typeof value !== 'number' || !Number.isFinite(value))
         return fallback;
@@ -90,36 +91,11 @@ function getTreeTypeRank(type) {
         return 1;
     return 2;
 }
-function getStopReason(signal, totalEntries, maxEntries) {
-    if (signal.aborted) {
-        return 'aborted';
-    }
-    if (totalEntries >= maxEntries) {
-        return 'maxEntries';
-    }
-    return undefined;
-}
-async function resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal) {
+async function resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps) {
     const type = resolveEntryType(entry.dirent);
-    if (type !== 'symlink') {
-        const normalized = normalizePath(entry.path);
-        if (!isPathWithinDirectories(normalized, rootDirectories)) {
-            return null;
-        }
-        if (isSensitivePath(entry.path, normalized)) {
-            return null;
-        }
-    }
-    else {
-        try {
-            const validated = await validateExistingPathDetailed(entry.path, signal);
-            if (isSensitivePath(validated.requestedPath, validated.resolvedPath)) {
-                return null;
-            }
-        }
-        catch {
-            return null;
-        }
+    const isAccessible = await isEntryAccessibleByType(entry.path, type, rootDirectories, signal, accessDeps);
+    if (!isAccessible) {
+        return null;
     }
     if (gitignoreMatcher &&
         isIgnoredByGitignore(gitignoreMatcher, root, entry.path, {
@@ -222,6 +198,12 @@ export async function treeDirectory(dirPath, options = {}) {
     const root = await validateExistingDirectory(dirPath, signal);
     const rootNormalized = normalizePath(root);
     const rootDirectories = [rootNormalized];
+    const accessDeps = {
+        normalizePath,
+        isPathWithinDirectories,
+        isSensitivePath,
+        validateSymlinkPath: validateExistingPathDetailed,
+    };
     try {
         const excludePatterns = normalized.includeIgnored
             ? []
@@ -253,12 +235,18 @@ export async function treeDirectory(dirPath, options = {}) {
             suppressErrors: true,
         });
         for await (const entry of stream) {
-            const stopReason = getStopReason(signal, totalEntries, normalized.maxEntries);
+            const stopReason = resolveStopReason({
+                signal,
+                current: totalEntries,
+                max: normalized.maxEntries,
+                abortedReason: 'aborted',
+                maxReason: 'maxEntries',
+            });
             if (stopReason) {
                 truncated = true;
                 break;
             }
-            const resolved = await resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal);
+            const resolved = await resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps);
             if (!resolved) {
                 continue;
             }

package/dist/prompts.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { withDefaultIcons } from './tools/shared.js';
 const HELP_PROMPT_NAME = 'get-help';
 const HELP_PROMPT_TITLE = 'Get Help';
-const HELP_PROMPT_DESCRIPTION = 'Retrieve the full filesystem-mcp XML usage guide.';
+const HELP_PROMPT_DESCRIPTION = 'Return filesystem-mcp usage instructions.';
 function filterInstructionsByTopic(instructions, topic) {
     const normalized = topic.trim().toLowerCase();
     if (!normalized)
@@ -16,7 +16,7 @@ function filterInstructionsByTopic(instructions, topic) {
         .map((sec) => sec.split('\n')[0]?.replace(/^##\s*/u, '') ?? '')
         .filter(Boolean)
         .join(', ');
-    return `Section '${topic}' not found. Available sections: ${available}\n\n${instructions}`;
+    return `Section '${topic}' not found. Available: ${available}\n\n${instructions}`;
 }
 export function registerGetHelpPrompt(server, instructions, iconInfo) {
     const baseConfig = withDefaultIcons({ title: HELP_PROMPT_TITLE, description: HELP_PROMPT_DESCRIPTION }, iconInfo);
@@ -26,7 +26,7 @@ export function registerGetHelpPrompt(server, instructions, iconInfo) {
             topic: z
                 .string()
                 .optional()
-                .describe('Section heading prefix to filter (e.g. "error handling strategy"). Omit for full instructions.'),
+                .describe('Optional section heading prefix (example: "error handling"). Omit to return full instructions.'),
         },
     }, ({ topic }) => {
         const text = topic

package/dist/resources/generated-instructions.js

@@ -2,7 +2,7 @@ import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
 import { buildCoreContextPack, getSharedConstraints, getToolContracts, } from './tool-info.js';
 import { buildWorkflowGuide } from './workflows.js';
 const INSTRUCTIONS_HEADER = `<role>
-Expert filesystem agent. Operate ONLY within allowed roots. Always discover before acting — never guess paths.
+Filesystem agent for local paths only. Operate inside allowed roots. Discover before action. Never guess paths.
 </role>
 
 <tools_overview>
@@ -15,16 +15,16 @@ Expert filesystem agent. Operate ONLY within allowed roots. Always discover befo
 </tools_overview>
 
 <resources>
-- \`internal://instructions\`: Full server usage guide.
-- \`internal://tool-catalog\`: Tool routing and cross-tool data-flow guide.
-- \`internal://workflows\`: Standard operating sequences (explore/search/edit/patch).
-- \`internal://tool-info/{name}\`: Per-tool details (nuances/gotchas), e.g. \`internal://tool-info/read\`.
-- \`filesystem-mcp://result/{id}\`: Large output cache. Call \`resources/read\` immediately if \`resourceUri\` is returned.
-- \`filesystem-mcp://metrics\`: Live per-tool stats.
+- \`internal://instructions\`: Full usage reference.
+- \`internal://tool-catalog\`: Tool routing and data-flow rules.
+- \`internal://workflows\`: Standard execution sequences.
+- \`internal://tool-info/{name}\`: Per-tool nuances and gotchas (example: \`internal://tool-info/read\`).
+- \`filesystem-mcp://result/{id}\`: Cached large output. If \`resourceUri\` is returned, call \`resources/read\` immediately.
+- \`filesystem-mcp://metrics\`: Per-tool runtime metrics.
 </resources>
 
 <task_protocol>
-Async execution: provide \`_meta.progressToken\` in \`tools/call\`, poll \`tasks/get\`, call \`tasks/result\`.
+Async execution: pass \`_meta.progressToken\` in \`tools/call\`, poll \`tasks/get\`, then call \`tasks/result\`.
 Task-capable: \`find\`, \`tree\`, \`read\`, \`read_many\`, \`stat_many\`, \`grep\`, \`mkdir\`, \`write\`, \`mv\`, \`rm\`, \`calculate_hash\`, \`apply_patch\`, \`search_and_replace\`.
 </task_protocol>
 `;
@@ -35,19 +35,19 @@ ${getSharedConstraints()
 </constraints>
 
 <error_handling>
-- \`E_ACCESS_DENIED\` → Call \`roots\`; use allowed path.
-- \`E_NOT_FOUND\`     → Call \`ls\`/\`find\`; verify spelling.
-- \`E_TOO_LARGE\`     → Use range/head or \`read_many\`.
-- \`E_TIMEOUT\`       → Reduce scope or result limits.
+- \`E_ACCESS_DENIED\` => call \`roots\`, then use an allowed path.
+- \`E_NOT_FOUND\` => call \`ls\` or \`find\`, then verify spelling.
+- \`E_TOO_LARGE\` => use \`head\`, line ranges, or \`read_many\`.
+- \`E_TIMEOUT\` => reduce scope or result limits.
 </error_handling>
 `;
 function formatToolSection(tool) {
     const parts = [`### ${tool.name}\n${tool.description}`];
     if (tool.nuances && tool.nuances.length > 0) {
-        parts.push(...tool.nuances.map((n) => `» ${n}`));
+        parts.push(...tool.nuances.map((n) => `- Nuance: ${n}`));
     }
     if (tool.gotchas && tool.gotchas.length > 0) {
-        parts.push(...tool.gotchas.map((g) => `⚠ ${g}`));
+        parts.push(...tool.gotchas.map((g) => `- Gotcha: ${g}`));
     }
     return parts.join('\n');
 }