@jagilber-org/index-server 1.28.9 → 1.28.19

package/dist/services/seedBootstrap.contentModel.js

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildContentModelSeed = buildContentModelSeed;
+/**
+ * Builds the canonical "content model" seed (002-content-model) from the
+ * authoritative instruction JSON schema at module-load time.
+ *
+ * Single source of truth: the schema. The body here is regenerated on every
+ * server start, so any change to the schema's `contentType.enum`, its
+ * description, the top-level `required` array, or referenced field
+ * descriptions automatically flows into the seed. A drift test
+ * (src/tests/contentModelSeed.spec.ts) enforces the wiring.
+ *
+ * Constraint (constitution A-7): generalized, public-safe, environment-agnostic.
+ */
+const instruction_schema_json_1 = __importDefault(require("../../schemas/instruction.schema.json"));
+/**
+ * Parse the `contentType` schema description for `<name> (<desc>)` fragments
+ * and filter to the canonical enum members.
+ */
+function parseContentTypeMatrix(s) {
+    const ct = s.properties.contentType;
+    if (!ct || !Array.isArray(ct.enum) || typeof ct.description !== 'string') {
+        throw new Error('content-model seed: schema is missing properties.contentType.enum or .description');
+    }
+    const enumSet = new Set(ct.enum);
+    const rows = [];
+    const seen = new Set();
+    const re = /([a-z][a-z-]*) \(([^)]+)\)/g;
+    let m;
+    while ((m = re.exec(ct.description)) !== null) {
+        const value = m[1];
+        const description = m[2].trim();
+        if (!enumSet.has(value))
+            continue;
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        rows.push({ value, description });
+    }
+    // Guarantee every enum member appears even if the description prose drifts.
+    for (const v of ct.enum) {
+        if (!seen.has(v))
+            rows.push({ value: v, description: '(no description in schema)' });
+    }
+    // Stable order: schema enum order
+    rows.sort((a, b) => ct.enum.indexOf(a.value) - ct.enum.indexOf(b.value));
+    return rows;
+}
+function fieldBullet(fieldName, s) {
+    const desc = s.properties[fieldName]?.description;
+    if (!desc) {
+        throw new Error(`content-model seed: schema property '${fieldName}' has no description`);
+    }
+    return `- \`${fieldName}\` — ${desc}`;
+}
+/**
+ * Common optional fields surfaced to agents. Order is curated for narrative
+ * flow; the *descriptions* are pulled from the schema so the seed cannot
+ * drift from `index_schema`. Adding/removing entries here is a deliberate
+ * editorial choice, but the prose is never duplicated.
+ */
+const COMMON_OPTIONAL_FIELDS = [
+    'priorityTier',
+    'semanticSummary',
+    'primaryCategory',
+    'owner',
+    'classification',
+    'version',
+    'status',
+    'reviewIntervalDays',
+    'lastReviewedAt',
+    'nextReviewDue',
+    'rationale'
+];
+function readSchemaVersion(s) {
+    const sv = s.properties.schemaVersion;
+    if (!sv || !Array.isArray(sv.enum) || sv.enum.length === 0) {
+        throw new Error('content-model seed: schema.properties.schemaVersion.enum is missing or empty');
+    }
+    // Pick the highest enum value (strings compared numerically when possible).
+    const sorted = [...sv.enum].sort((a, b) => {
+        const na = Number(a);
+        const nb = Number(b);
+        if (Number.isFinite(na) && Number.isFinite(nb))
+            return nb - na;
+        return b.localeCompare(a);
+    });
+    return sorted[0];
+}
+/**
+ * Build the canonical seed object for `002-content-model` from the schema.
+ *
+ * The function is pure: same schema input → same seed output. Tests rely on
+ * this determinism to assert drift-safety.
+ *
+ * @returns Canonical seed `{ file, id, json }` ready to push into CANONICAL_SEEDS.
+ */
+function buildContentModelSeed() {
+    const s = instruction_schema_json_1.default;
+    if (!Array.isArray(s.required) || s.required.length === 0) {
+        throw new Error('content-model seed: schema.required is missing or empty');
+    }
+    const matrix = parseContentTypeMatrix(s);
+    const requiredLines = s.required.map(f => fieldBullet(f, s)).join('\n');
+    const optionalLines = COMMON_OPTIONAL_FIELDS.map(f => fieldBullet(f, s)).join('\n');
+    const matrixRows = matrix
+        .map(r => `| \`${r.value}\` | ${r.description} |`)
+        .join('\n');
+    const schemaVersionValue = readSchemaVersion(s);
+    const body = `# Index Server Content Model
+
+Knowledge for AI agents writing or evaluating instruction entries. This document is regenerated from the canonical \`schemas/instruction.schema.json\` on every server start, so it always matches the validator the index actually runs.
+
+For the full machine-validatable schema (with current ranges, runtime limits, and the promotion-workflow checklist) call the \`index_schema\` MCP tool. Treat that tool as the validation source of truth at runtime; this seed is the conceptual knowledge guide.
+
+## Required fields
+
+Every instruction entry must include:
+
+${requiredLines}
+
+## \`contentType\` decision matrix
+
+Pick the \`contentType\` that matches what the entry is for:
+
+| Value | Use when |
+|-------|----------|
+${matrixRows}
+
+Default is \`instruction\`.
+
+## Common optional fields
+
+${optionalLines}
+
+Call \`index_schema\` for the authoritative list, validation rules, and minimal example.
+
+## Note on adjacent concepts
+
+Some agent platforms use terms such as plugin, MCP server, or connector for deployment surfaces. When documenting those surfaces in Index Server, choose the canonical \`contentType\` by purpose: external system guidance is \`integration\`, reusable context is \`knowledge\`, a callable capability is \`skill\`, and a multi-step process is \`workflow\`.
+`;
+    return {
+        file: '002-content-model.json',
+        id: '002-content-model',
+        json: {
+            id: '002-content-model',
+            title: 'Index Server Content Model & Field Reference',
+            body,
+            audience: 'all',
+            requirement: 'recommended',
+            priority: 95,
+            priorityTier: 'P1',
+            contentType: 'knowledge',
+            categories: ['bootstrap', 'content-model', 'reference', 'schema'],
+            primaryCategory: 'reference',
+            owner: 'system',
+            version: '1.0.0',
+            schemaVersion: schemaVersionValue,
+            semanticSummary: 'Knowledge for AI agents: required fields, the contentType decision matrix, and pointer to index_schema for the live JSON schema.'
+        }
+    };
+}

