dominds 1.27.6 → 1.28.0

package/dist/tools/team_mgmt.js

@@ -13,7 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.teamMgmtTools = exports.teamMgmtClearProblemsTool = exports.teamMgmtListProblemsTool = exports.teamMgmtValidateMcpCfgTool = exports.teamMgmtValidateTeamCfgTool = exports.teamMgmtValidatePrimingScriptsTool = exports.teamMgmtUnlinkSkillTool = exports.teamMgmtLinkSkillTool = exports.teamMgmtRmSymlinkTool = exports.teamMgmtCreateSymlinkTool = exports.teamMgmtReadSymlinkTool = exports.teamMgmtRmDirTool = exports.teamMgmtRmFileTool = exports.teamMgmtRipgrepSearchTool = exports.teamMgmtRipgrepFixedTool = exports.teamMgmtRipgrepCountTool = exports.teamMgmtRipgrepSnippetsTool = exports.teamMgmtRipgrepFilesTool = exports.teamMgmtMoveDirTool = exports.teamMgmtMoveFileTool = exports.teamMgmtMkDirTool = exports.teamMgmtApplyFileModificationTool = exports.teamMgmtPrepareFileRangeEditTool = exports.teamMgmtPrepareBlockReplaceTool = exports.teamMgmtPrepareInsertBeforeTool = exports.teamMgmtPrepareInsertAfterTool = exports.teamMgmtPrepareFileAppendTool = exports.teamMgmtOverwriteEntireFileTool = exports.teamMgmtCreateNewFileTool = exports.teamMgmtReadFileTool = exports.teamMgmtListDirTool = exports.teamMgmtListModelsTool = exports.teamMgmtListProvidersTool = exports.teamMgmtCheckProviderTool = void 0;
+exports.teamMgmtTools = exports.teamMgmtClearProblemsTool = exports.teamMgmtListProblemsTool = exports.teamMgmtValidateMcpCfgTool = exports.teamMgmtValidateTeamCfgTool = exports.teamMgmtValidatePrimingScriptsTool = exports.teamMgmtUnlinkSkillTool = exports.teamMgmtLinkSkillTool = exports.teamMgmtRmSymlinkTool = exports.teamMgmtCreateSymlinkTool = exports.teamMgmtReadSymlinkTool = exports.teamMgmtRmDirTool = exports.teamMgmtRmFileTool = exports.teamMgmtRipgrepSearchTool = exports.teamMgmtRipgrepFixedTool = exports.teamMgmtRipgrepCountTool = exports.teamMgmtRipgrepSnippetsTool = exports.teamMgmtRipgrepFilesTool = exports.teamMgmtMoveDirTool = exports.teamMgmtMoveFileTool = exports.teamMgmtMkDirTool = exports.teamMgmtApplyOccurrenceReplaceTool = exports.teamMgmtPrepareOccurrenceReplaceTool = exports.teamMgmtFileRangeEditTool = exports.teamMgmtFileBlockReplaceTool = exports.teamMgmtFileInsertBeforeTool = exports.teamMgmtFileInsertAfterTool = exports.teamMgmtFileAppendTool = exports.teamMgmtOverwriteEntireFileTool = exports.teamMgmtCreateNewFileTool = exports.teamMgmtReadFileTool = exports.teamMgmtListDirTool = exports.teamMgmtListModelsTool = exports.teamMgmtListProvidersTool = exports.teamMgmtCheckProviderTool = void 0;
 exports.splitCommandArgs = splitCommandArgs;
 exports.renderMemberProperties = renderMemberProperties;
 exports.renderTeamManual = renderTeamManual;
@@ -99,12 +99,6 @@ function yamlQuote(value) {
 function formatYamlCodeBlock(yaml) {
     return `\`\`\`yaml\n${yaml}\n\`\`\``;
 }
-function normalizeFileWriteBody(inputBody) {
-    if (inputBody === '' || inputBody.endsWith('\n')) {
-        return { normalizedBody: inputBody, addedTrailingNewlineToContent: false };
-    }
-    return { normalizedBody: `${inputBody}\n`, addedTrailingNewlineToContent: true };
-}
 function isEmptyLine(line) {
     return line.trim() === '';
 }
@@ -197,15 +191,6 @@ async function lintTeamYamlStyleProblems() {
         },
     ]);
 }
-function countLogicalLines(text) {
-    if (text === '')
-        return 0;
-    const parts = text.split('\n');
-    if (parts.length > 0 && parts[parts.length - 1] === '') {
-        parts.pop();
-    }
-    return parts.length;
-}
 function normalizePathToken(raw) {
     return raw.trim().replace(/\\/g, '/').replace(/^\/+/, '');
 }
