@hasna/knowledge 0.2.15 → 0.2.17

package/bin/open-knowledge-mcp.js

@@ -13660,10 +13660,11 @@ import { existsSync as existsSync7, readFileSync as readFileSync7, writeFileSync
 // package.json
 var package_default = {
   name: "@hasna/knowledge",
-  version: "0.2.15",
+  version: "0.2.17",
   description: "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   type: "module",
   bin: {
+    knowledge: "bin/open-knowledge.js",
     "open-knowledge": "bin/open-knowledge.js",
     "open-knowledge-mcp": "bin/open-knowledge-mcp.js"
   },
@@ -14134,8 +14135,8 @@ function createArtifactStore(config2, workspace) {
   return new LocalArtifactStore(workspace.artifactsDir);
 }
 
-// src/embeddings.ts
-import { createHash } from "crypto";
+// src/agent.ts
+import { randomUUID as randomUUID3 } from "crypto";
 
 // src/knowledge-db.ts
 import { Database } from "bun:sqlite";
@@ -14441,6 +14442,7 @@ function getKnowledgeDbStats(path) {
 }
 
 // src/providers.ts
+import { randomUUID as randomUUID2 } from "crypto";
 var DEFAULT_PROVIDER_SETTINGS = {
   openai: {
     api_key_env: "OPENAI_API_KEY",
@@ -14496,7 +14498,7 @@ var BUILTIN_ALIASES = {
   "deepseek-reasoning": "deepseek:deepseek-reasoner"
 };
 function providerConfig(config2) {
-  return config2.providers ?? {};
+  return config2?.providers ?? {};
 }
 function providerSettings(config2, provider) {
   const configured = providerConfig(config2)[provider] ?? {};
@@ -14570,6 +14572,80 @@ function assertProviderCredentials(provider, config2, env = process.env) {
     throw new Error(`Missing ${status.api_key_env} for ${provider}. Set the env var to use this provider.`);
   return status;
 }
+async function defaultFactory(provider) {
+  if (provider === "openai") {
+    const { createOpenAI } = await import("@ai-sdk/openai");
+    return createOpenAI;
+  }
+  if (provider === "anthropic") {
+    const { createAnthropic } = await import("@ai-sdk/anthropic");
+    return createAnthropic;
+  }
+  const { createDeepSeek } = await import("@ai-sdk/deepseek");
+  return createDeepSeek;
+}
+async function createAiSdkProviderRegistry(options = {}) {
+  const { createProviderRegistry } = await import("ai");
+  const env = options.env ?? process.env;
+  const providers = {};
+  for (const provider of Object.keys(DEFAULT_PROVIDER_SETTINGS)) {
+    const settings = providerSettings(options.config, provider);
+    const apiKey = env[settings.api_key_env];
+    if (!apiKey)
+      continue;
+    const factory = options.factories?.[provider] ?? await defaultFactory(provider);
+    providers[provider] = factory({ apiKey, baseURL: settings.base_url });
+  }
+  return createProviderRegistry(providers);
+}
+async function languageModelFor(aliasOrRef, options = {}) {
+  const modelRef = resolveModelRef(aliasOrRef, options.config);
+  const parsed = parseModelRef(modelRef);
+  assertProviderCredentials(parsed.provider, options.config, options.env);
+  const registry2 = await createAiSdkProviderRegistry(options);
+  return registry2.languageModel(modelRef);
+}
+function usageNumber(usage, keys) {
+  for (const key of keys) {
+    const value = usage[key];
+    if (typeof value === "number" && Number.isFinite(value))
+      return value;
+  }
+  return 0;
+}
+function normalizeAiSdkUsage(input) {
+  const usage = input.usage ?? {};
+  return {
+    provider: input.provider,
+    model: input.model,
+    input_tokens: usageNumber(usage, ["inputTokens", "promptTokens", "input_tokens", "prompt_tokens"]),
+    output_tokens: usageNumber(usage, ["outputTokens", "completionTokens", "output_tokens", "completion_tokens"]),
+    cost_usd: input.costUsd ?? 0,
+    metadata: {
+      usage,
+      provider_metadata: input.providerMetadata ?? {}
+    }
+  };
+}
+function recordProviderUsage(db, input) {
+  const id = `usage_${randomUUID2()}`;
+  db.run(`INSERT INTO provider_usage (id, run_id, provider, model, input_tokens, output_tokens, cost_usd, metadata_json, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+    id,
+    input.run_id ?? null,
+    input.provider,
+    input.model,
+    input.input_tokens,
+    input.output_tokens,
+    input.cost_usd,
+    JSON.stringify(input.metadata),
+    input.created_at ?? new Date().toISOString()
+  ]);
+  return id;
+}
+
+// src/retrieval.ts
+import { createHash as createHash2 } from "crypto";
 
 // src/provenance.ts
 function isStaleStatus(status) {
@@ -14614,6 +14690,7 @@ function withProvenance(metadata, provenance) {
 }
 
 // src/embeddings.ts
+import { createHash } from "crypto";
 var DEFAULT_EMBEDDING_MODEL_REF = "openai:text-embedding-3-small";
 var DEFAULT_EMBEDDING_DIMENSIONS = 1536;
 function embeddingConfig(config2) {
@@ -14948,1242 +15025,1547 @@ async function searchVectorIndex(options) {
   }
 }
 
-// src/outbox-consume.ts
-import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
-import { basename } from "path";
-
-// src/safety.ts
-import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
-import { relative as relative2, resolve as resolve2, sep as sep2 } from "path";
-function envEnabled(name) {
-  const value = process.env[name];
-  return value === "1" || value === "true" || value === "yes";
-}
-function resolveSafetyPolicy(config2, workspace) {
-  const extended = config2;
-  const configuredBuckets = new Set(extended.safety?.network?.allowed_s3_buckets ?? []);
-  if (config2.storage.type === "s3" && config2.storage.s3?.bucket)
-    configuredBuckets.add(config2.storage.s3.bucket);
-  if (process.env.HASNA_KNOWLEDGE_ALLOWED_S3_BUCKETS) {
-    for (const bucket of process.env.HASNA_KNOWLEDGE_ALLOWED_S3_BUCKETS.split(",").map((entry) => entry.trim()).filter(Boolean)) {
-      configuredBuckets.add(bucket);
-    }
-  }
-  return {
-    mode: config2.mode,
-    allowWriteRoots: [
-      workspace.home,
-      workspace.artifactsDir,
-      workspace.cacheDir,
-      workspace.exportsDir,
-      workspace.indexesDir,
-      workspace.logsDir,
-      workspace.runsDir,
-      workspace.schemasDir,
-      workspace.wikiDir
-    ].map((entry) => resolve2(entry)),
-    readOnlySourceAccess: true,
-    network: {
-      webSearchEnabled: extended.safety?.network?.web_search_enabled ?? envEnabled("HASNA_KNOWLEDGE_WEB_SEARCH"),
-      s3ReadsEnabled: extended.safety?.network?.s3_reads_enabled ?? envEnabled("HASNA_KNOWLEDGE_ALLOW_S3_READS"),
-      allowedS3Buckets: [...configuredBuckets].sort()
-    },
-    redaction: {
-      enabled: extended.safety?.redaction?.enabled ?? true
-    },
-    approvals: {
-      generatedWritesRequireApproval: extended.safety?.approvals?.generated_writes_require_approval ?? true
-    }
-  };
-}
-function isInside(root, target) {
-  const rel = relative2(root, target);
-  return rel === "" || !rel.startsWith("..") && rel !== ".." && !rel.startsWith(`..${sep2}`);
-}
-function assertWriteAllowed(targetPath, policy) {
-  const resolved = resolve2(targetPath);
-  if (!policy.allowWriteRoots.some((root) => isInside(root, resolved))) {
-    throw new Error(`Safety policy denied write outside .hasna/apps/knowledge: ${targetPath}`);
-  }
-}
-function assertS3ReadAllowed(uri, policy) {
-  const parsed = new URL(uri);
-  const bucket = parsed.hostname;
-  if (!policy.network.s3ReadsEnabled) {
-    throw new Error("Safety policy denied S3 read. Set safety.network.s3_reads_enabled=true or HASNA_KNOWLEDGE_ALLOW_S3_READS=1.");
-  }
-  if (!policy.network.allowedS3Buckets.includes(bucket)) {
-    throw new Error(`Safety policy denied S3 bucket "${bucket}". Add it to safety.network.allowed_s3_buckets or HASNA_KNOWLEDGE_ALLOWED_S3_BUCKETS.`);
+// src/search.ts
+function parseJsonObject2(value) {
+  if (!value)
+    return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
   }
 }
-function assertWebSearchAllowed(policy) {
-  if (!policy.network.webSearchEnabled) {
-    throw new Error("Safety policy denied web search. Set safety.network.web_search_enabled=true or HASNA_KNOWLEDGE_WEB_SEARCH=1.");
+function metadataString2(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "string" && value.length > 0)
+      return value;
   }
+  return null;
 }
-var REDACTION_PATTERNS = [
-  { type: "private_key_block", severity: "high", regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, replacement: "[REDACTED:private_key_block]" },
-  { type: "secret_assignment", severity: "high", regex: /\b(?:api[_-]?key|secret|token|password)\s*[:=]\s*['"]?[^'"\s]{8,}/gi, replacement: "[REDACTED:secret_assignment]" },
-  { type: "openai_api_key", severity: "high", regex: /\bsk-[A-Za-z0-9_-]{20,}\b/g, replacement: "[REDACTED:openai_api_key]" },
-  { type: "anthropic_api_key", severity: "high", regex: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g, replacement: "[REDACTED:anthropic_api_key]" },
-  { type: "aws_access_key_id", severity: "high", regex: /\bA(?:KIA|SIA)[A-Z0-9]{16}\b/g, replacement: "[REDACTED:aws_access_key_id]" }
-];
-function redactSecrets(text, policy) {
-  if (policy && !policy.redaction.enabled)
-    return { text, findings: [] };
-  let output = text;
-  const findings = [];
-  for (const pattern of REDACTION_PATTERNS) {
-    output = output.replace(pattern.regex, (match, ...args) => {
-      const offset = typeof args.at(-2) === "number" ? args.at(-2) : output.indexOf(match);
-      findings.push({
-        type: pattern.type,
-        severity: pattern.severity,
-        start: Math.max(0, offset),
-        end: Math.max(0, offset + match.length)
-      });
-      return pattern.replacement;
-    });
+function metadataNumber2(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "number" && Number.isFinite(value))
+      return value;
   }
-  return { text: output, findings };
+  return null;
 }
-function auditId(input) {
-  return `audit_${createHash2("sha256").update(`${input.event_type}\x00${input.action}\x00${input.target_uri ?? ""}\x00${input.created_at ?? ""}\x00${JSON.stringify(input.metadata ?? {})}\x00${randomUUID2()}`).digest("hex").slice(0, 24)}`;
+function unique(values) {
+  return Array.from(new Set(values));
 }
-function recordAuditEvent(db, input) {
-  const createdAt = input.created_at ?? new Date().toISOString();
-  const id = auditId({ ...input, created_at: createdAt });
-  db.run(`INSERT INTO audit_events (id, event_type, action, target_uri, decision, metadata_json, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?)`, [
-    id,
-    input.event_type,
-    input.action,
-    input.target_uri ?? null,
-    input.decision,
-    JSON.stringify(input.metadata ?? {}),
-    createdAt
-  ]);
-  return id;
+function queryTerms(query) {
+  const terms = query.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [];
+  return unique(terms.filter((term) => term.length > 0)).slice(0, 16);
 }
-function recordRedactionFindings(db, input) {
-  const createdAt = input.created_at ?? new Date().toISOString();
-  for (const finding of input.findings) {
-    db.run(`INSERT INTO redaction_findings (id, source_uri, run_id, severity, finding_type, metadata_json, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`, [
-      `redact_${randomUUID2()}`,
-      input.source_uri ?? null,
-      input.run_id ?? null,
-      finding.severity,
-      finding.type,
-      JSON.stringify({ ...input.metadata ?? {}, start: finding.start, end: finding.end }),
-      createdAt
-    ]);
-  }
-  return input.findings.length;
+function ftsQueryForTerms(terms) {
+  if (terms.length === 0)
+    return null;
+  return terms.map((term) => `${term}*`).join(" OR ");
 }
-
-// src/outbox-consume.ts
-function stableId2(prefix, value) {
-  return `${prefix}_${createHash3("sha256").update(value).digest("hex").slice(0, 20)}`;
+function escapeLikeTerm(term) {
+  return term.replace(/[\\%_]/g, (char) => `\\${char}`);
 }
-function asObject(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+function likeParams(terms, fieldsPerTerm) {
+  return terms.flatMap((term) => Array.from({ length: fieldsPerTerm }, () => `%${escapeLikeTerm(term)}%`));
 }
-function asString(value) {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
+function scoreFromRank(rank, index) {
+  const rankScore = Number.isFinite(rank) ? 1 / (1 + Math.abs(rank)) : 0;
+  const orderScore = 1 / (1 + index);
+  return roundScore(Math.max(rankScore, orderScore));
 }
-function buildSourceRef(event) {
-  const explicit = asString(event.source_ref) ?? asString(event.source_uri) ?? asString(event.uri);
-  if (explicit)
-    return explicit;
-  const fileId = asString(event.file_id);
-  if (fileId) {
-    const revision = asString(event.revision_id) ?? asString(event.revision);
-    const fileRef = `open-files://file/${encodeURIComponent(fileId)}`;
-    return revision ? `${fileRef}/revision/${encodeURIComponent(revision)}` : fileRef;
-  }
-  const sourceId = asString(event.source_id);
-  const path = asString(event.path);
-  if (sourceId && path) {
-    return `open-files://source/${encodeURIComponent(sourceId)}/path/${encodeURIComponent(path)}`;
-  }
-  throw new Error("Outbox event is missing source_ref, file_id, or source_id/path.");
+function catalogScore(haystack, terms) {
+  if (terms.length === 0)
+    return 0;
+  const matched = terms.filter((term) => haystack.includes(term)).length;
+  if (matched === 0)
+    return 0;
+  return roundScore(Math.min(0.85, 0.35 + matched / terms.length * 0.5));
 }
-function baseSourceUri(sourceRef, parsed) {
-  if (parsed.kind === "open-files" && parsed.entity === "file" && parsed.revision_id) {
-    return sourceRef.replace(/\/revision\/[^/]+$/, "");
-  }
-  return sourceRef;
+function semanticScore(score) {
+  return roundScore(Math.max(0, Math.min(1, (score + 1) / 2)));
 }
-function hashFromEvent(event) {
-  return asString(event.hash) ?? asString(event.checksum) ?? asString(event.sha256) ?? null;
+function roundScore(score) {
+  return Number(score.toFixed(6));
 }
-function revisionFromEvent(event, parsed, hash2) {
-  return asString(event.revision_id) ?? asString(event.revision) ?? asString(event.version_id) ?? (parsed.kind === "open-files" ? parsed.revision_id : undefined) ?? hash2 ?? null;
+function combinedScore(scores, citation) {
+  const keyword = scores.keyword ?? 0;
+  const semantic = scores.semantic ?? 0;
+  const catalog = scores.catalog ?? 0;
+  const citationBoost = citation?.chunk_id ? 0.05 : 0;
+  return roundScore(Math.min(1, keyword * 0.55 + semantic * 0.4 + catalog * 0.35 + citationBoost));
 }
-function eventType(event) {
-  return (asString(event.event) ?? asString(event.type) ?? asString(event.action) ?? asString(event.change_type) ?? "changed").toLowerCase();
+function existingProvenance(metadata) {
+  const provenance = metadata.provenance;
+  return provenance && typeof provenance === "object" && !Array.isArray(provenance) ? provenance : null;
 }
-function titleFromEvent(event) {
-  const path = asString(event.path);
-  return asString(event.title) ?? asString(event.name) ?? (path ? basename(path) : null);
+function provenanceForChunk2(row) {
+  const metadata = parseJsonObject2(row.chunk_metadata_json);
+  const existing = existingProvenance(metadata);
+  if (existing)
+    return existing;
+  if (!row.source_revision_id && !row.source_uri)
+    return null;
+  return sourceProvenance({
+    source_ref: metadataString2(metadata, ["source_ref"]),
+    source_uri: row.source_uri ?? metadataString2(metadata, ["source_uri"]),
+    source_kind: row.source_kind ?? metadataString2(metadata, ["source_kind"]),
+    source_revision_id: row.source_revision_id,
+    revision: row.revision ?? metadataString2(metadata, ["revision"]),
+    hash: row.hash ?? metadataString2(metadata, ["hash"]),
+    chunk_id: row.chunk_id,
+    start_offset: row.start_offset ?? metadataNumber2(metadata, ["start_offset"]),
+    end_offset: row.end_offset ?? metadataNumber2(metadata, ["end_offset"]),
+    status: metadataString2(metadata, ["status"]),
+    resolver: "open-files-read-only"
+  });
 }
-function normalizeEvent(event, now) {
-  const sourceRef = buildSourceRef(event);
-  const parsed = parseSourceRef(sourceRef);
-  const hash2 = hashFromEvent(event);
-  return {
-    raw: event,
-    eventType: eventType(event),
-    sourceRef,
-    sourceUri: baseSourceUri(sourceRef, parsed),
-    kind: parsed.kind,
-    title: titleFromEvent(event),
-    revision: revisionFromEvent(event, parsed, hash2),
-    hash: hash2,
-    status: asString(event.status)?.toLowerCase() ?? null,
-    updatedAt: asString(event.updated_at) ?? now,
-    acl: event.permissions ?? event.acl ?? undefined
-  };
-}
-function parseOutboxText(text) {
-  const trimmed = text.trim();
-  if (!trimmed)
+function selectFtsChunks(db, ftsQuery, limit) {
+  if (!ftsQuery)
     return [];
-  if (trimmed.startsWith("[")) {
-    const parsed = JSON.parse(trimmed);
-    if (!Array.isArray(parsed))
-      throw new Error("Outbox array parse failed.");
-    return parsed.map((entry) => {
-      const event = asObject(entry);
-      if (!event)
-        throw new Error("Outbox array entries must be objects.");
-      return event;
-    });
-  }
-  if (trimmed.startsWith("{")) {
-    try {
-      const parsed = JSON.parse(trimmed);
-      const object2 = asObject(parsed);
-      if (!object2)
-        throw new Error("Outbox object parse failed.");
-      if (Array.isArray(object2.events)) {
-        return object2.events.map((entry) => {
-          const event = asObject(entry);
-          if (!event)
-            throw new Error("Outbox events entries must be objects.");
-          return event;
-        });
-      }
-      if ("source_ref" in object2 || "source_uri" in object2 || "file_id" in object2)
-        return [object2];
-    } catch (error48) {
-      const lines = trimmed.split(/\r?\n/).filter((line) => line.trim().length > 0);
-      if (lines.length <= 1)
-        throw error48;
-      return lines.map((line) => {
-        const event = asObject(JSON.parse(line));
-        if (!event)
-          throw new Error("Outbox JSONL entries must be objects.");
-        return event;
-      });
-    }
-  }
-  return trimmed.split(/\r?\n/).filter((line) => line.trim().length > 0).map((line) => {
-    const event = asObject(JSON.parse(line));
-    if (!event)
-      throw new Error("Outbox JSONL entries must be objects.");
-    return event;
-  });
+  return db.query(`SELECT
+       chunks_fts.chunk_id,
+       c.kind AS chunk_kind,
+       c.wiki_page_id,
+       c.text,
+       c.token_count,
+       c.start_offset,
+       c.end_offset,
+       c.metadata_json AS chunk_metadata_json,
+       c.source_revision_id,
+       sr.revision,
+       sr.hash,
+       s.uri AS source_uri,
+       s.kind AS source_kind,
+       s.title AS source_title,
+       wp.path AS wiki_path,
+       wp.title AS wiki_title,
+       wp.artifact_uri AS wiki_artifact_uri,
+       wp.content_hash AS wiki_content_hash,
+       wp.status AS wiki_status,
+       wp.metadata_json AS wiki_metadata_json,
+       bm25(chunks_fts) AS rank
+     FROM chunks_fts
+     JOIN chunks c ON c.id = chunks_fts.chunk_id
+     LEFT JOIN source_revisions sr ON sr.id = c.source_revision_id
+     LEFT JOIN sources s ON s.id = sr.source_id
+     LEFT JOIN wiki_pages wp ON wp.id = c.wiki_page_id
+     WHERE chunks_fts MATCH ?
+     ORDER BY rank ASC
+     LIMIT ?`).all(ftsQuery, limit);
 }
-async function readS3Text(uri, config2, safetyPolicy) {
-  const parsed = new URL(uri);
-  const bucket = parsed.hostname;
-  const key = decodeURIComponent(parsed.pathname.replace(/^\/+/, ""));
-  if (!bucket || !key)
-    throw new Error(`Invalid S3 outbox URI: ${uri}`);
-  if (safetyPolicy)
-    assertS3ReadAllowed(uri, safetyPolicy);
-  const [{ S3Client, GetObjectCommand }, { fromIni }] = await Promise.all([
-    import("@aws-sdk/client-s3"),
-    import("@aws-sdk/credential-providers")
-  ]);
-  const s3Config = config2?.storage.type === "s3" && config2.storage.s3?.bucket === bucket ? config2.storage.s3 : undefined;
-  const client = new S3Client({
-    region: s3Config?.region,
-    credentials: s3Config?.profile ? fromIni({ profile: s3Config.profile }) : undefined,
-    maxAttempts: s3Config?.max_attempts
-  });
-  const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
-  if (!response.Body)
-    return "";
-  return await response.Body.transformToString();
+function catalogWhere(fields, terms) {
+  if (terms.length === 0)
+    return "1 = 0";
+  const clauses = terms.map(() => `(${fields.map((field) => `lower(COALESCE(${field}, '')) LIKE ? ESCAPE '\\'`).join(" OR ")})`);
+  return clauses.join(" OR ");
 }
-async function readOutboxInput(input, config2, safetyPolicy) {
-  if (input.startsWith("s3://"))
-    return readS3Text(input, config2, safetyPolicy);
-  if (!existsSync4(input))
-    throw new Error(`Outbox not found: ${input}`);
-  return readFileSync4(input, "utf8");
+function selectWikiPages(db, terms, limit) {
+  const fields = ["path", "title", "artifact_uri", "metadata_json"];
+  return db.query(`SELECT id, path, title, artifact_uri, content_hash, status, metadata_json
+     FROM wiki_pages
+     WHERE status = 'active' AND (${catalogWhere(fields, terms)})
+     ORDER BY updated_at DESC
+     LIMIT ?`).all(...likeParams(terms, fields.length), limit);
 }
-function mergeJson(existing, patch) {
-  let base = {};
-  if (existing) {
-    try {
-      base = asObject(JSON.parse(existing)) ?? {};
-    } catch {
-      base = {};
-    }
-  }
-  return JSON.stringify({ ...base, ...patch });
+function selectKnowledgeIndexes(db, terms, limit) {
+  const fields = ["kind", "name", "shard_key", "artifact_uri", "metadata_json"];
+  return db.query(`SELECT id, kind, name, artifact_uri, shard_key, metadata_json
+     FROM knowledge_indexes
+     WHERE ${catalogWhere(fields, terms)}
+     ORDER BY updated_at DESC
+     LIMIT ?`).all(...likeParams(terms, fields.length), limit);
 }
-function ensureSource(db, event, now) {
-  const id = stableId2("src", event.sourceUri);
-  db.run(`INSERT INTO sources (id, uri, kind, title, metadata_json, acl_json, created_at, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(uri) DO UPDATE SET
-       kind = excluded.kind,
-       title = COALESCE(excluded.title, sources.title),
-       updated_at = excluded.updated_at`, [
-    id,
-    event.sourceUri,
-    event.kind,
-    event.title,
-    JSON.stringify({ source_ref: event.sourceRef, source_uri: event.sourceUri, status: event.status, last_outbox_event: event.eventType }),
-    JSON.stringify(event.acl ?? {}),
-    now,
-    event.updatedAt
-  ]);
-  const row = db.query("SELECT id, metadata_json, acl_json FROM sources WHERE uri = ?").get(event.sourceUri);
-  if (!row)
-    throw new Error(`Failed to upsert source for outbox event: ${event.sourceUri}`);
-  const patch = {
-    source_ref: event.sourceRef,
-    source_uri: event.sourceUri,
-    last_outbox_event: event.eventType,
-    last_outbox_at: event.updatedAt
+function chunkResult(row, keywordScore) {
+  const metadata = parseJsonObject2(row.chunk_metadata_json);
+  const provenance = provenanceForChunk2(row);
+  const sourceRef = metadataString2(metadata, ["source_ref"]);
+  const sourceUri = row.source_uri ?? metadataString2(metadata, ["source_uri"]);
+  const isWiki = Boolean(row.wiki_page_id);
+  const result = {
+    kind: isWiki ? "wiki_chunk" : "source_chunk",
+    id: row.chunk_id,
+    title: isWiki ? row.wiki_title : row.source_title,
+    text: row.text,
+    score: 0,
+    scores: { keyword: keywordScore },
+    source: sourceUri || sourceRef ? {
+      uri: sourceUri,
+      ref: sourceRef,
+      kind: row.source_kind ?? metadataString2(metadata, ["source_kind"]),
+      revision: row.revision ?? metadataString2(metadata, ["revision"]),
+      hash: row.hash ?? metadataString2(metadata, ["hash"])
+    } : null,
+    citation: {
+      chunk_id: row.chunk_id,
+      start_offset: row.start_offset,
+      end_offset: row.end_offset
+    },
+    artifact: isWiki ? {
+      uri: row.wiki_artifact_uri,
+      path: row.wiki_path,
+      hash: row.wiki_content_hash,
+      shard_key: row.wiki_path
+    } : null,
+    provenance,
+    reasons: ["keyword_match"]
   };
-  if (event.status)
-    patch.status = event.status;
-  if (asString(event.raw.path))
-    patch.path = event.raw.path;
-  db.run("UPDATE sources SET metadata_json = ?, acl_json = CASE WHEN ? IS NULL THEN acl_json ELSE ? END, updated_at = ? WHERE id = ?", [
-    mergeJson(row.metadata_json, patch),
-    event.acl === undefined ? null : JSON.stringify(event.acl),
-    event.acl === undefined ? null : JSON.stringify(event.acl),
-    event.updatedAt,
-    row.id
-  ]);
-  return row.id;
+  result.score = combinedScore(result.scores, result.citation);
+  return result;
 }
-function ensureRevision(db, sourceId, event, now) {
-  if (!event.revision)
-    return null;
-  const id = stableId2("rev", `${sourceId}\x00${event.revision}`);
-  const metadata = {
-    source_ref: event.sourceRef,
-    source_uri: event.sourceUri,
-    status: event.status,
-    last_outbox_event: event.eventType,
-    reindex_required: true
+function wikiPageResult(row, terms) {
+  const metadata = parseJsonObject2(row.metadata_json);
+  const score = catalogScore(`${row.path} ${row.title} ${row.artifact_uri ?? ""} ${row.metadata_json}`.toLowerCase(), terms);
+  const result = {
+    kind: "wiki_page",
+    id: row.id,
+    title: row.title,
+    text: null,
+    score: 0,
+    scores: { catalog: score },
+    source: null,
+    citation: null,
+    artifact: {
+      uri: row.artifact_uri,
+      path: row.path,
+      hash: row.content_hash,
+      shard_key: row.path
+    },
+    provenance: existingProvenance(metadata),
+    reasons: ["wiki_catalog_match"]
   };
-  db.run(`INSERT INTO source_revisions (id, source_id, revision, hash, extracted_text_uri, metadata_json, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(source_id, revision) DO UPDATE SET
-       hash = COALESCE(excluded.hash, source_revisions.hash),
-       metadata_json = excluded.metadata_json`, [id, sourceId, event.revision, event.hash, asString(event.raw.extracted_text_ref) ?? null, JSON.stringify(metadata), now]);
-  const row = db.query("SELECT id FROM source_revisions WHERE source_id = ? AND revision = ?").get(sourceId, event.revision);
-  return row?.id ?? null;
+  result.score = combinedScore(result.scores, result.citation);
+  return result;
 }
-function revisionIdsForEvent(db, sourceId, event) {
-  if (event.revision) {
-    return db.query("SELECT id FROM source_revisions WHERE source_id = ? AND revision = ?").all(sourceId, event.revision).map((row) => row.id);
-  }
-  if (event.hash) {
-    return db.query("SELECT id FROM source_revisions WHERE source_id = ? AND hash = ?").all(sourceId, event.hash).map((row) => row.id);
-  }
-  return db.query("SELECT id FROM source_revisions WHERE source_id = ?").all(sourceId).map((row) => row.id);
+function indexResult(row, terms) {
+  const metadata = parseJsonObject2(row.metadata_json);
+  const score = catalogScore(`${row.kind} ${row.name} ${row.shard_key ?? ""} ${row.artifact_uri ?? ""} ${row.metadata_json}`.toLowerCase(), terms);
+  const result = {
+    kind: "knowledge_index",
+    id: row.id,
+    title: row.name,
+    text: null,
+    score: 0,
+    scores: { catalog: score },
+    source: null,
+    citation: null,
+    artifact: {
+      uri: row.artifact_uri,
+      path: metadataString2(metadata, ["artifact_key"]),
+      hash: metadataString2(metadata, ["content_hash"]),
+      shard_key: row.shard_key
+    },
+    provenance: existingProvenance(metadata),
+    reasons: ["index_catalog_match"]
+  };
+  result.score = combinedScore(result.scores, result.citation);
+  return result;
 }
-function invalidateRevision(db, revisionId) {
-  const chunks = db.query("SELECT id FROM chunks WHERE source_revision_id = ?").all(revisionId);
-  let embeddingsDeleted = 0;
-  let vectorEntriesDeleted = 0;
-  for (const chunk of chunks) {
-    const row = db.query("SELECT COUNT(*) AS n FROM chunk_embeddings WHERE chunk_id = ?").get(chunk.id);
-    embeddingsDeleted += row?.n ?? 0;
-    const vectorRow = db.query("SELECT COUNT(*) AS n FROM vector_index_entries WHERE chunk_id = ?").get(chunk.id);
-    vectorEntriesDeleted += vectorRow?.n ?? 0;
-    db.run("DELETE FROM vector_index_entries WHERE chunk_id = ?", [chunk.id]);
-    db.run("DELETE FROM chunk_embeddings WHERE chunk_id = ?", [chunk.id]);
-    db.run("DELETE FROM chunks_fts WHERE chunk_id = ?", [chunk.id]);
+function mergeResult(results, entry) {
+  const key = `${entry.kind}:${entry.id}`;
+  const existing = results.get(key);
+  if (!existing) {
+    results.set(key, entry);
+    return;
   }
-  db.run("DELETE FROM chunks WHERE source_revision_id = ?", [revisionId]);
-  const revision = db.query("SELECT metadata_json FROM source_revisions WHERE id = ?").get(revisionId);
-  db.run("UPDATE source_revisions SET metadata_json = ? WHERE id = ?", [mergeJson(revision?.metadata_json, { reindex_required: true, invalidated_at: new Date().toISOString() }), revisionId]);
-  return { chunksDeleted: chunks.length, embeddingsDeleted, vectorEntriesDeleted };
-}
-function isDeleteEvent(eventType2, status) {
-  return status === "deleted" || ["delete", "deleted", "remove", "removed"].includes(eventType2);
-}
-function isMoveEvent(eventType2) {
-  return ["move", "moved", "rename", "renamed", "path_changed"].includes(eventType2);
+  existing.scores = {
+    keyword: Math.max(existing.scores.keyword ?? 0, entry.scores.keyword ?? 0) || undefined,
+    semantic: Math.max(existing.scores.semantic ?? 0, entry.scores.semantic ?? 0) || undefined,
+    catalog: Math.max(existing.scores.catalog ?? 0, entry.scores.catalog ?? 0) || undefined
+  };
+  existing.reasons = unique([...existing.reasons, ...entry.reasons]);
+  existing.text = existing.text ?? entry.text;
+  existing.title = existing.title ?? entry.title;
+  existing.source = existing.source ?? entry.source;
+  existing.citation = existing.citation ?? entry.citation;
+  existing.artifact = existing.artifact ?? entry.artifact;
+  existing.provenance = existing.provenance ?? entry.provenance;
+  existing.score = combinedScore(existing.scores, existing.citation);
 }
-function isPermissionEvent(eventType2) {
-  return ["permission", "permissions", "permission_changed", "acl_changed"].includes(eventType2);
+function sortResults(results) {
+  const kindOrder = {
+    source_chunk: 0,
+    wiki_chunk: 1,
+    wiki_page: 2,
+    knowledge_index: 3
+  };
+  return results.sort((a, b) => {
+    if (b.score !== a.score)
+      return b.score - a.score;
+    return kindOrder[a.kind] - kindOrder[b.kind] || a.id.localeCompare(b.id);
+  });
 }
-async function consumeOpenFilesOutbox(options) {
-  const now = (options.now ?? new Date).toISOString();
-  if (options.safetyPolicy)
-    assertWriteAllowed(options.dbPath, options.safetyPolicy);
+async function hybridSearch(options) {
+  const query = options.query.trim();
+  if (!query)
+    throw new Error("Search query is required.");
+  const limit = Math.max(1, Math.min(options.limit ?? 10, 100));
+  const terms = queryTerms(query);
+  const ftsQuery = ftsQueryForTerms(terms);
+  const semanticEnabled = options.semantic === true || options.fake === true || Boolean(options.modelRef);
+  const warnings = [];
+  let semanticProvider = null;
+  let semanticModel = null;
+  let semanticDimensions = null;
+  let keywordCount = 0;
+  let catalogCount = 0;
+  let semanticCount = 0;
+  const merged = new Map;
   migrateKnowledgeDb(options.dbPath);
-  const text = await readOutboxInput(options.input, options.config, options.safetyPolicy);
-  const events = parseOutboxText(text);
   const db = openKnowledgeDb(options.dbPath);
-  const runId = `run_${randomUUID3()}`;
   try {
-    return db.transaction(() => {
-      db.run(`INSERT INTO runs (id, type, prompt, status, provider, model, metadata_json, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
-        runId,
-        "open-files-outbox",
-        options.input,
-        "completed",
-        "local",
-        "open-files-outbox",
-        JSON.stringify({ path: options.input, events: events.length }),
-        now,
-        now
-      ]);
-      const sourcesTouched = new Set;
-      const revisionsTouched = new Set;
-      let chunksDeleted = 0;
-      let embeddingsDeleted = 0;
-      let vectorEntriesDeleted = 0;
-      let staleRevisions = 0;
-      let deletedSources = 0;
-      let movedSources = 0;
-      let permissionUpdates = 0;
-      recordAuditEvent(db, {
-        event_type: "source_read",
-        action: options.input.startsWith("s3://") ? "s3_outbox_read" : "local_outbox_read",
-        target_uri: options.input,
-        decision: "allow",
-        metadata: { events: events.length, read_only: true },
-        created_at: now
-      });
-      events.forEach((raw, index) => {
-        const event = normalizeEvent(raw, now);
-        const sourceId = ensureSource(db, event, now);
-        sourcesTouched.add(sourceId);
-        const createdRevisionId = ensureRevision(db, sourceId, event, now);
-        if (createdRevisionId)
-          revisionsTouched.add(createdRevisionId);
-        const affectedRevisionIds = revisionIdsForEvent(db, sourceId, event);
-        for (const revisionId of affectedRevisionIds) {
-          revisionsTouched.add(revisionId);
-          const invalidation = invalidateRevision(db, revisionId);
-          chunksDeleted += invalidation.chunksDeleted;
-          embeddingsDeleted += invalidation.embeddingsDeleted;
-          vectorEntriesDeleted += invalidation.vectorEntriesDeleted;
-          staleRevisions += 1;
-        }
-        if (isDeleteEvent(event.eventType, event.status))
-          deletedSources += 1;
-        if (isMoveEvent(event.eventType))
-          movedSources += 1;
-        if (isPermissionEvent(event.eventType) || event.acl !== undefined)
-          permissionUpdates += 1;
-        db.run(`INSERT INTO run_events (id, run_id, level, event, metadata_json, created_at)
-           VALUES (?, ?, ?, ?, ?, ?)`, [
-          stableId2("evt", `${runId}\x00${index}\x00${event.sourceRef}\x00${event.eventType}`),
-          runId,
-          "info",
-          event.eventType,
-          JSON.stringify({
-            source_ref: event.sourceRef,
-            source_uri: event.sourceUri,
-            revision: event.revision,
-            hash: event.hash,
-            status: event.status,
-            affected_revisions: affectedRevisionIds.length
-          }),
-          event.updatedAt
-        ]);
-      });
-      db.run(`INSERT INTO provider_usage (id, run_id, provider, model, input_tokens, output_tokens, cost_usd, metadata_json, created_at)
-         VALUES (?, ?, ?, ?, 0, 0, 0, ?, ?)`, [
-        stableId2("usage", runId),
-        runId,
-        "local",
-        "open-files-outbox",
-        JSON.stringify({ note: "No model provider used for outbox invalidation." }),
-        now
-      ]);
-      recordAuditEvent(db, {
-        event_type: "write",
-        action: "knowledge_outbox_invalidation",
-        target_uri: options.dbPath,
-        decision: "allow",
-        metadata: {
-          run_id: runId,
-          events: events.length,
-          sources: sourcesTouched.size,
-          revisions: revisionsTouched.size,
-          chunks_deleted: chunksDeleted,
-          embeddings_deleted: embeddingsDeleted,
-          vector_entries_deleted: vectorEntriesDeleted
-        },
-        created_at: now
-      });
-      return {
-        path: options.input,
-        db_path: options.dbPath,
-        run_id: runId,
-        events_seen: events.length,
-        sources_touched: sourcesTouched.size,
-        revisions_touched: revisionsTouched.size,
-        chunks_deleted: chunksDeleted,
-        embeddings_deleted: embeddingsDeleted,
-        vector_entries_deleted: vectorEntriesDeleted,
-        stale_revisions: staleRevisions,
-        deleted_sources: deletedSources,
-        moved_sources: movedSources,
-        permission_updates: permissionUpdates
-      };
-    })();
+    const ftsRows = selectFtsChunks(db, ftsQuery, Math.max(limit * 3, 20));
+    keywordCount = ftsRows.length;
+    ftsRows.forEach((row, index) => mergeResult(merged, chunkResult(row, scoreFromRank(row.rank, index))));
+    const wikiRows = selectWikiPages(db, terms, Math.max(limit, 10));
+    const indexRows = selectKnowledgeIndexes(db, terms, Math.max(limit, 10));
+    catalogCount = wikiRows.length + indexRows.length;
+    wikiRows.forEach((row) => mergeResult(merged, wikiPageResult(row, terms)));
+    indexRows.forEach((row) => mergeResult(merged, indexResult(row, terms)));
   } finally {
     db.close();
   }
+  if (semanticEnabled) {
+    try {
+      const semantic = await searchVectorIndex({
+        dbPath: options.dbPath,
+        query,
+        limit: Math.max(limit * 3, 20),
+        config: options.config,
+        env: options.env,
+        modelRef: options.modelRef,
+        dimensions: options.dimensions,
+        fake: options.fake,
+        batchSize: options.batchSize,
+        maxParallelCalls: options.maxParallelCalls
+      });
+      semanticProvider = semantic.provider;
+      semanticModel = semantic.model;
+      semanticDimensions = semantic.dimensions;
+      semanticCount = semantic.results.length;
+      for (const row of semantic.results) {
+        const result = {
+          kind: "source_chunk",
+          id: row.chunk_id,
+          title: null,
+          text: row.text,
+          score: 0,
+          scores: { semantic: semanticScore(row.score) },
+          source: {
+            uri: row.source_uri,
+            ref: row.source_ref,
+            kind: row.provenance?.source_kind ?? null,
+            revision: row.revision,
+            hash: row.hash
+          },
+          citation: {
+            chunk_id: row.chunk_id,
+            start_offset: row.provenance?.start_offset ?? null,
+            end_offset: row.provenance?.end_offset ?? null
+          },
+          artifact: null,
+          provenance: row.provenance,
+          reasons: ["semantic_match"]
+        };
+        result.score = combinedScore(result.scores, result.citation);
+        mergeResult(merged, result);
+      }
+    } catch (error48) {
+      warnings.push(`semantic_search_failed: ${error48 instanceof Error ? error48.message : String(error48)}`);
+    }
+  }
+  const results = sortResults(Array.from(merged.values())).slice(0, limit);
+  return {
+    query,
+    limit,
+    mode: {
+      keyword: true,
+      catalog: true,
+      semantic: semanticEnabled
+    },
+    semantic_provider: semanticProvider,
+    semantic_model: semanticModel,
+    semantic_dimensions: semanticDimensions,
+    counts: {
+      keyword_results: keywordCount,
+      catalog_results: catalogCount,
+      semantic_results: semanticCount,
+      merged_results: results.length
+    },
+    warnings,
+    results
+  };
 }
-
-// src/manifest-ingest.ts
-import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
-import { basename as basename2 } from "path";
-function stableId3(prefix, value) {
-  return `${prefix}_${createHash4("sha256").update(value).digest("hex").slice(0, 20)}`;
-}
-function asObject2(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
-}
-function asString2(value) {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-function asNumber(value) {
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}
-function buildSourceRefFromItem(item) {
-  const explicit = asString2(item.source_ref) ?? asString2(item.source_uri) ?? asString2(item.uri);
-  if (explicit)
-    return explicit;
-  const fileId = asString2(item.file_id);
-  if (fileId) {
-    const revision = asString2(item.revision_id) ?? asString2(item.revision);
-    const fileRef = `open-files://file/${encodeURIComponent(fileId)}`;
-    return revision ? `${fileRef}/revision/${encodeURIComponent(revision)}` : fileRef;
-  }
-  const sourceId = asString2(item.source_id);
-  const path = asString2(item.path);
-  if (sourceId && path) {
-    return `open-files://source/${encodeURIComponent(sourceId)}/path/${encodeURIComponent(path)}`;
-  }
-  throw new Error("Manifest item is missing source_ref, file_id, or source_id/path.");
-}
-function baseSourceUri2(sourceRef, parsed) {
-  if (parsed.kind === "open-files" && parsed.entity === "file" && parsed.revision_id) {
-    return sourceRef.replace(/\/revision\/[^/]+$/, "");
-  }
-  return sourceRef;
-}
-function textFromItem(item) {
-  const direct = asString2(item.extracted_text) ?? asString2(item.text) ?? asString2(item.content_text) ?? asString2(item.markdown);
-  if (direct !== undefined)
-    return direct;
-  const content = item.content;
-  return typeof content === "string" ? content : null;
-}
-function extractedTextUriFromItem(item) {
-  const direct = asString2(item.extracted_text_ref) ?? asString2(item.extracted_text_uri) ?? asString2(item.text_ref);
-  if (direct)
-    return direct;
-  const content = asObject2(item.content);
-  return asString2(content?.extracted_text_ref) ?? asString2(content?.extracted_text_uri) ?? null;
+
+// src/retrieval.ts
+function stableId2(prefix, value) {
+  return `${prefix}_${createHash2("sha256").update(value).digest("hex").slice(0, 20)}`;
 }
-function titleFromItem(item) {
-  const path = asString2(item.path);
-  return asString2(item.title) ?? asString2(item.name) ?? (path ? basename2(path) : null);
+function normalizeQuery(query) {
+  return query.normalize("NFKC").trim().replace(/\s+/g, " ").toLowerCase();
 }
-function hashFromItem(item) {
-  return asString2(item.hash) ?? asString2(item.checksum) ?? asString2(item.sha256) ?? null;
+function queryTerms2(query) {
+  return Array.from(new Set(normalizeQuery(query).match(/[\p{L}\p{N}_]+/gu) ?? [])).slice(0, 16);
 }
-function revisionFromItem(item, parsed, hash2) {
-  const revision = asString2(item.revision_id) ?? asString2(item.revision) ?? asString2(item.version_id) ?? (parsed.kind === "open-files" ? parsed.revision_id : undefined) ?? hash2 ?? asString2(item.updated_at);
-  return revision ?? "current";
+function textForResult(result) {
+  return [result.title, result.text].filter(Boolean).join(" ").toLowerCase();
 }
-function metadataFromItem(item, normalized) {
-  const metadata = {};
-  for (const [key, value] of Object.entries(item)) {
-    if (["text", "content", "content_text", "extracted_text", "markdown"].includes(key))
-      continue;
-    metadata[key] = value;
-  }
-  metadata.source_ref = normalized.sourceRef;
-  metadata.source_uri = normalized.sourceUri;
-  metadata.status = normalized.status;
-  return metadata;
+function exactScore(result, terms) {
+  if (terms.length === 0)
+    return 0;
+  const text = textForResult(result);
+  const matched = terms.filter((term) => text.includes(term)).length;
+  return Number((matched / terms.length).toFixed(6));
 }
-function normalizeManifestItem(item, now) {
-  const sourceRef = buildSourceRefFromItem(item);
-  const parsed = parseSourceRef(sourceRef);
-  const sourceUri = baseSourceUri2(sourceRef, parsed);
-  const hash2 = hashFromItem(item);
-  const status = asString2(item.status) ?? "active";
+function hasReadOnlyProvenance(provenance) {
+  if (!provenance)
+    return true;
+  if ("read_only" in provenance)
+    return provenance.read_only === true;
+  if ("read_only_sources" in provenance)
+    return provenance.read_only_sources === true;
+  return true;
+}
+function isStale(provenance) {
+  if (!provenance)
+    return false;
+  if ("stale" in provenance && provenance.stale)
+    return true;
+  if ("status" in provenance)
+    return isStaleStatus(provenance.status);
+  return false;
+}
+function freshnessScore(result) {
+  if (isStale(result.provenance))
+    return 0;
+  if (result.source?.hash || result.source?.revision)
+    return 1;
+  if (result.artifact?.hash)
+    return 0.85;
+  if (result.provenance && "source_refs" in result.provenance && result.provenance.source_refs.length > 0)
+    return 0.75;
+  return 0.55;
+}
+function citationScore(result) {
+  if (result.citation?.chunk_id && (result.source?.uri || result.artifact?.uri))
+    return 1;
+  if (result.provenance && "citation_required" in result.provenance && result.provenance.citation_required)
+    return 0.75;
+  if (result.artifact?.uri)
+    return 0.65;
+  return 0.35;
+}
+function authorityScore(result) {
+  if (result.kind === "wiki_chunk")
+    return 0.85;
+  if (result.kind === "source_chunk")
+    return 0.8;
+  if (result.kind === "wiki_page")
+    return 0.65;
+  return 0.55;
+}
+function rerank(result, terms) {
+  const scores = {
+    base_score: result.score,
+    exact_score: exactScore(result, terms),
+    citation_score: citationScore(result),
+    freshness_score: freshnessScore(result),
+    authority_score: authorityScore(result)
+  };
+  const final = Math.min(1, scores.base_score * 0.65 + scores.exact_score * 0.1 + scores.citation_score * 0.1 + scores.freshness_score * 0.1 + scores.authority_score * 0.05);
+  const reasons = new Set(result.reasons);
+  if (scores.exact_score > 0.5)
+    reasons.add("exact_term");
+  if (scores.citation_score >= 0.75)
+    reasons.add("cited_source");
+  if (scores.freshness_score >= 0.85)
+    reasons.add("fresh_source");
   return {
-    raw: item,
-    sourceRef,
-    sourceUri,
-    kind: parsed.kind,
-    title: titleFromItem(item),
-    revision: revisionFromItem(item, parsed, hash2),
-    hash: hash2,
-    extractedTextUri: extractedTextUriFromItem(item),
-    text: textFromItem(item),
-    metadata: metadataFromItem(item, { sourceRef, sourceUri, status }),
-    acl: item.permissions ?? item.acl ?? {},
-    status,
-    updatedAt: asString2(item.updated_at) ?? now
+    ...result,
+    score: Number(final.toFixed(6)),
+    reasons: Array.from(reasons),
+    rerank: {
+      ...scores,
+      final_score: Number(final.toFixed(6))
+    }
   };
 }
-function parseManifestText(text) {
-  const trimmed = text.trim();
-  if (!trimmed)
-    return [];
-  if (trimmed.startsWith("[")) {
-    const parsed = JSON.parse(trimmed);
-    if (!Array.isArray(parsed))
-      throw new Error("Manifest array parse failed.");
-    return parsed.map((entry) => {
-      const item = asObject2(entry);
-      if (!item)
-        throw new Error("Manifest array entries must be objects.");
-      return item;
-    });
-  }
-  if (trimmed.startsWith("{")) {
-    try {
-      const parsed = JSON.parse(trimmed);
-      const object2 = asObject2(parsed);
-      if (!object2)
-        throw new Error("Manifest object parse failed.");
-      if (Array.isArray(object2.items)) {
-        return object2.items.map((entry) => {
-          const item = asObject2(entry);
-          if (!item)
-            throw new Error("Manifest items entries must be objects.");
-          return item;
-        });
-      }
-      if ("source_ref" in object2 || "source_uri" in object2 || "file_id" in object2)
-        return [object2];
-    } catch (error48) {
-      const lines = trimmed.split(/\r?\n/).filter((line) => line.trim().length > 0);
-      if (lines.length <= 1)
-        throw error48;
-      return lines.map((line) => {
-        const item = asObject2(JSON.parse(line));
-        if (!item)
-          throw new Error("Manifest JSONL entries must be objects.");
-        return item;
-      });
+function quoteFor(result, maxChars) {
+  const source = result.text ?? result.title;
+  if (!source)
+    return null;
+  const normalized = source.replace(/\s+/g, " ").trim();
+  return normalized.length <= maxChars ? normalized : `${normalized.slice(0, Math.max(0, maxChars - 1)).trim()}...`;
+}
+function citationFor(result) {
+  const id = stableId2("cite", `${result.kind}\x00${result.id}\x00${result.source?.uri ?? ""}\x00${result.artifact?.uri ?? ""}`);
+  return {
+    id,
+    result_id: result.id,
+    kind: result.kind,
+    source_uri: result.source?.uri ?? null,
+    source_ref: result.source?.ref ?? null,
+    artifact_uri: result.artifact?.uri ?? null,
+    artifact_path: result.artifact?.path ?? null,
+    revision: result.source?.revision ?? null,
+    hash: result.source?.hash ?? result.artifact?.hash ?? null,
+    chunk_id: result.citation?.chunk_id ?? null,
+    start_offset: result.citation?.start_offset ?? null,
+    end_offset: result.citation?.end_offset ?? null,
+    quote: quoteFor(result, 500),
+    provenance: result.provenance
+  };
+}
+function excerptFor(result, citation, contextChars) {
+  const text = quoteFor(result, contextChars);
+  if (!text)
+    return null;
+  return {
+    id: stableId2("excerpt", `${result.kind}\x00${result.id}`),
+    result_id: result.id,
+    citation_id: citation.id,
+    kind: result.kind,
+    text,
+    score: result.score
+  };
+}
+function placeholders(values) {
+  return values.map(() => "?").join(", ");
+}
+function loadGraphEvidence(dbPath, results) {
+  const chunkIds = results.map((result) => result.citation?.chunk_id).filter((id) => Boolean(id));
+  const wikiPageIds = results.filter((result) => result.kind === "wiki_page").map((result) => result.id);
+  const citations = [];
+  const backlinks = [];
+  if (chunkIds.length === 0 && wikiPageIds.length === 0)
+    return { citations, backlinks };
+  const db = openKnowledgeDb(dbPath);
+  try {
+    if (chunkIds.length > 0) {
+      citations.push(...db.query(`SELECT id, wiki_page_id, chunk_id, source_uri, quote, start_offset, end_offset
+         FROM citations
+         WHERE chunk_id IN (${placeholders(chunkIds)})
+         ORDER BY created_at DESC
+         LIMIT 50`).all(...chunkIds));
+    }
+    if (wikiPageIds.length > 0) {
+      citations.push(...db.query(`SELECT id, wiki_page_id, chunk_id, source_uri, quote, start_offset, end_offset
+         FROM citations
+         WHERE wiki_page_id IN (${placeholders(wikiPageIds)})
+         ORDER BY created_at DESC
+         LIMIT 50`).all(...wikiPageIds));
+      backlinks.push(...db.query(`SELECT from_page_id, to_page_id, label
+         FROM wiki_backlinks
+         WHERE from_page_id IN (${placeholders(wikiPageIds)}) OR to_page_id IN (${placeholders(wikiPageIds)})
+         LIMIT 50`).all(...wikiPageIds, ...wikiPageIds));
     }
+  } finally {
+    db.close();
   }
-  return trimmed.split(/\r?\n/).filter((line) => line.trim().length > 0).map((line) => {
-    const item = asObject2(JSON.parse(line));
-    if (!item)
-      throw new Error("Manifest JSONL entries must be objects.");
-    return item;
+  return { citations, backlinks };
+}
+async function retrieveKnowledgeContext(options) {
+  const contextChars = Math.max(200, Math.min(options.contextChars ?? 1200, 4000));
+  const search = await hybridSearch(options);
+  const terms = queryTerms2(search.query);
+  const warnings = [...search.warnings];
+  const permissionNotes = new Set;
+  const freshnessNotes = new Set;
+  const filtered = search.results.filter((result) => {
+    if (!hasReadOnlyProvenance(result.provenance)) {
+      warnings.push(`permission_filtered: ${result.kind}:${result.id}`);
+      permissionNotes.add("Dropped a result because provenance was not read-only.");
+      return false;
+    }
+    if (isStale(result.provenance)) {
+      warnings.push(`stale_filtered: ${result.kind}:${result.id}`);
+      freshnessNotes.add("Dropped a stale result whose source status requires reindexing.");
+      return false;
+    }
+    return true;
   });
+  const results = filtered.map((result) => rerank(result, terms)).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, search.limit);
+  const citations = results.map(citationFor);
+  const excerpts = results.map((result, index) => excerptFor(result, citations[index], contextChars)).filter((entry) => Boolean(entry));
+  for (const result of results) {
+    if (result.provenance && "read_only" in result.provenance && result.provenance.read_only) {
+      permissionNotes.add("All source-backed excerpts are read-only and citation-required.");
+    }
+    if (result.rerank.freshness_score >= 0.85) {
+      freshnessNotes.add("Fresh source revision/hash or artifact hash is present for top context.");
+    }
+  }
+  return {
+    query: search.query,
+    normalized_query: normalizeQuery(search.query),
+    created_at: new Date().toISOString(),
+    mode: search.mode,
+    warnings,
+    search_counts: search.counts,
+    results,
+    citations,
+    excerpts,
+    graph: loadGraphEvidence(options.dbPath, results),
+    notes: {
+      permissions: Array.from(permissionNotes),
+      freshness: Array.from(freshnessNotes)
+    }
+  };
 }
-async function readS3Text2(uri, config2, safetyPolicy) {
-  const parsed = new URL(uri);
-  const bucket = parsed.hostname;
-  const key = decodeURIComponent(parsed.pathname.replace(/^\/+/, ""));
-  if (!bucket || !key)
-    throw new Error(`Invalid S3 manifest URI: ${uri}`);
-  if (safetyPolicy)
-    assertS3ReadAllowed(uri, safetyPolicy);
-  const [{ S3Client, GetObjectCommand }, { fromIni }] = await Promise.all([
-    import("@aws-sdk/client-s3"),
-    import("@aws-sdk/credential-providers")
-  ]);
-  const s3Config = config2?.storage.type === "s3" && config2.storage.s3?.bucket === bucket ? config2.storage.s3 : undefined;
-  const client = new S3Client({
-    region: s3Config?.region,
-    credentials: s3Config?.profile ? fromIni({ profile: s3Config.profile }) : undefined,
-    maxAttempts: s3Config?.max_attempts
-  });
-  const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
-  if (!response.Body)
-    return "";
-  return await response.Body.transformToString();
+
+// src/agent.ts
+function estimateTokens(text) {
+  const words = text.trim().split(/\s+/).filter(Boolean).length;
+  return Math.max(1, Math.ceil(words * 1.25));
 }
-async function readManifestInput(input, config2, safetyPolicy) {
-  if (input.startsWith("s3://"))
-    return readS3Text2(input, config2, safetyPolicy);
-  if (!existsSync5(input))
-    throw new Error(`Manifest not found: ${input}`);
-  return readFileSync5(input, "utf8");
+function citationLabel(index) {
+  return `C${index + 1}`;
 }
-function chunkText(text, maxChars, overlapChars) {
-  const normalized = text.replace(/\r\n/g, `
+function localAnswer(prompt, context) {
+  if (context.excerpts.length === 0) {
+    return `No indexed knowledge matched the prompt: ${prompt}`;
+  }
+  const lines = [
+    `Found ${context.excerpts.length} relevant knowledge excerpt(s) for: ${prompt}`,
+    "",
+    ...context.excerpts.slice(0, 5).map((excerpt, index) => {
+      const citation = context.citations.find((entry) => entry.id === excerpt.citation_id);
+      const ref = citation?.source_ref ?? citation?.source_uri ?? citation?.artifact_path ?? citation?.artifact_uri ?? "unknown source";
+      return `[${citationLabel(index)}] ${excerpt.text} (${ref})`;
+    })
+  ];
+  return lines.join(`
 `);
-  if (!normalized.trim())
+}
+function promptForModel(prompt, context) {
+  const citations = context.citations.map((citation, index) => ({
+    id: citationLabel(index),
+    source_ref: citation.source_ref,
+    source_uri: citation.source_uri,
+    artifact_path: citation.artifact_path,
+    revision: citation.revision,
+    hash: citation.hash,
+    quote: citation.quote
+  }));
+  const excerpts = context.excerpts.map((excerpt, index) => ({
+    id: citationLabel(index),
+    kind: excerpt.kind,
+    text: excerpt.text,
+    score: excerpt.score
+  }));
+  return [
+    `Prompt: ${prompt}`,
+    "",
+    "Use only the provided context. Cite claims with citation ids like [C1]. If context is insufficient, say what is missing.",
+    "",
+    `Context excerpts:
+${JSON.stringify(excerpts, null, 2)}`,
+    "",
+    `Citations:
+${JSON.stringify(citations, null, 2)}`
+  ].join(`
+`);
+}
+function proposedUpdates(prompt, context) {
+  if (context.citations.length === 0)
     return [];
-  const chunks = [];
-  let start = 0;
-  while (start < normalized.length) {
-    const hardEnd = Math.min(normalized.length, start + maxChars);
-    let end = hardEnd;
-    if (hardEnd < normalized.length) {
-      const paragraphBreak = normalized.lastIndexOf(`
-
-`, hardEnd);
-      const sentenceBreak = normalized.lastIndexOf(". ", hardEnd);
-      const candidate = Math.max(paragraphBreak, sentenceBreak);
-      if (candidate > start + Math.floor(maxChars * 0.5))
-        end = candidate + (candidate === paragraphBreak ? 2 : 1);
-    }
-    const chunk = normalized.slice(start, end).trim();
-    if (chunk) {
-      chunks.push({
-        ordinal: chunks.length,
-        text: chunk,
-        startOffset: start,
-        endOffset: end
-      });
-    }
-    if (end >= normalized.length)
-      break;
-    start = Math.max(0, end - overlapChars);
-  }
-  return chunks;
-}
-function estimateTokenCount(text) {
-  const words = text.trim().split(/\s+/).filter(Boolean).length;
-  return Math.max(1, Math.ceil(words * 1.25));
-}
-function deleteChunksForRevision(db, sourceRevisionId) {
-  const rows = db.query("SELECT id FROM chunks WHERE source_revision_id = ?").all(sourceRevisionId);
-  for (const row of rows) {
-    db.run("DELETE FROM chunks_fts WHERE chunk_id = ?", [row.id]);
-  }
-  db.run("DELETE FROM chunks WHERE source_revision_id = ?", [sourceRevisionId]);
-  return rows.length;
-}
-function upsertSource(db, item, now) {
-  const sourceId = stableId3("src", item.sourceUri);
-  db.run(`INSERT INTO sources (id, uri, kind, title, metadata_json, acl_json, created_at, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(uri) DO UPDATE SET
-       kind = excluded.kind,
-       title = excluded.title,
-       metadata_json = excluded.metadata_json,
-       acl_json = excluded.acl_json,
-       updated_at = excluded.updated_at`, [
-    sourceId,
-    item.sourceUri,
-    item.kind,
-    item.title,
-    JSON.stringify(item.metadata),
-    JSON.stringify(item.acl ?? {}),
-    now,
-    item.updatedAt
-  ]);
-  const row = db.query("SELECT id FROM sources WHERE uri = ?").get(item.sourceUri);
-  if (!row)
-    throw new Error(`Failed to upsert source: ${item.sourceUri}`);
-  return row.id;
-}
-function upsertRevision(db, sourceId, item, now) {
-  const revisionId = stableId3("rev", `${sourceId}\x00${item.revision}`);
-  db.run(`INSERT INTO source_revisions (id, source_id, revision, hash, extracted_text_uri, metadata_json, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(source_id, revision) DO UPDATE SET
-       hash = excluded.hash,
-       extracted_text_uri = excluded.extracted_text_uri,
-       metadata_json = excluded.metadata_json`, [
-    revisionId,
-    sourceId,
-    item.revision,
-    item.hash,
-    item.extractedTextUri,
-    JSON.stringify(item.metadata),
-    now
-  ]);
-  const row = db.query("SELECT id FROM source_revisions WHERE source_id = ? AND revision = ?").get(sourceId, item.revision);
-  if (!row)
-    throw new Error(`Failed to upsert source revision: ${item.sourceRef}`);
-  return row.id;
-}
-function insertChunks(db, sourceRevisionId, item, now, maxChars, overlapChars, safetyPolicy) {
-  if (!item.text || item.status.toLowerCase() === "deleted")
-    return { chunksInserted: 0, redactions: 0 };
-  const redacted = redactSecrets(item.text, safetyPolicy);
-  if (redacted.findings.length > 0) {
-    recordRedactionFindings(db, {
-      source_uri: item.sourceUri,
-      findings: redacted.findings,
-      metadata: { source_ref: item.sourceRef, revision: item.revision },
-      created_at: now
-    });
-    recordAuditEvent(db, {
-      event_type: "redaction",
-      action: "source_text_redact",
-      target_uri: item.sourceUri,
-      decision: "redacted",
-      metadata: { findings: redacted.findings.length, source_ref: item.sourceRef, revision: item.revision },
-      created_at: now
-    });
-  }
-  const chunks = chunkText(redacted.text, maxChars, overlapChars);
-  for (const chunk of chunks) {
-    const chunkId = stableId3("chk", `${sourceRevisionId}\x00${chunk.ordinal}\x00${chunk.text}`);
-    const provenance = sourceProvenance({
-      source_ref: item.sourceRef,
-      source_uri: item.sourceUri,
-      source_kind: item.kind,
-      source_revision_id: sourceRevisionId,
-      revision: item.revision,
-      hash: item.hash,
-      chunk_id: chunkId,
-      start_offset: chunk.startOffset,
-      end_offset: chunk.endOffset,
-      status: item.status,
-      resolver: "open-files-read-only"
-    });
-    const metadata = withProvenance({
-      source_ref: item.sourceRef,
-      source_uri: item.sourceUri,
-      source_kind: item.kind,
-      source_revision_id: sourceRevisionId,
-      revision: item.revision,
-      hash: item.hash,
-      status: item.status,
-      path: asString2(item.raw.path) ?? null,
-      mime: asString2(item.raw.mime) ?? asString2(item.raw.content_type) ?? null,
-      size: asNumber(item.raw.size) ?? null
-    }, provenance);
-    db.run(`INSERT INTO chunks (id, source_revision_id, kind, ordinal, text, token_count, start_offset, end_offset, metadata_json, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
-      chunkId,
-      sourceRevisionId,
-      "source",
-      chunk.ordinal,
-      chunk.text,
-      estimateTokenCount(chunk.text),
-      chunk.startOffset,
-      chunk.endOffset,
-      JSON.stringify(metadata),
-      now
+  return [{
+    kind: "answer_note",
+    title: prompt.length > 80 ? `${prompt.slice(0, 77)}...` : prompt,
+    citations: context.citations.map((citation) => citation.id),
+    requires_approval: true
+  }];
+}
+function insertRun(dbPath, input) {
+  const db = openKnowledgeDb(dbPath);
+  try {
+    db.run(`INSERT INTO runs (id, type, prompt, status, provider, model, metadata_json, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      input.runId,
+      "knowledge-prompt",
+      input.prompt,
+      input.status,
+      input.provider,
+      input.model,
+      JSON.stringify(input.metadata),
+      input.now,
+      input.now
     ]);
-    db.run("INSERT INTO chunks_fts (chunk_id, text, title, source_uri) VALUES (?, ?, ?, ?)", [chunkId, chunk.text, item.title ?? "", item.sourceUri]);
+  } finally {
+    db.close();
   }
-  return { chunksInserted: chunks.length, redactions: redacted.findings.length };
-}
-async function ingestOpenFilesManifest(options) {
-  const now = options.now ?? new Date;
-  if (options.safetyPolicy)
-    assertWriteAllowed(options.dbPath, options.safetyPolicy);
-  migrateKnowledgeDb(options.dbPath);
-  const text = await readManifestInput(options.input, options.config, options.safetyPolicy);
-  const items = parseManifestText(text);
-  return ingestOpenFilesManifestItems({
-    dbPath: options.dbPath,
-    items,
-    sourceLabel: options.input,
-    safetyPolicy: options.safetyPolicy,
-    now,
-    maxChunkChars: options.maxChunkChars,
-    chunkOverlapChars: options.chunkOverlapChars
-  });
 }
-async function ingestOpenFilesManifestItems(options) {
-  const now = (options.now ?? new Date).toISOString();
-  const maxChunkChars = options.maxChunkChars ?? 4000;
-  const chunkOverlapChars = options.chunkOverlapChars ?? 200;
-  if (maxChunkChars < 500)
-    throw new Error("maxChunkChars must be at least 500.");
-  if (chunkOverlapChars < 0 || chunkOverlapChars >= maxChunkChars)
-    throw new Error("chunkOverlapChars must be less than maxChunkChars.");
-  if (options.safetyPolicy)
-    assertWriteAllowed(options.dbPath, options.safetyPolicy);
-  migrateKnowledgeDb(options.dbPath);
-  const db = openKnowledgeDb(options.dbPath);
+function addRunEvent(dbPath, input) {
+  const db = openKnowledgeDb(dbPath);
   try {
-    const result = db.transaction(() => {
-      const seenSources = new Set;
-      const seenRevisions = new Set;
-      let chunksInserted = 0;
-      let chunksDeleted = 0;
-      let redactions = 0;
-      let skipped = 0;
-      recordAuditEvent(db, {
-        event_type: "source_read",
-        action: options.readAction ?? (options.sourceLabel.startsWith("s3://") ? "s3_manifest_read" : "local_manifest_read"),
-        target_uri: options.sourceLabel,
-        decision: "allow",
-        metadata: { items: options.items.length, read_only: true },
-        created_at: now
-      });
-      for (const raw of options.items) {
-        const item = normalizeManifestItem(raw, now);
-        const sourceId = upsertSource(db, item, now);
-        const revisionId = upsertRevision(db, sourceId, item, now);
-        seenSources.add(sourceId);
-        seenRevisions.add(revisionId);
-        if (item.text || item.status.toLowerCase() === "deleted") {
-          chunksDeleted += deleteChunksForRevision(db, revisionId);
-        }
-        const inserted = insertChunks(db, revisionId, item, now, maxChunkChars, chunkOverlapChars, options.safetyPolicy);
-        chunksInserted += inserted.chunksInserted;
-        redactions += inserted.redactions;
-      }
-      recordAuditEvent(db, {
-        event_type: "write",
-        action: "knowledge_manifest_ingest",
-        target_uri: options.dbPath,
-        decision: "allow",
-        metadata: { items: options.items.length, sources: seenSources.size, revisions: seenRevisions.size, chunks_inserted: chunksInserted, redactions },
-        created_at: now
-      });
-      return {
-        path: options.sourceLabel,
-        db_path: options.dbPath,
-        items_seen: options.items.length,
-        sources_upserted: seenSources.size,
-        revisions_upserted: seenRevisions.size,
-        chunks_inserted: chunksInserted,
-        chunks_deleted: chunksDeleted,
-        redactions,
-        skipped
-      };
-    })();
-    return result;
+    db.run(`INSERT INTO run_events (id, run_id, level, event, metadata_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`, [
+      `evt_${randomUUID3()}`,
+      input.runId,
+      input.level,
+      input.event,
+      JSON.stringify(input.metadata),
+      input.now
+    ]);
   } finally {
     db.close();
   }
 }
-
-// src/source-ingest.ts
-import { createHash as createHash5 } from "crypto";
-import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
-import { basename as basename3 } from "path";
-
-// src/source-resolver.ts
-function parseJsonObject2(value) {
-  if (!value)
-    return {};
+function updateRun(dbPath, input) {
+  const db = openKnowledgeDb(dbPath);
   try {
-    const parsed = JSON.parse(value);
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
-  } catch {
-    return {};
+    db.run(`UPDATE runs
+       SET status = ?, provider = ?, model = ?, metadata_json = ?, updated_at = ?
+       WHERE id = ?`, [
+      input.status,
+      input.provider,
+      input.model,
+      JSON.stringify(input.metadata),
+      input.now,
+      input.runId
+    ]);
+  } finally {
+    db.close();
   }
 }
-function metadataString2(metadata, keys) {
-  for (const key of keys) {
-    const value = metadata[key];
-    if (typeof value === "string" && value.length > 0)
-      return value;
+function recordUsage(dbPath, runId, usage, provider, model, now, metadata = {}) {
+  const db = openKnowledgeDb(dbPath);
+  try {
+    recordProviderUsage(db, {
+      run_id: runId,
+      provider,
+      model,
+      input_tokens: usage.input_tokens,
+      output_tokens: usage.output_tokens,
+      cost_usd: usage.cost_usd,
+      metadata,
+      created_at: now
+    });
+  } finally {
+    db.close();
   }
-  return null;
 }
-function metadataNumber2(metadata, keys) {
-  for (const key of keys) {
-    const value = metadata[key];
-    if (typeof value === "number" && Number.isFinite(value))
-      return value;
+async function runKnowledgePrompt(options) {
+  const prompt = options.prompt.trim();
+  if (!prompt)
+    throw new Error("Knowledge prompt is required.");
+  const now = (options.now ?? new Date).toISOString();
+  const runId = `run_${randomUUID3()}`;
+  const modelRef = resolveModelRef(options.modelRef ?? "default", options.config);
+  const parsed = parseModelRef(modelRef);
+  migrateKnowledgeDb(options.dbPath);
+  insertRun(options.dbPath, {
+    runId,
+    prompt,
+    status: options.generate ? "running" : "dry_run",
+    provider: options.generate ? parsed.provider : "local",
+    model: options.generate ? parsed.model : "context-draft",
+    metadata: {
+      semantic: options.semantic === true || options.fake === true || Boolean(options.modelRef),
+      approve_write: options.approveWrite === true,
+      generated: options.generate === true
+    },
+    now
+  });
+  const { prompt: _prompt, generate: _generate, approveWrite: _approveWrite, now: _now, ...retrievalOptions } = options;
+  const context = await retrieveKnowledgeContext({
+    ...retrievalOptions,
+    query: prompt
+  });
+  addRunEvent(options.dbPath, {
+    runId,
+    level: "info",
+    event: "context_retrieved",
+    metadata: {
+      results: context.results.length,
+      citations: context.citations.length,
+      warnings: context.warnings
+    },
+    now
+  });
+  let answer = localAnswer(prompt, context);
+  let generated = false;
+  let provider = "local";
+  let model = "context-draft";
+  let usage = {
+    input_tokens: estimateTokens(prompt) + context.excerpts.reduce((sum, excerpt) => sum + estimateTokens(excerpt.text), 0),
+    output_tokens: estimateTokens(answer),
+    cost_usd: 0
+  };
+  const warnings = [...context.warnings];
+  if (options.generate) {
+    try {
+      if (options.fake) {
+        generated = true;
+        provider = parsed.provider;
+        model = parsed.model;
+        answer = `Fake generated answer for: ${prompt}
+
+${answer}`;
+      } else {
+        const { generateText } = await import("ai");
+        const languageModel = await languageModelFor(modelRef, {
+          config: options.config,
+          env: options.env
+        });
+        const result = await generateText({
+          model: languageModel,
+          system: "You answer company knowledge-base prompts using only provided context and citation ids.",
+          prompt: promptForModel(prompt, context)
+        });
+        generated = true;
+        provider = parsed.provider;
+        model = parsed.model;
+        answer = result.text;
+        const normalized = normalizeAiSdkUsage({
+          provider,
+          model,
+          usage: result.usage,
+          providerMetadata: result.providerMetadata
+        });
+        usage = {
+          input_tokens: normalized.input_tokens,
+          output_tokens: normalized.output_tokens,
+          cost_usd: normalized.cost_usd
+        };
+      }
+    } catch (error48) {
+      addRunEvent(options.dbPath, {
+        runId,
+        level: "error",
+        event: "answer_generation_failed",
+        metadata: { message: error48 instanceof Error ? error48.message : String(error48) },
+        now
+      });
+      updateRun(options.dbPath, {
+        runId,
+        status: "failed",
+        provider: parsed.provider,
+        model: parsed.model,
+        metadata: {
+          generated: false,
+          error: error48 instanceof Error ? error48.message : String(error48)
+        },
+        now
+      });
+      throw error48;
+    }
   }
-  return null;
+  const updates = proposedUpdates(prompt, context);
+  const writePolicy = {
+    approved: options.approveWrite === true,
+    durable_writes_performed: false,
+    reason: options.approveWrite ? "Approval flag recorded; durable wiki writing is deferred to the wiki compile task." : "Dry-run mode: proposed wiki updates require approval before durable writes."
+  };
+  addRunEvent(options.dbPath, {
+    runId,
+    level: "info",
+    event: generated ? "answer_generated" : "answer_drafted",
+    metadata: {
+      provider,
+      model,
+      proposed_updates: updates.length,
+      durable_writes_performed: false
+    },
+    now
+  });
+  recordUsage(options.dbPath, runId, usage, provider, model, now, {
+    generated,
+    citations: context.citations.length
+  });
+  updateRun(options.dbPath, {
+    runId,
+    status: generated ? "completed" : "dry_run",
+    provider,
+    model,
+    metadata: {
+      generated,
+      citations: context.citations.length,
+      proposed_updates: updates.length,
+      approve_write: options.approveWrite === true
+    },
+    now
+  });
+  return {
+    run_id: runId,
+    prompt,
+    generated,
+    provider,
+    model,
+    answer,
+    context,
+    citations: context.citations,
+    proposed_wiki_updates: updates,
+    write_policy: writePolicy,
+    usage,
+    warnings
+  };
 }
-function assertPurposeAllowed(permissions, purpose) {
-  const mode = permissions.mode;
-  if (typeof mode === "string" && mode !== "read_only") {
-    throw new Error(`Source resolver denied ${purpose}. Permission mode is ${mode}, expected read_only.`);
+
+// src/outbox-consume.ts
+import { createHash as createHash4, randomUUID as randomUUID5 } from "crypto";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import { basename } from "path";
+
+// src/safety.ts
+import { createHash as createHash3, randomUUID as randomUUID4 } from "crypto";
+import { relative as relative2, resolve as resolve2, sep as sep2 } from "path";
+function envEnabled(name) {
+  const value = process.env[name];
+  return value === "1" || value === "true" || value === "yes";
+}
+function resolveSafetyPolicy(config2, workspace) {
+  const extended = config2;
+  const configuredBuckets = new Set(extended.safety?.network?.allowed_s3_buckets ?? []);
+  if (config2.storage.type === "s3" && config2.storage.s3?.bucket)
+    configuredBuckets.add(config2.storage.s3.bucket);
+  if (process.env.HASNA_KNOWLEDGE_ALLOWED_S3_BUCKETS) {
+    for (const bucket of process.env.HASNA_KNOWLEDGE_ALLOWED_S3_BUCKETS.split(",").map((entry) => entry.trim()).filter(Boolean)) {
+      configuredBuckets.add(bucket);
+    }
   }
-  const denied = permissions.denied_purposes;
-  if (Array.isArray(denied) && denied.includes(purpose)) {
-    throw new Error(`Source resolver denied ${purpose}. Purpose is explicitly denied.`);
+  return {
+    mode: config2.mode,
+    allowWriteRoots: [
+      workspace.home,
+      workspace.artifactsDir,
+      workspace.cacheDir,
+      workspace.exportsDir,
+      workspace.indexesDir,
+      workspace.logsDir,
+      workspace.runsDir,
+      workspace.schemasDir,
+      workspace.wikiDir
+    ].map((entry) => resolve2(entry)),
+    readOnlySourceAccess: true,
+    network: {
+      webSearchEnabled: extended.safety?.network?.web_search_enabled ?? envEnabled("HASNA_KNOWLEDGE_WEB_SEARCH"),
+      s3ReadsEnabled: extended.safety?.network?.s3_reads_enabled ?? envEnabled("HASNA_KNOWLEDGE_ALLOW_S3_READS"),
+      allowedS3Buckets: [...configuredBuckets].sort()
+    },
+    redaction: {
+      enabled: extended.safety?.redaction?.enabled ?? true
+    },
+    approvals: {
+      generatedWritesRequireApproval: extended.safety?.approvals?.generated_writes_require_approval ?? true
+    }
+  };
+}
+function isInside(root, target) {
+  const rel = relative2(root, target);
+  return rel === "" || !rel.startsWith("..") && rel !== ".." && !rel.startsWith(`..${sep2}`);
+}
+function assertWriteAllowed(targetPath, policy) {
+  const resolved = resolve2(targetPath);
+  if (!policy.allowWriteRoots.some((root) => isInside(root, resolved))) {
+    throw new Error(`Safety policy denied write outside .hasna/apps/knowledge: ${targetPath}`);
   }
-  const allowed = permissions.allowed_purposes;
-  if (Array.isArray(allowed) && allowed.length > 0 && !allowed.includes(purpose)) {
-    throw new Error(`Source resolver denied ${purpose}. Allowed purposes: ${allowed.join(", ")}`);
+}
+function assertS3ReadAllowed(uri, policy) {
+  const parsed = new URL(uri);
+  const bucket = parsed.hostname;
+  if (!policy.network.s3ReadsEnabled) {
+    throw new Error("Safety policy denied S3 read. Set safety.network.s3_reads_enabled=true or HASNA_KNOWLEDGE_ALLOW_S3_READS=1.");
+  }
+  if (!policy.network.allowedS3Buckets.includes(bucket)) {
+    throw new Error(`Safety policy denied S3 bucket "${bucket}". Add it to safety.network.allowed_s3_buckets or HASNA_KNOWLEDGE_ALLOWED_S3_BUCKETS.`);
   }
 }
-function sourceRevisionRef(sourceUri, revision, fallback) {
-  if (!revision)
-    return fallback;
-  try {
-    const parsed = parseSourceRef(sourceUri);
-    if (parsed.kind === "open-files" && parsed.entity === "file") {
-      return `${sourceUri}/revision/${encodeURIComponent(revision.revision)}`;
-    }
-  } catch {
-    return fallback;
+function assertWebSearchAllowed(policy) {
+  if (!policy.network.webSearchEnabled) {
+    throw new Error("Safety policy denied web search. Set safety.network.web_search_enabled=true or HASNA_KNOWLEDGE_WEB_SEARCH=1.");
   }
-  return fallback;
 }
-function selectSource(db, sourceUri, requestedRef) {
-  return db.query(`SELECT id, uri, kind, title, metadata_json, acl_json, updated_at
-     FROM sources
-     WHERE uri = ? OR uri = ?
-     ORDER BY CASE WHEN uri = ? THEN 0 ELSE 1 END
-     LIMIT 1`).get(sourceUri, requestedRef, sourceUri) ?? null;
+var REDACTION_PATTERNS = [
+  { type: "private_key_block", severity: "high", regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, replacement: "[REDACTED:private_key_block]" },
+  { type: "secret_assignment", severity: "high", regex: /\b(?:api[_-]?key|secret|token|password)\s*[:=]\s*['"]?[^'"\s]{8,}/gi, replacement: "[REDACTED:secret_assignment]" },
+  { type: "openai_api_key", severity: "high", regex: /\bsk-[A-Za-z0-9_-]{20,}\b/g, replacement: "[REDACTED:openai_api_key]" },
+  { type: "anthropic_api_key", severity: "high", regex: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g, replacement: "[REDACTED:anthropic_api_key]" },
+  { type: "aws_access_key_id", severity: "high", regex: /\bA(?:KIA|SIA)[A-Z0-9]{16}\b/g, replacement: "[REDACTED:aws_access_key_id]" }
+];
+function redactSecrets(text, policy) {
+  if (policy && !policy.redaction.enabled)
+    return { text, findings: [] };
+  let output = text;
+  const findings = [];
+  for (const pattern of REDACTION_PATTERNS) {
+    output = output.replace(pattern.regex, (match, ...args) => {
+      const offset = typeof args.at(-2) === "number" ? args.at(-2) : output.indexOf(match);
+      findings.push({
+        type: pattern.type,
+        severity: pattern.severity,
+        start: Math.max(0, offset),
+        end: Math.max(0, offset + match.length)
+      });
+      return pattern.replacement;
+    });
+  }
+  return { text: output, findings };
 }
-function selectRevision(db, sourceId, revisionId) {
-  if (revisionId) {
-    return db.query(`SELECT id, revision, hash, extracted_text_uri, metadata_json, created_at
-       FROM source_revisions
-       WHERE source_id = ? AND revision = ?
-       LIMIT 1`).get(sourceId, revisionId) ?? null;
+function auditId(input) {
+  return `audit_${createHash3("sha256").update(`${input.event_type}\x00${input.action}\x00${input.target_uri ?? ""}\x00${input.created_at ?? ""}\x00${JSON.stringify(input.metadata ?? {})}\x00${randomUUID4()}`).digest("hex").slice(0, 24)}`;
+}
+function recordAuditEvent(db, input) {
+  const createdAt = input.created_at ?? new Date().toISOString();
+  const id = auditId({ ...input, created_at: createdAt });
+  db.run(`INSERT INTO audit_events (id, event_type, action, target_uri, decision, metadata_json, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+    id,
+    input.event_type,
+    input.action,
+    input.target_uri ?? null,
+    input.decision,
+    JSON.stringify(input.metadata ?? {}),
+    createdAt
+  ]);
+  return id;
+}
+function recordRedactionFindings(db, input) {
+  const createdAt = input.created_at ?? new Date().toISOString();
+  for (const finding of input.findings) {
+    db.run(`INSERT INTO redaction_findings (id, source_uri, run_id, severity, finding_type, metadata_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+      `redact_${randomUUID4()}`,
+      input.source_uri ?? null,
+      input.run_id ?? null,
+      finding.severity,
+      finding.type,
+      JSON.stringify({ ...input.metadata ?? {}, start: finding.start, end: finding.end }),
+      createdAt
+    ]);
   }
-  return db.query(`SELECT id, revision, hash, extracted_text_uri, metadata_json, created_at
-     FROM source_revisions
-     WHERE source_id = ?
-     ORDER BY created_at DESC, revision DESC
-     LIMIT 1`).get(sourceId) ?? null;
+  return input.findings.length;
 }
-function countChunks(db, revisionId) {
-  if (!revisionId)
-    return 0;
-  const row = db.query("SELECT COUNT(*) AS n FROM chunks WHERE source_revision_id = ?").get(revisionId);
-  return row?.n ?? 0;
+
+// src/outbox-consume.ts
+function stableId3(prefix, value) {
+  return `${prefix}_${createHash4("sha256").update(value).digest("hex").slice(0, 20)}`;
 }
-function selectChunks(db, revisionId, limit) {
-  if (!revisionId || limit <= 0)
-    return [];
-  return db.query(`SELECT id, kind, ordinal, text, token_count, start_offset, end_offset, metadata_json
-     FROM chunks
-     WHERE source_revision_id = ?
-     ORDER BY ordinal ASC
-     LIMIT ?`).all(revisionId, limit);
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
 }
-async function resolveOpenFilesSource(options) {
-  const purpose = options.purpose ?? "knowledge_answer";
-  const limit = Math.max(0, Math.min(options.limit ?? 10, 100));
-  const resolvedAt = (options.now ?? new Date).toISOString();
-  const parsed = parseSourceRef(options.sourceRef);
-  const sourceUri = catalogSourceUriForRef(options.sourceRef, parsed);
-  const requestedRevision = revisionIdForSourceRef(options.sourceRef);
-  if (options.safetyPolicy) {
-    if (!options.safetyPolicy.readOnlySourceAccess)
-      throw new Error("Safety policy denied source resolution.");
-    assertWriteAllowed(options.dbPath, options.safetyPolicy);
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function buildSourceRef(event) {
+  const explicit = asString(event.source_ref) ?? asString(event.source_uri) ?? asString(event.uri);
+  if (explicit)
+    return explicit;
+  const fileId = asString(event.file_id);
+  if (fileId) {
+    const revision = asString(event.revision_id) ?? asString(event.revision);
+    const fileRef = `open-files://file/${encodeURIComponent(fileId)}`;
+    return revision ? `${fileRef}/revision/${encodeURIComponent(revision)}` : fileRef;
   }
-  migrateKnowledgeDb(options.dbPath);
-  const db = openKnowledgeDb(options.dbPath);
-  try {
-    return db.transaction(() => {
-      const source = selectSource(db, sourceUri, options.sourceRef);
-      if (!source) {
-        recordAuditEvent(db, {
-          event_type: "source_read",
-          action: "open_files_resolve_missing",
-          target_uri: options.sourceRef,
-          decision: "allow",
-          metadata: { purpose, read_only: true, source_uri: sourceUri },
-          created_at: resolvedAt
+  const sourceId = asString(event.source_id);
+  const path = asString(event.path);
+  if (sourceId && path) {
+    return `open-files://source/${encodeURIComponent(sourceId)}/path/${encodeURIComponent(path)}`;
+  }
+  throw new Error("Outbox event is missing source_ref, file_id, or source_id/path.");
+}
+function baseSourceUri(sourceRef, parsed) {
+  if (parsed.kind === "open-files" && parsed.entity === "file" && parsed.revision_id) {
+    return sourceRef.replace(/\/revision\/[^/]+$/, "");
+  }
+  return sourceRef;
+}
+function hashFromEvent(event) {
+  return asString(event.hash) ?? asString(event.checksum) ?? asString(event.sha256) ?? null;
+}
+function revisionFromEvent(event, parsed, hash2) {
+  return asString(event.revision_id) ?? asString(event.revision) ?? asString(event.version_id) ?? (parsed.kind === "open-files" ? parsed.revision_id : undefined) ?? hash2 ?? null;
+}
+function eventType(event) {
+  return (asString(event.event) ?? asString(event.type) ?? asString(event.action) ?? asString(event.change_type) ?? "changed").toLowerCase();
+}
+function titleFromEvent(event) {
+  const path = asString(event.path);
+  return asString(event.title) ?? asString(event.name) ?? (path ? basename(path) : null);
+}
+function normalizeEvent(event, now) {
+  const sourceRef = buildSourceRef(event);
+  const parsed = parseSourceRef(sourceRef);
+  const hash2 = hashFromEvent(event);
+  return {
+    raw: event,
+    eventType: eventType(event),
+    sourceRef,
+    sourceUri: baseSourceUri(sourceRef, parsed),
+    kind: parsed.kind,
+    title: titleFromEvent(event),
+    revision: revisionFromEvent(event, parsed, hash2),
+    hash: hash2,
+    status: asString(event.status)?.toLowerCase() ?? null,
+    updatedAt: asString(event.updated_at) ?? now,
+    acl: event.permissions ?? event.acl ?? undefined
+  };
+}
+function parseOutboxText(text) {
+  const trimmed = text.trim();
+  if (!trimmed)
+    return [];
+  if (trimmed.startsWith("[")) {
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed))
+      throw new Error("Outbox array parse failed.");
+    return parsed.map((entry) => {
+      const event = asObject(entry);
+      if (!event)
+        throw new Error("Outbox array entries must be objects.");
+      return event;
+    });
+  }
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      const object2 = asObject(parsed);
+      if (!object2)
+        throw new Error("Outbox object parse failed.");
+      if (Array.isArray(object2.events)) {
+        return object2.events.map((entry) => {
+          const event = asObject(entry);
+          if (!event)
+            throw new Error("Outbox events entries must be objects.");
+          return event;
         });
-        return {
-          source_ref: options.sourceRef,
-          source_uri: sourceUri,
-          purpose,
-          read_only: true,
-          resolved: false,
-          resolver: {
-            name: "open-files-read-only",
-            mode: "local_catalog",
-            contract: "open-files-knowledge-source-v1"
-          },
-          source: null,
-          revision: null,
-          content: {
-            mime: null,
-            size: null,
-            hash: null,
-            text_available: false,
-            chunks_total: 0,
-            chunks_returned: 0,
-            char_count_returned: 0,
-            extracted_text_ref: null,
-            bytes_available: false,
-            bytes_exposed: false
-          },
-          chunks: [],
-          citations: []
-        };
       }
-      const sourceMetadata = parseJsonObject2(source.metadata_json);
-      const permissions = parseJsonObject2(source.acl_json);
-      try {
-        assertPurposeAllowed(permissions, purpose);
-      } catch (error48) {
-        recordAuditEvent(db, {
-          event_type: "source_read",
-          action: "open_files_resolve",
-          target_uri: options.sourceRef,
-          decision: "deny",
-          metadata: {
-            purpose,
-            read_only: true,
-            source_uri: source.uri,
-            error: error48 instanceof Error ? error48.message : String(error48)
-          },
-          created_at: resolvedAt
-        });
+      if ("source_ref" in object2 || "source_uri" in object2 || "file_id" in object2)
+        return [object2];
+    } catch (error48) {
+      const lines = trimmed.split(/\r?\n/).filter((line) => line.trim().length > 0);
+      if (lines.length <= 1)
         throw error48;
-      }
-      const revision = selectRevision(db, source.id, requestedRevision);
-      const revisionMetadata = parseJsonObject2(revision?.metadata_json);
-      const totalChunks = countChunks(db, revision?.id ?? null);
-      const rows = selectChunks(db, revision?.id ?? null, limit);
-      const effectiveSourceRef = sourceRevisionRef(source.uri, revision, options.sourceRef);
-      const chunks = rows.map((row) => {
-        const metadata = parseJsonObject2(row.metadata_json);
-        const evidence = {
-          resolver: "open-files-read-only",
-          mode: "local_catalog",
-          purpose,
-          read_only: true,
-          source_ref: metadataString2(metadata, ["source_ref"]) ?? effectiveSourceRef,
-          source_uri: source.uri,
-          source_revision_id: revision?.id ?? null,
-          revision: revision?.revision ?? null,
-          hash: revision?.hash ?? metadataString2(metadata, ["hash"]),
-          chunk_id: row.id,
-          start_offset: row.start_offset,
-          end_offset: row.end_offset,
-          resolved_at: resolvedAt
-        };
-        const provenance = sourceProvenance({
-          source_ref: evidence.source_ref,
-          source_uri: evidence.source_uri,
-          source_kind: source.kind,
-          source_revision_id: evidence.source_revision_id,
-          revision: evidence.revision,
-          hash: evidence.hash,
-          chunk_id: row.id,
-          start_offset: row.start_offset,
-          end_offset: row.end_offset,
-          status: metadataString2(metadata, ["status"]),
-          resolver: evidence.resolver
-        });
-        return {
-          id: row.id,
-          kind: row.kind,
-          ordinal: row.ordinal,
-          text: row.text,
-          token_count: row.token_count,
-          start_offset: row.start_offset,
-          end_offset: row.end_offset,
-          metadata,
-          evidence,
-          provenance
-        };
+      return lines.map((line) => {
+        const event = asObject(JSON.parse(line));
+        if (!event)
+          throw new Error("Outbox JSONL entries must be objects.");
+        return event;
       });
-      const citations = chunks.map((chunk) => ({
-        source_ref: chunk.evidence.source_ref,
-        source_uri: source.uri,
-        chunk_id: chunk.id,
-        quote: chunk.text.slice(0, 500),
-        start_offset: chunk.start_offset,
-        end_offset: chunk.end_offset,
-        evidence: chunk.evidence,
-        provenance: chunk.provenance
-      }));
+    }
+  }
+  return trimmed.split(/\r?\n/).filter((line) => line.trim().length > 0).map((line) => {
+    const event = asObject(JSON.parse(line));
+    if (!event)
+      throw new Error("Outbox JSONL entries must be objects.");
+    return event;
+  });
+}
+async function readS3Text(uri, config2, safetyPolicy) {
+  const parsed = new URL(uri);
+  const bucket = parsed.hostname;
+  const key = decodeURIComponent(parsed.pathname.replace(/^\/+/, ""));
+  if (!bucket || !key)
+    throw new Error(`Invalid S3 outbox URI: ${uri}`);
+  if (safetyPolicy)
+    assertS3ReadAllowed(uri, safetyPolicy);
+  const [{ S3Client, GetObjectCommand }, { fromIni }] = await Promise.all([
+    import("@aws-sdk/client-s3"),
+    import("@aws-sdk/credential-providers")
+  ]);
+  const s3Config = config2?.storage.type === "s3" && config2.storage.s3?.bucket === bucket ? config2.storage.s3 : undefined;
+  const client = new S3Client({
+    region: s3Config?.region,
+    credentials: s3Config?.profile ? fromIni({ profile: s3Config.profile }) : undefined,
+    maxAttempts: s3Config?.max_attempts
+  });
+  const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+  if (!response.Body)
+    return "";
+  return await response.Body.transformToString();
+}
+async function readOutboxInput(input, config2, safetyPolicy) {
+  if (input.startsWith("s3://"))
+    return readS3Text(input, config2, safetyPolicy);
+  if (!existsSync4(input))
+    throw new Error(`Outbox not found: ${input}`);
+  return readFileSync4(input, "utf8");
+}
+function mergeJson(existing, patch) {
+  let base = {};
+  if (existing) {
+    try {
+      base = asObject(JSON.parse(existing)) ?? {};
+    } catch {
+      base = {};
+    }
+  }
+  return JSON.stringify({ ...base, ...patch });
+}
+function ensureSource(db, event, now) {
+  const id = stableId3("src", event.sourceUri);
+  db.run(`INSERT INTO sources (id, uri, kind, title, metadata_json, acl_json, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(uri) DO UPDATE SET
+       kind = excluded.kind,
+       title = COALESCE(excluded.title, sources.title),
+       updated_at = excluded.updated_at`, [
+    id,
+    event.sourceUri,
+    event.kind,
+    event.title,
+    JSON.stringify({ source_ref: event.sourceRef, source_uri: event.sourceUri, status: event.status, last_outbox_event: event.eventType }),
+    JSON.stringify(event.acl ?? {}),
+    now,
+    event.updatedAt
+  ]);
+  const row = db.query("SELECT id, metadata_json, acl_json FROM sources WHERE uri = ?").get(event.sourceUri);
+  if (!row)
+    throw new Error(`Failed to upsert source for outbox event: ${event.sourceUri}`);
+  const patch = {
+    source_ref: event.sourceRef,
+    source_uri: event.sourceUri,
+    last_outbox_event: event.eventType,
+    last_outbox_at: event.updatedAt
+  };
+  if (event.status)
+    patch.status = event.status;
+  if (asString(event.raw.path))
+    patch.path = event.raw.path;
+  db.run("UPDATE sources SET metadata_json = ?, acl_json = CASE WHEN ? IS NULL THEN acl_json ELSE ? END, updated_at = ? WHERE id = ?", [
+    mergeJson(row.metadata_json, patch),
+    event.acl === undefined ? null : JSON.stringify(event.acl),
+    event.acl === undefined ? null : JSON.stringify(event.acl),
+    event.updatedAt,
+    row.id
+  ]);
+  return row.id;
+}
+function ensureRevision(db, sourceId, event, now) {
+  if (!event.revision)
+    return null;
+  const id = stableId3("rev", `${sourceId}\x00${event.revision}`);
+  const metadata = {
+    source_ref: event.sourceRef,
+    source_uri: event.sourceUri,
+    status: event.status,
+    last_outbox_event: event.eventType,
+    reindex_required: true
+  };
+  db.run(`INSERT INTO source_revisions (id, source_id, revision, hash, extracted_text_uri, metadata_json, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(source_id, revision) DO UPDATE SET
+       hash = COALESCE(excluded.hash, source_revisions.hash),
+       metadata_json = excluded.metadata_json`, [id, sourceId, event.revision, event.hash, asString(event.raw.extracted_text_ref) ?? null, JSON.stringify(metadata), now]);
+  const row = db.query("SELECT id FROM source_revisions WHERE source_id = ? AND revision = ?").get(sourceId, event.revision);
+  return row?.id ?? null;
+}
+function revisionIdsForEvent(db, sourceId, event) {
+  if (event.revision) {
+    return db.query("SELECT id FROM source_revisions WHERE source_id = ? AND revision = ?").all(sourceId, event.revision).map((row) => row.id);
+  }
+  if (event.hash) {
+    return db.query("SELECT id FROM source_revisions WHERE source_id = ? AND hash = ?").all(sourceId, event.hash).map((row) => row.id);
+  }
+  return db.query("SELECT id FROM source_revisions WHERE source_id = ?").all(sourceId).map((row) => row.id);
+}
+function invalidateRevision(db, revisionId) {
+  const chunks = db.query("SELECT id FROM chunks WHERE source_revision_id = ?").all(revisionId);
+  let embeddingsDeleted = 0;
+  let vectorEntriesDeleted = 0;
+  for (const chunk of chunks) {
+    const row = db.query("SELECT COUNT(*) AS n FROM chunk_embeddings WHERE chunk_id = ?").get(chunk.id);
+    embeddingsDeleted += row?.n ?? 0;
+    const vectorRow = db.query("SELECT COUNT(*) AS n FROM vector_index_entries WHERE chunk_id = ?").get(chunk.id);
+    vectorEntriesDeleted += vectorRow?.n ?? 0;
+    db.run("DELETE FROM vector_index_entries WHERE chunk_id = ?", [chunk.id]);
+    db.run("DELETE FROM chunk_embeddings WHERE chunk_id = ?", [chunk.id]);
+    db.run("DELETE FROM chunks_fts WHERE chunk_id = ?", [chunk.id]);
+  }
+  db.run("DELETE FROM chunks WHERE source_revision_id = ?", [revisionId]);
+  const revision = db.query("SELECT metadata_json FROM source_revisions WHERE id = ?").get(revisionId);
+  db.run("UPDATE source_revisions SET metadata_json = ? WHERE id = ?", [mergeJson(revision?.metadata_json, { reindex_required: true, invalidated_at: new Date().toISOString() }), revisionId]);
+  return { chunksDeleted: chunks.length, embeddingsDeleted, vectorEntriesDeleted };
+}
+function isDeleteEvent(eventType2, status) {
+  return status === "deleted" || ["delete", "deleted", "remove", "removed"].includes(eventType2);
+}
+function isMoveEvent(eventType2) {
+  return ["move", "moved", "rename", "renamed", "path_changed"].includes(eventType2);
+}
+function isPermissionEvent(eventType2) {
+  return ["permission", "permissions", "permission_changed", "acl_changed"].includes(eventType2);
+}
+async function consumeOpenFilesOutbox(options) {
+  const now = (options.now ?? new Date).toISOString();
+  if (options.safetyPolicy)
+    assertWriteAllowed(options.dbPath, options.safetyPolicy);
+  migrateKnowledgeDb(options.dbPath);
+  const text = await readOutboxInput(options.input, options.config, options.safetyPolicy);
+  const events = parseOutboxText(text);
+  const db = openKnowledgeDb(options.dbPath);
+  const runId = `run_${randomUUID5()}`;
+  try {
+    return db.transaction(() => {
+      db.run(`INSERT INTO runs (id, type, prompt, status, provider, model, metadata_json, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        runId,
+        "open-files-outbox",
+        options.input,
+        "completed",
+        "local",
+        "open-files-outbox",
+        JSON.stringify({ path: options.input, events: events.length }),
+        now,
+        now
+      ]);
+      const sourcesTouched = new Set;
+      const revisionsTouched = new Set;
+      let chunksDeleted = 0;
+      let embeddingsDeleted = 0;
+      let vectorEntriesDeleted = 0;
+      let staleRevisions = 0;
+      let deletedSources = 0;
+      let movedSources = 0;
+      let permissionUpdates = 0;
       recordAuditEvent(db, {
         event_type: "source_read",
-        action: "open_files_resolve",
-        target_uri: options.sourceRef,
+        action: options.input.startsWith("s3://") ? "s3_outbox_read" : "local_outbox_read",
+        target_uri: options.input,
+        decision: "allow",
+        metadata: { events: events.length, read_only: true },
+        created_at: now
+      });
+      events.forEach((raw, index) => {
+        const event = normalizeEvent(raw, now);
+        const sourceId = ensureSource(db, event, now);
+        sourcesTouched.add(sourceId);
+        const createdRevisionId = ensureRevision(db, sourceId, event, now);
+        if (createdRevisionId)
+          revisionsTouched.add(createdRevisionId);
+        const affectedRevisionIds = revisionIdsForEvent(db, sourceId, event);
+        for (const revisionId of affectedRevisionIds) {
+          revisionsTouched.add(revisionId);
+          const invalidation = invalidateRevision(db, revisionId);
+          chunksDeleted += invalidation.chunksDeleted;
+          embeddingsDeleted += invalidation.embeddingsDeleted;
+          vectorEntriesDeleted += invalidation.vectorEntriesDeleted;
+          staleRevisions += 1;
+        }
+        if (isDeleteEvent(event.eventType, event.status))
+          deletedSources += 1;
+        if (isMoveEvent(event.eventType))
+          movedSources += 1;
+        if (isPermissionEvent(event.eventType) || event.acl !== undefined)
+          permissionUpdates += 1;
+        db.run(`INSERT INTO run_events (id, run_id, level, event, metadata_json, created_at)
+           VALUES (?, ?, ?, ?, ?, ?)`, [
+          stableId3("evt", `${runId}\x00${index}\x00${event.sourceRef}\x00${event.eventType}`),
+          runId,
+          "info",
+          event.eventType,
+          JSON.stringify({
+            source_ref: event.sourceRef,
+            source_uri: event.sourceUri,
+            revision: event.revision,
+            hash: event.hash,
+            status: event.status,
+            affected_revisions: affectedRevisionIds.length
+          }),
+          event.updatedAt
+        ]);
+      });
+      db.run(`INSERT INTO provider_usage (id, run_id, provider, model, input_tokens, output_tokens, cost_usd, metadata_json, created_at)
+         VALUES (?, ?, ?, ?, 0, 0, 0, ?, ?)`, [
+        stableId3("usage", runId),
+        runId,
+        "local",
+        "open-files-outbox",
+        JSON.stringify({ note: "No model provider used for outbox invalidation." }),
+        now
+      ]);
+      recordAuditEvent(db, {
+        event_type: "write",
+        action: "knowledge_outbox_invalidation",
+        target_uri: options.dbPath,
         decision: "allow",
         metadata: {
-          purpose,
-          read_only: true,
-          source_uri: source.uri,
-          revision: revision?.revision ?? null,
-          chunks_returned: chunks.length,
-          chunks_total: totalChunks
+          run_id: runId,
+          events: events.length,
+          sources: sourcesTouched.size,
+          revisions: revisionsTouched.size,
+          chunks_deleted: chunksDeleted,
+          embeddings_deleted: embeddingsDeleted,
+          vector_entries_deleted: vectorEntriesDeleted
         },
-        created_at: resolvedAt
+        created_at: now
       });
-      const mime = metadataString2(sourceMetadata, ["mime", "content_type"]) ?? metadataString2(revisionMetadata, ["mime", "content_type"]);
-      const size = metadataNumber2(sourceMetadata, ["size", "size_bytes"]) ?? metadataNumber2(revisionMetadata, ["size", "size_bytes"]);
       return {
-        source_ref: effectiveSourceRef,
-        source_uri: source.uri,
-        purpose,
-        read_only: true,
-        resolved: true,
-        resolver: {
-          name: "open-files-read-only",
-          mode: "local_catalog",
-          contract: "open-files-knowledge-source-v1"
-        },
-        source: {
-          id: source.id,
-          uri: source.uri,
-          kind: source.kind,
-          title: source.title,
-          metadata: sourceMetadata,
-          permissions,
-          updated_at: source.updated_at
-        },
-        revision: revision ? {
-          id: revision.id,
-          revision: revision.revision,
-          hash: revision.hash,
-          extracted_text_uri: revision.extracted_text_uri,
-          metadata: revisionMetadata,
-          created_at: revision.created_at,
-          reindex_required: revisionMetadata.reindex_required === true
-        } : null,
-        content: {
-          mime,
-          size,
-          hash: revision?.hash ?? metadataString2(sourceMetadata, ["hash", "checksum", "sha256"]),
-          text_available: totalChunks > 0,
-          chunks_total: totalChunks,
-          chunks_returned: chunks.length,
-          char_count_returned: chunks.reduce((sum, chunk) => sum + chunk.text.length, 0),
-          extracted_text_ref: revision?.extracted_text_uri ?? metadataString2(revisionMetadata, ["extracted_text_ref", "extracted_text_uri"]),
-          bytes_available: false,
-          bytes_exposed: false
-        },
-        chunks,
-        citations
+        path: options.input,
+        db_path: options.dbPath,
+        run_id: runId,
+        events_seen: events.length,
+        sources_touched: sourcesTouched.size,
+        revisions_touched: revisionsTouched.size,
+        chunks_deleted: chunksDeleted,
+        embeddings_deleted: embeddingsDeleted,
+        vector_entries_deleted: vectorEntriesDeleted,
+        stale_revisions: staleRevisions,
+        deleted_sources: deletedSources,
+        moved_sources: movedSources,
+        permission_updates: permissionUpdates
       };
     })();
   } finally {
     db.close();
   }
 }
-
-// src/source-ingest.ts
-function sha256Text(text) {
-  return `sha256:${createHash5("sha256").update(text).digest("hex")}`;
+
+// src/manifest-ingest.ts
+import { createHash as createHash5 } from "crypto";
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { basename as basename2 } from "path";
+function stableId4(prefix, value) {
+  return `${prefix}_${createHash5("sha256").update(value).digest("hex").slice(0, 20)}`;
+}
+function asObject2(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function asString2(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function buildSourceRefFromItem(item) {
+  const explicit = asString2(item.source_ref) ?? asString2(item.source_uri) ?? asString2(item.uri);
+  if (explicit)
+    return explicit;
+  const fileId = asString2(item.file_id);
+  if (fileId) {
+    const revision = asString2(item.revision_id) ?? asString2(item.revision);
+    const fileRef = `open-files://file/${encodeURIComponent(fileId)}`;
+    return revision ? `${fileRef}/revision/${encodeURIComponent(revision)}` : fileRef;
+  }
+  const sourceId = asString2(item.source_id);
+  const path = asString2(item.path);
+  if (sourceId && path) {
+    return `open-files://source/${encodeURIComponent(sourceId)}/path/${encodeURIComponent(path)}`;
+  }
+  throw new Error("Manifest item is missing source_ref, file_id, or source_id/path.");
+}
+function baseSourceUri2(sourceRef, parsed) {
+  if (parsed.kind === "open-files" && parsed.entity === "file" && parsed.revision_id) {
+    return sourceRef.replace(/\/revision\/[^/]+$/, "");
+  }
+  return sourceRef;
+}
+function textFromItem(item) {
+  const direct = asString2(item.extracted_text) ?? asString2(item.text) ?? asString2(item.content_text) ?? asString2(item.markdown);
+  if (direct !== undefined)
+    return direct;
+  const content = item.content;
+  return typeof content === "string" ? content : null;
+}
+function extractedTextUriFromItem(item) {
+  const direct = asString2(item.extracted_text_ref) ?? asString2(item.extracted_text_uri) ?? asString2(item.text_ref);
+  if (direct)
+    return direct;
+  const content = asObject2(item.content);
+  return asString2(content?.extracted_text_ref) ?? asString2(content?.extracted_text_uri) ?? null;
+}
+function titleFromItem(item) {
+  const path = asString2(item.path);
+  return asString2(item.title) ?? asString2(item.name) ?? (path ? basename2(path) : null);
+}
+function hashFromItem(item) {
+  return asString2(item.hash) ?? asString2(item.checksum) ?? asString2(item.sha256) ?? null;
+}
+function revisionFromItem(item, parsed, hash2) {
+  const revision = asString2(item.revision_id) ?? asString2(item.revision) ?? asString2(item.version_id) ?? (parsed.kind === "open-files" ? parsed.revision_id : undefined) ?? hash2 ?? asString2(item.updated_at);
+  return revision ?? "current";
+}
+function metadataFromItem(item, normalized) {
+  const metadata = {};
+  for (const [key, value] of Object.entries(item)) {
+    if (["text", "content", "content_text", "extracted_text", "markdown"].includes(key))
+      continue;
+    metadata[key] = value;
+  }
+  metadata.source_ref = normalized.sourceRef;
+  metadata.source_uri = normalized.sourceUri;
+  metadata.status = normalized.status;
+  return metadata;
+}
+function normalizeManifestItem(item, now) {
+  const sourceRef = buildSourceRefFromItem(item);
+  const parsed = parseSourceRef(sourceRef);
+  const sourceUri = baseSourceUri2(sourceRef, parsed);
+  const hash2 = hashFromItem(item);
+  const status = asString2(item.status) ?? "active";
+  return {
+    raw: item,
+    sourceRef,
+    sourceUri,
+    kind: parsed.kind,
+    title: titleFromItem(item),
+    revision: revisionFromItem(item, parsed, hash2),
+    hash: hash2,
+    extractedTextUri: extractedTextUriFromItem(item),
+    text: textFromItem(item),
+    metadata: metadataFromItem(item, { sourceRef, sourceUri, status }),
+    acl: item.permissions ?? item.acl ?? {},
+    status,
+    updatedAt: asString2(item.updated_at) ?? now
+  };
 }
-function stripHtml(html) {
-  return html.replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<style[\s\S]*?<\/style>/gi, " ").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/\s+\n/g, `
-`).replace(/\n\s+/g, `
-`).replace(/[ \t]{2,}/g, " ").trim();
+function parseManifestText(text) {
+  const trimmed = text.trim();
+  if (!trimmed)
+    return [];
+  if (trimmed.startsWith("[")) {
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed))
+      throw new Error("Manifest array parse failed.");
+    return parsed.map((entry) => {
+      const item = asObject2(entry);
+      if (!item)
+        throw new Error("Manifest array entries must be objects.");
+      return item;
+    });
+  }
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      const object2 = asObject2(parsed);
+      if (!object2)
+        throw new Error("Manifest object parse failed.");
+      if (Array.isArray(object2.items)) {
+        return object2.items.map((entry) => {
+          const item = asObject2(entry);
+          if (!item)
+            throw new Error("Manifest items entries must be objects.");
+          return item;
+        });
+      }
+      if ("source_ref" in object2 || "source_uri" in object2 || "file_id" in object2)
+        return [object2];
+    } catch (error48) {
+      const lines = trimmed.split(/\r?\n/).filter((line) => line.trim().length > 0);
+      if (lines.length <= 1)
+        throw error48;
+      return lines.map((line) => {
+        const item = asObject2(JSON.parse(line));
+        if (!item)
+          throw new Error("Manifest JSONL entries must be objects.");
+        return item;
+      });
+    }
+  }
+  return trimmed.split(/\r?\n/).filter((line) => line.trim().length > 0).map((line) => {
+    const item = asObject2(JSON.parse(line));
+    if (!item)
+      throw new Error("Manifest JSONL entries must be objects.");
+    return item;
+  });
 }
-async function readS3Text3(uri, config2, safetyPolicy) {
+async function readS3Text2(uri, config2, safetyPolicy) {
   const parsed = new URL(uri);
   const bucket = parsed.hostname;
   const key = decodeURIComponent(parsed.pathname.replace(/^\/+/, ""));
   if (!bucket || !key)
-    throw new Error(`Invalid S3 source URI: ${uri}`);
+    throw new Error(`Invalid S3 manifest URI: ${uri}`);
   if (safetyPolicy)
     assertS3ReadAllowed(uri, safetyPolicy);
   const [{ S3Client, GetObjectCommand }, { fromIni }] = await Promise.all([
@@ -16201,199 +16583,259 @@ async function readS3Text3(uri, config2, safetyPolicy) {
     return "";
   return await response.Body.transformToString();
 }
-async function readWebText(uri, safetyPolicy) {
-  if (safetyPolicy)
-    assertWebSearchAllowed(safetyPolicy);
-  const response = await fetch(uri, {
-    headers: {
-      accept: "text/markdown,text/plain,text/html,application/json;q=0.8,*/*;q=0.5",
-      "user-agent": "@hasna/knowledge source-ingest"
+async function readManifestInput(input, config2, safetyPolicy) {
+  if (input.startsWith("s3://"))
+    return readS3Text2(input, config2, safetyPolicy);
+  if (!existsSync5(input))
+    throw new Error(`Manifest not found: ${input}`);
+  return readFileSync5(input, "utf8");
+}
+function chunkText(text, maxChars, overlapChars) {
+  const normalized = text.replace(/\r\n/g, `
+`);
+  if (!normalized.trim())
+    return [];
+  const chunks = [];
+  let start = 0;
+  while (start < normalized.length) {
+    const hardEnd = Math.min(normalized.length, start + maxChars);
+    let end = hardEnd;
+    if (hardEnd < normalized.length) {
+      const paragraphBreak = normalized.lastIndexOf(`
+
+`, hardEnd);
+      const sentenceBreak = normalized.lastIndexOf(". ", hardEnd);
+      const candidate = Math.max(paragraphBreak, sentenceBreak);
+      if (candidate > start + Math.floor(maxChars * 0.5))
+        end = candidate + (candidate === paragraphBreak ? 2 : 1);
     }
-  });
-  if (!response.ok)
-    throw new Error(`Web source read failed ${response.status}: ${uri}`);
-  const mime = response.headers.get("content-type");
-  const body = await response.text();
-  return { text: mime?.includes("html") ? stripHtml(body) : body, mime };
+    const chunk = normalized.slice(start, end).trim();
+    if (chunk) {
+      chunks.push({
+        ordinal: chunks.length,
+        text: chunk,
+        startOffset: start,
+        endOffset: end
+      });
+    }
+    if (end >= normalized.length)
+      break;
+    start = Math.max(0, end - overlapChars);
+  }
+  return chunks;
 }
-function titleForRef(parsed) {
-  if (parsed.kind === "file")
-    return basename3(parsed.path);
-  if (parsed.kind === "s3")
-    return basename3(parsed.key);
-  if (parsed.kind === "web")
-    return basename3(new URL(parsed.url).pathname) || parsed.url;
-  return parsed.path ? basename3(parsed.path) : parsed.id;
+function estimateTokenCount(text) {
+  const words = text.trim().split(/\s+/).filter(Boolean).length;
+  return Math.max(1, Math.ceil(words * 1.25));
 }
-async function readDirectSourceText(parsed, config2, safetyPolicy) {
-  if (parsed.kind === "file") {
-    if (!existsSync6(parsed.path))
-      throw new Error(`Source file not found: ${parsed.path}`);
-    const text = readFileSync6(parsed.path, "utf8");
-    return {
-      text,
-      contentSource: "file",
-      title: titleForRef(parsed),
-      mime: "text/plain",
-      size: text.length,
-      hash: sha256Text(text),
-      revision: null,
-      extractedTextRef: null,
-      metadata: { path: parsed.path },
-      permissions: { mode: "read_only" }
-    };
-  }
-  if (parsed.kind === "s3") {
-    const text = await readS3Text3(parsed.uri, config2, safetyPolicy);
-    return {
-      text,
-      contentSource: "s3",
-      title: titleForRef(parsed),
-      mime: "text/plain",
-      size: text.length,
-      hash: sha256Text(text),
-      revision: null,
-      extractedTextRef: null,
-      metadata: { bucket: parsed.bucket, key: parsed.key },
-      permissions: { mode: "read_only" }
-    };
+function deleteChunksForRevision(db, sourceRevisionId) {
+  const rows = db.query("SELECT id FROM chunks WHERE source_revision_id = ?").all(sourceRevisionId);
+  for (const row of rows) {
+    db.run("DELETE FROM chunks_fts WHERE chunk_id = ?", [row.id]);
   }
-  if (parsed.kind === "web") {
-    const web = await readWebText(parsed.url, safetyPolicy);
-    return {
-      text: web.text,
-      contentSource: "web",
-      title: titleForRef(parsed),
-      mime: web.mime,
-      size: web.text.length,
-      hash: sha256Text(web.text),
-      revision: null,
-      extractedTextRef: null,
-      metadata: { url: parsed.url },
-      permissions: { mode: "read_only" }
-    };
+  db.run("DELETE FROM chunks WHERE source_revision_id = ?", [sourceRevisionId]);
+  return rows.length;
+}
+function upsertSource(db, item, now) {
+  const sourceId = stableId4("src", item.sourceUri);
+  db.run(`INSERT INTO sources (id, uri, kind, title, metadata_json, acl_json, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(uri) DO UPDATE SET
+       kind = excluded.kind,
+       title = excluded.title,
+       metadata_json = excluded.metadata_json,
+       acl_json = excluded.acl_json,
+       updated_at = excluded.updated_at`, [
+    sourceId,
+    item.sourceUri,
+    item.kind,
+    item.title,
+    JSON.stringify(item.metadata),
+    JSON.stringify(item.acl ?? {}),
+    now,
+    item.updatedAt
+  ]);
+  const row = db.query("SELECT id FROM sources WHERE uri = ?").get(item.sourceUri);
+  if (!row)
+    throw new Error(`Failed to upsert source: ${item.sourceUri}`);
+  return row.id;
+}
+function upsertRevision(db, sourceId, item, now) {
+  const revisionId = stableId4("rev", `${sourceId}\x00${item.revision}`);
+  db.run(`INSERT INTO source_revisions (id, source_id, revision, hash, extracted_text_uri, metadata_json, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(source_id, revision) DO UPDATE SET
+       hash = excluded.hash,
+       extracted_text_uri = excluded.extracted_text_uri,
+       metadata_json = excluded.metadata_json`, [
+    revisionId,
+    sourceId,
+    item.revision,
+    item.hash,
+    item.extractedTextUri,
+    JSON.stringify(item.metadata),
+    now
+  ]);
+  const row = db.query("SELECT id FROM source_revisions WHERE source_id = ? AND revision = ?").get(sourceId, item.revision);
+  if (!row)
+    throw new Error(`Failed to upsert source revision: ${item.sourceRef}`);
+  return row.id;
+}
+function insertChunks(db, sourceRevisionId, item, now, maxChars, overlapChars, safetyPolicy) {
+  if (!item.text || item.status.toLowerCase() === "deleted")
+    return { chunksInserted: 0, redactions: 0 };
+  const redacted = redactSecrets(item.text, safetyPolicy);
+  if (redacted.findings.length > 0) {
+    recordRedactionFindings(db, {
+      source_uri: item.sourceUri,
+      findings: redacted.findings,
+      metadata: { source_ref: item.sourceRef, revision: item.revision },
+      created_at: now
+    });
+    recordAuditEvent(db, {
+      event_type: "redaction",
+      action: "source_text_redact",
+      target_uri: item.sourceUri,
+      decision: "redacted",
+      metadata: { findings: redacted.findings.length, source_ref: item.sourceRef, revision: item.revision },
+      created_at: now
+    });
   }
-  throw new Error(`Direct source reading is not available for ${parsed.uri}`);
-}
-async function readTextRef(uri, config2, safetyPolicy) {
-  if (uri.startsWith("open-files://")) {
-    throw new Error("Open-files extracted text refs require an open-files resolver API. Ingest an open-files manifest with extracted_text or an extracted_text_ref using file://, s3://, or https://.");
+  const chunks = chunkText(redacted.text, maxChars, overlapChars);
+  for (const chunk of chunks) {
+    const chunkId = stableId4("chk", `${sourceRevisionId}\x00${chunk.ordinal}\x00${chunk.text}`);
+    const provenance = sourceProvenance({
+      source_ref: item.sourceRef,
+      source_uri: item.sourceUri,
+      source_kind: item.kind,
+      source_revision_id: sourceRevisionId,
+      revision: item.revision,
+      hash: item.hash,
+      chunk_id: chunkId,
+      start_offset: chunk.startOffset,
+      end_offset: chunk.endOffset,
+      status: item.status,
+      resolver: "open-files-read-only"
+    });
+    const metadata = withProvenance({
+      source_ref: item.sourceRef,
+      source_uri: item.sourceUri,
+      source_kind: item.kind,
+      source_revision_id: sourceRevisionId,
+      revision: item.revision,
+      hash: item.hash,
+      status: item.status,
+      path: asString2(item.raw.path) ?? null,
+      mime: asString2(item.raw.mime) ?? asString2(item.raw.content_type) ?? null,
+      size: asNumber(item.raw.size) ?? null
+    }, provenance);
+    db.run(`INSERT INTO chunks (id, source_revision_id, kind, ordinal, text, token_count, start_offset, end_offset, metadata_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      chunkId,
+      sourceRevisionId,
+      "source",
+      chunk.ordinal,
+      chunk.text,
+      estimateTokenCount(chunk.text),
+      chunk.startOffset,
+      chunk.endOffset,
+      JSON.stringify(metadata),
+      now
+    ]);
+    db.run("INSERT INTO chunks_fts (chunk_id, text, title, source_uri) VALUES (?, ?, ?, ?)", [chunkId, chunk.text, item.title ?? "", item.sourceUri]);
   }
-  const parsed = parseSourceRef(uri);
-  const direct = await readDirectSourceText(parsed, config2, safetyPolicy);
-  return { text: direct.text, contentSource: "extracted_text_ref" };
+  return { chunksInserted: chunks.length, redactions: redacted.findings.length };
 }
-async function readOpenFilesSourceText(options) {
-  const resolved = await resolveOpenFilesSource({
+async function ingestOpenFilesManifest(options) {
+  const now = options.now ?? new Date;
+  if (options.safetyPolicy)
+    assertWriteAllowed(options.dbPath, options.safetyPolicy);
+  migrateKnowledgeDb(options.dbPath);
+  const text = await readManifestInput(options.input, options.config, options.safetyPolicy);
+  const items = parseManifestText(text);
+  return ingestOpenFilesManifestItems({
     dbPath: options.dbPath,
-    sourceRef: options.sourceRef,
-    purpose: options.purpose ?? "knowledge_index",
-    limit: 100,
+    items,
+    sourceLabel: options.input,
     safetyPolicy: options.safetyPolicy,
-    now: options.now
+    now,
+    maxChunkChars: options.maxChunkChars,
+    chunkOverlapChars: options.chunkOverlapChars
   });
-  if (!resolved.resolved) {
-    throw new Error("Open-files source is not in the local knowledge catalog. Ingest an open-files manifest first or use the open-files resolver API.");
-  }
-  if (resolved.revision?.extracted_text_uri && !resolved.content.text_available) {
-    const textRef = await readTextRef(resolved.revision.extracted_text_uri, options.config, options.safetyPolicy);
-    return {
-      text: textRef.text,
-      contentSource: textRef.contentSource,
-      title: resolved.source?.title ?? null,
-      mime: resolved.content.mime,
-      size: textRef.text.length,
-      hash: resolved.revision.hash ?? sha256Text(textRef.text),
-      revision: resolved.revision.revision,
-      extractedTextRef: resolved.revision.extracted_text_uri,
-      metadata: resolved.source?.metadata ?? {},
-      permissions: resolved.source?.permissions ?? { mode: "read_only" }
-    };
-  }
-  if (resolved.chunks.length === 0) {
-    throw new Error("Open-files source has no extracted text chunks yet. Ingest an open-files manifest with extracted_text or extracted_text_ref first.");
-  }
-  const text = resolved.chunks.map((chunk) => chunk.text).join(`
-
-`);
-  return {
-    text,
-    contentSource: "catalog_chunks",
-    title: resolved.source?.title ?? null,
-    mime: resolved.content.mime,
-    size: text.length,
-    hash: resolved.revision?.hash ?? sha256Text(text),
-    revision: resolved.revision?.revision ?? null,
-    extractedTextRef: resolved.revision?.extracted_text_uri ?? null,
-    metadata: resolved.source?.metadata ?? {},
-    permissions: resolved.source?.permissions ?? { mode: "read_only" }
-  };
 }
-function manifestItemForSource(sourceRef, parsed, resolved, purpose) {
-  const hash2 = resolved.hash ?? sha256Text(resolved.text);
-  const metadata = {
-    ...resolved.metadata,
-    source_ref: sourceRef,
-    content_source: resolved.contentSource,
-    read_only: true
-  };
-  const item = {
-    source_ref: sourceRef,
-    name: resolved.title ?? titleForRef(parsed),
-    mime: resolved.mime ?? "text/plain",
-    size: resolved.size ?? resolved.text.length,
-    hash: hash2,
-    revision: resolved.revision ?? hash2,
-    status: "active",
-    updated_at: new Date().toISOString(),
-    permissions: {
-      mode: "read_only",
-      allowed_purposes: [purpose],
-      ...resolved.permissions
-    },
-    metadata,
-    extracted_text_ref: resolved.extractedTextRef,
-    extracted_text: resolved.text
-  };
-  if (parsed.kind === "open-files") {
-    if (parsed.entity === "file")
-      item.file_id = parsed.id;
-    if (parsed.entity === "source") {
-      item.source_id = parsed.id;
-      item.path = parsed.path;
-    }
+async function ingestOpenFilesManifestItems(options) {
+  const now = (options.now ?? new Date).toISOString();
+  const maxChunkChars = options.maxChunkChars ?? 4000;
+  const chunkOverlapChars = options.chunkOverlapChars ?? 200;
+  if (maxChunkChars < 500)
+    throw new Error("maxChunkChars must be at least 500.");
+  if (chunkOverlapChars < 0 || chunkOverlapChars >= maxChunkChars)
+    throw new Error("chunkOverlapChars must be less than maxChunkChars.");
+  if (options.safetyPolicy)
+    assertWriteAllowed(options.dbPath, options.safetyPolicy);
+  migrateKnowledgeDb(options.dbPath);
+  const db = openKnowledgeDb(options.dbPath);
+  try {
+    const result = db.transaction(() => {
+      const seenSources = new Set;
+      const seenRevisions = new Set;
+      let chunksInserted = 0;
+      let chunksDeleted = 0;
+      let redactions = 0;
+      let skipped = 0;
+      recordAuditEvent(db, {
+        event_type: "source_read",
+        action: options.readAction ?? (options.sourceLabel.startsWith("s3://") ? "s3_manifest_read" : "local_manifest_read"),
+        target_uri: options.sourceLabel,
+        decision: "allow",
+        metadata: { items: options.items.length, read_only: true },
+        created_at: now
+      });
+      for (const raw of options.items) {
+        const item = normalizeManifestItem(raw, now);
+        const sourceId = upsertSource(db, item, now);
+        const revisionId = upsertRevision(db, sourceId, item, now);
+        seenSources.add(sourceId);
+        seenRevisions.add(revisionId);
+        if (item.text || item.status.toLowerCase() === "deleted") {
+          chunksDeleted += deleteChunksForRevision(db, revisionId);
+        }
+        const inserted = insertChunks(db, revisionId, item, now, maxChunkChars, chunkOverlapChars, options.safetyPolicy);
+        chunksInserted += inserted.chunksInserted;
+        redactions += inserted.redactions;
+      }
+      recordAuditEvent(db, {
+        event_type: "write",
+        action: "knowledge_manifest_ingest",
+        target_uri: options.dbPath,
+        decision: "allow",
+        metadata: { items: options.items.length, sources: seenSources.size, revisions: seenRevisions.size, chunks_inserted: chunksInserted, redactions },
+        created_at: now
+      });
+      return {
+        path: options.sourceLabel,
+        db_path: options.dbPath,
+        items_seen: options.items.length,
+        sources_upserted: seenSources.size,
+        revisions_upserted: seenRevisions.size,
+        chunks_inserted: chunksInserted,
+        chunks_deleted: chunksDeleted,
+        redactions,
+        skipped
+      };
+    })();
+    return result;
+  } finally {
+    db.close();
   }
-  if (parsed.kind === "file")
-    item.path = parsed.path;
-  if (parsed.kind === "s3")
-    item.path = parsed.key;
-  if (parsed.kind === "web")
-    item.url = parsed.url;
-  return item;
-}
-async function ingestSourceRef(options) {
-  const purpose = options.purpose ?? "knowledge_index";
-  const parsed = parseSourceRef(options.sourceRef);
-  const resolved = parsed.kind === "open-files" ? await readOpenFilesSourceText(options) : await readDirectSourceText(parsed, options.config, options.safetyPolicy);
-  const item = manifestItemForSource(options.sourceRef, parsed, resolved, purpose);
-  const result = await ingestOpenFilesManifestItems({
-    dbPath: options.dbPath,
-    items: [item],
-    sourceLabel: options.sourceRef,
-    readAction: "source_ref_ingest_read",
-    safetyPolicy: options.safetyPolicy,
-    now: options.now
-  });
-  return {
-    ...result,
-    source_ref: options.sourceRef,
-    content_source: resolved.contentSource,
-    read_only: true,
-    hash: String(item.hash)
-  };
 }
 
-// src/search.ts
+// src/source-ingest.ts
+import { createHash as createHash6 } from "crypto";
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { basename as basename3 } from "path";
+
+// src/source-resolver.ts
 function parseJsonObject3(value) {
   if (!value)
     return {};
@@ -16420,354 +16862,494 @@ function metadataNumber3(metadata, keys) {
   }
   return null;
 }
-function unique(values) {
-  return Array.from(new Set(values));
-}
-function queryTerms(query) {
-  const terms = query.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [];
-  return unique(terms.filter((term) => term.length > 0)).slice(0, 16);
-}
-function ftsQueryForTerms(terms) {
-  if (terms.length === 0)
-    return null;
-  return terms.map((term) => `${term}*`).join(" OR ");
+function assertPurposeAllowed(permissions, purpose) {
+  const mode = permissions.mode;
+  if (typeof mode === "string" && mode !== "read_only") {
+    throw new Error(`Source resolver denied ${purpose}. Permission mode is ${mode}, expected read_only.`);
+  }
+  const denied = permissions.denied_purposes;
+  if (Array.isArray(denied) && denied.includes(purpose)) {
+    throw new Error(`Source resolver denied ${purpose}. Purpose is explicitly denied.`);
+  }
+  const allowed = permissions.allowed_purposes;
+  if (Array.isArray(allowed) && allowed.length > 0 && !allowed.includes(purpose)) {
+    throw new Error(`Source resolver denied ${purpose}. Allowed purposes: ${allowed.join(", ")}`);
+  }
 }
-function escapeLikeTerm(term) {
-  return term.replace(/[\\%_]/g, (char) => `\\${char}`);
+function sourceRevisionRef(sourceUri, revision, fallback) {
+  if (!revision)
+    return fallback;
+  try {
+    const parsed = parseSourceRef(sourceUri);
+    if (parsed.kind === "open-files" && parsed.entity === "file") {
+      return `${sourceUri}/revision/${encodeURIComponent(revision.revision)}`;
+    }
+  } catch {
+    return fallback;
+  }
+  return fallback;
 }
-function likeParams(terms, fieldsPerTerm) {
-  return terms.flatMap((term) => Array.from({ length: fieldsPerTerm }, () => `%${escapeLikeTerm(term)}%`));
+function selectSource(db, sourceUri, requestedRef) {
+  return db.query(`SELECT id, uri, kind, title, metadata_json, acl_json, updated_at
+     FROM sources
+     WHERE uri = ? OR uri = ?
+     ORDER BY CASE WHEN uri = ? THEN 0 ELSE 1 END
+     LIMIT 1`).get(sourceUri, requestedRef, sourceUri) ?? null;
 }
-function scoreFromRank(rank, index) {
-  const rankScore = Number.isFinite(rank) ? 1 / (1 + Math.abs(rank)) : 0;
-  const orderScore = 1 / (1 + index);
-  return roundScore(Math.max(rankScore, orderScore));
+function selectRevision(db, sourceId, revisionId) {
+  if (revisionId) {
+    return db.query(`SELECT id, revision, hash, extracted_text_uri, metadata_json, created_at
+       FROM source_revisions
+       WHERE source_id = ? AND revision = ?
+       LIMIT 1`).get(sourceId, revisionId) ?? null;
+  }
+  return db.query(`SELECT id, revision, hash, extracted_text_uri, metadata_json, created_at
+     FROM source_revisions
+     WHERE source_id = ?
+     ORDER BY created_at DESC, revision DESC
+     LIMIT 1`).get(sourceId) ?? null;
 }
-function catalogScore(haystack, terms) {
-  if (terms.length === 0)
-    return 0;
-  const matched = terms.filter((term) => haystack.includes(term)).length;
-  if (matched === 0)
+function countChunks(db, revisionId) {
+  if (!revisionId)
     return 0;
-  return roundScore(Math.min(0.85, 0.35 + matched / terms.length * 0.5));
+  const row = db.query("SELECT COUNT(*) AS n FROM chunks WHERE source_revision_id = ?").get(revisionId);
+  return row?.n ?? 0;
 }
-function semanticScore(score) {
-  return roundScore(Math.max(0, Math.min(1, (score + 1) / 2)));
+function selectChunks(db, revisionId, limit) {
+  if (!revisionId || limit <= 0)
+    return [];
+  return db.query(`SELECT id, kind, ordinal, text, token_count, start_offset, end_offset, metadata_json
+     FROM chunks
+     WHERE source_revision_id = ?
+     ORDER BY ordinal ASC
+     LIMIT ?`).all(revisionId, limit);
 }
-function roundScore(score) {
-  return Number(score.toFixed(6));
+async function resolveOpenFilesSource(options) {
+  const purpose = options.purpose ?? "knowledge_answer";
+  const limit = Math.max(0, Math.min(options.limit ?? 10, 100));
+  const resolvedAt = (options.now ?? new Date).toISOString();
+  const parsed = parseSourceRef(options.sourceRef);
+  const sourceUri = catalogSourceUriForRef(options.sourceRef, parsed);
+  const requestedRevision = revisionIdForSourceRef(options.sourceRef);
+  if (options.safetyPolicy) {
+    if (!options.safetyPolicy.readOnlySourceAccess)
+      throw new Error("Safety policy denied source resolution.");
+    assertWriteAllowed(options.dbPath, options.safetyPolicy);
+  }
+  migrateKnowledgeDb(options.dbPath);
+  const db = openKnowledgeDb(options.dbPath);
+  try {
+    return db.transaction(() => {
+      const source = selectSource(db, sourceUri, options.sourceRef);
+      if (!source) {
+        recordAuditEvent(db, {
+          event_type: "source_read",
+          action: "open_files_resolve_missing",
+          target_uri: options.sourceRef,
+          decision: "allow",
+          metadata: { purpose, read_only: true, source_uri: sourceUri },
+          created_at: resolvedAt
+        });
+        return {
+          source_ref: options.sourceRef,
+          source_uri: sourceUri,
+          purpose,
+          read_only: true,
+          resolved: false,
+          resolver: {
+            name: "open-files-read-only",
+            mode: "local_catalog",
+            contract: "open-files-knowledge-source-v1"
+          },
+          source: null,
+          revision: null,
+          content: {
+            mime: null,
+            size: null,
+            hash: null,
+            text_available: false,
+            chunks_total: 0,
+            chunks_returned: 0,
+            char_count_returned: 0,
+            extracted_text_ref: null,
+            bytes_available: false,
+            bytes_exposed: false
+          },
+          chunks: [],
+          citations: []
+        };
+      }
+      const sourceMetadata = parseJsonObject3(source.metadata_json);
+      const permissions = parseJsonObject3(source.acl_json);
+      try {
+        assertPurposeAllowed(permissions, purpose);
+      } catch (error48) {
+        recordAuditEvent(db, {
+          event_type: "source_read",
+          action: "open_files_resolve",
+          target_uri: options.sourceRef,
+          decision: "deny",
+          metadata: {
+            purpose,
+            read_only: true,
+            source_uri: source.uri,
+            error: error48 instanceof Error ? error48.message : String(error48)
+          },
+          created_at: resolvedAt
+        });
+        throw error48;
+      }
+      const revision = selectRevision(db, source.id, requestedRevision);
+      const revisionMetadata = parseJsonObject3(revision?.metadata_json);
+      const totalChunks = countChunks(db, revision?.id ?? null);
+      const rows = selectChunks(db, revision?.id ?? null, limit);
+      const effectiveSourceRef = sourceRevisionRef(source.uri, revision, options.sourceRef);
+      const chunks = rows.map((row) => {
+        const metadata = parseJsonObject3(row.metadata_json);
+        const evidence = {
+          resolver: "open-files-read-only",
+          mode: "local_catalog",
+          purpose,
+          read_only: true,
+          source_ref: metadataString3(metadata, ["source_ref"]) ?? effectiveSourceRef,
+          source_uri: source.uri,
+          source_revision_id: revision?.id ?? null,
+          revision: revision?.revision ?? null,
+          hash: revision?.hash ?? metadataString3(metadata, ["hash"]),
+          chunk_id: row.id,
+          start_offset: row.start_offset,
+          end_offset: row.end_offset,
+          resolved_at: resolvedAt
+        };
+        const provenance = sourceProvenance({
+          source_ref: evidence.source_ref,
+          source_uri: evidence.source_uri,
+          source_kind: source.kind,
+          source_revision_id: evidence.source_revision_id,
+          revision: evidence.revision,
+          hash: evidence.hash,
+          chunk_id: row.id,
+          start_offset: row.start_offset,
+          end_offset: row.end_offset,
+          status: metadataString3(metadata, ["status"]),
+          resolver: evidence.resolver
+        });
+        return {
+          id: row.id,
+          kind: row.kind,
+          ordinal: row.ordinal,
+          text: row.text,
+          token_count: row.token_count,
+          start_offset: row.start_offset,
+          end_offset: row.end_offset,
+          metadata,
+          evidence,
+          provenance
+        };
+      });
+      const citations = chunks.map((chunk) => ({
+        source_ref: chunk.evidence.source_ref,
+        source_uri: source.uri,
+        chunk_id: chunk.id,
+        quote: chunk.text.slice(0, 500),
+        start_offset: chunk.start_offset,
+        end_offset: chunk.end_offset,
+        evidence: chunk.evidence,
+        provenance: chunk.provenance
+      }));
+      recordAuditEvent(db, {
+        event_type: "source_read",
+        action: "open_files_resolve",
+        target_uri: options.sourceRef,
+        decision: "allow",
+        metadata: {
+          purpose,
+          read_only: true,
+          source_uri: source.uri,
+          revision: revision?.revision ?? null,
+          chunks_returned: chunks.length,
+          chunks_total: totalChunks
+        },
+        created_at: resolvedAt
+      });
+      const mime = metadataString3(sourceMetadata, ["mime", "content_type"]) ?? metadataString3(revisionMetadata, ["mime", "content_type"]);
+      const size = metadataNumber3(sourceMetadata, ["size", "size_bytes"]) ?? metadataNumber3(revisionMetadata, ["size", "size_bytes"]);
+      return {
+        source_ref: effectiveSourceRef,
+        source_uri: source.uri,
+        purpose,
+        read_only: true,
+        resolved: true,
+        resolver: {
+          name: "open-files-read-only",
+          mode: "local_catalog",
+          contract: "open-files-knowledge-source-v1"
+        },
+        source: {
+          id: source.id,
+          uri: source.uri,
+          kind: source.kind,
+          title: source.title,
+          metadata: sourceMetadata,
+          permissions,
+          updated_at: source.updated_at
+        },
+        revision: revision ? {
+          id: revision.id,
+          revision: revision.revision,
+          hash: revision.hash,
+          extracted_text_uri: revision.extracted_text_uri,
+          metadata: revisionMetadata,
+          created_at: revision.created_at,
+          reindex_required: revisionMetadata.reindex_required === true
+        } : null,
+        content: {
+          mime,
+          size,
+          hash: revision?.hash ?? metadataString3(sourceMetadata, ["hash", "checksum", "sha256"]),
+          text_available: totalChunks > 0,
+          chunks_total: totalChunks,
+          chunks_returned: chunks.length,
+          char_count_returned: chunks.reduce((sum, chunk) => sum + chunk.text.length, 0),
+          extracted_text_ref: revision?.extracted_text_uri ?? metadataString3(revisionMetadata, ["extracted_text_ref", "extracted_text_uri"]),
+          bytes_available: false,
+          bytes_exposed: false
+        },
+        chunks,
+        citations
+      };
+    })();
+  } finally {
+    db.close();
+  }
 }
-function combinedScore(scores, citation) {
-  const keyword = scores.keyword ?? 0;
-  const semantic = scores.semantic ?? 0;
-  const catalog = scores.catalog ?? 0;
-  const citationBoost = citation?.chunk_id ? 0.05 : 0;
-  return roundScore(Math.min(1, keyword * 0.55 + semantic * 0.4 + catalog * 0.35 + citationBoost));
+
+// src/source-ingest.ts
+function sha256Text(text) {
+  return `sha256:${createHash6("sha256").update(text).digest("hex")}`;
 }
-function existingProvenance(metadata) {
-  const provenance = metadata.provenance;
-  return provenance && typeof provenance === "object" && !Array.isArray(provenance) ? provenance : null;
+function stripHtml(html) {
+  return html.replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<style[\s\S]*?<\/style>/gi, " ").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/\s+\n/g, `
+`).replace(/\n\s+/g, `
+`).replace(/[ \t]{2,}/g, " ").trim();
 }
-function provenanceForChunk2(row) {
-  const metadata = parseJsonObject3(row.chunk_metadata_json);
-  const existing = existingProvenance(metadata);
-  if (existing)
-    return existing;
-  if (!row.source_revision_id && !row.source_uri)
-    return null;
-  return sourceProvenance({
-    source_ref: metadataString3(metadata, ["source_ref"]),
-    source_uri: row.source_uri ?? metadataString3(metadata, ["source_uri"]),
-    source_kind: row.source_kind ?? metadataString3(metadata, ["source_kind"]),
-    source_revision_id: row.source_revision_id,
-    revision: row.revision ?? metadataString3(metadata, ["revision"]),
-    hash: row.hash ?? metadataString3(metadata, ["hash"]),
-    chunk_id: row.chunk_id,
-    start_offset: row.start_offset ?? metadataNumber3(metadata, ["start_offset"]),
-    end_offset: row.end_offset ?? metadataNumber3(metadata, ["end_offset"]),
-    status: metadataString3(metadata, ["status"]),
-    resolver: "open-files-read-only"
+async function readS3Text3(uri, config2, safetyPolicy) {
+  const parsed = new URL(uri);
+  const bucket = parsed.hostname;
+  const key = decodeURIComponent(parsed.pathname.replace(/^\/+/, ""));
+  if (!bucket || !key)
+    throw new Error(`Invalid S3 source URI: ${uri}`);
+  if (safetyPolicy)
+    assertS3ReadAllowed(uri, safetyPolicy);
+  const [{ S3Client, GetObjectCommand }, { fromIni }] = await Promise.all([
+    import("@aws-sdk/client-s3"),
+    import("@aws-sdk/credential-providers")
+  ]);
+  const s3Config = config2?.storage.type === "s3" && config2.storage.s3?.bucket === bucket ? config2.storage.s3 : undefined;
+  const client = new S3Client({
+    region: s3Config?.region,
+    credentials: s3Config?.profile ? fromIni({ profile: s3Config.profile }) : undefined,
+    maxAttempts: s3Config?.max_attempts
   });
+  const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+  if (!response.Body)
+    return "";
+  return await response.Body.transformToString();
 }
-function selectFtsChunks(db, ftsQuery, limit) {
-  if (!ftsQuery)
-    return [];
-  return db.query(`SELECT
-       chunks_fts.chunk_id,
-       c.kind AS chunk_kind,
-       c.wiki_page_id,
-       c.text,
-       c.token_count,
-       c.start_offset,
-       c.end_offset,
-       c.metadata_json AS chunk_metadata_json,
-       c.source_revision_id,
-       sr.revision,
-       sr.hash,
-       s.uri AS source_uri,
-       s.kind AS source_kind,
-       s.title AS source_title,
-       wp.path AS wiki_path,
-       wp.title AS wiki_title,
-       wp.artifact_uri AS wiki_artifact_uri,
-       wp.content_hash AS wiki_content_hash,
-       wp.status AS wiki_status,
-       wp.metadata_json AS wiki_metadata_json,
-       bm25(chunks_fts) AS rank
-     FROM chunks_fts
-     JOIN chunks c ON c.id = chunks_fts.chunk_id
-     LEFT JOIN source_revisions sr ON sr.id = c.source_revision_id
-     LEFT JOIN sources s ON s.id = sr.source_id
-     LEFT JOIN wiki_pages wp ON wp.id = c.wiki_page_id
-     WHERE chunks_fts MATCH ?
-     ORDER BY rank ASC
-     LIMIT ?`).all(ftsQuery, limit);
-}
-function catalogWhere(fields, terms) {
-  if (terms.length === 0)
-    return "1 = 0";
-  const clauses = terms.map(() => `(${fields.map((field) => `lower(COALESCE(${field}, '')) LIKE ? ESCAPE '\\'`).join(" OR ")})`);
-  return clauses.join(" OR ");
+async function readWebText(uri, safetyPolicy) {
+  if (safetyPolicy)
+    assertWebSearchAllowed(safetyPolicy);
+  const response = await fetch(uri, {
+    headers: {
+      accept: "text/markdown,text/plain,text/html,application/json;q=0.8,*/*;q=0.5",
+      "user-agent": "@hasna/knowledge source-ingest"
+    }
+  });
+  if (!response.ok)
+    throw new Error(`Web source read failed ${response.status}: ${uri}`);
+  const mime = response.headers.get("content-type");
+  const body = await response.text();
+  return { text: mime?.includes("html") ? stripHtml(body) : body, mime };
 }
-function selectWikiPages(db, terms, limit) {
-  const fields = ["path", "title", "artifact_uri", "metadata_json"];
-  return db.query(`SELECT id, path, title, artifact_uri, content_hash, status, metadata_json
-     FROM wiki_pages
-     WHERE status = 'active' AND (${catalogWhere(fields, terms)})
-     ORDER BY updated_at DESC
-     LIMIT ?`).all(...likeParams(terms, fields.length), limit);
+function titleForRef(parsed) {
+  if (parsed.kind === "file")
+    return basename3(parsed.path);
+  if (parsed.kind === "s3")
+    return basename3(parsed.key);
+  if (parsed.kind === "web")
+    return basename3(new URL(parsed.url).pathname) || parsed.url;
+  return parsed.path ? basename3(parsed.path) : parsed.id;
 }
-function selectKnowledgeIndexes(db, terms, limit) {
-  const fields = ["kind", "name", "shard_key", "artifact_uri", "metadata_json"];
-  return db.query(`SELECT id, kind, name, artifact_uri, shard_key, metadata_json
-     FROM knowledge_indexes
-     WHERE ${catalogWhere(fields, terms)}
-     ORDER BY updated_at DESC
-     LIMIT ?`).all(...likeParams(terms, fields.length), limit);
+async function readDirectSourceText(parsed, config2, safetyPolicy) {
+  if (parsed.kind === "file") {
+    if (!existsSync6(parsed.path))
+      throw new Error(`Source file not found: ${parsed.path}`);
+    const text = readFileSync6(parsed.path, "utf8");
+    return {
+      text,
+      contentSource: "file",
+      title: titleForRef(parsed),
+      mime: "text/plain",
+      size: text.length,
+      hash: sha256Text(text),
+      revision: null,
+      extractedTextRef: null,
+      metadata: { path: parsed.path },
+      permissions: { mode: "read_only" }
+    };
+  }
+  if (parsed.kind === "s3") {
+    const text = await readS3Text3(parsed.uri, config2, safetyPolicy);
+    return {
+      text,
+      contentSource: "s3",
+      title: titleForRef(parsed),
+      mime: "text/plain",
+      size: text.length,
+      hash: sha256Text(text),
+      revision: null,
+      extractedTextRef: null,
+      metadata: { bucket: parsed.bucket, key: parsed.key },
+      permissions: { mode: "read_only" }
+    };
+  }
+  if (parsed.kind === "web") {
+    const web = await readWebText(parsed.url, safetyPolicy);
+    return {
+      text: web.text,
+      contentSource: "web",
+      title: titleForRef(parsed),
+      mime: web.mime,
+      size: web.text.length,
+      hash: sha256Text(web.text),
+      revision: null,
+      extractedTextRef: null,
+      metadata: { url: parsed.url },
+      permissions: { mode: "read_only" }
+    };
+  }
+  throw new Error(`Direct source reading is not available for ${parsed.uri}`);
 }
-function chunkResult(row, keywordScore) {
-  const metadata = parseJsonObject3(row.chunk_metadata_json);
-  const provenance = provenanceForChunk2(row);
-  const sourceRef = metadataString3(metadata, ["source_ref"]);
-  const sourceUri = row.source_uri ?? metadataString3(metadata, ["source_uri"]);
-  const isWiki = Boolean(row.wiki_page_id);
-  const result = {
-    kind: isWiki ? "wiki_chunk" : "source_chunk",
-    id: row.chunk_id,
-    title: isWiki ? row.wiki_title : row.source_title,
-    text: row.text,
-    score: 0,
-    scores: { keyword: keywordScore },
-    source: sourceUri || sourceRef ? {
-      uri: sourceUri,
-      ref: sourceRef,
-      kind: row.source_kind ?? metadataString3(metadata, ["source_kind"]),
-      revision: row.revision ?? metadataString3(metadata, ["revision"]),
-      hash: row.hash ?? metadataString3(metadata, ["hash"])
-    } : null,
-    citation: {
-      chunk_id: row.chunk_id,
-      start_offset: row.start_offset,
-      end_offset: row.end_offset
-    },
-    artifact: isWiki ? {
-      uri: row.wiki_artifact_uri,
-      path: row.wiki_path,
-      hash: row.wiki_content_hash,
-      shard_key: row.wiki_path
-    } : null,
-    provenance,
-    reasons: ["keyword_match"]
-  };
-  result.score = combinedScore(result.scores, result.citation);
-  return result;
+async function readTextRef(uri, config2, safetyPolicy) {
+  if (uri.startsWith("open-files://")) {
+    throw new Error("Open-files extracted text refs require an open-files resolver API. Ingest an open-files manifest with extracted_text or an extracted_text_ref using file://, s3://, or https://.");
+  }
+  const parsed = parseSourceRef(uri);
+  const direct = await readDirectSourceText(parsed, config2, safetyPolicy);
+  return { text: direct.text, contentSource: "extracted_text_ref" };
 }
-function wikiPageResult(row, terms) {
-  const metadata = parseJsonObject3(row.metadata_json);
-  const score = catalogScore(`${row.path} ${row.title} ${row.artifact_uri ?? ""} ${row.metadata_json}`.toLowerCase(), terms);
-  const result = {
-    kind: "wiki_page",
-    id: row.id,
-    title: row.title,
-    text: null,
-    score: 0,
-    scores: { catalog: score },
-    source: null,
-    citation: null,
-    artifact: {
-      uri: row.artifact_uri,
-      path: row.path,
-      hash: row.content_hash,
-      shard_key: row.path
-    },
-    provenance: existingProvenance(metadata),
-    reasons: ["wiki_catalog_match"]
+async function readOpenFilesSourceText(options) {
+  const resolved = await resolveOpenFilesSource({
+    dbPath: options.dbPath,
+    sourceRef: options.sourceRef,
+    purpose: options.purpose ?? "knowledge_index",
+    limit: 100,
+    safetyPolicy: options.safetyPolicy,
+    now: options.now
+  });
+  if (!resolved.resolved) {
+    throw new Error("Open-files source is not in the local knowledge catalog. Ingest an open-files manifest first or use the open-files resolver API.");
+  }
+  if (resolved.revision?.extracted_text_uri && !resolved.content.text_available) {
+    const textRef = await readTextRef(resolved.revision.extracted_text_uri, options.config, options.safetyPolicy);
+    return {
+      text: textRef.text,
+      contentSource: textRef.contentSource,
+      title: resolved.source?.title ?? null,
+      mime: resolved.content.mime,
+      size: textRef.text.length,
+      hash: resolved.revision.hash ?? sha256Text(textRef.text),
+      revision: resolved.revision.revision,
+      extractedTextRef: resolved.revision.extracted_text_uri,
+      metadata: resolved.source?.metadata ?? {},
+      permissions: resolved.source?.permissions ?? { mode: "read_only" }
+    };
+  }
+  if (resolved.chunks.length === 0) {
+    throw new Error("Open-files source has no extracted text chunks yet. Ingest an open-files manifest with extracted_text or extracted_text_ref first.");
+  }
+  const text = resolved.chunks.map((chunk) => chunk.text).join(`
+
+`);
+  return {
+    text,
+    contentSource: "catalog_chunks",
+    title: resolved.source?.title ?? null,
+    mime: resolved.content.mime,
+    size: text.length,
+    hash: resolved.revision?.hash ?? sha256Text(text),
+    revision: resolved.revision?.revision ?? null,
+    extractedTextRef: resolved.revision?.extracted_text_uri ?? null,
+    metadata: resolved.source?.metadata ?? {},
+    permissions: resolved.source?.permissions ?? { mode: "read_only" }
   };
-  result.score = combinedScore(result.scores, result.citation);
-  return result;
 }
-function indexResult(row, terms) {
-  const metadata = parseJsonObject3(row.metadata_json);
-  const score = catalogScore(`${row.kind} ${row.name} ${row.shard_key ?? ""} ${row.artifact_uri ?? ""} ${row.metadata_json}`.toLowerCase(), terms);
-  const result = {
-    kind: "knowledge_index",
-    id: row.id,
-    title: row.name,
-    text: null,
-    score: 0,
-    scores: { catalog: score },
-    source: null,
-    citation: null,
-    artifact: {
-      uri: row.artifact_uri,
-      path: metadataString3(metadata, ["artifact_key"]),
-      hash: metadataString3(metadata, ["content_hash"]),
-      shard_key: row.shard_key
+function manifestItemForSource(sourceRef, parsed, resolved, purpose) {
+  const hash2 = resolved.hash ?? sha256Text(resolved.text);
+  const metadata = {
+    ...resolved.metadata,
+    source_ref: sourceRef,
+    content_source: resolved.contentSource,
+    read_only: true
+  };
+  const item = {
+    source_ref: sourceRef,
+    name: resolved.title ?? titleForRef(parsed),
+    mime: resolved.mime ?? "text/plain",
+    size: resolved.size ?? resolved.text.length,
+    hash: hash2,
+    revision: resolved.revision ?? hash2,
+    status: "active",
+    updated_at: new Date().toISOString(),
+    permissions: {
+      mode: "read_only",
+      allowed_purposes: [purpose],
+      ...resolved.permissions
     },
-    provenance: existingProvenance(metadata),
-    reasons: ["index_catalog_match"]
+    metadata,
+    extracted_text_ref: resolved.extractedTextRef,
+    extracted_text: resolved.text
   };
-  result.score = combinedScore(result.scores, result.citation);
-  return result;
-}
-function mergeResult(results, entry) {
-  const key = `${entry.kind}:${entry.id}`;
-  const existing = results.get(key);
-  if (!existing) {
-    results.set(key, entry);
-    return;
+  if (parsed.kind === "open-files") {
+    if (parsed.entity === "file")
+      item.file_id = parsed.id;
+    if (parsed.entity === "source") {
+      item.source_id = parsed.id;
+      item.path = parsed.path;
+    }
   }
-  existing.scores = {
-    keyword: Math.max(existing.scores.keyword ?? 0, entry.scores.keyword ?? 0) || undefined,
-    semantic: Math.max(existing.scores.semantic ?? 0, entry.scores.semantic ?? 0) || undefined,
-    catalog: Math.max(existing.scores.catalog ?? 0, entry.scores.catalog ?? 0) || undefined
-  };
-  existing.reasons = unique([...existing.reasons, ...entry.reasons]);
-  existing.text = existing.text ?? entry.text;
-  existing.title = existing.title ?? entry.title;
-  existing.source = existing.source ?? entry.source;
-  existing.citation = existing.citation ?? entry.citation;
-  existing.artifact = existing.artifact ?? entry.artifact;
-  existing.provenance = existing.provenance ?? entry.provenance;
-  existing.score = combinedScore(existing.scores, existing.citation);
+  if (parsed.kind === "file")
+    item.path = parsed.path;
+  if (parsed.kind === "s3")
+    item.path = parsed.key;
+  if (parsed.kind === "web")
+    item.url = parsed.url;
+  return item;
 }
-function sortResults(results) {
-  const kindOrder = {
-    source_chunk: 0,
-    wiki_chunk: 1,
-    wiki_page: 2,
-    knowledge_index: 3
-  };
-  return results.sort((a, b) => {
-    if (b.score !== a.score)
-      return b.score - a.score;
-    return kindOrder[a.kind] - kindOrder[b.kind] || a.id.localeCompare(b.id);
+async function ingestSourceRef(options) {
+  const purpose = options.purpose ?? "knowledge_index";
+  const parsed = parseSourceRef(options.sourceRef);
+  const resolved = parsed.kind === "open-files" ? await readOpenFilesSourceText(options) : await readDirectSourceText(parsed, options.config, options.safetyPolicy);
+  const item = manifestItemForSource(options.sourceRef, parsed, resolved, purpose);
+  const result = await ingestOpenFilesManifestItems({
+    dbPath: options.dbPath,
+    items: [item],
+    sourceLabel: options.sourceRef,
+    readAction: "source_ref_ingest_read",
+    safetyPolicy: options.safetyPolicy,
+    now: options.now
   });
-}
-async function hybridSearch(options) {
-  const query = options.query.trim();
-  if (!query)
-    throw new Error("Search query is required.");
-  const limit = Math.max(1, Math.min(options.limit ?? 10, 100));
-  const terms = queryTerms(query);
-  const ftsQuery = ftsQueryForTerms(terms);
-  const semanticEnabled = options.semantic === true || options.fake === true || Boolean(options.modelRef);
-  const warnings = [];
-  let semanticProvider = null;
-  let semanticModel = null;
-  let semanticDimensions = null;
-  let keywordCount = 0;
-  let catalogCount = 0;
-  let semanticCount = 0;
-  const merged = new Map;
-  migrateKnowledgeDb(options.dbPath);
-  const db = openKnowledgeDb(options.dbPath);
-  try {
-    const ftsRows = selectFtsChunks(db, ftsQuery, Math.max(limit * 3, 20));
-    keywordCount = ftsRows.length;
-    ftsRows.forEach((row, index) => mergeResult(merged, chunkResult(row, scoreFromRank(row.rank, index))));
-    const wikiRows = selectWikiPages(db, terms, Math.max(limit, 10));
-    const indexRows = selectKnowledgeIndexes(db, terms, Math.max(limit, 10));
-    catalogCount = wikiRows.length + indexRows.length;
-    wikiRows.forEach((row) => mergeResult(merged, wikiPageResult(row, terms)));
-    indexRows.forEach((row) => mergeResult(merged, indexResult(row, terms)));
-  } finally {
-    db.close();
-  }
-  if (semanticEnabled) {
-    try {
-      const semantic = await searchVectorIndex({
-        dbPath: options.dbPath,
-        query,
-        limit: Math.max(limit * 3, 20),
-        config: options.config,
-        env: options.env,
-        modelRef: options.modelRef,
-        dimensions: options.dimensions,
-        fake: options.fake,
-        batchSize: options.batchSize,
-        maxParallelCalls: options.maxParallelCalls
-      });
-      semanticProvider = semantic.provider;
-      semanticModel = semantic.model;
-      semanticDimensions = semantic.dimensions;
-      semanticCount = semantic.results.length;
-      for (const row of semantic.results) {
-        const result = {
-          kind: "source_chunk",
-          id: row.chunk_id,
-          title: null,
-          text: row.text,
-          score: 0,
-          scores: { semantic: semanticScore(row.score) },
-          source: {
-            uri: row.source_uri,
-            ref: row.source_ref,
-            kind: row.provenance?.source_kind ?? null,
-            revision: row.revision,
-            hash: row.hash
-          },
-          citation: {
-            chunk_id: row.chunk_id,
-            start_offset: row.provenance?.start_offset ?? null,
-            end_offset: row.provenance?.end_offset ?? null
-          },
-          artifact: null,
-          provenance: row.provenance,
-          reasons: ["semantic_match"]
-        };
-        result.score = combinedScore(result.scores, result.citation);
-        mergeResult(merged, result);
-      }
-    } catch (error48) {
-      warnings.push(`semantic_search_failed: ${error48 instanceof Error ? error48.message : String(error48)}`);
-    }
-  }
-  const results = sortResults(Array.from(merged.values())).slice(0, limit);
   return {
-    query,
-    limit,
-    mode: {
-      keyword: true,
-      catalog: true,
-      semantic: semanticEnabled
-    },
-    semantic_provider: semanticProvider,
-    semantic_model: semanticModel,
-    semantic_dimensions: semanticDimensions,
-    counts: {
-      keyword_results: keywordCount,
-      catalog_results: catalogCount,
-      semantic_results: semanticCount,
-      merged_results: results.length
-    },
-    warnings,
-    results
+    ...result,
+    source_ref: options.sourceRef,
+    content_source: resolved.contentSource,
+    read_only: true,
+    hash: String(item.hash)
   };
 }
 
 // src/storage-contract.ts
-import { createHash as createHash6, randomUUID as randomUUID4 } from "crypto";
+import { createHash as createHash7, randomUUID as randomUUID6 } from "crypto";
 var GENERATED_ARTIFACTS = [
   {
     kind: "schema",
@@ -16803,7 +17385,7 @@ var GENERATED_ARTIFACTS = [
 function hashArtifactBody(body) {
   const bytes = typeof body === "string" ? Buffer.from(body) : Buffer.from(body);
   return {
-    hash: `sha256:${createHash6("sha256").update(bytes).digest("hex")}`,
+    hash: `sha256:${createHash7("sha256").update(bytes).digest("hex")}`,
     size_bytes: bytes.byteLength
   };
 }
@@ -16928,7 +17510,7 @@ function recordStorageObjects(db, objects, now = new Date) {
   `);
   const insert = db.transaction((entries) => {
     for (const entry of entries) {
-      statement.run(randomUUID4(), entry.uri, entry.kind, entry.content_type ?? null, entry.hash ?? null, entry.size_bytes ?? null, JSON.stringify({
+      statement.run(randomUUID6(), entry.uri, entry.kind, entry.content_type ?? null, entry.hash ?? null, entry.size_bytes ?? null, JSON.stringify({
         key: entry.key,
         ...entry.metadata ?? {}
       }), timestamp, timestamp);
@@ -16938,15 +17520,15 @@ function recordStorageObjects(db, objects, now = new Date) {
 }
 
 // src/wiki-layout.ts
-import { createHash as createHash7 } from "crypto";
+import { createHash as createHash8 } from "crypto";
 function todayParts(now) {
   const year = String(now.getUTCFullYear());
   const month = String(now.getUTCMonth() + 1).padStart(2, "0");
   const day = String(now.getUTCDate()).padStart(2, "0");
   return { year, month, day };
 }
-function stableId4(prefix, value) {
-  return `${prefix}_${createHash7("sha256").update(value).digest("hex").slice(0, 20)}`;
+function stableId5(prefix, value) {
+  return `${prefix}_${createHash8("sha256").update(value).digest("hex").slice(0, 20)}`;
 }
 function estimateTokenCount2(text) {
   const words = text.trim().split(/\s+/).filter(Boolean).length;
@@ -17064,7 +17646,7 @@ function provenanceFor(artifact) {
 }
 function recordWikiChunk(db, pageId, title, artifact, body, now) {
   const provenance = provenanceFor(artifact);
-  const chunkId = stableId4("chk", `${pageId}\x00${artifact.hash ?? artifact.uri}`);
+  const chunkId = stableId5("chk", `${pageId}\x00${artifact.hash ?? artifact.uri}`);
   const existing = db.query("SELECT id FROM chunks WHERE wiki_page_id = ?").all(pageId);
   for (const row of existing)
     db.run("DELETE FROM chunks_fts WHERE chunk_id = ?", [row.id]);
@@ -17100,7 +17682,7 @@ function recordWikiLayoutCatalog(db, artifacts, now = new Date) {
          artifact_uri = excluded.artifact_uri,
          metadata_json = excluded.metadata_json,
          updated_at = excluded.updated_at`, [
-      stableId4("idx", "root:indexes/root.md"),
+      stableId5("idx", "root:indexes/root.md"),
       "root",
       "root",
       rootIndex.uri,
@@ -17115,7 +17697,7 @@ function recordWikiLayoutCatalog(db, artifacts, now = new Date) {
     ]);
   }
   if (wikiReadme) {
-    const wikiPageId = stableId4("wiki", "wiki/README.md");
+    const wikiPageId = stableId5("wiki", "wiki/README.md");
     db.run(`INSERT INTO wiki_pages (id, path, title, artifact_uri, content_hash, status, metadata_json, created_at, updated_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(path) DO UPDATE SET
@@ -17295,6 +17877,22 @@ class KnowledgeService {
       config: this.config()
     });
   }
+  async retrieveContext(options) {
+    const workspace = this.ensureWorkspace();
+    return retrieveKnowledgeContext({
+      ...options,
+      dbPath: workspace.knowledgeDbPath,
+      config: this.config()
+    });
+  }
+  async runPrompt(options) {
+    const workspace = this.ensureWorkspace();
+    return runKnowledgePrompt({
+      ...options,
+      dbPath: workspace.knowledgeDbPath,
+      config: this.config()
+    });
+  }
 }
 function createKnowledgeService(options = {}) {
   return new KnowledgeService(options);
@@ -17460,6 +18058,40 @@ function buildServer() {
       return errorText(error48 instanceof Error ? error48.message : String(error48));
     }
   });
+  registerTool(server, "knowledge_search", "Knowledge context search", "Return a reranked citation context pack for agent prompts", {
+    scope: scopeField,
+    query: exports_external.string().describe("Search query or prompt"),
+    limit: exports_external.number().optional().describe("Maximum context results"),
+    semantic: exports_external.boolean().optional().describe("Include vector semantic results"),
+    model: exports_external.string().optional().describe("Embedding model ref, default openai:text-embedding-3-small"),
+    dimensions: exports_external.number().optional().describe("Embedding dimensions for deterministic fake mode"),
+    fake: exports_external.boolean().optional().describe("Use deterministic fake embeddings for local tests")
+  }, async ({ scope, query, limit, semantic, model, dimensions, fake }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...await service.retrieveContext({ query, limit, semantic, modelRef: model, dimensions, fake }) });
+    } catch (error48) {
+      return errorText(error48 instanceof Error ? error48.message : String(error48));
+    }
+  });
+  registerTool(server, "knowledge_ask", "Knowledge prompt answer", "Answer a prompt using read-only knowledge context and optional AI SDK generation", {
+    scope: scopeField,
+    prompt: exports_external.string().describe("Prompt to answer with the knowledge base"),
+    limit: exports_external.number().optional().describe("Maximum context results"),
+    semantic: exports_external.boolean().optional().describe("Include vector semantic results"),
+    generate: exports_external.boolean().optional().describe("Call AI SDK text generation; omitted returns a local citation draft"),
+    approve_write: exports_external.boolean().optional().describe("Record approval intent for future durable wiki writes"),
+    model: exports_external.string().optional().describe("Model alias/ref, default configured provider default"),
+    dimensions: exports_external.number().optional().describe("Embedding dimensions for deterministic fake mode"),
+    fake: exports_external.boolean().optional().describe("Use deterministic fake embeddings/generation for local tests")
+  }, async ({ scope, prompt, limit, semantic, generate, approve_write, model, dimensions, fake }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...await service.runPrompt({ prompt, limit, semantic, generate, approveWrite: approve_write, modelRef: model, dimensions, fake }) });
+    } catch (error48) {
+      return errorText(error48 instanceof Error ? error48.message : String(error48));
+    }
+  });
   registerTool(server, "ok_add", "Add a knowledge item", "Add a new item to the knowledge store", {
     title: exports_external.string().describe("Item title"),
     content: exports_external.string().describe("Item content/body"),