package/dist/services/seedBootstrap.contentTypes.d.ts

@@ -0,0 +1,5 @@
+export declare function buildContentTypesSeed(): {
+    file: string;
+    id: string;
+    json: Record<string, unknown>;
+};

package/dist/services/seedBootstrap.contentTypes.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildContentTypesSeed = buildContentTypesSeed;
+const instruction_schema_json_1 = __importDefault(require("../../schemas/instruction.schema.json"));
+function contentTypeRows(s) {
+    const ct = s.properties.contentType;
+    if (!ct || !Array.isArray(ct.enum) || typeof ct.description !== 'string') {
+        throw new Error('content-types seed: schema is missing properties.contentType.enum or .description');
+    }
+    const rows = [];
+    const seen = new Set();
+    const enumSet = new Set(ct.enum);
+    const re = /([a-z][a-z-]*) \(([^)]+)\)/g;
+    let m;
+    while ((m = re.exec(ct.description)) !== null) {
+        const value = m[1];
+        if (!enumSet.has(value) || seen.has(value))
+            continue;
+        seen.add(value);
+        rows.push({ value, description: m[2].trim() });
+    }
+    for (const value of ct.enum) {
+        if (!seen.has(value))
+            rows.push({ value, description: '(no description in schema)' });
+    }
+    rows.sort((a, b) => ct.enum.indexOf(a.value) - ct.enum.indexOf(b.value));
+    return rows;
+}
+function readSchemaVersion(s) {
+    const sv = s.properties.schemaVersion;
+    if (!sv || !Array.isArray(sv.enum) || sv.enum.length === 0) {
+        throw new Error('content-types seed: schema.properties.schemaVersion.enum is missing or empty');
+    }
+    return [...sv.enum].sort((a, b) => Number(b) - Number(a))[0];
+}
+function buildContentTypesSeed() {
+    const s = instruction_schema_json_1.default;
+    const matrixRows = contentTypeRows(s)
+        .map(r => `| \`${r.value}\` | ${r.description} |`)
+        .join('\n');
+    const body = `# Index Server Content Types
+
+This knowledge seed lists the canonical \`contentType\` taxonomy from \`schemas/instruction.schema.json\`. It is regenerated from the schema on every server start so agents see the same enum values the validator enforces.
+
+For the full machine-validatable schema, call the \`index_schema\` MCP tool.
+
+| Value | Use when |
+|-------|----------|
+${matrixRows}
+
+Default is \`instruction\`.
+`;
+    return {
+        file: '003-content-types.json',
+        id: '003-content-types',
+        json: {
+            id: '003-content-types',
+            title: 'Index Server Content Types',
+            body,
+            audience: 'all',
+            requirement: 'recommended',
+            priority: 94,
+            priorityTier: 'P1',
+            contentType: 'knowledge',
+            categories: ['bootstrap', 'content-types', 'schema'],
+            primaryCategory: 'schema',
+            owner: 'system',
+            version: '1.0.0',
+            schemaVersion: readSchemaVersion(s),
+            semanticSummary: 'Canonical Index Server contentType taxonomy generated from instruction.schema.json.',
+        },
+    };
+}

