@svashevchenko/ez-know 0.1.0 → 0.2.0

package/dist/cli.js

@@ -2393,679 +2393,909 @@ function buildKnowledgeGraphQLText(result) {
   });
 }
 
-// packages/core/src/knowledge/patch/apply.ts
-import { existsSync as existsSync3 } from "node:fs";
-import { mkdir as mkdir2, rm, unlink, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname } from "node:path";
-
-// packages/core/src/knowledge/patch/validation.ts
-import { readFile as readFile4, stat } from "node:fs/promises";
-import { join as join4 } from "node:path";
-async function buildSourceFingerprintInput(sourceFiles) {
-  const entries = await Promise.all(
-    sourceFiles.map(async (filePath) => {
-      const [fileStat, content] = await Promise.all([
-        stat(filePath),
-        readFile4(filePath, "utf8")
-      ]);
-      return {
-        path: filePath,
-        size: fileStat.size,
-        mtimeMs: fileStat.mtimeMs,
-        contentHash: sha256(content)
-      };
-    })
-  );
-  entries.sort((left, right) => left.path.localeCompare(right.path));
-  return entries;
+// packages/core/src/knowledge/schema-discovery.ts
+import {
+  isAbstractType,
+  isCompositeType,
+  isListType,
+  isNonNullType,
+  isObjectType,
+  isScalarType,
+  isUnionType
+} from "graphql";
+var KNOWLEDGE_SCHEMA_RESOURCE_URI = "ez-know://schema";
+var KNOWLEDGE_SCHEMA_LOOKUP_URI = "ez-know://lookup/{target}";
+function unwrapType(type) {
+  if (isNonNullType(type) || isListType(type)) {
+    return unwrapType(type.ofType);
+  }
+  if (isObjectType(type) || isScalarType(type) || isUnionType(type) || isAbstractType(type)) {
+    return { name: type.name, composite: type };
+  }
+  return { name: "Unknown", composite: type };
 }
-function buildCanonicalPathForCollection(rootDir, domain, type) {
-  return join4(
-    rootDir,
-    domain,
-    KNOWLEDGE_EXTRACTION_TYPE_REGISTRY[type].storageFile
-  );
+function describeType(type) {
+  if (isNonNullType(type)) {
+    return `${describeType(type.ofType)}!`;
+  }
+  if (isListType(type)) {
+    return `[${describeType(type.ofType)}]`;
+  }
+  if (isObjectType(type) || isScalarType(type) || isUnionType(type)) {
+    return type.name;
+  }
+  if (isAbstractType(type)) {
+    return type.name;
+  }
+  return "Unknown";
 }
-function buildAffectedFileList(knowledgeRoot, operations) {
-  const affected = /* @__PURE__ */ new Set();
-  for (const operation of operations) {
-    affected.add(
-      buildCanonicalPathForCollection(
-        knowledgeRoot,
-        operation.domain,
-        operation.type
-      )
-    );
+function formatDefaultValue(value) {
+  if (value === void 0 || value === null) {
+    return null;
   }
-  return [...affected].sort((left, right) => left.localeCompare(right));
+  return JSON.stringify(value) ?? String(value);
 }
-function buildCollectionRecordsForDomain(state, type, domain) {
-  const records = [...state.byCollection[type].values()].filter(
-    (record2) => inferDomainForRecord(record2) === domain
-  );
-  records.sort((left, right) => left.id.localeCompare(right.id));
-  return records;
+function summarizeField(field) {
+  const traversedType = unwrapType(field.type).composite;
+  const traversesTo = isCompositeType(traversedType) && !isScalarType(traversedType) ? traversedType.name : null;
+  return {
+    name: field.name,
+    type: describeType(field.type),
+    description: field.description ?? null,
+    arguments: field.args?.map((argument) => ({
+      name: argument.name,
+      type: describeType(argument.type),
+      description: argument.description ?? null,
+      defaultValue: formatDefaultValue(argument.defaultValue)
+    })) ?? [],
+    traversesTo
+  };
 }
-async function computeValidationResult(knowledgeRoot, patchId, patch, operations) {
-  const effectiveBase = await loadEffectiveKnowledgeStoreFromRoot(
-    knowledgeRoot,
-    {
-      selectedPatchId: patchId,
-      includeSelectedPatch: false
-    }
-  );
-  const simulation = simulateKnowledgePatch(
-    effectiveBase.store,
-    operations,
-    patchId
-  );
-  const affectedFiles = buildAffectedFileList(knowledgeRoot, operations);
-  const diagnostics = [
-    ...effectiveBase.diagnostics,
-    ...simulation.diagnostics
-  ];
-  if (diagnostics.length > 0) {
-    return knowledgePatchValidationResultSchema.parse({
-      valid: false,
-      diagnostics,
-      operationCount: operations.length,
-      appliedOperationIds: simulation.appliedOperationIds,
-      affectedFiles
-    });
-  }
-  const sourceFingerprint = await buildSourceFingerprintInput(
-    effectiveBase.store.sourceFiles
-  );
-  const fingerprint = sha256(
-    JSON.stringify({
-      schemaVersion: KNOWLEDGE_PATCH_SCHEMA_VERSION,
-      patch: {
-        id: patch.id,
-        status: patch.status,
-        updatedAt: patch.updatedAt
-      },
-      operations,
-      sourceFingerprint
-    })
-  );
-  return knowledgePatchValidationResultSchema.parse({
-    valid: true,
-    fingerprint,
-    diagnostics,
-    operationCount: operations.length,
-    appliedOperationIds: simulation.appliedOperationIds,
-    affectedFiles
-  });
+function summarizeObjectType(type) {
+  const fields = Object.values(type.getFields()).map(summarizeField);
+  return {
+    name: type.name,
+    description: type.description ?? null,
+    fields,
+    traversalFields: fields.filter((field) => field.traversesTo !== null).map((field) => field.name)
+  };
 }
-async function validateKnowledgePatch(envValue, patchId, cwd = process.cwd()) {
-  const knowledgeRoot = resolveKnowledgeRoot2(envValue, cwd);
-  const state = await readKnowledgePatch(envValue, patchId, cwd);
-  return computeValidationResult(
-    knowledgeRoot,
-    patchId,
-    state.patch,
-    state.operations
-  );
+function getObjectTypes(schema) {
+  return Object.values(schema.getTypeMap()).filter((type) => isObjectType(type)).filter((type) => !type.name.startsWith("__")).filter((type) => type.name !== schema.getQueryType()?.name);
 }
-
-// packages/core/src/knowledge/patch/apply.ts
-async function writeCanonicalFilesFromSimulation(knowledgeRoot, operations, simulationState) {
-  const plannedWrites = /* @__PURE__ */ new Map();
-  for (const operation of operations) {
-    const filePath = buildCanonicalPathForCollection(
-      knowledgeRoot,
-      operation.domain,
-      operation.type
-    );
-    const records = buildCollectionRecordsForDomain(
-      simulationState,
-      operation.type,
-      operation.domain
-    );
-    if (operation.type === "domains") {
-      if (records.length === 0) {
-        if (existsSync3(filePath)) {
-          await unlink(filePath);
-        }
-        continue;
-      }
-      plannedWrites.set(filePath, `${JSON.stringify(records[0], null, 2)}
-`);
-      continue;
-    }
-    plannedWrites.set(filePath, `${JSON.stringify(records, null, 2)}
-`);
-  }
-  for (const filePath of plannedWrites.keys()) {
-    await mkdir2(dirname(filePath), { recursive: true });
-  }
-  for (const [filePath, content] of plannedWrites.entries()) {
-    await writeFile2(filePath, content, "utf8");
+function buildKnowledgeSchemaDiscoveryDocument(schema) {
+  const queryType2 = schema.getQueryType();
+  if (!queryType2) {
+    throw new Error("Knowledge GraphQL schema has no root query type.");
   }
+  return {
+    resource: {
+      uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
+      title: "Knowledge GraphQL Schema",
+      description: "Canonical discovery view of the runtime knowledge GraphQL schema."
+    },
+    source: {
+      kind: "runtime-schema",
+      queryType: queryType2.name
+    },
+    rootQuery: summarizeObjectType(queryType2),
+    objectTypes: getObjectTypes(schema).map(summarizeObjectType)
+  };
 }
-async function applyKnowledgePatch(envValue, input, cwd = process.cwd()) {
-  const parsedInput = knowledgePatchApplyToolInputSchema.parse(input);
-  const knowledgeRoot = resolveKnowledgeRoot2(envValue, cwd);
-  const patchDir = resolveKnowledgePatchDirectory(
-    envValue,
-    parsedInput.patchId,
-    cwd
-  );
-  const patchState = await loadPatchStateByDir(patchDir);
-  const validation = await computeValidationResult(
-    knowledgeRoot,
-    patchState.patch.id,
-    patchState.patch,
-    patchState.operations
-  );
-  const diagnostics = [...validation.diagnostics];
-  const pendingPatches = (await listKnowledgePatches(envValue, cwd)).filter(
-    (patch) => patch.status === "draft"
-  );
-  const firstPendingPatchId = pendingPatches[0]?.id;
-  if (firstPendingPatchId !== void 0 && firstPendingPatchId !== patchState.patch.id) {
-    diagnostics.push(
-      buildDiagnostic({
-        severity: "error",
-        code: "apply_out_of_order",
-        message: `Patch "${patchState.patch.id}" cannot be applied while earlier pending patch "${firstPendingPatchId}" still exists.`,
-        patchId: patchState.patch.id
-      })
-    );
+function getLookupMetadata(schema, target) {
+  const queryType2 = schema.getQueryType();
+  if (!queryType2) {
+    throw new Error("Knowledge GraphQL schema has no root query type.");
   }
-  if (!parsedInput.approval.approved) {
-    diagnostics.push(
-      buildDiagnostic({
-        severity: "error",
-        code: "approval_required",
-        message: "Patch apply requires explicit approval.",
-        patchId: patchState.patch.id
-      })
-    );
+  if (target === queryType2.name) {
+    return {
+      resource: {
+        uri: `ez-know://lookup/${target}`,
+        title: `Knowledge schema lookup: ${target}`,
+        description: "Focused lookup of the root query fields and their arguments."
+      },
+      source: {
+        kind: "runtime-schema",
+        queryType: queryType2.name
+      },
+      lookup: {
+        target: queryType2.name,
+        kind: "root-query"
+      },
+      rootQuery: summarizeObjectType(queryType2)
+    };
   }
-  if (firstPendingPatchId !== void 0 && firstPendingPatchId !== patchState.patch.id || !parsedInput.approval.approved || !validation.valid || parsedInput.approval.validationFingerprint !== validation.fingerprint) {
-    if (validation.valid && parsedInput.approval.validationFingerprint !== validation.fingerprint) {
-      diagnostics.push(
-        buildDiagnostic({
-          severity: "error",
-          code: "stale_validation_fingerprint",
-          message: "Patch validation fingerprint is stale. Revalidate before apply.",
-          patchId: patchState.patch.id
-        })
-      );
-    }
+  const rootField = queryType2.getFields()[target];
+  if (rootField) {
     return {
-      patchId: patchState.patch.id,
-      applied: false,
-      validation,
-      diagnostics,
-      deletedPatch: false
+      resource: {
+        uri: `ez-know://lookup/${target}`,
+        title: `Knowledge schema lookup: ${target}`,
+        description: "Focused lookup of a single root query field and its arguments."
+      },
+      source: {
+        kind: "runtime-schema",
+        queryType: queryType2.name
+      },
+      lookup: {
+        target,
+        kind: "root-field"
+      },
+      field: summarizeField(rootField),
+      parentType: queryType2.name
     };
   }
-  const store = await loadKnowledgeStoreFromRoot(knowledgeRoot);
-  const simulation = simulateKnowledgePatch(
-    store,
-    patchState.operations,
-    patchState.patch.id
-  );
-  if (simulation.diagnostics.length > 0) {
+  const objectType = schema.getType(target);
+  if (objectType && isObjectType(objectType)) {
+    const typeSummary = summarizeObjectType(objectType);
+    const rootFields = Object.values(queryType2.getFields()).filter((field) => unwrapType(field.type).name === target).map((field) => field.name);
     return {
-      patchId: patchState.patch.id,
-      applied: false,
-      validation: {
-        ...validation,
-        valid: false,
-        diagnostics: simulation.diagnostics
+      resource: {
+        uri: `ez-know://lookup/${target}`,
+        title: `Knowledge schema lookup: ${target}`,
+        description: "Focused lookup of a single GraphQL type and its nested traversal fields."
       },
-      diagnostics: simulation.diagnostics,
-      deletedPatch: false
+      source: {
+        kind: "runtime-schema",
+        queryType: queryType2.name
+      },
+      lookup: {
+        target,
+        kind: "object-type"
+      },
+      type: typeSummary,
+      rootFields
     };
   }
-  await writeCanonicalFilesFromSimulation(
-    knowledgeRoot,
-    patchState.operations,
-    simulation.state
+  throw new Error(
+    `Unknown schema lookup target "${target}". Use a root field name, a type name, or "Query".`
   );
-  try {
-    await loadKnowledgeStoreFromRoot(knowledgeRoot);
-  } catch (error) {
-    const reloadDiagnostics = error instanceof KnowledgeStoreLoadError ? error.diagnostics.map(
-      (diagnostic) => buildDiagnostic({
-        severity: "critical",
-        code: diagnostic.kind,
-        message: diagnostic.message,
-        path: diagnostic.path ? [diagnostic.path] : void 0,
-        targetId: diagnostic.id
-      })
-    ) : [
-      buildDiagnostic({
-        severity: "critical",
-        code: "reload_failed",
-        message: "Canonical knowledge store reload failed after apply.",
-        patchId: patchState.patch.id
-      })
-    ];
-    return {
-      patchId: patchState.patch.id,
-      applied: false,
-      validation,
-      diagnostics: reloadDiagnostics,
-      deletedPatch: false
-    };
+}
+function buildKnowledgeSchemaLookupDocument(schema, target) {
+  return getLookupMetadata(schema, target);
+}
+function listKnowledgeSchemaTargets(schema) {
+  const queryType2 = schema.getQueryType();
+  if (!queryType2) {
+    throw new Error("Knowledge GraphQL schema has no root query type.");
   }
-  await rm(patchDir, { recursive: true, force: true });
+  const objectTypeNames = getObjectTypes(schema).map((type) => type.name);
+  const rootFieldNames = Object.keys(queryType2.getFields());
+  const targetNames = ["Query", ...rootFieldNames, ...objectTypeNames];
+  return Array.from(new Set(targetNames)).sort(
+    (left, right) => left.localeCompare(right)
+  );
+}
+
+// packages/core/src/knowledge/resource-catalog.ts
+var KnowledgeResourceNotFoundError = class extends Error {
+  constructor(uri, message = `Unknown ez-know resource URI "${uri}".`) {
+    super(message);
+    this.uri = uri;
+    this.name = "KnowledgeResourceNotFoundError";
+  }
+  uri;
+  code = "RESOURCE_NOT_FOUND";
+};
+var KnowledgeResourceUriError = class extends Error {
+  constructor(uri, message) {
+    super(message);
+    this.uri = uri;
+    this.name = "KnowledgeResourceUriError";
+  }
+  uri;
+  code = "INVALID_RESOURCE_URI";
+};
+function createJsonResourceContent(uri, text) {
   return {
-    patchId: patchState.patch.id,
-    applied: true,
-    validation,
-    diagnostics: [],
-    deletedPatch: true
+    uri,
+    mimeType: "application/json",
+    text
   };
 }
-
-// packages/core/src/knowledge/patch/scope-audit.ts
-import { readdir as readdir2 } from "node:fs/promises";
-import { isAbsolute as isAbsolute2, relative, resolve as resolve5, sep as sep2 } from "node:path";
-import { z as z6 } from "zod/v4";
-var compareScopeWithEvidenceInputSchema = z6.object({
-  patchId: z6.string().min(1),
-  rootFolder: z6.string().trim().min(1).optional()
-});
-var compareScopeWithEvidenceResultSchema = z6.object({
-  patchId: z6.string().min(1),
-  rootFolder: z6.string().min(1),
-  scopeFiles: z6.array(z6.string()),
-  coveredFiles: z6.array(z6.string()),
-  omittedFiles: z6.array(
-    z6.object({
-      path: z6.string(),
-      reason: z6.string()
+function createMarkdownResourceContent(uri, text) {
+  return {
+    uri,
+    mimeType: "text/markdown",
+    text
+  };
+}
+function createKnowledgeSchemaResourceDefinition() {
+  return {
+    uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
+    name: "knowledge-schema",
+    title: "Knowledge GraphQL Schema",
+    description: "Canonical runtime GraphQL schema discovery payload for the knowledge layer.",
+    mimeType: "application/json",
+    read: () => ({
+      resource: {
+        uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
+        title: "Knowledge GraphQL Schema",
+        description: "Canonical runtime GraphQL schema discovery payload for the knowledge layer.",
+        mimeType: "application/json"
+      },
+      content: createJsonResourceContent(
+        KNOWLEDGE_SCHEMA_RESOURCE_URI,
+        createKnowledgeSchemaDiscoveryText()
+      )
     })
-  ),
-  uncoveredFiles: z6.array(z6.string()),
-  outOfRootEvidenceFiles: z6.array(z6.string()),
-  message: z6.string()
-});
-function toPosixPath(value) {
-  return value.replaceAll(sep2, "/");
+  };
 }
-function normalizeAuditedRoot(rootFolder) {
-  return resolve5(rootFolder);
+function createKnowledgeExtractionTypesResourceDefinition() {
+  return {
+    uri: KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+    name: "knowledge-extraction-types",
+    title: "Knowledge Extraction Types",
+    description: "Canonical registry of knowledge types supported by the extraction workflow.",
+    mimeType: "application/json",
+    read: () => ({
+      resource: {
+        uri: KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+        title: "Knowledge Extraction Types",
+        description: "Canonical registry of knowledge types supported by the extraction workflow.",
+        mimeType: "application/json"
+      },
+      content: createJsonResourceContent(
+        KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+        JSON.stringify(buildKnowledgeExtractionTypeIndexDocument(), null, 2)
+      )
+    })
+  };
 }
-function isPathWithinRoot(rootFolder, filePath) {
-  const relativePath = toPosixPath(relative(rootFolder, filePath));
-  return Boolean(
-    relativePath && relativePath !== ".." && !relativePath.startsWith("../")
+function createKnowledgeSchemaLookupTemplateDefinition() {
+  return {
+    uriTemplate: KNOWLEDGE_SCHEMA_LOOKUP_URI,
+    name: "knowledge-schema-lookup",
+    title: "Knowledge Schema Lookup",
+    description: "Focused runtime GraphQL schema lookup for a type name, root field, or Query.",
+    mimeType: "application/json",
+    list: () => listKnowledgeSchemaTargets(knowledgeGraphSchema).map((target) => ({
+      uri: `ez-know://lookup/${target}`,
+      name: target,
+      title: `Knowledge schema lookup: ${target}`,
+      description: target === "Query" ? "Focused lookup of the root query fields." : `Focused lookup of ${target}.`,
+      mimeType: "application/json"
+    })),
+    read: (uri) => {
+      const target = readUriSegment(uri, "ez-know://lookup/");
+      try {
+        return {
+          resource: {
+            uri,
+            title: `Knowledge schema lookup: ${target}`,
+            description: target === "Query" ? "Focused lookup of the root query fields and their arguments." : `Focused lookup of ${target}.`,
+            mimeType: "application/json"
+          },
+          content: createJsonResourceContent(
+            uri,
+            createKnowledgeSchemaLookupText(target)
+          )
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new KnowledgeResourceUriError(uri, error.message);
+        }
+        throw error;
+      }
+    }
+  };
+}
+function createKnowledgeExtractionSchemaTemplateDefinition() {
+  return {
+    uriTemplate: KNOWLEDGE_EXTRACTION_SCHEMA_RESOURCE_URI,
+    name: "knowledge-extraction-schema",
+    title: "Knowledge Extraction Schema",
+    description: "Runtime JSON-schema discovery for a supported knowledge type.",
+    mimeType: "application/json",
+    list: () => listKnowledgeExtractionResourceTypes().map((definition) => ({
+      uri: `ez-know://extraction/schema/${definition.collection}`,
+      name: definition.collection,
+      title: `${definition.title} Extraction Schema`,
+      description: `Runtime schema discovery for ${definition.title.toLowerCase()}.`,
+      mimeType: "application/json"
+    })),
+    read: (uri) => {
+      const type = readUriSegment(uri, "ez-know://extraction/schema/");
+      try {
+        const document = buildKnowledgeExtractionSchemaDocument(type);
+        return {
+          resource: {
+            uri: `ez-know://extraction/schema/${document.type.collection}`,
+            title: `${document.type.title} Extraction Schema`,
+            description: "Runtime JSON Schema view of the canonical knowledge object model.",
+            mimeType: "application/json"
+          },
+          content: createJsonResourceContent(
+            `ez-know://extraction/schema/${document.type.collection}`,
+            JSON.stringify(document, null, 2)
+          )
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new KnowledgeResourceUriError(uri, error.message);
+        }
+        throw error;
+      }
+    }
+  };
+}
+function createKnowledgeExtractionGuideTemplateDefinition() {
+  return {
+    uriTemplate: KNOWLEDGE_EXTRACTION_GUIDE_RESOURCE_URI,
+    name: "knowledge-extraction-guide",
+    title: "Knowledge Extraction Guide",
+    description: "Checked-in Markdown guidance for a supported knowledge type.",
+    mimeType: "text/markdown",
+    list: () => listKnowledgeExtractionResourceTypes().map((definition) => ({
+      uri: `ez-know://extraction/guide/${definition.collection}`,
+      name: definition.collection,
+      title: `${definition.title} Extraction Guide`,
+      description: `Checked-in extraction guidance for ${definition.title.toLowerCase()}.`,
+      mimeType: "text/markdown"
+    })),
+    read: async (uri) => {
+      const type = readUriSegment(uri, "ez-know://extraction/guide/");
+      try {
+        const document = await buildKnowledgeExtractionGuideDocument(type);
+        return {
+          resource: {
+            uri: `ez-know://extraction/guide/${document.type.collection}`,
+            title: `${document.type.title} Extraction Guide`,
+            description: "Checked-in Markdown guidance for extracting this knowledge type.",
+            mimeType: "text/markdown"
+          },
+          content: createMarkdownResourceContent(
+            `ez-know://extraction/guide/${document.type.collection}`,
+            document.markdown
+          )
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new KnowledgeResourceUriError(uri, error.message);
+        }
+        throw error;
+      }
+    }
+  };
+}
+function createKnowledgeSchemaDiscoveryText() {
+  return JSON.stringify(buildKnowledgeSchemaDiscoveryDocument(knowledgeGraphSchema), null, 2);
+}
+function createKnowledgeSchemaLookupText(target) {
+  return JSON.stringify(
+    buildKnowledgeSchemaLookupDocument(knowledgeGraphSchema, target),
+    null,
+    2
   );
 }
-function normalizePathWithinRoot(rootFolder, filePath, outputRoot = rootFolder) {
-  let candidate;
-  if (isAbsolute2(filePath)) {
-    candidate = resolve5(filePath);
-  } else {
-    const repoRelativeCandidate = resolve5(outputRoot, filePath);
-    candidate = isPathWithinRoot(rootFolder, repoRelativeCandidate) ? repoRelativeCandidate : resolve5(rootFolder, filePath);
+function readUriSegment(uri, prefix) {
+  if (!uri.startsWith(prefix)) {
+    throw new KnowledgeResourceNotFoundError(uri);
   }
-  const relativePath = toPosixPath(relative(outputRoot, candidate));
-  if (!relativePath || relativePath === ".." || relativePath.startsWith("../")) {
-    return null;
+  const segment = uri.slice(prefix.length);
+  if (segment.length === 0 || segment.includes("/")) {
+    throw new KnowledgeResourceUriError(
+      uri,
+      `Unsupported ez-know resource URI "${uri}".`
+    );
   }
-  return relativePath;
+  return segment;
 }
-async function collectScopeFiles(currentDir, auditedRoot, patchStorageRoot, outputRoot) {
-  if (currentDir === patchStorageRoot) {
-    return [];
+var KNOWLEDGE_RESOURCE_DEFINITIONS = [
+  createKnowledgeSchemaResourceDefinition(),
+  createKnowledgeExtractionTypesResourceDefinition()
+];
+var KNOWLEDGE_RESOURCE_TEMPLATE_DEFINITIONS = [
+  createKnowledgeSchemaLookupTemplateDefinition(),
+  createKnowledgeExtractionSchemaTemplateDefinition(),
+  createKnowledgeExtractionGuideTemplateDefinition()
+];
+function listKnowledgeResourceEntries() {
+  return KNOWLEDGE_RESOURCE_DEFINITIONS.map(({ read: _read, ...metadata }) => ({
+    ...metadata
+  }));
+}
+function listKnowledgeResourceTemplateEntries() {
+  return KNOWLEDGE_RESOURCE_TEMPLATE_DEFINITIONS.map(({ list: _list, read: _read, ...metadata }) => ({
+    ...metadata
+  }));
+}
+function listKnowledgeResourceTemplateResources(uriTemplate) {
+  const template = KNOWLEDGE_RESOURCE_TEMPLATE_DEFINITIONS.find(
+    (entry) => entry.uriTemplate === uriTemplate
+  );
+  if (!template) {
+    throw new KnowledgeResourceNotFoundError(uriTemplate);
   }
-  const entries = await readdir2(currentDir, { withFileTypes: true });
-  const files = [];
-  for (const entry of entries) {
-    const entryPath = resolve5(currentDir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(
-        ...await collectScopeFiles(
-          entryPath,
-          auditedRoot,
-          patchStorageRoot,
-          outputRoot
-        )
-      );
-      continue;
-    }
-    if (!entry.isFile()) {
-      continue;
-    }
-    const normalized = normalizePathWithinRoot(auditedRoot, entryPath, outputRoot);
-    if (normalized) {
-      files.push(normalized);
-    }
+  return template.list();
+}
+function getKnowledgeResourceEntry(uri) {
+  return KNOWLEDGE_RESOURCE_DEFINITIONS.find((entry) => entry.uri === uri);
+}
+async function readKnowledgeResourceDocument(uri) {
+  const resource = getKnowledgeResourceEntry(uri);
+  if (resource) {
+    return await resource.read();
+  }
+  if (uri.startsWith("ez-know://lookup/")) {
+    return await createKnowledgeSchemaLookupTemplateDefinition().read(uri);
+  }
+  if (uri.startsWith("ez-know://extraction/schema/")) {
+    return await createKnowledgeExtractionSchemaTemplateDefinition().read(uri);
+  }
+  if (uri.startsWith("ez-know://extraction/guide/")) {
+    return await createKnowledgeExtractionGuideTemplateDefinition().read(uri);
+  }
+  throw new KnowledgeResourceNotFoundError(uri);
+}
+
+// packages/core/src/knowledge/patch/apply.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { mkdir as mkdir2, rm, unlink, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname } from "node:path";
+
+// packages/core/src/knowledge/patch/validation.ts
+import { readFile as readFile4, stat } from "node:fs/promises";
+import { join as join4 } from "node:path";
+async function buildSourceFingerprintInput(sourceFiles) {
+  const entries = await Promise.all(
+    sourceFiles.map(async (filePath) => {
+      const [fileStat, content] = await Promise.all([
+        stat(filePath),
+        readFile4(filePath, "utf8")
+      ]);
+      return {
+        path: filePath,
+        size: fileStat.size,
+        mtimeMs: fileStat.mtimeMs,
+        contentHash: sha256(content)
+      };
+    })
+  );
+  entries.sort((left, right) => left.path.localeCompare(right.path));
+  return entries;
+}
+function buildCanonicalPathForCollection(rootDir, domain, type) {
+  return join4(
+    rootDir,
+    domain,
+    KNOWLEDGE_EXTRACTION_TYPE_REGISTRY[type].storageFile
+  );
+}
+function buildAffectedFileList(knowledgeRoot, operations) {
+  const affected = /* @__PURE__ */ new Set();
+  for (const operation of operations) {
+    affected.add(
+      buildCanonicalPathForCollection(
+        knowledgeRoot,
+        operation.domain,
+        operation.type
+      )
+    );
   }
-  return files;
+  return [...affected].sort((left, right) => left.localeCompare(right));
 }
-async function compareScopeWithEvidence(envValue, input, cwd = process.cwd()) {
-  const parsedInput = compareScopeWithEvidenceInputSchema.parse(input);
-  const patchState = await readKnowledgePatch(envValue, parsedInput.patchId, cwd);
-  const auditedRoot = normalizeAuditedRoot(
-    parsedInput.rootFolder ?? patchState.patch.rootFolder
+function buildCollectionRecordsForDomain(state, type, domain) {
+  const records = [...state.byCollection[type].values()].filter(
+    (record2) => inferDomainForRecord(record2) === domain
   );
-  const repositoryRoot = resolve5(cwd);
-  const effectiveState = await loadEffectiveKnowledgeStoreFromRoot(
-    resolveKnowledgeRoot2(envValue, cwd),
+  records.sort((left, right) => left.id.localeCompare(right.id));
+  return records;
+}
+async function computeValidationResult(knowledgeRoot, patchId, patch, operations) {
+  const effectiveBase = await loadEffectiveKnowledgeStoreFromRoot(
+    knowledgeRoot,
     {
-      selectedPatchId: parsedInput.patchId
+      selectedPatchId: patchId,
+      includeSelectedPatch: false
     }
   );
-  const effectivePatchIds = new Set(effectiveState.patchIds);
-  const coveredFiles = /* @__PURE__ */ new Set();
-  const outOfRootEvidenceFiles = /* @__PURE__ */ new Set();
-  for (const evidence of effectiveState.store.evidence) {
-    const provenance = effectiveState.provenance.get(evidence.id);
-    if (!provenance?.patchIds.some((patchId) => effectivePatchIds.has(patchId))) {
-      continue;
-    }
-    const sourcePath = evidence.location?.path;
-    if (!sourcePath) {
-      continue;
-    }
-    const normalized = normalizePathWithinRoot(
-      auditedRoot,
-      sourcePath,
-      repositoryRoot
-    );
-    if (normalized) {
-      coveredFiles.add(normalized);
-      continue;
-    }
-    outOfRootEvidenceFiles.add(sourcePath);
-  }
-  const omittedFiles = patchState.patch.omittedFiles.map((entry) => ({
-    path: entry.path,
-    reason: entry.reason
-  }));
-  const omittedFileSet = new Set(omittedFiles.map((entry) => entry.path));
-  const patchStorageRoot = resolve5(auditedRoot, KNOWLEDGE_PATCH_FOLDER_NAME);
-  const scopeFiles = (await collectScopeFiles(
-    auditedRoot,
-    auditedRoot,
-    patchStorageRoot,
-    repositoryRoot
-  )).sort((left, right) => left.localeCompare(right));
-  const uncoveredFiles = scopeFiles.filter(
-    (filePath) => !coveredFiles.has(filePath) && !omittedFileSet.has(filePath)
+  const simulation = simulateKnowledgePatch(
+    effectiveBase.store,
+    operations,
+    patchId
   );
-  const sortedCoveredFiles = [...coveredFiles].sort(
-    (left, right) => left.localeCompare(right)
+  const affectedFiles = buildAffectedFileList(knowledgeRoot, operations);
+  const diagnostics = [
+    ...effectiveBase.diagnostics,
+    ...simulation.diagnostics
+  ];
+  if (diagnostics.length > 0) {
+    return knowledgePatchValidationResultSchema.parse({
+      valid: false,
+      diagnostics,
+      operationCount: operations.length,
+      appliedOperationIds: simulation.appliedOperationIds,
+      affectedFiles
+    });
+  }
+  const sourceFingerprint = await buildSourceFingerprintInput(
+    effectiveBase.store.sourceFiles
   );
-  const sortedOutOfRootEvidenceFiles = [...outOfRootEvidenceFiles].sort(
-    (left, right) => left.localeCompare(right)
+  const fingerprint = sha256(
+    JSON.stringify({
+      schemaVersion: KNOWLEDGE_PATCH_SCHEMA_VERSION,
+      patch: {
+        id: patch.id,
+        status: patch.status,
+        updatedAt: patch.updatedAt
+      },
+      operations,
+      sourceFingerprint
+    })
   );
-  const message = uncoveredFiles.length > 0 ? `Recheck ${uncoveredFiles.length} uncovered file(s): add evidence-backed knowledge or mark them omitted with a reason.` : "Scope audit complete. No uncovered files remain.";
-  return compareScopeWithEvidenceResultSchema.parse({
-    patchId: parsedInput.patchId,
-    rootFolder: auditedRoot,
-    scopeFiles,
-    coveredFiles: sortedCoveredFiles,
-    omittedFiles,
-    uncoveredFiles,
-    outOfRootEvidenceFiles: sortedOutOfRootEvidenceFiles,
-    message
+  return knowledgePatchValidationResultSchema.parse({
+    valid: true,
+    fingerprint,
+    diagnostics,
+    operationCount: operations.length,
+    appliedOperationIds: simulation.appliedOperationIds,
+    affectedFiles
   });
 }
-
-// packages/core/src/knowledge/patch/index.ts
-async function executeKnowledgePatchAction(envValue, input, cwd = process.cwd()) {
-  switch (input.action) {
-    case "create":
-      return createKnowledgePatch(envValue, input.patch, cwd);
-    case "list":
-      return listKnowledgePatches(envValue, cwd);
-    case "get":
-      return readKnowledgePatch(envValue, input.patchId, cwd);
-    case "add_operation":
-      return addKnowledgePatchOperation(
-        envValue,
-        input.patchId,
-        input.operation,
-        cwd
-      );
-    case "update_operation":
-      return updateKnowledgePatchOperation(
-        envValue,
-        input.patchId,
-        input.update,
-        cwd
-      );
-    case "update_metadata":
-      return updateKnowledgePatchMetadata(
-        envValue,
-        input.patchId,
-        input.metadata,
-        cwd
-      );
-    case "delete_operation":
-      return deleteKnowledgePatchOperation(
-        envValue,
-        input.patchId,
-        input.operationId,
-        cwd
-      );
-    case "validate":
-      return validateKnowledgePatch(envValue, input.patchId, cwd);
-    case "close":
-      return closeKnowledgePatch(envValue, input.patchId, cwd);
-  }
-}
-function buildKnowledgePatchToolText(result) {
-  return JSON.stringify(result, null, 2);
+async function validateKnowledgePatch(envValue, patchId, cwd = process.cwd()) {
+  const knowledgeRoot = resolveKnowledgeRoot2(envValue, cwd);
+  const state = await readKnowledgePatch(envValue, patchId, cwd);
+  return computeValidationResult(
+    knowledgeRoot,
+    patchId,
+    state.patch,
+    state.operations
+  );
 }
 
-// packages/core/src/knowledge/schema-discovery.ts
-import {
-  isAbstractType,
-  isCompositeType,
-  isListType,
-  isNonNullType,
-  isObjectType,
-  isScalarType,
-  isUnionType
-} from "graphql";
-var KNOWLEDGE_SCHEMA_RESOURCE_URI = "knowledge-schema://schema";
-var KNOWLEDGE_SCHEMA_LOOKUP_URI = "knowledge-schema://lookup/{target}";
-function unwrapType(type) {
-  if (isNonNullType(type) || isListType(type)) {
-    return unwrapType(type.ofType);
-  }
-  if (isObjectType(type) || isScalarType(type) || isUnionType(type) || isAbstractType(type)) {
-    return { name: type.name, composite: type };
-  }
-  return { name: "Unknown", composite: type };
-}
-function describeType(type) {
-  if (isNonNullType(type)) {
-    return `${describeType(type.ofType)}!`;
-  }
-  if (isListType(type)) {
-    return `[${describeType(type.ofType)}]`;
-  }
-  if (isObjectType(type) || isScalarType(type) || isUnionType(type)) {
-    return type.name;
-  }
-  if (isAbstractType(type)) {
-    return type.name;
+// packages/core/src/knowledge/patch/apply.ts
+async function writeCanonicalFilesFromSimulation(knowledgeRoot, operations, simulationState) {
+  const plannedWrites = /* @__PURE__ */ new Map();
+  for (const operation of operations) {
+    const filePath = buildCanonicalPathForCollection(
+      knowledgeRoot,
+      operation.domain,
+      operation.type
+    );
+    const records = buildCollectionRecordsForDomain(
+      simulationState,
+      operation.type,
+      operation.domain
+    );
+    if (operation.type === "domains") {
+      if (records.length === 0) {
+        if (existsSync3(filePath)) {
+          await unlink(filePath);
+        }
+        continue;
+      }
+      plannedWrites.set(filePath, `${JSON.stringify(records[0], null, 2)}
+`);
+      continue;
+    }
+    plannedWrites.set(filePath, `${JSON.stringify(records, null, 2)}
+`);
   }
-  return "Unknown";
-}
-function formatDefaultValue(value) {
-  if (value === void 0 || value === null) {
-    return null;
+  for (const filePath of plannedWrites.keys()) {
+    await mkdir2(dirname(filePath), { recursive: true });
   }
-  return JSON.stringify(value) ?? String(value);
-}
-function summarizeField(field) {
-  const traversedType = unwrapType(field.type).composite;
-  const traversesTo = isCompositeType(traversedType) && !isScalarType(traversedType) ? traversedType.name : null;
-  return {
-    name: field.name,
-    type: describeType(field.type),
-    description: field.description ?? null,
-    arguments: field.args?.map((argument) => ({
-      name: argument.name,
-      type: describeType(argument.type),
-      description: argument.description ?? null,
-      defaultValue: formatDefaultValue(argument.defaultValue)
-    })) ?? [],
-    traversesTo
-  };
-}
-function summarizeObjectType(type) {
-  const fields = Object.values(type.getFields()).map(summarizeField);
-  return {
-    name: type.name,
-    description: type.description ?? null,
-    fields,
-    traversalFields: fields.filter((field) => field.traversesTo !== null).map((field) => field.name)
-  };
-}
-function getObjectTypes(schema) {
-  return Object.values(schema.getTypeMap()).filter((type) => isObjectType(type)).filter((type) => !type.name.startsWith("__")).filter((type) => type.name !== schema.getQueryType()?.name);
-}
-function buildKnowledgeSchemaDiscoveryDocument(schema) {
-  const queryType2 = schema.getQueryType();
-  if (!queryType2) {
-    throw new Error("Knowledge GraphQL schema has no root query type.");
+  for (const [filePath, content] of plannedWrites.entries()) {
+    await writeFile2(filePath, content, "utf8");
   }
-  return {
-    resource: {
-      uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
-      title: "Knowledge GraphQL Schema",
-      description: "Canonical discovery view of the runtime knowledge GraphQL schema."
-    },
-    source: {
-      kind: "runtime-schema",
-      queryType: queryType2.name
-    },
-    rootQuery: summarizeObjectType(queryType2),
-    objectTypes: getObjectTypes(schema).map(summarizeObjectType)
-  };
 }
-function getLookupMetadata(schema, target) {
-  const queryType2 = schema.getQueryType();
-  if (!queryType2) {
-    throw new Error("Knowledge GraphQL schema has no root query type.");
+async function applyKnowledgePatch(envValue, input, cwd = process.cwd()) {
+  const parsedInput = knowledgePatchApplyToolInputSchema.parse(input);
+  const knowledgeRoot = resolveKnowledgeRoot2(envValue, cwd);
+  const patchDir = resolveKnowledgePatchDirectory(
+    envValue,
+    parsedInput.patchId,
+    cwd
+  );
+  const patchState = await loadPatchStateByDir(patchDir);
+  const validation = await computeValidationResult(
+    knowledgeRoot,
+    patchState.patch.id,
+    patchState.patch,
+    patchState.operations
+  );
+  const diagnostics = [...validation.diagnostics];
+  const pendingPatches = (await listKnowledgePatches(envValue, cwd)).filter(
+    (patch) => patch.status === "draft"
+  );
+  const firstPendingPatchId = pendingPatches[0]?.id;
+  if (firstPendingPatchId !== void 0 && firstPendingPatchId !== patchState.patch.id) {
+    diagnostics.push(
+      buildDiagnostic({
+        severity: "error",
+        code: "apply_out_of_order",
+        message: `Patch "${patchState.patch.id}" cannot be applied while earlier pending patch "${firstPendingPatchId}" still exists.`,
+        patchId: patchState.patch.id
+      })
+    );
   }
-  if (target === queryType2.name) {
+  if (!parsedInput.approval.approved) {
+    diagnostics.push(
+      buildDiagnostic({
+        severity: "error",
+        code: "approval_required",
+        message: "Patch apply requires explicit approval.",
+        patchId: patchState.patch.id
+      })
+    );
+  }
+  if (firstPendingPatchId !== void 0 && firstPendingPatchId !== patchState.patch.id || !parsedInput.approval.approved || !validation.valid || parsedInput.approval.validationFingerprint !== validation.fingerprint) {
+    if (validation.valid && parsedInput.approval.validationFingerprint !== validation.fingerprint) {
+      diagnostics.push(
+        buildDiagnostic({
+          severity: "error",
+          code: "stale_validation_fingerprint",
+          message: "Patch validation fingerprint is stale. Revalidate before apply.",
+          patchId: patchState.patch.id
+        })
+      );
+    }
     return {
-      resource: {
-        uri: `knowledge-schema://lookup/${target}`,
-        title: `Knowledge schema lookup: ${target}`,
-        description: "Focused lookup of the root query fields and their arguments."
-      },
-      source: {
-        kind: "runtime-schema",
-        queryType: queryType2.name
-      },
-      lookup: {
-        target: queryType2.name,
-        kind: "root-query"
-      },
-      rootQuery: summarizeObjectType(queryType2)
+      patchId: patchState.patch.id,
+      applied: false,
+      validation,
+      diagnostics,
+      deletedPatch: false
     };
   }
-  const rootField = queryType2.getFields()[target];
-  if (rootField) {
+  const store = await loadKnowledgeStoreFromRoot(knowledgeRoot);
+  const simulation = simulateKnowledgePatch(
+    store,
+    patchState.operations,
+    patchState.patch.id
+  );
+  if (simulation.diagnostics.length > 0) {
     return {
-      resource: {
-        uri: `knowledge-schema://lookup/${target}`,
-        title: `Knowledge schema lookup: ${target}`,
-        description: "Focused lookup of a single root query field and its arguments."
-      },
-      source: {
-        kind: "runtime-schema",
-        queryType: queryType2.name
-      },
-      lookup: {
-        target,
-        kind: "root-field"
+      patchId: patchState.patch.id,
+      applied: false,
+      validation: {
+        ...validation,
+        valid: false,
+        diagnostics: simulation.diagnostics
       },
-      field: summarizeField(rootField),
-      parentType: queryType2.name
+      diagnostics: simulation.diagnostics,
+      deletedPatch: false
     };
   }
-  const objectType = schema.getType(target);
-  if (objectType && isObjectType(objectType)) {
-    const typeSummary = summarizeObjectType(objectType);
-    const rootFields = Object.values(queryType2.getFields()).filter((field) => unwrapType(field.type).name === target).map((field) => field.name);
+  await writeCanonicalFilesFromSimulation(
+    knowledgeRoot,
+    patchState.operations,
+    simulation.state
+  );
+  try {
+    await loadKnowledgeStoreFromRoot(knowledgeRoot);
+  } catch (error) {
+    const reloadDiagnostics = error instanceof KnowledgeStoreLoadError ? error.diagnostics.map(
+      (diagnostic) => buildDiagnostic({
+        severity: "critical",
+        code: diagnostic.kind,
+        message: diagnostic.message,
+        path: diagnostic.path ? [diagnostic.path] : void 0,
+        targetId: diagnostic.id
+      })
+    ) : [
+      buildDiagnostic({
+        severity: "critical",
+        code: "reload_failed",
+        message: "Canonical knowledge store reload failed after apply.",
+        patchId: patchState.patch.id
+      })
+    ];
     return {
-      resource: {
-        uri: `knowledge-schema://lookup/${target}`,
-        title: `Knowledge schema lookup: ${target}`,
-        description: "Focused lookup of a single GraphQL type and its nested traversal fields."
-      },
-      source: {
-        kind: "runtime-schema",
-        queryType: queryType2.name
-      },
-      lookup: {
-        target,
-        kind: "object-type"
-      },
-      type: typeSummary,
-      rootFields
+      patchId: patchState.patch.id,
+      applied: false,
+      validation,
+      diagnostics: reloadDiagnostics,
+      deletedPatch: false
     };
   }
-  throw new Error(
-    `Unknown schema lookup target "${target}". Use a root field name, a type name, or "Query".`
+  await rm(patchDir, { recursive: true, force: true });
+  return {
+    patchId: patchState.patch.id,
+    applied: true,
+    validation,
+    diagnostics: [],
+    deletedPatch: true
+  };
+}
+
+// packages/core/src/knowledge/patch/scope-audit.ts
+import { readdir as readdir2 } from "node:fs/promises";
+import { isAbsolute as isAbsolute2, relative, resolve as resolve5, sep as sep2 } from "node:path";
+import { z as z6 } from "zod/v4";
+var compareScopeWithEvidenceInputSchema = z6.object({
+  patchId: z6.string().min(1),
+  rootFolder: z6.string().trim().min(1).optional()
+});
+var compareScopeWithEvidenceResultSchema = z6.object({
+  patchId: z6.string().min(1),
+  rootFolder: z6.string().min(1),
+  scopeFiles: z6.array(z6.string()),
+  coveredFiles: z6.array(z6.string()),
+  omittedFiles: z6.array(
+    z6.object({
+      path: z6.string(),
+      reason: z6.string()
+    })
+  ),
+  uncoveredFiles: z6.array(z6.string()),
+  outOfRootEvidenceFiles: z6.array(z6.string()),
+  message: z6.string()
+});
+function toPosixPath(value) {
+  return value.replaceAll(sep2, "/");
+}
+function normalizeAuditedRoot(rootFolder) {
+  return resolve5(rootFolder);
+}
+function isPathWithinRoot(rootFolder, filePath) {
+  const relativePath = toPosixPath(relative(rootFolder, filePath));
+  return Boolean(
+    relativePath && relativePath !== ".." && !relativePath.startsWith("../")
   );
 }
-function buildKnowledgeSchemaLookupDocument(schema, target) {
-  return getLookupMetadata(schema, target);
+function normalizePathWithinRoot(rootFolder, filePath, outputRoot = rootFolder) {
+  let candidate;
+  if (isAbsolute2(filePath)) {
+    candidate = resolve5(filePath);
+  } else {
+    const repoRelativeCandidate = resolve5(outputRoot, filePath);
+    candidate = isPathWithinRoot(rootFolder, repoRelativeCandidate) ? repoRelativeCandidate : resolve5(rootFolder, filePath);
+  }
+  const relativePath = toPosixPath(relative(outputRoot, candidate));
+  if (!relativePath || relativePath === ".." || relativePath.startsWith("../")) {
+    return null;
+  }
+  return relativePath;
 }
-function createKnowledgeSchemaResourceText(schema) {
-  return JSON.stringify(buildKnowledgeSchemaDiscoveryDocument(schema), null, 2);
+async function collectScopeFiles(currentDir, auditedRoot, patchStorageRoot, outputRoot) {
+  if (currentDir === patchStorageRoot) {
+    return [];
+  }
+  const entries = await readdir2(currentDir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const entryPath = resolve5(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(
+        ...await collectScopeFiles(
+          entryPath,
+          auditedRoot,
+          patchStorageRoot,
+          outputRoot
+        )
+      );
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    const normalized = normalizePathWithinRoot(auditedRoot, entryPath, outputRoot);
+    if (normalized) {
+      files.push(normalized);
+    }
+  }
+  return files;
 }
-function createKnowledgeSchemaLookupText(schema, target) {
-  return JSON.stringify(
-    buildKnowledgeSchemaLookupDocument(schema, target),
-    null,
-    2
+async function compareScopeWithEvidence(envValue, input, cwd = process.cwd()) {
+  const parsedInput = compareScopeWithEvidenceInputSchema.parse(input);
+  const patchState = await readKnowledgePatch(envValue, parsedInput.patchId, cwd);
+  const auditedRoot = normalizeAuditedRoot(
+    parsedInput.rootFolder ?? patchState.patch.rootFolder
   );
-}
-function listKnowledgeSchemaTargets(schema) {
-  const queryType2 = schema.getQueryType();
-  if (!queryType2) {
-    throw new Error("Knowledge GraphQL schema has no root query type.");
+  const repositoryRoot = resolve5(cwd);
+  const effectiveState = await loadEffectiveKnowledgeStoreFromRoot(
+    resolveKnowledgeRoot2(envValue, cwd),
+    {
+      selectedPatchId: parsedInput.patchId
+    }
+  );
+  const effectivePatchIds = new Set(effectiveState.patchIds);
+  const coveredFiles = /* @__PURE__ */ new Set();
+  const outOfRootEvidenceFiles = /* @__PURE__ */ new Set();
+  for (const evidence of effectiveState.store.evidence) {
+    const provenance = effectiveState.provenance.get(evidence.id);
+    if (!provenance?.patchIds.some((patchId) => effectivePatchIds.has(patchId))) {
+      continue;
+    }
+    const sourcePath = evidence.location?.path;
+    if (!sourcePath) {
+      continue;
+    }
+    const normalized = normalizePathWithinRoot(
+      auditedRoot,
+      sourcePath,
+      repositoryRoot
+    );
+    if (normalized) {
+      coveredFiles.add(normalized);
+      continue;
+    }
+    outOfRootEvidenceFiles.add(sourcePath);
   }
-  const objectTypeNames = getObjectTypes(schema).map((type) => type.name);
-  const rootFieldNames = Object.keys(queryType2.getFields());
-  const targetNames = ["Query", ...rootFieldNames, ...objectTypeNames];
-  return Array.from(new Set(targetNames)).sort(
+  const omittedFiles = patchState.patch.omittedFiles.map((entry) => ({
+    path: entry.path,
+    reason: entry.reason
+  }));
+  const omittedFileSet = new Set(omittedFiles.map((entry) => entry.path));
+  const patchStorageRoot = resolve5(auditedRoot, KNOWLEDGE_PATCH_FOLDER_NAME);
+  const scopeFiles = (await collectScopeFiles(
+    auditedRoot,
+    auditedRoot,
+    patchStorageRoot,
+    repositoryRoot
+  )).sort((left, right) => left.localeCompare(right));
+  const uncoveredFiles = scopeFiles.filter(
+    (filePath) => !coveredFiles.has(filePath) && !omittedFileSet.has(filePath)
+  );
+  const sortedCoveredFiles = [...coveredFiles].sort(
+    (left, right) => left.localeCompare(right)
+  );
+  const sortedOutOfRootEvidenceFiles = [...outOfRootEvidenceFiles].sort(
     (left, right) => left.localeCompare(right)
   );
+  const message = uncoveredFiles.length > 0 ? `Recheck ${uncoveredFiles.length} uncovered file(s): add evidence-backed knowledge or mark them omitted with a reason.` : "Scope audit complete. No uncovered files remain.";
+  return compareScopeWithEvidenceResultSchema.parse({
+    patchId: parsedInput.patchId,
+    rootFolder: auditedRoot,
+    scopeFiles,
+    coveredFiles: sortedCoveredFiles,
+    omittedFiles,
+    uncoveredFiles,
+    outOfRootEvidenceFiles: sortedOutOfRootEvidenceFiles,
+    message
+  });
 }
 
-// packages/mcp/src/resources/knowledge-extraction.ts
-import { ResourceTemplate } from "@modelcontextprotocol/server";
-function createJsonResourceContent(uri, text) {
-  return {
-    contents: [
-      {
-        uri,
-        mimeType: "application/json",
-        text
-      }
-    ]
-  };
+// packages/core/src/knowledge/patch/index.ts
+async function executeKnowledgePatchAction(envValue, input, cwd = process.cwd()) {
+  switch (input.action) {
+    case "create":
+      return createKnowledgePatch(envValue, input.patch, cwd);
+    case "list":
+      return listKnowledgePatches(envValue, cwd);
+    case "get":
+      return readKnowledgePatch(envValue, input.patchId, cwd);
+    case "add_operation":
+      return addKnowledgePatchOperation(
+        envValue,
+        input.patchId,
+        input.operation,
+        cwd
+      );
+    case "update_operation":
+      return updateKnowledgePatchOperation(
+        envValue,
+        input.patchId,
+        input.update,
+        cwd
+      );
+    case "update_metadata":
+      return updateKnowledgePatchMetadata(
+        envValue,
+        input.patchId,
+        input.metadata,
+        cwd
+      );
+    case "delete_operation":
+      return deleteKnowledgePatchOperation(
+        envValue,
+        input.patchId,
+        input.operationId,
+        cwd
+      );
+    case "validate":
+      return validateKnowledgePatch(envValue, input.patchId, cwd);
+    case "close":
+      return closeKnowledgePatch(envValue, input.patchId, cwd);
+  }
 }
-function createMarkdownResourceContent(uri, text) {
-  return {
-    contents: [
-      {
-        uri,
-        mimeType: "text/markdown",
-        text
-      }
-    ]
-  };
+function buildKnowledgePatchToolText(result) {
+  return JSON.stringify(result, null, 2);
 }
+
+// packages/mcp/src/resources/knowledge-extraction.ts
+import { ResourceTemplate } from "@modelcontextprotocol/server";
 function listExtractionTypeNames() {
   return listKnowledgeExtractionResourceTypes().flatMap((definition) => [
     definition.collection,
@@ -3073,30 +3303,29 @@ function listExtractionTypeNames() {
   ]);
 }
 function registerKnowledgeExtractionResources(server) {
+  const resource = getKnowledgeResourceEntry(KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI);
+  if (!resource) {
+    throw new Error("Knowledge extraction resource metadata is missing.");
+  }
   server.registerResource(
-    "knowledge-extraction-types",
+    resource.name,
     KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
     {
-      title: "Knowledge Extraction Types",
-      description: "Canonical registry of knowledge types supported by the extraction workflow.",
-      mimeType: "application/json"
+      title: resource.title,
+      description: resource.description,
+      mimeType: resource.mimeType
     },
-    async (uri) => createJsonResourceContent(
-      uri.href,
-      JSON.stringify(buildKnowledgeExtractionTypeIndexDocument(), null, 2)
-    )
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
   server.registerResource(
     "knowledge-extraction-schema",
     new ResourceTemplate(KNOWLEDGE_EXTRACTION_SCHEMA_RESOURCE_URI, {
       list: async () => ({
-        resources: listKnowledgeExtractionResourceTypes().map((definition) => ({
-          uri: `ez-know://extraction/schema/${definition.collection}`,
-          name: definition.collection,
-          title: `${definition.title} Extraction Schema`,
-          description: `Runtime schema discovery for ${definition.title.toLowerCase()}.`,
-          mimeType: "application/json"
-        }))
+        resources: listKnowledgeResourceTemplateResources(
+          KNOWLEDGE_EXTRACTION_SCHEMA_RESOURCE_URI
+        )
       }),
       complete: {
         type: async (value) => listExtractionTypeNames().filter(
@@ -3109,29 +3338,17 @@ function registerKnowledgeExtractionResources(server) {
       description: "Runtime JSON-schema discovery for a supported knowledge type.",
       mimeType: "application/json"
     },
-    async (_uri, variables) => {
-      const type = variables.type;
-      if (typeof type !== "string" || type.length === 0) {
-        throw new Error("Resource type is required.");
-      }
-      const document = buildKnowledgeExtractionSchemaDocument(type);
-      return createJsonResourceContent(
-        `ez-know://extraction/schema/${document.type.collection}`,
-        JSON.stringify(document, null, 2)
-      );
-    }
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
   server.registerResource(
     "knowledge-extraction-guide",
     new ResourceTemplate(KNOWLEDGE_EXTRACTION_GUIDE_RESOURCE_URI, {
       list: async () => ({
-        resources: listKnowledgeExtractionResourceTypes().map((definition) => ({
-          uri: `ez-know://extraction/guide/${definition.collection}`,
-          name: definition.collection,
-          title: `${definition.title} Extraction Guide`,
-          description: `Checked-in extraction guidance for ${definition.title.toLowerCase()}.`,
-          mimeType: "text/markdown"
-        }))
+        resources: listKnowledgeResourceTemplateResources(
+          KNOWLEDGE_EXTRACTION_GUIDE_RESOURCE_URI
+        )
       }),
       complete: {
         type: async (value) => listExtractionTypeNames().filter(
@@ -3144,17 +3361,9 @@ function registerKnowledgeExtractionResources(server) {
       description: "Checked-in Markdown guidance for a supported knowledge type.",
       mimeType: "text/markdown"
     },
-    async (_uri, variables) => {
-      const type = variables.type;
-      if (typeof type !== "string" || type.length === 0) {
-        throw new Error("Resource type is required.");
-      }
-      const document = await buildKnowledgeExtractionGuideDocument(type);
-      return createMarkdownResourceContent(
-        `ez-know://extraction/guide/${document.type.collection}`,
-        document.markdown
-      );
-    }
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
 }
 
@@ -3218,6 +3427,104 @@ function registerKnowledgeGraphTool(server, getStore) {
   );
 }
 
+// packages/mcp/src/tools/legacy-resource-tools.ts
+import * as z8 from "zod/v4";
+function createTextToolResult(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ]
+  };
+}
+function serializeResourceError(error, uri) {
+  if (error instanceof KnowledgeResourceNotFoundError || error instanceof KnowledgeResourceUriError) {
+    return {
+      error: {
+        code: error.code,
+        message: error.message,
+        uri: error.uri
+      }
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      error: {
+        code: "RESOURCE_READ_FAILED",
+        message: error.message,
+        uri
+      }
+    };
+  }
+  return {
+    error: {
+      code: "RESOURCE_READ_FAILED",
+      message: "Unknown resource read failure.",
+      uri
+    }
+  };
+}
+function isLegacyResourceToolsEnabled(value = process.env.EZ_KNOW_LEGACY_RESOURCES) {
+  if (value === void 0) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized.length === 0) {
+    return false;
+  }
+  return !["0", "false", "off", "no"].includes(normalized);
+}
+function registerLegacyResourceTools(server) {
+  server.registerTool(
+    "list_mcp_resources",
+    {
+      title: "Legacy MCP Resource List",
+      description: "Lists the ez-know resources exposed through the legacy tool fallback.",
+      inputSchema: z8.object({})
+    },
+    async () => createTextToolResult({
+      resources: listKnowledgeResourceEntries()
+    })
+  );
+  server.registerTool(
+    "list_mcp_resource_templates",
+    {
+      title: "Legacy MCP Resource Templates",
+      description: "Lists the ez-know resource templates exposed through the legacy tool fallback.",
+      inputSchema: z8.object({})
+    },
+    async () => createTextToolResult({
+      resourceTemplates: listKnowledgeResourceTemplateEntries()
+    })
+  );
+  server.registerTool(
+    "read_mcp_resource",
+    {
+      title: "Legacy MCP Resource Read",
+      description: "Reads a single ez-know resource by URI through the legacy tool fallback.",
+      inputSchema: z8.object({
+        uri: z8.string().min(1)
+      })
+    },
+    async (input) => {
+      const parsedInput = z8.object({ uri: z8.string().min(1) }).parse(input);
+      try {
+        const result = await readKnowledgeResourceDocument(parsedInput.uri);
+        return createTextToolResult({
+          resource: result.resource,
+          contents: [result.content]
+        });
+      } catch (error) {
+        return createTextToolResult(
+          serializeResourceError(error, parsedInput.uri)
+        );
+      }
+    }
+  );
+}
+
 // packages/mcp/src/tools/knowledge-patch-apply.ts
 function registerKnowledgePatchApplyTool(server) {
   server.registerTool(
@@ -3274,43 +3581,29 @@ function registerKnowledgePatchTool(server) {
 
 // packages/mcp/src/resources/knowledge-schema.ts
 import { ResourceTemplate as ResourceTemplate2 } from "@modelcontextprotocol/server";
-function createJsonResourceContent2(uri, text) {
-  return {
-    contents: [
-      {
-        uri,
-        mimeType: "application/json",
-        text
-      }
-    ]
-  };
-}
 function registerKnowledgeSchemaResources(server) {
+  const resource = getKnowledgeResourceEntry(KNOWLEDGE_SCHEMA_RESOURCE_URI);
+  if (!resource) {
+    throw new Error("Knowledge schema resource metadata is missing.");
+  }
   server.registerResource(
-    "knowledge-schema",
+    resource.name,
     KNOWLEDGE_SCHEMA_RESOURCE_URI,
     {
-      title: "Knowledge GraphQL Schema",
-      description: "Canonical runtime GraphQL schema discovery payload for the knowledge layer.",
-      mimeType: "application/json"
+      title: resource.title,
+      description: resource.description,
+      mimeType: resource.mimeType
     },
-    async (uri) => createJsonResourceContent2(
-      uri.href,
-      createKnowledgeSchemaResourceText(knowledgeGraphSchema)
-    )
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
   server.registerResource(
     "knowledge-schema-lookup",
     new ResourceTemplate2(KNOWLEDGE_SCHEMA_LOOKUP_URI, {
       list: async () => ({
-        resources: listKnowledgeSchemaTargets(knowledgeGraphSchema).map(
-          (target) => ({
-            uri: `knowledge-schema://lookup/${target}`,
-            name: target,
-            title: `Knowledge schema lookup: ${target}`,
-            description: target === "Query" ? "Focused lookup of the root query fields." : `Focused lookup of ${target}.`,
-            mimeType: "application/json"
-          })
+        resources: listKnowledgeResourceTemplateResources(
+          KNOWLEDGE_SCHEMA_LOOKUP_URI
         )
       }),
       complete: {
@@ -3324,27 +3617,19 @@ function registerKnowledgeSchemaResources(server) {
       description: "Focused runtime GraphQL schema lookup for a type name, root field, or Query.",
       mimeType: "application/json"
     },
-    async (_uri, variables) => {
-      const target = variables.target;
-      if (typeof target !== "string" || target.length === 0) {
-        throw new Error("Resource target is required.");
-      }
-      return createJsonResourceContent2(
-        `knowledge-schema://lookup/${target}`,
-        createKnowledgeSchemaLookupText(knowledgeGraphSchema, target)
-      );
-    }
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
 }
 
 // packages/mcp/src/run.ts
-async function startMcpServer() {
-  const server = new McpServer({
-    name: "ez-know",
-    version: "0.1.0"
-  });
+function registerMcpServerCapabilities(server) {
   registerKnowledgeSchemaResources(server);
   registerKnowledgeExtractionResources(server);
+  if (isLegacyResourceToolsEnabled()) {
+    registerLegacyResourceTools(server);
+  }
   registerKnowledgeGraphTool(server, async () => {
     const effectiveState = await loadEffectiveKnowledgeStoreFromEnv(
       process.env.EZ_KNOW_ROOT
@@ -3354,6 +3639,13 @@ async function startMcpServer() {
   registerKnowledgePatchTool(server);
   registerKnowledgePatchApplyTool(server);
   registerCompareScopeWithEvidenceTool(server);
+}
+async function startMcpServer() {
+  const server = new McpServer({
+    name: "ez-know",
+    version: "0.1.0"
+  });
+  registerMcpServerCapabilities(server);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
@@ -3448,7 +3740,7 @@ import {
   OpenAPIRegistry,
   OpenApiGeneratorV3
 } from "@asteasolutions/zod-to-openapi";
-import { z as z8 } from "zod/v4";
+import { z as z9 } from "zod/v4";
 
 // packages/rest/src/schema-registry.ts
 var REST_COLLECTION_SCHEMA_REGISTRY = {
@@ -3526,14 +3818,14 @@ var REST_CONFIDENCE_SCHEMA = confidenceSchema;
 var REST_CERTAINTY_SCHEMA = certaintySchema;
 
 // packages/rest/src/openapi.ts
-extendZodWithOpenApi2(z8);
+extendZodWithOpenApi2(z9);
 var openApiRegistry = new OpenAPIRegistry();
 var restErrorResponseSchema = openApiRegistry.register(
   "RestErrorResponse",
-  z8.object({
-    error: z8.object({
-      code: z8.string(),
-      message: z8.string()
+  z9.object({
+    error: z9.object({
+      code: z9.string(),
+      message: z9.string()
     })
   }).openapi({
     description: "Standard REST error envelope."
@@ -3541,51 +3833,51 @@ var restErrorResponseSchema = openApiRegistry.register(
 );
 var restHealthResponseSchema = openApiRegistry.register(
   "RestHealthResponse",
-  z8.object({
-    service: z8.string(),
-    status: z8.literal("ok"),
-    storeAvailable: z8.boolean()
+  z9.object({
+    service: z9.string(),
+    status: z9.literal("ok"),
+    storeAvailable: z9.boolean()
   }).openapi({
     description: "Service health payload."
   })
 );
 var restPatchSummarySchema = openApiRegistry.register(
   "RestPatchSummary",
-  z8.object({
-    id: z8.string(),
-    status: z8.string(),
-    title: z8.string(),
-    description: z8.string().optional(),
-    rootFolder: z8.string(),
-    omittedFiles: z8.array(
-      z8.object({
-        path: z8.string(),
-        reason: z8.string()
+  z9.object({
+    id: z9.string(),
+    status: z9.string(),
+    title: z9.string(),
+    description: z9.string().optional(),
+    rootFolder: z9.string(),
+    omittedFiles: z9.array(
+      z9.object({
+        path: z9.string(),
+        reason: z9.string()
       })
     ),
-    operationCount: z8.number().int().min(0),
-    createdAt: z8.string(),
-    updatedAt: z8.string()
+    operationCount: z9.number().int().min(0),
+    createdAt: z9.string(),
+    updatedAt: z9.string()
   }).openapi({
     description: "Patch inventory summary."
   })
 );
 var restPatchProvenanceEntrySchema = openApiRegistry.register(
   "RestPatchProvenanceEntry",
-  z8.object({
-    patchIds: z8.array(z8.string()),
-    patched: z8.boolean()
+  z9.object({
+    patchIds: z9.array(z9.string()),
+    patched: z9.boolean()
   }).openapi({
     description: "Patch provenance for a previewed record."
   })
 );
 var restPatchFacetItemSchema = openApiRegistry.register(
   "RestPatchFacetItem",
-  z8.object({
-    id: z8.string(),
-    label: z8.string(),
-    patched: z8.boolean(),
-    provenancePatchIds: z8.array(z8.string())
+  z9.object({
+    id: z9.string(),
+    label: z9.string(),
+    patched: z9.boolean(),
+    provenancePatchIds: z9.array(z9.string())
   }).openapi({
     description: "Patch-aware facet option."
   })
@@ -3600,7 +3892,7 @@ var certaintyRef = openApiRegistry.register(
 );
 var restOpenApiDocumentSchema = openApiRegistry.register(
   "RestOpenApiDocument",
-  z8.record(z8.string(), z8.unknown())
+  z9.record(z9.string(), z9.unknown())
 );
 var previewCollectionResponseSchemas = /* @__PURE__ */ new Map();
 for (const collection of REST_COLLECTIONS) {
@@ -3621,24 +3913,24 @@ for (const collection of REST_COLLECTIONS) {
   const previewItemSchema = openApiRegistry.register(
     `${schemaDefinition.itemName}PreviewRecord`,
     itemSchemaSource.extend({
-      patched: z8.boolean(),
-      provenancePatchIds: z8.array(z8.string())
+      patched: z9.boolean(),
+      provenancePatchIds: z9.array(z9.string())
     })
   );
   const collectionResponseSchema = openApiRegistry.register(
     schemaDefinition.collectionResponseName,
-    z8.object({
-      items: z8.array(itemSchema),
-      count: z8.number().int().min(0)
+    z9.object({
+      items: z9.array(itemSchema),
+      count: z9.number().int().min(0)
     }).openapi({
       description: `${schemaDefinition.itemName} collection response.`
     })
   );
   const previewCollectionResponseSchema = openApiRegistry.register(
     `${schemaDefinition.itemName}PreviewCollectionResponse`,
-    z8.object({
-      items: z8.array(previewItemSchema),
-      count: z8.number().int().min(0)
+    z9.object({
+      items: z9.array(previewItemSchema),
+      count: z9.number().int().min(0)
     }).openapi({
       description: `${schemaDefinition.itemName} preview collection response.`
     })
@@ -3649,7 +3941,7 @@ for (const collection of REST_COLLECTIONS) {
   );
   const itemResponseSchema = openApiRegistry.register(
     schemaDefinition.itemResponseName,
-    z8.object({
+    z9.object({
       item: itemSchema
     }).openapi({
       description: `${schemaDefinition.itemName} item response.`
@@ -3691,8 +3983,8 @@ for (const collection of REST_COLLECTIONS) {
     path: `${REST_V1_PREFIX}/${collection.route}/{id}`,
     summary: `Get ${collection.label.toLowerCase()} by id`,
     request: {
-      params: z8.object({
-        id: z8.string()
+      params: z9.object({
+        id: z9.string()
       })
     },
     responses: {
@@ -3725,25 +4017,25 @@ for (const collection of REST_COLLECTIONS) {
 }
 var restPatchInventoryResponseSchema = openApiRegistry.register(
   "RestPatchInventoryResponse",
-  z8.object({
-    items: z8.array(restPatchSummarySchema),
-    count: z8.number().int().min(0)
+  z9.object({
+    items: z9.array(restPatchSummarySchema),
+    count: z9.number().int().min(0)
   }).openapi({
     description: "Patch inventory response."
   })
 );
 var restPatchPreviewResponseSchema = openApiRegistry.register(
   "RestPatchPreviewResponse",
-  z8.object({
-    selectedPatchId: z8.string(),
-    prefixPatchIds: z8.array(z8.string()),
-    patches: z8.array(restPatchSummarySchema),
-    provenance: z8.record(z8.string(), restPatchProvenanceEntrySchema),
-    facets: z8.object({
-      domains: z8.array(restPatchFacetItemSchema),
-      entities: z8.array(restPatchFacetItemSchema)
+  z9.object({
+    selectedPatchId: z9.string(),
+    prefixPatchIds: z9.array(z9.string()),
+    patches: z9.array(restPatchSummarySchema),
+    provenance: z9.record(z9.string(), restPatchProvenanceEntrySchema),
+    facets: z9.object({
+      domains: z9.array(restPatchFacetItemSchema),
+      entities: z9.array(restPatchFacetItemSchema)
     }).strict(),
-    collections: z8.object({
+    collections: z9.object({
       domains: previewCollectionResponseSchemas.get("domains"),
       entities: previewCollectionResponseSchemas.get("entities"),
       relationships: previewCollectionResponseSchemas.get("relationships"),
@@ -3788,8 +4080,8 @@ openApiRegistry.registerPath({
   path: `${REST_V1_PREFIX}/${REST_PATCH_PREVIEW_PATH}`,
   summary: "Preview a patch prefix",
   request: {
-    params: z8.object({
-      patchId: z8.string()
+    params: z9.object({
+      patchId: z9.string()
     })
   },
   responses: {
@@ -3858,7 +4150,7 @@ openApiRegistry.registerPath({
       description: "Default Response",
       content: {
         "text/html": {
-          schema: z8.string()
+          schema: z9.string()
         }
       }
     }
@@ -4612,7 +4904,7 @@ function renderHelpText() {
     "",
     "Launch modes:",
     "  init",
-    "    Prompts for a skills folder and installs bundled reference skills.",
+    "    Prompts for a skills folder and installs bundled ez-know skills.",
     "    Config: interactive terminal",
     "",
     "  mcp",