@@ -1523,10 +1508,10 @@ exports.teamMgmtReadFileTool = {
 exports.teamMgmtCreateNewFileTool = {
     type: 'func',
     name: 'team_mgmt_create_new_file',
-    description: `Create a new file under ${MINDS_DIR}/ (no prepare/apply). Refuses to overwrite existing files.`,
+    description: `Create a new file under ${MINDS_DIR}/ from inline content or a ws_mod pad source. Refuses to overwrite existing files.`,
     descriptionI18n: {
-        en: `Create a new file under ${MINDS_DIR}/ (no prepare/apply). Refuses to overwrite existing files.`,
-        zh: `在 ${MINDS_DIR}/ 下创建一个新文件（不走 prepare/apply）。若文件已存在则拒绝覆写。`,
+        en: `Create a new file under ${MINDS_DIR}/ from inline content or a ws_mod pad source. Refuses to overwrite existing files.`,
+        zh: `用内联 content 或 ws_mod pad 来源在 ${MINDS_DIR}/ 下创建一个新文件。若文件已存在则拒绝覆写。`,
     },
     parameters: {
         type: 'object',
@@ -1535,26 +1520,13 @@ exports.teamMgmtCreateNewFileTool = {
         properties: {
             path: { type: 'string' },
             content: { type: 'string' },
+            pad_id: { type: 'string' },
+            pad_range: { type: 'string' },
         },
     },
     argsValidation: 'dominds',
-    async call(dlg, _caller, args) {
+    async call(dlg, caller, args) {
         const language = getUserLang(dlg);
-        const t = language === 'zh'
-            ? {
-                invalidArgs: (msg) => `参数不正确：${msg}`,
-                fileExists: '文件已存在，拒绝创建。',
-                notAFile: '路径已存在但不是文件（可能是目录），拒绝创建。',
-                nextOverwrite: '下一步：先用 team_mgmt_read_file 获取 total_lines/size_bytes，然后再调用 team_mgmt_overwrite_entire_file 覆盖写入。',
-                ok: '已创建新文件。',
-            }
-            : {
-                invalidArgs: (msg) => `Invalid args: ${msg}`,
-                fileExists: 'File already exists; refusing to create.',
-                notAFile: 'Path exists but is not a file (e.g. a directory); refusing to create.',
-                nextOverwrite: 'Next: call team_mgmt_read_file to get total_lines/size_bytes, then use team_mgmt_overwrite_entire_file to overwrite.',
-                ok: 'Created new file.',
-            };
         try {
             const mindsState = await getMindsDirState();
             if (mindsState.kind === 'not_directory') {
@@ -1563,114 +1535,66 @@ exports.teamMgmtCreateNewFileTool = {
             await ensureMindsRootDirExists();
             const pathValue = args['path'];
             const rawPath = typeof pathValue === 'string' ? pathValue.trim() : '';
-            if (!rawPath) {
-                const content = formatYamlCodeBlock([
-                    `status: error`,
-                    `mode: create_new_file`,
-                    `error: INVALID_ARGS`,
-                    `summary: ${yamlQuote(t.invalidArgs('Path required'))}`,
-                ].join('\n'));
-                return fail(content, [{ type: 'environment_msg', role: 'user', content }]);
-            }
-            const rel = toMindsRelativePath(rawPath);
-            const { abs } = ensureMindsScopedPath(rel);
-            if (rel === MINDS_DIR) {
-                const content = formatYamlCodeBlock([
-                    `status: error`,
-                    `mode: create_new_file`,
-                    `path: ${yamlQuote(rel)}`,
-                    `error: NOT_A_FILE`,
-                    `summary: ${yamlQuote(t.notAFile)}`,
-                ].join('\n'));
-                return fail(content, [{ type: 'environment_msg', role: 'user', content }]);
-            }
+            if (!rawPath)
+                throw new Error('Path required');
             const contentValue = args['content'];
             if (contentValue !== undefined && typeof contentValue !== 'string') {
                 throw new Error('Invalid content (expected string)');
             }
-            const initialContent = typeof contentValue === 'string' ? contentValue : '';
-            try {
-                const st = await promises_1.default.stat(abs);
-                if (!st.isFile()) {
-                    const out = formatYamlCodeBlock([
-                        `status: error`,
-                        `mode: create_new_file`,
-                        `path: ${yamlQuote(rel)}`,
-                        `error: NOT_A_FILE`,
-                        `summary: ${yamlQuote(t.notAFile)}`,
-                    ].join('\n'));
-                    return fail(out, [{ type: 'environment_msg', role: 'user', content: out }]);
-                }
-                const out = formatYamlCodeBlock([
-                    `status: error`,
-                    `mode: create_new_file`,
-                    `path: ${yamlQuote(rel)}`,
-                    `error: FILE_EXISTS`,
-                    `summary: ${yamlQuote(t.fileExists)}`,
-                    `next: ${yamlQuote(t.nextOverwrite)}`,
-                ].join('\n'));
-                return fail(out, [{ type: 'environment_msg', role: 'user', content: out }]);
+            const padIdValue = args['pad_id'];
+            if (padIdValue !== undefined && typeof padIdValue !== 'string') {
+                throw new Error('Invalid pad_id (expected string)');
             }
-            catch (err) {
-                if (!isFsErrWithCode(err) || err.code !== 'ENOENT')
-                    throw err;
+            const padRangeValue = args['pad_range'];
+            if (padRangeValue !== undefined && typeof padRangeValue !== 'string') {
+                throw new Error('Invalid pad_range (expected string)');
             }
-            const { normalizedBody, addedTrailingNewlineToContent } = normalizeFileWriteBody(initialContent);
-            await promises_1.default.mkdir(path_1.default.dirname(abs), { recursive: true });
-            await promises_1.default.writeFile(abs, normalizedBody, 'utf8');
-            const newTotalBytes = Buffer.byteLength(normalizedBody, 'utf8');
-            const newTotalLines = countLogicalLines(normalizedBody);
-            const normalizedNewlineAdded = addedTrailingNewlineToContent && normalizedBody !== '';
-            const summary = language === 'zh'
-                ? `${t.ok} path=${rel}; new_total_lines=${newTotalLines}; new_total_bytes=${newTotalBytes}.`
-                : `${t.ok} path=${rel}; new_total_lines=${newTotalLines}; new_total_bytes=${newTotalBytes}.`;
-            const out = formatYamlCodeBlock([
-                `status: ok`,
-                `mode: create_new_file`,
-                `path: ${yamlQuote(rel)}`,
-                `new_total_lines: ${newTotalLines}`,
-                `new_total_bytes: ${newTotalBytes}`,
-                `normalized_trailing_newline_added: ${normalizedNewlineAdded}`,
-                `summary: ${yamlQuote(summary)}`,
-            ].join('\n'));
-            await refreshDerivedStateAfterTeamMgmtWrite({
-                relPaths: [rel],
-                trigger: 'create_new_file',
+            const rel = toMindsRelativePath(rawPath);
+            ensureMindsScopedPath(rel);
+            const proxyCaller = makeMindsOnlyAccessMember(caller);
+            const output = await txt_1.createNewFileTool.call(dlg, proxyCaller, {
+                path: rel,
+                ...(contentValue !== undefined ? { content: contentValue } : {}),
+                ...(padIdValue !== undefined ? { pad_id: padIdValue } : {}),
+                ...(padRangeValue !== undefined ? { pad_range: padRangeValue } : {}),
             });
-            return ok(out, [{ type: 'environment_msg', role: 'user', content: out }]);
+            const content = toolCallOutputToString(output);
+            if (isSuccessfulYamlToolResult(content, 'create_new_file')) {
+                await refreshDerivedStateAfterTeamMgmtWrite({
+                    relPaths: [rel],
+                    trigger: 'create_new_file',
+                });
+            }
+            return output;
         }
         catch (err) {
             const msg = language === 'zh'
                 ? `错误：${err instanceof Error ? err.message : String(err)}`
                 : `Error: ${err instanceof Error ? err.message : String(err)}`;
-            const out = formatYamlCodeBlock([
-                `status: error`,
-                `mode: create_new_file`,
-                `error: FAILED`,
-                `summary: ${yamlQuote(msg)}`,
-            ].join('\n'));
-            return fail(out, [{ type: 'environment_msg', role: 'user', content: out }]);
+            return fail(msg, [{ type: 'environment_msg', role: 'user', content: msg }]);
         }
     },
 };
 exports.teamMgmtOverwriteEntireFileTool = {
     type: 'func',
     name: 'team_mgmt_overwrite_entire_file',
-    description: `Overwrite an existing file under ${MINDS_DIR}/ (writes immediately; guarded).`,
+    description: `Overwrite an existing file under ${MINDS_DIR}/ from inline content or a ws_mod pad source (writes immediately; guarded).`,
     descriptionI18n: {
-        en: `Overwrite an existing file under ${MINDS_DIR}/ (writes immediately; guarded).`,
-        zh: `整体覆盖写入 ${MINDS_DIR}/ 下的已存在文件（直接写盘，带护栏）。`,
+        en: `Overwrite an existing file under ${MINDS_DIR}/ from inline content or a ws_mod pad source (writes immediately; guarded).`,
+        zh: `用内联 content 或 ws_mod pad 来源整体覆盖写入 ${MINDS_DIR}/ 下的已存在文件（直接写盘，带护栏）。`,
     },
     parameters: {
         type: 'object',
         additionalProperties: false,
-        required: ['path', 'known_old_total_lines', 'known_old_total_bytes', 'content'],
+        required: ['path', 'known_old_total_lines', 'known_old_total_bytes'],
         properties: {
             path: { type: 'string' },
             known_old_total_lines: { type: 'integer' },
             known_old_total_bytes: { type: 'integer' },
             content_format: { type: 'string' },
             content: { type: 'string' },
+            pad_id: { type: 'string' },
+            pad_range: { type: 'string' },
         },
     },
     argsValidation: 'dominds',
@@ -1699,9 +1623,17 @@ exports.teamMgmtOverwriteEntireFileTool = {
                     : 'known_old_total_bytes must be an integer.');
             }
             const contentValue = args['content'];
-            if (typeof contentValue !== 'string') {
+            if (contentValue !== undefined && typeof contentValue !== 'string') {
                 throw new Error(language === 'zh' ? 'content 需要为字符串。' : 'content must be a string.');
             }
+            const padIdValue = args['pad_id'];
+            if (padIdValue !== undefined && typeof padIdValue !== 'string') {
+                throw new Error('Invalid pad_id (expected string)');
+            }
+            const padRangeValue = args['pad_range'];
+            if (padRangeValue !== undefined && typeof padRangeValue !== 'string') {
+                throw new Error('Invalid pad_range (expected string)');
+            }
             const contentFormatValue = args['content_format'];
             const contentFormat = contentFormatValue === undefined
                 ? undefined
@@ -1718,7 +1650,9 @@ exports.teamMgmtOverwriteEntireFileTool = {
                 path: rel,
                 known_old_total_lines: knownLinesValue,
                 known_old_total_bytes: knownBytesValue,
-                content: contentValue,
+                ...(contentValue !== undefined ? { content: contentValue } : {}),
+                ...(padIdValue !== undefined ? { pad_id: padIdValue } : {}),
+                ...(padRangeValue !== undefined ? { pad_range: padRangeValue } : {}),
                 ...(contentFormat ? { content_format: contentFormat } : {}),
             });
             const result = toolCallOutputToString(output);
@@ -1738,23 +1672,26 @@ exports.teamMgmtOverwriteEntireFileTool = {
         }
     },
 };
-exports.teamMgmtPrepareFileAppendTool = {
+exports.teamMgmtFileAppendTool = {
     type: 'func',
-    name: 'team_mgmt_prepare_file_append',
-    description: `Prepare an append-to-EOF modification under ${MINDS_DIR}/ (does not write yet).`,
+    name: 'team_mgmt_file_append',
+    description: `Append to a file under ${MINDS_DIR}/ directly.`,
     descriptionI18n: {
-        en: `Prepare an append-to-EOF modification under ${MINDS_DIR}/ (does not write yet).`,
-        zh: `规划 ${MINDS_DIR}/ 下“末尾追加”修改（不会立刻写入）。`,
+        en: `Append to a file under ${MINDS_DIR}/ directly.`,
+        zh: `直接向 ${MINDS_DIR}/ 下文件末尾追加内容。`,
     },
     parameters: {
         type: 'object',
         additionalProperties: false,
-        required: ['path', 'content'],
+        required: ['path'],
         properties: {
             path: { type: 'string' },
             create: { type: 'boolean' },
-            existing_hunk_id: { type: 'string' },
             content: { type: 'string' },
+            pad_id: { type: 'string' },
+            pad_range: { type: 'string' },
+            preview: { type: 'boolean' },
+            show_diff: { type: 'boolean' },
         },
     },
     argsValidation: 'dominds',
@@ -1778,25 +1715,42 @@ exports.teamMgmtPrepareFileAppendTool = {
             if (createValue !== undefined && typeof createValue !== 'boolean') {
                 throw new Error('Invalid create (expected boolean)');
             }
-            const existingHunkIdValue = args['existing_hunk_id'];
-            const existingHunkId = existingHunkIdValue === undefined
-                ? undefined
-                : typeof existingHunkIdValue === 'string'
-                    ? existingHunkIdValue
-                    : undefined;
-            if (existingHunkIdValue !== undefined && typeof existingHunkIdValue !== 'string') {
-                throw new Error('Invalid existing_hunk_id (expected string)');
-            }
             const contentValue = args['content'];
-            if (typeof contentValue !== 'string')
+            if (contentValue !== undefined && typeof contentValue !== 'string') {
                 throw new Error('Invalid content (expected string)');
-            const output = await txt_1.prepareFileAppendTool.call(dlg, proxyCaller, {
+            }
+            const padIdValue = args['pad_id'];
+            if (padIdValue !== undefined && typeof padIdValue !== 'string') {
+                throw new Error('Invalid pad_id (expected string)');
+            }
+            const padRangeValue = args['pad_range'];
+            if (padRangeValue !== undefined && typeof padRangeValue !== 'string') {
+                throw new Error('Invalid pad_range (expected string)');
+            }
+            const previewValue = args['preview'];
+            if (previewValue !== undefined && typeof previewValue !== 'boolean') {
+                throw new Error('Invalid preview (expected boolean)');
+            }
+            const showDiffValue = args['show_diff'];
+            if (showDiffValue !== undefined && typeof showDiffValue !== 'boolean') {
+                throw new Error('Invalid show_diff (expected boolean)');
+            }
+            const output = await txt_1.fileAppendTool.call(dlg, proxyCaller, {
                 path: rel,
                 ...(create !== undefined ? { create } : {}),
-                ...(existingHunkId ? { existing_hunk_id: existingHunkId } : {}),
-                content: contentValue,
+                ...(contentValue !== undefined ? { content: contentValue } : {}),
+                ...(padIdValue !== undefined ? { pad_id: padIdValue } : {}),
+                ...(padRangeValue !== undefined ? { pad_range: padRangeValue } : {}),
+                ...(previewValue !== undefined ? { preview: previewValue } : {}),
+                ...(showDiffValue !== undefined ? { show_diff: showDiffValue } : {}),
             });
             const content = toolCallOutputToString(output);
+            if (isSuccessfulYamlToolResult(content, 'file_append')) {
+                await refreshDerivedStateAfterTeamMgmtWrite({
+                    relPaths: [rel],
+                    trigger: 'team_mgmt_file_append',
+                });
+            }
             return output;
         }
         catch (err) {
@@ -1807,25 +1761,28 @@ exports.teamMgmtPrepareFileAppendTool = {
         }
     },
 };
-exports.teamMgmtPrepareInsertAfterTool = {
+exports.teamMgmtFileInsertAfterTool = {
     type: 'func',
-    name: 'team_mgmt_prepare_file_insert_after',
-    description: `Prepare an insertion after an anchor under ${MINDS_DIR}/ (does not write yet).`,
+    name: 'team_mgmt_file_insert_after',
+    description: `Insert after an anchor under ${MINDS_DIR}/ directly.`,
     descriptionI18n: {
-        en: `Prepare an insertion after an anchor under ${MINDS_DIR}/ (does not write yet).`,
-        zh: `按锚点规划 ${MINDS_DIR}/ 下“在其后插入”修改（不会立刻写入）。`,
+        en: `Insert after an anchor under ${MINDS_DIR}/ directly.`,
+        zh: `按锚点直接在 ${MINDS_DIR}/ 下文件中后插内容。`,
     },
     parameters: {
         type: 'object',
         additionalProperties: false,
-        required: ['path', 'anchor', 'content'],
+        required: ['path', 'anchor'],
         properties: {
             path: { type: 'string' },
             anchor: { type: 'string' },
             occurrence: { type: ['integer', 'string'] },
             match: { type: 'string' },
-            existing_hunk_id: { type: 'string' },
             content: { type: 'string' },
+            pad_id: { type: 'string' },
+            pad_range: { type: 'string' },
+            preview: { type: 'boolean' },
+            show_diff: { type: 'boolean' },
         },
     },
     argsValidation: 'dominds',
@@ -1861,22 +1818,44 @@ exports.teamMgmtPrepareInsertAfterTool = {
             if (matchValue !== undefined && typeof matchValue !== 'string') {
                 throw new Error("Invalid match (expected 'contains'|'equals')");
             }
-            const existingHunkIdValue = args['existing_hunk_id'];
-            if (existingHunkIdValue !== undefined && typeof existingHunkIdValue !== 'string') {
-                throw new Error('Invalid existing_hunk_id (expected string)');
-            }
             const contentValue = args['content'];
-            if (typeof contentValue !== 'string')
+            if (contentValue !== undefined && typeof contentValue !== 'string') {
                 throw new Error('Invalid content (expected string)');
-            const output = await txt_1.prepareFileInsertAfterTool.call(dlg, proxyCaller, {
+            }
+            const padIdValue = args['pad_id'];
+            if (padIdValue !== undefined && typeof padIdValue !== 'string') {
+                throw new Error('Invalid pad_id (expected string)');
+            }
+            const padRangeValue = args['pad_range'];
+            if (padRangeValue !== undefined && typeof padRangeValue !== 'string') {
+                throw new Error('Invalid pad_range (expected string)');
+            }
+            const previewValue = args['preview'];
+            if (previewValue !== undefined && typeof previewValue !== 'boolean') {
+                throw new Error('Invalid preview (expected boolean)');
+            }
+            const showDiffValue = args['show_diff'];
+            if (showDiffValue !== undefined && typeof showDiffValue !== 'boolean') {
+                throw new Error('Invalid show_diff (expected boolean)');
+            }
+            const output = await txt_1.fileInsertAfterTool.call(dlg, proxyCaller, {
                 path: rel,
                 anchor,
                 ...(occurrenceValue !== undefined ? { occurrence: occurrenceValue } : {}),
                 ...(matchValue !== undefined ? { match: matchValue } : {}),
-                ...(existingHunkIdValue ? { existing_hunk_id: existingHunkIdValue } : {}),
-                content: contentValue,
+                ...(contentValue !== undefined ? { content: contentValue } : {}),
+                ...(padIdValue !== undefined ? { pad_id: padIdValue } : {}),
+                ...(padRangeValue !== undefined ? { pad_range: padRangeValue } : {}),
+                ...(previewValue !== undefined ? { preview: previewValue } : {}),
+                ...(showDiffValue !== undefined ? { show_diff: showDiffValue } : {}),
             });
             const content = toolCallOutputToString(output);
+            if (isSuccessfulYamlToolResult(content, 'file_insert_after')) {
+                await refreshDerivedStateAfterTeamMgmtWrite({
+                    relPaths: [rel],
+                    trigger: 'team_mgmt_file_insert_after',
+                });
+            }
             return output;
         }
         catch (err) {
@@ -1887,25 +1866,28 @@ exports.teamMgmtPrepareInsertAfterTool = {
         }
     },
 };
-exports.teamMgmtPrepareInsertBeforeTool = {
+exports.teamMgmtFileInsertBeforeTool = {
     type: 'func',
-    name: 'team_mgmt_prepare_file_insert_before',
-    description: `Prepare an insertion before an anchor under ${MINDS_DIR}/ (does not write yet).`,
+    name: 'team_mgmt_file_insert_before',
+    description: `Insert before an anchor under ${MINDS_DIR}/ directly.`,
     descriptionI18n: {
-        en: `Prepare an insertion before an anchor under ${MINDS_DIR}/ (does not write yet).`,
-        zh: `按锚点规划 ${MINDS_DIR}/ 下“在其前插入”修改（不会立刻写入）。`,
+        en: `Insert before an anchor under ${MINDS_DIR}/ directly.`,
+        zh: `按锚点直接在 ${MINDS_DIR}/ 下文件中前插内容。`,
     },
     parameters: {
         type: 'object',
         additionalProperties: false,
-        required: ['path', 'anchor', 'content'],
+        required: ['path', 'anchor'],
         properties: {
             path: { type: 'string' },
             anchor: { type: 'string' },
             occurrence: { type: ['integer', 'string'] },
             match: { type: 'string' },
-            existing_hunk_id: { type: 'string' },
             content: { type: 'string' },
+            pad_id: { type: 'string' },
+            pad_range: { type: 'string' },
+            preview: { type: 'boolean' },
+            show_diff: { type: 'boolean' },
         },
     },
     argsValidation: 'dominds',
@@ -1941,22 +1923,44 @@ exports.teamMgmtPrepareInsertBeforeTool = {
             if (matchValue !== undefined && typeof matchValue !== 'string') {
                 throw new Error("Invalid match (expected 'contains'|'equals')");
             }
-            const existingHunkIdValue = args['existing_hunk_id'];
-            if (existingHunkIdValue !== undefined && typeof existingHunkIdValue !== 'string') {
-                throw new Error('Invalid existing_hunk_id (expected string)');
-            }
             const contentValue = args['content'];
-            if (typeof contentValue !== 'string')
+            if (contentValue !== undefined && typeof contentValue !== 'string') {
                 throw new Error('Invalid content (expected string)');
-            const output = await txt_1.prepareFileInsertBeforeTool.call(dlg, proxyCaller, {
+            }
+            const padIdValue = args['pad_id'];
+            if (padIdValue !== undefined && typeof padIdValue !== 'string') {
+                throw new Error('Invalid pad_id (expected string)');
+            }
+            const padRangeValue = args['pad_range'];
+            if (padRangeValue !== undefined && typeof padRangeValue !== 'string') {
+                throw new Error('Invalid pad_range (expected string)');
+            }
+            const previewValue = args['preview'];
+            if (previewValue !== undefined && typeof previewValue !== 'boolean') {
+                throw new Error('Invalid preview (expected boolean)');
+            }
+            const showDiffValue = args['show_diff'];
+            if (showDiffValue !== undefined && typeof showDiffValue !== 'boolean') {
+                throw new Error('Invalid show_diff (expected boolean)');
+            }
+            const output = await txt_1.fileInsertBeforeTool.call(dlg, proxyCaller, {
                 path: rel,
                 anchor,
                 ...(occurrenceValue !== undefined ? { occurrence: occurrenceValue } : {}),
                 ...(matchValue !== undefined ? { match: matchValue } : {}),
-                ...(existingHunkIdValue ? { existing_hunk_id: existingHunkIdValue } : {}),
-                content: contentValue,
+                ...(contentValue !== undefined ? { content: contentValue } : {}),
+                ...(padIdValue !== undefined ? { pad_id: padIdValue } : {}),
+                ...(padRangeValue !== undefined ? { pad_range: padRangeValue } : {}),
+                ...(previewValue !== undefined ? { preview: previewValue } : {}),
+                ...(showDiffValue !== undefined ? { show_diff: showDiffValue } : {}),
             });
             const content = toolCallOutputToString(output);
+            if (isSuccessfulYamlToolResult(content, 'file_insert_before')) {
+                await refreshDerivedStateAfterTeamMgmtWrite({
+                    relPaths: [rel],
+                    trigger: 'team_mgmt_file_insert_before',
+                });
+            }
             return output;
         }
         catch (err) {
@@ -1967,18 +1971,18 @@ exports.teamMgmtPrepareInsertBeforeTool = {
         }
     },
 };
-exports.teamMgmtPrepareBlockReplaceTool = {
+exports.teamMgmtFileBlockReplaceTool = {
     type: 'func',
-    name: 'team_mgmt_prepare_file_block_replace',
-    description: `Prepare a block replacement between anchors in a file under ${MINDS_DIR}/ (does not write yet).`,
+    name: 'team_mgmt_file_block_replace',
+    description: `Replace an anchor-delimited block under ${MINDS_DIR}/ directly.`,
     descriptionI18n: {
-        en: `Prepare a block replacement between anchors in a file under ${MINDS_DIR}/ (does not write yet).`,
-        zh: `按锚点规划 ${MINDS_DIR}/ 下文件的块替换（不会立刻写入）。`,
+        en: `Replace an anchor-delimited block under ${MINDS_DIR}/ directly.`,
+        zh: `按锚点直接替换 ${MINDS_DIR}/ 下文件中的块内容。`,
     },
     parameters: {
         type: 'object',
         additionalProperties: false,
-        required: ['path', 'start_anchor', 'end_anchor', 'content'],
+        required: ['path', 'start_anchor', 'end_anchor'],
         properties: {
             path: { type: 'string' },
             start_anchor: { type: 'string' },
@@ -1988,8 +1992,11 @@ exports.teamMgmtPrepareBlockReplaceTool = {
             match: { type: 'string' },
             require_unique: { type: 'boolean' },
             strict: { type: 'boolean' },
-            existing_hunk_id: { type: 'string' },
             content: { type: 'string' },
+            pad_id: { type: 'string' },
+            pad_range: { type: 'string' },
+            preview: { type: 'boolean' },
+            show_diff: { type: 'boolean' },
         },
     },
     argsValidation: 'dominds',
@@ -2039,14 +2046,27 @@ exports.teamMgmtPrepareBlockReplaceTool = {
             if (strictValue !== undefined && typeof strictValue !== 'boolean') {
                 throw new Error('Invalid strict (expected boolean)');
             }
-            const existingHunkIdValue = args['existing_hunk_id'];
-            if (existingHunkIdValue !== undefined && typeof existingHunkIdValue !== 'string') {
-                throw new Error('Invalid existing_hunk_id (expected string)');
-            }
             const contentValue = args['content'];
-            if (typeof contentValue !== 'string')
+            if (contentValue !== undefined && typeof contentValue !== 'string') {
                 throw new Error('Invalid content (expected string)');
-            const output = await txt_1.prepareFileBlockReplaceTool.call(dlg, proxyCaller, {
+            }
+            const padIdValue = args['pad_id'];
+            if (padIdValue !== undefined && typeof padIdValue !== 'string') {
+                throw new Error('Invalid pad_id (expected string)');
+            }
+            const padRangeValue = args['pad_range'];
+            if (padRangeValue !== undefined && typeof padRangeValue !== 'string') {
+                throw new Error('Invalid pad_range (expected string)');
+            }
+            const previewValue = args['preview'];
+            if (previewValue !== undefined && typeof previewValue !== 'boolean') {
+                throw new Error('Invalid preview (expected boolean)');
+            }
+            const showDiffValue = args['show_diff'];
+            if (showDiffValue !== undefined && typeof showDiffValue !== 'boolean') {
+                throw new Error('Invalid show_diff (expected boolean)');
+            }
+            const output = await txt_1.fileBlockReplaceTool.call(dlg, proxyCaller, {
                 path: rel,
                 start_anchor: startAnchor,
                 end_anchor: endAnchor,
@@ -2055,10 +2075,19 @@ exports.teamMgmtPrepareBlockReplaceTool = {
                 ...(matchValue !== undefined ? { match: matchValue } : {}),
                 ...(requireUniqueValue !== undefined ? { require_unique: requireUniqueValue } : {}),
                 ...(strictValue !== undefined ? { strict: strictValue } : {}),
-                ...(existingHunkIdValue ? { existing_hunk_id: existingHunkIdValue } : {}),
-                content: contentValue,
+                ...(contentValue !== undefined ? { content: contentValue } : {}),
+                ...(padIdValue !== undefined ? { pad_id: padIdValue } : {}),
+                ...(padRangeValue !== undefined ? { pad_range: padRangeValue } : {}),
+                ...(previewValue !== undefined ? { preview: previewValue } : {}),
+                ...(showDiffValue !== undefined ? { show_diff: showDiffValue } : {}),
             });
             const content = toolCallOutputToString(output);
+            if (isSuccessfulYamlToolResult(content, 'file_block_replace')) {
+                await refreshDerivedStateAfterTeamMgmtWrite({
+                    relPaths: [rel],
+                    trigger: 'team_mgmt_file_block_replace',
+                });
+            }
             return output;
         }
         catch (err) {
@@ -2069,13 +2098,13 @@ exports.teamMgmtPrepareBlockReplaceTool = {
         }
     },
 };
-exports.teamMgmtPrepareFileRangeEditTool = {
+exports.teamMgmtFileRangeEditTool = {
     type: 'func',
-    name: 'team_mgmt_prepare_file_range_edit',
-    description: `Prepare a single-file modification under ${MINDS_DIR}/ (does not write yet).`,
+    name: 'team_mgmt_file_range_edit',
+    description: `Directly write a precise line range under ${MINDS_DIR}/ from inline content or a ws_mod pad source.`,
     descriptionI18n: {
-        en: `Prepare a single-file modification under ${MINDS_DIR}/ (does not write yet).`,
-        zh: `按行号范围规划 ${MINDS_DIR}/ 下的单文件修改（不会立刻写入）。`,
+        en: `Directly write a precise line range under ${MINDS_DIR}/ from inline content or a ws_mod pad source.`,
+        zh: `用内联 content 或 ws_mod pad 来源按精确行号范围直接写入 ${MINDS_DIR}/ 下的文件。`,
     },
     parameters: {
         type: 'object',
@@ -2084,8 +2113,11 @@ exports.teamMgmtPrepareFileRangeEditTool = {
         properties: {
             path: { type: 'string' },
             range: { type: 'string' },
-            existing_hunk_id: { type: 'string' },
             content: { type: 'string' },
+            pad_id: { type: 'string' },
+            pad_range: { type: 'string' },
+            preview: { type: 'boolean' },
+            show_diff: { type: 'boolean' },
         },
     },
     argsValidation: 'dominds',
@@ -2105,24 +2137,45 @@ exports.teamMgmtPrepareFileRangeEditTool = {
                 throw new Error('Path required');
             if (!rangeSpec)
                 throw new Error('Range required (e.g. 10~20 or ~)');
-            const existingHunkIdValue = args['existing_hunk_id'];
-            if (existingHunkIdValue !== undefined && typeof existingHunkIdValue !== 'string') {
-                throw new Error('Invalid existing_hunk_id (expected string)');
-            }
             const contentValue = args['content'];
             if (contentValue !== undefined && typeof contentValue !== 'string') {
                 throw new Error('Invalid content (expected string)');
             }
+            const padIdValue = args['pad_id'];
+            if (padIdValue !== undefined && typeof padIdValue !== 'string') {
+                throw new Error('Invalid pad_id (expected string)');
+            }
+            const padRangeValue = args['pad_range'];
+            if (padRangeValue !== undefined && typeof padRangeValue !== 'string') {
+                throw new Error('Invalid pad_range (expected string)');
+            }
+            const previewValue = args['preview'];
+            if (previewValue !== undefined && typeof previewValue !== 'boolean') {
+                throw new Error('Invalid preview (expected boolean)');
+            }
+            const showDiffValue = args['show_diff'];
+            if (showDiffValue !== undefined && typeof showDiffValue !== 'boolean') {
+                throw new Error('Invalid show_diff (expected boolean)');
+            }
             const rel = toMindsRelativePath(filePath);
             ensureMindsScopedPath(rel);
             const proxyCaller = makeMindsOnlyAccessMember(caller);
-            const output = await txt_1.prepareFileRangeEditTool.call(dlg, proxyCaller, {
+            const output = await txt_1.fileRangeEditTool.call(dlg, proxyCaller, {
                 path: rel,
                 range: rangeSpec,
-                ...(existingHunkIdValue ? { existing_hunk_id: existingHunkIdValue } : {}),
-                ...(typeof contentValue === 'string' ? { content: contentValue } : {}),
+                ...(contentValue !== undefined ? { content: contentValue } : {}),
+                ...(padIdValue !== undefined ? { pad_id: padIdValue } : {}),
+                ...(padRangeValue !== undefined ? { pad_range: padRangeValue } : {}),
+                ...(previewValue !== undefined ? { preview: previewValue } : {}),
+                ...(showDiffValue !== undefined ? { show_diff: showDiffValue } : {}),
             });
             const content = toolCallOutputToString(output);
+            if (isSuccessfulYamlToolResult(content, 'file_range_edit')) {
+                await refreshDerivedStateAfterTeamMgmtWrite({
+                    relPaths: [rel],
+                    trigger: 'team_mgmt_file_range_edit',
+                });
+            }
             return output;
         }
         catch (err) {
@@ -2133,19 +2186,27 @@ exports.teamMgmtPrepareFileRangeEditTool = {
         }
     },
 };
-exports.teamMgmtApplyFileModificationTool = {
+exports.teamMgmtPrepareOccurrenceReplaceTool = {
     type: 'func',
-    name: 'team_mgmt_apply_file_modification',
-    description: `Apply a previously planned file modification under ${MINDS_DIR}/ by hunk id.`,
+    name: 'team_mgmt_prepare_occurrence_replace',
+    description: `Prepare a literal occurrence replacement plan under ${MINDS_DIR}/. Designed for batch same-literal replacement; direct file tools are usually clearer for single-block edits.`,
     descriptionI18n: {
-        en: `Apply a previously planned file modification under ${MINDS_DIR}/ by hunk id.`,
-        zh: `按 hunk id 应用之前规划的 ${MINDS_DIR}/ 下的单文件修改。`,
+        en: `Prepare a literal occurrence replacement plan under ${MINDS_DIR}/. Designed for batch same-literal replacement; direct file tools are usually clearer for single-block edits.`,
+        zh: `规划 ${MINDS_DIR}/ 下文件内的字面量 occurrence 替换。主要面向同一字面量的批量替换；单块编辑通常使用 direct file 工具更清晰。`,
     },
     parameters: {
         type: 'object',
         additionalProperties: false,
-        required: ['hunk_id'],
-        properties: { hunk_id: { type: 'string' } },
+        required: ['path', 'find'],
+        properties: {
+            path: { type: 'string' },
+            find: { type: 'string' },
+            content: { type: 'string' },
+            pad_id: { type: 'string' },
+            pad_range: { type: 'string' },
+            occurrence_indexes: { type: 'array', items: { type: 'integer' } },
+            show_diff: { type: 'boolean' },
+        },
     },
     argsValidation: 'dominds',
     async call(dlg, caller, args) {
@@ -2156,21 +2217,118 @@ exports.teamMgmtApplyFileModificationTool = {
                 throw new Error(`${MINDS_DIR} exists but is not a directory: ${mindsState.abs}`);
             }
             await ensureMindsRootDirExists();
-            const hunkIdValue = args['hunk_id'];
-            const id = typeof hunkIdValue === 'string' ? hunkIdValue.trim() : '';
-            if (!id)
-                throw new Error('Hunk id required (e.g. a1b2c3d4)');
+            const pathValue = args['path'];
+            const findValue = args['find'];
+            const rawPath = typeof pathValue === 'string' ? pathValue.trim() : '';
+            const findText = typeof findValue === 'string' ? findValue : '';
+            if (!rawPath)
+                throw new Error('Path required');
+            if (!findText)
+                throw new Error('find is required');
+            const contentValue = args['content'];
+            if (contentValue !== undefined && typeof contentValue !== 'string') {
+                throw new Error('Invalid content (expected string)');
+            }
+            const padIdValue = args['pad_id'];
+            if (padIdValue !== undefined && typeof padIdValue !== 'string') {
+                throw new Error('Invalid pad_id (expected string)');
+            }
+            const padRangeValue = args['pad_range'];
+            if (padRangeValue !== undefined && typeof padRangeValue !== 'string') {
+                throw new Error('Invalid pad_range (expected string)');
+            }
+            const occurrenceIndexesValue = args['occurrence_indexes'];
+            if (occurrenceIndexesValue !== undefined) {
+                if (!Array.isArray(occurrenceIndexesValue)) {
+                    throw new Error('Invalid occurrence_indexes (expected array of positive integers)');
+                }
+                const occurrenceIndexItems = occurrenceIndexesValue;
+                for (const item of occurrenceIndexItems) {
+                    if (typeof item !== 'number' || !Number.isInteger(item) || item <= 0) {
+                        throw new Error('Invalid occurrence_indexes (expected array of positive integers)');
+                    }
+                }
+            }
+            const showDiffValue = args['show_diff'];
+            if (showDiffValue !== undefined && typeof showDiffValue !== 'boolean') {
+                throw new Error('Invalid show_diff (expected boolean)');
+            }
+            const rel = toMindsRelativePath(rawPath);
+            ensureMindsScopedPath(rel);
+            const proxyCaller = makeMindsOnlyAccessMember(caller);
+            return await txt_1.prepareOccurrenceReplaceTool.call(dlg, proxyCaller, {
+                path: rel,
+                find: findText,
+                ...(contentValue !== undefined ? { content: contentValue } : {}),
+                ...(padIdValue !== undefined ? { pad_id: padIdValue } : {}),
+                ...(padRangeValue !== undefined ? { pad_range: padRangeValue } : {}),
+                ...(occurrenceIndexesValue !== undefined
+                    ? { occurrence_indexes: occurrenceIndexesValue }
+                    : {}),
+                ...(showDiffValue !== undefined ? { show_diff: showDiffValue } : {}),
+            });
+        }
+        catch (err) {
+            const msg = language === 'zh'
+                ? `错误：${err instanceof Error ? err.message : String(err)}`
+                : `Error: ${err instanceof Error ? err.message : String(err)}`;
+            return fail(msg, [{ type: 'environment_msg', role: 'user', content: msg }]);
+        }
+    },
+};
+exports.teamMgmtApplyOccurrenceReplaceTool = {
+    type: 'func',
+    name: 'team_mgmt_apply_occurrence_replace',
+    description: `Apply a prepared literal occurrence replacement plan under ${MINDS_DIR}/.`,
+    descriptionI18n: {
+        en: `Apply a prepared literal occurrence replacement plan under ${MINDS_DIR}/.`,
+        zh: `应用 ${MINDS_DIR}/ 下文件的字面量 occurrence 替换 plan。`,
+    },
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['plan_id'],
+        properties: {
+            plan_id: { type: 'string' },
+            show_diff: { type: 'boolean' },
+        },
+    },
+    argsValidation: 'dominds',
+    async call(dlg, caller, args) {
+        const language = getUserLang(dlg);
+        try {
+            const mindsState = await getMindsDirState();
+            if (mindsState.kind === 'not_directory') {
+                throw new Error(`${MINDS_DIR} exists but is not a directory: ${mindsState.abs}`);
+            }
+            await ensureMindsRootDirExists();
+            const planIdValue = args['plan_id'];
+            const planId = typeof planIdValue === 'string' ? planIdValue.trim() : '';
+            if (!planId)
+                throw new Error('plan_id required');
+            const showDiffValue = args['show_diff'];
+            if (showDiffValue !== undefined && typeof showDiffValue !== 'boolean') {
+                throw new Error('Invalid show_diff (expected boolean)');
+            }
             const proxyCaller = makeMindsOnlyAccessMember(caller);
-            const output = await txt_1.applyFileModificationTool.call(dlg, proxyCaller, { hunk_id: id });
+            const output = await txt_1.applyOccurrenceReplaceTool.call(dlg, proxyCaller, {
+                plan_id: planId,
+                ...(showDiffValue !== undefined ? { show_diff: showDiffValue } : {}),
+            });
             const content = toolCallOutputToString(output);
-            if (isSuccessfulYamlToolResult(content, 'apply_file_modification')) {
-                const relPath = extractPathFromYamlToolOutput(content);
-                if (relPath) {
-                    await refreshDerivedStateAfterTeamMgmtWrite({
-                        relPaths: [relPath],
-                        trigger: 'team_mgmt_apply_file_modification',
+            if (isSuccessfulYamlToolResult(content, 'apply_occurrence_replace')) {
+                const outputRel = extractPathFromYamlToolOutput(content);
+                if (outputRel === null) {
+                    log.warn('Missing path in successful team_mgmt occurrence replace output', {
+                        trigger: 'team_mgmt_apply_occurrence_replace',
+                        planId,
                     });
                 }
+                const rel = outputRel ?? MINDS_DIR;
+                await refreshDerivedStateAfterTeamMgmtWrite({
+                    relPaths: [rel],
+                    trigger: 'team_mgmt_apply_occurrence_replace',
+                });
             }
             return output;
         }
@@ -3479,7 +3637,7 @@ function renderTeamManual(language) {
                 '想快速查看有哪些 provider / models / model_param_options：用 `team_mgmt_list_providers({})` 和 `team_mgmt_list_models({ provider_pattern: \"*\", model_pattern: \"*\" })`。',
                 '不要把内置成员（例如 `fuxi` / `pangu`）的定义写入 `.minds/team.yaml`（这里只定义 rtws（运行时工作区）自己的成员）：内置成员通常带有特殊权限/目录访问边界；重复定义可能引入冲突、权限误配或行为不一致。',
                 '`hidden: true` 表示影子/隐藏成员：不会出现在系统提示的团队目录里，但仍然可以通过 tellask-special 函数诉请。',
-                '修改文件推荐流程：先 `team_mgmt_read_file({ path: \"team.yaml\", range: \"<start~end>\", max_lines: 0, show_linenos: true })` 定位行号；小改动用 `team_mgmt_prepare_file_range_edit({ path: \"team.yaml\", range: \"<line~range>\", existing_hunk_id: \"\", content: \"<new content>\" })` 生成 diff（工具会返回 hunk_id），再用 `team_mgmt_apply_file_modification({ hunk_id: \"<hunk_id>\" })` 显式确认写入。注意：prepare 只生成内存中的预览，apply 之前不会落盘；此时再次读取文件仍只能读到旧内容。若只是修订同一个尚未落盘的预览，可再次调用 `team_mgmt_prepare_file_range_edit({ path: \"team.yaml\", range: \"<line~range>\", existing_hunk_id: \"<hunk_id>\", content: \"<new content>\" })` 覆写；若想基于这次改动继续追加下一笔修改，必须先 apply 当前 hunk，再重新 read/prepare 新的改动。如确实需要整文件覆盖：先 `team_mgmt_read_file({ path: \"team.yaml\", range: \"\", max_lines: 0, show_linenos: true })` 从 YAML header 获取 total_lines/size_bytes，再用 `team_mgmt_overwrite_entire_file({ path: \"team.yaml\", known_old_total_lines: <n>, known_old_total_bytes: <n>, content_format: \"\", content: \"...\" })`。',
+                '修改文件推荐流程：先 `team_mgmt_read_file({ path: \"team.yaml\", range: \"<start~end>\", max_lines: 0, show_linenos: true })` 定位行号；精确行号范围改动直接用 `team_mgmt_file_range_edit({ path: \"team.yaml\", range: \"<line~range>\", content: \"<new content>\" })` 写入。同一字面量多点批量替换推荐使用 `team_mgmt_prepare_occurrence_replace({ path: \"team.yaml\", find: \"<old>\", content: \"<new>\" })` 后接 `team_mgmt_apply_occurrence_replace({ plan_id: \"<plan_id>\" })`；若只选中单个 occurrence，工具会成功生成 plan 但返回 `notice: NOT_MULTI_OCCURRENCE`，此时通常改用 `team_mgmt_file_range_edit` 或 `team_mgmt_file_block_replace` 更清晰。若需要先审阅差异，可加 `preview: true, show_diff: true` 做只读预览，确认后再去掉 `preview` 写入。如确实需要整文件覆盖：先 `team_mgmt_read_file({ path: \"team.yaml\", range: \"\", max_lines: 0, show_linenos: true })` 从 YAML header 获取 total_lines/size_bytes，再用 `team_mgmt_overwrite_entire_file({ path: \"team.yaml\", known_old_total_lines: <n>, known_old_total_bytes: <n>, content_format: \"\", content: \"...\" })`；大正文优先把内容准备到 pad，再传 `pad_id/pad_range`。',
                 '部署/组织建议（可选）：如果你不希望出现显在“团队管理者”，可由一个影子/隐藏成员持有 `team_mgmt` 负责维护 `.minds/**`（尤其 `team.yaml`），由人类在需要时触发其执行（例如初始化/调整权限/更新模型）。Dominds 不强制这种组织方式；你也可以让显在成员拥有 `team_mgmt` 或由人类直接维护文件。',
             ]) +
             fmtSubHeader('Schema Snapshot（自动生成，来自当前解析器白名单）') +
@@ -3543,7 +3701,7 @@ function renderTeamManual(language) {
             'Deployment/org suggestion (optional): if you do not want a visible team manager, keep `team_mgmt` only on a hidden/shadow member and have a human trigger it when needed; Dominds does not require this organizational setup.',
             'If a member is assigned team-management responsibility (especially by granting `team_mgmt`), that member’s `persona.*.md` must explicitly require reading the relevant `man({ "toolsetId": "team_mgmt" })` chapters before any team-management action, and maintaining `.minds/**` team mind assets by handbook-standard workflow rather than improvising ad hoc edits.',
             'Role ownership is not write permission: even if `.minds/team/<id>/*` belongs to a member role, editing it still depends on whether the current actor holds `team_mgmt` or equivalent team-asset maintenance authority. “This is your own persona/knowhow/pitfalls” does not mean “you may rewrite it yourself”.',
-            'Recommended editing workflow: use `team_mgmt_read_file({ path: \"team.yaml\", range: \"<start~end>\", max_lines: 0, show_linenos: true })` to find line numbers; for small edits, run `team_mgmt_prepare_file_range_edit({ path: \"team.yaml\", range: \"<line~range>\", existing_hunk_id: \"\", content: \"<new content>\" })` to get a diff (the tool returns hunk_id), then confirm with `team_mgmt_apply_file_modification({ hunk_id: \"<hunk_id>\" })`. Important: prepare only creates an in-memory preview and does not persist anything before apply, so re-reading the file at this point still returns the old content. If you only want to revise the same not-yet-persisted preview, call `team_mgmt_prepare_file_range_edit({ path: \"team.yaml\", range: \"<line~range>\", existing_hunk_id: \"<hunk_id>\", content: \"<new content>\" })` again; if you want a further edit based on this change, you must apply the current hunk first, then read/prepare the next change. If you truly need a full overwrite: first `team_mgmt_read_file({ path: \"team.yaml\", range: \"\", max_lines: 0, show_linenos: true })` and read total_lines/size_bytes from the YAML header, then use `team_mgmt_overwrite_entire_file({ path: \"team.yaml\", known_old_total_lines: <n>, known_old_total_bytes: <n>, content_format: \"\", content: \"...\" })`.',
+            'Recommended editing workflow: use `team_mgmt_read_file({ path: \"team.yaml\", range: \"<start~end>\", max_lines: 0, show_linenos: true })` to find line numbers; for precise line-range edits, run `team_mgmt_file_range_edit({ path: \"team.yaml\", range: \"<line~range>\", content: \"<new content>\" })` directly. For multi-point replacement of the same literal, prefer `team_mgmt_prepare_occurrence_replace({ path: \"team.yaml\", find: \"<old>\", content: \"<new>\" })` followed by `team_mgmt_apply_occurrence_replace({ plan_id: \"<plan_id>\" })`; if only one occurrence is selected, the tool still creates a plan but returns `notice: NOT_MULTI_OCCURRENCE`, and `team_mgmt_file_range_edit` or `team_mgmt_file_block_replace` is usually clearer. If you need to review the diff first, pass `preview: true, show_diff: true`, then remove `preview` to write. If you truly need a full overwrite: first `team_mgmt_read_file({ path: \"team.yaml\", range: \"\", max_lines: 0, show_linenos: true })` and read total_lines/size_bytes from the YAML header, then use `team_mgmt_overwrite_entire_file({ path: \"team.yaml\", known_old_total_lines: <n>, known_old_total_bytes: <n>, content_format: \"\", content: \"...\" })`; for large bodies, prepare a pad first and pass `pad_id/pad_range`.',
         ])) +
         fmtSubHeader('Schema Snapshot (generated from parser allow-list)') +
         fmtList([
@@ -4985,12 +5143,13 @@ exports.teamMgmtTools = [
     exports.teamMgmtReadFileTool,
     exports.teamMgmtCreateNewFileTool,
     exports.teamMgmtOverwriteEntireFileTool,
-    exports.teamMgmtPrepareFileAppendTool,
-    exports.teamMgmtPrepareInsertAfterTool,
-    exports.teamMgmtPrepareInsertBeforeTool,
-    exports.teamMgmtPrepareBlockReplaceTool,
-    exports.teamMgmtPrepareFileRangeEditTool,
-    exports.teamMgmtApplyFileModificationTool,
+    exports.teamMgmtFileAppendTool,
+    exports.teamMgmtFileInsertAfterTool,
+    exports.teamMgmtFileInsertBeforeTool,
+    exports.teamMgmtFileBlockReplaceTool,
+    exports.teamMgmtFileRangeEditTool,
+    exports.teamMgmtPrepareOccurrenceReplaceTool,
+    exports.teamMgmtApplyOccurrenceReplaceTool,
     exports.teamMgmtMkDirTool,
     exports.teamMgmtMoveFileTool,
     exports.teamMgmtMoveDirTool,