package/dist/services/seedBootstrap.d.ts

@@ -14,6 +14,7 @@ export interface SeedSummary {
     created: string[];
     existing: string[];
     skipped: string[];
+    upgraded: string[];
     disabled: boolean;
     reason?: string;
     hash: string;

package/dist/services/seedBootstrap.js

@@ -11,6 +11,8 @@ const crypto_1 = __importDefault(require("crypto"));
 const indexContext_1 = require("./indexContext");
 const logger_1 = require("./logger");
 const runtimeConfig_1 = require("../config/runtimeConfig");
+const seedBootstrap_contentModel_1 = require("./seedBootstrap.contentModel");
+const seedBootstrap_contentTypes_1 = require("./seedBootstrap.contentTypes");
 // Canonical seed instruction objects (kept intentionally minimal – DO NOT add environment specific data)
 const CANONICAL_SEEDS = [
     {
@@ -156,13 +158,15 @@ docker compose up  # HTTP on :8787
 Restart your MCP client after configuration changes. Verify with \`health_check\`.
 
 For full configuration options: see \`docs/mcp_configuration.md\` and \`docs/configuration.md\`.`,
-            audience: 'agents',
-            requirement: 'required',
+            audience: 'all',
+            requirement: 'mandatory',
             priority: 100,
+            priorityTier: 'P1',
+            contentType: 'instruction',
             categories: ['bootstrap', 'mcp-activation', 'quick-start', 'documentation'],
             owner: 'system',
-            version: 3,
-            schemaVersion: '5',
+            version: '3.0.0',
+            schemaVersion: '6',
             semanticSummary: 'Index Server quick start: search-first workflow, knowledge contribution, copilot instructions setup, and MCP client configuration for AI agents'
         }
     },
@@ -173,17 +177,26 @@ For full configuration options: see \`docs/mcp_configuration.md\` and \`docs/con
             id: '001-lifecycle-bootstrap',
             title: 'Lifecycle Bootstrap: Local-First Instruction Strategy',
             body: 'Purpose: Early lifecycle guidance after bootstrap confirmation. Keep index minimal; prefer local-first P0/P1 additions; promote only after stability.',
-            audience: 'agents',
+            audience: 'all',
             requirement: 'recommended',
-            priorityTier: 'p1',
+            priority: 99,
+            priorityTier: 'P1',
+            contentType: 'instruction',
             categories: ['bootstrap', 'lifecycle'],
             owner: 'system',
-            version: 1,
-            schemaVersion: '5',
+            version: '1.0.0',
+            schemaVersion: '6',
             semanticSummary: 'Lifecycle and promotion guardrails after bootstrap confirmation',
             reviewIntervalDays: 120
         }
-    }
+    },
+    // 002-content-model is generated from schemas/instruction.schema.json at
+    // module load. Single source of truth: any change to the schema's required
+    // fields, contentType enum, or referenced field descriptions automatically
+    // flows into the seed body. Drift is enforced by
+    // src/tests/contentModelSeed.spec.ts.
+    (0, seedBootstrap_contentModel_1.buildContentModelSeed)(),
+    (0, seedBootstrap_contentTypes_1.buildContentTypesSeed)()
 ];
 function computeCanonicalHash() {
     const canonical = CANONICAL_SEEDS.map(s => ({ id: s.id, file: s.file, json: s.json })).sort((a, b) => a.id.localeCompare(b.id));
@@ -198,7 +211,7 @@ function autoSeedBootstrap() {
     const cfg = (0, runtimeConfig_1.getRuntimeConfig)().bootstrapSeed;
     const disabled = !cfg.autoSeed;
     const dir = safeInstructionsDir();
-    const summary = { dir, created: [], existing: [], skipped: [], disabled, hash: computeCanonicalHash() };
+    const summary = { dir, created: [], existing: [], skipped: [], upgraded: [], disabled, hash: computeCanonicalHash() };
     if (disabled) {
         summary.reason = 'disabled_by_env';
         return summary;
@@ -215,10 +228,76 @@ function autoSeedBootstrap() {
     for (const seed of CANONICAL_SEEDS) {
         const target = path_1.default.join(dir, seed.file);
         const exists = fs_1.default.existsSync(target);
+        // Canonical body hash (matches the sourceHash baked at write time).
+        // Used both to bake into freshly written seeds and to detect drift
+        // against existing on-disk seeds whose generated body has changed
+        // (e.g. 002-content-model after an instruction.schema.json edit).
+        const canonicalBody = typeof seed.json.body === 'string' ? seed.json.body : '';
+        const canonicalSourceHash = crypto_1.default.createHash('sha256').update(canonicalBody, 'utf8').digest('hex');
         if (exists) {
-            summary.existing.push(seed.file);
-            summary.skipped.push(seed.file);
-            continue; // do not overwrite
+            // Detect schema-invalid stale seeds from earlier versions and rewrite
+            // them. Pre-v1.28.10 wrote `requirement: 'required'` and
+            // `priorityTier: 'p1'` (lowercase), both rejected by the current
+            // instruction.schema.json. Without this upgrade path, broken seeds
+            // persist forever because we previously never overwrote existing files.
+            // We deliberately scope the upgrade to enum violations (not arbitrary
+            // user edits) so hand-curated valid seeds are preserved. RCA 2026-05-07.
+            //
+            // Additionally: detect canonical-body drift (sourceHash mismatch)
+            // for canonical seeds. The 002-content-model seed is generated from
+            // instruction.schema.json on every server start; without this check
+            // an existing on-disk seed would silently go stale after a schema
+            // edit, violating the documented single-source-of-truth contract.
+            // RCA 2026-05-08 (PR #324 quality review).
+            let stale = false;
+            let staleReason = '';
+            try {
+                const existing = JSON.parse(fs_1.default.readFileSync(target, 'utf8'));
+                const validRequirement = ['mandatory', 'critical', 'recommended', 'optional', 'deprecated'];
+                const validPriorityTier = ['P1', 'P2', 'P3', 'P4'];
+                if (typeof existing.requirement === 'string' && !validRequirement.includes(existing.requirement)) {
+                    stale = true;
+                    staleReason = `invalid requirement="${existing.requirement}"`;
+                }
+                else if (typeof existing.priorityTier === 'string' && !validPriorityTier.includes(existing.priorityTier)) {
+                    stale = true;
+                    staleReason = `invalid priorityTier="${existing.priorityTier}"`;
+                }
+                else if (typeof existing.sourceHash === 'string' && existing.sourceHash !== canonicalSourceHash) {
+                    // sourceHash on disk no longer matches the in-code canonical body.
+                    // Refresh so canonical seeds track the current source-of-truth.
+                    stale = true;
+                    staleReason = `canonical body drift: on-disk sourceHash=${existing.sourceHash.slice(0, 12)}… expected=${canonicalSourceHash.slice(0, 12)}…`;
+                }
+                else if (typeof existing.sourceHash !== 'string') {
+                    // Pre-sourceHash legacy install: an older Index Server version
+                    // wrote canonical seeds without baking sourceHash. Without this
+                    // branch a stale legacy body would skip refresh forever, since
+                    // the hash-mismatch check above never trips. Treat absence as
+                    // drift so legacy installs converge on the current canonical
+                    // body. RCA 2026-05-08 (PR #324 reliability advisory).
+                    stale = true;
+                    staleReason = 'missing sourceHash (legacy pre-sourceHash install)';
+                }
+            }
+            catch (e) {
+                stale = true;
+                staleReason = `unparseable_json: ${(e instanceof Error) ? e.message : String(e)}`;
+            }
+            if (!stale) {
+                summary.existing.push(seed.file);
+                summary.skipped.push(seed.file);
+                continue; // valid existing seed; do not overwrite
+            }
+            try {
+                fs_1.default.unlinkSync(target);
+            }
+            catch { /* fall through to write */ }
+            try {
+                process.stderr.write(`[seed] upgrading stale seed ${seed.file}: ${staleReason}\n`);
+            }
+            catch { /* ignore */ }
+            // fall through to write canonical content
         }
         // Directory empty OR missing seed triggers creation.
         try {
@@ -226,10 +305,17 @@ function autoSeedBootstrap() {
             // Inject timestamps at write time so loaders never trigger
             // [invariant-repair] firstSeenTs WARN noise on subsequent reads.
             const nowIso = new Date().toISOString();
-            const stamped = { createdAt: nowIso, firstSeenTs: nowIso, ...seed.json };
+            // Bake-in sourceHash so integrity_verify reports zero drift on a fresh install.
+            // Schema requires sha256(body) for the body field; without this seeds appear
+            // as drift forever (expected hash empty, actual populated).
+            const sourceHash = canonicalSourceHash;
+            const stamped = { createdAt: nowIso, updatedAt: nowIso, firstSeenTs: nowIso, sourceHash, ...seed.json };
             fs_1.default.writeFileSync(tmp, JSON.stringify(stamped, null, 2), { encoding: 'utf8' });
             fs_1.default.renameSync(tmp, target);
-            summary.created.push(seed.file);
+            if (exists)
+                summary.upgraded.push(seed.file);
+            else
+                summary.created.push(seed.file);
         }
         catch (e) {
             summary.reason = `partial_failure ${(e instanceof Error) ? e.message : String(e)}`;

package/dist/services/toolRegistry.js

@@ -12,20 +12,9 @@ const schemas_1 = require("../schemas");
 const featureFlags_1 = require("./featureFlags");
 const envUtils_1 = require("../utils/envUtils");
 const runtimeConfig_1 = require("../config/runtimeConfig");
+const instruction_1 = require("../models/instruction");
 // Input schema helpers (keep intentionally permissive if params optional)
 const stringReq = (name) => ({ type: 'object', additionalProperties: false, required: [name], properties: { [name]: { type: 'string' } } });
-const extensionsInputSchema = {
-    type: 'object',
-    additionalProperties: {
-        anyOf: [
-            { type: 'string' },
-            { type: 'number' },
-            { type: 'boolean' },
-            { type: 'array', items: {} },
-            { type: 'object', additionalProperties: true },
-        ],
-    },
-};
 const DANGEROUS_DIAGNOSTIC_TOOLS = new Set([
     'diagnostics_block',
     'diagnostics_microtaskFlood',
@@ -42,14 +31,21 @@ function buildInstructionBodyInputSchema(baseDescription) {
 function withDynamicInstructionBodyLimits(name, inputSchema) {
     const schema = JSON.parse(JSON.stringify(inputSchema));
     if (name === 'index_add') {
-        const entryProps = schema.properties?.entry?.properties ?? {};
+        const entry = schema.properties?.entry ?? {};
+        const entryProps = entry.properties ?? {};
         entryProps.body = buildInstructionBodyInputSchema('Instruction body.');
+        // Sub-schema $id must be unique across compile cycles so Ajv (a) does
+        // not reject duplicate-id registration and (b) can still resolve the
+        // embedded "#/definitions/..." $refs scoped to this schema.
+        entry.$id = `tool-input/index_add/entry/${++subSchemaCounter}`;
     }
     else if (name === 'index_import') {
         const entries = schema.properties?.entries?.oneOf;
         const arrayVariant = Array.isArray(entries) ? entries.find((candidate) => candidate.type === 'array') : undefined;
-        const itemProps = arrayVariant?.items?.properties ?? {};
+        const items = arrayVariant?.items ?? {};
+        const itemProps = items.properties ?? {};
         itemProps.body = buildInstructionBodyInputSchema('Instruction body.');
+        items.$id = `tool-input/index_import/entry/${++subSchemaCounter}`;
     }
     else if (name === 'index_dispatch') {
         const props = schema.properties ?? {};
@@ -59,6 +55,7 @@ function withDynamicInstructionBodyLimits(name, inputSchema) {
     }
     return schema;
 }
+let subSchemaCounter = 0;
 // Explicit param schemas derived from handlers in toolHandlers.ts
 const INPUT_SCHEMAS = {
     // graph export (Phase 1 + Phase 2 enrichment). All params optional.
@@ -94,7 +91,7 @@ const INPUT_SCHEMAS = {
             keywords: { type: 'array', items: { type: 'string' }, description: 'Explicit keyword array for search action when the caller wants direct token control.' },
             ids: { type: 'array', items: { type: 'string' }, description: 'Array of instruction IDs for remove or export actions.' },
             category: { type: 'string', description: 'Filter by category for list action.' },
-            contentType: { type: 'string', enum: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent', 'chat-session'], description: 'Filter by content type for list, search, or query actions, or specify the entry content type for add action. Legacy "chat-session" write inputs are migrated to "workflow".' },
+            contentType: { type: 'string', enum: [...instruction_1.CONTENT_TYPES], description: 'Filter by content type for list, search, or query actions, or specify the entry content type for add action.' },
             text: { type: 'string', description: 'Full-text search within query action.' },
             includeCategories: { type: 'boolean', description: 'Search categories in addition to id/title/semanticSummary/body for search action.' },
             caseSensitive: { type: 'boolean', description: 'Enable case-sensitive matching for search action.' },
@@ -145,20 +142,27 @@ const INPUT_SCHEMAS = {
     // NOTE: instructions_query & instructions_categories removed as standalone tools.
     // They are now exclusively accessed via index_dispatch with actions 'query' and 'categories'.
     // legacy read-only instruction method schemas removed in favor of dispatcher
+    //
+    // index_import / index_add tool input schemas are DERIVED from the canonical
+    // instruction schema via buildToolInputEntrySchema(). The two surfaces only
+    // differ in their caller-required minimum (index_add accepts {id, body};
+    // index_import requires {id, title, body, priority, audience, requirement}).
+    // Both reject server-managed properties (additionalProperties:false +
+    // server-managed keys stripped) and share property definitions, enums and
+    // patterns with on-disk validation. Hand-maintaining these schemas was the
+    // original drift source — see src/schemas/instructionSchema.ts.
     'index_import': { type: 'object', additionalProperties: false, properties: {
             entries: { oneOf: [
-                    { type: 'array', minItems: 1, items: { type: 'object', required: ['id', 'title', 'body', 'priority', 'audience', 'requirement'], additionalProperties: false, properties: {
-                                id: { type: 'string' }, title: { type: 'string' }, body: { type: 'string' }, rationale: { type: 'string' }, priority: { type: 'number' }, audience: { type: 'string' }, requirement: { type: 'string' }, categories: { type: 'array', items: { type: 'string' } }, version: { type: 'string' }, owner: { type: 'string' }, status: { type: 'string', enum: ['approved', 'draft', 'review', 'deprecated'] }, priorityTier: { type: 'string', enum: ['P1', 'P2', 'P3', 'P4'] }, classification: { type: 'string', enum: ['public', 'internal', 'restricted'] }, lastReviewedAt: { type: 'string' }, nextReviewDue: { type: 'string' }, semanticSummary: { type: 'string' }, changeLog: { type: 'array', items: { type: 'object', additionalProperties: true } }, contentType: { type: 'string', enum: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent', 'chat-session'] }, extensions: extensionsInputSchema, mode: { type: 'string' }
-                            } } },
+                    { type: 'array', minItems: 1, items: (0, schemas_1.buildToolInputEntrySchema)({
+                            required: ['id', 'title', 'body', 'priority', 'audience', 'requirement'],
+                        }) },
                     { type: 'string', description: 'Stringified JSON array of instruction entries, or a file path to a JSON array of instruction entries' }
                 ] },
             source: { type: 'string', description: 'Directory path containing .json instruction files to import' },
             mode: { enum: ['skip', 'overwrite'] }
         } },
     'index_add': { type: 'object', additionalProperties: false, required: ['entry'], properties: {
-            entry: { type: 'object', required: ['id', 'body'], additionalProperties: false, properties: {
-                    id: { type: 'string', minLength: 1, maxLength: 120, pattern: '^[a-z0-9](?:[a-z0-9-_]{0,118}[a-z0-9])?$' }, title: { type: 'string' }, body: { type: 'string' }, rationale: { type: 'string' }, priority: { type: 'number', minimum: 1, maximum: 100 }, audience: { type: 'string', enum: ['individual', 'group', 'all'] }, requirement: { type: 'string', enum: ['mandatory', 'critical', 'recommended', 'optional', 'deprecated'] }, categories: { type: 'array', items: { type: 'string', pattern: '^[a-z0-9][a-z0-9-_]{0,48}$' } }, deprecatedBy: { type: 'string' }, riskScore: { type: 'number' }, version: { type: 'string' }, owner: { type: 'string' }, status: { type: 'string', enum: ['approved', 'draft', 'review', 'deprecated'] }, priorityTier: { type: 'string', enum: ['P1', 'P2', 'P3', 'P4'] }, classification: { type: 'string', enum: ['public', 'internal', 'restricted'] }, lastReviewedAt: { type: 'string' }, nextReviewDue: { type: 'string' }, semanticSummary: { type: 'string' }, changeLog: { type: 'array', items: { type: 'object', additionalProperties: true } }, contentType: { type: 'string', enum: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent', 'chat-session'] }, extensions: extensionsInputSchema
-                } },
+            entry: (0, schemas_1.buildToolInputEntrySchema)({ required: ['id', 'body'] }),
             overwrite: { type: 'boolean' },
             lax: { type: 'boolean' }
         } },
@@ -208,6 +212,28 @@ const INPUT_SCHEMAS = {
             metadata: { type: 'object', additionalProperties: true },
             tags: { type: 'array', maxItems: 10, items: { type: 'string' } }
         } },
+    'feedback_manage': { type: 'object', additionalProperties: false, required: ['action'], properties: {
+            action: { type: 'string', enum: ['submit', 'list', 'get', 'update', 'delete', 'stats'], description: 'Feedback management action to perform.' },
+            id: { type: 'string', description: 'Feedback entry id for get, update, and delete actions.' },
+            type: { type: 'string', enum: ['issue', 'status', 'security', 'feature-request', 'bug-report', 'performance', 'usability', 'other'] },
+            severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
+            status: { type: 'string', enum: ['new', 'acknowledged', 'in-progress', 'resolved', 'closed'] },
+            title: { type: 'string', maxLength: 200 },
+            description: { type: 'string', maxLength: 10000 },
+            context: { type: 'object', additionalProperties: true, properties: {
+                    clientInfo: { type: 'object', properties: { name: { type: 'string' }, version: { type: 'string' } } },
+                    serverVersion: { type: 'string' },
+                    environment: { type: 'object', additionalProperties: true },
+                    sessionId: { type: 'string' },
+                    toolName: { type: 'string' },
+                    requestId: { type: 'string' }
+                } },
+            metadata: { type: 'object', additionalProperties: true },
+            tags: { type: 'array', maxItems: 10, items: { type: 'string' } },
+            limit: { type: 'number', minimum: 1, maximum: 200, description: 'Maximum entries to return for list action.' },
+            offset: { type: 'number', minimum: 0, description: 'Pagination offset for list action.' },
+            since: { type: 'string', description: 'ISO date filter for list and stats actions.' }
+        } },
     // instructions search tool - PRIMARY discovery mechanism
     'index_search': { type: 'object', additionalProperties: false, required: ['keywords'], properties: {
             keywords: {
@@ -221,7 +247,7 @@ const INPUT_SCHEMAS = {
             limit: { type: 'number', minimum: 1, maximum: 100, default: 50, description: 'Maximum number of instruction IDs to return' },
             includeCategories: { type: 'boolean', default: false, description: 'Include categories in search scope' },
             caseSensitive: { type: 'boolean', default: false, description: 'Perform case-sensitive matching' },
-            contentType: { type: 'string', enum: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent'], description: 'Filter results by content type (optional)' }
+            contentType: { type: 'string', enum: [...instruction_1.CONTENT_TYPES], description: 'Filter results by content type (optional)' }
         } },
     // promote_from_repo tool
     'promote_from_repo': { type: 'object', additionalProperties: false, required: ['repoPath'], properties: {
@@ -322,15 +348,16 @@ INPUT_SCHEMAS['trace_dump'] = { type: 'object', additionalProperties: false, pro
     } };
 // Stable & mutation classification lists (mirrors usage in toolHandlers; exported to remove duplication there).
 exports.STABLE = new Set(['health_check', 'feedback_submit', 'graph_export', 'index_dispatch', 'index_search', 'index_governanceHash', 'prompt_review', 'integrity_verify', 'usage_track', 'usage_hotset', 'metrics_snapshot', 'gates_evaluate', 'meta_tools', 'help_overview', 'index_schema', 'manifest_status', 'index_diagnostics', 'meta_activation_guide', 'meta_check_activation', 'bootstrap', 'bootstrap_status', 'feature_status', 'index_health', 'index_inspect', 'index_debug', 'integrity_manifest', 'messaging_read', 'messaging_list_channels', 'messaging_stats', 'messaging_get', 'messaging_thread', 'trace_dump']);
-exports.MUTATION = new Set(['index_add', 'index_import', 'index_repair', 'index_reload', 'index_remove', 'index_groom', 'index_enrich', 'index_governanceUpdate', 'index_normalize', 'usage_flush', 'manifest_refresh', 'manifest_repair', 'promote_from_repo', 'bootstrap_request', 'bootstrap_confirmFinalize', 'messaging_send', 'messaging_ack', 'messaging_update', 'messaging_purge', 'messaging_reply', 'diagnostics_block', 'diagnostics_microtaskFlood', 'diagnostics_memoryPressure']);
+exports.MUTATION = new Set(['feedback_manage', 'index_add', 'index_import', 'index_repair', 'index_reload', 'index_remove', 'index_groom', 'index_enrich', 'index_governanceUpdate', 'index_normalize', 'usage_flush', 'manifest_refresh', 'manifest_repair', 'promote_from_repo', 'bootstrap_request', 'bootstrap_confirmFinalize', 'messaging_send', 'messaging_ack', 'messaging_update', 'messaging_purge', 'messaging_reply', 'diagnostics_block', 'diagnostics_microtaskFlood', 'diagnostics_memoryPressure']);
 // Tool tier classification (002-tool-consolidation spec)
 // core: always visible, essential daily use
 // extended: opt-in via INDEX_SERVER_FLAG_TOOLS_EXTENDED=1 or flags.json tools_extended:true
 // admin: opt-in via INDEX_SERVER_FLAG_TOOLS_ADMIN=1, rarely needed ops/debug tools
 const TOOL_TIERS = {
-    // Core (7 after feedback_dispatch removal; feedback_submit remains always visible for agent reporting)
+    // Core (feedback_submit remains always visible for agent reporting; feedback_manage is the management dispatcher)
     'health_check': 'core',
     'feedback_submit': 'core',
+    'feedback_manage': 'extended',
     'index_dispatch': 'core',
     'index_search': 'core',
     'prompt_review': 'core',
@@ -459,6 +486,7 @@ function describeTool(name) {
         case 'meta_tools': return 'Enumerate available tools & their metadata.';
         // feedback system descriptions
         case 'feedback_submit': return 'Submit feedback entry (issue, status report, security alert, feature request, etc.).';
+        case 'feedback_manage': return 'Manage feedback entries through a single action dispatcher. Actions: submit, list, get, update, delete, stats.';
         case 'bootstrap': return 'Unified bootstrap dispatcher. Actions: request, confirm, status.';
         case 'manifest_status': return 'Report index manifest presence and drift summary.';
         case 'manifest_refresh': return 'Rewrite manifest from current index state.';