@jagilber-org/index-server 1.22.1 → 1.26.1

package/dist/services/handlers/instructions.query.js

@@ -294,31 +294,6 @@ exports.instructionActions = {
             items = items.filter(e => e.title.toLowerCase().includes(text) || e.body.toLowerCase().includes(text) || (e.semanticSummary || '').toLowerCase().includes(text));
             pushStage('text');
         }
-        try {
-            const recent = st._recentAdds;
-            if (recent) {
-                const now = Date.now();
-                const GRACE = 300;
-                for (const [id, meta] of Object.entries(recent)) {
-                    if (now - meta.ts > GRACE)
-                        continue;
-                    if (items.some(e => e.id === id))
-                        continue;
-                    const catMatchAll = !catsAll.length || catsAll.every(c => meta.categories.includes(c));
-                    const catMatchAny = !catsAny.length || meta.categories.some(c => catsAny.includes(c));
-                    const catExcluded = catsEx.length && meta.categories.some(c => catsEx.includes(c));
-                    if (catMatchAll && catMatchAny && !catExcluded) {
-                        const injected = st.byId.get(id);
-                        if (injected) {
-                            items = items.concat([injected]);
-                            if ((0, instructions_shared_1.traceVisibility)())
-                                (0, tracing_1.emitTrace)('[trace:query:recent-add-injected]', { id, graceMs: now - meta.ts });
-                        }
-                    }
-                }
-            }
-        }
-        catch { /* ignore fallback */ }
         const total = items.length;
         const limit = Math.min(Math.max((p.limit ?? 100), 1), 1000);
         const offset = Math.max((p.offset ?? 0), 0);
@@ -377,8 +352,22 @@ exports.instructionActions = {
         return { error: 'missing id' };
     const st = (0, indexContext_1.ensureLoaded)();
     const entry = st.byId.get(id);
-    if (!entry)
+    if (!entry) {
+        // Check if the file exists on disk but was skipped during load (#208)
+        const dir = (0, indexContext_1.getInstructionsDir)();
+        const filePath = path_1.default.join(dir, `${id}.json`);
+        const fileExists = fs_1.default.existsSync(filePath);
+        if (fileExists) {
+            // File exists but wasn't loaded — check loadErrors for the reason
+            const loadError = st.loadErrors?.find(e => {
+                const fileName = path_1.default.basename(e.file);
+                return e.file === `${id}.json` || fileName === `${id}.json` || e.file.endsWith(`${path_1.default.sep}${id}.json`);
+            });
+            const skipReason = loadError?.error || 'unknown (file exists but was not loaded)';
+            return { id, exists: false, fileMissing: false, skipped: true, skipReason };
+        }
         return { id, exists: false, fileMissing: true };
+    }
     let schemaErrors;
     let classificationIssues;
     let normalized;
@@ -438,9 +427,11 @@ exports.instructionActions = {
     catch {
         recursionRisk = effectiveGovernanceLike === 0 ? 'none' : (leakageRatio < 0.01 ? 'warning' : 'critical');
     }
+    // #131: surface invariant-repair summary so operators can detect silent reconstruction
+    const invariantRepairs = (0, indexContext_1.getInvariantRepairSummary)();
     const snapshot = path_1.default.join(process.cwd(), 'snapshots', 'canonical-instructions.json');
     if (!fs_1.default.existsSync(snapshot))
-        return { snapshot: 'missing', hash: st.hash, count: st.list.length, governanceHash, recursionRisk, leakage: { governanceLike, keywordHit, leakageRatio }, summary };
+        return { snapshot: 'missing', hash: st.hash, count: st.list.length, governanceHash, recursionRisk, leakage: { governanceLike, keywordHit, leakageRatio }, summary, invariantRepairs };
     try {
         const raw = JSON.parse(fs_1.default.readFileSync(snapshot, 'utf8'));
         const snapItems = raw.items || [];
@@ -455,10 +446,10 @@ exports.instructionActions = {
                 changed.push(e.id);
         }
         const extra = snapItems.filter(i => !st.byId.has(i.id)).map(i => i.id);
-        return { snapshot: 'present', hash: st.hash, count: st.list.length, missing, changed, extra, drift: missing.length + changed.length + extra.length, governanceHash, recursionRisk, leakage: { governanceLike, keywordHit, leakageRatio }, summary };
+        return { snapshot: 'present', hash: st.hash, count: st.list.length, missing, changed, extra, drift: missing.length + changed.length + extra.length, governanceHash, recursionRisk, leakage: { governanceLike, keywordHit, leakageRatio }, summary, invariantRepairs };
     }
     catch (e) {
-        return { snapshot: 'error', error: e instanceof Error ? e.message : String(e), hash: st.hash, governanceHash, recursionRisk, leakage: { governanceLike, keywordHit, leakageRatio }, summary };
+        return { snapshot: 'error', error: e instanceof Error ? e.message : String(e), hash: st.hash, governanceHash, recursionRisk, leakage: { governanceLike, keywordHit, leakageRatio }, summary, invariantRepairs };
     }
 });
 (0, registry_1.registerHandler)('index_debug', () => {

package/dist/services/handlers/instructions.shared.d.ts

@@ -29,4 +29,58 @@ export declare function guard<TParams, TResult>(name: string, fn: (p: TParams) =
 export declare function traceVisibility(): boolean;
 export declare function traceInstructionVisibility(id: string, phase: string, extra?: Record<string, unknown>): void;
 export declare function traceEnvSnapshot(phase: string, extra?: Record<string, unknown>): void;
+/** Returns true if the category string is considered junk (numeric prefix, single char, case-ticket ID). */
+export declare function isJunkCategory(cat: string): boolean;
+/** Normalize a categories array: deduplicate, lowercase, remove junk, remove plural duplicates, sort. */
+export declare function normalizeCategories(cats: unknown[]): string[];
+/** Compute SHA-256 hash of an instruction body. */
+export declare function computeSourceHash(body: string): string;
+/** Bump a semver version string. Returns the new version string. */
+export declare function bumpVersion(currentVersion: string | undefined, bump: 'patch' | 'minor' | 'major'): string;
+/** Create a changelog entry object for an instruction version change. */
+export declare function createChangeLogEntry(version: string, summary: string): {
+    version: string;
+    changedAt: string;
+    summary: string;
+};
+/**
+ * Normalize categories supplied as input to add/import handlers:
+ * filter to non-empty strings, lowercase, deduplicate, and sort.
+ *
+ * Distinct from {@link normalizeCategories} (used by groom), which also
+ * strips junk patterns and plural duplicates.
+ */
+export declare function normalizeInputCategories(cats: unknown): string[];
+type ChangeLogArr = NonNullable<InstructionEntry['changeLog']>;
+export interface RepairChangeLogOptions {
+    /** Final/expected version that the last entry must end with. */
+    finalVersion: string;
+    /** ISO timestamp to use as `now`. */
+    now: string;
+    /** Fallback entry pushed when the supplied changeLog is empty/invalid. */
+    fallback: {
+        version: string;
+        changedAt: string;
+        summary: string;
+    };
+    /** Summary to use when appending a trailing entry to reach finalVersion. */
+    trailingSummary: string;
+}
+/**
+ * Repair a changelog array: drop malformed entries, ensure non-empty,
+ * and ensure the last entry's version matches `finalVersion`.
+ *
+ * Used by the overwrite/merge and new-entry paths in `index_add` plus any
+ * other handler that needs to normalize a user-supplied changeLog.
+ */
+export declare function repairChangeLog(cl: unknown, options: RepairChangeLogOptions): ChangeLogArr;
+/** Governance keys merged from input into the entry by `index_add`. */
+export declare const ADD_GOVERNANCE_KEYS: readonly (keyof ImportEntry)[];
+/** Governance keys merged from input into the entry by `index_import`.
+ * Differs from {@link ADD_GOVERNANCE_KEYS} by also including `changeLog`,
+ * since import accepts changeLog directly without invoking repair logic.
+ */
+export declare const IMPORT_GOVERNANCE_KEYS: readonly (keyof ImportEntry)[];
+/** Copy defined governance fields from `source` into `target` for the given keys. */
+export declare function applyGovernanceKeys(target: InstructionEntry, source: ImportEntry, keys: readonly (keyof ImportEntry)[]): void;
 export {};

package/dist/services/handlers/instructions.shared.js

@@ -1,5 +1,9 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMPORT_GOVERNANCE_KEYS = exports.ADD_GOVERNANCE_KEYS = void 0;
 exports.isMutationEnabled = isMutationEnabled;
 exports.isCI = isCI;
 exports.limitResponseSize = limitResponseSize;
@@ -7,6 +11,16 @@ exports.guard = guard;
 exports.traceVisibility = traceVisibility;
 exports.traceInstructionVisibility = traceInstructionVisibility;
 exports.traceEnvSnapshot = traceEnvSnapshot;
+exports.isJunkCategory = isJunkCategory;
+exports.normalizeCategories = normalizeCategories;
+exports.computeSourceHash = computeSourceHash;
+exports.bumpVersion = bumpVersion;
+exports.createChangeLogEntry = createChangeLogEntry;
+exports.normalizeInputCategories = normalizeInputCategories;
+exports.repairChangeLog = repairChangeLog;
+exports.applyGovernanceKeys = applyGovernanceKeys;
+// Shared utilities used across instruction handler submodules.
+const crypto_1 = __importDefault(require("crypto"));
 const indexContext_1 = require("../indexContext");
 const runtimeConfig_1 = require("../../config/runtimeConfig");
 const tracing_1 = require("../tracing");
@@ -38,7 +52,7 @@ function guard(name, fn) {
     return (p) => {
         const viaDispatcher = !!(p && typeof p === 'object' && p._viaDispatcher);
         if (!isMutationEnabled() && !viaDispatcher) {
-            throw { code: -32601, message: `Mutation disabled. Use index_dispatch with action parameter instead of direct ${name} calls. Set INDEX_SERVER_MUTATION=1 to enable direct calls.`, data: { method: name, alternative: 'index_dispatch', reason: 'mutation_disabled' } };
+            throw { code: -32601, message: `Direct mutation calls are disabled by the current runtime override. Use index_dispatch with an action parameter instead of direct ${name} calls, or remove INDEX_SERVER_MUTATION=0 to re-enable direct calls.`, data: { method: name, alternative: 'index_dispatch', reason: 'mutation_disabled' } };
         }
         return fn(p);
     };
@@ -89,3 +103,114 @@ function traceEnvSnapshot(phase, extra) {
     }
     catch { /* ignore env tracing errors */ }
 }
+// ── Shared category normalization (#135) ──────────────────────────
+// Extracted from groom handler to eliminate duplication across groom/normalize/repair.
+/** Returns true if the category string is considered junk (numeric prefix, single char, case-ticket ID). */
+function isJunkCategory(cat) {
+    return /^\d/.test(cat) || cat.length <= 1 || /^case-\d{6,}$/.test(cat);
+}
+/** Normalize a categories array: deduplicate, lowercase, remove junk, remove plural duplicates, sort. */
+function normalizeCategories(cats) {
+    let normCats = Array.from(new Set((cats || []).filter(c => typeof c === 'string').map(c => c.toLowerCase())));
+    normCats = normCats.filter(c => !isJunkCategory(c));
+    normCats = normCats.filter(cat => !(cat.endsWith('s') && normCats.includes(cat.slice(0, -1))));
+    return normCats.sort();
+}
+// ── Shared source hash computation (#135) ─────────────────────────
+/** Compute SHA-256 hash of an instruction body. */
+function computeSourceHash(body) {
+    return crypto_1.default.createHash('sha256').update(body, 'utf8').digest('hex');
+}
+// ── Shared version bump logic (#135) ──────────────────────────────
+/** Bump a semver version string. Returns the new version string. */
+function bumpVersion(currentVersion, bump) {
+    const parts = (currentVersion || '1.0.0').split('.').map(n => parseInt(n || '0', 10));
+    while (parts.length < 3)
+        parts.push(0);
+    if (bump === 'major') {
+        parts[0]++;
+        parts[1] = 0;
+        parts[2] = 0;
+    }
+    else if (bump === 'minor') {
+        parts[1]++;
+        parts[2] = 0;
+    }
+    else if (bump === 'patch') {
+        parts[2]++;
+    }
+    return parts.join('.');
+}
+// ── Shared changelog entry creation (#135) ────────────────────────
+/** Create a changelog entry object for an instruction version change. */
+function createChangeLogEntry(version, summary) {
+    return { version, changedAt: new Date().toISOString(), summary };
+}
+// ── Shared input-side category normalization (#135) ──────────────
+/**
+ * Normalize categories supplied as input to add/import handlers:
+ * filter to non-empty strings, lowercase, deduplicate, and sort.
+ *
+ * Distinct from {@link normalizeCategories} (used by groom), which also
+ * strips junk patterns and plural duplicates.
+ */
+function normalizeInputCategories(cats) {
+    const arr = Array.isArray(cats) ? cats : [];
+    return Array.from(new Set(arr
+        .filter((c) => typeof c === 'string' && c.trim().length > 0)
+        .map(c => c.toLowerCase()))).sort();
+}
+/**
+ * Repair a changelog array: drop malformed entries, ensure non-empty,
+ * and ensure the last entry's version matches `finalVersion`.
+ *
+ * Used by the overwrite/merge and new-entry paths in `index_add` plus any
+ * other handler that needs to normalize a user-supplied changeLog.
+ */
+function repairChangeLog(cl, options) {
+    const out = [];
+    if (Array.isArray(cl)) {
+        for (const entry of cl) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const { version: v, changedAt: ca, summary: sum } = entry;
+            if (typeof v === 'string' && v.trim() && typeof sum === 'string' && sum.trim()) {
+                const caIso = typeof ca === 'string' && /T/.test(ca) ? ca : options.now;
+                out.push({ version: v.trim(), changedAt: caIso, summary: sum.trim() });
+            }
+        }
+    }
+    if (!out.length) {
+        out.push({ ...options.fallback });
+    }
+    const lastVer = out[out.length - 1].version;
+    if (lastVer !== options.finalVersion) {
+        out.push({ version: options.finalVersion, changedAt: options.now, summary: options.trailingSummary });
+    }
+    return out;
+}
+// ── Shared governance key merge (#135) ────────────────────────────
+/** Governance keys merged from input into the entry by `index_add`. */
+exports.ADD_GOVERNANCE_KEYS = [
+    'version', 'owner', 'status', 'priorityTier', 'classification',
+    'lastReviewedAt', 'nextReviewDue', 'semanticSummary', 'contentType', 'extensions'
+];
+/** Governance keys merged from input into the entry by `index_import`.
+ * Differs from {@link ADD_GOVERNANCE_KEYS} by also including `changeLog`,
+ * since import accepts changeLog directly without invoking repair logic.
+ */
+exports.IMPORT_GOVERNANCE_KEYS = [
+    'version', 'owner', 'status', 'priorityTier', 'classification',
+    'lastReviewedAt', 'nextReviewDue', 'changeLog', 'semanticSummary',
+    'contentType', 'extensions'
+];
+/** Copy defined governance fields from `source` into `target` for the given keys. */
+function applyGovernanceKeys(target, source, keys) {
+    const t = target;
+    for (const k of keys) {
+        const v = source[k];
+        if (v !== undefined) {
+            t[k] = v;
+        }
+    }
+}

package/dist/services/handlers.activation.js

@@ -13,89 +13,91 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Created: 2026-02-01 (in response to repeated multi-session activation pain)
  */
 const registry_1 = require("../server/registry");
+const envUtils_1 = require("../utils/envUtils");
 const ACTIVATION_GUIDE_VERSION = '1.0.0';
 (0, registry_1.registerHandler)('meta_activation_guide', () => {
+    const diagnosticsEnabled = (0, envUtils_1.dangerousDiagnosticsEnabled)();
+    const categories = {
+        instructionManagement: {
+            function: 'activate_instruction_management_and_operations_tools()',
+            description: 'Core instruction index operations: add, search, dispatch, remove, repair, import, normalize, reload',
+            tools: [
+                'index_add',
+                'index_dispatch',
+                'index_search',
+                'index_remove',
+                'index_repair',
+                'index_import',
+                'index_health',
+                'index_normalize',
+                'index_reload',
+                'usage_track',
+                'usage_hotset',
+                'manifest_refresh'
+            ],
+            toolCount: 12
+        },
+        graphAndSchema: {
+            function: 'activate_instruction_graph_and_schema_tools()',
+            description: 'Instruction graph export and JSON schema retrieval',
+            tools: ['graph_export', 'index_schema'],
+            toolCount: 2
+        },
+        governance: {
+            function: 'activate_governance_management_tools()',
+            description: 'Governance operations: enrich placeholder fields, compute/update governance hash',
+            tools: [
+                'index_enrich',
+                'index_governanceHash',
+                'index_governanceUpdate'
+            ],
+            toolCount: 3
+        },
+        manifest: {
+            function: 'activate_manifest_management_tools()',
+            description: 'index manifest repair and status checks',
+            tools: ['manifest_repair', 'manifest_status'],
+            toolCount: 2
+        },
+        bootstrap: {
+            function: 'activate_bootstrap_management_tools()',
+            description: 'Bootstrap confirmation and finalization for guarded mutations',
+            tools: [
+                'bootstrap_request',
+                'bootstrap_confirmFinalize',
+                'bootstrap_status'
+            ],
+            toolCount: 3
+        },
+        health: {
+            function: 'activate_feedback_and_health_monitoring_tools()',
+            description: 'Feedback submission and system health monitoring',
+            tools: [
+                'feedback_submit',
+                'health_check'
+            ],
+            toolCount: 2
+        }
+    };
+    if (diagnosticsEnabled) {
+        categories.diagnostics = {
+            function: 'activate_diagnostic_stress_testing_tools()',
+            description: 'CPU/memory/microtask stress testing for performance analysis',
+            tools: [
+                'diagnostics_block',
+                'diagnostics_memoryPressure',
+                'diagnostics_microtaskFlood'
+            ],
+            toolCount: 3
+        };
+    }
     return {
         version: ACTIVATION_GUIDE_VERSION,
         generatedAt: new Date().toISOString(),
         problem: 'Index Server tools show as "disabled by the user" in VSCode even when properly configured in settings.json (chat.mcp.tools)',
         rootCause: 'Settings.json configuration provides permission framework but does NOT trigger actual tool enablement. Activation functions must be called explicitly.',
         solution: 'Call VSCode activation functions to enable tool categories. These functions are VSCode client-side features that must be invoked before using MCP tools.',
-        categories: {
-            instructionManagement: {
-                function: 'activate_instruction_management_and_operations_tools()',
-                description: 'Core instruction index operations: add, search, dispatch, remove, repair, import, normalize, reload',
-                tools: [
-                    'index_add',
-                    'index_dispatch',
-                    'index_search',
-                    'index_remove',
-                    'index_repair',
-                    'index_import',
-                    'index_health',
-                    'index_normalize',
-                    'index_reload',
-                    'usage_track',
-                    'usage_hotset',
-                    'manifest_refresh'
-                ],
-                toolCount: 12
-            },
-            graphAndSchema: {
-                function: 'activate_instruction_graph_and_schema_tools()',
-                description: 'Instruction graph export and JSON schema retrieval',
-                tools: ['graph_export', 'index_schema'],
-                toolCount: 2
-            },
-            governance: {
-                function: 'activate_governance_management_tools()',
-                description: 'Governance operations: enrich placeholder fields, compute/update governance hash',
-                tools: [
-                    'index_enrich',
-                    'index_governanceHash',
-                    'index_governanceUpdate'
-                ],
-                toolCount: 3
-            },
-            manifest: {
-                function: 'activate_manifest_management_tools()',
-                description: 'index manifest repair and status checks',
-                tools: ['manifest_repair', 'manifest_status'],
-                toolCount: 2
-            },
-            bootstrap: {
-                function: 'activate_bootstrap_management_tools()',
-                description: 'Bootstrap confirmation and finalization for guarded mutations',
-                tools: [
-                    'bootstrap_request',
-                    'bootstrap_confirmFinalize',
-                    'bootstrap_status'
-                ],
-                toolCount: 3
-            },
-            diagnostics: {
-                function: 'activate_diagnostic_stress_testing_tools()',
-                description: 'CPU/memory/microtask stress testing for performance analysis',
-                tools: [
-                    'diagnostics_block',
-                    'diagnostics_memoryPressure',
-                    'diagnostics_microtaskFlood'
-                ],
-                toolCount: 3
-            },
-            health: {
-                function: 'activate_feedback_and_health_monitoring_tools()',
-                description: 'Feedback submission and system health monitoring',
-                tools: [
-                    'feedback_submit',
-                    'feedback_list',
-                    'feedback_health',
-                    'feedback_stats',
-                    'health_check'
-                ],
-                toolCount: 5
-            }
-        },
+        categories,
         quickStart: {
             step1: 'Identify which tool you need (e.g., index_search)',
             step2: 'Find matching category in activation categories above (e.g., instructionManagement)',
@@ -145,6 +147,7 @@ const ACTIVATION_GUIDE_VERSION = '1.0.0';
         };
     }
     // Map tool names to activation categories
+    const diagnosticsEnabled = (0, envUtils_1.dangerousDiagnosticsEnabled)();
     const toolMapping = {
         'index_add': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
         'index_dispatch': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
@@ -168,15 +171,14 @@ const ACTIVATION_GUIDE_VERSION = '1.0.0';
         'bootstrap_request': { category: 'bootstrap', function: 'activate_bootstrap_management_tools' },
         'bootstrap_confirmFinalize': { category: 'bootstrap', function: 'activate_bootstrap_management_tools' },
         'bootstrap_status': { category: 'bootstrap', function: 'activate_bootstrap_management_tools' },
-        'diagnostics_block': { category: 'diagnostics', function: 'activate_diagnostic_stress_testing_tools' },
-        'diagnostics_memoryPressure': { category: 'diagnostics', function: 'activate_diagnostic_stress_testing_tools' },
-        'diagnostics_microtaskFlood': { category: 'diagnostics', function: 'activate_diagnostic_stress_testing_tools' },
         'feedback_submit': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' },
-        'feedback_list': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' },
-        'feedback_health': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' },
-        'feedback_stats': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' },
         'health_check': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' }
     };
+    if (diagnosticsEnabled) {
+        toolMapping['diagnostics_block'] = { category: 'diagnostics', function: 'activate_diagnostic_stress_testing_tools' };
+        toolMapping['diagnostics_memoryPressure'] = { category: 'diagnostics', function: 'activate_diagnostic_stress_testing_tools' };
+        toolMapping['diagnostics_microtaskFlood'] = { category: 'diagnostics', function: 'activate_diagnostic_stress_testing_tools' };
+    }
     const mapping = toolMapping[toolName];
     if (!mapping) {
         return {

package/dist/services/handlers.dashboardConfig.d.ts

@@ -7,7 +7,7 @@
  *  - Default semantics
  *  - Category (core | dashboard | instructions | manifest | tracing | diagnostics | stress | usage | validation | auth | metrics | experimental)
  *  - Description
- *  - Stability (stable | diagnostic | experimental | deprecated | reserved)
+ *  - Stability (stable | diagnostic | experimental | reserved)
  *  - Since (version first introduced when known – best effort)
  *
  * The list is curated (not discovered dynamically) to ensure ordering stability and to include flags
@@ -18,7 +18,7 @@ export interface FlagMeta {
     name: string;
     category: string;
     description: string;
-    stability: 'stable' | 'diagnostic' | 'experimental' | 'deprecated' | 'reserved';
+    stability: 'stable' | 'diagnostic' | 'experimental' | 'reserved';
     since?: string;
     default?: string;
     type?: 'boolean' | 'string' | 'number';

package/dist/services/handlers.dashboardConfig.js

@@ -8,7 +8,7 @@ const envUtils_1 = require("../utils/envUtils");
 exports.FLAG_REGISTRY = [
     // Core operation & dashboard
     { name: 'INDEX_SERVER_DIR', category: 'core', description: 'Instructions catalog directory. Defaults to ./instructions relative to CWD.', stability: 'stable', default: './instructions', type: 'string', since: '1.0.0' },
-    { name: 'INDEX_SERVER_MUTATION', category: 'core', description: 'Enable mutation tools (add/import/remove/enrich/governance updates).', stability: 'stable', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_MUTATION', category: 'core', description: 'Override mutation tools (unset or 1 = enabled, 0 = read-only).', stability: 'stable', default: 'on', type: 'boolean', since: '1.0.0' },
     { name: 'INDEX_SERVER_VERBOSE_LOGGING', category: 'core', description: 'Verbose logging (handshake, dispatch timings).', stability: 'stable', default: 'off', type: 'boolean', since: '1.0.0' },
     { name: 'INDEX_SERVER_LOG_DIAG', category: 'diagnostics', description: 'Diagnostic logging (lower-level/internal).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.0.0' },
     { name: 'INDEX_SERVER_DASHBOARD', category: 'dashboard', description: 'Enable admin dashboard HTTP server.', stability: 'stable', default: 'off', type: 'boolean', since: '1.0.0' },
@@ -72,7 +72,6 @@ exports.FLAG_REGISTRY = [
     { name: 'INDEX_SERVER_MEMORY_MONITOR', category: 'diagnostics', description: 'Enable periodic memory usage sampling/logging.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.0' },
     { name: 'INDEX_SERVER_LOG_MUTATION', category: 'diagnostics', description: 'Emit mutation-specific verbose logs.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.0' },
     // Legacy / removed (for awareness; not parsed at runtime)
-    { name: 'INDEX_SERVER_SHORTCIRCUIT', category: 'deprecated', description: 'Removed legacy short-circuit handshake path.', stability: 'deprecated', default: '(removed)', since: '<1.1.0' },
     // Multi-instance / leader-follower
     { name: 'INDEX_SERVER_MODE', category: 'multi-instance', description: 'Instance mode: standalone (default), leader, follower, auto.', stability: 'experimental', default: 'standalone', type: 'string', since: '1.8.5' },
     { name: 'INDEX_SERVER_LEADER_PORT', category: 'multi-instance', description: 'HTTP port for leader MCP transport (thin clients connect here).', stability: 'experimental', default: '9090', type: 'number', since: '1.8.5' },